Annotation of html5/spec/the-iframe-element.html, revision 1.144
1.1 mike 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
1.61 mike 2: <!DOCTYPE html>
1.46 mike 3: <html lang="en-US-x-Hixie" class="split chapter"><head><title>4.8.2 The iframe element — HTML5 </title><style type="text/css">
1.1 mike 4: pre { margin-left: 2em; white-space: pre-wrap; }
5: h2 { margin: 3em 0 1em 0; }
6: h3 { margin: 2.5em 0 1em 0; }
7: h4 { margin: 2.5em 0 0.75em 0; }
8: h5, h6 { margin: 2.5em 0 1em; }
9: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
10: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
11: p { margin: 1em 0; }
12: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
13: dl, dd { margin-top: 0; margin-bottom: 0; }
14: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
15: dt + dt { margin-top: 0; }
16: dd dt { margin-top: 0.25em; margin-bottom: 0; }
17: dd p { margin-top: 0; }
18: dd dl + p { margin-top: 1em; }
19: dd table + p { margin-top: 1em; }
20: p + * > li, dd li { margin: 1em 0; }
21: dt, dfn { font-weight: bold; font-style: normal; }
1.83 mike 22: i, em { font-style: italic; }
1.1 mike 23: dt dfn { font-style: italic; }
24: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
25: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
26: pre em { font-weight: bolder; font-style: normal; }
27: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
28: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
29: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
30: table thead, table tbody { border-bottom: solid; }
31: table tbody th:first-child { border-left: solid; }
32: table tbody th { text-align: left; }
33: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
34: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
35:
36: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
37: .matrix, .matrix td { border: none; text-align: right; }
38: .matrix { margin-left: 2em; }
39: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
40: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
41: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
42:
43: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
1.96 mike 44: img.extra, p.overview { float: right; }
1.94 mike 45: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
1.1 mike 46: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
1.94 mike 47: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
1.1 mike 48: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
49: pre.css:first-line { color: #AAAA50; }
50: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
51: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
52: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
53: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
54: dl.domintro dd p { margin: 0.5em 0; }
1.124 mike 55: dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
1.1 mike 56: dl.switch { padding-left: 2em; }
57: dl.switch > dt { text-indent: -1.5em; }
58: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
59: dl.triple { padding: 0 0 0 1em; }
60: dl.triple dt, dl.triple dd { margin: 0; display: inline }
61: dl.triple dt:after { content: ':'; }
62: dl.triple dd:after { content: '\A'; white-space: pre; }
63: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
64: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
65: a .diff-new { border-bottom: 1px blue solid; }
66:
67: h2 { page-break-before: always; }
68: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
69: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
70:
1.26 mike 71: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
72: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 mike 73:
74: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
75: div.head p { margin: 0; }
76: div.head h1 { margin: 0; }
77: div.head .logo { float: right; margin: 0 1em; }
78: div.head .logo img { border: none } /* remove border from top image */
79: div.head dl { margin: 1em 0; }
80: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
81:
82: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
83: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
84: body > .toc > li > * { margin-bottom: 0.5em; }
85: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
86: .toc, .toc li { list-style: none; }
87:
88: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
89: .brief li { margin: 0; padding: 0; }
90: .brief li p { margin: 0; padding: 0; }
91:
92: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
93: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
94: .category-list li { display: inline; }
95: .category-list li:not(:last-child)::after { content: ', '; }
96: .category-list li > span, .category-list li > a { text-transform: lowercase; }
97: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
98:
99: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
100: .XXX > :first-child { margin-top: 0; }
101: p .XXX { line-height: 3em; }
102: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
103: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
104: .annotation :link, .annotation :visited { color: inherit; }
105: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
106: .annotation span { border: none ! important; }
107: .note { color: green; background: transparent; font-family: sans-serif; }
108: .warning { color: red; background: transparent; }
109: .note, .warning { font-weight: bolder; font-style: italic; }
1.83 mike 110: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 mike 111: p.note, div.note { padding: 0.5em 2em; }
112: span.note { padding: 0 2em; }
113: .note p:first-child, .warning p:first-child { margin-top: 0; }
114: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
115: .warning:before { font-style: normal; }
116: p.note:before { content: 'Note: '; }
117: p.warning:before { content: '\26A0 Warning! '; }
118:
119: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
120: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
121: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.12 mike 122: .bookkeeping dt { margin: 0.5em 2em 0; }
123: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 mike 124:
125: h4 { position: relative; z-index: 3; }
126: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
127: .element {
128: background: #EEEEFF;
129: color: black;
130: margin: 0 0 1em 0.15em;
131: padding: 0 1em 0.25em 0.75em;
132: border-left: solid #9999FF 0.25em;
133: position: relative;
134: z-index: 1;
135: }
136: .element:before {
137: position: absolute;
138: z-index: 2;
139: top: 0;
140: left: -1.15em;
141: height: 2em;
142: width: 0.9em;
143: background: #EEEEFF;
144: content: ' ';
145: border-style: none none solid solid;
146: border-color: #9999FF;
147: border-width: 0.25em;
148: }
149:
150: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
151: td > .example:only-child { margin: 0 0 0 0.1em; }
152:
153: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
154: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
155: ul.domTree li li { list-style: none; }
156: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
157: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
158: ul.domTree span { font-style: italic; font-family: serif; }
159: ul.domTree .t1 code { color: purple; font-weight: bold; }
160: ul.domTree .t2 { font-style: normal; font-family: monospace; }
161: ul.domTree .t2 .name { color: black; font-weight: bold; }
162: ul.domTree .t2 .value { color: blue; font-weight: normal; }
163: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
164: ul.domTree .t7 code, .domTree .t8 code { color: green; }
165: ul.domTree .t10 code { color: teal; }
166:
167: body.dfnEnabled dfn { cursor: pointer; }
168: .dfnPanel {
169: display: inline;
170: position: absolute;
171: z-index: 10;
172: height: auto;
173: width: auto;
174: padding: 0.5em 0.75em;
175: font: small sans-serif, Droid Sans Fallback;
176: background: #DDDDDD;
177: color: black;
178: border: outset 0.2em;
179: }
180: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
181: .dfnPanel :link, .dfnPanel :visited { color: black; }
182: .dfnPanel p { font-weight: bolder; }
183: .dfnPanel * + p { margin-top: 0.25em; }
184: .dfnPanel li { list-style-position: inside; }
185:
186: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
187: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
188: #configUI p label { display: block; }
189: #configUI #updateUI, #configUI .loginUI { text-align: center; }
190: #configUI input[type=button] { display: block; margin: auto; }
1.11 mike 191:
1.30 mike 192: fieldset { margin: 1em; padding: 0.5em 1em; }
193: fieldset > legend + * { margin-top: 0; }
1.21 mike 194: fieldset > :last-child { margin-bottom: 0; }
1.30 mike 195: fieldset p { margin: 0.5em 0; }
196:
1.62 mike 197: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><style type="text/css">
1.1 mike 198:
199: .applies thead th > * { display: block; }
200: .applies thead code { display: block; }
201: .applies tbody th { whitespace: nowrap; }
202: .applies td { text-align: center; }
203: .applies .yes { background: yellow; }
204:
1.14 mike 205: .matrix, .matrix td { border: hidden; text-align: right; }
1.1 mike 206: .matrix { margin-left: 2em; }
207:
208: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
209: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
210: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
211:
1.17 mike 212: td.eg { border-width: thin; text-align: center; }
213:
1.1 mike 214: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
215: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
216: #table-example-1 caption { padding-bottom: 0.5em; }
217: #table-example-1 thead, #table-example-1 tbody { border: none; }
218: #table-example-1 th, #table-example-1 td { border: solid thin; }
219: #table-example-1 th { font-weight: normal; }
220: #table-example-1 td { border-style: none solid; vertical-align: top; }
221: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
222: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
223: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
224: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
225: #table-example-1 tbody td:first-child::after { content: leader(". "); }
226: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
227: #table-example-1 tbody td:first-child + td { width: 10em; }
228: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
229: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
230:
231: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
232: .apple-table-examples * { font-family: "Times", serif; }
233: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
234: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
235: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
236: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
237: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
238: .apple-table-examples td { text-align: right; vertical-align: top; }
239: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
240: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
241: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
242: .apple-table-examples sup { line-height: 0; }
243:
244: .details-example img { vertical-align: top; }
245:
1.40 mike 246: #base64-table {
247: white-space: nowrap;
248: font-size: 0.6em;
249: column-width: 6em;
250: column-count: 5;
251: column-gap: 1em;
252: -moz-column-width: 6em;
253: -moz-column-count: 5;
254: -moz-column-gap: 1em;
255: -webkit-column-width: 6em;
256: -webkit-column-count: 5;
257: -webkit-column-gap: 1em;
258: }
259: #base64-table thead { display: none; }
260: #base64-table * { border: none; }
261: #base64-table tbody td:first-child:after { content: ':'; }
262: #base64-table tbody td:last-child { text-align: right; }
263:
1.1 mike 264: #named-character-references-table {
1.19 mike 265: white-space: nowrap;
1.1 mike 266: font-size: 0.6em;
1.19 mike 267: column-width: 30em;
1.1 mike 268: column-gap: 1em;
1.19 mike 269: -moz-column-width: 30em;
1.1 mike 270: -moz-column-gap: 1em;
1.19 mike 271: -webkit-column-width: 30em;
1.1 mike 272: -webkit-column-gap: 1em;
273: }
1.19 mike 274: #named-character-references-table > table > tbody > tr > td:first-child + td,
1.1 mike 275: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
276: #named-character-references-table > table > tbody > tr > td:last-child:hover > span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
1.19 mike 277: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
1.1 mike 278:
1.2 mike 279: .glyph.control { color: red; }
280:
1.4 mike 281: @font-face {
282: font-family: 'Essays1743';
283: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
284: }
285: @font-face {
286: font-family: 'Essays1743';
287: font-weight: bold;
288: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
289: }
290: @font-face {
291: font-family: 'Essays1743';
292: font-style: italic;
293: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
294: }
295: @font-face {
296: font-family: 'Essays1743';
297: font-style: italic;
298: font-weight: bold;
299: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
300: }
301:
1.61 mike 302: </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script type="text/javascript">
1.45 mike 303: function getCookie(name) {
304: var params = location.search.substr(1).split("&");
305: for (var index = 0; index < params.length; index++) {
306: if (params[index] == name)
307: return "1";
308: var data = params[index].split("=");
309: if (data[0] == name)
310: return unescape(data[1]);
311: }
312: var cookies = document.cookie.split("; ");
313: for (var index = 0; index < cookies.length; index++) {
314: var data = cookies[index].split("=");
315: if (data[0] == name)
316: return unescape(data[1]);
317: }
318: return null;
319: }
320: </script>
1.1 mike 321: <script src="link-fixup.js"></script>
1.36 mike 322: <link href="style.css" rel="stylesheet"><link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
1.1 mike 323: <link href="spec.html#contents" title="Table of contents" rel="index">
1.47 mike 324: <link href="the-canvas-element.html" title="4.8.11 The canvas element" rel="next">
1.54 mike 325: </head><body><div class="head" id="head">
1.1 mike 326: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
1.3 mike 327:
1.1 mike 328: <h1>HTML5</h1>
329: </div><div>
1.36 mike 330: <a href="embedded-content-1.html" class="prev">4.8 Embedded content</a> –
1.1 mike 331: <a href="spec.html#contents">Table of contents</a> –
1.47 mike 332: <a href="the-canvas-element.html" class="next">4.8.11 The canvas element</a>
333: <ol class="toc"><li><ol><li><ol><li><a href="the-iframe-element.html#the-iframe-element"><span class="secno">4.8.2 </span>The <code>iframe</code> element</a></li><li><a href="the-iframe-element.html#the-embed-element"><span class="secno">4.8.3 </span>The <code>embed</code> element</a></li><li><a href="the-iframe-element.html#the-object-element"><span class="secno">4.8.4 </span>The <code>object</code> element</a></li><li><a href="the-iframe-element.html#the-param-element"><span class="secno">4.8.5 </span>The <code>param</code> element</a></li><li><a href="the-iframe-element.html#the-video-element"><span class="secno">4.8.6 </span>The <code>video</code> element</a></li><li><a href="the-iframe-element.html#the-audio-element"><span class="secno">4.8.7 </span>The <code>audio</code> element</a></li><li><a href="the-iframe-element.html#the-source-element"><span class="secno">4.8.8 </span>The <code>source</code> element</a></li><li><a href="the-iframe-element.html#the-track-element"><span class="secno">4.8.9 </span>The <code>track</code> element</a></li><li><a href="the-iframe-element.html#media-elements"><span class="secno">4.8.10 </span>Media elements</a>
1.65 mike 334: <ol><li><a href="the-iframe-element.html#error-codes"><span class="secno">4.8.10.1 </span>Error codes</a></li><li><a href="the-iframe-element.html#location-of-the-media-resource"><span class="secno">4.8.10.2 </span>Location of the media resource</a></li><li><a href="the-iframe-element.html#mime-types"><span class="secno">4.8.10.3 </span>MIME types</a></li><li><a href="the-iframe-element.html#network-states"><span class="secno">4.8.10.4 </span>Network states</a></li><li><a href="the-iframe-element.html#loading-the-media-resource"><span class="secno">4.8.10.5 </span>Loading the media resource</a></li><li><a href="the-iframe-element.html#offsets-into-the-media-resource"><span class="secno">4.8.10.6 </span>Offsets into the media resource</a></li><li><a href="the-iframe-element.html#ready-states"><span class="secno">4.8.10.7 </span>Ready states</a></li><li><a href="the-iframe-element.html#playing-the-media-resource"><span class="secno">4.8.10.8 </span>Playing the media resource</a></li><li><a href="the-iframe-element.html#seeking"><span class="secno">4.8.10.9 </span>Seeking</a></li><li><a href="the-iframe-element.html#media-resources-with-multiple-media-tracks"><span class="secno">4.8.10.10 </span>Media resources with multiple media tracks</a>
1.76 mike 335: <ol><li><a href="the-iframe-element.html#audiotracklist-and-videotracklist-objects"><span class="secno">4.8.10.10.1 </span><code>AudioTrackList</code> and <code>VideoTrackList</code> objects</a></li><li><a href="the-iframe-element.html#selecting-specific-audio-and-video-tracks-declaratively"><span class="secno">4.8.10.10.2 </span>Selecting specific audio and video tracks declaratively</a></li></ol></li><li><a href="the-iframe-element.html#synchronising-multiple-media-elements"><span class="secno">4.8.10.11 </span>Synchronising multiple media elements</a>
1.47 mike 336: <ol><li><a href="the-iframe-element.html#introduction-0"><span class="secno">4.8.10.11.1 </span>Introduction</a></li><li><a href="the-iframe-element.html#media-controllers"><span class="secno">4.8.10.11.2 </span>Media controllers</a></li><li><a href="the-iframe-element.html#assigning-a-media-controller-declaratively"><span class="secno">4.8.10.11.3 </span>Assigning a media controller declaratively</a></li></ol></li><li><a href="the-iframe-element.html#timed-text-tracks"><span class="secno">4.8.10.12 </span>Timed text tracks</a>
1.121 mike 337: <ol><li><a href="the-iframe-element.html#text-track-model"><span class="secno">4.8.10.12.1 </span>Text track model</a></li><li><a href="the-iframe-element.html#sourcing-in-band-text-tracks"><span class="secno">4.8.10.12.2 </span>Sourcing in-band text tracks</a></li><li><a href="the-iframe-element.html#sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</a></li><li><a href="the-iframe-element.html#text-track-api"><span class="secno">4.8.10.12.4 </span>Text track API</a></li><li><a href="the-iframe-element.html#text-tracks-describing-chapters"><span class="secno">4.8.10.12.5 </span>Text tracks describing chapters</a></li><li><a href="the-iframe-element.html#cue-events"><span class="secno">4.8.10.12.6 </span>Event definitions</a></li></ol></li><li><a href="the-iframe-element.html#user-interface"><span class="secno">4.8.10.13 </span>User interface</a></li><li><a href="the-iframe-element.html#time-ranges"><span class="secno">4.8.10.14 </span>Time ranges</a></li><li><a href="the-iframe-element.html#event-definitions"><span class="secno">4.8.10.15 </span>Event definitions</a></li><li><a href="the-iframe-element.html#mediaevents"><span class="secno">4.8.10.16 </span>Event summary</a></li><li><a href="the-iframe-element.html#security-and-privacy-considerations"><span class="secno">4.8.10.17 </span>Security and privacy considerations</a></li><li><a href="the-iframe-element.html#best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.18 </span>Best practices for authors using media elements</a></li><li><a href="the-iframe-element.html#best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.19 </span>Best practices for implementors of media elements</a></li></ol></li></ol></li></ol></li></ol></div>
1.1 mike 338:
1.25 mike 339: <h4 id="the-iframe-element"><span class="secno">4.8.2 </span>The <dfn><code>iframe</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
1.1 mike 340: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
341: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
342: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
343: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 344: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.16 mike 345: <dt>Contexts in which this element can be used:</dt>
1.1 mike 346: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
347: <dt>Content model:</dt>
1.18 mike 348: <dd>Text that conforms to <a href="#iframe-content-model">the requirements given in the prose</a>.</dd>
1.1 mike 349: <dt>Content attributes:</dt>
350: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
351: <dd><code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code></dd>
352: <dd><code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code></dd>
353: <dd><code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code></dd>
354: <dd><code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code></dd>
355: <dd><code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code></dd>
356: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
357: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
358: <dt>DOM interface:</dt>
359: <dd>
360: <pre class="idl">interface <dfn id="htmliframeelement">HTMLIFrameElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
361: attribute DOMString <a href="#dom-iframe-src" title="dom-iframe-src">src</a>;
362: attribute DOMString <a href="#dom-iframe-srcdoc" title="dom-iframe-srcdoc">srcdoc</a>;
363: attribute DOMString <a href="#dom-iframe-name" title="dom-iframe-name">name</a>;
1.81 mike 364: [PutForwards=<span title="dom-DOMSettableTokenList-value">value</span>] readonly attribute <a href="infrastructure.html#domsettabletokenlist">DOMSettableTokenList</a> <a href="#dom-iframe-sandbox" title="dom-iframe-sandbox">sandbox</a>;
1.1 mike 365: attribute boolean <a href="#dom-iframe-seamless" title="dom-iframe-seamless">seamless</a>;
366: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
367: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1.68 mike 368: readonly attribute Document? <a href="#dom-iframe-contentdocument" title="dom-iframe-contentDocument">contentDocument</a>;
369: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a>? <a href="#dom-iframe-contentwindow" title="dom-iframe-contentWindow">contentWindow</a>;
1.1 mike 370: };</pre>
371: </dd>
1.101 mike 372: </dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
1.1 mike 373: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p><p>The <dfn id="attr-iframe-src" title="attr-iframe-src"><code>src</code></dfn> attribute
374: gives the address of a page that the <a href="browsers.html#nested-browsing-context">nested browsing
375: context</a> is to contain. The attribute, if present, must be a
376: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
377: spaces</a>.</p><p>The <dfn id="attr-iframe-srcdoc" title="attr-iframe-srcdoc"><code>srcdoc</code></dfn>
378: attribute gives the content of the page that the <a href="browsers.html#nested-browsing-context">nested
1.32 mike 379: browsing context</a> is to contain. The value of the attribute is
1.82 mike 380: the source of <dfn id="an-iframe-srcdoc-document">an <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code> document</dfn>.</p><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="infrastructure.html#html-documents">HTML documents</a>,
1.101 mike 381: the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
1.1 mike 382: syntax</a> that consists of the following syntactic components,
1.101 mike 383: in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
1.1 mike 384: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
385:
1.101 mike 386: <li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
1.1 mike 387:
1.101 mike 388: </li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
1.1 mike 389: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
390:
1.101 mike 391: <li>The root element, in the form of an <code><a href="semantics.html#the-html-element">html</a></code> <a href="syntax.html#syntax-elements" title="syntax-elements">element</a>.</li>
1.1 mike 392:
1.101 mike 393: <li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
1.1 mike 394: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
395:
1.82 mike 396: </ol><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="infrastructure.html#xml-documents">XML documents</a>,
1.1 mike 397: the attribute, if present, must have a value that matches the
398: production labeled <code><a href="infrastructure.html#document">document</a></code> in the XML
1.101 mike 399: specification. <a href="references.html#refsXML">[XML]</a></p><p>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute and the
1.1 mike 400: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute are both
401: specified together, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code>
402: attribute takes priority. This allows authors to provide a fallback
403: <a href="urls.html#url">URL</a> for legacy user agents that do not support the
404: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute.</p><div class="impl">
405:
406: <p>When an <code><a href="#the-iframe-element">iframe</a></code> element is first <a href="infrastructure.html#insert-an-element-into-a-document" title="insert
407: an element into a document">inserted into a document</a>, the
408: user agent must create a <a href="browsers.html#nested-browsing-context">nested browsing context</a>, and
409: then <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> for the
410: first time.</p>
411:
412: <p>Whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a <a href="browsers.html#nested-browsing-context">nested
1.32 mike 413: browsing context</a> has its <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute set, changed, or
414: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.1 mike 415: attributes</a>.</p>
416:
417: <p>Similarly, whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a
418: <a href="browsers.html#nested-browsing-context">nested browsing context</a> but with no <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute specified has its
1.32 mike 419: <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute set, changed, or
420: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.46 mike 421: attributes</a>.</p>
1.1 mike 422: <p>When the user agent is to <dfn id="process-the-iframe-attributes">process the <code>iframe</code>
423: attributes</dfn>, it must run the first appropriate steps from the
424: following list:</p>
425:
426: <dl class="switch"><dt>If the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute
427: is specified</dt>
428:
1.46 mike 429: <dd><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 430: <a href="browsers.html#browsing-context">browsing context</a> to a resource whose
1.101 mike 431: <a href="fetching-resources.html#content-type">Content-Type</a> is <code><a href="iana.html#text-html">text/html</a></code>, whose
1.34 mike 432: <a href="urls.html#url">URL</a> is <code><a href="urls.html#about:srcdoc">about:srcdoc</a></code>, and whose data
433: consists of the value of the attribute. The resulting
434: <code><a href="infrastructure.html#document">Document</a></code> must be considered <a href="#an-iframe-srcdoc-document">an
435: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
436: document</a>.</p></dd>
1.1 mike 437:
438: <dt>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code>
439: attribute is specified but the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not</dt>
440:
441: <dd>
442:
443: <ol><li><p>If the value of the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is the empty string,
444: jump to the <i title="">empty</i> step below.</p></li>
445:
446: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of
447: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute, relative
448: to the <code><a href="#the-iframe-element">iframe</a></code> element.</p></li>
449:
450: <li><p>If that is not successful, then jump to the <i title="">empty</i> step below.</p></li>
451:
452: <li><p>If the resulting <a href="urls.html#absolute-url">absolute URL</a> is an
453: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for the string
454: "<code><a href="fetching-resources.html#about:blank">about:blank</a></code>", and the user agent is processing this
455: <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first time, then jump to
456: the <i title="">empty</i> step below. (In cases other than the
457: first time, <code><a href="fetching-resources.html#about:blank">about:blank</a></code> is loaded
458: normally.)</p></li>
459:
1.46 mike 460: <li><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 461: <a href="browsers.html#browsing-context">browsing context</a> to the resulting <a href="urls.html#absolute-url">absolute
1.1 mike 462: URL</a>.</p></li>
463:
464: </ol><p><i>Empty</i>: When the steps above require the user agent to
465: jump to the <i title="">empty</i> step, if the user agent is
466: processing this <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first
467: time, then the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
1.66 mike 468: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-load">load</code> at the <code><a href="#the-iframe-element">iframe</a></code> element.
469: (After jumping to this step, the above steps are not resumed.)
470: <span class="note">No <code title="event-load">load</code> event
471: is fired at the <code><a href="fetching-resources.html#about:blank">about:blank</a></code> document
472: itself.</span></p>
1.1 mike 473:
474: </dd>
475:
476: <dt>Otherwise</dt>
477:
478: <dd>
479:
480: <p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
481: named <code title="event-load">load</code> at the
482: <code><a href="#the-iframe-element">iframe</a></code> element.</p>
483:
484: </dd>
485:
486: </dl><p>Any <a href="history.html#navigate" title="navigate">navigation</a> required of the user
487: agent in the <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a>
488: algorithm must be completed with the <code><a href="#the-iframe-element">iframe</a></code> element's
489: document's <a href="browsers.html#browsing-context">browsing context</a> as the <a href="history.html#source-browsing-context">source
490: browsing context</a>.</p>
491:
1.8 mike 492: <p>Furthermore, if the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="history.html#session-history">session
493: history</a> contained only one <code><a href="infrastructure.html#document">Document</a></code> when the
494: <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> algorithm
495: was invoked, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
496: <code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
497: was created, then any <a href="history.html#navigate" title="navigate">navigation</a>
498: required of the user agent in that algorithm must be completed with
1.46 mike 499: <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
1.1 mike 500: </div><p class="note">If, when the element is created, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not set, and
501: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is either
502: also not set or set but its value cannot be <a href="urls.html#resolve-a-url" title="resolve a
503: url">resolved</a>, the browsing context will remain at the
504: initial <code><a href="fetching-resources.html#about:blank">about:blank</a></code> page.</p><p class="note">If the user <a href="history.html#navigate" title="navigate">navigates</a>
505: away from this page, the <code><a href="#the-iframe-element">iframe</a></code>'s corresponding
506: <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object will proxy new <code><a href="browsers.html#window">Window</a></code>
1.9 mike 507: objects for new <code><a href="infrastructure.html#document">Document</a></code> objects, but the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute will not change.</p><div class="impl">
508:
509: <div class="note">
510:
511: <p><a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">Removing</a>
512: an <code><a href="#the-iframe-element">iframe</a></code> from a <code><a href="infrastructure.html#document">Document</a></code> does not cause
513: its <a href="browsers.html#browsing-context">browsing context</a> to be discarded. Indeed, an
514: <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> can survive its
515: original parent <code><a href="infrastructure.html#document">Document</a></code> if its <code><a href="#the-iframe-element">iframe</a></code> is
516: moved to another <code><a href="infrastructure.html#document">Document</a></code>.</p>
517:
1.10 mike 518: <p>On the other hand, if an <code><a href="#the-iframe-element">iframe</a></code> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">removed</a> from a
519: <code><a href="infrastructure.html#document">Document</a></code> and is then subsequently garbage collected,
520: this will likely mean (in the absence of other references) that the
521: <a href="browsers.html#child-browsing-context">child browsing context</a>'s <code><a href="browsers.html#windowproxy">WindowProxy</a></code>
522: object will become eligble for garbage collection, which will then
523: lead to that <a href="browsers.html#browsing-context">browsing context</a> being <a href="browsers.html#a-browsing-context-is-discarded" title="a
524: browsing context is discarded">discarded</a>, which will then
525: lead to its <code><a href="infrastructure.html#document">Document</a></code> being <a href="browsers.html#discard-a-document" title="discard a
1.9 mike 526: document">discarded</a> also. This happens without notice to any
527: scripts running in that <code><a href="infrastructure.html#document">Document</a></code>; for example, no
528: <code title="event-unload">unload</code> events are fired (the
1.10 mike 529: "<a href="history.html#unload-a-document">unload a document</a>" steps are not run).</p>
1.9 mike 530:
531: </div>
532:
533: </div><div class="example">
1.1 mike 534:
535: <p>Here a blog uses the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute in conjunction
536: with the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> and <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attributes described
537: below to provide users of user agents that support this feature
538: with an extra layer of protection from script injection in the blog
539: post comments:</p>
540:
541: <pre><article>
542: <h1>I got my own magazine!</h1>
543: <p>After much effort, I've finally found a publisher, and so now I
544: have my own magazine! Isn't that awesome?! The first issue will come
545: out in September, and we have articles about getting food, and about
546: getting in boxes, it's going to be great!</p>
547: <footer>
1.144 ! mike 548: <p>Written by <a href="/users/cap">cap</a>.
! 549: <time pubdate>2009-08-21T23:32Z</time></p>
1.1 mike 550: </footer>
551: <article>
1.144 ! mike 552: <footer> At <time pubdate>2009-08-21T23:35Z</time>, <a href="/users/ch">ch</a> writes: </footer>
1.33 mike 553: <iframe seamless sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
1.1 mike 554: </article>
555: <article>
1.144 ! mike 556: <footer> At <time pubdate>2009-08-21T23:44Z</time>, <a href="/users/cap">cap</a> writes: </footer>
1.33 mike 557: <iframe seamless sandbox srcdoc="<p>Yeah, you can see it <a href=&quot;/gallery?mode=cover&amp;amp;page=1&quot;>in my gallery</a>."></iframe>
1.1 mike 558: </article>
559: <article>
1.144 ! mike 560: <footer> At <time pubdate>2009-08-21T23:58Z</time>, <a href="/users/ch">ch</a> writes: </footer>
1.33 mike 561: <iframe seamless sandbox srcdoc="<p>hey that's earl's table.
1.1 mike 562: <p>you should get earl&amp;amp;me on the next cover."></iframe>
563: </article></pre>
564:
565: <p>Notice the way that quotes have to be escaped (otherwise the
1.101 mike 566: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute would end
567: prematurely), and the way raw ampersands (e.g. in URLs or in prose)
568: mentioned in the sandboxed content have to be <em>doubly</em>
569: escaped — once so that the ampersand is preserved when
570: originally parsing the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute, and once more
1.1 mike 571: to prevent the ampersand from being misinterpreted when parsing the
572: sandboxed content.</p>
573:
1.101 mike 574: </div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
1.1 mike 575: remember to use U+0022 QUOTATION MARK characters (") to wrap the
576: attribute contents and then to escape all U+0022 QUOTATION MARK (")
577: and U+0026 AMPERSAND (&) characters, and to specify the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, to ensure safe
1.141 mike 578: embedding of content.</p><p class="note">Due to restrictions of <a href="the-xhtml-syntax.html#the-xhtml-syntax">the XHTML
579: syntax</a>, in XML the U+003C LESS-THAN SIGN character (<)
580: needs to be escaped as well. In order to prevent <a href="http://www.w3.org/TR/REC-xml/#AVNormalize">attribute-value
1.39 mike 581: normalization</a>, some of XML's whitespace characters —
1.52 mike 582: specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
1.39 mike 583: (LF), and U+000D CARRIAGE RETURN (CR) — also need to be
1.101 mike 584: escaped. <a href="references.html#refsXML">[XML]</a></p><hr><p>The <dfn id="attr-iframe-name" title="attr-iframe-name"><code>name</code></dfn>
1.1 mike 585: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
586: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
587: browsing context</a>. <span class="impl">When the browsing
588: context is created, if the attribute is present, the <a href="browsers.html#browsing-context-name">browsing
589: context name</a> must be set to the value of this attribute;
590: otherwise, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set to the
591: empty string.</span></p><div class="impl">
592:
593: <p>Whenever the <code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code> attribute
594: is set, the nested <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#browsing-context-name" title="browsing context name">name</a> must be changed to the new
595: value. If the attribute is removed, the <a href="browsers.html#browsing-context-name">browsing context
596: name</a> must be set to the empty string.</p>
597:
598: <p>When content loads in an <code><a href="#the-iframe-element">iframe</a></code>, after any <code title="event-load">load</code> events are fired within the content
599: itself, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
600: a simple event</a> named <code title="event-load">load</code> at
601: the <code><a href="#the-iframe-element">iframe</a></code> element. When content whose <a href="urls.html#url">URL</a>
602: has the <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code>
603: element's <code><a href="infrastructure.html#document">Document</a></code> fails to load (e.g. due to a DNS
604: error, network error, or if the server returned a 4xx or 5xx status
605: code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or
606: equivalent</a>), then the user agent must <a href="webappapis.html#queue-a-task">queue a
607: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the element instead. (This event
1.101 mike 608: does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
1.1 mike 609: script errors, or any errors for cross-origin resources.)</p>
610:
611: <p>The <a href="webappapis.html#task-source">task source</a> for these <a href="webappapis.html#concept-task" title="concept-task">tasks</a> is the <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation
612: task source</a>.</p>
613:
614: <p class="note">A <code title="event-load">load</code> event is also
615: fired at the <code><a href="#the-iframe-element">iframe</a></code> element when it is created if no
616: other data is loaded in it.</p>
617:
618: <p>When there is an <a href="dom.html#active-parser">active parser</a> in the
619: <code><a href="#the-iframe-element">iframe</a></code>, and when anything in the <code><a href="#the-iframe-element">iframe</a></code> is
1.101 mike 620: <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
1.1 mike 621: the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a>'s
622: <a href="browsers.html#active-document">active document</a>, the <code><a href="#the-iframe-element">iframe</a></code> must
1.101 mike 623: <a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
1.1 mike 624:
625: <p class="note">If, during the handling of the <code title="event-load">load</code> event, the <a href="browsers.html#browsing-context">browsing
1.101 mike 626: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> is again <a href="history.html#navigate" title="navigate">navigated</a>, that will further <a href="the-end.html#delay-the-load-event">delay the
1.1 mike 627: load event</a>.</p>
628:
629: </div><hr><p>The <dfn id="attr-iframe-sandbox" title="attr-iframe-sandbox"><code>sandbox</code></dfn>
630: attribute, when specified, enables a set of extra restrictions on
631: any content hosted by the <code><a href="#the-iframe-element">iframe</a></code>. Its value must be an
1.20 mike 632: <a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique space-separated tokens</a> that are
1.77 mike 633: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a>. The allowed values are
1.1 mike 634: <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code>,
1.77 mike 635: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>,
636: <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>, and
637: <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>.
638:
639: When the attribute is set, the content is treated as being from a
640: unique <a href="origin-0.html#origin">origin</a>, forms and scripts are disabled, links
641: are prevented from targeting other <a href="browsers.html#browsing-context" title="browsing
1.114 mike 642: context">browsing contexts</a>, and plugins are secured. The
1.1 mike 643: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
644: keyword allows the content to be treated as being from the same
645: origin instead of forcing it into a unique origin, the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
646: keyword allows the content to <a href="history.html#navigate">navigate</a> its
647: <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>, and the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> and <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
648: keywords re-enable forms and scripts respectively (though scripts
1.77 mike 649: are still prevented from creating popups).</p><p class="warning">Setting both the
650: <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code> and
1.1 mike 651: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
652: keywords together when the embedded page has the <a href="origin-0.html#same-origin">same
653: origin</a> as the page containing the <code><a href="#the-iframe-element">iframe</a></code> allows
654: the embedded page to simply remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">Sandboxing hostile content is of minimal help if
655: an attacker can convince the user to just visit the hostile content
656: directly, rather than in the <code><a href="#the-iframe-element">iframe</a></code>. To limit the
657: damage that can be caused by hostile HTML content, it should be
1.127 mike 658: served from a separate dedicated domain.</p><div class="impl">
1.1 mike 659:
1.46 mike 660:
1.1 mike 661: <p>While the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
662: attribute is specified, the <code><a href="#the-iframe-element">iframe</a></code> element's
663: <a href="browsers.html#nested-browsing-context">nested browsing context</a> must have the flags given in
664: the following list set. In addition, any browsing contexts <a href="browsers.html#nested-browsing-context" title="nested browsing context">nested</a> within an
665: <code><a href="#the-iframe-element">iframe</a></code>, either directly or indirectly, must have all
666: the flags set on them as were set on the <code><a href="#the-iframe-element">iframe</a></code>'s
667: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> when the
668: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
669:
670: <dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
671:
672: <dd>
673:
674: <p>This flag <a href="history.html#sandboxLinks">prevents content from
675: navigating browsing contexts other than the sandboxed browsing
676: context itself</a> (or browsing contexts further nested inside
677: it), and the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> (which is
678: protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
679: context flag</a> defined next).</p>
680:
681: <p>This flag also <a href="browsers.html#sandboxWindowOpen">prevents content
682: from creating new auxiliary browsing contexts</a>, e.g. using the
1.72 mike 683: <code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute, the
684: <code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> method, or the <code title="dom-showModalDialog"><a href="timers.html#dom-showmodaldialog">showModalDialog()</a></code> method.</p>
1.1 mike 685:
686: </dd>
687:
688:
689: <dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
690: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
691: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
692: found to have the <dfn id="attr-iframe-sandbox-allow-top-navigation" title="attr-iframe-sandbox-allow-top-navigation"><code>allow-top-navigation</code></dfn>
693: keyword set</dt>
694:
695: <dd>
696:
697: <p>This flag <a href="history.html#sandboxLinks">prevents content from
698: navigating their <span>top-level browsing context</span></a>.</p>
699:
700: <p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
701: is set, content can navigate its <a href="browsers.html#top-level-browsing-context">top-level browsing
702: context</a>, but other <a href="browsers.html#browsing-context" title="browsing context">browsing
703: contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
704: navigation browsing context flag</a> defined above.</p>
705:
706: </dd>
707:
708:
709: <dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
710:
711: <dd>
712:
713: <p>This flag prevents content from instantiating <a href="infrastructure.html#plugin" title="plugin">plugins</a>, whether using <a href="#sandboxPluginEmbed">the <code>embed</code> element</a>, <a href="#sandboxPluginObject">the <code>object</code> element</a>,
1.101 mike 714: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
1.1 mike 715: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
1.114 mike 716: browsing context</a>, unless those <a href="infrastructure.html#plugin" title="plugin">plugins</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>.</p>
1.1 mike 717:
718: </dd>
719:
720:
721: <dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
722:
723: <dd>
724:
725: <p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attribute on
726: descendant <code><a href="#the-iframe-element">iframe</a></code> elements.</p>
727:
728: <p class="note">This prevents a page inserted using the <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
729: keyword from using a CSS-selector-based method of probing the DOM
730: of other pages on the same site (in particular, pages that contain
731: user-sensitive information).</p>
732:
1.46 mike 733:
1.1 mike 734:
735: </dd>
736:
737:
738: <dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn>, unless
739: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
740: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
741: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-same-origin" title="attr-iframe-sandbox-allow-same-origin"><code>allow-same-origin</code></dfn>
742: keyword set</dt>
743:
744: <dd>
745:
746: <p>This flag <a href="origin-0.html#sandboxOrigin">forces content into a unique
747: origin</a>, thus preventing it from accessing other content from
748: the same <a href="origin-0.html#origin">origin</a>.</p>
749:
750: <p>This flag also <a href="dom.html#sandboxCookies">prevents script from
751: reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
1.38 mike 752: attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code>.
1.1 mike 753:
1.101 mike 754: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
1.1 mike 755:
756: </p>
757:
758: <div class="note">
759:
760: <p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
761: attribute is intended for two cases.</p>
762:
763: <p>First, it can be used to allow content from the same site to
764: be sandboxed to disable scripting, while still allowing access to
765: the DOM of the sandboxed content.</p>
766:
767: <p>Second, it can be used to embed content from a third-party
768: site, sandboxed to prevent that site from opening popup windows,
769: etc, without preventing the embedded page from communicating back
770: to its originating site, using the database APIs to store data,
771: etc.</p>
772:
773: </div>
774:
775: </dd>
776:
777:
778: <dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn>, unless
779: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
780: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
781: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-forms" title="attr-iframe-sandbox-allow-forms"><code>allow-forms</code></dfn>
782: keyword set</dt>
783:
784: <dd>
785:
786: <p>This flag <a href="association-of-controls-and-forms.html#sandboxSubmitBlocked">blocks form
787: submission</a>.</p>
788:
789: </dd>
790:
791:
792: <dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn>, unless
793: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
794: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
795: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-scripts" title="attr-iframe-sandbox-allow-scripts"><code>allow-scripts</code></dfn>
796: keyword set</dt>
797:
798: <dd>
799:
800: <p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
801: execution</a>.</p>
802:
803: </dd>
804:
805:
806: <dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
807: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
808: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
809: found to have the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
810: keyword (defined above) set</dt>
811:
812: <dd>
813:
814: <p>This flag blocks features that trigger automatically, such as
1.47 mike 815: <a href="#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
1.1 mike 816: video</a> or <a href="association-of-controls-and-forms.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
817: focusing a form control</a>. It is relaxed by the same flag as
818: scripts, because when scripts are enabled these features are
819: trivially possible anyway, and it would be unfortunate to force
820: authors to use script to do them when sandboxed rather than
821: allowing them to use the declarative features.</p>
822:
823: </dd>
824:
825: </dl><p>These flags must not be set unless the conditions listed above
826: define them as being set.</p>
827:
828: <p class="warning">These flags only take effect when the
829: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code> is
1.15 mike 830: <a href="history.html#navigate" title="navigate">navigated</a>. Removing them, or removing
1.1 mike 831: the entire <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
832: attribute, has no effect on an already-loaded page.</p>
833:
834: </div><div class="example">
835:
836: <p>In this example, some completely-unknown, potentially hostile,
837: user-provided HTML content is embedded in a page. Because it is
1.127 mike 838: served from a separate domain, it is affected by all the normal
839: cross-site restrictions. In addition, the embedded page has
840: scripting disabled, plugins disabled, forms disabled, and it cannot
841: navigate any frames or windows other than itself (or any frames or
842: windows it itself embeds).</p>
1.1 mike 843:
844: <pre><p>We're not scared of you! Here is your content, unedited:</p>
1.127 mike 845: <iframe sandbox src="http://usercontent.example.net/getusercontent.cgi?id=12193"></iframe></pre>
1.1 mike 846:
1.127 mike 847: <p class="warning">It is important to use a separate domain so that
848: if the attacker convinces the user to visit that page directly, the
849: page doesn't run in the context of the site's origin, which would
850: make the user vulnerable to any attack found in the page.</p>
1.1 mike 851:
852: </div><div class="example">
853:
854: <p>In this example, a gadget from another site is embedded. The
855: gadget has scripting and forms enabled, and the origin sandbox
856: restrictions are lifted, allowing the gadget to communicate with
857: its originating server. The sandbox is still useful, however, as it
858: disables plugins and popups, thus reducing the risk of the user
859: being exposed to malware and other annoyances.</p>
860:
861: <pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
862: src="http://maps.example.com/embedded.html"></iframe></pre>
863:
864: </div><div class="example">
865:
866: <p>Suppose a file A contained the following fragment:</p>
867:
868: <pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
869:
870: <p>Suppose that file B contained an iframe also:</p>
871:
872: <pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
873:
874: <p>Further, suppose that file C contained a link:</p>
875:
876: <pre><a href=D>Link</a></pre>
877:
878: <p>For this example, suppose all the files were served as
1.101 mike 879: <code><a href="iana.html#text-html">text/html</a></code>.</p>
1.1 mike 880:
881: <p>Page C in this scenario has all the sandboxing flags
882: set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
883: scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
884: keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
885: disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
886: have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
887: set.</p>
888:
1.142 mike 889: <p>Suppose now that a script in A removes all the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attributes in A
890: and B. This would change nothing
891: immediately. If the user clicked the link in C, loading page D into
892: the <code><a href="#the-iframe-element">iframe</a></code> in B, page D would now act as if the
893: <code><a href="#the-iframe-element">iframe</a></code> in B had the <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
1.1 mike 894: and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
895: set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
896: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
897: loaded.</p>
898:
899: <p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
900: ill-advised, because it can make it quite hard to reason about what
901: will be allowed and what will not.</p>
902:
1.127 mike 903: </div><p class="note">Potentially hostile files should not be served from
904: the same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code>
905: element. Using a different domain ensures that scripts in the files
906: are unable to attack the site, even if the user is tricked into
907: visiting those pages directly, without the protection of the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">If the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
1.1 mike 908: keyword is set along with <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
909: keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
910: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
911: "sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
912: reload itself, effectively breaking out of the sandbox
1.46 mike 913: altogether.</p><hr><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
1.1 mike 914: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
915: indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
916: context</a> is to be rendered in a manner that makes it appear to
917: be part of the containing document (seamlessly included in the
918: parent document). <span class="impl">Specifically, when the
919: attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
920: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
921: the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
922: <code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
923: <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
924: <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
925: document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
926: document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
927: address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
1.33 mike 928: <code><a href="#the-iframe-element">iframe</a></code> element's document, or the <a href="browsers.html#browsing-context">browsing
929: context</a>'s <a href="browsers.html#active-document">active document</a> is <a href="#an-iframe-srcdoc-document">an
930: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
931: document</a>, the following requirements apply:</span></p><div class="impl">
1.1 mike 932:
1.13 mike 933: <ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
934: flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
935: will <a href="history.html#seamlessLinks">cause links to open in the parent
936: browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
937: override</a> is used (<code title="">target="_self"</code>).</p></li>
1.1 mike 938:
939: <li><p>In a CSS-supporting user agent: the user agent must add all
940: the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
941: the cascade of the <a href="browsers.html#active-document">active document</a> of the
942: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
943: at the appropriate cascade levels, before any style sheets
944: specified by the document itself.</p></li>
945:
946: <li><p>In a CSS-supporting user agent: the user agent must, for the
947: purpose of CSS property inheritance only, treat the root element of
948: the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
949: element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
950: the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
951: root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
952: inherit the computed values of those properties on the
953: <code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
954: values.)</p></li>
955:
956: <li><p>In visual media, in a CSS-supporting user agent: the user agent
957: should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
958: width that the element would have if it was a non-replaced
959: block-level element with 'width: auto'.</p></li>
960:
961: <li><p>In visual media, in a CSS-supporting user agent: the user
962: agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
963: the height of the bounding box around the content rendered in the
964: <code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
965: bullet point), as it would be if the scrolling position was such
966: that the top of the viewport for the content rendered in the
967: <code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
968: canvas.</p></li>
969:
970: <li>
971:
972: <p>In visual media, in a CSS-supporting user agent: the user agent
973: must force the height of the initial containing block of the
974: <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
975: context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
976:
977: <p class="note">This is intended to get around the otherwise
978: circular dependency of percentage dimensions that depend on the
979: height of the containing block, thus affecting the height of the
980: document's bounding box, thus affecting the height of the
981: viewport, thus affecting the size of the initial containing
982: block.</p>
983:
984: </li>
985:
986: <li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
987: browsing context</a> without announcing that it is a separate
988: document.</p></li>
989:
990: <li>
991:
992: <p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
993: document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
994: context</a> was part of the document that the
1.35 mike 995: <code><a href="#the-iframe-element">iframe</a></code> is in, if any.</p>
1.1 mike 996:
997: <p class="example">For example if the user agent supports listing
998: all the links in a document, links in "seamlessly" nested
999: documents would be included in that list without being
1000: significantly distinguished from links in the document itself.</p>
1001:
1002: </li>
1003:
1004: </ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
1005: conditions listed above are not met, then the user agent should
1006: render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
1007: clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
1008: and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
1009: false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
1010:
1011: <p class="warning">It is important that user agents recheck the
1012: above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
1013: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
1014: changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
1015: gets unset if the <a href="browsers.html#nested-browsing-context">nested browsing context</a> is <a href="history.html#navigate" title="navigate">navigated</a> to another origin.</p>
1016:
1017: </div><p class="note">The attribute can be set or removed dynamically,
1018: with the rendering updating in tandem.</p><div class="example">
1019:
1020: <p>In this example, the site's navigation is embedded using a
1021: client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
1022: <code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
1023: opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
1024: legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
1025: element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
1026: attribute with the value <code title="">_parent</code>. Similarly,
1027: in new user agents the styles of the parent page will be
1028: automatically applied to the contents of the frame, but to support
1029: legacy user agents authors might wish to include the styles
1030: explicitly.</p>
1031:
1032: <pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
1033:
1034: </div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1035: attributes</a> for cases where the embedded content has specific
1036: dimensions (e.g. ad units have well-defined dimensions).</p><p>An <code><a href="#the-iframe-element">iframe</a></code> element never has <a href="content-models.html#fallback-content">fallback
1037: content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
1038: context</a>, regardless of whether the specified initial contents
1039: are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
1040: nothing. (In legacy user agents that do not support
1041: <code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
1.82 mike 1042: that could act as fallback content.)</p><p id="iframe-content-model">When used in <a href="infrastructure.html#html-documents">HTML
1.18 mike 1043: documents</a>, the allowed content model of <code><a href="#the-iframe-element">iframe</a></code>
1.101 mike 1044: elements is text, except that invoking the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment
1.18 mike 1045: parsing algorithm</a> with the <code><a href="#the-iframe-element">iframe</a></code> element as the
1.101 mike 1046: <var title="concept-frag-parse-context"><a href="the-end.html#concept-frag-parse-context">context</a></var> element and
1.48 mike 1047: the text contents as the <var title="">input</var> must result in a
1048: list of nodes that are all <a href="content-models.html#phrasing-content">phrasing content</a>, with no
1.101 mike 1049: <a href="parsing.html#parse-error" title="parse error">parse errors</a> having occurred, with
1.48 mike 1050: no <code><a href="scripting-1.html#the-script-element">script</a></code> elements being anywhere in the list or as
1.18 mike 1051: descendants of elements in the list, and with all the elements in
1052: the list (including their descendants) being themselves
1.82 mike 1053: conforming.</p><p>The <code><a href="#the-iframe-element">iframe</a></code> element must be empty in <a href="infrastructure.html#xml-documents">XML
1.101 mike 1054: documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
1.1 mike 1055: <code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
1056:
1057: <p>The IDL attributes <dfn id="dom-iframe-src" title="dom-iframe-src"><code>src</code></dfn>, <dfn id="dom-iframe-srcdoc" title="dom-iframe-srcdoc"><code>srcdoc</code></dfn>, <dfn id="dom-iframe-name" title="dom-iframe-name"><code>name</code></dfn>, <dfn id="dom-iframe-sandbox" title="dom-iframe-sandbox"><code>sandbox</code></dfn>, and <dfn id="dom-iframe-seamless" title="dom-iframe-seamless"><code>seamless</code></dfn> must
1058: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1059: name.</p>
1060:
1061: <p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
1062: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1063: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
1064: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1065:
1066: <p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
1067: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1068: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
1069: context</a>.</p>
1070:
1071: </div><div class="example">
1072:
1073: <p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
1074: include advertising from an advertising broker:</p>
1075:
1076: <pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
1077: width="468" height="60"></iframe></pre>
1078:
1.46 mike 1079: </div><h4 id="the-embed-element"><span class="secno">4.8.3 </span>The <dfn><code>embed</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
1.1 mike 1080: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1081: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1082: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1083: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 1084: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.16 mike 1085: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1086: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1087: <dt>Content model:</dt>
1088: <dd>Empty.</dd>
1089: <dt>Content attributes:</dt>
1090: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1091: <dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
1092: <dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
1093: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1094: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1095: <dd>Any other attribute that has no namespace (see prose).</dd>
1096: <dt>DOM interface:</dt>
1097: <dd>
1098: <pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1099: attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
1100: attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
1101: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1102: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1103: };</pre>
1104: <div class="impl">
1105: <p>Depending on the type of content instantiated by the
1106: <code><a href="#the-embed-element">embed</a></code> element, the node may also support other
1107: interfaces.</p>
1108: </div>
1109: </dd>
1.101 mike 1110: </dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
1.1 mike 1111: integration point for an external (typically non-HTML) application
1112: or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
1113: gives the address of the resource being embedded. The attribute, if
1114: present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
1115: surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
1116: attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
1117: plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
1118: MIME type</a>. If both the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute and the <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute are present, then the
1119: <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
1120: same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
1121: metadata</a> of the resource given by the <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute.</p><div class="impl">
1122:
1123: <p>When the element is created with neither a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute nor a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute, and when attributes
1124: are removed such that neither attribute is present on the element
1.47 mike 1125: anymore, and when the element has a <a href="#media-element">media element</a>
1.1 mike 1126: ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
1127: element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
1128: content</a>, any plugins instantiated for the element must be
1129: removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
1130:
1131: <p>An <code><a href="#the-embed-element">embed</a></code> element is said to be <dfn id="concept-embed-active" title="concept-embed-active">potentially active</dfn> when the
1132: following conditions are all met simultaneously:</p>
1133:
1134: <ul class="brief"><li>The element is <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>.</li>
1135: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
1136: <li>The element has either a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute set or a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute set (or both).</li>
1137: <li>The element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute is either absent or its value is the empty string.</li>
1.47 mike 1138: <li>The element is not a descendant of a <a href="#media-element">media element</a>.</li>
1.1 mike 1139: <li>The element is not a descendant of an <code><a href="#the-object-element">object</a></code> element that is not showing its <a href="content-models.html#fallback-content">fallback content</a>.</li>
1140: </ul><p>Whenever an <code><a href="#the-embed-element">embed</a></code> element that was not <a href="#concept-embed-active" title="concept-embed-active">potentially active</a> becomes <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, and whenever
1141: a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1142: <code><a href="#the-embed-element">embed</a></code> element's <code title="attr-embed-type"><a href="#attr-embed-type">src</a></code> attribute is set, changed, or
1143: removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1144: <code><a href="#the-embed-element">embed</a></code> element's <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is set, changed, or
1145: removed, the appropriate set of steps from the following is then
1146: applied:</p>
1147:
1148: <dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1149: attribute set</dt>
1150:
1151: <dd>
1152:
1153: <p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
1154: the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1155: attribute, relative to the element. If that is successful, the
1156: user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
1157: URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
1.46 mike 1158: origin</a> if it has one. The <a href="webappapis.html#concept-task" title="concept-task">task</a> that is
1.1 mike 1159: <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking
1160: task source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
1161: appropriate <a href="infrastructure.html#plugin">plugin</a> based on the <a href="#concept-embed-type" title="concept-embed-type">content's type</a>, and hand that
1162: <a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
1.46 mike 1163: previously instantiated plugin for the element.</p>
1.101 mike 1164: <p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
1.1 mike 1165: the element's document.</p>
1.46 mike 1166:
1167:
1.1 mike 1168: </dd>
1169:
1170: <dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1171: attribute set</dt>
1172:
1173: <dd><p>The user agent should find and instantiate an appropriate
1174: <a href="infrastructure.html#plugin">plugin</a> based on the value of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute.</p>
1175:
1176: </dd></dl><p>Whenever an <code><a href="#the-embed-element">embed</a></code> element that was <a href="#concept-embed-active" title="concept-embed-active">potentially active</a> stops being
1177: <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
1178: <a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
1179: be unloaded.</p>
1180:
1.114 mike 1181: <p id="sandboxPluginEmbed">When a <a href="infrastructure.html#plugin">plugin</a> is to be
1.127 mike 1182: instantiated but it cannot be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a> and the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed
1183: plugins browsing context flag</a> was set on the <a href="browsers.html#browsing-context">browsing
1184: context</a> for which the <code><a href="#the-embed-element">embed</a></code> element's
1185: <code><a href="infrastructure.html#document">Document</a></code> is the <a href="browsers.html#active-document">active document</a> when that
1186: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent must not
1187: instantiate the <a href="infrastructure.html#plugin">plugin</a>, and must instead render the
1188: <code><a href="#the-embed-element">embed</a></code> element in a manner that conveys that the
1189: <a href="infrastructure.html#plugin">plugin</a> was disabled. The user agent may offer the user
1190: the option to override the sandbox and instantiate the
1191: <a href="infrastructure.html#plugin">plugin</a> anyway; if the user invokes such an option, the
1192: user agent must act as if the conditions above did not apply for the
1193: purposes of this element.</p>
1.114 mike 1194:
1195: <p class="warning">Plugins that cannot be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a> are disabled in
1196: sandboxed browsing contexts because they might not honor the
1197: restrictions imposed by the sandbox (e.g. they might allow scripting
1198: even when scripting in the sandbox is disabled). User agents should
1199: convey the danger of overriding the sandbox to the user if an option
1200: to do so is provided.</p>
1201:
1.1 mike 1202: <p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
1203: CSS 'display' property. The selected plugin is instantiated even if
1204: the element is hidden with a 'display:none' CSS style.</p>
1205:
1206: <p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
1207: being embedded is defined as follows:</p>
1208:
1209: <ol><li><p>If the element has a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute, and that attribute's
1210: value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
1211: of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
1212: <a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
1213:
1214: <li>
1215:
1.46 mike 1216:
1.1 mike 1217: <p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
1218: component of the <a href="urls.html#url">URL</a> of the specified resource (after
1219: any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1220: supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
1221: type</a> is the type that that plugin can handle.</p>
1222:
1223: <p class="example">For example, a plugin might say that it can
1224: handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
1225: components that end with the four character string "<code title="">.swf</code>".</p>
1226:
1.46 mike 1227:
1228:
1.1 mike 1229:
1230: </li>
1231:
1232: <li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
1233: that is the <a href="#concept-embed-type" title="concept-embed-type">content's
1234: type</a>.</p></li>
1235:
1236: <li><p>Otherwise, the content has no type and there can be no
1237: appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
1238:
1.46 mike 1239:
1.1 mike 1240:
1241: </ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
1242: content</a>. If the user agent can't find a suitable plugin, then
1243: the user agent must use a default plugin. (This default could be as
1244: simple as saying "Unsupported Format".)</p>
1245:
1246: <p>Whether the resource is fetched successfully or not (e.g. whether
1247: the response code was a 2xx code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or equivalent</a>) must be
1248: ignored when determining the resource's type and when handing the
1249: resource to the plugin.</p>
1250:
1251: <p class="note">This allows servers to return data for plugins even
1252: with error responses (e.g. HTTP 500 Internal Server Error codes can
1253: still contain plugin data).</p>
1254:
1.101 mike 1255: </div><p>Any namespace-less attribute other than <code title="attr-embed-name"><a href="obsolete.html#attr-embed-name">name</a></code>, <code title="attr-embed-align"><a href="obsolete.html#attr-embed-align">align</a></code>, <code title="attr-embed-hspace"><a href="obsolete.html#attr-embed-hspace">hspace</a></code>, and <code title="attr-embed-vspace"><a href="obsolete.html#attr-embed-vspace">vspace</a></code> may be specified on the <code><a href="#the-embed-element">embed</a></code> element,
1.1 mike 1256: so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
1257: characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
1258: LATIN CAPITAL LETTER Z). These attributes are then passed as
1.82 mike 1259: parameters to the <a href="infrastructure.html#plugin">plugin</a>.</p><p class="note">All attributes in <a href="infrastructure.html#html-documents">HTML documents</a> get
1.1 mike 1260: lowercased automatically, so the restriction on uppercase letters
1261: doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
1262: that have side-effects beyond just sending parameters to the
1263: <a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
1264:
1265: <p>The user agent should pass the names and values of all the
1266: attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
1267: to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
1268:
1269: <p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
1270: <code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
1271: <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
1272: expose that interface while the element is instantiated.</p>
1273:
1274: </div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1275: attributes</a>.</p><div class="impl">
1276:
1277: <p>The IDL attributes <dfn id="dom-embed-src" title="dom-embed-src"><code>src</code></dfn> and <dfn id="dom-embed-type" title="dom-embed-type"><code>type</code></dfn> each must
1278: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1279: name.</p>
1280:
1281: </div><div class="example">
1282:
1283: <p>Here's a way to embed a resource that requires a proprietary
1.69 mike 1284: plugin, like Flash:</p>
1.1 mike 1285:
1286: <pre><embed src="catgame.swf"></pre>
1287:
1.69 mike 1288: <p>If the user does not have the plugin (for example if the
1289: plugin vendor doesn't support the user's platform), then the user
1.1 mike 1290: will be unable to use the resource.</p>
1291:
1292: <p>To pass the plugin a parameter "quality" with the value "high",
1293: an attribute can be specified:</p>
1294:
1295: <pre><embed src="catgame.swf" quality="high"></pre>
1296:
1297: <p>This would be equivalent to the following, when using an
1298: <code><a href="#the-object-element">object</a></code> element instead:</p>
1299:
1300: <pre><object data="catgame.swf">
1301: <param name="quality" value="high">
1302: </object></pre>
1303:
1.15 mike 1304: </div><h4 id="the-object-element"><span class="secno">4.8.4 </span>The <dfn><code>object</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
1.1 mike 1305: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1306: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1307: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1.46 mike 1308: <dd>If the element has a <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute: <a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.1 mike 1309: <dd><a href="forms.html#category-listed" title="category-listed">Listed</a>, <a href="forms.html#category-submit" title="category-submit">submittable</a>, <a href="forms.html#form-associated-element">form-associated element</a>.</dd>
1.126 mike 1310: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.16 mike 1311: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1312: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1313: <dt>Content model:</dt>
1314: <dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
1315: <dt>Content attributes:</dt>
1316: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1317: <dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
1318: <dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
1.69 mike 1319: <dd><code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code></dd>
1.1 mike 1320: <dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
1321: <dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
1322: <dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
1323: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1324: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1325: <dt>DOM interface:</dt>
1326: <dd>
1327: <pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1328: attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
1329: attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
1.69 mike 1330: attribute boolean <a href="#dom-object-typemustmatch" title="dom-object-typeMustMatch">typeMustMatch</a>;
1.1 mike 1331: attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
1332: attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
1.68 mike 1333: readonly attribute <a href="forms.html#htmlformelement">HTMLFormElement</a>? <a href="association-of-controls-and-forms.html#dom-fae-form" title="dom-fae-form">form</a>;
1.1 mike 1334: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1335: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1.68 mike 1336: readonly attribute Document? <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
1337: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a>? <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
1.1 mike 1338:
1339: readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
1340: readonly attribute <a href="association-of-controls-and-forms.html#validitystate">ValidityState</a> <a href="association-of-controls-and-forms.html#dom-cva-validity" title="dom-cva-validity">validity</a>;
1341: readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
1342: boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
1.101 mike 1343: void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(DOMString error);
1.1 mike 1344: };</pre>
1345: <div class="impl">
1346: <p>Depending on the type of content instantiated by the
1347: <code><a href="#the-object-element">object</a></code> element, the node also supports other
1348: interfaces.</p>
1349: </div>
1350: </dd>
1351: </dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
1352: resource, which, depending on the type of the resource, will either
1353: be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1354: or as an external resource to be processed by a
1355: <a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
1356: attribute, if present, specifies the address of the resource. If
1357: present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.69 mike 1358: URL potentially surrounded by spaces</a>.</p><p class="warning">Authors who reference resources from other <a href="origin-0.html#origin" title="origin">origins</a> that they do not trust are urged to
1359: use the <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1360: attribute defined below. Without that attribute, it is possible in
1361: certain cases for an attacker on the remote host to use the plugin
1362: mechanism to run arbitrary scripts, even if the author has used
1363: features such as the Flash "allowScriptAccess" parameter.</p><p>The <dfn id="attr-object-type" title="attr-object-type"><code>type</code></dfn>
1.1 mike 1364: attribute, if present, specifies the type of the resource. If
1.69 mike 1365: present, the attribute must be a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>.</p><p>At least one of either the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute or the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute must be present.</p><p>The <dfn id="attr-object-typemustmatch" title="attr-object-typemustmatch"><code>typemustmatch</code></dfn>
1.88 mike 1366: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> whose presence
1.69 mike 1367: indicates that the resource specified by the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is only to be used if
1368: the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1369: attribute and the <a href="fetching-resources.html#content-type">Content-Type</a> of the aforementioned
1370: resource match.</p><p>The <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1371: attribute must not be specified unless both the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute and the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute are present.</p><p>The <dfn id="attr-object-name" title="attr-object-name"><code>name</code></dfn>
1.1 mike 1372: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
1373: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
1374: browsing context</a>, if applicable.</p><div class="impl">
1375:
1376: <p>When the element is created, when it is popped off the
1.101 mike 1377: <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
1378: or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
1.1 mike 1379: <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
1380: document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
1381: document">removed from a document</a>; and whenever the element's
1382: <code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
1383: active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
1384: changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
1.101 mike 1385: whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
1386: changed, or removed; and, when its <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is not present,
1.1 mike 1387: whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
1.101 mike 1388: set, changed, or removed; and, when neither its <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute nor its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute are present, whenever
1.1 mike 1389: its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
1390: changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
1391: to run the following steps to (re)determine what the
1392: <code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
1393: for this <a href="webappapis.html#concept-task" title="concept-task">task</a> is the <a href="webappapis.html#dom-manipulation-task-source">DOM
1.46 mike 1394: manipulation task source</a>.</p>
1.1 mike 1395: <ol><li>
1396:
1397: <p>If the user has indicated a preference that this
1398: <code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
1399: shown instead of the element's usual behavior, then jump to the
1400: last step in the overall set of steps (fallback).</p>
1401:
1402: <p class="note">For example, a user could ask for the element's
1403: <a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
1404: uses a format that the user finds more accessible.</p>
1405:
1406: </li>
1407:
1408: <li>
1409:
1.47 mike 1410: <p>If the element has an ancestor <a href="#media-element">media element</a>, or
1.1 mike 1411: has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
1412: showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
1413: not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
1414: with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
1415: <code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
1.101 mike 1416: element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
1417: <a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
1.1 mike 1418: the last step in the overall set of steps (fallback).</p>
1419:
1420: </li>
1421:
1422: <li>
1423:
1.46 mike 1424:
1.101 mike 1425: <p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
1.1 mike 1426: attribute is present, and has a value that isn't the empty string,
1427: then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
1.114 mike 1428: according to the value of the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute, and either
1429: <a href="#sandboxPluginObject">plugins aren't being sandboxed</a>
1430: or that <a href="infrastructure.html#plugin">plugin</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>, then that
1431: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>,
1432: and the value of the <code title="attr-object-data"><a href="#attr-object-data">data</a></code>
1433: attribute, if any, should be passed to the <a href="infrastructure.html#plugin">plugin</a>. If
1434: no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
1435: <a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the last step in the
1436: overall set of steps (fallback).</p>
1.1 mike 1437:
1.46 mike 1438:
1.1 mike 1439: </li>
1440:
1.46 mike 1441:
1.1 mike 1442: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1443: is present and its value is not the empty string, then:</p>
1444:
1445: <ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1446: attribute is present and its value is not a type that the user
1447: agent supports, and is not a type that the user agent can find a
1448: <a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
1449: step in the overall set of steps (fallback) without fetching the
1450: content to examine its real type.</p></li>
1451:
1452: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
1453: <a href="urls.html#url">URL</a> specified by the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute, relative to the
1454: element.</p></li>
1455:
1456: <li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1457: <code title="event-error">error</code> at the element, then jump
1458: to the last step in the overall set of steps (fallback).</p></li>
1459:
1460: <li>
1461:
1462: <p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
1463: from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
1.46 mike 1464: it has one.</p>
1.1 mike 1465:
1.46 mike 1466: <p>Fetching the resource
1.101 mike 1467: must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
1.1 mike 1468: until the <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task
1469: source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
1470:
1.41 mike 1471: <p>For the purposes of the <a href="offline.html#application-cache">application cache</a>
1472: networking model, this <a href="fetching-resources.html#fetch">fetch</a> operation is not for a
1473: <a href="browsers.html#child-browsing-context">child browsing context</a> (though it might end up
1474: being used for one after all, as defined below).</p>
1475:
1.1 mike 1476: </li>
1477:
1478: <li><p>If the resource is not yet available (e.g. because the
1479: resource was not available in the cache, so that loading the
1480: resource required making a request over the network), then jump
1481: to the last step in the overall set of steps (fallback). The
1482: <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue
1483: a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task source</a>
1484: once the resource is available must restart this algorithm from
1485: this step. Resources can load incrementally; user agents may opt
1486: to consider a resource "available" whenever enough data has been
1487: obtained to begin processing the resource.</p></li>
1488:
1489: <li><p>If the load failed (e.g. there was an HTTP 404 error,
1490: there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1491: <code title="event-error">error</code> at the element, then jump
1492: to the last step in the overall set of steps (fallback).</p></li>
1493:
1494: <li id="object-type-detection">
1495:
1496: <p>Determine the <var title="">resource type</var>, as follows:</p>
1497:
1498:
1499: <ol><li>
1500:
1501: <p>Let the <var title="">resource type</var> be unknown.</p>
1502:
1503: </li>
1504:
1505: <li>
1506:
1.69 mike 1507: <p>If the <code><a href="#the-object-element">object</a></code> element has a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute and a <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1508: attribute, and the resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type metadata</a>,
1509: and the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1510: resource's Content-Type metadata</a> is an <a href="infrastructure.html#ascii-case-insensitive">ASCII
1511: case-insensitive</a> match for the value of the element's
1512: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, then let
1513: <var title="">resource type</var> be that type and jump to the
1514: step below labeled <i>handler</i>.</p>
1515:
1516:
1517: </li>
1518:
1519: <li>
1520:
1521: <p>If the <code><a href="#the-object-element">object</a></code> element has a <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1522: attribute, jump to the step below labeled <i>handler</i>.</p>
1523:
1524: </li>
1525:
1526: <li>
1527:
1.46 mike 1528:
1.1 mike 1529:
1530: <p>If the user agent is configured to strictly obey
1531: Content-Type headers for this resource, and the resource has
1532: <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1533: metadata</a>, then let the <var title="">resource
1534: type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1535: metadata</a>, and jump to the step below labeled
1536: <i>handler</i>.</p>
1537:
1.69 mike 1538: <p class="warning">This can introduce a vulnerability, wherein
1539: a site is trying to embed a resource that uses a particular
1540: plugin, but the remote site overrides that and instead
1541: furnishes the user agent with a resource that triggers a
1542: different plugin with different security characteristics. </p>
1543:
1.1 mike 1544: </li>
1545:
1546: <li>
1547:
1548: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1549: attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
1550: attribute's value is not a type that the user agent supports,
1551: but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
1552: then let the <var title="">resource type</var> be the type
1553: specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1554: attribute, and jump to the step below labeled
1555: <i>handler</i>.</p>
1556:
1557: </li>
1558:
1559: <li>
1560:
1561: <p>Run the approprate set of steps from the following
1562: list:</p>
1563:
1564: <dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
1565: Content-Type metadata</a></dt>
1566:
1567: <dd>
1568:
1569: <ol><li>
1570:
1571: <p>Let <var title="">binary</var> be false.</p>
1572:
1573: </li>
1574:
1575: <li>
1576:
1577: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1578: resource's Content-Type metadata</a> is
1579: "<code>text/plain</code>", and the result of applying the
1580: <a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
1.49 mike 1581: for distinguishing if a resource is text or binary</a>
1.1 mike 1582: to the resource is that the resource is not
1583: <code>text/plain</code>, then set <var title="">binary</var> to true.</p>
1584:
1585: </li>
1586:
1587: <li>
1588:
1589: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1590: resource's Content-Type metadata</a> is
1591: "<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
1592:
1593: </li>
1594:
1595: <li>
1596:
1597: <p>If <var title="">binary</var> is false, then let the
1598: <var title="">resource type</var> be the type specified in
1599: <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1600: metadata</a>, and jump to the step below labeled
1601: <i>handler</i>.</p>
1602:
1603: </li>
1604:
1605: <li>
1606:
1607: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1608: the <code><a href="#the-object-element">object</a></code> element, and its value is not
1609: <code>application/octet-stream</code>, then run the
1610: following steps:</p>
1611:
1612: <ol><li>
1613:
1614: <p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
1615: the attribute's value is a type that starts with "<code>image/</code>" that is not also an <a href="infrastructure.html#xml-mime-type">XML MIME type</a>,
1616: then let the <var title="">resource type</var> be the type specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1617:
1618: </li>
1619:
1620: <li>
1621:
1622: <p>Jump to the step below labeled <i>handler</i>.</p>
1623:
1624: </li>
1625:
1626: </ol></li>
1627:
1628: </ol></dd>
1629:
1630: <dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1631: metadata</a></dt>
1632:
1633: <dd>
1634:
1635: <ol><li>
1636:
1637: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1638: the <code><a href="#the-object-element">object</a></code> element, then let the <var title="">tentative type</var> be the type specified in that
1639: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1640:
1641: <p>Otherwise, let <var title="">tentative type</var> be the
1642: <a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
1643: resource</a>.</p>
1644:
1645: </li>
1646:
1647: <li>
1648:
1649: <p>If <var title="">tentative type</var> is <em>not</em>
1650: <code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
1651: type</var> and jump to the step below labeled
1652: <i>handler</i>.</p>
1653:
1654: </li>
1655:
1656: </ol></dd>
1657:
1658: </dl></li>
1659:
1660: <li>
1661:
1.46 mike 1662:
1.1 mike 1663: <p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
1664: of the <a href="urls.html#url">URL</a> of the specified resource (after any
1665: redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1666: supports, then let <var title="">resource type</var> be the
1667: type that that plugin can handle.</p>
1668:
1669: <p class="example">For example, a plugin might say that it can
1670: handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
1671: the four character string "<code title="">.swf</code>".</p>
1672:
1.46 mike 1673:
1674:
1.1 mike 1675:
1676: </li>
1677:
1.69 mike 1678: </ol><p class="note">It is possible for this step to finish, or for
1679: one of the substeps above to jump straight to the next step,
1680: with <var title="">resource type</var> still being unknown. In
1681: both cases, the next step will trigger fallback.</p>
1.1 mike 1682:
1683: </li>
1684:
1685: <li><p><i>Handler</i>: Handle the content as given by the first
1686: of the following cases that matches:</p>
1687:
1688: <dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
1689: the user agent supports, but it <em>is</em> a type that a
1690: <a href="infrastructure.html#plugin">plugin</a> supports</dt>
1691:
1692: <dd>
1693:
1694: <p>If <a href="#sandboxPluginObject">plugins are being
1.114 mike 1695: sandboxed</a> and the plugin that supports <var title="">resource type</var> cannot be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>, jump to the last
1696: step in the overall set of steps (fallback).</p>
1.1 mike 1697:
1698: <p>Otherwise, the user agent should <a href="#object-plugin">use the plugin that supports <var title="">resource type</var></a> and pass the content of the
1699: resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
1700: <a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
1701: step in the overall set of steps (fallback).</p>
1702:
1703: </dd>
1704:
1705:
1706: <dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
1707: type</a>, or
1.46 mike 1708:
1.1 mike 1709: if the <var title="">resource type</var> does not start with
1710: "<code>image/</code>"</dt>
1711:
1712: <dd>
1713:
1714: <p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
1715: newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
1716: not already have one.</p>
1717:
1718: <p>If the <a href="urls.html#url">URL</a> of the given resource is not
1719: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, the element's <a href="browsers.html#nested-browsing-context">nested browsing
1.46 mike 1720: context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that
1.34 mike 1721: resource, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
1.1 mike 1722: <code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
1.34 mike 1723: context</a> as the <a href="history.html#source-browsing-context">source browsing context</a>.
1724: (The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of
1725: the <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
1.1 mike 1726: browsing context gets further navigated to other
1727: locations.)</p>
1728:
1729: <p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
1730: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, the user agent must
1731: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
1732: named <code title="event-load">load</code> at the
1.66 mike 1733: <code><a href="#the-object-element">object</a></code> element. <span class="note">No <code title="event-load">load</code> event is fired at the
1734: <code><a href="fetching-resources.html#about:blank">about:blank</a></code> document itself.</span></p>
1.1 mike 1735:
1.101 mike 1736: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1.1 mike 1737: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1738:
1739: <p>If the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1740: is present, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1741: to the value of this attribute; otherwise, the <a href="browsers.html#browsing-context-name">browsing
1742: context name</a> must be set to the empty string.</p>
1743:
1.41 mike 1744: <p class="note">In certain situations, e.g. if the resource
1745: was <a href="fetching-resources.html#fetch" title="fetch">fetched</a> from an
1746: <a href="offline.html#application-cache">application cache</a> but it is an HTML file with a
1747: <code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> attribute
1748: that points to a different <a href="offline.html#concept-appcache-manifest" title="concept-appcache-manifest">application cache
1749: manifest</a>, the <a href="history.html#navigate" title="navigate">navigation</a>
1750: of the <a href="browsers.html#browsing-context">browsing context</a> will be restarted so as
1751: to load the resource afresh from the network or a different
1752: <a href="offline.html#application-cache">application cache</a>. Even if the resource is then
1753: found to have a different type, it is still used as part of a
1754: <a href="browsers.html#nested-browsing-context">nested browsing context</a>: only the
1755: <a href="history.html#navigate">navigate</a> algorithm is restarted, not this
1756: <code><a href="#the-object-element">object</a></code> algorithm.</p>
1.1 mike 1757:
1.46 mike 1758:
1.1 mike 1759:
1760: </dd>
1761:
1762:
1763: <dt>If the <var title="">resource type</var> starts with
1764: "<code>image/</code>", and support for images has not been
1765: disabled</dt>
1766:
1767: <dd>
1768:
1769: <p>Apply the <a href="fetching-resources.html#content-type-sniffing:-image" title="content-type sniffing: image">image
1770: sniffing</a> rules to determine the type of the image.</p>
1771:
1.101 mike 1772: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1.1 mike 1773: specified image. The image is not a <a href="browsers.html#nested-browsing-context">nested browsing
1774: context</a>.</p>
1775:
1776: <p>If the image cannot be rendered, e.g. because it is
1777: malformed or in an unsupported format, jump to the last step
1778: in the overall set of steps (fallback).</p>
1779:
1780: </dd>
1781:
1782:
1783: <dt>Otherwise</dt>
1784:
1785: <dd>
1786:
1787: <p>The given <var title="">resource type</var> is not
1788: supported. Jump to the last step in the overall set of steps
1789: (fallback).</p>
1790:
1791: <p class="note">If the previous step ended with the <var title="">resource type</var> being unknown, this is the case
1792: that is triggered.</p>
1793:
1794: </dd>
1795:
1796: </dl></li>
1797:
1798: <li><p>The element's contents are not part of what the
1799: <code><a href="#the-object-element">object</a></code> element represents.</p>
1800:
1801: </li><li>
1802:
1803: <p>Once the resource is completely loaded, <a href="webappapis.html#queue-a-task">queue a
1804: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-load">load</code> at the element.</p>
1805:
1.46 mike 1806: <p>The <a href="webappapis.html#task-source">task source</a> for this task is the <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task
1.1 mike 1807: source</a>.</p>
1808:
1809: </li>
1810:
1811: </ol></li>
1812:
1813: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1814: is absent but the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1.114 mike 1815: attribute is present, and the user agent can find a
1816: <a href="infrastructure.html#plugin">plugin</a> suitable according to the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, and either <a href="#sandboxPluginObject">plugins aren't being sandboxed</a> or
1817: the <a href="infrastructure.html#plugin">plugin</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>, then that
1.1 mike 1818: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
1.114 mike 1819: these conditions cannot be met, or if the <a href="infrastructure.html#plugin">plugin</a>
1820: reports an error, jump to the next step (fallback).</p></li>
1.1 mike 1821:
1822: <li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
1.101 mike 1823: <a href="rendering.html#represents">represents</a> the element's children, ignoring any
1.1 mike 1824: leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
1825: <a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
1826: <a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
1827:
1828: </ol><p id="object-plugin">When the algorithm above instantiates a
1829: <a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
1830: <a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
1831: on the element, in the order they were added to the element, with
1832: the attributes added by the parser being ordered in source order,
1833: followed by a parameter named "PARAM" whose value is null,
1834: followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
1835: <code><a href="#the-param-element">param</a></code> elements that are children of the
1836: <code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
1837: <a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
1838: <code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
1839: should expose that interface. The <code><a href="#the-object-element">object</a></code> element
1.101 mike 1840: <a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
1.1 mike 1841: <a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
1842: context</a>.</p>
1843:
1.114 mike 1844: <p id="sandboxPluginObject">Plugins are considered sandboxed for the
1.127 mike 1845: purpose of an <code><a href="#the-object-element">object</a></code> element if the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed
1846: plugins browsing context flag</a> was set on the
1847: <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing
1848: context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
1.1 mike 1849:
1.127 mike 1850: <p class="note">The above algorithm is independent of CSS properties
1.1 mike 1851: (including 'display', 'overflow', and 'visibility'). For example, it
1852: runs even if the element is hidden with a 'display:none' CSS style,
1853: and does not run <em>again</em> if the element's visibility
1854: changes.</p>
1855:
1856: <p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
1857: elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
1858: referenced resources can't be shown (e.g. because it returned a 404
1859: error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
1860: nested inside each other, targeting multiple user agents with
1861: different capabilities, with the user agent picking the first one it
1862: supports.</p>
1863:
1864: <p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1865: is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
1866: <a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
1867: name">name</a> must be changed to the new value. If the attribute
1868: is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
1869: context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1870: to the empty string.</p>
1871:
1872: </div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
1873: if present while the <code><a href="#the-object-element">object</a></code> element represents an
1874: image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
1875: map</a>. <span class="impl">The attribute must be ignored if the
1876: <code><a href="#the-object-element">object</a></code> element doesn't represent an image.</span></p><p>The <code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code> attribute is used to
1877: explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
1878: <a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
1879:
1880: <p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
1881: elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
1882: validation</a>.</p>
1883:
1884: </div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1885: attributes</a>.</p><div class="impl">
1886:
1.131 mike 1887: <p>The IDL attributes <dfn id="dom-object-data" title="dom-object-data"><code>data</code></dfn>, <dfn id="dom-object-type" title="dom-object-type"><code>type</code></dfn> and <dfn id="dom-object-name" title="dom-object-name"><code>name</code></dfn> each must
1.1 mike 1888: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1.131 mike 1889: name. The <dfn id="dom-object-typemustmatch" title="dom-object-typeMustMatch"><code>typeMustMatch</code></dfn>
1890: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code> content
1891: attribute. The <dfn id="dom-object-usemap" title="dom-object-useMap"><code>useMap</code></dfn> IDL attribute
1892: must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-object-usemap">usemap</code> content attribute.</p>
1.69 mike 1893:
1.1 mike 1894: <p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
1895: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1896: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
1897: <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
1898: must return null.</p>
1899:
1900: <p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
1901: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1902: <code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1903: if it has one; otherwise, it must return null.</p>
1904:
1905: <p>The <code title="dom-cva-willValidate"><a href="association-of-controls-and-forms.html#dom-cva-willvalidate">willValidate</a></code>, <code title="dom-cva-validity"><a href="association-of-controls-and-forms.html#dom-cva-validity">validity</a></code>, and <code title="dom-cva-validationMessage"><a href="association-of-controls-and-forms.html#dom-cva-validationmessage">validationMessage</a></code>
1906: attributes, and the <code title="dom-cva-checkValidatity"><a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity">checkValidity()</a></code> and <code title="dom-cva-setCustomValidity"><a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity">setCustomValidity()</a></code>
1907: methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
1908: <code title="dom-fae-form"><a href="association-of-controls-and-forms.html#dom-fae-form">form</a></code> IDL attribute is part of the
1909: element's forms API.</p>
1910:
1911: </div><div class="example">
1912:
1913: <p>In the following example, a Java applet is embedded in a page
1914: using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
1915: better to avoid using applets like these and instead use native
1916: JavaScript and HTML to provide the functionality, since that way
1917: the application will work on all Web browsers without requiring a
1918: third-party plugin. Many devices, especially embedded devices, do
1919: not support third-party technologies like Java.)</p>
1920:
1921: <pre><figure>
1922: <object type="application/x-java-applet">
1923: <param name="code" value="MyJavaClass">
1924: <p>You do not have Java available, or it is disabled.</p>
1925: </object>
1926: <figcaption>My Java Clock</figcaption>
1927: </figure></pre>
1928:
1929: </div><div class="example">
1930:
1931: <p>In this example, an HTML page is embedded in another using the
1932: <code><a href="#the-object-element">object</a></code> element.</p>
1933:
1934: <pre><figure>
1935: <object data="clock.html"></object>
1936: <figcaption>My HTML Clock</figcaption>
1937: </figure></pre>
1938:
1939: </div><div class="example">
1940:
1941: <p>The following example shows how a plugin can be used in HTML (in
1942: this case the Flash plugin, to show a video file). Fallback is
1943: provided for users who do not have Flash enabled, in this case
1.47 mike 1944: using the <code><a href="#the-video-element">video</a></code> element to show the video for those
1945: using user agents that support <code><a href="#the-video-element">video</a></code>, and finally
1.1 mike 1946: providing a link to the video for those who have neither Flash nor
1.47 mike 1947: a <code><a href="#the-video-element">video</a></code>-capable browser.</p>
1.1 mike 1948:
1949: <pre><p>Look at my video:
1950: <object type="application/x-shockwave-flash">
1951: <param name=movie value="http://video.example.com/library/watch.swf">
1952: <param name=allowfullscreen value=true>
1953: <param name=flashvars value="http://video.example.com/vids/315981">
1954: <video controls src="http://video.example.com/vids/315981">
1955: <a href="http://video.example.com/vids/315981">View video</a>.
1956: </video>
1957: </object>
1958: </p></pre>
1959:
1.15 mike 1960: </div><h4 id="the-param-element"><span class="secno">4.8.5 </span>The <dfn><code>param</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
1.1 mike 1961: <dd>None.</dd>
1.16 mike 1962: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1963: <dd>As a child of an <code><a href="#the-object-element">object</a></code> element, before any <a href="content-models.html#flow-content">flow content</a>.</dd>
1964: <dt>Content model:</dt>
1965: <dd>Empty.</dd>
1966: <dt>Content attributes:</dt>
1967: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1968: <dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
1969: <dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
1970: <dt>DOM interface:</dt>
1971: <dd>
1972: <pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1973: attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
1974: attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
1975: };</pre>
1976: </dd>
1977: </dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
1.101 mike 1978: invoked by <code><a href="#the-object-element">object</a></code> elements. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-param-name" title="attr-param-name"><code>name</code></dfn>
1.1 mike 1979: attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
1980: attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
1981:
1982: <p>If both attributes are present, and if the parent element of the
1983: <code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
1984: element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
1.94 mike 1985: name-value pair.</p>
1.1 mike 1986:
1.23 mike 1987: <p>If either the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> defined by a
1988: <code><a href="#the-param-element">param</a></code> element that is the child of an
1.101 mike 1989: <code><a href="#the-object-element">object</a></code> element that <a href="rendering.html#represents">represents</a> an
1.23 mike 1990: instantiated <a href="infrastructure.html#plugin">plugin</a> changes, and if that
1991: <a href="infrastructure.html#plugin">plugin</a> is communicating with the user agent using an
1992: API that features the ability to update the <a href="infrastructure.html#plugin">plugin</a> when
1993: the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> so changes, then
1994: the user agent must appropriately exercise that ability to notify
1995: the <a href="infrastructure.html#plugin">plugin</a> of the change.</p>
1996:
1.1 mike 1997: <p>The IDL attributes <dfn id="dom-param-name" title="dom-param-name"><code>name</code></dfn> and <dfn id="dom-param-value" title="dom-param-value"><code>value</code></dfn> must both
1998: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1999: name.</p>
2000:
2001: </div><div class="example">
2002:
2003: <p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
2004: can be used to pass a parameter to a plugin, in this case the O3D
2005: plugin.</p>
2006:
2007: <pre><!DOCTYPE HTML>
2008: <html lang="en">
1.6 mike 2009: <head>
2010: <title>O3D Utah Teapot</title>
2011: </head>
2012: <body>
2013: <p>
2014: <object type="application/vnd.o3d.auto">
2015: <strong><param name="o3d_features" value="FloatingPointTextures"></strong>
2016: <img src="o3d-teapot.png"
2017: title="3D Utah Teapot illustration rendered using O3D."
2018: alt="When O3D renders the Utah Teapot, it appears as a squat
2019: teapot with a shiny metallic finish on which the
2020: surroundings are reflected, with a faint shadow caused by
2021: the lighting.">
2022: <p>To see the teapot actually rendered by O3D on your
2023: computer, please download and install the <a
2024: href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
2025: </object>
2026: <script src="o3d-teapot.js"></script>
2027: </p>
2028: </body>
1.1 mike 2029: </html></pre>
2030:
1.47 mike 2031: </div><h4 id="the-video-element"><span class="secno">4.8.6 </span>The <dfn id="video"><code>video</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
2032: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2033: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2034: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2035: <dd>If the element has a <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute: <a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 2036: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.47 mike 2037: <dt>Contexts in which this element can be used:</dt>
2038: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2039: <dt>Content model:</dt>
2040: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2041: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2042: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2043: <dd>If the element does not have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute: zero or more <code><a href="#the-source-element">source</a></code> elements, then
2044: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2045: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2046: <dt>Content attributes:</dt>
2047: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2048: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2049: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2050: <dd><code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code></dd>
2051: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2052: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2053: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2054: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2055: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2056: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2057: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
2058: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
2059: <dt>DOM interface:</dt>
2060: <dd>
2061: <pre class="idl">interface <dfn id="htmlvideoelement">HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {
2062: attribute unsigned long <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
2063: attribute unsigned long <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
2064: readonly attribute unsigned long <a href="#dom-video-videowidth" title="dom-video-videoWidth">videoWidth</a>;
2065: readonly attribute unsigned long <a href="#dom-video-videoheight" title="dom-video-videoHeight">videoHeight</a>;
2066: attribute DOMString <a href="#dom-video-poster" title="dom-video-poster">poster</a>;
2067: };</pre>
2068: </dd>
2069: </dl><p>A <code><a href="#the-video-element">video</a></code> element is used for playing videos or
2070: movies, and audio files with captions.</p><p>Content may be provided inside the <code><a href="#the-video-element">video</a></code>
2071: element<span class="impl">. User agents should not show this content
2072: to the user</span>; it is intended for older Web browsers which do
2073: not support <code><a href="#the-video-element">video</a></code>, so that legacy video plugins can be
2074: tried, or to show text to the users of these older browsers informing
2075: them of how to access the video contents.</p><p class="note">In particular, this content is not intended to
2076: address accessibility concerns. To make video content accessible to
2077: the blind, deaf, and those with other physical or cognitive
1.90 mike 2078: disabilities, a variety of features are available. Captions can be
2079: provided, either embedded in the video stream or as external files
2080: using the <code><a href="#the-track-element">track</a></code> element. Sign-language tracks can be
2081: provided, again either embedded in the video stream or by
2082: synchronizing multiple <code><a href="#the-video-element">video</a></code> elements using the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute or a
2083: <code><a href="#mediacontroller">MediaController</a></code> object. Audio descriptions can be
2084: provided, either as a separate track embedded in the video stream,
2085: or a separate audio track in an <code><a href="#the-audio-element">audio</a></code> element <a href="#slaved-media-elements" title="slaved media elements">slaved</a> to the same controller
2086: as the <code><a href="#the-video-element">video</a></code> element(s), or in text form using a
2087: <span>WebVTT file</span> referenced using the <code><a href="#the-track-element">track</a></code>
2088: element and synthesized into speech by the user agent. WebVTT can
2089: also be used to provide chapter titles. For users who would rather
2090: not use a media element at all, transcripts or other textual
2091: alternatives can be provided by simply linking to them in the prose
2092: near the <code><a href="#the-video-element">video</a></code> element.</p><p>The <code><a href="#the-video-element">video</a></code> element is a <a href="#media-element">media element</a>
1.47 mike 2093: whose <a href="#media-data">media data</a> is ostensibly video data, possibly
2094: with associated audio data.</p><p>The <code title="attr-media-src"><a href="#attr-media-src">src</a></code>, <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
2095: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2096: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2097: <code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code>, and <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attributes are <a href="#media-element-attributes" title="media element attributes">the attributes common to all media
2098: elements</a>.</p><p>The <dfn id="attr-video-poster" title="attr-video-poster"><code>poster</code></dfn>
2099: attribute gives the address of an image file that the user agent can
2100: show while no video data is available. The attribute, if present,
2101: must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2102: spaces</a>.</p><div class="impl">
2103:
2104: <p>If the specified resource is to be used, then, when the element
2105: is created or when the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
2106: attribute is set, changed, or removed, the user agent must run the
2107: following steps to determine the element's <dfn id="poster-frame">poster
2108: frame</dfn>:</p>
2109: <ol><li><p>If there is an existing instance of this algorithm running
2110: for this <code><a href="#the-video-element">video</a></code> element, abort that instance of this
2111: algorithm without changing the <a href="#poster-frame">poster frame</a>.</p></li>
2112:
2113: <li><p>If the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
1.51 mike 2114: attribute's value is the empty string or if the attribute is
2115: absent, then there is no <a href="#poster-frame">poster frame</a>; abort these
2116: steps.</p></li>
1.47 mike 2117:
2118: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code> attribute's value relative
2119: to the element. If this fails, then there is no <a href="#poster-frame">poster
2120: frame</a>; abort these steps.</p></li>
2121:
2122: <li><p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
2123: from the element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>.
1.101 mike 2124: This must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's
1.47 mike 2125: document.</p></li>
2126:
2127:
2128:
2129: <li><p>If an image is thus obtained, the <a href="#poster-frame">poster frame</a>
2130: is that image. Otherwise, there is no <a href="#poster-frame">poster
2131: frame</a>.</p></li>
2132:
2133: </ol></div><p class="note">The image given by the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code> attribute, the <i><a href="#poster-frame">poster
2134: frame</a></i>, is intended to be a representative frame of the video
2135: (typically one of the first non-blank frames) that gives the user an
2136: idea of what the video is like.</p><div class="impl">
2137:
2138: <hr><p>When no video data is available (the element's <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is either
2139: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, or <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> but no video
2140: data has yet been obtained at all, or the element's <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is any
2141: subsequent value but the <a href="#media-resource">media resource</a> does not have a
2142: video channel), the <code><a href="#the-video-element">video</a></code> element
1.101 mike 2143: <a href="rendering.html#represents">represents</a> the <a href="#poster-frame">poster frame</a>.</p>
1.47 mike 2144:
2145: <p>When a <code><a href="#the-video-element">video</a></code> element is <a href="#dom-media-paused" title="dom-media-paused">paused</a> and the <a href="#current-playback-position" title="current
2146: playback position">current playback position</a> is the first
1.101 mike 2147: frame of video, the element <a href="rendering.html#represents">represents</a> the <a href="#poster-frame">poster
1.94 mike 2148: frame</a>, unless a frame of video has already been shown, in
1.101 mike 2149: which case the element <a href="rendering.html#represents">represents</a> the frame of video
1.94 mike 2150: corresponding to the <a href="#current-playback-position" title="current playback position">current
2151: playback position</a>.</p>
1.47 mike 2152:
2153: <p>When a <code><a href="#the-video-element">video</a></code> element is <a href="#dom-media-paused" title="dom-media-paused">paused</a> at any other position, and
2154: the <a href="#media-resource">media resource</a> has a video channel, the element
1.101 mike 2155: <a href="rendering.html#represents">represents</a> the frame of video corresponding to the
1.47 mike 2156: <a href="#current-playback-position" title="current playback position">current playback
2157: position</a>, or, if that is not yet available (e.g. because the
2158: video is seeking or buffering), the last frame of the video to have
2159: been rendered.</p>
2160:
2161: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2162: resource</a> has a video channel is <a href="#potentially-playing">potentially
1.101 mike 2163: playing</a>, it <a href="rendering.html#represents">represents</a> the frame of video at the
1.47 mike 2164: continuously increasing <a href="#current-playback-position" title="current playback
2165: position">"current" position</a>. When the <a href="#current-playback-position">current playback
2166: position</a> changes such that the last frame rendered is no
2167: longer the frame corresponding to the <a href="#current-playback-position">current playback
2168: position</a> in the video, the new frame must be rendered.
2169:
2170: Similarly, any audio associated with the <a href="#media-resource">media resource</a>
2171: must, if played, be played synchronized with the <a href="#current-playback-position">current
2172: playback position</a>, at the element's <a href="#effective-media-volume">effective media
2173: volume</a>.</p>
2174:
2175: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2176: resource</a> has a video channel is neither <a href="#potentially-playing">potentially
2177: playing</a> nor <a href="#dom-media-paused" title="dom-media-paused">paused</a>
1.101 mike 2178: (e.g. when seeking or stalled), the element <a href="rendering.html#represents">represents</a>
1.47 mike 2179: the last frame of the video to have been rendered.</p>
2180:
2181: <p class="note">Which frame in a video stream corresponds to a
2182: particular playback position is defined by the video stream's
2183: format.</p>
2184:
1.101 mike 2185: <p>The <code><a href="#the-video-element">video</a></code> element also <a href="rendering.html#represents">represents</a> any
1.47 mike 2186: <a href="#text-track-cue" title="text track cue">text track cues</a> whose
2187: <a href="#text-track-cue-active-flag">text track cue active flag</a> is set and whose
2188: <a href="#text-track">text track</a> is in the <a href="#text-track-showing" title="text track
2189: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track showing by
2190: default">showing by default</a> modes.</p>
2191:
2192: <p>In addition to the above, the user agent may provide messages to
2193: the user (such as "buffering", "no video loaded", "error", or more
2194: detailed information) by overlaying text or icons on the video or
2195: other areas of the element's playback area, or in another
2196: appropriate manner.</p>
2197:
2198: <p>User agents that cannot render the video may instead make the
1.101 mike 2199: element <a href="rendering.html#represents" title="represents">represent</a> a link to an
1.47 mike 2200: external video playback utility or to the video data itself.</p>
2201:
1.105 mike 2202: <p>When a <code><a href="#the-video-element">video</a></code> element's <a href="#media-resource">media resource</a>
2203: has a video channel, the element <a href="infrastructure.html#provides-a-paint-source">provides a paint
2204: source</a> whose width is the <a href="#media-resource">media resource</a>'s <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a>, whose
2205: height is the <a href="#media-resource">media resource</a>'s <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a>, and
2206: whose appearance is the frame of video corresponding to the <a href="#current-playback-position" title="current playback position">current playback position</a>,
2207: if that is available, or else (e.g. when the video is seeking or
2208: buffering) its previous appearance, if any, or else (e.g. because
2209: the video is still loading the first frame) blackness.</p>
2210:
1.47 mike 2211: <hr></div><dl class="domintro"><dt><var title="">video</var> . <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code></dt>
2212: <dt><var title="">video</var> . <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code></dt>
2213:
2214: <dd>
2215:
2216: <p>These attributes return the intrinsic dimensions of the video,
2217: or zero if the dimensions are not known.</p>
2218:
2219: </dd>
2220:
2221: </dl><div class="impl">
2222:
2223: <p>The <dfn id="concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2224: width</dfn> and <dfn id="concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</dfn> of the
2225: <a href="#media-resource">media resource</a> are the dimensions of the resource in
2226: CSS pixels after taking into account the resource's dimensions,
2227: aspect ratio, clean aperture, resolution, and so forth, as defined
2228: for the format used by the resource. If an anamorphic format does
2229: not define how to apply the aspect ratio to the video data's
2230: dimensions to obtain the "correct" dimensions, then the user agent
2231: must apply the ratio by increasing one dimension and leaving the
2232: other unchanged.</p>
2233:
2234: <p>The <dfn id="dom-video-videowidth" title="dom-video-videoWidth"><code>videoWidth</code></dfn> IDL
2235: attribute must return the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> of the
2236: video in CSS pixels. The <dfn id="dom-video-videoheight" title="dom-video-videoHeight"><code>videoHeight</code></dfn> IDL
2237: attribute must return the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> of
2238: the video in CSS pixels. If the element's <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then the
2239: attributes must return 0.</p>
2240:
2241: </div><p>The <code><a href="#the-video-element">video</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
2242: attributes</a>.</p><div class="impl">
2243:
2244: <p>In the absence of style rules to the contrary, video content
2245: should be rendered inside the element's playback area such that the
2246: video content is shown centered in the playback area at the largest
2247: possible size that fits completely within it, with the video
2248: content's aspect ratio being preserved. Thus, if the aspect ratio of
2249: the playback area does not match the aspect ratio of the video, the
2250: video will be shown letterboxed or pillarboxed. Areas of the
2251: element's playback area that do not contain the video represent
2252: nothing.</p>
2253:
2254: <p class="note">In user agents that implement CSS, the above
1.101 mike 2255: requirement can be implemented by using the <a href="rendering.html#video-object-fit">style rule suggested in the rendering
1.47 mike 2256: section</a>.</p>
2257:
2258: <p>The intrinsic width of a <code><a href="#the-video-element">video</a></code> element's playback
2259: area is the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2260: width</a> of the video resource, if that is available; otherwise
2261: it is the intrinsic width of the <a href="#poster-frame">poster frame</a>, if that
2262: is available; otherwise it is 300 CSS pixels.</p>
2263:
2264: <p>The intrinsic height of a <code><a href="#the-video-element">video</a></code> element's playback
2265: area is the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic
2266: height</a> of the video resource, if that is available; otherwise
2267: it is the intrinsic height of the <a href="#poster-frame">poster frame</a>, if that
2268: is available; otherwise it is 150 CSS pixels.</p>
2269:
2270: <hr><p>User agents should provide controls to enable or disable the
2271: display of closed captions, audio description tracks, and other
2272: additional data associated with the video stream, though such
2273: features should, again, not interfere with the page's normal
2274: rendering.</p>
2275:
2276: <p>User agents may allow users to view the video content in manners
2277: more suitable to the user (e.g. full-screen or in an independent
2278: resizable window). As for the other user interface features,
2279: controls to enable this should not interfere with the page's normal
2280: rendering unless the user agent is <a href="#expose-a-user-interface-to-the-user" title="expose a user
2281: interface to the user">exposing a user interface</a>. In such an
2282: independent context, however, user agents may make full user
2283: interfaces visible, with, e.g., play, pause, seeking, and volume
2284: controls, even if the <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute is absent.</p>
2285:
2286: <p>User agents may allow video playback to affect system features
2287: that could interfere with the user's experience; for example, user
2288: agents could disable screensavers while video playback is in
2289: progress.</p>
2290:
2291: <hr><p>The <dfn id="dom-video-poster" title="dom-video-poster"><code>poster</code></dfn> IDL
2292: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code> content attribute.</p>
2293:
2294: </div><div class="example">
2295:
2296: <p>This example shows how to detect when a video has failed to play
2297: correctly:</p>
2298:
2299: <pre><script>
2300: function failed(e) {
2301: // video playback failed - show a message saying why
2302: switch (e.target.error.code) {
2303: case e.target.error.MEDIA_ERR_ABORTED:
2304: alert('You aborted the video playback.');
2305: break;
2306: case e.target.error.MEDIA_ERR_NETWORK:
2307: alert('A network error caused the video download to fail part-way.');
2308: break;
2309: case e.target.error.MEDIA_ERR_DECODE:
2310: alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
2311: break;
2312: case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
2313: alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
2314: break;
2315: default:
2316: alert('An unknown error occurred.');
2317: break;
2318: }
2319: }
2320: </script>
2321: <p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
2322: <p><a href="tgif.vid">Download the video file</a>.</p></pre>
2323:
2324: </div><h4 id="the-audio-element"><span class="secno">4.8.7 </span>The <dfn id="audio"><code>audio</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
2325: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2326: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2327: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2328: <dd>If the element has a <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute: <a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 2329: <dd>If the element has a <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute: <a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.47 mike 2330: <dt>Contexts in which this element can be used:</dt>
2331: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2332: <dt>Content model:</dt>
2333: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2334: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2335: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
1.103 mike 2336: <dd>If the element does not have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute: zero or more <code><a href="#the-source-element">source</a></code> elements, then
1.47 mike 2337: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2338: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2339: <dt>Content attributes:</dt>
2340: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2341: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2342: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2343: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2344: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2345: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2346: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2347: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2348: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2349: <dt>DOM interface:</dt>
2350: <dd>
2351: <pre class="idl">[NamedConstructor=<a href="#dom-audio" title="dom-Audio">Audio</a>(),
1.101 mike 2352: NamedConstructor=<a href="#dom-audio-s" title="dom-Audio-s">Audio</a>(DOMString src)]
1.47 mike 2353: interface <dfn id="htmlaudioelement">HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {};</pre>
2354: </dd>
1.101 mike 2355: </dl><p>An <code><a href="#the-audio-element">audio</a></code> element <a href="rendering.html#represents">represents</a> a sound or
1.47 mike 2356: audio stream.</p><p>Content may be provided inside the <code><a href="#the-audio-element">audio</a></code>
2357: element<span class="impl">. User agents should not show this content
2358: to the user</span>; it is intended for older Web browsers which do
2359: not support <code><a href="#the-audio-element">audio</a></code>, so that legacy audio plugins can be
2360: tried, or to show text to the users of these older browsers informing
2361: them of how to access the audio contents.</p><p class="note">In particular, this content is not intended to
2362: address accessibility concerns. To make audio content accessible to
2363: the deaf or to those with other physical or cognitive disabilities,
1.90 mike 2364: a variety of features are available. If captions or a sign language
2365: video are available, the <code><a href="#the-video-element">video</a></code> element can be used
2366: instead of the <code><a href="#the-audio-element">audio</a></code> element to play the audio,
2367: allowing users to enable the visual alternatives. Chapter titles can
2368: be provided to aid navigation, using the <code><a href="#the-track-element">track</a></code> element
2369: and a WebVTT file. And, naturally, transcripts or other textual
2370: alternatives can be provided by simply linking to them in the prose
2371: near the <code><a href="#the-audio-element">audio</a></code> element.</p><p>The <code><a href="#the-audio-element">audio</a></code> element is a <a href="#media-element">media element</a>
1.47 mike 2372: whose <a href="#media-data">media data</a> is ostensibly audio data.</p><p>The <code title="attr-media-src"><a href="#attr-media-src">src</a></code>, <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
2373: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2374: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2375: <code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code>, and <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attributes are <a href="#media-element-attributes" title="media element attributes">the attributes common to all media
2376: elements</a>.</p><div class="impl">
2377:
2378: <p>When an <code><a href="#the-audio-element">audio</a></code> element is <a href="#potentially-playing">potentially
2379: playing</a>, it must have its audio data played synchronized with
2380: the <a href="#current-playback-position">current playback position</a>, at the element's
2381: <a href="#effective-media-volume">effective media volume</a>.</p>
2382:
2383: <p>When an <code><a href="#the-audio-element">audio</a></code> element is not <a href="#potentially-playing">potentially
2384: playing</a>, audio must not play for the element.</p>
2385:
2386: </div><dl class="domintro"><dt><var title="">audio</var> = new <code title="dom-Audio"><a href="#dom-audio">Audio</a></code>( [ <var title="">url</var> ] )</dt>
2387:
2388: <dd>
2389:
2390: <p>Returns a new <code><a href="#the-audio-element">audio</a></code> element, with the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute set to the value
2391: passed in the argument, if applicable.</p>
2392:
2393: </dd>
2394:
2395: </dl><div class="impl">
2396:
2397: <p>Two constructors are provided for creating
2398: <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> objects (in addition to the factory
2399: methods from DOM Core such as <code title="">createElement()</code>): <dfn id="dom-audio" title="dom-Audio"><code>Audio()</code></dfn> and <dfn id="dom-audio-s" title="dom-Audio-s"><code>Audio(<var title="">src</var>)</code></dfn>. When invoked as constructors,
2400: these must return a new <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new
2401: <code><a href="#the-audio-element">audio</a></code> element). The element must have its <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute set to the
2402: literal value "<code title="attr-media-preload-auto"><a href="#attr-media-preload-auto">auto</a></code>". If the <var title="">src</var> argument is present, the object created must have
2403: its <code title="attr-media-src"><a href="#attr-media-src">src</a></code> content attribute set to
2404: the provided value, and the user agent must invoke the object's
2405: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2406: algorithm</a> before returning. The element's document must be
2407: the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
2408: context</a> of the <code><a href="browsers.html#window">Window</a></code> object on which the
2409: interface object of the invoked constructor is found.</p>
2410:
2411: </div><h4 id="the-source-element"><span class="secno">4.8.8 </span>The <dfn><code>source</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
2412: <dd>None.</dd>
2413: <dt>Contexts in which this element can be used:</dt>
2414: <dd>As a child of a <a href="#media-element">media element</a>, before any <a href="content-models.html#flow-content">flow content</a>
2415: or <code><a href="#the-track-element">track</a></code> elements.</dd>
2416: <dt>Content model:</dt>
2417: <dd>Empty.</dd>
2418: <dt>Content attributes:</dt>
2419: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2420: <dd><code title="attr-source-src"><a href="#attr-source-src">src</a></code></dd>
2421: <dd><code title="attr-source-type"><a href="#attr-source-type">type</a></code></dd>
2422: <dd><code title="attr-source-media"><a href="#attr-source-media">media</a></code></dd>
2423: <dt>DOM interface:</dt>
2424: <dd>
2425: <pre class="idl">interface <dfn id="htmlsourceelement">HTMLSourceElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2426: attribute DOMString <a href="#dom-source-src" title="dom-source-src">src</a>;
2427: attribute DOMString <a href="#dom-source-type" title="dom-source-type">type</a>;
2428: attribute DOMString <a href="#dom-source-media" title="dom-source-media">media</a>;
2429: };</pre>
2430: </dd>
2431: </dl><p>The <code><a href="#the-source-element">source</a></code> element allows authors to specify
2432: multiple alternative <a href="#media-resource" title="media resource">media
2433: resources</a> for <a href="#media-element" title="media element">media
1.101 mike 2434: elements</a>. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-source-src" title="attr-source-src"><code>src</code></dfn> attribute
1.47 mike 2435: gives the address of the <a href="#media-resource">media resource</a>. The value must
2436: be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2437: spaces</a>. This attribute must be present.</p><p class="note">Dynamically modifying a <code><a href="#the-source-element">source</a></code> element
2438: and its attribute when the element is already inserted in a
2439: <code><a href="#the-video-element">video</a></code> or <code><a href="#the-audio-element">audio</a></code> element will have no
1.62 mike 2440: effect. To change what is playing, just use the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute on the <a href="#media-element">media
2441: element</a> directly, possibly making use of the <code title="dom-navigator-canPlayType"><a href="#dom-navigator-canplaytype">canPlayType()</a></code> method to
2442: pick from amongst available resources. Generally, manipulating
2443: <code><a href="#the-source-element">source</a></code> elements manually after the document has been
2444: parsed is an unncessarily complicated approach.</p><p>The <dfn id="attr-source-type" title="attr-source-type"><code>type</code></dfn>
1.47 mike 2445: attribute gives the type of the <a href="#media-resource">media resource</a>, to help
2446: the user agent determine if it can play this <a href="#media-resource">media
2447: resource</a> before fetching it. If specified, its value must be
2448: a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>. The <code title="">codecs</code>
2449: parameter, which certain MIME types define, might be necessary to
1.101 mike 2450: specify exactly how the resource is encoded. <a href="references.html#refsRFC4281">[RFC4281]</a></p><div class="example">
1.47 mike 2451:
2452: <p>The following list shows some examples of how to use the <code title="">codecs=</code> MIME parameter in the <code title="attr-source-type"><a href="#attr-source-type">type</a></code> attribute.</p>
2453:
2454: <dl><dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2455: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></pre></dd>
2456:
2457: <dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2458: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></pre></dd>
2459:
2460: <dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
2461: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></pre></dd>
2462:
2463: <dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2464: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></pre></dd>
2465:
2466:
2467: <dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2468: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></pre></dd>
2469:
2470: <dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2471: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></pre></dd>
2472:
2473: <dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
2474: <dd><pre><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></pre></dd>
2475:
2476:
2477: <dt>Theora video and Vorbis audio in Ogg container</dt>
2478: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></pre></dd>
2479:
2480: <dt>Theora video and Speex audio in Ogg container</dt>
2481: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></pre></dd>
2482:
2483: <dt>Vorbis audio alone in Ogg container</dt>
2484: <dd><pre><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></pre></dd>
2485:
2486: <dt>Speex audio alone in Ogg container</dt>
2487: <dd><pre><source src='audio.spx' type='audio/ogg; codecs=speex'></pre></dd>
2488:
2489: <dt>FLAC audio alone in Ogg container</dt>
2490: <dd><pre><source src='audio.oga' type='audio/ogg; codecs=flac'></pre></dd>
2491:
2492: <dt>Dirac video and Vorbis audio in Ogg container</dt>
2493: <dd><pre><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></pre></dd>
2494:
2495:
2496:
2497:
2498:
2499:
2500: </dl></div><p>The <dfn id="attr-source-media" title="attr-source-media"><code>media</code></dfn>
2501: attribute gives the intended media type of the <a href="#media-resource">media
2502: resource</a>, to help the user agent determine if this
2503: <a href="#media-resource">media resource</a> is useful to the user before fetching
2504: it. Its value must be a <a href="common-microsyntaxes.html#valid-media-query">valid media query</a>.</p><p id="source-default-media">The default, if the <code title="attr-srouce-media">media</code> attribute is omitted, is
2505: "<code title="">all</code>", meaning that by default the <a href="#media-resource">media
2506: resource</a> is suitable for all media.</p><div class="impl">
2507:
2508: <p>If a <code><a href="#the-source-element">source</a></code> element is inserted as a child of a
2509: <a href="#media-element">media element</a> that has no <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> has the value
2510: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, the user
2511: agent must invoke the <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2512: algorithm</a>.</p>
2513:
2514: <p>The IDL attributes <dfn id="dom-source-src" title="dom-source-src"><code>src</code></dfn>, <dfn id="dom-source-type" title="dom-source-type"><code>type</code></dfn>, and <dfn id="dom-source-media" title="dom-source-media"><code>media</code></dfn> must
2515: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2516: name.</p>
2517:
2518: </div><div class="example">
2519:
2520: <p>If the author isn't sure if the user agents will all be able to
2521: render the media resources provided, the author can listen to the
2522: <code title="event-error">error</code> event on the last
2523: <code><a href="#the-source-element">source</a></code> element and trigger fallback behavior:</p>
2524:
2525: <pre><script>
2526: function fallback(video) {
2527: // replace <video> with its contents
2528: while (video.hasChildNodes()) {
2529: if (video.firstChild instanceof HTMLSourceElement)
2530: video.removeChild(video.firstChild);
2531: else
2532: video.parentNode.insertBefore(video.firstChild, video);
2533: }
2534: video.parentNode.removeChild(video);
2535: }
2536: </script>
2537: <video controls autoplay>
2538: <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
2539: <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
2540: onerror="fallback(parentNode)">
2541: ...
2542: </video></pre>
2543:
2544: </div><h4 id="the-track-element"><span class="secno">4.8.9 </span>The <dfn><code>track</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
2545: <dd>None.</dd>
2546: <dt>Contexts in which this element can be used:</dt>
2547: <dd>As a child of a <a href="#media-element">media element</a>, before any <a href="content-models.html#flow-content">flow content</a>.</dd>
2548: <dt>Content model:</dt>
2549: <dd>Empty.</dd>
2550: <dt>Content attributes:</dt>
2551: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2552: <dd><code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code></dd>
2553: <dd><code title="attr-track-src"><a href="#attr-track-src">src</a></code></dd>
2554: <dd><code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code></dd>
2555: <dd><code title="attr-track-label"><a href="#attr-track-label">label</a></code></dd>
2556: <dd><code title="attr-track-default"><a href="#attr-track-default">default</a></code></dd>
2557: <dt>DOM interface:</dt>
2558: <dd>
2559: <pre class="idl">interface <dfn id="htmltrackelement">HTMLTrackElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2560: attribute DOMString <a href="#dom-track-kind" title="dom-track-kind">kind</a>;
2561: attribute DOMString <a href="#dom-track-src" title="dom-track-src">src</a>;
2562: attribute DOMString <a href="#dom-track-srclang" title="dom-track-srclang">srclang</a>;
2563: attribute DOMString <a href="#dom-track-label" title="dom-track-label">label</a>;
2564: attribute boolean <a href="#dom-track-default" title="dom-track-default">default</a>;
2565:
1.130 mike 2566: const unsigned short <a href="#dom-track-none" title="dom-track-NONE">NONE</a> = 0;
2567: const unsigned short <a href="#dom-track-loading" title="dom-track-LOADING">LOADING</a> = 1;
2568: const unsigned short <a href="#dom-track-loaded" title="dom-track-LOADED">LOADED</a> = 2;
2569: const unsigned short <a href="#dom-track-error" title="dom-track-ERROR">ERROR</a> = 3;
2570: readonly attribute unsigned short <a href="#dom-track-readystate" title="dom-track-readyState">readyState</a>;
2571:
1.47 mike 2572: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-track-track" title="dom-track-track">track</a>;
2573: };</pre>
2574: </dd>
2575: </dl><p>The <code><a href="#the-track-element">track</a></code> element allows authors to specify explicit
1.101 mike 2576: external timed <a href="#text-track" title="text track">text tracks</a> for <a href="#media-element" title="media element">media elements</a>. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-track-kind" title="attr-track-kind"><code>kind</code></dfn>
1.47 mike 2577: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following
2578: table lists the keywords defined for this attribute. The keyword
2579: given in the first cell of each row maps to the state given in the
2580: second cell.</p><table><thead><tr><th>Keyword
2581: </th><th>State
2582: </th><th>Brief description
2583: </th></tr></thead><tbody><tr><td><dfn id="attr-track-kind-keyword-subtitles" title="attr-track-kind-keyword-subtitles"><code>subtitles</code></dfn>
2584: </td><td><dfn id="attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</dfn>
2585: </td><td>
1.123 mike 2586: Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the <a href="#media-resource">media resource</a>'s audio track).
1.115 mike 2587: Overlaid on the video.
1.47 mike 2588: </td></tr><tr><td><dfn id="attr-track-kind-keyword-captions" title="attr-track-kind-keyword-captions"><code>captions</code></dfn>
2589: </td><td><dfn id="attr-track-kind-captions" title="attr-track-kind-captions">Captions</dfn>
2590: </td><td>
1.123 mike 2591: Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf).
1.115 mike 2592: Overlaid on the video; labeled as appropriate for the hard-of-hearing.
1.47 mike 2593: </td></tr><tr><td><dfn id="attr-track-kind-keyword-descriptions" title="attr-track-kind-keyword-descriptions"><code>descriptions</code></dfn>
2594: </td><td><dfn id="attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</dfn>
2595: </td><td>
1.95 mike 2596: Textual descriptions of the video component of the <a href="#media-resource">media resource</a>, intended for audio synthesis when the visual component is obscured, unavailable, or not usable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind).
2597: Synthesized as audio.
1.47 mike 2598: </td></tr><tr><td><dfn id="attr-track-kind-keyword-chapters" title="attr-track-kind-keyword-chapters"><code>chapters</code></dfn>
2599: </td><td><dfn id="attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</dfn>
2600: </td><td>
2601: Chapter titles, intended to be used for navigating the <a href="#media-resource">media resource</a>.
1.91 mike 2602: Displayed as an interactive (potentially nested) list in the user agent's interface.
1.47 mike 2603: </td></tr><tr><td><dfn id="attr-track-kind-keyword-metadata" title="attr-track-kind-keyword-metadata"><code>metadata</code></dfn>
2604: </td><td><dfn id="attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</dfn>
2605: </td><td>
2606: Tracks intended for use from script.
2607: Not displayed by the user agent.
2608: </td></tr></tbody></table><p>The attribute may be omitted. The <i>missing value default</i> is
2609: the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a> state.</p><p>The <dfn id="attr-track-src" title="attr-track-src"><code>src</code></dfn> attribute
2610: gives the address of the text track data. The value must be a
2611: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2612: spaces</a>. This attribute must be present.</p><div class="impl">
2613:
2614: <p>If the element has a <code title="attr-track-src"><a href="#attr-track-src">src</a></code>
2615: attribute whose value is not the empty string and whose value, when
2616: the attribute was set, could be successfully <a href="urls.html#resolve-a-url" title="resolve a
2617: url">resolved</a> relative to the element, then the element's
2618: <dfn id="track-url">track URL</dfn> is the resulting <a href="urls.html#absolute-url">absolute
2619: URL</a>. Otherwise, the element's <a href="#track-url">track URL</a> is the
2620: empty string.</p>
2621:
2622: </div><p>The <dfn id="attr-track-srclang" title="attr-track-srclang"><code>srclang</code></dfn>
2623: attribute gives the language of the text track data. The value must
2624: be a valid BCP 47 language tag. This attribute must be present if
2625: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute is
2626: in the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a>
1.101 mike 2627: state. <a href="references.html#refsBCP47">[BCP47]</a></p><div class="impl">
1.47 mike 2628:
2629: <p>If the element has a <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attribute whose value is
2630: not the empty string, then the element's <dfn id="track-language">track language</dfn>
2631: is the value of the attribute. Otherwise, the element has no
2632: <a href="#track-language">track language</a>.</p>
2633:
2634: </div><p>The <dfn id="attr-track-label" title="attr-track-label"><code>label</code></dfn>
2635: attribute gives a user-readable title for the track. This title is
2636: used by user agents when listing <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitle</a>, <a href="#attr-track-kind-captions" title="attr-track-kind-captions">caption</a>, and <a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">audio description</a> tracks
2637: in their user interface.</p><p>The value of the <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2638: attribute, if the attribute is present, must not be the empty
2639: string. Furthermore, there must not be two <code><a href="#the-track-element">track</a></code>
2640: element children of the same <a href="#media-element">media element</a> whose <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attributes are in the same
2641: state, whose <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code>
2642: attributes are both missing or have values that represent the same
2643: language, and whose <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2644: attributes are again both missing or both have the same value.</p><div class="impl">
2645:
2646: <p>If the element has a <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2647: attribute whose value is not the empty string, then the element's
2648: <dfn id="track-label">track label</dfn> is the value of the attribute. Otherwise, the
2649: element's <a href="#track-label">track label</a> is a user-agent defined string
2650: (e.g. the string "untitled" in the user's locale, or a value
2651: automatically generated from the other attributes).</p>
2652:
2653: </div><p>The <dfn id="attr-track-default" title="attr-track-default"><code>default</code></dfn>
2654: attribute, if specified, indicates that the track is to be enabled
2655: if the user's preferences do not indicate that another track would
2656: be more appropriate. There must not be more than one
1.130 mike 2657: <code><a href="#the-track-element">track</a></code> element with the same parent node with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute specified.</p><dl class="domintro"><dt><var title="">track</var> . <code title="dom-track-readyState"><a href="#dom-track-readystate">readyState</a></code></dt>
2658: <dd>
2659: <p>Returns the <a href="#text-track-readiness-state">text track readiness state</a>,
2660: represented by a number from the following list:</p>
2661: <dl><dt><var title="">track</var> . <code title="dom-track-NONE"><a href="#dom-track-none">NONE</a></code> (0)</dt>
2662: <dd>
2663: <p>The <a href="#text-track-not-loaded">text track not loaded</a> state.</p>
2664: </dd>
2665: <dt><var title="">track</var> . <code title="dom-track-LOADING"><a href="#dom-track-loading">LOADING</a></code> (1)</dt>
2666: <dd>
2667: <p>The <a href="#text-track-loading">text track loading</a> state.</p>
2668: </dd>
2669: <dt><var title="">track</var> . <code title="dom-track-LOADED"><a href="#dom-track-loaded">LOADED</a></code> (2)</dt>
2670: <dd>
2671: <p>The <a href="#text-track-loaded">text track loaded</a> state.</p>
2672: </dd>
2673: <dt><var title="">track</var> . <code title="dom-track-ERROR"><a href="#dom-track-error">ERROR</a></code> (3)</dt>
2674: <dd>
2675: <p>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</p>
2676: </dd>
2677: </dl></dd>
2678:
2679: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
1.47 mike 2680:
2681: <dd>
2682:
2683: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object corresponding to the <a href="#text-track">text track</a> of the <code><a href="#the-track-element">track</a></code> element.</p>
2684:
2685: </dd>
2686:
2687: </dl><div class="impl">
2688:
1.130 mike 2689: <p>The <dfn id="dom-track-readystate" title="dom-track-readyState"><code>readyState</code></dfn> attribute
2690: must return the numeric value corresponding to the <a href="#text-track-readiness-state">text track
2691: readiness state</a> of the <code><a href="#the-track-element">track</a></code> element's
2692: <a href="#text-track">text track</a>, as defined by the following list:</p>
2693:
2694: <dl><dt><dfn id="dom-track-none" title="dom-track-NONE"><code>NONE</code></dfn> (numeric value 0)</dt>
2695: <dd>The <a href="#text-track-not-loaded">text track not loaded</a> state.</dd>
2696: <dt><dfn id="dom-track-loading" title="dom-track-LOADING"><code>LOADING</code></dfn> (numeric value 1)</dt>
2697: <dd>The <a href="#text-track-loading">text track loading</a> state.</dd>
2698: <dt><dfn id="dom-track-loaded" title="dom-track-LOADED"><code>LOADED</code></dfn> (numeric value 2)</dt>
2699: <dd>The <a href="#text-track-loaded">text track loaded</a> state.</dd>
2700: <dt><dfn id="dom-track-error" title="dom-track-ERROR"><code>ERROR</code></dfn> (numeric value 3)</dt>
2701: <dd>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</dd>
2702: </dl><p>The <dfn id="dom-track-track" title="dom-track-track"><code>track</code></dfn> IDL
1.47 mike 2703: attribute must, on getting, return the <code><a href="#the-track-element">track</a></code> element's
2704: <a href="#text-track">text track</a>'s corresponding <code><a href="#texttrack">TextTrack</a></code>
2705: object.</p>
2706:
2707: <p>The <dfn id="dom-track-src" title="dom-track-src"><code>src</code></dfn>, <dfn id="dom-track-srclang" title="dom-track-srclang"><code>srclang</code></dfn>, <dfn id="dom-track-label" title="dom-track-label"><code>label</code></dfn>, and <dfn id="dom-track-default" title="dom-track-default"><code>default</code></dfn> IDL attributes
2708: must <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the
2709: same name. The <dfn id="dom-track-kind" title="dom-track-kind"><code>kind</code></dfn>
2710: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
2711: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
2712:
2713: </div><div class="example">
2714:
2715: <p>This video has subtitles in several languages:</p>
2716:
2717: <pre><video src="brave.webm">
2718: <track kind=subtitles src=brave.en.vtt srclang=en label="English">
1.123 mike 2719: <track kind=captions src=brave.en.hoh.vtt srclang=en label="English for the Hard of Hearing">
1.73 mike 2720: <track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
2721: <track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
1.47 mike 2722: </video></pre>
2723:
2724: </div><h4 id="media-elements"><span class="secno">4.8.10 </span>Media elements</h4><p><dfn id="media-element" title="media element">Media elements</dfn>
2725: (<code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>, in this specification)
2726: implement the following interface:</p><pre class="idl">interface <dfn id="htmlmediaelement">HTMLMediaElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2727:
2728: // error state
1.68 mike 2729: readonly attribute <a href="#mediaerror">MediaError</a>? <a href="#dom-media-error" title="dom-media-error">error</a>;
1.47 mike 2730:
2731: // network state
2732: attribute DOMString <a href="#dom-media-src" title="dom-media-src">src</a>;
2733: readonly attribute DOMString <a href="#dom-media-currentsrc" title="dom-media-currentSrc">currentSrc</a>;
1.61 mike 2734: attribute DOMString <a href="#dom-media-crossorigin" title="dom-media-crossOrigin">crossOrigin</a>;
1.47 mike 2735: const unsigned short <a href="#dom-media-network_empty" title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</a> = 0;
2736: const unsigned short <a href="#dom-media-network_idle" title="dom-media-NETWORK_IDLE">NETWORK_IDLE</a> = 1;
2737: const unsigned short <a href="#dom-media-network_loading" title="dom-media-NETWORK_LOADING">NETWORK_LOADING</a> = 2;
2738: const unsigned short <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a> = 3;
2739: readonly attribute unsigned short <a href="#dom-media-networkstate" title="dom-media-networkState">networkState</a>;
2740: attribute DOMString <a href="#dom-media-preload" title="dom-media-preload">preload</a>;
2741: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-buffered" title="dom-media-buffered">buffered</a>;
2742: void <a href="#dom-media-load" title="dom-media-load">load</a>();
1.101 mike 2743: DOMString <a href="#dom-navigator-canplaytype" title="dom-navigator-canPlayType">canPlayType</a>(DOMString type);
1.47 mike 2744:
2745: // ready state
2746: const unsigned short <a href="#dom-media-have_nothing" title="dom-media-HAVE_NOTHING">HAVE_NOTHING</a> = 0;
2747: const unsigned short <a href="#dom-media-have_metadata" title="dom-media-HAVE_METADATA">HAVE_METADATA</a> = 1;
2748: const unsigned short <a href="#dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</a> = 2;
2749: const unsigned short <a href="#dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</a> = 3;
2750: const unsigned short <a href="#dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</a> = 4;
2751: readonly attribute unsigned short <a href="#dom-media-readystate" title="dom-media-readyState">readyState</a>;
2752: readonly attribute boolean <a href="#dom-media-seeking" title="dom-media-seeking">seeking</a>;
2753:
2754: // playback state
2755: attribute double <a href="#dom-media-currenttime" title="dom-media-currentTime">currentTime</a>;
2756: readonly attribute double <a href="#dom-media-initialtime" title="dom-media-initialTime">initialTime</a>;
2757: readonly attribute double <a href="#dom-media-duration" title="dom-media-duration">duration</a>;
2758: readonly attribute <span>Date</span> <a href="#dom-media-startoffsettime" title="dom-media-startOffsetTime">startOffsetTime</a>;
2759: readonly attribute boolean <a href="#dom-media-paused" title="dom-media-paused">paused</a>;
2760: attribute double <a href="#dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate">defaultPlaybackRate</a>;
2761: attribute double <a href="#dom-media-playbackrate" title="dom-media-playbackRate">playbackRate</a>;
2762: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-played" title="dom-media-played">played</a>;
2763: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-seekable" title="dom-media-seekable">seekable</a>;
2764: readonly attribute boolean <a href="#dom-media-ended" title="dom-media-ended">ended</a>;
2765: attribute boolean <a href="#dom-media-autoplay" title="dom-media-autoplay">autoplay</a>;
2766: attribute boolean <a href="#dom-media-loop" title="dom-media-loop">loop</a>;
2767: void <a href="#dom-media-play" title="dom-media-play">play</a>();
2768: void <a href="#dom-media-pause" title="dom-media-pause">pause</a>();
2769:
2770: // media controller
2771: attribute <span>DOMString</span> <a href="#dom-media-mediagroup" title="dom-media-mediaGroup">mediaGroup</a>;
1.68 mike 2772: attribute <a href="#mediacontroller">MediaController</a>? <a href="#dom-media-controller" title="dom-media-controller">controller</a>;
1.47 mike 2773:
2774: // controls
2775: attribute boolean <a href="#dom-media-controls" title="dom-media-controls">controls</a>;
2776: attribute double <a href="#dom-media-volume" title="dom-media-volume">volume</a>;
2777: attribute boolean <a href="#dom-media-muted" title="dom-media-muted">muted</a>;
2778: attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
2779:
2780: // tracks
1.76 mike 2781: readonly attribute <a href="#audiotracklist">AudioTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
2782: readonly attribute <a href="#videotracklist">VideoTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
1.121 mike 2783: readonly attribute <a href="#texttracklist">TextTrackList</a> <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
1.132 mike 2784: <a href="#texttrack">TextTrack</a> <a href="#dom-media-addtexttrack" title="dom-media-addTextTrack">addTextTrack</a>(DOMString kind, optional DOMString label, optional DOMString language);
1.61 mike 2785: };</pre><p>The <dfn id="media-element-attributes">media element attributes</dfn>, <code title="attr-media-src"><a href="#attr-media-src">src</a></code>, <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code>, <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
1.47 mike 2786: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2787: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2788: <code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code>, and <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code>, apply to all <a href="#media-element" title="media element">media elements</a>. They are defined in
2789: this section.</p><p><a href="#media-element" title="media element">Media elements</a> are used to
2790: present audio data, or video and audio data, to the user. This is
2791: referred to as <dfn id="media-data">media data</dfn> in this section, since this
2792: section applies equally to <a href="#media-element" title="media element">media
1.56 mike 2793: elements</a> for audio or for video.
1.85 mike 2794:
1.56 mike 2795: The term <dfn id="media-resource">media resource</dfn> is used to refer to the complete
2796: set of media data, e.g. the complete video file, or complete audio
2797: file.
1.85 mike 2798:
1.56 mike 2799: </p><p>A <a href="#media-resource">media resource</a> can have multiple audio and video
1.47 mike 2800: tracks. For the purposes of a <a href="#media-element">media element</a>, the video
2801: data of the <a href="#media-resource">media resource</a> is only that of the
2802: currently selected track (if any) given by the element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attribute, and the
2803: audio data of the <a href="#media-resource">media resource</a> is the result of
2804: mixing all the currently enabled tracks (if any) given by the
2805: element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>
2806: attribute.</p><p class="note">Both <code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>
2807: elements can be used for both audio and video. The main difference
2808: between the two is simply that the <code><a href="#the-audio-element">audio</a></code> element has no
2809: playback area for visual content (such as video or captions),
2810: whereas the <code><a href="#the-video-element">video</a></code> element does.</p><div class="impl">
2811:
2812: <p>Except where otherwise specified, the <a href="webappapis.html#task-source">task source</a>
2813: for all the tasks <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> in this
2814: section and its subsections is the <dfn id="media-element-event-task-source">media element event task
2815: source</dfn>.</p>
2816:
2817: </div><h5 id="error-codes"><span class="secno">4.8.10.1 </span>Error codes</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-error"><a href="#dom-media-error">error</a></code></dt>
2818:
2819: <dd>
2820:
2821: <p>Returns a <code><a href="#mediaerror">MediaError</a></code> object representing the
2822: current error state of the element.</p>
2823:
2824: <p>Returns null if there is no error.</p>
2825:
2826: </dd>
2827:
2828: </dl><div class="impl">
2829:
2830: <p>All <a href="#media-element" title="media element">media elements</a> have an
2831: associated error status, which records the last error the element
2832: encountered since its <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2833: algorithm</a> was last invoked. The <dfn id="dom-media-error" title="dom-media-error"><code>error</code></dfn> attribute, on
2834: getting, must return the <code><a href="#mediaerror">MediaError</a></code> object created for
2835: this last error, or null if there has not been an error.</p>
2836:
2837: </div><pre class="idl">interface <dfn id="mediaerror">MediaError</dfn> {
2838: const unsigned short <a href="#dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</a> = 1;
2839: const unsigned short <a href="#dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</a> = 2;
2840: const unsigned short <a href="#dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</a> = 3;
2841: const unsigned short <a href="#dom-mediaerror-media_err_src_not_supported" title="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED">MEDIA_ERR_SRC_NOT_SUPPORTED</a> = 4;
2842: readonly attribute unsigned short <a href="#dom-mediaerror-code" title="dom-MediaError-code">code</a>;
2843: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-error"><a href="#dom-media-error">error</a></code> . <code title="dom-MediaError-code"><a href="#dom-mediaerror-code">code</a></code></dt>
2844:
2845: <dd>
2846:
2847: <p>Returns the current error's error code, from the list below.</p>
2848:
2849: </dd>
2850:
2851: </dl><div class="impl">
2852:
2853: <p>The <dfn id="dom-mediaerror-code" title="dom-MediaError-code"><code>code</code></dfn>
2854: attribute of a <code><a href="#mediaerror">MediaError</a></code> object must return the code
2855: for the error, which must be one of the following:</p>
2856:
2857: </div><dl><dt><dfn id="dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED"><code>MEDIA_ERR_ABORTED</code></dfn> (numeric value 1)</dt>
2858:
2859: <dd>The fetching process for the <a href="#media-resource">media resource</a> was
2860: aborted by the user agent at the user's request.</dd>
2861:
2862: <dt><dfn id="dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK"><code>MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
2863:
2864: <dd>A network error of some description caused the user agent to
2865: stop fetching the <a href="#media-resource">media resource</a>, after the resource
2866: was established to be usable.</dd>
2867:
2868: <dt><dfn id="dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE"><code>MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
2869:
2870: <dd>An error of some description occurred while decoding the
2871: <a href="#media-resource">media resource</a>, after the resource was established to
2872: be usable.</dd>
2873:
2874: <dt><dfn id="dom-mediaerror-media_err_src_not_supported" title="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED"><code>MEDIA_ERR_SRC_NOT_SUPPORTED</code></dfn> (numeric value 4)</dt>
2875:
2876: <dd>The <a href="#media-resource">media resource</a> indicated by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was not suitable.</dd>
2877:
2878: </dl><h5 id="location-of-the-media-resource"><span class="secno">4.8.10.2 </span>Location of the media resource</h5><p>The <dfn id="attr-media-src" title="attr-media-src"><code>src</code></dfn> content
2879: attribute on <a href="#media-element" title="media element">media elements</a> gives
2880: the address of the media resource (video, audio) to show. The
2881: attribute, if present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.61 mike 2882: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-media-crossorigin" title="attr-media-crossorigin"><code>crossorigin</code></dfn>
2883: content attribute on <a href="#media-element" title="media element">media
2884: elements</a> is a <a href="fetching-resources.html#cors-settings-attribute">CORS settings attribute</a>.</p><div class="impl">
1.47 mike 2885:
2886: <p>If a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute of a
2887: <a href="#media-element">media element</a> is set or changed, the user agent must
2888: invoke the <a href="#media-element">media element</a>'s <a href="#media-element-load-algorithm">media element load
2889: algorithm</a>. (<em>Removing</em> the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute does not do this, even
2890: if there are <code><a href="#the-source-element">source</a></code> elements present.)</p>
2891:
2892: <p>The <dfn id="dom-media-src" title="dom-media-src"><code>src</code></dfn> IDL
2893: attribute on <a href="#media-element" title="media element">media elements</a> must
2894: <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the same name.</p>
2895:
1.61 mike 2896: <p>The <dfn id="dom-media-crossorigin" title="dom-media-crossOrigin"><code>crossOrigin</code></dfn> IDL
2897: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
2898: attribute.</p>
2899:
1.47 mike 2900: </div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code></dt>
2901:
2902: <dd>
2903:
2904: <p>Returns the address of the current <a href="#media-resource">media resource</a>.</p>
2905:
2906: <p>Returns the empty string when there is no <a href="#media-resource">media resource</a>.</p>
2907:
2908: </dd>
2909:
2910: </dl><div class="impl">
2911:
2912: <p>The <dfn id="dom-media-currentsrc" title="dom-media-currentSrc"><code>currentSrc</code></dfn> IDL
2913: attribute is initially the empty string. Its value is changed by the
2914: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2915: algorithm</a> defined below.</p>
2916:
2917: </div><p class="note">There are two ways to specify a <a href="#media-resource">media
2918: resource</a>, the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
2919: attribute, or <code><a href="#the-source-element">source</a></code> elements. The attribute overrides
1.53 mike 2920: the elements.</p><h5 id="mime-types"><span class="secno">4.8.10.3 </span>MIME types</h5><p>A <a href="#media-resource">media resource</a> can be described in terms of its
1.47 mike 2921: <em>type</em>, specifically a <a href="infrastructure.html#mime-type">MIME type</a>, in some cases
2922: with a <code title="">codecs</code> parameter. (Whether the <code title="">codecs</code> parameter is allowed or not depends on the
1.101 mike 2923: MIME type.) <a href="references.html#refsRFC4281">[RFC4281]</a></p><p>Types are usually somewhat incomplete descriptions; for example
1.47 mike 2924: "<code title="">video/mpeg</code>" doesn't say anything except what
2925: the container type is, and even a type like "<code title="">video/mp4; codecs="avc1.42E01E,
2926: mp4a.40.2"</code>" doesn't include information like the actual
2927: bitrate (only the maximum bitrate). Thus, given a type, a user agent
2928: can often only know whether it <em>might</em> be able to play
2929: media of that type (with varying levels of confidence), or whether
2930: it definitely <em>cannot</em> play media of that type.</p><p><dfn id="a-type-that-the-user-agent-knows-it-cannot-render">A type that the user agent knows it cannot render</dfn> is
2931: one that describes a resource that the user agent definitely does
2932: not support, for example because it doesn't recognize the container
2933: type, or it doesn't support the listed codecs.</p><p>The <a href="infrastructure.html#mime-type">MIME type</a>
2934: "<code>application/octet-stream</code>" with no parameters is never
2935: <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user agent knows it cannot render</a>. User
2936: agents must treat that type as equivalent to the lack of any
2937: explicit <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a>
2938: when it is used to label a potential <a href="#media-resource">media
2939: resource</a>.</p><p class="note">
2940: "<code>application/octet-stream</code>"
2941: is special-cased here; if any parameter appears with it, it
2942: should
2943:
2944: be treated just like any other <a href="infrastructure.html#mime-type">MIME type</a>.
2945:
2946: This is a deviation from the rule that unknown <a href="infrastructure.html#mime-type">MIME type</a> parameters
2947: should be ignored.
2948:
2949:
2950: </p><dl class="domintro"><dt><var title="">media</var> . <code title="dom-navigator-canPlayType"><a href="#dom-navigator-canplaytype">canPlayType</a></code>(<var title="">type</var>)</dt>
2951:
2952: <dd>
2953:
2954: <p>Returns the empty string (a negative response), "maybe", or
2955: "probably" based on how confident the user agent is that it can
2956: play media resources of the given type.</p>
2957:
2958: </dd>
2959:
2960: </dl><div class="impl">
2961:
2962: <p>The <dfn id="dom-navigator-canplaytype" title="dom-navigator-canPlayType"><code>canPlayType(<var title="">type</var>)</code></dfn> method must return the empty
2963: string if <var title="">type</var> is <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user
2964: agent knows it cannot render</a> or is the type
2965: "<code>application/octet-stream</code>"; it must return "<code title="">probably</code>" if the user agent is confident that the
2966: type represents a <a href="#media-resource">media resource</a> that it can render if
2967: used in with this <code><a href="#the-audio-element">audio</a></code> or <code><a href="#the-video-element">video</a></code> element;
2968: and it must return "<code title="">maybe</code>" otherwise.
2969: Implementors are encouraged to return "<code title="">maybe</code>"
2970: unless the type can be confidently established as being supported or
2971: not. Generally, a user agent should never return "<code title="">probably</code>" for a type that allows the <code title="">codecs</code> parameter if that parameter is not
2972: present.</p>
2973:
2974: </div><div class="example">
2975:
2976: <p>This script tests to see if the user agent supports a
2977: (fictional) new format to dynamically decide whether to use a
2978: <code><a href="#the-video-element">video</a></code> element or a plugin:</p>
2979:
2980: <pre><section id="video">
2981: <p><a href="playing-cats.nfv">Download video</a></p>
2982: </section>
2983: <script>
2984: var videoSection = document.getElementById('video');
2985: var videoElement = document.createElement('video');
2986: var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
1.69 mike 2987: if (support != "probably" && "New Fictional Video Plugin" in navigator.plugins) {
1.47 mike 2988: // not confident of browser support
2989: // but we have a plugin
2990: // so use plugin instead
2991: videoElement = document.createElement("embed");
2992: } else if (support == "") {
2993: // no support from browser and no plugin
2994: // do nothing
2995: videoElement = null;
2996: }
2997: if (videoElement) {
2998: while (videoSection.hasChildNodes())
2999: videoSection.removeChild(videoSection.firstChild);
3000: videoElement.setAttribute("src", "playing-cats.nfv");
3001: videoSection.appendChild(videoElement);
3002: }
3003: </script></pre>
3004:
3005: </div><p class="note">The <code title="attr-source-type"><a href="#attr-source-type">type</a></code>
3006: attribute of the <code><a href="#the-source-element">source</a></code> element allows the user agent
3007: to avoid downloading resources that use formats it cannot
3008: render.</p><h5 id="network-states"><span class="secno">4.8.10.4 </span>Network states</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code></dt>
3009:
3010: <dd>
3011:
3012: <p>Returns the current state of network activity for the element,
3013: from the codes in the list below.</p>
3014:
3015: </dd>
3016:
3017: </dl><div class="impl">
3018:
3019: <p>As <a href="#media-element" title="media element">media elements</a> interact
3020: with the network, their current network activity is represented by
3021: the <dfn id="dom-media-networkstate" title="dom-media-networkState"><code>networkState</code></dfn>
3022: attribute. On getting, it must return the current network state of
3023: the element, which must be one of the following values:</p>
3024:
3025: </div><dl><dt><dfn id="dom-media-network_empty" title="dom-media-NETWORK_EMPTY"><code>NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
3026:
3027: <dd>The element has not yet been initialized. All attributes are in
3028: their initial states.</dd>
3029:
3030: <dt><dfn id="dom-media-network_idle" title="dom-media-NETWORK_IDLE"><code>NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
3031:
3032: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3033: algorithm</a> is active and</span> has selected a <a href="#media-resource" title="media resource">resource</a>, but it is not actually
3034: using the network at this time.</dd>
3035:
3036: <dt><dfn id="dom-media-network_loading" title="dom-media-NETWORK_LOADING"><code>NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
3037:
3038: <dd>The user agent is actively trying to download data.</dd>
3039:
3040: <dt><dfn id="dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE"><code>NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
3041:
3042: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3043: algorithm</a> is active, but it</span> has not yet found a <a href="#media-resource" title="media resource">resource</a> to use.</dd>
3044:
3045: </dl><div class="impl">
3046:
3047: <p>The <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3048: algorithm</a> defined below describes exactly when the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute changes
3049: value and what events fire to indicate changes in this state.</p>
3050:
3051: </div><h5 id="loading-the-media-resource"><span class="secno">4.8.10.5 </span>Loading the media resource</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-load"><a href="#dom-media-load">load</a></code>()</dt>
3052:
3053: <dd>
3054:
3055: <p>Causes the element to reset and start selecting and loading a
3056: new <a href="#media-resource">media resource</a> from scratch.</p>
3057:
3058: </dd>
3059:
3060: </dl><div class="impl">
3061:
3062: <p>All <a href="#media-element" title="media element">media elements</a> have an
3063: <dfn id="autoplaying-flag">autoplaying flag</dfn>, which must begin in the true state, and
3064: a <dfn id="delaying-the-load-event-flag">delaying-the-load-event flag</dfn>, which must begin in the
3065: false state. While the <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> is
1.101 mike 3066: true, the element must <a href="the-end.html#delay-the-load-event">delay the load event</a> of its
1.47 mike 3067: document.</p>
3068:
3069: <p>When the <dfn id="dom-media-load" title="dom-media-load"><code>load()</code></dfn>
3070: method on a <a href="#media-element">media element</a> is invoked, the user agent
3071: must run the <a href="#media-element-load-algorithm">media element load algorithm</a>.</p>
3072:
3073: <p>The <dfn id="media-element-load-algorithm">media element load algorithm</dfn> consists of the
3074: following steps.</p>
3075:
3076: <ol><li><p>Abort any already-running instance of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3077: algorithm</a> for this element.</p></li>
3078:
3079: <li>
3080:
3081: <p>If there are any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> from
3082: the <a href="#media-element">media element</a>'s <a href="#media-element-event-task-source">media element event task
3083: source</a> in one of the <a href="webappapis.html#task-queue" title="task queue">task
3084: queues</a>, then remove those tasks.</p>
3085:
3086: <p class="note">Basically, pending events and callbacks for the
3087: media element are discarded when the media element starts loading
3088: a new resource.</p>
3089:
3090: </li>
3091:
3092: <li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> is set to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code> or <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>, <a href="webappapis.html#queue-a-task">queue a
3093: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code> at the <a href="#media-element">media
3094: element</a>.</p></li>
3095:
3096: <li>
3097:
3098: <p>If the <a href="#media-element">media element</a>'s <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> is not set to
3099: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, then
3100: run these substeps:</p>
3101:
3102: <ol><li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3103: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the <a href="#media-element">media
3104: element</a>.</p></li>
3105:
3106: <li><p>If a fetching process is in progress for the <a href="#media-element">media
3107: element</a>, the user agent should stop it.</p></li>
3108:
3109: <li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3110: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>.</p></li>
3111:
3112: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3113: text tracks</a>.</p></li>
3114:
3115: <li><p>If <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is
3116: not set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then set it
3117: to that state.
3118:
3119: </p></li>
3120:
3121: <li><p>If the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
3122: attribute is false, then set it to true.</p></li>
3123:
3124: <li><p>If <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true,
3125: set it to false.</p></li>
3126:
3127: <li>
3128:
3129: <p>Set the <a href="#current-playback-position">current playback position</a> to 0.</p>
3130:
1.107 mike 3131: <p>Set the <a href="#official-playback-position">official playback position</a> to 0.</p>
3132:
3133: <p>If this changed the <a href="#official-playback-position">official playback position</a>,
1.47 mike 3134: then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3135: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
3136: <a href="#media-element">media element</a>.</p>
3137:
3138: </li>
3139:
3140: <li><p>Set the <a href="#initial-playback-position">initial playback position</a> to
3141: 0.</p></li>
3142:
3143: <li><p>Set the <a href="#timeline-offset">timeline offset</a> to Not-a-Number
3144: (NaN).</p></li>
3145:
3146: <li>
3147:
3148: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3149: attribute to Not-a-Number (NaN).</p>
3150:
3151: <p class="note">The user agent <a href="#durationChange">will
3152: not</a> fire a <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event
3153: for this particular change of the duration.</p>
3154:
3155: </li>
3156:
3157: </ol></li>
3158:
3159: <li><p>Set the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute to the
3160: value of the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
3161: attribute.</p></li>
3162:
3163: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code> attribute
3164: to null and the <a href="#autoplaying-flag">autoplaying flag</a> to true.</p></li>
3165:
3166: <li><p>Invoke the <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3167: algorithm</a>.</p></li>
3168:
3169: <li>
3170:
3171: <p class="note">Playback of any previously playing <a href="#media-resource">media
3172: resource</a> for this element stops.</p>
3173:
3174: </li>
3175:
3176: </ol><p>The <dfn id="concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3177: algorithm</dfn> for a <a href="#media-element">media element</a> is as follows. This
3178: algorithm is always invoked synchronously, but one of the first
3179: steps in the algorithm is to return and continue running the
3180: remaining steps asynchronously, meaning that it runs in the
3181: background with scripts and other <a href="webappapis.html#concept-task" title="concept-task">tasks</a> running in parallel. In addition,
3182: this algorithm interacts closely with the <a href="webappapis.html#event-loop">event loop</a>
3183: mechanism; in particular, it has <a href="webappapis.html#synchronous-section" title="synchronous
3184: section">synchronous sections</a> (which are triggered as part of
3185: the <a href="webappapis.html#event-loop">event loop</a> algorithm). Steps in such sections are
3186: marked with ⌛.</p>
3187:
3188: <ol><li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_NO_SOURCE"><a href="#dom-media-network_no_source">NETWORK_NO_SOURCE</a></code>.</p></li>
3189:
3190: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
3191: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that invoked this
3192: algorithm to continue. The <a href="webappapis.html#synchronous-section">synchronous section</a>
3193: consists of all the remaining steps of this algorithm until the
3194: algorithm says the <a href="webappapis.html#synchronous-section">synchronous section</a> has
3195: ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous
3196: sections</a> are marked with ⌛.)</p></li>
3197:
3198: <li>
3199:
3200: <p>⌛ If the <a href="#media-element">media element</a> has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute, then let <var title="">mode</var> be <i title="">attribute</i>.</p>
3201:
3202: <p>⌛ Otherwise, if the <a href="#media-element">media element</a> does not
3203: have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute but has a
3204: <code><a href="#the-source-element">source</a></code> element child, then let <var title="">mode</var> be <i title="">children</i> and let <var title="">candidate</var> be the first such <code><a href="#the-source-element">source</a></code>
3205: element child in <a href="infrastructure.html#tree-order">tree order</a>.</p>
3206:
3207: <p>⌛ Otherwise the <a href="#media-element">media element</a> has neither a
3208: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute nor a
3209: <code><a href="#the-source-element">source</a></code> element child: set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, and abort
3210: these steps; the <a href="webappapis.html#synchronous-section">synchronous section</a> ends.</p>
3211:
3212: </li>
3213:
3214: <li><p>⌛ Set the <a href="#media-element">media element</a>'s
1.101 mike 3215: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> to true (this <a href="the-end.html#delay-the-load-event" title="delay the load event">delays the load event</a>), and set
1.47 mike 3216: its <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3217: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3218:
3219: <li><p>⌛ <a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3220: event</a> named <code title="event-media-loadstart"><a href="#event-media-loadstart">loadstart</a></code> at the <a href="#media-element">media
3221: element</a>.</p></li>
3222:
3223: <li>
3224:
3225: <p>If <var title="">mode</var> is <i title="">attribute</i>, then
3226: run these substeps:</p>
3227:
3228: <ol><li><p>⌛ <i>Process candidate</i>: If the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute's value is the empty
3229: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3230: down to the <i title="">failed</i> step below.</p></li>
3231:
3232: <li><p>⌛ Let <var title="">absolute URL</var> be the
3233: <a href="urls.html#absolute-url">absolute URL</a> that would have resulted from <a href="urls.html#resolve-a-url" title="resolve a url">resolving</a> the <a href="urls.html#url">URL</a>
3234: specified by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
3235: attribute's value relative to the <a href="#media-element">media element</a> when
3236: the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was last
3237: changed.</p>
3238: </li><li><p>⌛ If <var title="">absolute URL</var> was obtained
3239: successfully, set the <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code> attribute to <var title="">absolute URL</var>.</p></li>
3240:
3241: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3242: remaining steps asynchronously.</p></li>
3243:
3244: <li><p>If <var title="">absolute URL</var> was obtained
3245: successfully, run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3246: algorithm</a> with <var title="">absolute URL</var>. If that
3247: algorithm returns without aborting <em>this</em> one, then the
3248: load failed.</p></li>
3249:
3250: <li>
3251:
3252: <p><i>Failed</i>: Reaching this step indicates that the media
3253: resource failed to load or that the given <a href="urls.html#url">URL</a> could
3254: not be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a>. In one
3255: atomic operation, run the following steps:</p>
3256:
3257: <ol><li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3258: attribute to a new <code><a href="#mediaerror">MediaError</a></code> object whose <code title="dom-MediaError-code"><a href="#dom-mediaerror-code">code</a></code> attribute is set to
3259: <code title="dom-MediaError-MEDIA_ERR_SRC_NOT_SUPPORTED"><a href="#dom-mediaerror-media_err_src_not_supported">MEDIA_ERR_SRC_NOT_SUPPORTED</a></code>.</p></li>
3260:
3261: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3262: text tracks</a>.</p></li>
3263:
3264: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3265: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3266: value.</p></li>
3267:
3268: </ol></li>
3269:
3270: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3271: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3272: at the <a href="#media-element">media element</a>.</p></li>
3273:
3274: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a>
1.101 mike 3275: to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying
1.47 mike 3276: the load event</a>.</p></li>
3277:
3278: <li><p>Abort these steps. Until the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code> method is invoked or the
3279: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute is changed, the
3280: element won't attempt to load another resource.</p></li>
3281:
3282:
3283: </ol><p>Otherwise, the <code><a href="#the-source-element">source</a></code> elements will be used; run
3284: these substeps:</p>
3285:
3286: <ol><li>
3287:
3288: <p>⌛ Let <var title="">pointer</var> be a position
3289: defined by two adjacent nodes in the <a href="#media-element">media
3290: element</a>'s child list, treating the start of the list
3291: (before the first child in the list, if any) and end of the list
3292: (after the last child in the list, if any) as nodes in their own
3293: right. One node is the node before <var title="">pointer</var>,
3294: and the other node is the node after <var title="">pointer</var>. Initially, let <var title="">pointer</var> be the position between the <var title="">candidate</var> node and the next node, if there are
3295: any, or the end of the list, if it is the last node.</p>
3296:
3297: <p>As nodes are inserted and removed into the <a href="#media-element">media
3298: element</a>, <var title="">pointer</var> must be updated as
3299: follows:</p>
3300:
3301: <dl><dt>If a new node is inserted between the two nodes that
3302: define <var title="">pointer</var></dt>
3303:
3304: <dd>Let <var title="">pointer</var> be the point between the
3305: node before <var title="">pointer</var> and the new node. In
3306: other words, insertions at <var title="">pointer</var> go after
3307: <var title="">pointer</var>.</dd>
3308:
3309: <dt>If the node before <var title="">pointer</var> is removed</dt>
3310:
3311: <dd>Let <var title="">pointer</var> be the point between the
3312: node after <var title="">pointer</var> and the node before the
3313: node after <var title="">pointer</var>. In other words, <var title="">pointer</var> doesn't move relative to the remaining
3314: nodes.</dd>
3315:
3316: <dt>If the node after <var title="">pointer</var> is removed</dt>
3317:
3318: <dd>Let <var title="">pointer</var> be the point between the
3319: node before <var title="">pointer</var> and the node after the
3320: node before <var title="">pointer</var>. Just as with the
3321: previous case, <var title="">pointer</var> doesn't move
3322: relative to the remaining nodes.</dd>
3323:
3324: </dl><p>Other changes don't affect <var title="">pointer</var>.</p>
3325:
3326: </li>
3327:
3328: <li><p>⌛ <i>Process candidate</i>: If <var title="">candidate</var> does not have a <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute, or if its <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute's value is the empty
3329: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3330: down to the <i title="">failed</i> step below.</p></li>
3331:
3332: <li><p>⌛ Let <var title="">absolute URL</var> be the
3333: <a href="urls.html#absolute-url">absolute URL</a> that would have resulted from <a href="urls.html#resolve-a-url" title="resolve a url">resolving</a> the <a href="urls.html#url">URL</a>
3334: specified by <var title="">candidate</var>'s <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute's value relative to
3335: the <var title="">candidate</var> when the <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute was last
3336: changed.</p>
3337: </li><li><p>⌛ If <var title="">absolute URL</var> was not
3338: obtained successfully, then end the <a href="webappapis.html#synchronous-section">synchronous
3339: section</a>, and jump down to the <i title="">failed</i> step
3340: below.</p></li>
3341:
3342: <li><p>⌛ If <var title="">candidate</var> has a <code title="attr-source-type"><a href="#attr-source-type">type</a></code> attribute whose value, when
3343: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3344: described by the <code title="">codecs</code> parameter, for
3345: types that define that parameter), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3346: the user agent knows it cannot render</a>, then end the
3347: <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
3348:
3349: <li><p>⌛ If <var title="">candidate</var> has a <code title="attr-source-media"><a href="#attr-source-media">media</a></code> attribute whose value does
3350: not <a href="common-microsyntaxes.html#matches-the-environment" title="matches the environment">match the
3351: environment</a>, then end the <a href="webappapis.html#synchronous-section">synchronous
3352: section</a>, and jump down to the <i title="">failed</i> step
3353: below.</p></li>
3354:
3355: <li><p>⌛ Set the <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code> attribute to <var title="">absolute URL</var>.</p></li>
3356:
3357: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3358: remaining steps asynchronously.</p></li>
3359:
3360: <li><p>Run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource
3361: fetch algorithm</a> with <var title="">absolute URL</var>. If
3362: that algorithm returns without aborting <em>this</em> one, then
3363: the load failed.</p></li>
3364:
3365: <li><p><i title="">Failed</i>: <a href="webappapis.html#queue-a-task">Queue a task</a> to
3366: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the <var title="">candidate</var> element, in the context of the <a href="fetching-resources.html#fetch" title="fetch">fetching process</a> that was used to try to
3367: obtain <var title="">candidate</var>'s corresponding <a href="#media-resource">media
3368: resource</a> in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3369: algorithm</a>.</p></li>
3370:
3371: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3372: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3373: steps of this algorithm until the algorithm says the
3374: <a href="webappapis.html#synchronous-section">synchronous section</a> has ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous sections</a> are
3375: marked with ⌛.)</p></li>
3376:
3377: <li><p>⌛ <a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's
3378: media-resource-specific text tracks</a>.</p></li>
3379:
3380: <li><p>⌛ <i title="">Find next candidate</i>: Let <var title="">candidate</var> be null.</p></li>
3381:
3382: <li><p>⌛ <i title="">Search loop</i>: If the node after
3383: <var title="">pointer</var> is the end of the list, then jump to
3384: the <i title="">waiting</i> step below.</p></li>
3385:
3386: <li><p>⌛ If the node after <var title="">pointer</var> is
3387: a <code><a href="#the-source-element">source</a></code> element, let <var title="">candidate</var>
3388: be that element.</p></li>
3389:
3390: <li><p>⌛ Advance <var title="">pointer</var> so that the
3391: node before <var title="">pointer</var> is now the node that was
3392: after <var title="">pointer</var>, and the node after <var title="">pointer</var> is the node after the node that used to be
3393: after <var title="">pointer</var>, if any.</p></li>
3394:
3395: <li><p>⌛ If <var title="">candidate</var> is null, jump
3396: back to the <i title="">search loop</i> step. Otherwise, jump
3397: back to the <i title="">process candidate</i> step.</p></li>
3398:
3399: <li><p>⌛ <i title="">Waiting</i>: Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3400: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3401: value.</p></li>
3402:
3403: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3404: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3405: event">delaying the load event</a>.</p></li>
3406:
3407: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3408: remaining steps asynchronously.</p></li>
3409:
3410: <li><p>Wait until the node after <var title="">pointer</var> is a
3411: node other than the end of the list. (This step might wait
3412: forever.)</p></li>
3413:
3414: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3415: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3416: steps of this algorithm until the algorithm says the
3417: <a href="webappapis.html#synchronous-section">synchronous section</a> has ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous sections</a> are
3418: marked with ⌛.)</p></li>
3419:
3420: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3421: flag</a> back to true (this <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3422: event">delays the load event</a> again, in case it hasn't been
3423: fired yet).</p>
3424:
3425: </li><li><p>⌛ Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> back to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3426:
3427: <li><p>⌛ Jump back to the <i title="">find next
3428: candidate</i> step above.</p></li>
3429:
3430: </ol></li>
3431:
3432: </ol><p>The <dfn id="concept-media-load-resource" title="concept-media-load-resource">resource fetch
3433: algorithm</dfn> for a <a href="#media-element">media element</a> and a given
3434: <a href="urls.html#absolute-url">absolute URL</a> is as follows:</p>
3435:
3436: <ol><li><p>Let the <var title="">current media resource</var> be the
3437: resource given by the <a href="urls.html#absolute-url">absolute URL</a> passed to this
3438: algorithm. This is now the element's <a href="#media-resource">media
3439: resource</a>.</p></li>
3440:
1.84 mike 3441: <li><p>Optionally, run the following substeps. This is the expected
3442: behavior if the user agent intends to not attempt to fetch the
3443: resource until the use requests it explicitly (e.g. as a way to
3444: implement the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>
3445: attribute's <code title="attr-media-preload-none"><a href="#attr-media-preload-none">none</a></code>
3446: keyword).</p>
3447:
3448: <ol><li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>.</p></li>
3449:
3450: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3451: event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the
3452: element.</p></li>
3453:
1.109 mike 3454: <li><p>Wait for the task to be run.</p></li>
3455:
1.84 mike 3456: <li><p>Wait for an implementation-defined event (e.g. the user
3457: requesting that the media element begin playback).</p></li>
3458:
3459: <li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3460:
3461: </ol></li>
3462:
1.47 mike 3463: <li>
3464:
1.61 mike 3465: <p>Perform a <a href="fetching-resources.html#potentially-cors-enabled-fetch">potentially CORS-enabled fetch</a> of the
3466: <var title="">current media resource</var>'s <a href="urls.html#absolute-url">absolute
3467: URL</a>, with the <i>mode</i> being the state of the
3468: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
1.128 mike 3469: attribute, the <i title="">origin</i> being the <a href="origin-0.html#origin">origin</a> of the
1.61 mike 3470: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
3471: <i>default origin behaviour</i> set to <i>taint</i>.</p>
3472:
3473: <p>The resource obtained in this fashion, if any, contains the
3474: <a href="#media-data">media data</a>. It can be <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>
3475: or <a href="fetching-resources.html#cors-cross-origin">CORS-cross-origin</a>; this affects whether subtitles
3476: referenced in the <a href="#media-data">media data</a> are exposed in the API
3477: and, for <code><a href="#the-video-element">video</a></code> elements, whether a
3478: <code><a href="the-canvas-element.html#the-canvas-element">canvas</a></code> gets tainted when the video is drawn on
3479: it.</p>
3480:
1.109 mike 3481: <p>While the load is not suspended (see below), every 350ms
3482: (±200ms) or for every byte received, whichever is
3483: <em>least</em> frequent, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
3484: simple event</a> named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the element.</p>
1.47 mike 3485:
3486: <p>The <dfn id="stall-timeout">stall timeout</dfn> is a user-agent defined length of
3487: time, which should be about three seconds. When a <a href="#media-element">media
3488: element</a> that is actively attempting to obtain <a href="#media-data">media
3489: data</a> has failed to receive any data for a duration equal to
3490: the <a href="#stall-timeout">stall timeout</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a
3491: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-stalled"><a href="#event-media-stalled">stalled</a></code> at the element.</p>
3492:
3493: <p>User agents may allow users to selectively block or slow
3494: <a href="#media-data">media data</a> downloads. When a <a href="#media-element">media
3495: element</a>'s download has been blocked altogether, the user
3496: agent must act as if it was stalled (as opposed to acting as if
3497: the connection was closed). The rate of the download may also be
3498: throttled automatically by the user agent, e.g. to balance the
3499: download with other connections sharing the same bandwidth.</p>
3500:
1.109 mike 3501: <p id="resourceSuspend">User agents may decide to not download
3502: more content at any time, e.g. after buffering five minutes of a
3503: one hour media resource, while waiting for the user to decide
3504: whether to play the resource or not, or while waiting for user
3505: input in an interactive resource. When a <a href="#media-element">media
3506: element</a>'s download has been suspended, the user agent must
3507: <a href="webappapis.html#queue-a-task">queue a task</a> to set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> and <a href="webappapis.html#fire-a-simple-event">fire
3508: a simple event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the element. If and
3509: when downloading of the resource resumes, the user agent must
3510: <a href="webappapis.html#queue-a-task">queue a task</a> to set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>. Between
3511: the queuing of these tasks, the load is suspended (so <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> events don't fire, as
3512: described above).</p>
1.47 mike 3513:
3514: <p class="note">The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute provides a
3515: hint regarding how much buffering the author thinks is advisable,
3516: even in the absence of the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute.</p>
3517:
3518: <p>When a user agent decides to completely stall a download,
3519: e.g. if it is waiting until the user starts playback before
3520: downloading any further content, the element's
3521: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> must be set to
1.101 mike 3522: false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the
1.47 mike 3523: load event</a>.</p>
3524:
3525: <p>The user agent may use whatever means necessary to fetch the
3526: resource (within the constraints put forward by this and other
3527: specifications); for example, reconnecting to the server in the
3528: face of network errors, using HTTP range retrieval requests, or
3529: switching to a streaming protocol. The user agent must consider a
3530: resource erroneous only if it has given up trying to fetch it.</p>
3531:
3532: <p>The <a href="webappapis.html#networking-task-source">networking task source</a> <a href="webappapis.html#concept-task" title="concept-task">tasks</a> to process the data as it is
3533: being fetched must, when appropriate, include the relevant
3534: substeps from the following list:</p>
3535:
3536: <dl class="switch"><dt>If the <a href="#media-data">media data</a> cannot be fetched at all, due
3537: to network errors, causing the user agent to give up trying to
3538: fetch the resource</dt>
3539:
3540: <dt>If the <a href="#media-resource">media resource</a> is found to have <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a> that, when
3541: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3542: described by the <code title="">codecs</code> parameter, if the
3543: parameter is defined for that type), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3544: the user agent knows it cannot render</a> (even if the actual
3545: <a href="#media-data">media data</a> is in a supported format)</dt>
3546:
3547: <dt>If the <a href="#media-data">media data</a> can be fetched but is found by
3548: inspection to be in an unsupported format, or can otherwise not
3549: be rendered at all</dt>
3550:
3551: <dd>
3552:
3553: <p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in
3554: other protocols), and other fatal network errors that occur
3555: before the user agent has established whether the <var title="">current media resource</var> is usable, as well as
3556: the file using an unsupported container format, or using
3557: unsupported codecs for all the data, must cause the user agent
3558: to execute the following steps:</p>
3559:
3560: <ol><li><p>The user agent should cancel the fetching
3561: process.</p></li>
3562:
3563: <li><p>Abort this subalgorithm, returning to the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3564: algorithm</a>.</p>
3565:
3566: </li></ol></dd>
3567:
3568:
3569:
3570:
3571:
1.122 mike 3572: <dt id="found-another-audio-track">If the <a href="#media-resource">media
3573: resource</a> is found to have an audio track</dt>
3574:
3575: <dd>
3576:
1.142 mike 3577: <ol><li><p>Create an <code><a href="#audiotrack">AudioTrack</a></code> object to represent the
1.122 mike 3578: audio track.</p></li>
3579:
3580: <li><p>Update the <a href="#media-element">media element</a>'s <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> attribute's
3581: <code><a href="#audiotracklist">AudioTrackList</a></code> object with the new
3582: <code><a href="#audiotrack">AudioTrack</a></code> object.</p></li>
3583:
3584: <li><p>Fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and
3585: is not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
3586: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized
3587: to the new <code><a href="#audiotrack">AudioTrack</a></code> object, at this
3588: <code><a href="#audiotracklist">AudioTrackList</a></code> object.</p></li>
3589:
3590: </ol></dd>
3591:
3592:
3593: <dt id="found-another-video-track">If the <a href="#media-resource">media
3594: resource</a> is found to have a video track</dt>
3595:
3596: <dd>
3597:
3598: <ol><li><p>Create a <code><a href="#videotrack">VideoTrack</a></code> object to represent the
3599: video track.</p></li>
3600:
3601: <li><p>Update the <a href="#media-element">media element</a>'s <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attribute's
3602: <code><a href="#videotracklist">VideoTrackList</a></code> object with the new
3603: <code><a href="#videotrack">VideoTrack</a></code> object.</p></li>
3604:
3605: <li><p>Fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and
3606: is not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
3607: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized
3608: to the new <code><a href="#videotrack">VideoTrack</a></code> object, at this
3609: <code><a href="#videotracklist">VideoTrackList</a></code> object.</p></li>
3610:
3611: </ol></dd>
3612:
3613:
1.47 mike 3614: <dt id="getting-media-metadata">Once enough of the <a href="#media-data">media
3615: data</a> has been fetched to determine the duration of the
1.139 mike 3616: <a href="#media-resource">media resource</a>, its dimensions, and other
3617: metadata</dt>
1.47 mike 3618:
3619: <dd>
3620:
3621: <p>This indicates that the resource is usable. The user agent
3622: must follow these substeps:</p>
3623:
3624: <ol><li>
3625:
3626: <p><a href="#defineTimeline">Establish the media timeline</a> for the purposes
3627: of the <a href="#current-playback-position">current playback position</a>, the
3628: <a href="#earliest-possible-position">earliest possible position</a>, and the <a href="#initial-playback-position">initial
3629: playback position</a>, based on the <a href="#media-data">media
3630: data</a>.</p>
3631:
3632: </li>
3633:
3634: <li>
3635:
3636: <p>Update the <a href="#timeline-offset">timeline offset</a> to the date and
3637: time that corresponds to the zero time in the <a href="#media-timeline">media
3638: timeline</a> established in the previous step, if any. If
3639: no explicit time and date is given by the <a href="#media-resource">media
3640: resource</a>, the <a href="#timeline-offset">timeline offset</a> must be set
3641: to Not-a-Number (NaN).</p>
3642:
3643: </li>
3644:
1.107 mike 3645: <li><p>Set the <a href="#current-playback-position">current playback position</a> and the
3646: <a href="#official-playback-position">official playback position</a> to the <a href="#earliest-possible-position">earliest
3647: possible position</a>.</p></li>
1.47 mike 3648:
3649: <li>
3650:
3651: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3652: attribute with the time of the last frame of the resource, if
3653: known, on the <a href="#media-timeline">media timeline</a> established above.
3654: If it is not known (e.g. a stream that is in principle
3655: infinite), update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute to the
3656: value positive Infinity.</p>
3657:
3658: <p class="note">The user agent <a href="#durationChange">will</a> <a href="webappapis.html#queue-a-task">queue a task</a> to
3659: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
3660: element at this point.</p>
3661:
3662: </li>
3663:
3664: <li><p>For <code><a href="#the-video-element">video</a></code> elements, set the <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code> and <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code>
3665: attributes.</p></li>
3666:
3667: <li>
3668:
3669: <p>Set the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to
3670: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>.</p>
3671:
3672: <p class="note">A <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> DOM
3673: event <a href="#fire-loadedmetadata">will be fired</a> as part
3674: of setting the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to a
3675: new value.</p>
3676:
3677:
3678:
3679: </li>
3680:
3681: <li><p>Let <var title="">jumped</var> be false.</p></li>
3682:
1.116 mike 3683: <li><p>If the <a href="#media-element">media element</a>'s <a href="#default-playback-start-position">default playback
3684: start position</a> is greater than zero, then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to that time, and let <var title="">jumped</var> be true.</p></li>
3685:
3686: <li><p>Let the <a href="#media-element">media element</a>'s <a href="#default-playback-start-position">default playback
3687: start position</a> be zero.</p></li>
3688:
1.47 mike 3689: <li>
3690:
3691: <p>If either the <a href="#media-resource">media resource</a> or the address of
3692: the <var title="">current media resource</var> indicate a
3693: particular start time, then set the <a href="#initial-playback-position">initial playback
1.116 mike 3694: position</a> to that time and, if <var title="">jumped</var> is still false, <a href="#dom-media-seek" title="dom-media-seek">seek</a> to that time and let <var title="">jumped</var> be true.</p>
1.47 mike 3695:
3696: <p class="example">For example, with media formats that
3697: support the <cite>Media Fragments URI</cite> fragment
3698: identifier syntax, the fragment identifier can be used to
1.101 mike 3699: indicate a start position. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 3700:
3701: </li>
3702:
1.74 mike 3703: <li>
3704:
3705: <p>If either the <a href="#media-resource">media resource</a> or the address of
3706: the <var title="">current media resource</var> indicate a
3707: particular set of audio or video tracks to enable, then the
3708: selected audio tracks must be enabled in the element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> object, and,
3709: of the selected video tracks, the one that is listed first in
3710: the element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> object must
3711: be selected.</p>
3712:
3713: </li>
1.47 mike 3714:
3715: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
3716: media controller</a>, then: if <var title="">jumped</var> is
3717: true and the <a href="#initial-playback-position">initial playback position</a>, relative
3718: to the <a href="#current-media-controller">current media controller</a>'s timeline, is
3719: greater than the <a href="#current-media-controller">current media controller</a>'s
3720: <a href="#media-controller-position">media controller position</a>, then <a href="#seek-the-media-controller">seek the
3721: media controller</a> to the <a href="#media-element">media element</a>'s
3722: <a href="#initial-playback-position">initial playback position</a>, relative to the
3723: <a href="#current-media-controller">current media controller</a>'s timeline; otherwise,
3724: <a href="#dom-media-seek" title="dom-media-seek">seek</a> the <a href="#media-element">media
3725: element</a> to the <a href="#media-controller-position">media controller position</a>,
1.107 mike 3726: relative to the <a href="#media-element">media element</a>'s timeline.</p></li>
3727:
1.116 mike 3728: </ol><p>Once the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
3729: reaches <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
3730: <a href="#fire-loadeddata">after the <code title="event-media-loadeddata">loadeddata</code> event has been
3731: fired</a>, set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3732: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3733: event">delaying the load event</a>.</p>
3734:
3735: <p class="note">A user agent that is attempting to reduce
3736: network usage while still fetching the metadata for each
3737: <a href="#media-resource">media resource</a> would also stop buffering at this
3738: point, following <a href="#resourceSuspend">the rules
3739: described previously</a>, which involve the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute
3740: switching to the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> value and a
3741: <code title="event-suspend">suspend</code> event firing.</p>
1.47 mike 3742:
1.116 mike 3743: <p class="note">The user agent is <em>required</em> to
1.47 mike 3744: determine the duration of the <a href="#media-resource">media resource</a> and
3745: go through this step before playing.</p>
3746: </dd>
3747:
3748:
3749: <dt>Once the entire <a href="#media-resource">media resource</a> has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (but potentially before any of it
3750: has been decoded)</dt>
3751:
3752: <dd>
3753:
1.116 mike 3754: <p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the <a href="#media-element">media
3755: element</a>.</p>
1.47 mike 3756:
1.116 mike 3757: <p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> and
1.109 mike 3758: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the <a href="#media-element">media
1.108 mike 3759: element</a>.</p>
3760:
1.109 mike 3761: <p>If the user agent ever discards any <a href="#media-data">media data</a>
3762: and then needs to resume the network activity to obtain it
1.116 mike 3763: again, then it must <a href="webappapis.html#queue-a-task">queue a task</a> to set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p>
1.109 mike 3764:
3765: <p class="note">If the user agent can keep the <a href="#media-resource">media
3766: resource</a> loaded, then the algorithm will continue to its
3767: final step below, which aborts the algorithm.</p>
1.47 mike 3768: </dd>
3769:
3770:
1.116 mike 3771: <dt>If the connection is interrupted after some <a href="#media-data">media
3772: data</a> has been received, causing the user agent to give up
3773: trying to fetch the resource</dt>
1.47 mike 3774:
3775: <dd>
3776:
3777: <p>Fatal network errors that occur after the user agent has
3778: established whether the <var title="">current media
1.84 mike 3779: resource</var> is usable (i.e. once the <a href="#media-element">media
3780: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is no
3781: longer <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>)
3782: must cause the user agent to execute the following steps:</p>
1.47 mike 3783:
3784: <ol><li><p>The user agent should cancel the fetching
3785: process.</p></li>
3786:
3787: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3788: attribute to a new <code><a href="#mediaerror">MediaError</a></code> object whose <code title="dom-MediaError-code"><a href="#dom-mediaerror-code">code</a></code> attribute is set to
3789: <code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code>.</p></li>
3790:
1.116 mike 3791: <li><p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code> at the <a href="#media-element">media
3792: element</a>.</p></li>
1.47 mike 3793:
1.84 mike 3794: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3795: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3796: value.</p></li>
3797:
3798: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3799: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3800: event">delaying the load event</a>.</p></li>
3801:
3802: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3803: algorithm</a>.</p></li>
3804:
3805: </ol></dd>
3806:
3807:
3808: <dt id="fatal-decode-error">If the <a href="#media-data">media data</a> is
3809: corrupted</dt>
3810:
3811: <dd>
3812:
3813: <p>Fatal errors in decoding the <a href="#media-data">media data</a> that
3814: occur after the user agent has established whether the <var title="">current media resource</var> is usable must cause the
3815: user agent to execute the following steps:</p>
3816:
3817: <ol><li><p>The user agent should cancel the fetching
3818: process.</p></li>
3819:
3820: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3821: attribute to a new <code><a href="#mediaerror">MediaError</a></code> object whose <code title="dom-MediaError-code"><a href="#dom-mediaerror-code">code</a></code> attribute is set to
3822: <code title="dom-MediaError-MEDIA_ERR_DECODE"><a href="#dom-mediaerror-media_err_decode">MEDIA_ERR_DECODE</a></code>.</p></li>
3823:
1.116 mike 3824: <li><p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code> at the <a href="#media-element">media
3825: element</a>.</p></li>
1.47 mike 3826:
3827: <li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute has a
3828: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3829: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3830: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
1.116 mike 3831: value and <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the element.
3832: Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3833: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3834: value.</p></li>
3835:
3836: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3837: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3838: event">delaying the load event</a>.</p></li>
3839:
3840: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3841: algorithm</a>.</p></li>
3842:
3843: </ol></dd>
3844:
3845:
3846: <dt>If the <a href="#media-data">media data</a> fetching process is aborted by
3847: the user</dt>
3848:
3849: <dd>
3850:
3851: <p>The fetching process is aborted by the user, e.g. because the
3852: user navigated the browsing context to another page, the user
3853: agent must execute the following steps. These steps are not
3854: followed if the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code>
3855: method itself is invoked while these steps are running, as the
3856: steps above handle that particular kind of abort.</p>
3857:
3858: <ol><li><p>The user agent should cancel the fetching
3859: process.</p></li>
3860:
3861: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3862: attribute to a new <code><a href="#mediaerror">MediaError</a></code> object whose <code title="dom-MediaError-code"><a href="#dom-mediaerror-code">code</a></code> attribute is set to
3863: <code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.</p></li>
3864:
1.116 mike 3865: <li><p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code> at the <a href="#media-element">media
3866: element</a>.</p></li>
1.47 mike 3867:
3868: <li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute has a
3869: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3870: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3871: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
1.116 mike 3872: value and <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the element.
3873: Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3874: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3875: value.</p></li>
3876:
3877: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3878: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3879: event">delaying the load event</a>.</p></li>
3880:
3881: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3882: algorithm</a>.</p></li>
3883:
3884: </ol></dd>
3885:
3886:
3887: <dt id="non-fatal-media-error">If the <a href="#media-data">media data</a> can
3888: be fetched but has non-fatal errors or uses, in part, codecs that
3889: are unsupported, preventing the user agent from rendering the
3890: content completely correctly but not preventing playback
3891: altogether</dt>
3892:
3893: <dd>
3894:
3895: <p>The server returning data that is partially usable but cannot
3896: be optimally rendered must cause the user agent to render just
3897: the bits it can handle, and ignore the rest.</p>
3898:
3899:
3900:
3901: </dd>
3902:
3903:
1.116 mike 3904: <dt id="found-a-media-resource-specific-timed-track">If the
3905: <a href="#media-resource">media resource</a> is found to declare a
3906: <a href="#media-resource-specific-text-track">media-resource-specific text track</a> that the user
3907: agent supports</dt>
1.47 mike 3908:
3909: <dd>
3910:
1.61 mike 3911: <p>If the <a href="#media-data">media data</a> is
1.116 mike 3912: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>, run the <a href="#steps-to-expose-a-media-resource-specific-text-track">steps to expose a
3913: media-resource-specific text track</a> with the relevant
3914: data.</p>
1.61 mike 3915:
3916: <p class="note">Cross-origin videos do not expose their
3917: subtitles, since that would allow attacks such as hostile sites
3918: reading subtitles from confidential videos on a user's
3919: intranet.</p>
1.47 mike 3920:
3921: </dd>
3922:
3923: </dl><p>When the <a href="webappapis.html#networking-task-source">networking task source</a> has <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> the last <a href="webappapis.html#concept-task" title="concept-task">task</a> as part of <a href="fetching-resources.html#fetch" title="fetch">fetching</a> the <a href="#media-resource">media resource</a>
3924: (i.e. once the download has completed), if the fetching process
3925: completes without errors, including decoding the media data, and
3926: if all of the data is available to the user agent without network
3927: access, then, the user agent must move on to the next step. This
3928: might never happen, e.g. when streaming an infinite resource such
3929: as Web radio, or if the resource is longer than the user agent's
3930: ability to cache data.</p>
3931:
3932: <p>While the user agent might still need network access to obtain
3933: parts of the <a href="#media-resource">media resource</a>, the user agent must
3934: remain on this step.</p>
3935:
3936: <p class="example">For example, if the user agent has discarded
3937: the first half of a video, the user agent will remain at this step
3938: even once the <a href="#ended-playback" title="ended playback">playback has
3939: ended</a>, because there is always the chance the user will
3940: seek back to the start. In fact, in this situation, once <a href="#ended-playback" title="ended playback">playback has ended</a>, the user agent
1.116 mike 3941: will end up firing a <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> event, as described
1.47 mike 3942: earlier.</p>
3943:
3944: </li>
3945:
1.109 mike 3946:
1.47 mike 3947: <li><p>If the user agent ever reaches this step (which can only
3948: happen if the entire resource gets loaded and kept available):
3949: abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3950: algorithm</a>.</p></li>
3951:
3952: </ol></div><hr><p>The <dfn id="attr-media-preload" title="attr-media-preload"><code>preload</code></dfn>
3953: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following table
3954: lists the keywords and states for the attribute — the keywords
3955: in the left column map to the states in the cell in the second
3956: column on the same row as the keyword.</p><table><thead><tr><th> Keyword
3957: </th><th> State
3958: </th><th> Brief description
3959: </th></tr></thead><tbody><tr><td><dfn id="attr-media-preload-none" title="attr-media-preload-none"><code>none</code></dfn>
3960: </td><td><dfn id="attr-media-preload-none-state" title="attr-media-preload-none-state">None</dfn>
3961: </td><td>Hints to the user agent that either the author does not expect the user to need the media resource, or that the server wants to minimise unnecessary traffic.
3962: </td></tr><tr><td><dfn id="attr-media-preload-metadata" title="attr-media-preload-metadata"><code>metadata</code></dfn>
3963: </td><td><dfn id="attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</dfn>
1.62 mike 3964: </td><td>Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, first frame, track list, duration, etc) is reasonable. If the user agent precisely fetches no more than the metadata, then the <a href="#media-element">media element</a> will end up with its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute set to <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>; typically though, some frames will be obtained as well and it will probably be <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.
1.47 mike 3965: </td></tr><tr><td><dfn id="attr-media-preload-auto" title="attr-media-preload-auto"><code>auto</code></dfn>
3966: </td><td><dfn id="attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</dfn>
3967: </td><td>Hints to the user agent that the user agent can put the user's needs first without risk to the server, up to and including optimistically downloading the entire resource.
3968: </td></tr></tbody></table><p>The empty string is also a valid keyword, and maps to the <a href="#attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</a> state. The
3969: attribute's <i>missing value default</i> is user-agent defined,
3970: though the <a href="#attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</a> state is
3971: suggested as a compromise between reducing server load and providing
3972: an optimal user experience.</p><div class="impl">
3973:
3974: <p>The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute is
3975: intended to provide a hint to the user agent about what the author
3976: thinks will lead to the best user experience. The attribute may be
3977: ignored altogether, for example based on explicit user preferences
3978: or based on the available connectivity.</p>
3979:
3980: <p>The <dfn id="dom-media-preload" title="dom-media-preload"><code>preload</code></dfn> IDL
3981: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
3982: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
3983:
3984: </div><p class="note">The <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute can override
3985: the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute (since
3986: if the media plays, it naturally has to buffer first, regardless of
3987: the hint given by the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute). Including
3988: both is not an error, however.</p><hr><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code></dt>
3989:
3990: <dd>
3991:
3992: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
3993: ranges of the <a href="#media-resource">media resource</a> that the user agent has
3994: buffered.</p>
3995:
3996: </dd>
3997:
3998: </dl><div class="impl">
3999:
4000: <p>The <dfn id="dom-media-buffered" title="dom-media-buffered"><code>buffered</code></dfn>
4001: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4002: <code>TimeRanges</code> object</a> that represents the ranges of
4003: the <a href="#media-resource">media resource</a>, if any, that the user agent has
4004: buffered, at the time the attribute is evaluated. Users agents must
4005: accurately determine the ranges available, even for media streams
4006: where this can only be determined by tedious inspection.</p>
4007:
4008: <p class="note">Typically this will be a single range anchored at
4009: the zero point, but if, e.g. the user agent uses HTTP range requests
4010: in response to seeking, then there could be multiple ranges.</p>
4011:
4012: <p>User agents may discard previously buffered data.</p>
4013:
4014: <p class="note">Thus, a time position included within a range of the
4015: objects return by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code> attribute at one time can
4016: end up being not included in the range(s) of objects returned by the
4017: same attribute at later times.</p>
4018:
4019: </div><h5 id="offsets-into-the-media-resource"><span class="secno">4.8.10.6 </span>Offsets into the media resource</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code></dt>
4020:
4021: <dd>
4022:
4023: <p>Returns the length of the <a href="#media-resource">media resource</a>, in
4024: seconds, assuming that the start of the <a href="#media-resource">media
4025: resource</a> is at time zero.</p>
4026:
4027: <p>Returns NaN if the duration isn't available.</p><p>
4028:
4029: </p><p>Returns Infinity for unbounded streams.</p>
4030:
4031: </dd>
4032:
4033: <dt><var title="">media</var> . <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
4034:
4035: <dd>
4036:
1.107 mike 4037: <p>Returns the <a href="#official-playback-position">official playback position</a>, in seconds.</p>
1.47 mike 4038:
4039: <p>Can be set, to seek to the given time.</p><p>
4040:
1.119 mike 4041: </p><p>Will throw an <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception if there
1.47 mike 4042: is no selected <a href="#media-resource">media resource</a>
1.71 mike 4043: or if there is a <a href="#current-media-controller">current media controller</a>.</p>
1.47 mike 4044:
4045: </dd>
4046:
4047: <dt><var title="">media</var> . <code title="dom-media-initialTime"><a href="#dom-media-initialtime">initialTime</a></code></dt>
4048:
4049: <dd>
4050:
4051: <p>Returns the <a href="#initial-playback-position">initial playback position</a>, that is, time
4052: to which the <a href="#media-resource">media resource</a> was automatically seeked
4053: when it was loaded. Returns zero if the <a href="#initial-playback-position">initial playback
4054: position</a> is still unknown.</p>
4055:
4056: </dd>
4057:
4058: </dl><div class="impl">
4059:
4060: <p>A <a href="#media-resource">media resource</a> has a <dfn id="media-timeline">media timeline</dfn>
4061: that maps times (in seconds) to positions in the <a href="#media-resource">media
4062: resource</a>. The origin of a timeline is its earliest defined
4063: position. The duration of a timeline is its last defined
4064: position.</p>
4065:
4066: <p><dfn id="defineTimeline" title="establish the media
4067: timeline">Establishing the media timeline</dfn>: If the <a href="#media-resource">media
4068: resource</a> somehow specifies an explicit timeline whose origin
4069: is not negative, then the <a href="#media-timeline">media timeline</a> should be that
4070: timeline. (Whether the <a href="#media-resource">media resource</a> can specify a
4071: timeline or not depends on the <a href="#media-resource" title="media resource">media
4072: resource's</a> format.) If the <a href="#media-resource">media resource</a>
4073: specifies an explicit start time <em>and date</em>, then that time
4074: and date should be considered the zero point in the <a href="#media-timeline">media
4075: timeline</a>; the <a href="#timeline-offset">timeline offset</a> will be the time
4076: and date, exposed using the <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
4077: attribute.</p>
4078:
4079: <p>If the <a href="#media-resource">media resource</a> has a discontinuous timeline,
4080: the user agent must extend the timeline used at the start of the
4081: resource across the entire resource, so that the <a href="#media-timeline">media
4082: timeline</a> of the <a href="#media-resource">media resource</a> increases
4083: linearly starting from the <a href="#earliest-possible-position">earliest possible position</a>
4084: (as defined below), even if the underlying <a href="#media-data">media data</a>
4085: has out-of-order or even overlapping time codes.</p>
4086:
4087: <p class="example">For example, if two clips have been concatenated
4088: into one video file, but the video format exposes the original times
4089: for the two clips, the video data might expose a timeline that goes,
4090: say, 00:15..00:29 and then 00:05..00:38. However, the user agent
4091: would not expose those times; it would instead expose the times as
4092: 00:15..00:29 and 00:29..01:02, as a single video.</p>
4093:
4094: <p>In the absence of an explicit timeline, the zero time on the
4095: <a href="#media-timeline">media timeline</a> should correspond to the first frame of
4096: the <a href="#media-resource">media resource</a>. For static audio and video files
4097: this is generally trivial. For streaming resources, if the user
4098: agent will be able to seek to an earlier point than the first frame
4099: originally provided by the server, then the zero time should
4100: correspond to the earliest seekable time of the <a href="#media-resource">media
4101: resource</a>; otherwise, it should correspond to the first frame
4102: received from the server (the point in the <a href="#media-resource">media
4103: resource</a> at which the user agent began receiving the
4104: stream).</p>
4105:
4106: <p class="example">Another example would be a stream that carries a
4107: video with several concatenated fragments, broadcast by a server
4108: that does not allow user agents to request specific times but
4109: instead just streams the video data in a predetermined order. If a
4110: user agent connects to this stream and receives fragments defined as
4111: covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
4112: UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
4113: expose this with a <a href="#media-timeline">media timeline</a> starting at 0s and
4114: extending to 3,600s (one hour). Assuming the streaming server
4115: disconnected at the end of the second clip, the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute would then
4116: return 3,600. The <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code> attribute
4117: would return a <code>Date</code> object with a time corresponding to
4118: 2010-03-20 23:15:00 UTC. However, if a different user agent
4119: connected five minutes later, <em>it</em> would (presumably) receive
4120: fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
4121: 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
4122: and would expose this with a <a href="#media-timeline">media timeline</a> starting at
4123: 0s and extending to 3,300s (fifty five minutes). In this case, the
4124: <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
4125: attribute would return a <code>Date</code> object with a time
4126: corresponding to 2010-03-20 23:20:00 UTC.</p>
4127:
4128: <p>In any case, the user agent must ensure that the <a href="#earliest-possible-position">earliest
4129: possible position</a> (as defined below) using the established
4130: <a href="#media-timeline">media timeline</a>, is greater than or equal to zero.</p>
4131:
4132: <p>The <a href="#media-timeline">media timeline</a> also has an associated clock.
4133: Which clock is used is user-agent defined, and may be <a href="#media-resource">media
4134: resource</a>-dependent, but it should approximate the user's wall
4135: clock.</p>
4136:
4137: <p class="note">All the <a href="#media-element" title="media element">media
4138: elements</a> that share <a href="#current-media-controller">current media controller</a> use
4139: the same clock for their <a href="#media-timeline">media timeline</a>.</p>
4140:
4141: <p><a href="#media-element" title="media element">Media elements</a> have a
4142: <dfn id="current-playback-position">current playback position</dfn>, which must initially (i.e. in
4143: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4144: <a href="#current-playback-position">current playback position</a> is a time on the <a href="#media-timeline">media
4145: timeline</a>.</p>
4146:
1.107 mike 4147: <p><a href="#media-element" title="media element">Media elements</a> also have an
4148: <dfn id="official-playback-position">official playback position</dfn>, which must initially be set
4149: to zero seconds. The <a href="#official-playback-position">official playback position</a> is an
4150: approximation of the <a href="#current-playback-position">current playback position</a>
4151: that is kept stable while scripts are running.</p>
4152:
1.116 mike 4153: <p><a href="#media-element" title="media element">Media elements</a> also have a
4154: <dfn id="default-playback-start-position">default playback start position</dfn>, which must initially be
4155: set to zero seconds. This time is used to allow the element to be
4156: seeked even before the media is loaded.</p>
4157:
1.47 mike 4158: <p>The <dfn id="dom-media-currenttime" title="dom-media-currentTime"><code>currentTime</code></dfn>
1.116 mike 4159: attribute must, on getting, return the <a href="#media-element">media element</a>'s
4160: <a href="#default-playback-start-position">default playback start position</a>, unless that is zero,
4161: in which case it must return the element's <a href="#official-playback-position">official playback
4162: position</a>. The returned value must be expressed in seconds. On
4163: setting, if the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
1.107 mike 4164: controller</a>, then the user agent must throw an
1.119 mike 4165: <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception; otherwise, if the
1.116 mike 4166: <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then it must set
4167: the <a href="#media-element">media element</a>'s <a href="#default-playback-start-position">default playback start
4168: position</a> to the new value; otherwise, it must set the
4169: <a href="#official-playback-position">official playback position</a> to the new value and then
4170: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the new value. The new
4171: value must be interpreted as being in seconds.</p>
1.47 mike 4172:
4173: <p><a href="#media-element" title="media element">Media elements</a> have an
4174: <dfn id="initial-playback-position">initial playback position</dfn>, which must initially (i.e. in
4175: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4176: <a href="#initial-playback-position">initial playback position</a> is updated when a <a href="#media-resource">media
4177: resource</a> is loaded. The <a href="#initial-playback-position">initial playback
4178: position</a> is a time on the <a href="#media-timeline">media timeline</a>.</p>
4179:
1.50 mike 4180: <p>The <dfn id="dom-media-initialtime" title="dom-media-initialTime"><code>initialTime</code></dfn>
1.47 mike 4181: attribute must, on getting, return the <a href="#initial-playback-position">initial playback
4182: position</a>, expressed in seconds.</p>
4183:
4184: <p>If the <a href="#media-resource">media resource</a> is a streaming resource, then
4185: the user agent might be unable to obtain certain parts of the
4186: resource after it has expired from its buffer. Similarly, some <a href="#media-resource" title="media resource">media resources</a> might have a
4187: <a href="#media-timeline">media timeline</a> that doesn't start at zero. The
4188: <dfn id="earliest-possible-position">earliest possible position</dfn> is the earliest position in
4189: the stream or resource that the user agent can ever obtain
4190: again. It is also a time on the <a href="#media-timeline">media timeline</a>.</p>
4191:
4192: <p class="note">The <a href="#earliest-possible-position">earliest possible position</a> is not
4193: explicitly exposed in the API; it corresponds to the start time of
4194: the first range in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute's
4195: <code><a href="#timeranges">TimeRanges</a></code> object, if any, or the <a href="#current-playback-position">current
4196: playback position</a> otherwise.</p>
4197:
4198: <p>When the <a href="#earliest-possible-position">earliest possible position</a> changes, then:
4199: if the <a href="#current-playback-position">current playback position</a> is before the
4200: <a href="#earliest-possible-position">earliest possible position</a>, the user agent must <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest possible
4201: position</a>; otherwise, if the user agent has not fired a <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> event at the
4202: element in the past 15 to 250ms and is not still running event
4203: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4204: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p>
4205:
4206: <p class="note">Because of the above requirement and the requirement
4207: in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
4208: algorithm</a> that kicks in <a href="#getting-media-metadata">when the metadata of the clip becomes
4209: known</a>, the <a href="#current-playback-position">current playback position</a> can never be
4210: less than the <a href="#earliest-possible-position">earliest possible position</a>.</p>
4211:
4212: <p>The <dfn id="dom-media-duration" title="dom-media-duration"><code>duration</code></dfn>
4213: attribute must return the time of the end of the <a href="#media-resource">media
4214: resource</a>, in seconds, on the <a href="#media-timeline">media timeline</a>. If
4215: no <a href="#media-data">media data</a> is available, then the attributes must
4216: return the Not-a-Number (NaN) value. If the <a href="#media-resource">media
1.62 mike 4217: resource</a> is not known to be bounded (e.g. streaming radio, or
4218: a live event with no announced end time), then the attribute must
4219: return the positive Infinity value.</p>
1.47 mike 4220:
4221: <p>The user agent must determine the duration of the <a href="#media-resource">media
4222: resource</a> before playing any part of the <a href="#media-data">media
4223: data</a> and before setting <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> to a value equal to
4224: or greater than <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, even if doing
4225: so requires fetching multiple parts of the resource.</p>
4226:
4227: <p id="durationChange">When the length of the <a href="#media-resource">media
4228: resource</a> changes to a known value (e.g. from being unknown to
4229: known, or from a previously established length to a new length) the
4230: user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4231: event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
4232: <a href="#media-element">media element</a>. (The event is not fired when the
1.63 mike 4233: duration is reset as part of loading a new media resource.) If the
4234: duration is changed such that the <a href="#current-playback-position">current playback
4235: position</a> ends up being greater than the time of the end of
4236: the <a href="#media-resource">media resource</a>, then the user agent must also <a href="#dom-media-seek" title="dom-media-seek">seek</a> the to the time of the end of the
4237: <a href="#media-resource">media resource</a>.</p>
1.47 mike 4238:
4239: <p class="example">If an "infinite" stream ends for some reason,
4240: then the duration would change from positive Infinity to the time of
4241: the last frame or sample in the stream, and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
4242: be fired. Similarly, if the user agent initially estimated the
4243: <a href="#media-resource">media resource</a>'s duration instead of determining it
4244: precisely, and later revises the estimate based on new information,
4245: then the duration would change and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
4246: be fired.</p>
4247:
4248: <p>Some video files also have an explicit date and time
4249: corresponding to the zero time in the <a href="#media-timeline">media timeline</a>,
4250: known as the <dfn id="timeline-offset">timeline offset</dfn>. Initially, the
4251: <a href="#timeline-offset">timeline offset</a> must be set to Not-a-Number (NaN).</p>
4252:
4253: <p>The <dfn id="dom-media-startoffsettime" title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
4254: attribute must return a new <code>Date</code> object representing
4255: the current <a href="#timeline-offset">timeline offset</a>.</p>
4256:
4257: </div><hr><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn>
4258: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that, if specified,
4259: indicates that the <a href="#media-element">media element</a> is to seek back to the
4260: start of the <a href="#media-resource">media resource</a> upon reaching the end.</p><p>The <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code> attribute has no
4261: effect while the element has a <a href="#current-media-controller">current media
4262: controller</a>.</p><div class="impl">
4263:
4264: <p>The <dfn id="dom-media-loop" title="dom-media-loop"><code>loop</code></dfn> IDL
4265: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4266: same name.</p>
4267:
1.65 mike 4268: </div><h5 id="ready-states"><span class="secno">4.8.10.7 </span>Ready states</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code></dt>
1.47 mike 4269:
4270: <dd>
4271:
4272: <p>Returns a value that expresses the current state of the element
4273: with respect to rendering the <a href="#current-playback-position">current playback
4274: position</a>, from the codes in the list below.</p>
4275:
4276: </dd>
4277:
4278: </dl><div class="impl">
4279:
4280: <p><a href="#media-element" title="media element">Media elements</a> have a
4281: <i>ready state</i>, which describes to what degree they are ready
4282: to be rendered at the <a href="#current-playback-position">current playback position</a>. The
4283: possible values are as follows; the ready state of a media element
4284: at any particular time is the greatest value describing the state of
4285: the element:</p>
4286:
4287: </div><dl><dt><dfn id="dom-media-have_nothing" title="dom-media-HAVE_NOTHING"><code>HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
4288:
4289: <dd>No information regarding the <a href="#media-resource">media resource</a> is
4290: available. No data for the <a href="#current-playback-position">current playback position</a>
4291: is available. <a href="#media-element" title="media element">Media elements</a>
4292: whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code>
4293: attribute are set to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> are always in
4294: the <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>
4295: state.</dd>
4296:
4297: <dt><dfn id="dom-media-have_metadata" title="dom-media-HAVE_METADATA"><code>HAVE_METADATA</code></dfn> (numeric value 1)</dt>
4298:
4299: <dd>Enough of the resource has been obtained that the duration of
4300: the resource is available. In the case of a <code><a href="#the-video-element">video</a></code>
4301: element, the dimensions of the video are also available. The API
1.119 mike 4302: will no longer throw an exception when seeking. No <a href="#media-data">media
1.47 mike 4303: data</a> is available for the immediate <a href="#current-playback-position">current playback
1.139 mike 4304: position</a>.</dd>
1.47 mike 4305:
4306: <dt><dfn id="dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA"><code>HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
4307:
4308: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4309: is available, but either not enough data is available that the user
4310: agent could successfully advance the <a href="#current-playback-position">current playback
4311: position</a> in the <a href="#direction-of-playback">direction of playback</a> at all
4312: without immediately reverting to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4313: there is no more data to obtain in the <a href="#direction-of-playback">direction of
4314: playback</a>. For example, in video this corresponds to the user
1.62 mike 4315: agent having data from the current frame, but not the next frame,
4316: when the <a href="#current-playback-position">current playback position</a> is at the end of
4317: the current frame; and to when <a href="#ended-playback" title="ended
4318: playback">playback has ended</a>.</dd>
1.47 mike 4319:
4320: <dt><dfn id="dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA"><code>HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
4321:
4322: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4323: is available, as well as enough data for the user agent to advance
4324: the <a href="#current-playback-position">current playback position</a> in the <a href="#direction-of-playback">direction
4325: of playback</a> at least a little without immediately reverting
4326: to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
1.139 mike 4327: state, and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>. For example, in
4328: video this corresponds to the user agent having data for at least
4329: the current frame and the next frame when the <a href="#current-playback-position">current
4330: playback position</a> is at the instant in time between the two
4331: frames, or to the user agent having the video data for the current
4332: frame and audio data to keep playing at least a little when the
4333: <a href="#current-playback-position">current playback position</a> is in the middle of a frame.
4334: The user agent cannot be in this state if <a href="#ended-playback" title="ended
4335: playback">playback has ended</a>, as the <a href="#current-playback-position">current playback
4336: position</a> can never advance in this case.</dd>
1.47 mike 4337:
4338: <dt><dfn id="dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA"><code>HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
4339:
4340: <dd>All the conditions described for the <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> state
4341: are met, and, in addition, the user agent estimates that data is
4342: being fetched at a rate where the <a href="#current-playback-position">current playback
4343: position</a>, if it were to advance at the <a href="#effective-playback-rate">effective
4344: playback rate</a>, would not overtake the available data before
4345: playback reaches the end of the <a href="#media-resource">media resource</a>.</dd>
4346:
1.62 mike 4347: </dl><p class="note">In practice, the difference between <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> is
4348: negligible. Really the only time the difference is relevant is when
4349: painting a <code><a href="#the-video-element">video</a></code> element onto a <code><a href="the-canvas-element.html#the-canvas-element">canvas</a></code>,
4350: where it distinguishes the case where something will be drawn (<code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or
4351: greater) from the case where nothing is drawn (<code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> or less).
4352: Similarly, the difference between <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> (only
4353: the current frame) and <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> (at least
4354: this frame and the next) can be negligible (in the extreme, only one
4355: frame). The only time that distinction really matters is when a page
4356: provides an interface for "frame-by-frame" navigation.</p><div class="impl">
1.47 mike 4357:
4358: <p>When the ready state of a <a href="#media-element">media element</a> whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> is not <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> changes, the
4359: user agent must follow the steps given below:</p>
4360:
4361: <ol><li>
4362:
4363: <p>Apply the first applicable set of substeps from the following
4364: list:</p>
4365:
4366:
4367: <dl class="switch"><dt>If the previous ready state was <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, and the new
4368: ready state is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code></dt>
4369:
4370: <dd id="fire-loadedmetadata">
4371:
4372: <p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4373: named <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> at the
4374: element.</p>
4375:
4376: <p class="note">Before this task is run, as part of the event
4377: loop mechanism, the rendering will have been updated to resize
4378: the <code><a href="#the-video-element">video</a></code> element if appropriate.</p>
4379:
4380: </dd>
4381:
4382:
4383:
4384: <dt id="handling-first-frame-available">If the previous ready state
4385: was <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and
4386: the new ready state is <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or
4387: greater</dt>
4388:
4389: <dd>
4390:
4391: <p id="fire-loadeddata">If this is the first time this occurs for
4392: this <a href="#media-element">media element</a> since the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code> algorithm was last invoked,
4393: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
4394: simple event</a> named <code title="event-media-loadeddata"><a href="#event-media-loadeddata">loadeddata</a></code> at the element.</p>
4395:
4396: <p>If the new ready state is <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4397: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>,
4398: then the relevant steps below must then be run also.</p>
4399:
4400: </dd>
4401:
4402:
4403: <dt>If the previous ready state was <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or more,
4404: and the new ready state is <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or
4405: less</dt>
4406:
4407: <dd>
4408:
4409: <p id="fire-waiting-when-waiting">If the <a href="#media-element">media
4410: element</a> was <a href="#potentially-playing">potentially playing</a> before its
4411: <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
4412: changed to a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>, and
4413: the element has not <a href="#ended-playback">ended playback</a>, and playback
4414: has not <a href="#stopped-due-to-errors">stopped due to errors</a>, and playback has not
4415: <a href="#paused-for-user-interaction">paused for user interaction</a>, the user agent must
4416: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4417: named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at
4418: the element, and <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
4419: simple event</a> named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the element.</p>
4420:
4421: </dd>
4422:
4423:
4424: <dt>If the previous ready state was <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or
4425: less, and the new ready state is <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code></dt>
4426:
4427: <dd>
4428:
4429: <p>The user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
4430: simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>.</p>
4431:
4432: <p>If the element's <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4433: attribute is false, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
4434: to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4435:
4436: </dd>
4437:
4438:
4439: <dt>If the new ready state is <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code></dt>
4440:
4441: <dd>
4442:
4443: <p>If the previous ready state was <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or
4444: less, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
4445: a simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>, and, if the element's
4446: <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false,
4447: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4448: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4449:
4450: <p>If the <a href="#autoplaying-flag">autoplaying flag</a> is true, and the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is true, and the
4451: <a href="#media-element">media element</a> has an <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute specified,
4452: and the <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s
4453: <a href="browsers.html#browsing-context">browsing context</a> did not have the <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed
4454: automatic features browsing context flag</a> set when the
4455: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent may also
4456: set the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute to
4457: false, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4458: event</a> named <code title="event-media-play"><a href="#event-media-play">play</a></code>, and
4459: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4460: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4461:
4462: <p class="note">User agents do not need to support autoplay,
4463: and it is suggested that user agents honor user preferences on the
4464: matter. Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
4465: using script to force the video to play, so as to allow the user
4466: to override the behavior if so desired.</p>
4467:
4468: <p>In any case, the user agent must finally <a href="webappapis.html#queue-a-task">queue a
4469: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-canplaythrough"><a href="#event-media-canplaythrough">canplaythrough</a></code>.</p>
4470:
4471: </dd>
4472:
4473: </dl></li>
4474:
4475: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4476: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4477: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4478: controller</a>.</p></li>
4479:
4480: </ol></div><p class="note">It is possible for the ready state of a media
4481: element to jump between these states discontinuously. For example,
4482: the state of a media element can jump straight from <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> to <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> without
4483: passing through the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> and
4484: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>
4485: states.</p><div class="impl">
4486:
4487: <p>The <dfn id="dom-media-readystate" title="dom-media-readyState"><code>readyState</code></dfn> IDL
4488: attribute must, on getting, return the value described above that
4489: describes the current ready state of the <a href="#media-element">media
4490: element</a>.</p>
4491:
4492: </div><p>The <dfn id="attr-media-autoplay" title="attr-media-autoplay"><code>autoplay</code></dfn>
4493: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When present, the
4494: user agent <span class="impl">(as described in the algorithm
4495: described herein)</span> will automatically begin playback of the
4496: <a href="#media-resource">media resource</a> as soon as it can do so without
4497: stopping.</p><p class="note">Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
4498: using script to trigger automatic playback, as this allows the user
4499: to override the automatic playback when it is not desired, e.g. when
4500: using a screen reader. Authors are also encouraged to consider not
4501: using the automatic playback behavior at all, and instead to let the
4502: user agent wait for the user to start playback explicitly.</p><div class="impl">
4503:
4504: <p>The <dfn id="dom-media-autoplay" title="dom-media-autoplay"><code>autoplay</code></dfn>
4505: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4506: same name.</p>
4507:
4508: </div><h5 id="playing-the-media-resource"><span class="secno">4.8.10.8 </span>Playing the media resource</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code></dt>
4509:
4510: <dd>
4511:
4512: <p>Returns true if playback is paused; false otherwise.</p>
4513:
4514: </dd>
4515:
4516: <dt><var title="">media</var> . <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code></dt>
4517:
4518: <dd>
4519:
4520: <p>Returns true if playback has reached the end of the <a href="#media-resource">media resource</a>.</p>
4521:
4522: </dd>
4523:
4524: <dt><var title="">media</var> . <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
4525:
4526: <dd>
4527:
4528: <p>Returns the default rate of playback, for when the user is not
4529: fast-forwarding or reversing through the <a href="#media-resource">media
4530: resource</a>.</p>
4531:
4532: <p>Can be set, to change the default rate of playback.</p>
4533:
4534: <p>The default rate has no direct effect on playback, but if the
4535: user switches to a fast-forward mode, when they return to the
4536: normal playback mode, it is expected that the rate of playback
4537: will be returned to the default rate of playback.</p>
4538:
4539: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4540: the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
4541: attribute is ignored and the <a href="#current-media-controller">current media
4542: controller</a>'s <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code>
4543: is used instead.</p>
4544:
4545: </dd>
4546:
4547: <dt><var title="">media</var> . <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
4548:
4549: <dd>
4550:
4551: <p>Returns the current rate playback, where 1.0 is normal speed.</p>
4552:
4553: <p>Can be set, to change the rate of playback.</p>
4554:
4555: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4556: the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>
4557: attribute is ignored and the <a href="#current-media-controller">current media
4558: controller</a>'s <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> is
4559: used instead.</p>
4560:
4561: </dd>
4562:
4563: <dt><var title="">media</var> . <code title="dom-media-played"><a href="#dom-media-played">played</a></code></dt>
4564:
4565: <dd>
4566:
4567: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4568: ranges of the <a href="#media-resource">media resource</a> that the user agent has
4569: played.</p>
4570:
4571: </dd>
4572:
4573: <dt><var title="">media</var> . <code title="dom-media-play"><a href="#dom-media-play">play</a></code>()</dt>
4574:
4575: <dd>
4576:
4577: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4578: to false, loading the <a href="#media-resource">media resource</a> and beginning
4579: playback if necessary. If the playback had ended, will restart it
4580: from the start.</p>
4581:
4582: </dd>
4583:
4584: <dt><var title="">media</var> . <code title="dom-media-pause"><a href="#dom-media-pause">pause</a></code>()</dt>
4585:
4586: <dd>
4587:
4588: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4589: to true, loading the <a href="#media-resource">media resource</a> if necessary.</p>
4590:
4591: </dd>
4592:
4593: </dl><div class="impl">
4594:
4595: <p>The <dfn id="dom-media-paused" title="dom-media-paused"><code>paused</code></dfn>
4596: attribute represents whether the <a href="#media-element">media element</a> is
4597: paused or not. The attribute must initially be true.</p>
4598:
4599: <p>A <a href="#media-element">media element</a> is a <dfn id="blocked-media-element">blocked media
4600: element</dfn> if its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is in the
1.62 mike 4601: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> state, the
4602: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4603: the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> state,
4604: or if the element has <a href="#paused-for-user-interaction">paused for user interaction</a>.</p>
1.47 mike 4605:
4606: <p>A <a href="#media-element">media element</a> is said to be <dfn id="potentially-playing">potentially
4607: playing</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4608: attribute is false, the element has not <a href="#ended-playback">ended playback</a>,
4609: playback has not <a href="#stopped-due-to-errors">stopped due to errors</a>,
4610: the element either has no <a href="#current-media-controller">current media controller</a> or
4611: has a <a href="#current-media-controller">current media controller</a> but is not <a href="#blocked-on-its-media-controller">blocked
4612: on its media controller</a>,
4613: and the element is not a <a href="#blocked-media-element">blocked media element</a>.</p>
4614:
4615: <p>A <a href="#media-element">media element</a> is said to have <dfn id="ended-playback">ended
4616: playback</dfn> when:</p>
4617:
4618: <ul><li>The element's <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> or greater,
4619: and
4620:
4621: </li><li>
4622:
4623: <p>Either:
4624:
4625: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the end of the
4626: <a href="#media-resource">media resource</a>, and
4627:
4628: </li><li>The <a href="#direction-of-playback">direction of playback</a> is forwards, and
4629:
4630: </li><li>
4631: Either
4632: the <a href="#media-element">media element</a> does not have a <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code> attribute specified,
4633: or the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4634: controller</a>.
4635:
4636: </li></ul><p>Or:
4637:
4638: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the
4639: <a href="#earliest-possible-position">earliest possible position</a>, and
4640:
4641: </li><li>The <a href="#direction-of-playback">direction of playback</a> is backwards.
4642:
4643: </li></ul></li>
4644:
4645: </ul><p>The <dfn id="dom-media-ended" title="dom-media-ended"><code>ended</code></dfn>
1.113 mike 4646: attribute must return true if, the last time the <a href="webappapis.html#event-loop">event
4647: loop</a> reached step 1, the <a href="#media-element">media element</a> had
1.47 mike 4648: <a href="#ended-playback">ended playback</a> and the <a href="#direction-of-playback">direction of
1.113 mike 4649: playback</a> was forwards, and false otherwise.</p>
1.47 mike 4650:
4651: <p>A <a href="#media-element">media element</a> is said to have <dfn id="stopped-due-to-errors">stopped due to
4652: errors</dfn> when the element's <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> or greater, and
4653: the user agent <a href="#non-fatal-media-error">encounters a
4654: non-fatal error</a> during the processing of the <a href="#media-data">media
4655: data</a>, and due to that error, is not able to play the content
4656: at the <a href="#current-playback-position">current playback position</a>.</p>
4657:
4658: <p>A <a href="#media-element">media element</a> is said to have <dfn id="paused-for-user-interaction">paused for user
4659: interaction</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false, the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is either
4660: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4661: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> and
4662: the user agent has reached a point in the <a href="#media-resource">media
4663: resource</a> where the user has to make a selection for the
4664: resource to continue.
4665: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4666: controller</a> when this happens, then the user agent must
4667: <a href="#report-the-controller-state">report the controller state</a> for the <a href="#media-element">media
1.113 mike 4668: element</a>'s <a href="#current-media-controller">current media controller</a>. If the
1.47 mike 4669: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4670: controller</a> when the user makes a selection, allowing playback
4671: to resume, the user agent must similarly <a href="#report-the-controller-state">report the controller
4672: state</a> for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current
4673: media controller</a>.
4674: </p>
4675:
4676: <p>It is possible for a <a href="#media-element">media element</a> to have both
4677: <a href="#ended-playback">ended playback</a> and <a href="#paused-for-user-interaction">paused for user
4678: interaction</a> at the same time.</p>
4679:
4680: <p>When a <a href="#media-element">media element</a> that is <a href="#potentially-playing">potentially
4681: playing</a> stops playing because it has <a href="#paused-for-user-interaction">paused for user
4682: interaction</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
4683: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p>
4684:
4685: <p class="note">A <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code>
4686: DOM event <a href="#fire-waiting-when-waiting">can be fired</a> as a
4687: result of an element that is <a href="#potentially-playing">potentially playing</a>
4688: stopping playback due to its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute changing to
4689: a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.</p>
4690:
4691: <p>When the <a href="#current-playback-position">current playback position</a> reaches the end
4692: of the <a href="#media-resource">media resource</a> when the <a href="#direction-of-playback">direction of
4693: playback</a> is forwards, then the user agent must follow these
4694: steps:</p>
4695:
4696: <ol><li><p>If the <a href="#media-element">media element</a> has a <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code> attribute specified
4697: and does not have a <a href="#current-media-controller">current media controller</a>,
4698: then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4699: possible position</a> of the <a href="#media-resource">media resource</a> and
4700: abort these steps.</p></li>
1.113 mike 4701: <li><p>As defined above, the <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> IDL attribute starts returning
4702: true once the <a href="webappapis.html#event-loop">event loop</a>'s current <a href="webappapis.html#concept-task" title="concept-task">task</a> ends.</p></li>
1.47 mike 4703:
1.113 mike 4704: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4705: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the <a href="#media-element">media
4706: element</a>.</p></li>
4707:
4708: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> that, if the <a href="#media-element">media
4709: element</a> does not have a <a href="#current-media-controller">current media
4710: controller</a>, and the <a href="#media-element">media element</a> has still
4711: <a href="#ended-playback">ended playback</a>, and the <a href="#direction-of-playback">direction of
4712: playback</a> is still forwards, and <a href="#dom-media-paused" title="dom-media-paused">paused</a> is false, changes <a href="#dom-media-paused" title="dom-media-paused">paused</a> to true and <a href="webappapis.html#fire-a-simple-event" title="fire a simple event">fires a simple event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> at the <a href="#media-element">media
4713: element</a>.</p></li>
4714:
4715: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4716: event</a> named <code title="event-media-ended"><a href="#event-media-ended">ended</a></code> at
4717: the <a href="#media-element">media element</a>.</p></li>
1.47 mike 4718:
1.113 mike 4719: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4720: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4721: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4722: controller</a>.</p></li>
1.47 mike 4723:
4724: </ol><p>When the <a href="#current-playback-position">current playback position</a> reaches the
4725: <a href="#earliest-possible-position">earliest possible position</a> of the <a href="#media-resource">media
4726: resource</a> when the <a href="#direction-of-playback">direction of playback</a> is
1.113 mike 4727: backwards, then the user agent must only <a href="webappapis.html#queue-a-task">queue a task</a>
4728: to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p>
1.47 mike 4729:
1.113 mike 4730: <hr><p>The <dfn id="dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
1.47 mike 4731: attribute gives the desired speed at which the <a href="#media-resource">media
4732: resource</a> is to play, as a multiple of its intrinsic
4733: speed. The attribute is mutable: on getting it must return the last
4734: value it was set to, or 1.0 if it hasn't yet been set; on setting
4735: the attribute must be set to the new value.</p>
4736:
4737: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> is
4738: used by the user agent when it <a href="#expose-a-user-interface-to-the-user" title="expose a user interface
4739: to the user">exposes a user interface to the user</a>.</p>
4740:
4741: <p>The <dfn id="dom-media-playbackrate" title="dom-media-playbackRate"><code>playbackRate</code></dfn>
4742: attribute gives the <a href="#effective-playback-rate">effective playback rate</a>
4743: (assuming there is no <a href="#current-media-controller">current media controller</a> overriding it),
4744: which is the speed at which the <a href="#media-resource">media resource</a> plays,
4745: as a multiple of its intrinsic speed. If it is not equal to the
4746: <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>,
4747: then the implication is that the user is using a feature such as
4748: fast forward or slow motion playback. The attribute is mutable: on
4749: getting it must return the last value it was set to, or 1.0 if it
4750: hasn't yet been set; on setting the attribute must be set to the new
4751: value, and the playback will change speed
4752: (if the element is <a href="#potentially-playing">potentially playing</a> and there is no
4753: <a href="#current-media-controller">current media controller</a>).</p>
4754:
4755: <p id="rateUpdate">When the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or
4756: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4757: change value (either by being set by script or by being changed
4758: directly by the user agent, e.g. in response to user control) the
4759: user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4760: event</a> named <code title="event-media-ratechange"><a href="#event-media-ratechange">ratechange</a></code> at the <a href="#media-element">media
4761: element</a>.</p>
4762:
4763: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> and
4764: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4765: have no effect when the <a href="#media-element">media element</a> has a
4766: <a href="#current-media-controller">current media controller</a>; the namesake attributes on
4767: the <code><a href="#mediacontroller">MediaController</a></code> object are used instead in that
4768: situation.</p>
4769:
4770: <hr><p>The <dfn id="dom-media-played" title="dom-media-played"><code>played</code></dfn>
4771: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4772: <code>TimeRanges</code> object</a> that represents the ranges of
4773: the <a href="#media-resource">media resource</a>, if any, that the user agent has so
4774: far rendered, at the time the attribute is evaluated.</p>
4775:
4776: <hr><p>When the <dfn id="dom-media-play" title="dom-media-play"><code>play()</code></dfn>
4777: method on a <a href="#media-element">media element</a> is invoked, the user agent
4778: must run the following steps.</p>
4779:
4780: <ol><li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute has
4781: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4782: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4783: algorithm</a>.</p></li>
4784:
4785: <li>
4786:
4787: <p>If the <a href="#ended-playback" title="ended playback">playback has ended</a>
4788: and the <a href="#direction-of-playback">direction of playback</a> is forwards,
4789: and the <a href="#media-element">media element</a> does not have a <a href="#current-media-controller">current
4790: media controller</a>,
4791: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4792: possible position</a> of the <a href="#media-resource">media resource</a>.</p>
4793:
4794: <p class="note">This <a href="#seekUpdate">will cause</a> the user
4795: agent to <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
1.107 mike 4796: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4797: <a href="#media-element">media element</a>.</p>
1.47 mike 4798: </li>
4799:
4800: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
4801: media controller</a>, then <a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">bring the media element up
4802: to speed with its new media controller</a>.</p>
4803:
4804: </li><li>
4805:
4806: <p>If the <a href="#media-element">media element</a>'s <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is true, run
4807: the following substeps:</p>
4808:
4809: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to false.</p></li>
4810:
4811: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4812: named <code title="event-media-play"><a href="#event-media-play">play</a></code> at the element.</p></li>
4813:
4814: <li>
4815:
4816: <p>If the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute has the
4817: value <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>,
4818: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, or
4819: <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
4820: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4821: named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the
4822: element.</p>
4823:
4824: <p>Otherwise, the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute has the
4825: value <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4826: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>:
4827: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
4828: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> at the
4829: element.</p>
4830:
4831: </li>
4832:
4833: </ol></li>
4834:
4835: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4836: flag</a> to false.</p></li>
4837:
4838: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4839: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4840: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4841: controller</a>.</p></li>
4842:
4843: </ol><hr><p>When the <dfn id="dom-media-pause" title="dom-media-pause"><code>pause()</code></dfn>
4844: method is invoked, and when the user agent is required to pause the
4845: <a href="#media-element">media element</a>, the user agent must run the following
4846: steps:</p>
4847:
4848: <ol><li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute has
4849: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4850: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4851: algorithm</a>.</p></li>
4852:
4853: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4854: flag</a> to false.</p></li>
4855:
4856: <li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false, run the
4857: following steps:</p>
4858:
4859: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to true.</p></li>
4860:
4861: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4862: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4863: element.</p></li>
4864:
4865: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4866: event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code>
4867: at the element.</p></li>
4868:
1.107 mike 4869: <li><p>Set the <a href="#official-playback-position">official playback position</a> to the
4870: <a href="#current-playback-position">current playback position</a>.</p></li>
4871:
1.47 mike 4872: </ol></li>
4873:
4874: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4875: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4876: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4877: controller</a>.</p></li>
4878:
4879: </ol><hr><p>The
4880: <dfn id="effective-playback-rate">effective playback rate</dfn> is not necessarily the element's
4881: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>. When a
4882: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4883: controller</a>, its <a href="#effective-playback-rate">effective playback rate</a> is the
4884: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
4885: rate</a>. Otherwise, the
4886: <a href="#effective-playback-rate">effective playback rate</a> is just the element's <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>.
4887: Thus, the <a href="#current-media-controller">current media controller</a> overrides the
4888: <a href="#media-element">media element</a>.
4889: </p>
4890:
4891: <p>If the <a href="#effective-playback-rate">effective playback rate</a> is positive or zero,
4892: then the <dfn id="direction-of-playback">direction of playback</dfn> is forwards. Otherwise, it
4893: is backwards.</p>
4894:
4895: <p id="media-playback">When a <a href="#media-element">media element</a> is
4896: <a href="#potentially-playing">potentially playing</a> and its <code><a href="infrastructure.html#document">Document</a></code> is a
4897: <a href="browsers.html#fully-active">fully active</a> <code><a href="infrastructure.html#document">Document</a></code>, its <a href="#current-playback-position">current
4898: playback position</a> must increase monotonically at
4899: <a href="#effective-playback-rate">effective playback rate</a> units of media time per unit time
4900: of the <a href="#media-timeline">media timeline</a>'s clock.</p>
4901:
4902: <p class="note">The <a href="#effective-playback-rate">effective playback rate</a> can be 0.0,
4903: in which case the <a href="#current-playback-position">current playback position</a> doesn't
4904: move, despite playback not being paused (<code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> doesn't become true, and the
4905: <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> event doesn't
4906: fire).</p>
4907:
4908: <p class="note">This specification doesn't define how the user agent
4909: achieves the appropriate playback rate — depending on the
4910: protocol and media available, it is plausible that the user agent
4911: could negotiate with the server to have the server provide the media
4912: data at the appropriate rate, so that (except for the period between
4913: when the rate is changed and when the server updates the stream's
4914: playback rate) the client doesn't actually have to drop or
4915: interpolate any frames.</p>
4916:
1.107 mike 4917: <p>Any time the user agent <a href="webappapis.html#provide-a-stable-state" title="provide a stable
4918: state">provides a stable state</a>, the <a href="#official-playback-position">official playback
4919: position</a> must be set to the <a href="#current-playback-position">current playback
4920: position</a>.</p>
4921:
1.47 mike 4922: <p>When the <a href="#direction-of-playback">direction of playback</a> is backwards, any
4923: corresponding audio must be muted. When the <a href="#effective-playback-rate">effective playback
4924: rate</a> is so low or so high that the user agent cannot play
4925: audio usefully, the corresponding audio must also be muted. If the
4926: <a href="#effective-playback-rate">effective playback rate</a> is not 1.0, the user agent may
4927: apply pitch adjustments to the audio as necessary to render it
4928: faithfully.</p>
4929:
4930: <p><a href="#media-element" title="media element">Media elements</a> that are
4931: <a href="#potentially-playing">potentially playing</a> while not <a href="infrastructure.html#in-a-document">in a
4932: <code>Document</code></a> must not play any video, but should
4933: play any audio component. Media elements must not stop playing just
4934: because all references to them have been removed; only once a media
4935: element is in a state where no further audio could ever be played by
4936: that element may the element be garbage collected.</p>
4937:
4938: <p class="note">It is possible for an element to which no explicit
4939: references exist to play audio, even if such an element is not still
4940: actively playing: for instance, it could have a <a href="#current-media-controller">current media
4941: controller</a> that still has references and can still be
4942: unpaused, or it could be unpaused but stalled waiting for content to
4943: buffer.</p>
4944:
4945: <hr><p>When the <a href="#current-playback-position">current playback position</a> of a <a href="#media-element">media
4946: element</a> changes (e.g. due to playback or seeking), the user
4947: agent must run the following steps. If the <a href="#current-playback-position">current playback
4948: position</a> changes while the steps are running, then the user
4949: agent must wait for the steps to complete, and then must immediately
4950: rerun the steps.
4951: (These steps are thus run as often as possible or needed — if
4952: one iteration takes a long time, this can cause certain <a href="#text-track-cue" title="text track cue">cues</a> to be skipped over as the user
4953: agent rushes ahead to "catch up".)
4954: </p>
4955:
1.104 mike 4956: <ol><li><p>Let <var title="">current cues</var> be a list of <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain all the
4957: <a href="#text-track-cue" title="text track cue">cues</a> of all the <a href="#text-track-hidden" title="text track hidden">hidden</a>, <a href="#text-track-showing" title="text track
1.47 mike 4958: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
4959: default">showing by default</a> <a href="#text-track" title="text track">text
4960: tracks</a> of the <a href="#media-element">media element</a> (not the <a href="#text-track-disabled" title="text track disabled">disabled</a> ones) whose <a href="#text-track-cue-start-time" title="text track cue start time">start times</a> are less than
4961: or equal to the <a href="#current-playback-position">current playback position</a> and whose
4962: <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are greater
1.104 mike 4963: than the <a href="#current-playback-position">current playback position</a>.</p></li>
1.47 mike 4964:
1.104 mike 4965: <li><p>Let <var title="">other cues</var> be a list of <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain all the
4966: <a href="#text-track-cue" title="text track cue">cues</a> of <a href="#text-track-hidden" title="text track
4967: hidden">hidden</a>, <a href="#text-track-showing" title="text track
1.47 mike 4968: showing">showing</a>, and <a href="#text-track-showing-by-default" title="text track showing by
4969: default">showing by default</a> <a href="#text-track" title="text track">text
4970: tracks</a> of the <a href="#media-element">media element</a> that are not
1.104 mike 4971: present in <var title="">current cues</var>.</p></li>
4972:
4973: <li><p>Let <var title="">last time</var> be the <a href="#current-playback-position">current
4974: playback position</a> at the time this algorithm was last run
4975: for this <a href="#media-element">media element</a>, if this is not the first time
4976: it has run.</p></li>
4977:
4978: <li><p>If the <a href="#current-playback-position">current playback position</a> has, since the
4979: last time this algorithm was run, only changed through its usual
4980: monotonic increase during normal playback, then let <var title="">missed cues</var> be the list of <a href="#text-track-cue" title="text track
4981: cue">cues</a> in <var title="">other cues</var> whose <a href="#text-track-cue-start-time" title="text track cue start time">start times</a> are greater
4982: than or equal to <var title="">last time</var> and whose <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are less than or
4983: equal to the <a href="#current-playback-position">current playback position</a>. Otherwise, let
4984: <var title="">missed cues</var> be an empty list.</p></li>
1.47 mike 4985:
4986: <li><p>If the time was reached through the usual monotonic increase
4987: of the <a href="#current-playback-position">current playback position</a> during normal
4988: playback, and if the user agent has not fired a <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> event at the
4989: element in the past 15 to 250ms and is not still running event
4990: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4991: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.
4992: (In the other cases, such as explicit seeks, relevant events get
4993: fired as part of the overall process of changing the <a href="#current-playback-position">current
4994: playback position</a>.)</p>
4995:
4996: <p class="note">The event thus is not to be fired faster than about
4997: 66Hz or slower than 4Hz (assuming the event handlers don't take
4998: longer than 250ms to run). User agents are encouraged to vary the
4999: frequency of the event based on the system load and the average
5000: cost of processing the event each time, so that the UI updates are
5001: not any more frequent than the user agent can comfortably handle
5002: while decoding the video.</p></li>
5003:
5004: <li><p>If all of the <a href="#text-track-cue" title="text track cue">cues</a> in
5005: <var title="">current cues</var> have their <a href="#text-track-cue-active-flag">text track cue
1.104 mike 5006: active flag</a> set, none of the <a href="#text-track-cue" title="text track
1.47 mike 5007: cue">cues</a> in <var title="">other cues</var> have their
1.104 mike 5008: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, and <var title="">missed cues</var> is empty, then abort these
1.47 mike 5009: steps.</p></li>
5010:
1.104 mike 5011: <li>
5012:
5013: <p>If the time was reached through the usual monotonic increase of
5014: the <a href="#current-playback-position">current playback position</a> during normal playback,
5015: and there are <a href="#text-track-cue" title="text track cue">cues</a> in <var title="">other cues</var> that have their <a href="#text-track-cue-pause-on-exit-flag">text track cue
5016: pause-on-exit flag</a> set and that either have their
5017: <a href="#text-track-cue-active-flag">text track cue active flag</a> set or are also in <var title="">missed cues</var>, then immediately <a href="#dom-media-pause" title="dom-media-pause">pause</a> the <a href="#media-element">media
5018: element</a>. </p>
5019:
5020: <p class="note">In the other cases, such as explicit seeks,
5021: playback is not paused by going past the end time of a <a href="#text-track-cue" title="text track cue">cue</a>, even if that <a href="#text-track-cue" title="text
5022: track cue">cue</a> has its <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
5023: flag</a> set.</p>
5024:
5025: </li>
5026:
5027: <li>
5028:
5029: <p>Let <var title="">events</var> be a list of <a href="webappapis.html#concept-task" title="concept-task">tasks</a>, initially empty. Each <a href="webappapis.html#concept-task" title="concept-task">task</a> in this list will be associated
5030: with a <a href="#text-track">text track</a>, a <a href="#text-track-cue">text track cue</a>, and
5031: a time, which are used to sort the list before the <a href="webappapis.html#concept-task" title="concept-task">tasks</a> are queued.</p>
5032:
5033: <p>Let <var title="">affected tracks</var> be a list of <a href="#text-track" title="text track">text tracks</a>, initially empty.</p>
5034:
5035: <p>When the steps below say to <dfn id="prepare-an-event">prepare an event</dfn> named
5036: <var title="">event</var> for a <a href="#text-track-cue">text track cue</a> <var title="">target</var> with a time <var title="">time</var>, the
5037: user agent must run these substeps:</p>
5038:
5039: <ol><li><p>Let <var title="">track</var> be the <a href="#text-track">text
5040: track</a> with which the <a href="#text-track-cue">text track cue</a> <var title="">target</var> is associated.</p></li>
5041:
5042: <li><p>Create a <a href="webappapis.html#concept-task" title="concept-task">task</a> to
5043: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <var title="">event</var>
5044: at <var title="">target</var>.</p></li>
5045:
5046: <li><p>Add to the newly create <a href="webappapis.html#concept-task" title="concept-task">task</a> to <var title="">events</var>,
5047: associated with the time <var title="">time</var>, the <a href="#text-track">text
5048: track</a> <var title="">track</var>, and the <a href="#text-track-cue">text track
5049: cue</a> <var title="">target</var>.</p></li>
5050:
5051: <li><p>Add <var title="">track</var> to <var title="">affected
5052: tracks</var>.</p></li>
5053:
5054: </ol></li>
5055:
5056: <li><p>For each <a href="#text-track-cue" title="text track cue">text track cue</a>
5057: in <var title="">missed cues</var>, <a href="#prepare-an-event">prepare an event</a>
5058: named <code title="event-enter">enter</code> for the
5059: <code><a href="#texttrackcue">TextTrackCue</a></code> object with the <a href="#text-track-cue-start-time">text track cue
5060: start time</a>.</p></li>
5061:
5062: <li><p>For each <a href="#text-track-cue" title="text track cue">text track cue</a>
5063: in <var title="">other cues</var> that either has its <a href="#text-track-cue-active-flag">text
5064: track cue active flag</a> set or is in <var title="">missed
5065: cues</var>, <a href="#prepare-an-event">prepare an event</a> named <code title="event-exit">exit</code> for the <code><a href="#texttrackcue">TextTrackCue</a></code>
5066: object with the <a href="#text-track-cue-end-time">text track cue end time</a>.</p></li>
5067:
5068: <li><p>For each <a href="#text-track-cue" title="text track cue">text track cue</a>
5069: in <var title="">current cues</var> that does not have its
5070: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, <a href="#prepare-an-event">prepare an
5071: event</a> named <code title="event-enter">enter</code> for the
5072: <code><a href="#texttrackcue">TextTrackCue</a></code> object with the <a href="#text-track-cue-start-time">text track cue
5073: start time</a>.</p></li>
5074:
5075: <li>
5076:
5077: <p>Sort the <a href="webappapis.html#concept-task" title="concept-task">tasks</a> in <var title="">events</var> in ascending time order (<a href="webappapis.html#concept-task" title="concept-task">tasks</a> with earlier times
5078: first).</p>
5079:
1.111 mike 5080: <p>Further sort <a href="webappapis.html#concept-task" title="concept-task">tasks</a> in <var title="">events</var> that have the same time by the relative
5081: <a href="#text-track-cue-order">text track cue order</a> of the <a href="#text-track-cue" title="text track
5082: cue">text track cues</a> associated with these <a href="webappapis.html#concept-task" title="concept-task">tasks</a>.</p>
1.104 mike 5083:
5084: </li>
5085:
5086: <li><p><a href="webappapis.html#queue-a-task" title="queue a task">Queue</a> each <a href="webappapis.html#concept-task" title="concept-task">task</a> in <var title="">events</var>, in
5087: list order.</p></li>
5088:
5089: <li><p>Sort <var title="">affected tracks</var> in the same order
5090: as the <a href="#text-track" title="text track">text tracks</a> appear in the
5091: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, and
5092: remove duplicates.</p>
5093:
5094: </li><li><p>For each <a href="#text-track">text track</a> in <var title="">affected
5095: tracks</var>, in the list order, <a href="webappapis.html#queue-a-task">queue a task</a> to
5096: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-cuechange">cuechange</code> at the
5097: <code><a href="#texttrack">TextTrack</a></code> object, and, if the <a href="#text-track">text track</a>
5098: has a corresponding <code><a href="#the-track-element">track</a></code> element, to then <a href="webappapis.html#fire-a-simple-event">fire
5099: a simple event</a> named <code title="event-cuechange">cuechange</code> at the <code><a href="#the-track-element">track</a></code>
1.47 mike 5100: element as well.</p></li>
5101:
5102: <li><p>Set the <a href="#text-track-cue-active-flag">text track cue active flag</a> of all the
5103: <a href="#text-track-cue" title="text track cue">cues</a> in the <var title="">current cues</var>, and unset the <a href="#text-track-cue-active-flag">text track cue
5104: active flag</a> of all the <a href="#text-track-cue" title="text track
5105: cue">cues</a> in the <var title="">other cues</var>.</p></li>
5106:
5107: <li><p>Run the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
5108: rendering</a> of each of the <a href="#text-track" title="text track">text
5109: tracks</a> in <var title="">affected tracks</var> that are <a href="#text-track-showing" title="text track showing">showing</a> or <a href="#text-track-showing-by-default" title="text
5110: track showing by default">showing by default</a>.
5111: </p></li>
5112:
5113: </ol><p>For the purposes of the algorithm above, a <a href="#text-track-cue">text track
5114: cue</a> is considered to be part of a <a href="#text-track">text track</a>
5115: only if it is listed in the <a href="#text-track-list-of-cues">text track list of cues</a>,
5116: not merely if it is associated with the <a href="#text-track">text
5117: track</a>.</p>
5118:
5119: <p class="note">If the <a href="#media-element">media element</a>'s
5120: <code><a href="infrastructure.html#document">Document</a></code> stops being a <a href="browsers.html#fully-active">fully active</a>
5121: document, then the playback will <a href="#media-playback">stop</a>
5122: until the document is active again.</p>
5123:
5124: <p>When a <a href="#media-element">media element</a> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an
5125: element from a document">removed from a
5126: <code>Document</code></a>, the user agent must run
5127: the following steps:</p>
5128:
5129: <ol><li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
5130: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that removed the
5131: <a href="#media-element">media element</a> from the <code><a href="infrastructure.html#document">Document</a></code> to
5132: continue. The <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the
5133: remaining steps of this algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous
5134: section</a> are marked with ⌛.)</p></li>
5135:
5136: <li><p>⌛ If the <a href="#media-element">media element</a> is <a href="infrastructure.html#in-a-document">in a
5137: <code>Document</code></a>, abort these steps.</p></li>
5138:
5139: <li><p>⌛ If the <a href="#media-element">media element</a>'s <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute has
5140: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, abort these
5141: steps.</p></li>
5142:
5143: <li><p>⌛ <a href="#dom-media-pause" title="dom-media-pause">Pause</a> the
5144: <a href="#media-element">media element</a>.</p>
5145:
5146: </li></ol></div><h5 id="seeking"><span class="secno">4.8.10.9 </span>Seeking</h5><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code></dt>
5147:
5148: <dd>
5149:
5150: <p>Returns true if the user agent is currently seeking.</p>
5151:
5152: </dd>
5153:
5154: <dt><var title="">media</var> . <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code></dt>
5155:
5156: <dd>
5157:
5158: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5159: ranges of the <a href="#media-resource">media resource</a> to which it is possible
5160: for the user agent to seek.</p>
5161:
5162: </dd>
5163:
5164: </dl><div class="impl">
5165:
5166: <p>The <dfn id="dom-media-seeking" title="dom-media-seeking"><code>seeking</code></dfn>
5167: attribute must initially have the value false.</p>
5168:
5169: <p>When the user agent is required to <dfn id="dom-media-seek" title="dom-media-seek">seek</dfn> to a particular <var title="">new
5170: playback position</var> in the <a href="#media-resource">media resource</a>, it means
5171: that the user agent must run the following steps. This algorithm
5172: interacts closely with the <a href="webappapis.html#event-loop">event loop</a> mechanism; in
5173: particular, it has a <a href="webappapis.html#synchronous-section">synchronous
5174: section</a> (which is triggered as part of the <a href="webappapis.html#event-loop">event
5175: loop</a> algorithm). Steps in that section are marked with
5176: ⌛.</p>
5177:
1.107 mike 5178: <ol><li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, abort these
5179: steps.</p></li>
1.47 mike 5180:
5181: <li><p>If the element's <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute is true,
5182: then another instance of this algorithm is already running. Abort
5183: that other instance of the algorithm without waiting for the step
5184: that it is running to complete.</p></li>
5185:
5186: <li><p>Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL
5187: attribute to true.</p></li>
5188:
5189: <li><p>If the seek was in response to a DOM method call or setting
5190: of an IDL attribute, then continue the script. The remainder of
5191: these steps must be run asynchronously. With the exception of the
5192: steps marked with ⌛, they could be aborted at any time by
5193: another instance of this algorithm being invoked.</p></li>
5194:
5195: <li><p>If the <var title="">new playback position</var> is later
5196: than the end of the <a href="#media-resource">media resource</a>, then let it be the
5197: end of the <a href="#media-resource">media resource</a> instead.</p></li>
5198:
5199: <li><p>If the <var title="">new playback position</var> is less
5200: than the <a href="#earliest-possible-position">earliest possible position</a>, let it be that
5201: position instead.</p></li>
5202:
5203: <li><p>If the (possibly now changed) <var title="">new playback
5204: position</var> is not in one of the ranges given in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute, then let it
5205: be the position in one of the ranges given in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute that is the
5206: nearest to the <var title="">new playback position</var>. If two
5207: positions both satisfy that constraint (i.e. the <var title="">new
5208: playback position</var> is exactly in the middle between two ranges
5209: in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute)
5210: then use the position that is closest to the <a href="#current-playback-position">current playback
5211: position</a>. If there are no ranges given in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute then set the
5212: <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
5213: false and abort these steps.</p></li>
5214:
5215: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
5216: event</a> named <code title="event-media-seeking"><a href="#event-media-seeking">seeking</a></code>
5217: at the element.</p></li>
5218:
5219: <li>
5220:
5221: <p>Set the <a href="#current-playback-position">current playback position</a> to the given
5222: <var title="">new playback position</var>.</p>
5223:
5224: <p class="note">If the <a href="#media-element">media element</a> was
5225: <a href="#potentially-playing">potentially playing</a> immediately before it started
5226: seeking, but seeking caused its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to change
5227: to a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>, then a
5228: <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> <a href="#fire-waiting-when-waiting">will be fired</a> at the
5229: element.</p>
5230:
5231:
1.107 mike 5232: <p class="note">The <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> attribute does
5233: not get updated asynchronously, as it returns the <a href="#official-playback-position">official
5234: playback position</a>, not the <a href="#current-playback-position">current playback
5235: position</a>.</p>
5236:
1.47 mike 5237: </li>
5238:
5239: <li><p>Wait until the user agent has established whether or not the
5240: <a href="#media-data">media data</a> for the <var title="">new playback
5241: position</var> is available, and, if it is, until it has decoded
5242: enough data to play back that position.</p>
5243: </li>
5244:
5245: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
5246: section</a> consists of all the remaining steps of this
5247: algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous section</a> are
5248: marked with ⌛.)</p></li>
5249:
5250: <li><p>⌛ Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
5251: false.</p></li>
5252:
1.120 mike 5253: <li id="seekUpdate"><p>⌛ <a href="webappapis.html#queue-a-task">Queue a task</a> to
5254: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
1.47 mike 5255: element.</p></li>
5256:
5257: <li><p>⌛ <a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
5258: event</a> named <code title="event-media-seeked"><a href="#event-media-seeked">seeked</a></code>
5259: at the element.</p></li>
5260:
5261: </ol><p>The <dfn id="dom-media-seekable" title="dom-media-seekable"><code>seekable</code></dfn>
5262: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5263: <code>TimeRanges</code> object</a> that represents the ranges of
5264: the <a href="#media-resource">media resource</a>, if any, that the user agent is able
5265: to seek to, at the time the attribute is evaluated.</p>
5266:
5267: <p class="note">If the user agent can seek to anywhere in the
5268: <a href="#media-resource">media resource</a>, e.g. because it is a simple movie file
5269: and the user agent and the server support HTTP Range requests, then
5270: the attribute would return an object with one range, whose start is
5271: the time of the first frame (the <a href="#earliest-possible-position">earliest possible
5272: position</a>, typically zero), and whose end is the same as the
5273: time of the first frame plus the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute's value (which
5274: would equal the time of the last frame, and might be positive
5275: Infinity).</p>
5276:
5277: <p class="note">The range might be continuously changing, e.g. if
5278: the user agent is buffering a sliding window on an infinite
5279: stream. This is the behavior seen with DVRs viewing live TV, for
5280: instance.</p>
5281:
5282: <p><a href="#media-resource" title="media resource">Media resources</a> might be
5283: internally scripted or interactive. Thus, a <a href="#media-element">media
5284: element</a> could play in a non-linear fashion. If this happens,
5285: the user agent must act as if the algorithm for <a href="#dom-media-seek" title="dom-media-seek">seeking</a> was used whenever the
5286: <a href="#current-playback-position">current playback position</a> changes in a discontinuous
5287: fashion (so that the relevant events fire).
5288: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
5289: controller</a>, then the user agent must <a href="#seek-the-media-controller">seek the media
5290: controller</a> appropriately instead.
5291: </p>
5292:
5293: </div><h5 id="media-resources-with-multiple-media-tracks"><span class="secno">4.8.10.10 </span>Media resources with multiple media tracks</h5><p>A <a href="#media-resource">media resource</a> can have multiple embedded audio
5294: and video tracks. For example, in addition to the primary video and
5295: audio tracks, a <a href="#media-resource">media resource</a> could have
5296: foreign-language dubbed dialogues, director's commentaries, audio
5297: descriptions, alternative angles, or sign-language overlays.</p><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code></dt>
5298:
5299: <dd>
5300:
1.76 mike 5301: <p>Returns an <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
1.47 mike 5302: the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
5303:
5304: </dd>
5305:
5306: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code></dt>
5307:
5308: <dd>
5309:
1.106 mike 5310: <p>Returns a <code><a href="#videotracklist">VideoTrackList</a></code> object representing
1.47 mike 5311: the video tracks available in the <a href="#media-resource">media resource</a>.</p>
5312:
5313: </dd>
5314:
5315: </dl><div class="impl">
5316:
5317: <p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
5318: attribute of a <a href="#media-element">media element</a> must return a
1.76 mike 5319: <a href="infrastructure.html#live">live</a> <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
1.47 mike 5320: the audio tracks available in the <a href="#media-element">media element</a>'s
5321: <a href="#media-resource">media resource</a>. The same object must be returned each
5322: time.</p>
5323:
5324: <p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
5325: attribute of a <a href="#media-element">media element</a> must return a
1.76 mike 5326: <a href="infrastructure.html#live">live</a> <code><a href="#videotracklist">VideoTrackList</a></code> object
1.47 mike 5327: representing the video tracks available in the <a href="#media-element">media
5328: element</a>'s <a href="#media-resource">media resource</a>. The same object must
5329: be returned each time.</p>
5330:
1.76 mike 5331: <p class="note">There are only ever one <code><a href="#audiotracklist">AudioTrackList</a></code>
5332: object and one <code><a href="#videotracklist">VideoTrackList</a></code> object per <a href="#media-element">media
1.47 mike 5333: element</a>, even if another <a href="#media-resource">media resource</a> is
1.76 mike 5334: loaded into the element: the objects are reused. (The
5335: <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects are
5336: not, though.)</p>
1.47 mike 5337:
1.67 mike 5338: </div><div class="example">
5339:
5340: <p>In this example, a script defines a function that takes a URL to
5341: a video and a reference to an element where the video is to be
5342: placed. That function then tries to load the video, and, once it is
5343: loaded, checks to see if there is a sign-language track available.
5344: If there is, it also displays that track. Both tracks are just
5345: placed in the given container; it's assumed that styles have been
5346: applied to make this work in a pretty way!</p>
5347:
5348: <pre><script>
5349: function loadVideo(url, container) {
5350: var controller = new MediaController();
5351: var video = document.createElement('video');
5352: video.src = url;
5353: video.autoplay = true;
5354: video.controls = true;
5355: video.controller = controller;
5356: container.appendChild(video);
5357: video.onloadedmetadata = function (event) {
5358: for (var i = 0; i < video.videoTracks.length; i += 1) {
1.76 mike 5359: if (video.videoTracks[i].kind == 'sign') {
1.67 mike 5360: var sign = document.createElement('video');
1.76 mike 5361: sign.src = url + '#track=' + video.videoTracks[i].id;
1.67 mike 5362: sign.autoplay = true;
5363: sign.controller = controller;
5364: container.appendChild(sign);
5365: return;
5366: }
5367: }
5368: };
5369: }
5370: </script></pre>
5371:
1.76 mike 5372: </div><h6 id="audiotracklist-and-videotracklist-objects"><span class="secno">4.8.10.10.1 </span><code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code> objects</h6><p>The <code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code>
5373: interfaces are used by attributes defined in the previous
5374: section.</p><pre class="idl">interface <dfn id="audiotracklist">AudioTrackList</dfn> {
5375: readonly attribute unsigned long <a href="#dom-audiotracklist-length" title="dom-AudioTrackList-length">length</a>;
1.101 mike 5376: getter <a href="#audiotrack">AudioTrack</a> (unsigned long index);
5377: <a href="#audiotrack">AudioTrack</a>? <a href="#dom-audiotracklist-gettrackbyid" title="dom-AudioTrackList-getTrackById">getTrackById</a>(DOMString id);
1.121 mike 5378:
1.118 mike 5379: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
1.121 mike 5380: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onaddtrack" title="handler-TrackList-onaddtrack">onaddtrack</a>;
1.76 mike 5381: };
1.47 mike 5382:
1.76 mike 5383: interface <dfn id="audiotrack">AudioTrack</dfn> {
5384: readonly attribute DOMString <a href="#dom-audiotrack-id" title="dom-AudioTrack-id">id</a>;
5385: readonly attribute DOMString <a href="#dom-audiotrack-kind" title="dom-AudioTrack-kind">kind</a>;
5386: readonly attribute DOMString <a href="#dom-audiotrack-label" title="dom-AudioTrack-label">label</a>;
5387: readonly attribute DOMString <a href="#dom-audiotrack-language" title="dom-AudioTrack-language">language</a>;
5388: attribute boolean <a href="#dom-audiotrack-enabled" title="dom-AudioTrack-enabled">enabled</a>;
1.47 mike 5389: };
5390:
1.76 mike 5391: interface <dfn id="videotracklist">VideoTrackList</dfn> {
5392: readonly attribute unsigned long <a href="#dom-videotracklist-length" title="dom-VideoTrackList-length">length</a>;
1.101 mike 5393: getter <a href="#videotrack">VideoTrack</a> (unsigned long index);
5394: <a href="#videotrack">VideoTrack</a>? <a href="#dom-videotracklist-gettrackbyid" title="dom-VideoTrackList-getTrackById">getTrackById</a>(DOMString id);
1.76 mike 5395: readonly attribute long <a href="#dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex">selectedIndex</a>;
1.121 mike 5396:
1.118 mike 5397: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
1.121 mike 5398: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onaddtrack" title="handler-TrackList-onaddtrack">onaddtrack</a>;
1.47 mike 5399: };
5400:
1.76 mike 5401: interface <dfn id="videotrack">VideoTrack</dfn> {
5402: readonly attribute DOMString <a href="#dom-videotrack-id" title="dom-VideoTrack-id">id</a>;
5403: readonly attribute DOMString <a href="#dom-videotrack-kind" title="dom-VideoTrack-kind">kind</a>;
5404: readonly attribute DOMString <a href="#dom-videotrack-label" title="dom-VideoTrack-label">label</a>;
5405: readonly attribute DOMString <a href="#dom-videotrack-language" title="dom-VideoTrack-language">language</a>;
5406: attribute boolean <a href="#dom-videotrack-selected" title="dom-VideoTrack-selected">selected</a>;
5407: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> . <code title="dom-AudioTrackList-length"><a href="#dom-audiotracklist-length">length</a></code></dt>
5408: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> . <code title="dom-VideoTrackList-length"><a href="#dom-videotracklist-length">length</a></code></dt>
1.47 mike 5409:
5410: <dd>
5411:
5412: <p>Returns the number of tracks in the list.</p>
5413:
5414: </dd>
5415:
1.76 mike 5416: <dt><var title="">audioTrack</var> = <var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>[<var title="">index</var>]</dt>
5417: <dt><var title="">videoTrack</var> = <var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code>[<var title="">index</var>]</dt>
1.47 mike 5418:
5419: <dd>
5420:
1.76 mike 5421: <p>Returns the specified <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object.</p>
1.47 mike 5422:
5423: </dd>
5424:
1.76 mike 5425: <dt><var title="">audioTrack</var> = <var title="">media</var> . <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> . <code title="dom-AudioTrackList-getTrackById"><a href="#dom-audiotracklist-gettrackbyid">getTrackById</a></code>( <var title="">id</var> )</dt>
5426: <dt><var title="">videoTrack</var> = <var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> . <code title="dom-VideoTrackList-getTrackById"><a href="#dom-videotracklist-gettrackbyid">getTrackById</a></code>( <var title="">id</var> )</dt>
1.47 mike 5427:
5428: <dd>
5429:
1.76 mike 5430: <p>Returns the <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object with the given identifier, or null if no track has that identifier.</p>
1.47 mike 5431:
5432: </dd>
5433:
1.76 mike 5434: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-id"><a href="#dom-audiotrack-id">id</a></code></dt>
5435: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-id"><a href="#dom-videotrack-id">id</a></code></dt>
1.47 mike 5436:
5437: <dd>
5438:
1.76 mike 5439: <p>Returns the ID of the given track. This is the ID that can be
5440: used with a fragment identifier if the format supports the
5441: <cite>Media Fragments URI</cite> syntax, and that can be used with
1.101 mike 5442: the <code title="">getTrackById()</code> method. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5443:
5444: </dd>
5445:
1.76 mike 5446: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-kind"><a href="#dom-audiotrack-kind">kind</a></code></dt>
5447: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-kind"><a href="#dom-videotrack-kind">kind</a></code></dt>
1.47 mike 5448:
5449: <dd>
5450:
1.76 mike 5451: <p>Returns the category the given track falls into. The <a href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p>
1.47 mike 5452:
5453: </dd>
5454:
1.76 mike 5455: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-label"><a href="#dom-audiotrack-label">label</a></code></dt>
5456: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-label"><a href="#dom-videotrack-label">label</a></code></dt>
1.47 mike 5457:
5458: <dd>
5459:
1.76 mike 5460: <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
1.47 mike 5461:
5462: </dd>
5463:
1.76 mike 5464: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-language"><a href="#dom-audiotrack-language">language</a></code></dt>
5465: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-language"><a href="#dom-videotrack-language">language</a></code></dt>
1.47 mike 5466:
5467: <dd>
5468:
1.76 mike 5469: <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
1.47 mike 5470:
5471: </dd>
5472:
1.76 mike 5473: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-enabled"><a href="#dom-audiotrack-enabled">enabled</a></code> [ = <var title="">value</var> ]</dt>
1.47 mike 5474:
5475: <dd>
5476:
1.76 mike 5477: <p>Returns true if the given track is active, and false otherwise.</p>
5478:
5479: <p>Can be set, to change whether the track is enabled or not. If multiple audio tracks are enabled simultaneously, they are mixed.</p>
1.47 mike 5480:
5481: </dd>
5482:
1.76 mike 5483: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> . <code title="dom-VideoTrackList-selectedIndex"><a href="#dom-videotracklist-selectedindex">selectedIndex</a></code></dt>
1.47 mike 5484:
5485: <dd>
5486:
5487: <p>Returns the index of the currently selected track, if any, or −1 otherwise.</p>
5488:
5489: </dd>
5490:
1.76 mike 5491: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-selected"><a href="#dom-videotrack-selected">selected</a></code> [ = <var title="">value</var> ]</dt>
1.47 mike 5492:
5493: <dd>
5494:
1.76 mike 5495: <p>Returns true if the given track is active, and false otherwise.</p>
5496:
5497: <p>Can be set, to change whether the track is selected or not. Either zero or one video track is selected; selecting a new track while a previous one is selected will unselect the previous one.</p>
1.47 mike 5498:
5499: </dd>
5500:
5501: </dl><div class="impl">
5502:
1.76 mike 5503: <p>An <code><a href="#audiotracklist">AudioTrackList</a></code> object represents a dynamic list
5504: of zero or more audio tracks, of which zero or more can be enabled
5505: at a time. Each audio track is represented by an
5506: <code><a href="#audiotrack">AudioTrack</a></code> object.</p>
5507:
5508: <p>A <code><a href="#videotracklist">VideoTrackList</a></code> object represents a dynamic list of
5509: zero or more video tracks, of which zero or one can be selected at a
5510: time. Each video track is represented by a <code><a href="#videotrack">VideoTrack</a></code>
5511: object.</p>
5512:
5513: <p>Tracks in <code><a href="#audiotracklist">AudioTrackList</a></code> and
5514: <code><a href="#videotracklist">VideoTrackList</a></code> objects must be consistently ordered. If
5515: the <a href="#media-resource">media resource</a> is in a format that defines an
5516: order, then that order must be used; otherwise, the order must be
5517: the relative order in which the tracks are declared in the
5518: <a href="#media-resource">media resource</a>. The order used is called the <i>natural
5519: order</i> of the list.</p>
5520:
5521: <p class="note">Each track in a <code>TrackList</code> thus has an
5522: index; the first has the index 0, and each subsequent track is
5523: numbered one higher than the previous one. If a <a href="#media-resource">media
5524: resource</a> dynamically adds or removes audio or video tracks,
5525: then the indices of the tracks will change dynamically. If the
5526: <a href="#media-resource">media resource</a> changes entirely, then all the previous
5527: tracks will be removed and replaced with new tracks.</p>
5528:
5529: <p>The <dfn id="dom-audiotracklist-length" title="dom-AudioTrackList-length"><code>AudioTrackList.length</code></dfn>
5530: and <dfn id="dom-videotracklist-length" title="dom-VideoTrackList-length"><code>VideoTrackList.length</code></dfn>
5531: attributes must return the number of tracks represented by their
5532: objects at the time of getting.</p>
5533:
5534: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of
5535: <code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code> objects
5536: at any instant are the numbers from zero to the number of tracks
5537: represented by the respective object minus one, if any tracks are
1.142 mike 5538: represented. If an <code><a href="#audiotracklist">AudioTrackList</a></code> or
1.76 mike 5539: <code><a href="#videotracklist">VideoTrackList</a></code> object represents no tracks, it has no
5540: <a href="infrastructure.html#supported-property-indices">supported property indices</a>.</p>
5541:
5542: <p>To <a href="infrastructure.html#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> for a
5543: given index <var title="">index</var> in an
5544: <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> object
5545: <var title="">list</var>, the user agent must return the
5546: <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object that
5547: represents the <var title="">index</var>th track in <var title="">list</var>.</p>
5548:
5549: <p>The <dfn id="dom-audiotracklist-gettrackbyid" title="dom-AudioTrackList-getTrackById"><code>AudioTrackList.getTrackById(<var title="">id</var>)</code></dfn> and <dfn id="dom-videotracklist-gettrackbyid" title="dom-VideoTrackList-getTrackById"><code>VideoTrackList.getTrackById(<var title="">id</var>)</code></dfn> methods must return the first
5550: <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object
5551: (respectively) in the <code><a href="#audiotrack">AudioTrack</a></code> or
5552: <code><a href="#videotrack">VideoTrack</a></code> object (respectively) whose identifier is
5553: equal to the value of the <var title="">id</var> argument (in the
5554: natural order of the list, as defined above). When no tracks match
5555: the given argument, the methods must return null.</p>
5556:
5557: <p>The <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects
5558: represent specific tracks of a <a href="#media-resource">media resource</a>. Each
5559: track can have an identifier, category, label, and language. These
5560: aspects of a track are permanent for the lifetime of the track; even
5561: if a track is removed from a <a href="#media-resource">media resource</a>'s
5562: <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> objects,
5563: those aspects do not change.</p>
5564:
5565: <p>In addition, <code><a href="#audiotrack">AudioTrack</a></code> objects can each be enabled
5566: or disabled; this is the audio track's <i>enabled state</i>. When an
5567: <code><a href="#audiotrack">AudioTrack</a></code> is created, its <i>enabled state</i> must be
5568: set to false (disabled). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
5569: can override this.</p>
5570:
5571: <p>Similarly, a single <code><a href="#videotrack">VideoTrack</a></code> object per
5572: <code><a href="#videotracklist">VideoTrackList</a></code> object can be selected, this is the
1.120 mike 5573: video track's <i>selection state</i>. When a
1.76 mike 5574: <code><a href="#videotrack">VideoTrack</a></code> is created, its <i>selection state</i> must
5575: be set to false (not selected). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
5576: can override this.</p>
5577:
5578: <p>The <dfn id="dom-audiotrack-id" title="dom-AudioTrack-id"><code>AudioTrack.id</code></dfn> and <dfn id="dom-videotrack-id" title="dom-VideoTrack-id"><code>VideTrack.id</code></dfn>
5579: attributes must return the identifier of the track, if it has one,
5580: or the empty string otherwise. If the <a href="#media-resource">media resource</a> is
5581: in a format that supports the <cite>Media Fragments URI</cite>
5582: fragment identifier syntax, the identifier returned for a particular
5583: track must be the same identifier that would enable the track if
5584: used as the name of a track in the track dimension of such a
1.101 mike 5585: fragment identifier. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5586:
1.76 mike 5587: <p>The <dfn id="dom-audiotrack-kind" title="dom-AudioTrack-kind"><code>AudioTrack.kind</code></dfn> and
5588: <dfn id="dom-videotrack-kind" title="dom-VideoTrack-kind"><code>VideoTrack.kind</code></dfn>
5589: attributes must return the category of the track, if it has one, or
5590: the empty string otherwise.</p>
1.47 mike 5591:
5592: <p>The category of a track is the string given in the first column
5593: of the table below that is the most appropriate for the track based
5594: on the definitions in the table's second and third columns, as
5595: determined by the metadata included in the track in the <a href="#media-resource">media
5596: resource</a>. For Ogg files, the Role header of the track gives
5597: the relevant metadata. The cell in the third column of a row says
5598: what the category given in the cell in the first column of that row
5599: applies to; a category is only appropriate for an audio track if it
5600: applies to audio tracks, and a category is only appropriate for
1.76 mike 5601: video tracks if it applies to video tracks. Categories must only be
5602: returned for <code><a href="#audiotrack">AudioTrack</a></code> objects if they are appropriate
5603: for audio, and must only be returned for <code><a href="#videotrack">VideoTrack</a></code>
5604: objects if they are appropriate for video.</p>
1.47 mike 5605:
1.76 mike 5606: </div><table id="dom-TrackList-getKind-categories"><caption>Return values for <code title="dom-AudioTrack-kind"><a href="#dom-audiotrack-kind">AudioTrack.kind()</a></code> and <code title="dom-VideoTrack-kind"><a href="#dom-videotrack-kind">VideoTrack.kind()</a></code></caption>
1.47 mike 5607: <thead><tr><th>Category
5608: </th><th>Definition
5609: </th><th>Applies to...</th>
5610: <th>Examples
1.76 mike 5611: </th></tr></thead><tbody><tr><td>"<dfn id="value-track-kind-alternate" title="value-track-kind-alternate"><code>alternative</code></dfn>"
1.47 mike 5612: </td><td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
5613: </td><td>Audio and video.
1.89 mike 5614: </td><td>Ogg: "audio/alternate" or "video/alternate".
1.47 mike 5615:
1.76 mike 5616: </td></tr><tr><td>"<dfn id="value-track-kind-description" title="value-track-kind-description"><code>description</code></dfn>"
1.47 mike 5617: </td><td>An audio description of a video track.
5618: </td><td>Audio only.
5619: </td><td>Ogg: "audio/audiodesc".
5620:
1.76 mike 5621: </td></tr><tr><td>"<dfn id="value-track-kind-main" title="value-track-kind-main"><code>main</code></dfn>"
1.47 mike 5622: </td><td>The primary audio or video track.
5623: </td><td>Audio and video.
5624: </td><td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
5625:
1.76 mike 5626: </td></tr><tr><td>"<dfn id="value-track-kind-sign" title="value-track-kind-sign"><code>sign</code></dfn>"
1.47 mike 5627: </td><td>A sign-language interpretation of an audio track.
5628: </td><td>Video only.
5629: </td><td>Ogg: "video/sign".
5630:
1.76 mike 5631: </td></tr><tr><td>"<dfn id="value-track-kind-translation" title="value-track-kind-translation"><code>translation</code></dfn>"
1.47 mike 5632: </td><td>A translated version of the main track.
5633: </td><td>Audio only.
5634: </td><td>Ogg: "audio/dub".
5635:
1.76 mike 5636: </td></tr><tr><td>"<dfn id="value-track-kind-commentary" title="value-track-kind-commentary"><code>commentary</code></dfn>"
5637: </td><td>Commentary on the primary audio or video track, e.g. a director's commentary.
5638: </td><td>Audio and video.
5639: </td><td>No known formats expose this category at this time.
5640:
5641: </td></tr><tr><td>"<dfn id="value-track-kind-none" title="value-track-kind-none"><code></code></dfn>" (empty string)
1.47 mike 5642: </td><td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
5643: </td><td>Audio and video.
5644: </td><td>Any other track type or track role.
5645:
5646: </td></tr></tbody></table><div class="impl">
5647:
1.76 mike 5648: <p>The <dfn id="dom-audiotrack-label" title="dom-AudioTrack-label"><code>AudioTrack.label</code></dfn> and
5649: <dfn id="dom-videotrack-label" title="dom-VideoTrack-label"><code>VideoTrack.label</code></dfn>
5650: attributes must return the label of the track, if it has one, or the
5651: empty string otherwise.</p>
5652:
5653: <p>The <dfn id="dom-audiotrack-language" title="dom-AudioTrack-language"><code>AudioTrack.language</code></dfn>
5654: and <dfn id="dom-videotrack-language" title="dom-VideoTrack-language"><code>VideoTrack.language</code></dfn>
5655: attributes must return the BCP 47 language tag of the language of
5656: the track, if it has one, or the empty string otherwise. If the user
1.47 mike 5657: agent is not able to express that language as a BCP 47 language tag
5658: (for example because the language information in the <a href="#media-resource">media
5659: resource</a>'s format is a free-form string without a defined
1.76 mike 5660: interpretation), then the method must return the empty string, as if
5661: the track had no language.</p>
1.47 mike 5662:
1.76 mike 5663: <p>The <dfn id="dom-audiotrack-enabled" title="dom-AudioTrack-enabled"><code>AudioTrack.enabled</code></dfn>
5664: attribute, on getting, must return true if the track is currently
5665: enabled, and false otherwise. On setting, it must enable the track
5666: if the new value is true, and disable it otherwise. (If the track is
5667: no longer in an <code><a href="#audiotracklist">AudioTrackList</a></code> object, then the track
5668: being enabled or disabled has no effect beyond changing the value of
5669: the attribute on the <code><a href="#audiotrack">AudioTrack</a></code> object.)</p>
5670:
5671: <p>Whenever an audio track in an <code><a href="#audiotracklist">AudioTrackList</a></code> is
5672: enabled or disabled, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
5673: to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-change">change</code> at the
5674: <code><a href="#audiotracklist">AudioTrackList</a></code> object.</p>
5675:
5676: <p>The <dfn id="dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex"><code>VideoTrackList.selectedIndex</code></dfn>
5677: attribute must return the index of the currently selected track, if
5678: any. If the <code><a href="#videotracklist">VideoTrackList</a></code> object does not currently
5679: represent any tracks, or if none of the tracks are selected, it must
5680: instead return −1.</p>
5681:
5682: <p>The <dfn id="dom-videotrack-selected" title="dom-VideoTrack-selected"><code>VideoTrack.selected</code></dfn>
5683: attribute, on getting, must return true if the track is currently
5684: selected, and false otherwise. On setting, it must select the track
5685: if the new value is true, and unselect it otherwise. If the track is
5686: in a <code><a href="#videotracklist">VideoTrackList</a></code>, then all the other
5687: <code><a href="#videotrack">VideoTrack</a></code> objects in that list must be unselected. (If
5688: the track is no longer in a <code><a href="#videotracklist">VideoTrackList</a></code> object, then
5689: the track being selected or unselected has no effect beyond changing
5690: the value of the attribute on the <code><a href="#videotrack">VideoTrack</a></code>
5691: object.)</p>
5692:
5693: <p>Whenever a track in a <code><a href="#videotracklist">VideoTrackList</a></code> that was
5694: previously not selected is selected, the user agent must <a href="webappapis.html#queue-a-task">queue
5695: a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-change">change</code> at the
5696: <code><a href="#videotracklist">VideoTrackList</a></code> object.</p>
1.47 mike 5697:
5698: <hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
5699: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
5700: event types</a>) that must be supported, as IDL attributes, by
1.76 mike 5701: all objects implementing the <code><a href="#audiotracklist">AudioTrackList</a></code> and
5702: <code><a href="#videotracklist">VideoTrackList</a></code> interfaces:</p>
1.47 mike 5703:
5704: <table><thead><tr><th><a href="webappapis.html#event-handlers" title="event handlers">Event handler</a> </th><th><a href="webappapis.html#event-handler-event-type">Event handler event type</a>
5705: </th></tr></thead><tbody><tr><td><dfn id="handler-tracklist-onchange" title="handler-TrackList-onchange"><code>onchange</code></dfn> </td><td> <code title="event-change">change</code>
1.121 mike 5706: </td></tr><tr><td><dfn id="handler-tracklist-onaddtrack" title="handler-TrackList-onaddtrack"><code>onaddtrack</code></dfn> </td><td> <code title="event-addtrack">addtrack</code>
1.47 mike 5707: </td></tr></tbody></table><hr><p>The <a href="webappapis.html#task-source">task source</a> for the <a href="webappapis.html#concept-task" title="concept-task">tasks</a> listed in this section is the
5708: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5709:
5710:
5711:
5712: </div><h6 id="selecting-specific-audio-and-video-tracks-declaratively"><span class="secno">4.8.10.10.2 </span>Selecting specific audio and video tracks declaratively</h6><p>The <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> and
5713: <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attributes
5714: allow scripts to select which track should play, but it is also
5715: possible to select specific tracks declaratively, by specifying
5716: particular tracks in the fragment identifier of the <a href="urls.html#url">URL</a>
5717: of the <a href="#media-resource">media resource</a>. The format of the fragment
5718: identifier depends on the <a href="infrastructure.html#mime-type">MIME type</a> of the <a href="#media-resource">media
1.101 mike 5719: resource</a>. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3986">[RFC3986]</a></p><div class="example">
1.47 mike 5720:
5721: <p>In this example, a video that uses a format that supports the
5722: <cite>Media Fragments URI</cite> fragment identifier syntax is
5723: embedded in such a way that the alternative angles labeled
1.101 mike 5724: "Alternative" are enabled instead of the default video track. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5725:
5726: <pre><video src="myvideo#track=Alternative"></video></pre>
5727:
5728:
5729: </div><h5 id="synchronising-multiple-media-elements"><span class="secno">4.8.10.11 </span>Synchronising multiple media elements</h5><h6 id="introduction-0"><span class="secno">4.8.10.11.1 </span>Introduction</h6><p>Each <a href="#media-element">media element</a> can have a
5730: <code><a href="#mediacontroller">MediaController</a></code>. A <code><a href="#mediacontroller">MediaController</a></code> is an
5731: object that coordinates the playback of multiple <a href="#media-element" title="media
5732: element">media elements</a>, for instance so that a sign-language
5733: interpreter track can be overlaid on a video track, with the two
5734: being kept in sync.</p><p>By default, a <a href="#media-element">media element</a> has no
5735: <code><a href="#mediacontroller">MediaController</a></code>. An implicit
5736: <code><a href="#mediacontroller">MediaController</a></code> can be assigned using the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content attribute.
5737: An explicit <code><a href="#mediacontroller">MediaController</a></code> can be assigned directly
5738: using the <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> IDL
5739: attribute.</p><p><a href="#media-element" title="media element">Media elements</a> with a
5740: <code><a href="#mediacontroller">MediaController</a></code> are said to be <i>slaved</i> to their
5741: controller. The <code><a href="#mediacontroller">MediaController</a></code> modifies the playback
5742: rate and the playback volume of each of the <a href="#media-element" title="media
5743: element">media elements</a> slaved to it, and ensures that when
5744: any of its slaved <a href="#media-element" title="media element">media elements</a>
5745: unexpectedly stall, the others are stopped at the same time.</p><p>When a <a href="#media-element">media element</a> is slaved to a
5746: <code><a href="#mediacontroller">MediaController</a></code>, its playback rate is fixed to that of
5747: the other tracks in the same <code><a href="#mediacontroller">MediaController</a></code>, and any
5748: looping is disabled.</p><h6 id="media-controllers"><span class="secno">4.8.10.11.2 </span>Media controllers</h6><pre class="idl">[<a href="#dom-mediacontroller" title="dom-MediaController">Constructor</a>]
5749: interface <dfn id="mediacontroller">MediaController</dfn> {
5750: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-buffered" title="dom-MediaController-buffered">buffered</a>;
5751: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-seekable" title="dom-MediaController-seekable">seekable</a>;
5752: readonly attribute double <a href="#dom-mediacontroller-duration" title="dom-MediaController-duration">duration</a>;
5753: attribute double <a href="#dom-mediacontroller-currenttime" title="dom-MediaController-currentTime">currentTime</a>;
5754:
5755: readonly attribute boolean <a href="#dom-mediacontroller-paused" title="dom-MediaController-paused">paused</a>;
5756: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-played" title="dom-MediaController-played">played</a>;
5757: void <a href="#dom-mediacontroller-play" title="dom-MediaController-play">play</a>();
5758: void <a href="#dom-mediacontroller-pause" title="dom-MediaController-pause">pause</a>();
5759:
5760: attribute double <a href="#dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate">defaultPlaybackRate</a>;
5761: attribute double <a href="#dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate">playbackRate</a>;
5762:
5763: attribute double <a href="#dom-mediacontroller-volume" title="dom-MediaController-volume">volume</a>;
5764: attribute boolean <a href="#dom-mediacontroller-muted" title="dom-MediaController-muted">muted</a>;
5765:
1.118 mike 5766: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onemptied" title="handler-MediaController-onemptied">onemptied</a>;
5767: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata">onloadedmetadata</a>;
5768: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata">onloadeddata</a>;
5769: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay">oncanplay</a>;
5770: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough">oncanplaythrough</a>;
5771: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onplaying" title="handler-MediaController-onplaying">onplaying</a>;
5772: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onended" title="handler-MediaController-onended">onended</a>;
5773: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting">onwaiting</a>;
5774:
5775: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange">ondurationchange</a>;
5776: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate">ontimeupdate</a>;
5777: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onplay" title="handler-MediaController-onplay">onplay</a>;
5778: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onpause" title="handler-MediaController-onpause">onpause</a>;
5779: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onratechange" title="handler-MediaController-onratechange">onratechange</a>;
5780: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange">onvolumechange</a>;
1.47 mike 5781: };</pre><dl class="domintro"><dt><var title="">controller</var> = new <code title="dom-MediaController"><a href="#dom-mediacontroller">MediaController</a></code>()</dt>
5782:
5783: <dd>
5784:
5785: <p>Returns a new <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5786:
5787: </dd>
5788:
5789: <dt><var title="">media</var> . <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> [ = <var title="">controller</var> ]</dt>
5790:
5791: <dd>
5792:
5793: <p>Returns the current <code><a href="#mediacontroller">MediaController</a></code> for the <a href="#media-element">media element</a>, if any; returns null otherwise.</p>
5794:
5795: <p>Can be set, to set an explicit <code><a href="#mediacontroller">MediaController</a></code>.
5796: Doing so removes the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if
5797: any.</p>
5798:
5799: </dd>
5800:
5801: <dt><var title="">controller</var> . <code title="dom-MediaController-buffered"><a href="#dom-mediacontroller-buffered">buffered</a></code></dt>
5802:
5803: <dd>
5804:
5805: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5806: intersection of the time ranges for which the user agent has all
5807: relevant media data for all the slaved <a href="#media-element" title="media
5808: element">media elements</a>.</p>
5809:
5810: </dd>
5811:
5812: <dt><var title="">controller</var> . <code title="dom-MediaController-seekable"><a href="#dom-mediacontroller-seekable">seekable</a></code></dt>
5813:
5814: <dd>
5815:
5816: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5817: intersection of the time ranges into which the user agent can seek
5818: for all the slaved <a href="#media-element" title="media element">media
5819: elements</a>.</p>
5820:
5821: </dd>
5822:
5823: <dt><var title="">controller</var> . <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code></dt>
5824:
5825: <dd>
5826:
5827: <p>Returns the difference between the earliest playable moment and
5828: the latest playable moment (not considering whether the data in
5829: question is actually buffered or directly seekable, but not
5830: including time in the future for infinite streams). Will return
5831: zero if there is no media.</p>
5832:
5833: </dd>
5834:
5835: <dt><var title="">controller</var> . <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
5836:
5837: <dd>
5838:
5839: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds,
5840: as a position between zero time and the current <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code>.</p>
5841:
5842: <p>Can be set, to seek to the given time.</p><p>
5843:
5844: </p></dd>
5845:
5846: <dt><var title="">controller</var> . <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code></dt>
5847:
5848: <dd>
5849:
5850: <p>Returns true if playback is paused; false otherwise. When this
5851: attribute is true, any <a href="#media-element">media element</a> slaved to this
5852: controller will be stopped.</p>
5853:
5854: </dd>
5855:
1.113 mike 5856: <dt><var title="">controller</var> . <code title="dom-MediaController-play"><a href="#dom-mediacontroller-play">play</a></code>()</dt>
1.47 mike 5857:
5858: <dd>
5859:
1.113 mike 5860: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5861: attribute to false.</p>
1.47 mike 5862:
5863: </dd>
5864:
1.113 mike 5865: <dt><var title="">controller</var> . <code title="dom-MediaController-pause"><a href="#dom-mediacontroller-pause">pause</a></code>()</dt>
1.47 mike 5866:
5867: <dd>
5868:
5869: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
1.113 mike 5870: attribute to true.</p>
1.47 mike 5871:
5872: </dd>
5873:
1.113 mike 5874: <dt><var title="">controller</var> . <code title="dom-MediaController-played"><a href="#dom-mediacontroller-played">played</a></code></dt>
1.47 mike 5875:
5876: <dd>
5877:
1.113 mike 5878: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5879: union of the time ranges in all the slaved <a href="#media-element" title="media
5880: element">media elements</a> that have been played.</p>
1.47 mike 5881:
5882: </dd>
5883:
5884: <dt><var title="">controller</var> . <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
5885:
5886: <dd>
5887:
5888: <p>Returns the default rate of playback.</p>
5889:
5890: <p>Can be set, to change the default rate of playback.</p>
5891:
5892: <p>This default rate has no direct effect on playback, but if the
5893: user switches to a fast-forward mode, when they return to the
5894: normal playback mode, it is expected that rate of playback (<code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code>) will
5895: be returned to this default rate.</p>
5896:
5897: </dd>
5898:
5899: <dt><var title="">controller</var> . <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
5900:
5901: <dd>
5902:
5903: <p>Returns the current rate of playback.</p>
5904:
5905: <p>Can be set, to change the rate of playback.</p>
5906:
5907: </dd>
5908:
5909: <dt><var title="">controller</var> . <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
5910:
5911: <dd>
5912:
5913: <p>Returns the current playback volume multiplier, as a number in
5914: the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the
5915: loudest.</p>
5916:
5917: <p>Can be set, to change the volume multiplier.</p>
5918:
1.119 mike 5919: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the new value is not
1.47 mike 5920: in the range 0.0 .. 1.0.</p>
5921:
5922: </dd>
5923:
5924: <dt><var title="">controller</var> . <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
5925:
5926: <dd>
5927:
5928: <p>Returns true if all audio is muted (regardless of other
5929: attributes either on the controller or on any <a href="#media-element" title="media
5930: element">media elements</a> slaved to this controller), and
5931: false otherwise.</p>
5932:
5933: <p>Can be set, to change whether the audio is muted or not.</p>
5934:
5935: </dd>
5936:
5937: </dl><div class="impl">
5938:
5939: <p>A <a href="#media-element">media element</a> can have a <dfn id="current-media-controller">current media
5940: controller</dfn>, which is a <code><a href="#mediacontroller">MediaController</a></code> object.
5941: When a <a href="#media-element">media element</a> is created without a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, it does
5942: not have a <a href="#current-media-controller">current media controller</a>. (If it is created
5943: <em>with</em> such an attribute, then that attribute initializes the
5944: <a href="#current-media-controller">current media controller</a>, as defined below.)</p>
5945:
5946: <p>The <dfn id="slaved-media-elements">slaved media elements</dfn> of a
5947: <code><a href="#mediacontroller">MediaController</a></code> are the <a href="#media-element" title="media
5948: element">media elements</a> whose <a href="#current-media-controller">current media
5949: controller</a> is that <code><a href="#mediacontroller">MediaController</a></code>. All the
5950: <a href="#slaved-media-elements">slaved media elements</a> of a <code><a href="#mediacontroller">MediaController</a></code>
5951: must use the same clock for their definition of their <a href="#media-timeline">media
5952: timeline</a>'s unit time.</p>
5953:
5954: <hr><p>The <dfn id="dom-media-controller" title="dom-media-controller"><code>controller</code></dfn> attribute
5955: on a <a href="#media-element">media element</a>, on getting, must return the
5956: element's <a href="#current-media-controller">current media controller</a>, if any, or null
5957: otherwise. On setting, it must first remove the element's <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if any,
5958: and then set the <a href="#current-media-controller">current media controller</a> to the given
5959: value. If the given value is null, the element no longer has a
5960: <a href="#current-media-controller">current media controller</a>; if it is not null, then the
5961: user agent must <a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">bring the media element up to speed with its
5962: new media controller</a>.</p>
5963:
5964: <hr><p>The <dfn id="dom-mediacontroller" title="dom-MediaController"><code>MediaController()</code></dfn>
5965: constructor, when invoked, must return a newly created
5966: <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5967:
5968: <hr><p>The <dfn id="dom-mediacontroller-seekable" title="dom-MediaController-seekable"><code>seekable</code></dfn>
5969: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5970: <code>TimeRanges</code> object</a> that represents the
5971: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5972: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5973: user agent is able to seek to, at the time the attribute is
5974: evaluated.</p>
5975:
5976: <p>The <dfn id="dom-mediacontroller-buffered" title="dom-MediaController-buffered"><code>buffered</code></dfn>
5977: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5978: <code>TimeRanges</code> object</a> that represents the
5979: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5980: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5981: user agent has buffered, at the time the attribute is evaluated.
5982: Users agents must accurately determine the ranges available, even
5983: for media streams where this can only be determined by tedious
5984: inspection.</p>
5985:
5986: <p>The <dfn id="dom-mediacontroller-duration" title="dom-MediaController-duration"><code>duration</code></dfn>
5987: attribute must return the <a href="#media-controller-duration">media controller
5988: duration</a>.</p>
5989:
5990: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5991: <a href="#media-controller-duration">media controller duration</a> changes, whichever happens
5992: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5993: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-MediaController-durationchange"><a href="#event-mediacontroller-durationchange">durationchange</a></code>
5994: at the <code><a href="#mediacontroller">MediaController</a></code>. If the
5995: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-duration">media controller
5996: duration</a> decreases such that the <a href="#media-controller-position">media controller
5997: position</a> is greater than the <a href="#media-controller-duration">media controller
5998: duration</a>, the user agent must immediately <a href="#seek-the-media-controller">seek the
5999: media controller</a> to <a href="#media-controller-duration">media controller
6000: duration</a>.</p>
6001:
6002: <p>The <dfn id="dom-mediacontroller-currenttime" title="dom-MediaController-currentTime"><code>currentTime</code></dfn>
6003: attribute must return the <a href="#media-controller-position">media controller position</a> on
6004: getting, and on setting must <a href="#seek-the-media-controller">seek the media controller</a>
6005: to the new value.</p>
6006:
6007: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
6008: <a href="#media-controller-position">media controller position</a> changes, whichever happens
6009: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
6010: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-MediaController-timeupdate"><a href="#event-mediacontroller-timeupdate">timeupdate</a></code> at the
6011: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6012:
6013: <hr><p>When a <code><a href="#mediacontroller">MediaController</a></code> is created it is a
6014: <dfn id="playing-media-controller">playing media controller</dfn>. It can be changed into a
6015: <dfn id="paused-media-controller">paused media controller</dfn> and back either via the user
6016: agent's user interface (when the element is <a href="#expose-a-user-interface-to-the-user" title="expose a
6017: user interface to the user">exposing a user interface to the
6018: user</a>) or by script using the APIs defined in this section
6019: (see below).</p>
6020:
6021: <p>The <dfn id="dom-mediacontroller-paused" title="dom-MediaController-paused"><code>paused</code></dfn>
6022: attribute must return true if the <code><a href="#mediacontroller">MediaController</a></code>
6023: object is a <a href="#paused-media-controller">paused media controller</a>, and false
6024: otherwise.</p>
6025:
6026: <p>When the <dfn id="dom-mediacontroller-pause" title="dom-MediaController-pause"><code>pause()</code></dfn> method
6027: is invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#playing-media-controller">playing
6028: media controller</a> then the user agent must change the
6029: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#paused-media-controller">paused media
6030: controller</a>, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
6031: event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
6032: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
6033: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
6034:
6035: <p>When the <dfn id="dom-mediacontroller-play" title="dom-MediaController-play"><code>play()</code></dfn> method is
6036: invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#paused-media-controller">paused media
6037: controller</a>, the user agent must change the
6038: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#playing-media-controller">playing media
6039: controller</a>, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
6040: event</a> named <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code> at the
6041: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
6042: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
6043:
1.113 mike 6044: <p>The <dfn id="dom-mediacontroller-played" title="dom-MediaController-played"><code>played</code></dfn>
6045: attribute must return a new static <a href="#normalized-timeranges-object">normalized
6046: <code>TimeRanges</code> object</a> that represents the union of
6047: the ranges of the <a href="#media-resource" title="media resource">media
6048: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
6049: user agent has so far rendered, at the time the attribute is
6050: evaluated.</p>
6051:
1.47 mike 6052: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-default-playback-rate">media controller
6053: default playback rate</dfn> and a <dfn id="media-controller-playback-rate">media controller playback
6054: rate</dfn>, which must both be set to 1.0 when the
6055: <code><a href="#mediacontroller">MediaController</a></code> object is created.</p>
6056:
6057: <p>The <dfn id="dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
6058: attribute, on getting, must return the
6059: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
6060: playback rate</a>, and on setting, must set the
6061: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
6062: playback rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a
6063: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-MediaController-ratechange"><a href="#event-mediacontroller-ratechange">ratechange</a></code> at the
6064: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6065:
6066: <p>The <dfn id="dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate"><code>playbackRate</code></dfn>
6067: attribute, on getting, must return the
6068: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
6069: rate</a>, and on setting, must set the
6070: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
6071: rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a task</a> to
6072: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-MediaController-ratechange"><a href="#event-mediacontroller-ratechange">ratechange</a></code> at the
6073: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6074:
6075: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-volume-multiplier">media controller volume
6076: multiplier</dfn>, which must be set to 1.0 when the
6077: <code><a href="#mediacontroller">MediaController</a></code> object is created, and a <dfn id="media-controller-mute-override">media
6078: controller mute override</dfn>, much must initially be false.</p>
6079:
6080: <p>The <dfn id="dom-mediacontroller-volume" title="dom-MediaController-volume"><code>volume</code></dfn>
6081: attribute, on getting, must return the
6082: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-volume-multiplier">media controller volume
6083: multiplier</a>, and on setting, if the new value is in the range
6084: 0.0 to 1.0 inclusive, must set the <code><a href="#mediacontroller">MediaController</a></code>'s
6085: <a href="#media-controller-volume-multiplier">media controller volume multiplier</a> to the new value and
6086: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
6087: <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
6088: at the <code><a href="#mediacontroller">MediaController</a></code>. If the new value is outside the
6089: range 0.0 to 1.0 inclusive, then, on setting, an
1.119 mike 6090: <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exception must be raised instead.</p>
1.47 mike 6091:
6092: <p>The <dfn id="dom-mediacontroller-muted" title="dom-MediaController-muted"><code>muted</code></dfn>
6093: attribute, on getting, must return the
6094: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
6095: override</a>, and on setting, must set the
6096: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
6097: override</a> to the new value and <a href="webappapis.html#queue-a-task">queue a task</a> to
6098: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code> at
6099: the <code><a href="#mediacontroller">MediaController</a></code>.</p>
6100:
6101: <hr><p>The <a href="#media-resource" title="media resource">media resources</a> of all
6102: the <a href="#slaved-media-elements">slaved media elements</a> of a
6103: <code><a href="#mediacontroller">MediaController</a></code> have a defined temporal relationship
6104: which provides relative offsets between the zero time of each such
6105: <a href="#media-resource">media resource</a>: for <a href="#media-resource" title="media resource">media
6106: resources</a> with a <a href="#timeline-offset">timeline offset</a>, their relative
6107: offsets are the difference between their <a href="#timeline-offset">timeline
6108: offset</a>; the zero times of all the <a href="#media-resource" title="media
6109: resource">media resources</a> without a <a href="#timeline-offset">timeline
6110: offset</a> are not offset from each other (i.e. the origins of
6111: their timelines are cotemporal); and finally, the zero time of the
6112: <a href="#media-resource">media resource</a> with the earliest <a href="#timeline-offset">timeline
6113: offset</a> (if any) is not offset from the zero times of the
6114: <a href="#media-resource" title="media resource">media resources</a> without a
6115: <a href="#timeline-offset">timeline offset</a> (i.e. the origins of <a href="#media-resource" title="media
6116: resource">media resources</a> without a <a href="#timeline-offset">timeline
6117: offset</a> are further cotemporal with the earliest defined point
6118: on the timeline of the <a href="#media-resource">media resource</a> with the earliest
6119: <a href="#timeline-offset">timeline offset</a>).</p>
6120:
6121: <p>The <dfn id="media-resource-end-position">media resource end position</dfn> of a <a href="#media-resource">media
6122: resource</a> in a <a href="#media-element">media element</a> is defined as
6123: follows: if the <a href="#media-resource">media resource</a> has a finite and known
6124: duration, the <a href="#media-resource-end-position">media resource end position</a> is the
6125: duration of the <a href="#media-resource">media resource</a>'s timeline (the last
6126: defined position on that timeline); otherwise, the <a href="#media-resource">media
6127: resource</a>'s duration is infinite or unknown, and the
6128: <a href="#media-resource-end-position">media resource end position</a> is the time of the last
6129: frame of <a href="#media-data">media data</a> currently available for that
6130: <a href="#media-resource">media resource</a>.</p>
6131:
6132: <p>Each <code><a href="#mediacontroller">MediaController</a></code> also has its own defined
6133: timeline. On this timeline, all the <a href="#media-resource" title="media
6134: resource">media resources</a> of all the <a href="#slaved-media-elements">slaved media
6135: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code> are temporally
6136: aligned according to their defined offsets. The <dfn id="media-controller-duration">media
6137: controller duration</dfn> of that <code><a href="#mediacontroller">MediaController</a></code> is
6138: the time from the earliest <a href="#earliest-possible-position">earliest possible position</a>,
6139: relative to this <code><a href="#mediacontroller">MediaController</a></code> timeline, of any of
6140: the <a href="#media-resource" title="media resource">media resources</a> of the
6141: <a href="#slaved-media-elements">slaved media elements</a> of the
6142: <code><a href="#mediacontroller">MediaController</a></code>, to the time of the latest <a href="#media-resource-end-position">media
6143: resource end position</a> of the <a href="#media-resource" title="media
6144: resource">media resources</a> of the <a href="#slaved-media-elements">slaved media
6145: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code>, again relative
6146: to this <code><a href="#mediacontroller">MediaController</a></code> timeline.</p>
6147:
6148: <p>Each <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-position">media controller
6149: position</dfn>. This is the time on the
6150: <code><a href="#mediacontroller">MediaController</a></code>'s timeline at which the user agent is
6151: trying to play the <a href="#slaved-media-elements">slaved media elements</a>. When a
6152: <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#media-controller-position">media controller
6153: position</a> is initially zero.</p>
6154:
6155: <p>When the user agent is to <dfn id="bring-the-media-element-up-to-speed-with-its-new-media-controller" title="bring the media element up
6156: to speed with its new media controller">bring a media element up to
6157: speed with its new media controller</dfn>, it must <a href="#dom-media-seek" title="dom-media-seek">seek</a> that <a href="#media-element">media element</a>
6158: to the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-position">media controller
6159: position</a> relative to the <a href="#media-element">media element</a>'s
1.107 mike 6160: timeline.</p>
1.47 mike 6161:
6162: <p>When the user agent is to <dfn id="seek-the-media-controller">seek the media controller</dfn> to
6163: a particular <var title="">new playback position</var>, it must
6164: follow these steps:</p>
6165:
6166: <ol><li><p>If the <var title="">new playback position</var> is less
6167: than zero, then set it to zero.</p></li>
6168:
6169: <li><p>If the <var title="">new playback position</var> is greater
6170: than the <a href="#media-controller-duration">media controller duration</a>, then set it to the
6171: <a href="#media-controller-duration">media controller duration</a>.</p></li>
6172:
6173: <li><p>Set the <a href="#media-controller-position">media controller position</a> to the <var title="">new playback position</var>.</p></li>
6174:
6175: <li><p><a href="#dom-media-seek" title="dom-media-seek">Seek</a> each <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a> to the
6176: <var title="">new playback position</var> relative to the
1.107 mike 6177: <a href="#media-element">media element</a> timeline.</p></li>
1.47 mike 6178: </ol><p>A <code><a href="#mediacontroller">MediaController</a></code> is a <dfn id="blocked-media-controller">blocked media
6179: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
6180: <a href="#paused-media-controller">paused media controller</a>, or if any of its <a href="#slaved-media-elements">slaved
6181: media elements</a> are <a href="#blocked-media-element" title="blocked media
6182: element">blocked media elements</a>, or if any of its
6183: <a href="#slaved-media-elements">slaved media elements</a> whose <a href="#autoplaying-flag">autoplaying
1.70 mike 6184: flag</a> is true still have their <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute set to true, or if
1.47 mike 6185: all of its <a href="#slaved-media-elements">slaved media elements</a> have their <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute set to true.</p>
6186:
6187: <p>A <a href="#media-element">media element</a> is <dfn id="blocked-on-its-media-controller">blocked on its media
6188: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
6189: <a href="#blocked-media-controller">blocked media controller</a>, or if its <a href="#media-controller-position">media
6190: controller position</a> is either before the <a href="#media-resource">media
6191: resource</a>'s <a href="#earliest-possible-position">earliest possible position</a> relative
6192: to the <code><a href="#mediacontroller">MediaController</a></code>'s timeline or after the end of
6193: the <a href="#media-resource">media resource</a> relative to the
6194: <code><a href="#mediacontroller">MediaController</a></code>'s timeline.</p>
6195:
6196: <p id="controller-playback">When a <code><a href="#mediacontroller">MediaController</a></code> is
6197: not a <a href="#blocked-media-controller">blocked media controller</a> and it has at least one
6198: <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a>
6199: whose <code><a href="infrastructure.html#document">Document</a></code> is a <a href="browsers.html#fully-active">fully active</a>
6200: <code><a href="infrastructure.html#document">Document</a></code>, the <code><a href="#mediacontroller">MediaController</a></code>'s
6201: <a href="#media-controller-position">media controller position</a> must increase monotonically
6202: at <a href="#media-controller-playback-rate">media controller playback rate</a> units of time on the
6203: <code><a href="#mediacontroller">MediaController</a></code>'s timeline per unit time of the clock
6204: used by its <a href="#slaved-media-elements">slaved media elements</a>.</p>
6205:
6206: <p>When the zero point on the timeline of a
6207: <code><a href="#mediacontroller">MediaController</a></code> moves relative to the timelines of the
6208: <a href="#slaved-media-elements">slaved media elements</a> by a time difference <var title="">ΔT</var>, the <code><a href="#mediacontroller">MediaController</a></code>'s
6209: <a href="#media-controller-position">media controller position</a> must be decremented by <var title="">ΔT</var>.</p>
6210:
6211: <p class="note">In some situations, e.g. when playing back a live
6212: stream without buffering anything, the <a href="#media-controller-position">media controller
1.125 mike 6213: position</a> would increase monotonically as described above at the
1.47 mike 6214: same rate as the <var title="">ΔT</var> described in the
6215: previous paragraph decreases it, with the end result that for all
6216: intents and purposes, the <a href="#media-controller-position">media controller position</a>
6217: would appear to remain constant (probably with the value 0).</p>
6218:
6219: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="most-recently-reported-readiness-state">most recently reported
6220: readiness state</dfn>, which is a number from 0 to 4 derived from
6221: the numbers used for the <a href="#media-element">media element</a> <code title="attr-media-readyState">readyState</code> attribute, and a
6222: <dfn id="most-recently-reported-playback-state">most recently reported playback state</dfn>, which is either
6223: <i>playing</i>, <i>waiting</i>, or <i>ended</i>.</p>
6224:
6225: <p>When a <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#most-recently-reported-readiness-state">most
6226: recently reported readiness state</a> must be set to 0, and its
6227: <a href="#most-recently-reported-playback-state">most recently reported playback state</a> must be set to
6228: <i>waiting</i>.</p>
6229:
6230: <p>When a user agent is required to <dfn id="report-the-controller-state">report the controller
6231: state</dfn> for a <code><a href="#mediacontroller">MediaController</a></code>, the user agent must
6232: run the following steps:</p>
6233:
6234: <ol><li>
6235:
6236: <p>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved media
6237: elements</a>, let <var title="">new readiness state</var> be
6238: 0.</p>
6239:
6240: <p>Otherwise, let it have the lowest value of the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> IDL attributes of
6241: all of its <a href="#slaved-media-elements">slaved media elements</a>.</p>
6242:
6243: </li>
6244:
6245: <li>
6246:
6247: <p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
6248: reported readiness state</a> is not equal to <var title="">new
6249: readiness state</var> then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
6250: a simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
6251: whose name is the event name corresponding to the value of <var title="">new readiness state</var> given in the table below:</p>
6252:
6253:
6254: <table><thead><tr><th>Value of <var title="">new readiness state</var>
6255: </th><th>Event name
6256:
6257: </th></tr></thead><tbody><tr><td> 0
6258: </td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
6259:
6260: </td></tr><tr><td> 1
6261: </td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
6262:
6263: </td></tr><tr><td> 2
6264: </td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
6265:
6266: </td></tr><tr><td> 3
6267: </td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
6268:
6269: </td></tr><tr><td> 4
6270: </td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
6271:
6272: </td></tr></tbody></table></li>
6273:
6274: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
6275: reported readiness state</a> be <var title="">new readiness
6276: state</var>.</p></li>
6277:
6278: <li>
6279:
6280: <p>Initialize <var title="">new playback state</var> by setting it
6281: to the state given for the first matching condition from the
6282: following list:</p>
6283:
6284: <dl class="switch"><dt>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved
6285: media elements</a></dt>
6286:
6287: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
6288:
6289: <dt>If all of the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#slaved-media-elements">slaved
6290: media elements</a> have <a href="#ended-playback">ended playback</a> and the
6291: <a href="#media-controller-playback-rate">media controller playback rate</a> is positive or
6292: zero</dt>
6293:
6294: <dd>Let <var title="">new playback state</var> be <i>ended</i>.</dd>
6295:
6296: <dt>If the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#blocked-media-controller">blocked media
6297: controller</a></dt>
6298:
6299: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
6300:
6301: <dt>Otherwise</dt>
6302:
6303: <dd>Let <var title="">new playback state</var> be <i>playing</i>.</dd>
6304:
6305: </dl></li>
6306:
6307: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6308: reported playback state</a> is not equal to <var title="">new
1.113 mike 6309: playback state</var> and the <var title="">new playback state</var>
6310: is <i>ended</i>, then <a href="webappapis.html#queue-a-task">queue a task</a> that, if the
6311: <code><a href="#mediacontroller">MediaController</a></code> object is a <a href="#playing-media-controller">playing media
6312: controller</a>, and all of the <code><a href="#mediacontroller">MediaController</a></code>'s
6313: <a href="#slaved-media-elements">slaved media elements</a> have still <a href="#ended-playback">ended
6314: playback</a>, and the <a href="#media-controller-playback-rate">media controller playback
6315: rate</a> is still positive or zero, changes the
6316: <code><a href="#mediacontroller">MediaController</a></code> object to a <a href="#paused-media-controller">paused media
6317: controller</a> and then <a href="webappapis.html#fire-a-simple-event" title="fire a simple event">fires
6318: a simple event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
6319: <code><a href="#mediacontroller">MediaController</a></code> object.</p></li>
6320:
6321: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6322: reported playback state</a> is not equal to <var title="">new
1.47 mike 6323: playback state</var> then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
6324: simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
1.75 mike 6325: whose name is <code title="event-MediaController-playing"><a href="#event-mediacontroller-playing">playing</a></code> if <var title="">new playback state</var> is <i>playing</i>, <code title="event-MediaController-ended"><a href="#event-mediacontroller-ended">ended</a></code> if <var title="">new playback state</var> is <i>ended</i>, and <code title="event-MediaController-waiting"><a href="#event-mediacontroller-waiting">waiting</a></code>
1.47 mike 6326: otherwise.</p></li>
6327:
6328: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6329: reported playback state</a> be <var title="">new playback
6330: state</var>.</p></li>
6331:
1.121 mike 6332: </ol><hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
6333: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
6334: event types</a>) that must be supported, as IDL attributes, by
6335: all objects implementing the <code><a href="#mediacontroller">MediaController</a></code>
6336: interface:</p>
1.47 mike 6337:
6338: <table><thead><tr><th><a href="webappapis.html#event-handlers" title="event handlers">Event handler</a> </th><th><a href="webappapis.html#event-handler-event-type">Event handler event type</a>
6339: </th></tr></thead><tbody><tr><td><dfn id="handler-mediacontroller-onemptied" title="handler-MediaController-onemptied"><code>onemptied</code></dfn> </td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
6340: </td></tr><tr><td><dfn id="handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata"><code>onloadedmetadata</code></dfn> </td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
6341: </td></tr><tr><td><dfn id="handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata"><code>onloadeddata</code></dfn> </td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
6342: </td></tr><tr><td><dfn id="handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay"><code>oncanplay</code></dfn> </td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
6343: </td></tr><tr><td><dfn id="handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough"><code>oncanplaythrough</code></dfn> </td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
6344: </td></tr><tr><td><dfn id="handler-mediacontroller-onplaying" title="handler-MediaController-onplaying"><code>onplaying</code></dfn> </td><td> <code title="event-MediaController-playing"><a href="#event-mediacontroller-playing">playing</a></code>
1.75 mike 6345: </td></tr><tr><td><dfn id="handler-mediacontroller-onended" title="handler-MediaController-onended"><code>onended</code></dfn> </td><td> <code title="event-MediaController-ended"><a href="#event-mediacontroller-ended">ended</a></code>
1.47 mike 6346: </td></tr><tr><td><dfn id="handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting"><code>onwaiting</code></dfn> </td><td> <code title="event-MediaController-waiting"><a href="#event-mediacontroller-waiting">waiting</a></code>
6347: </td></tr></tbody><tbody><tr><td><dfn id="handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange"><code>ondurationchange</code></dfn> </td><td> <code title="event-MediaController-durationchange"><a href="#event-mediacontroller-durationchange">durationchange</a></code>
1.87 mike 6348: </td></tr><tr><td><dfn id="handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate"><code>ontimeupdate</code></dfn> </td><td> <code title="event-MediaController-timeupdate"><a href="#event-mediacontroller-timeupdate">timeupdate</a></code>
1.47 mike 6349: </td></tr><tr><td><dfn id="handler-mediacontroller-onplay" title="handler-MediaController-onplay"><code>onplay</code></dfn> </td><td> <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code>
6350: </td></tr><tr><td><dfn id="handler-mediacontroller-onpause" title="handler-MediaController-onpause"><code>onpause</code></dfn> </td><td> <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code>
6351: </td></tr><tr><td><dfn id="handler-mediacontroller-onratechange" title="handler-MediaController-onratechange"><code>onratechange</code></dfn> </td><td> <code title="event-MediaController-ratechange"><a href="#event-mediacontroller-ratechange">ratechange</a></code>
6352: </td></tr><tr><td><dfn id="handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange"><code>onvolumechange</code></dfn> </td><td> <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
6353: </td></tr></tbody></table><hr><p>The <a href="webappapis.html#task-source">task source</a> for the <a href="webappapis.html#concept-task" title="concept-task">tasks</a> listed in this section is the
6354: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
6355:
6356: </div><h6 id="assigning-a-media-controller-declaratively"><span class="secno">4.8.10.11.3 </span>Assigning a media controller declaratively</h6><p>The <dfn id="attr-media-mediagroup" title="attr-media-mediagroup"><code>mediagroup</code></dfn> content
6357: attribute on <a href="#media-element" title="media element">media elements</a> can
6358: be used to link multiple <a href="#media-element" title="media element">media
6359: elements</a> together by implicitly creating a
1.126 mike 6360: <code><a href="#mediacontroller">MediaController</a></code>. The value is text; <a href="#media-element" title="media
6361: element">media elements</a> with the same value are automatically
6362: linked by the user agent.</p><div class="impl">
1.47 mike 6363:
6364: <p>When a <a href="#media-element">media element</a> is created with a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and when
6365: a <a href="#media-element">media element</a>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is set,
6366: changed, or removed, the user agent must run the following
6367: steps:</p>
6368:
6369: <ol><li><p>Let <var title="">m</var> be the <a href="#media-element">media element</a>
6370: in question.</p></li>
6371:
6372: <li><p>Let <var title="">m</var> have no <a href="#current-media-controller">current
6373: media controller</a>, if it currently has one.</p></li>
6374:
6375: <li><p>If <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is being
6376: removed, then abort these steps.</p></li>
6377:
6378: <li>
6379:
6380: <p>If there is another <a href="#media-element">media element</a> whose
6381: <code><a href="infrastructure.html#document">Document</a></code> is the same as <var title="">m</var>'s
6382: <code><a href="infrastructure.html#document">Document</a></code> (even if one or both of these elements are
6383: not actually <a href="infrastructure.html#in-a-document" title="in a Document"><em>in</em> the
6384: <code>Document</code></a>), and which also has a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and
6385: whose <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>
6386: attribute has the same value as the new value of <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, then
6387: let <var title="">controller</var> be that <a href="#media-element">media
6388: element</a>'s <a href="#current-media-controller">current media controller</a>.</p>
6389:
6390: <p>Otherwise, let <var title="">controller</var> be a newly created
6391: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6392:
6393: </li>
6394:
6395: <li><p>Let <var title="">m</var>'s <a href="#current-media-controller">current media
6396: controller</a> be <var title="">controller</var>.</p></li>
6397:
6398: <li><p><a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">Bring the media element up to speed with its new media
6399: controller</a>.</p></li>
6400:
6401: </ol><p>The <dfn id="dom-media-mediagroup" title="dom-media-mediaGroup"><code>mediaGroup</code></dfn> IDL
6402: attribute on <a href="#media-element" title="media element">media elements</a> must
6403: <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content
6404: attribute.</p>
6405:
6406: </div><div class="example">
6407:
6408: <p>Multiple <a href="#media-element" title="media element">media elements</a>
6409: referencing the same <a href="#media-resource">media resource</a> will share a
6410: single network request. This can be used to efficiently play two
6411: (video) tracks from the same <a href="#media-resource">media resource</a> in two
6412: different places on the screen. Used with the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, these
6413: elements can also be kept synchronised.</p>
6414:
6415: <p>In this example, a sign-languge interpreter track from a movie
6416: file is overlaid on the primary video track of that same video file
6417: using two <code><a href="#the-video-element">video</a></code> elements, some CSS, and an implicit
6418: <code><a href="#mediacontroller">MediaController</a></code>:</p>
6419:
6420: <pre><article>
6421: <style scoped>
6422: div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
6423: video { position; absolute; bottom: 0; right: 0; }
6424: video:first-child { width: 100%; height: 100%; }
6425: video:last-child { width: 30%; }
6426: </style>
6427: <div>
6428: <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
6429: <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
6430: </div>
6431: </article></pre>
6432:
6433: </div><h5 id="timed-text-tracks"><span class="secno">4.8.10.12 </span>Timed text tracks</h5><h6 id="text-track-model"><span class="secno">4.8.10.12.1 </span>Text track model</h6><p>A <a href="#media-element">media element</a> can have a group of associated <dfn id="text-track" title="text track">text tracks</dfn>, known as the <a href="#media-element">media
6434: element</a>'s <dfn id="list-of-text-tracks">list of text tracks</dfn>. The <a href="#text-track" title="text track">text tracks</a> are sorted as follows:</p><ol class="brief"><li>The <a href="#text-track" title="text track">text tracks</a> corresponding
6435: to <code><a href="#the-track-element">track</a></code> element children of the <a href="#media-element">media
6436: element</a>, in <a href="infrastructure.html#tree-order">tree order</a>.</li>
6437:
6438: <li>Any <a href="#text-track" title="text track">text tracks</a> added using
6439: the <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack()</a></code> method, in
6440: the order they were added, oldest first.</li>
6441:
6442: <li>Any <a href="#media-resource-specific-text-track" title="media-resource-specific text
6443: track">media-resource-specific text tracks</a> (<a href="#text-track" title="text track">text tracks</a> corresponding to data in
6444: the <a href="#media-resource">media resource</a>), in the order defined by the
6445: <a href="#media-resource">media resource</a>'s format specification.</li>
6446:
6447: </ol><p>A <a href="#text-track">text track</a> consists of:</p><dl><dt><dfn id="text-track-kind" title="text track kind">The kind of text track</dfn>
6448:
6449: </dt><dd>
6450:
6451: <p>This decides how the track is handled by the user agent. The
6452: kind is represented by a string. The possible strings are:</p>
6453:
6454: <ul class="brief"><li><dfn id="dom-texttrack-kind-subtitles" title="dom-TextTrack-kind-subtitles"><code>subtitles</code></dfn>
6455: </li><li><dfn id="dom-texttrack-kind-captions" title="dom-TextTrack-kind-captions"><code>captions</code></dfn>
6456: </li><li><dfn id="dom-texttrack-kind-descriptions" title="dom-TextTrack-kind-descriptions"><code>descriptions</code></dfn>
6457: </li><li><dfn id="dom-texttrack-kind-chapters" title="dom-TextTrack-kind-chapters"><code>chapters</code></dfn>
6458: </li><li><dfn id="dom-texttrack-kind-metadata" title="dom-TextTrack-kind-metadata"><code>metadata</code></dfn>
6459: </li></ul><p>The <a href="#text-track-kind" title="text track kind">kind of track</a> can
6460: change dynamically, in the case of a <a href="#text-track">text track</a>
6461: corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6462:
6463: </dd>
6464:
6465: <dt><dfn id="text-track-label" title="text track label">A label</dfn>
6466:
6467: </dt><dd>
6468:
6469: <p>This is a human-readable string intended to identify the track
6470: for the user. In certain cases, the label might be generated
6471: automatically.</p>
6472:
6473: <p>The <a href="#text-track-label" title="text track label">label of a track</a> can
6474: change dynamically, in the case of a <a href="#text-track">text track</a>
6475: corresponding to a <code><a href="#the-track-element">track</a></code> element or in the case of an
6476: automatically-generated label whose value depends on variable
6477: factors such as the user's preferred user interface language.</p>
6478:
6479: </dd>
6480:
6481: <dt><dfn id="text-track-language" title="text track language">A language</dfn>
6482:
6483: </dt><dd>
6484:
6485: <p>This is a string (a BCP 47 language tag) representing the
1.101 mike 6486: language of the text track's cues. <a href="references.html#refsBCP47">[BCP47]</a></p>
1.47 mike 6487:
6488: <p>The <a href="#text-track-language" title="text track language">language of a text
6489: track</a> can change dynamically, in the case of a <a href="#text-track">text
6490: track</a> corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6491:
6492: </dd>
6493:
6494: <dt><dfn id="text-track-readiness-state" title="text track readiness state">A readiness state</dfn>
6495:
6496: </dt><dd>
6497:
6498: <p>One of the following:</p>
6499:
6500: <dl><dt><dfn id="text-track-not-loaded" title="text track not loaded">Not loaded</dfn>
6501:
6502: </dt><dd>
6503:
1.132 mike 6504: <p>Indicates that the text track's cues have not been
6505: obtained.</p>
1.47 mike 6506:
6507: </dd>
6508:
6509: <dt><dfn id="text-track-loading" title="text track loading">Loading</dfn>
6510:
6511: </dt><dd>
6512:
6513: <p>Indicates that the text track is loading and there have been
6514: no fatal errors encountered so far. Further cues might still be
1.132 mike 6515: added to the track by the parser.</p>
1.47 mike 6516:
6517: </dd>
6518:
6519: <dt><dfn id="text-track-loaded" title="text track loaded">Loaded</dfn>
6520:
6521: </dt><dd>
6522:
6523: <p>Indicates that the text track has been loaded with no fatal
1.132 mike 6524: errors.</p>
1.47 mike 6525:
6526: </dd>
6527:
6528: <dt><dfn id="text-track-failed-to-load" title="text track failed to load">Failed to load</dfn>
6529:
6530: </dt><dd>
6531:
6532: <p>Indicates that the text track was enabled, but when the user
6533: agent attempted to obtain it, this failed in some way
6534: (e.g. <a href="urls.html#url">URL</a> could not be <a href="urls.html#resolve-a-url" title="resolve a
6535: url">resolved</a>, network error, unknown text track
6536: format). Some or all of the cues are likely missing and will not
6537: be obtained.</p>
6538:
6539: </dd>
6540:
6541: </dl><p>The <a href="#text-track-readiness-state" title="text track readiness state">readiness
6542: state</a> of a <a href="#text-track">text track</a> changes dynamically as
6543: the track is obtained.</p>
6544:
6545: </dd>
6546:
6547: <dt><dfn id="text-track-mode" title="text track mode">A mode</dfn>
6548:
6549: </dt><dd>
6550:
6551: <p>One of the following:</p>
6552:
6553: <dl><dt><dfn id="text-track-disabled" title="text track disabled">Disabled</dfn>
6554:
6555: </dt><dd>
6556:
6557: <p>Indicates that the text track is not active. Other than for
6558: the purposes of exposing the track in the DOM, the user agent is
6559: ignoring the text track. No cues are active, no events are
6560: fired, and the user agent will not attempt to obtain the track's
6561: cues.</p>
6562:
6563: </dd>
6564:
6565: <dt><dfn id="text-track-hidden" title="text track hidden">Hidden</dfn>
6566:
6567: </dt><dd>
6568:
6569: <p>Indicates that the text track is active, but that the user
6570: agent is not actively displaying the cues. If no attempt has yet
6571: been made to obtain the track's cues, the user agent will
6572: perform such an attempt momentarily. The user agent is
6573: maintaining a list of which cues are active, and events are
6574: being fired accordingly.</p>
6575:
6576: </dd>
6577:
6578: <dt><dfn id="text-track-showing" title="text track showing">Showing</dfn>
6579: <dt><dfn id="text-track-showing-by-default" title="text track showing by default">Showing by default</dfn>
6580:
6581: </dt></dt><dd>
6582:
6583: <p>Indicates that the text track is active. If no attempt has
6584: yet been made to obtain the track's cues, the user agent will
6585: perform such an attempt momentarily. The user agent is
6586: maintaining a list of which cues are active, and events are
6587: being fired accordingly. In addition, for text tracks whose
6588: <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-subtitles">subtitles</code> or <code title="dom-mediatrack-kind-captions">captions</code>, the cues
1.115 mike 6589: are being overlaid on the video as appropriate; for text tracks
6590: whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-descriptions">descriptions</code>,
1.47 mike 6591: the user agent is making the cues available to the user in a
1.115 mike 6592: non-visual fashion; and for text tracks whose <a href="#text-track-kind" title="text
6593: track kind">kind</a> is <code title="dom-mediatrack-kind-chapters">chapters</code>, the user
1.47 mike 6594: agent is making available to the user a mechanism by which the
6595: user can navigate to any point in the <a href="#media-resource">media
6596: resource</a> by selecting a cue.</p>
6597:
6598: <p>The <a href="#text-track-showing-by-default" title="text track showing by default">showing by
6599: default</a> state is used in conjunction with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute on
6600: <code><a href="#the-track-element">track</a></code> elements to indicate that the text track was
6601: enabled due to that attribute. This allows the user agent to
6602: override the state if a later track is discovered that is more
6603: appropriate per the user's preferences.</p>
6604:
6605: </dd>
6606:
6607: </dl></dd>
6608:
6609: <dt><dfn id="text-track-list-of-cues" title="text track list of cues">A list of zero or more cues</dfn>
6610:
6611: </dt><dd>
6612:
6613: <p>A list of <a href="#text-track-cue" title="text track cue">text track
6614: cues</a>, along with <dfn id="rules-for-updating-the-text-track-rendering">rules for updating the text track
6615: rendering</dfn>.
6616: </p>
6617:
6618: <p>The <a href="#text-track-list-of-cues" title="text track list of cues">list of cues of a
6619: text track</a> can change dynamically, either because the
6620: <a href="#text-track">text track</a> has <a href="#text-track-not-loaded" title="text track not
6621: loaded">not yet been loaded</a> or is still <a href="#text-track-loading" title="text
1.132 mike 6622: track loading">loading</a>, or due to DOM manipulation.</p>
1.47 mike 6623:
6624: </dd>
6625:
6626: </dl><p>Each <a href="#text-track">text track</a> has a corresponding
6627: <code><a href="#texttrack">TextTrack</a></code> object.</p><p>The <a href="#text-track" title="text track">text tracks</a> of a
6628: <a href="#media-element">media element</a> are <dfn id="the-text-tracks-are-ready" title="the text tracks are
6629: ready">ready</dfn> if all the <a href="#text-track" title="text track">text
6630: tracks</a> whose <a href="#text-track-mode" title="text track mode">mode</a> was
6631: not in the <a href="#text-track-disabled" title="text track disabled">disabled</a> state
6632: when the element's <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
6633: algorithm</a> last started now have a <a href="#text-track-readiness-state">text track readiness
6634: state</a> of <a href="#text-track-loaded" title="text track loaded">loaded</a> or
6635: <a href="#text-track-failed-to-load" title="text track failed to load">failed to load</a>.</p><hr><p>A <dfn id="text-track-cue">text track cue</dfn> is the unit of time-sensitive data
6636: in a <a href="#text-track">text track</a>, corresponding for instance for
6637: subtitles and captions to the text that appears at a particular time
6638: and disappears at another time.</p><p>Each <a href="#text-track-cue">text track cue</a> consists of:</p><dl><dt><dfn id="text-track-cue-identifier" title="text track cue identifier">An identifier</dfn>
6639: </dt><dd>
6640: <p>An arbitrary string.</p>
6641: </dd>
6642:
6643: <dt><dfn id="text-track-cue-start-time" title="text track cue start time">A start time</dfn>
6644: </dt><dd>
1.129 mike 6645: <p>The time, in seconds and fractions of a second, that describes
6646: the beginning of the range of the <a href="#media-data">media data</a> to which
6647: the cue applies.</p>
1.47 mike 6648: </dd>
6649:
6650: <dt><dfn id="text-track-cue-end-time" title="text track cue end time">An end time</dfn>
6651: </dt><dd>
1.129 mike 6652: <p>The time, in seconds and fractions of a second, that describes
6653: the end of the range of the <a href="#media-data">media data</a> to which the
6654: cue applies.</p>
1.47 mike 6655: </dd>
6656:
6657: <dt><dfn id="text-track-cue-pause-on-exit-flag" title="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
6658: </dt><dd>
6659: <p>A boolean indicating whether playback of the <a href="#media-resource">media
1.136 mike 6660: resource</a> is to pause when the end of the range to which the
6661: cue applies is reached.</p>
1.47 mike 6662: </dd>
6663:
6664: <dt><dfn id="text-track-cue-writing-direction" title="text track cue writing direction">A writing direction</dfn>
6665: </dt><dd>
6666: <p>A writing direction, either <dfn id="text-track-cue-horizontal-writing-direction" title="text track cue
6667: horizontal writing direction">horizontal</dfn> (a line extends
6668: horizontally and is positioned vertically, with consecutive lines
6669: displayed below each other), <dfn id="text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical
6670: growing left writing direction">vertical growing left</dfn> (a
6671: line extends vertically and is positioned horizontally, with
6672: consecutive lines displayed to the left of each other), or <dfn id="text-track-cue-vertical-growing-right-writing-direction" title="text track cue vertical
6673: growing right writing direction">vertical growing right</dfn> (a
6674: line extends vertically and is positioned horizontally, with
6675: consecutive lines displayed to the right of each other).</p>
6676:
6677:
6678: </dd>
6679:
6680:
6681: <dt><dfn id="text-track-cue-size" title="text track cue size">A size</dfn>
6682: </dt><dd>
6683: <p>A number giving the size of the box within which the text of
6684: each line of the cue is to be aligned, to be interpreted as a
6685: percentage of the video, as defined by the <a href="#text-track-cue-writing-direction" title="text
6686: track cue writing direction">writing direction</a>.</p>
6687: </dd>
6688:
6689:
6690: <dt><dfn id="text-track-cue-text" title="text track cue text">The text of the cue</dfn>
6691: </dt><dd>
6692: <p>The raw text of the cue, and rules for its interpretation,
6693: allowing the text to be rendered and converted to a DOM fragment.</p>
6694: </dd>
6695:
6696: </dl><p>A <a href="#text-track-cue">text track cue</a> is immutable.</p><p>Each <a href="#text-track-cue">text track cue</a> has a corresponding
6697: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and can be associated with a
6698: particular <a href="#text-track">text track</a>. Once a <a href="#text-track-cue">text track
6699: cue</a> is associated with a particular <a href="#text-track">text track</a>,
6700: the association is permanent.</p><p>In addition, each <a href="#text-track-cue">text track cue</a> has two pieces of
6701: dynamic information:</p><dl><dt>The <dfn id="text-track-cue-active-flag" title="text track cue active flag">active flag</dfn>
6702: </dt><dd>
6703:
6704: <p>This flag must be initially unset. The flag is used to ensure
6705: events are fired appropriately when the cue becomes active or
6706: inactive, and to make sure the right cues are rendered.</p>
6707:
6708: <p>The user agent must synchronously unset this flag whenever the
6709: <a href="#text-track-cue">text track cue</a> is removed from its <a href="#text-track">text
6710: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>; whenever the
6711: <a href="#text-track">text track</a> itself is removed from its <a href="#media-element">media
6712: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> or has its
6713: <a href="#text-track-mode">text track mode</a> changed to <a href="#text-track-disabled" title="text track
6714: disabled">disabled</a>; and whenever the <a href="#media-element">media
6715: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is changed back to
6716: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>. When the
6717: flag is unset in this way for one or more cues in <a href="#text-track" title="text track">text tracks</a> that were <a href="#text-track-showing" title="text track showing">showing</a> or <a href="#text-track-showing-by-default" title="text
6718: track showing by default">showing by default</a> prior to the
6719: relevant incident, the user agent must, after having unset the
6720: flag for all the affected cues, apply the <a href="#rules-for-updating-the-text-track-rendering">rules for updating
6721: the text track rendering</a> of those <a href="#text-track" title="text
6722: track">text tracks</a>.
6723: </p></dd>
6724:
6725: <dt>The <dfn id="text-track-cue-display-state" title="text track cue display state">display state</dfn>
6726: </dt><dd>
6727:
6728: <p>This is used as part of the rendering model, to keep cues in a
6729: consistent position. It must initially be empty. Whenever the
6730: <a href="#text-track-cue-active-flag">text track cue active flag</a> is unset, the user agent
6731: must empty the <a href="#text-track-cue-display-state">text track cue display state</a>.</p>
6732:
6733: </dd>
6734:
6735: </dl><p>The <a href="#text-track-cue" title="text track cue">text track cues</a> of a
6736: <a href="#media-element">media element</a>'s <a href="#text-track" title="text track">text
6737: tracks</a> are ordered relative to each other in the <dfn id="text-track-cue-order">text
6738: track cue order</dfn>, which is determined as follows: first group
6739: the <a href="#text-track-cue" title="text track cue">cues</a> by their <a href="#text-track">text
6740: track</a>, with the groups being sorted in the same order as
6741: their <a href="#text-track" title="text track">text tracks</a> appear in the
6742: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>;
6743: then, within each group, <a href="#text-track-cue" title="text track cue">cues</a>
6744: must be sorted by their <a href="#text-track-cue-start-time" title="text track cue start
6745: time">start time</a>, earliest first; then, any <a href="#text-track-cue" title="text track cue">cues</a> with the same <a href="#text-track-cue-start-time" title="text
6746: track cue start time">start time</a> must be sorted by their
1.111 mike 6747: <a href="#text-track-cue-end-time" title="text track cue end time">end time</a>, latest
1.47 mike 6748: first; and finally, any <a href="#text-track-cue" title="text track cue">cues</a>
6749: with identical <a href="#text-track-cue-end-time" title="text track cue end time">end
6750: times</a> must be sorted in the order they were created (so
6751: e.g. for cues from a <span>WebVTT</span> file, that would be the
6752: order in which the cues were listed in the file).</p><h6 id="sourcing-in-band-text-tracks"><span class="secno">4.8.10.12.2 </span>Sourcing in-band text tracks</h6><p>A <dfn id="media-resource-specific-text-track">media-resource-specific text track</dfn> is a <a href="#text-track">text
6753: track</a> that corresponds to data found in the <a href="#media-resource">media
6754: resource</a>.</p><div class="impl">
6755:
6756: <p>Rules for processing and rendering such data are defined by the
6757: relevant specifications, e.g. the specification of the video format
6758: if the <a href="#media-resource">media resource</a> is a video.</p>
6759:
6760: <p>When a <a href="#media-resource">media resource</a> contains data that the user
6761: agent recognises and supports as being equivalent to a <a href="#text-track">text
6762: track</a>, the user agent <a href="#found-a-media-resource-specific-timed-track">runs</a> the
6763: <dfn id="steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text track</dfn>
1.122 mike 6764: with the relevant data, as follows.</p>
6765:
6766:
1.47 mike 6767:
6768: <ol><li><p>Associate the relevant data with a new <a href="#text-track">text
6769: track</a> and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6770: object. The <a href="#text-track">text track</a> is a
6771: <a href="#media-resource-specific-text-track">media-resource-specific text track</a>.</p></li>
6772:
6773: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-kind" title="text track
6774: kind">kind</a>, <a href="#text-track-label" title="text track label">label</a>,
6775: and <a href="#text-track-language" title="text track language">language</a> based on the
6776: semantics of the relevant data, as defined by the relevant
6777: specification.</p></li>
6778:
6779: <li><p>Populate the new <a href="#text-track">text track</a>'s <a href="#text-track-list-of-cues" title="text track list of cues">list of cues</a> with the cues
6780: parsed so far, folllowing the <span>guidelines for exposing
6781: cues</span>, and begin updating it dynamically as
6782: necessary.</p></li>
6783:
1.137 mike 6784: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-readiness-state" title="text
6785: track readiness state">readiness state</a> to <a href="#text-track-loaded" title="text
6786: track loaded">loaded</a>.</p></li>
1.47 mike 6787: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-mode" title="text
6788: track mode">mode</a> to the mode consistent with the user's
6789: preferences and the requirements of the relevant specification for
6790: the data.</p></li>
6791:
6792: <li><p>Leave the <a href="#text-track-list-of-cues">text track list of cues</a> empty, and
6793: associate with it the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
6794: rendering</a> appropriate for the format in question.</p>
6795:
6796: </li><li><p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6797: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p></li>
6798:
1.122 mike 6799: <li><p>Fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and is
6800: not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
6801: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code>
6802: attribute initialized to the <a href="#text-track">text track</a>'s
6803: <code><a href="#texttrack">TextTrack</a></code> object, at the <a href="#media-element">media element</a>'s
6804: <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> attribute's
6805: <code><a href="#texttracklist">TextTrackList</a></code> object.</p></li>
6806:
1.47 mike 6807: </ol><p>When a <a href="#media-element">media element</a> is to <dfn id="forget-the-media-element-s-media-resource-specific-text-tracks">forget the media
6808: element's media-resource-specific text tracks</dfn>, the user
6809: agent must remove from the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list
6810: of text tracks</a> all the <a href="#media-resource-specific-text-track" title="media-resource-specific
6811: text track">media-resource-specific text tracks</a>.</p>
6812:
6813: </div><div class="impl">
6814:
6815: <h6 id="sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</h6>
6816:
6817: <p>When a <code><a href="#the-track-element">track</a></code> element is created, it must be
6818: associated with a new <a href="#text-track">text track</a> (with its value set
6819: as defined below) and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6820: object.</p>
6821:
6822: <p>The <a href="#text-track-kind">text track kind</a> is determined from the state of
6823: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute
6824: according to the following table; for a state given in a cell of the
6825: first column, the <a href="#text-track-kind" title="text track kind">kind</a> is the
6826: string given in the second column:</p>
6827:
6828: <table><thead><tr><th>State
6829: </th><th>String
6830: </th></tr></thead><tbody><tr><td><a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</a>
6831: </td><td><code title="dom-timedtrack-kind-subtitles">subtitles</code>
6832: </td></tr><tr><td><a href="#attr-track-kind-captions" title="attr-track-kind-captions">Captions</a>
6833: </td><td><code title="dom-timedtrack-kind-captions">captions</code>
6834: </td></tr><tr><td><a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</a>
6835: </td><td><code title="dom-timedtrack-kind-descriptions">descriptions</code>
6836: </td></tr><tr><td><a href="#attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</a>
6837: </td><td><code title="dom-timedtrack-kind-chapters">chapters</code>
6838: </td></tr><tr><td><a href="#attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</a>
6839: </td><td><code title="dom-timedtrack-kind-metadata">metadata</code>
6840: </td></tr></tbody></table><p>The <a href="#text-track-label">text track label</a> is the element's <a href="#track-label">track
6841: label</a>.</p>
6842:
6843: <p>The <a href="#text-track-language">text track language</a> is the element's
6844: <a href="#track-language">track language</a>, if any, or the empty string
6845: otherwise.</p>
6846:
6847: <p>As the <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code>, <code title="attr-track-label"><a href="#attr-track-label">label</a></code>, and <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attributes are set,
6848: changed, or removed, the <a href="#text-track">text track</a> must update
6849: accordingly, as per the definitions above.</p>
6850:
6851: <p class="note">Changes to the <a href="#track-url">track URL</a> are handled in
6852: the algorithm below.</p>
6853:
6854: <p>The <a href="#text-track-list-of-cues">text track list of cues</a> is initially empty. It
6855: is dynamically modified when the referenced file is parsed.
6856: Associated with the list are the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text
6857: track rendering</a> appropriate for the format in question; for
1.101 mike 6858: <span>WebVTT</span>, this is the <a href="rendering.html#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the
1.47 mike 6859: display of WebVTT text tracks</a>.</p>
6860:
6861: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6862: the new parent is a <a href="#media-element">media element</a>, then the user agent
6863: must add the <code><a href="#the-track-element">track</a></code> element's corresponding <a href="#text-track">text
6864: track</a> to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
1.122 mike 6865: tracks</a>, and then <a href="webappapis.html#queue-a-task">queue a task</a> to fire an event
6866: with the name <code title="event-addtrack">addtrack</code>, that
6867: does not bubble and is not cancelable, and that uses the
6868: <code><a href="#trackevent">TrackEvent</a></code> interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized to
6869: the <a href="#text-track">text track</a>'s <code><a href="#texttrack">TextTrack</a></code> object, at the
6870: <a href="#media-element">media element</a>'s <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> attribute's
6871: <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
1.47 mike 6872:
6873: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6874: the old parent was a <a href="#media-element">media element</a>, then the user agent
6875: must remove the <code><a href="#the-track-element">track</a></code> element's corresponding
6876: <a href="#text-track">text track</a> from the <a href="#media-element">media element</a>'s
1.122 mike 6877: <a href="#list-of-text-tracks">list of text tracks</a>.</p>
1.47 mike 6878:
6879: <p>When a <a href="#text-track">text track</a> corresponding to a
6880: <code><a href="#the-track-element">track</a></code> element is added to a <a href="#media-element">media
6881: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, the user agent
6882: must set the <a href="#text-track-mode">text track mode</a> appropriately, as
6883: determined by the following conditions:</p>
6884:
6885: <dl class="switch"><dt>If the <a href="#text-track-kind">text track kind</a> is <code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code> or <code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code> and the user
6886: has indicated an interest in having a track with this <a href="#text-track-kind">text
6887: track kind</a>, <a href="#text-track-language">text track language</a>, and
6888: <a href="#text-track-label">text track label</a> enabled, and there is no other
6889: <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6890: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6891: kind</a> of either <code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code> or <code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code> whose
6892: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6893: showing">showing</a></dt>
6894:
6895: <dt>If the <a href="#text-track-kind">text track kind</a> is <code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code> and
6896: the user has indicated an interest in having text descriptions with
6897: this <a href="#text-track-language">text track language</a> and <a href="#text-track-label">text track
6898: label</a> enabled, and there is no other <a href="#text-track">text
6899: track</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
6900: text tracks</a> with a <a href="#text-track-kind">text track kind</a> of <code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code> whose
6901: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6902: showing">showing</a></dt>
6903:
1.62 mike 6904: <dd>
6905: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6906: track showing">showing</a>.</p>
6907:
6908: <p>If there is a <a href="#text-track">text track</a> in the <a href="#media-element">media
6909: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6910: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing-by-default" title="text track showing
6911: by default">showing by default</a>, the user agent must
6912: furthermore change <em>that</em> <a href="#text-track">text track</a>'s
6913: <a href="#text-track-mode">text track mode</a> to <a href="#text-track-hidden" title="text track
6914: hidden">hidden</a>.</p>
6915: </dd>
6916:
1.47 mike 6917: <dt>If the <a href="#text-track-kind">text track kind</a> is <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> and the
6918: <a href="#text-track-language">text track language</a> is one that the user agent has
6919: reason to believe is appropriate for the user, and there is no
6920: other <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6921: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6922: kind</a> of <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> whose
6923: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6924: showing">showing</a></dt>
6925:
6926: <dd>
6927: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6928: track showing">showing</a>.</p>
6929: </dd>
6930:
6931: <dt>If the <code><a href="#the-track-element">track</a></code> element has a <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute specified, and
6932: there is no other <a href="#text-track">text track</a> in the <a href="#media-element">media
6933: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6934: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6935: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track
6936: showing by default">showing by default</a></dt>
6937:
6938: <dd>
6939: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing-by-default" title="text
6940: track showing by default">showing by default</a>.</p>
6941: </dd>
6942:
6943: <dt>Otherwise</dt>
6944:
6945: <dd>
6946: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-disabled" title="text
6947: track disabled">disabled</a>.</p>
6948: </dd>
6949:
6950: </dl><p>When a <a href="#text-track">text track</a> corresponding to a
6951: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6952: mode</a> set to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6953: <a href="#text-track-showing" title="text track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by default">showing by default</a>,
6954: and when a <a href="#text-track">text track</a> corresponding to a
6955: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6956: mode</a> set to <a href="#text-track-disabled" title="text track
6957: disabled">disabled</a> and subsequently changes its <a href="#text-track-mode">text
6958: track mode</a> to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6959: <a href="#text-track-showing" title="text track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by default">showing by default</a> for
6960: the first time, the user agent must immediately and synchronously
6961: run the following algorithm. This algorithm interacts closely with
6962: the <a href="webappapis.html#event-loop">event loop</a> mechanism; in particular, it has a
6963: <a href="webappapis.html#synchronous-section">synchronous section</a> (which is triggered as part of the
6964: <a href="webappapis.html#event-loop">event loop</a> algorithm). The step in that section is
6965: marked with ⌛.</p>
6966:
6967: <ol><li><p>Set the <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-loading" title="text track loading">loading</a>.</p></li>
6968:
6969: <li><p>Let <var title="">URL</var> be the <a href="#track-url">track URL</a> of
6970: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6971:
6972: <li><p>Asynchronously run the remaining steps, while continuing
6973: with whatever task was responsible for creating the <a href="#text-track">text
6974: track</a> or changing the <a href="#text-track-mode">text track
6975: mode</a>.</p></li>
6976:
6977: <li>
6978:
1.61 mike 6979: <p><i>Download</i>: At this point, the text track is downloaded.</p>
6980:
6981: <p>If <var title="">URL</var> is not the empty string, perform a
6982: <a href="fetching-resources.html#potentially-cors-enabled-fetch">potentially CORS-enabled fetch</a> of <var title="">URL</var>, with the <i>mode</i> being the state of the
6983: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
1.128 mike 6984: attribute, the <i title="">origin</i> being the <a href="origin-0.html#origin">origin</a> of the
1.61 mike 6985: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
6986: <i>default origin behaviour</i> set to <i>fail</i>.</p>
6987:
6988: <p>The resource obtained in this fashion, if any, contains the
6989: text track data. If any data is obtained, it is by definition
6990: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a> (cross-origin resources that are not
6991: suitably CORS-enabled do not get this far).</p>
6992:
1.47 mike 6993: <p>The <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue
6994: a task">queued</a> by the <a href="fetching-resources.html#fetch" title="fetch">fetching
6995: algorithm</a> on the <a href="webappapis.html#networking-task-source">networking task source</a> to
1.135 mike 6996: process the data as it is being fetched must <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type sniffing">determine the sniffed type of a the
6997: resource</a>. If the sniffed type of the resource is not a
6998: supported text track format, the load will fail, as described
6999: below. Otherwise, the resource's data must be passed to the
7000: appropriate parser
7001: as it is received, with the <a href="#text-track-list-of-cues">text track list of cues</a>
7002: being used for that parser's output.</p>
1.47 mike 7003:
7004: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> fails for
7005: any reason (network error, the server returns an error code, a
1.61 mike 7006: cross-origin check fails, etc), if <var title="">URL</var> is the
1.135 mike 7007: empty string, or if the sniffed type of the resource is not a
7008: supported text track format, then <a href="webappapis.html#queue-a-task">queue a task</a> to
7009: first change the <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-failed-to-load" title="text track failed to load">failed to load</a> and then
7010: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the <code><a href="#the-track-element">track</a></code>
7011: element; and then, once that <a href="webappapis.html#concept-task" title="concept-task">task</a> is <a href="webappapis.html#queue-a-task" title="queue a
1.47 mike 7012: task">queued</a>, move on to the step below labeled
7013: <i>monitoring</i>.</p>
7014:
7015: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> does not
1.136 mike 7016: fail, then the final <a href="webappapis.html#concept-task" title="concept-task">task</a> that
7017: is <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the
7018: <a href="webappapis.html#networking-task-source">networking task source</a> must run the following
7019: steps:</p>
1.99 mike 7020:
7021: <ol><li><p>Change the <a href="#text-track-readiness-state">text track readiness state</a> to
7022: <a href="#text-track-loaded" title="text track loaded">loaded</a>.</p></li>
7023:
7024: <li>
7025:
7026: <p>If the file was successfully processed, <a href="webappapis.html#fire-a-simple-event">fire a simple
7027: event</a> named <code title="event-load">load</code> at the
7028: <code><a href="#the-track-element">track</a></code> element.</p>
7029:
7030: <p>If the file was not successfully processed, e.g. the format
7031: in question is an XML format and the file contained a
7032: well-formedness error that the XML specification requires be
7033: detected and reported to the application, then <a href="webappapis.html#fire-a-simple-event">fire a
7034: simple event</a> named <code title="event-error">error</code>
7035: at the <code><a href="#the-track-element">track</a></code> element.</p>
7036:
7037: </li>
7038:
1.136 mike 7039: <li><p>Jump to the step below labeled <i>monitoring</i>.</p></li>
1.47 mike 7040:
1.136 mike 7041: </ol><p>If, while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> is
1.47 mike 7042: active, either:</p>
7043:
7044: <ul><li>the <a href="#track-url">track URL</a> changes so that it is no longer
7045: equal to <var title="">URL</var>, while the <a href="#text-track-mode">text track
7046: mode</a> is set to <a href="#text-track-hidden" title="text track
7047: hidden">hidden</a>, <a href="#text-track-showing" title="text track
7048: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
7049: default">showing by default</a>; or</li>
7050:
7051: <li>the <a href="#text-track-mode">text track mode</a> changes to <a href="#text-track-hidden" title="text track hidden">hidden</a>, <a href="#text-track-showing" title="text
7052: track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track
7053: showing by default">showing by default</a>, while the
7054: <a href="#track-url">track URL</a> is not equal to <var title="">URL</var></li>
7055:
7056: </ul><p>...then the user agent must run the following steps:</p>
7057:
1.136 mike 7058: <ol><li><p>Abort the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a>,
7059: discarding any pending <a href="webappapis.html#concept-task" title="concept-task">tasks</a>
7060: generated by that algorithm.</p></li>
1.47 mike 7061:
7062: <li><p>Let <var title="">URL</var> be the new <a href="#track-url">track
7063: URL</a>.</p></li>
7064:
7065: <li><p>Jump back to the top of the step labeled
7066: <i>download</i>.</p></li>
7067:
7068: </ol><p>Until one of the above circumstances occurs, the user agent
7069: must remain on this step.</p>
7070:
7071: </li>
7072:
7073: <li><p><i>Monitoring</i>: Wait until the <a href="#track-url">track URL</a> is
7074: no longer equal to <var title="">URL</var>, at the same time as the
7075: <a href="#text-track-mode">text track mode</a> is set to <a href="#text-track-hidden" title="text track
7076: hidden">hidden</a>, <a href="#text-track-showing" title="text track
7077: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
7078: default">showing by default</a>.</p></li>
7079:
7080: <li><p>Wait until the <a href="#text-track-readiness-state">text track readiness state</a> is
7081: no longer set to <a href="#text-track-loading" title="text track
7082: loading">loading</a>.</p></li>
7083:
7084: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
7085: section</a> consists of the following step. (The step in the
7086: <a href="webappapis.html#synchronous-section">synchronous section</a> is marked with ⌛.)</p></li>
7087:
7088: <li><p>⌛ Set the <a href="#text-track-readiness-state">text track readiness state</a> to
7089: <a href="#text-track-loading" title="text track loading">loading</a>.</p></li>
7090:
7091:
7092: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
7093: remaining steps asynchronously.</p></li>
7094:
7095: <li><p>Jump to the step labeled <i>download</i>.</p></li>
7096:
1.121 mike 7097: </ol></div><h6 id="text-track-api"><span class="secno">4.8.10.12.4 </span>Text track API</h6><pre class="idl">interface <dfn id="texttracklist">TextTrackList</dfn> {
7098: readonly attribute unsigned long <a href="#dom-texttracklist-length" title="dom-TextTrackList-length">length</a>;
7099: getter <a href="#texttrack">TextTrack</a> (unsigned long index);
7100:
7101: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttracklist-onaddtrack" title="handler-TextTrackList-onaddtrack">onaddtrack</a>;
7102: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> . <code title="">length</code></dt>
1.47 mike 7103: <dd>
7104: <p>Returns the number of <a href="#text-track" title="text track">text tracks</a> associated with the <a href="#media-element">media element</a> (e.g. from <code><a href="#the-track-element">track</a></code> elements). This is the number of <a href="#text-track" title="text track">text tracks</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
7105: </dd>
7106:
7107: <dt><var title="">media</var> . <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks[</a></code> <var title="">n</var> <code title="">]</code></dt>
7108: <dd>
7109: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object representing the <var title="">n</var>th <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
7110: </dd>
7111:
7112: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
7113: <dd>
7114: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object representing the <code><a href="#the-track-element">track</a></code> element's <a href="#text-track">text track</a>.</p>
7115: </dd>
7116:
7117: </dl><div class="impl">
7118:
1.121 mike 7119: <p>A <code><a href="#texttracklist">TextTrackList</a></code> object represents a dynamically
7120: updating list of <a href="#text-track" title="text track">text tracks</a> in a
7121: given order.</p>
7122:
7123: <p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn> attribute
7124: of <a href="#media-element" title="media element">media elements</a> must return a
7125: <code><a href="#texttracklist">TextTrackList</a></code> object representing the
7126: <code><a href="#texttrack">TextTrack</a></code> objects of the <a href="#text-track" title="text track">text
7127: tracks</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
7128: tracks</a>, in the same order as in the <a href="#list-of-text-tracks">list of text
7129: tracks</a>. The same object must be returned each time the
7130: attribute is accessed. <a href="references.html#refsWEBIDL">[WEBIDL]</a></p>
7131:
7132: <p>The <dfn id="dom-texttracklist-length" title="dom-TextTrackList-length"><code>length</code></dfn> attribute
7133: of a <code><a href="#texttracklist">TextTrackList</a></code> object must return the number of
7134: <a href="#text-track" title="text track">text tracks</a> in the list represented
7135: by the <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
7136:
7137: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of a
7138: <code><a href="#texttracklist">TextTrackList</a></code> object at any instant are the numbers
7139: from zero to the number of <a href="#text-track" title="text track">text
7140: tracks</a> in the list represented by the
7141: <code><a href="#texttracklist">TextTrackList</a></code> object minus one, if any. If there are no
7142: <a href="#text-track" title="text track">text tracks</a> in the list, there are
7143: no <a href="infrastructure.html#supported-property-indices">supported property indices</a>.</p>
7144:
7145: <p>To <a href="infrastructure.html#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> of a
7146: <code><a href="#texttracklist">TextTrackList</a></code> object for a given index <var title="">index</var>, the user agent must return the <var title="">index</var>th <a href="#text-track">text track</a> in the list
7147: represented by the <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
1.47 mike 7148:
1.86 mike 7149: </div><hr><pre class="idl">interface <dfn id="texttrack">TextTrack</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.47 mike 7150: readonly attribute DOMString <a href="#dom-texttrack-kind" title="dom-TextTrack-kind">kind</a>;
7151: readonly attribute DOMString <a href="#dom-texttrack-label" title="dom-TextTrack-label">label</a>;
7152: readonly attribute DOMString <a href="#dom-texttrack-language" title="dom-TextTrack-language">language</a>;
7153:
1.117 mike 7154: const unsigned short <a href="#dom-texttrack-disabled" title="dom-TextTrack-DISABLED">DISABLED</a> = 0;
1.47 mike 7155: const unsigned short <a href="#dom-texttrack-hidden" title="dom-TextTrack-HIDDEN">HIDDEN</a> = 1;
7156: const unsigned short <a href="#dom-texttrack-showing" title="dom-TextTrack-SHOWING">SHOWING</a> = 2;
7157: attribute unsigned short <a href="#dom-texttrack-mode" title="dom-TextTrack-mode">mode</a>;
7158:
1.68 mike 7159: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a>? <a href="#dom-texttrack-cues" title="dom-TextTrack-cues">cues</a>;
7160: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a>? <a href="#dom-texttrack-activecues" title="dom-TextTrack-activeCues">activeCues</a>;
1.47 mike 7161:
1.132 mike 7162: void <a href="#dom-texttrack-addcue" title="dom-TextTrack-addCue">addCue</a>(<a href="#texttrackcue">TextTrackCue</a> cue);
7163: void <a href="#dom-texttrack-removecue" title="dom-TextTrack-removeCue">removeCue</a>(<a href="#texttrackcue">TextTrackCue</a> cue);
7164:
1.118 mike 7165: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
1.110 mike 7166: };</pre><dl class="domintro"><dt><var title="">textTrack</var> . <code title="dom-TextTrack-kind"><a href="#dom-texttrack-kind">kind</a></code></dt>
1.47 mike 7167: <dd>
7168: <p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
7169: </dd>
7170:
7171: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-label"><a href="#dom-texttrack-label">label</a></code></dt>
7172: <dd>
7173: <p>Returns the <a href="#text-track-label">text track label</a>.</p>
7174: </dd>
7175:
7176: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-language"><a href="#dom-texttrack-language">language</a></code></dt>
7177: <dd>
7178: <p>Returns the <a href="#text-track-language">text track language</a> string.</p>
7179: </dd>
7180:
1.128 mike 7181: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> [ = <var title="">value</var> ]</dt>
1.47 mike 7182: <dd>
7183: <p>Returns the <a href="#text-track-mode">text track mode</a>, represented by a
7184: number from the following list:</p>
1.117 mike 7185: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-DISABLED"><a href="#dom-texttrack-disabled">DISABLED</a></code> (0)</dt>
1.47 mike 7186: <dd>
7187: <p>The <a href="#text-track-disabled">text track disabled</a> mode.</p>
7188: </dd>
7189: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-HIDDEN"><a href="#dom-texttrack-hidden">HIDDEN</a></code> (1)</dt>
7190: <dd>
7191: <p>The <a href="#text-track-hidden">text track hidden</a> mode.</p>
7192: </dd>
7193: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-SHOWING"><a href="#dom-texttrack-showing">SHOWING</a></code> (2)</dt>
7194: <dd>
7195: <p>The <a href="#text-track-showing">text track showing</a> and <a href="#text-track-showing-by-default" title="text track showing by default">showing by default</a> modes.</p>
7196: </dd>
7197: </dl><p>Can be set, to change the mode.</p>
7198: </dd>
7199:
7200: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-cues"><a href="#dom-texttrack-cues">cues</a></code></dt>
7201: <dd>
7202: <p>Returns the <a href="#text-track-list-of-cues">text track list of cues</a>, as a <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7203: </dd>
7204:
7205: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-activeCues"><a href="#dom-texttrack-activecues">activeCues</a></code></dt>
7206: <dd>
7207: <p>Returns the <a href="#text-track-cue" title="text track cue">text track cues</a> from the <a href="#text-track-list-of-cues">text track list of cues</a> that are currently active (i.e. that start before the <a href="#current-playback-position">current playback position</a> and end after it), as a <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7208: </dd>
7209:
1.132 mike 7210: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-addCue"><a href="#dom-texttrack-addcue">addCue</a></code>( <var title="">cue</var> )</dt>
7211: <dd>
7212: <p>Adds the given cue to <var title="">textTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
7213: <p>Throws an exception if the argument is associated with another <a href="#text-track">text track</a> or already in the list of cues.</p>
7214: </dd>
7215:
7216: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-removeCue"><a href="#dom-texttrack-removecue">removeCue</a></code>( <var title="">cue</var> )</dt>
7217: <dd>
7218: <p>Removes the given cue from <var title="">textTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
7219: <p>Throws an exception if the argument is associated with another <a href="#text-track">text track</a> or not in the list of cues.</p>
7220: </dd>
7221:
7222: <dt><var title="">textTrack</var> = <var title="">media</var> . <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack</a></code>( <var title="">kind</var> [, <var title="">label</var> [, <var title="">language</var> ] ] )</dt>
7223: <dd>
7224: <p>Creates and returns a new <code><a href="#texttrack">TextTrack</a></code> object, which is also added to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
7225: </dd>
7226:
1.47 mike 7227: </dl><div class="impl">
7228:
7229: <p>The <dfn id="dom-texttrack-kind" title="dom-TextTrack-kind"><code>kind</code></dfn>
7230: attribute must return the <a href="#text-track-kind">text track kind</a> of the
7231: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7232: represents.</p>
7233:
7234: <p>The <dfn id="dom-texttrack-label" title="dom-TextTrack-label"><code>label</code></dfn>
7235: attribute must return the <a href="#text-track-label">text track label</a> of the
7236: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7237: represents.</p>
7238:
7239: <p>The <dfn id="dom-texttrack-language" title="dom-TextTrack-language"><code>language</code></dfn>
7240: attribute must return the <a href="#text-track-language">text track language</a> of the
7241: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7242: represents.</p>
7243:
1.130 mike 7244: <p>The <dfn id="dom-texttrack-mode" title="dom-TextTrack-mode"><code>mode</code></dfn>
1.47 mike 7245: attribute, on getting, must return the numeric value corresponding
7246: to the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text track</a>
7247: that the <code><a href="#texttrack">TextTrack</a></code> object represents, as defined by
7248: the following list:</p>
7249:
1.117 mike 7250: <dl><dt><dfn id="dom-texttrack-disabled" title="dom-TextTrack-DISABLED"><code>DISABLED</code></dfn> (numeric value 0)</dt>
1.47 mike 7251: <dd>The <a href="#text-track-disabled">text track disabled</a> mode.</dd>
7252: <dt><dfn id="dom-texttrack-hidden" title="dom-TextTrack-HIDDEN"><code>HIDDEN</code></dfn> (numeric value 1)</dt>
7253: <dd>The <a href="#text-track-hidden">text track hidden</a> mode.</dd>
7254: <dt><dfn id="dom-texttrack-showing" title="dom-TextTrack-SHOWING"><code>SHOWING</code></dfn> (numeric value 2)</dt>
7255: <dd>The <a href="#text-track-showing">text track showing</a> and <a href="#text-track-showing-by-default" title="text track showing by default">showing by default</a> modes.</dd>
7256: </dl><p>On setting, if the new value is not either 0, 1, or 2, the user
1.119 mike 7257: agent must throw an <code><a href="infrastructure.html#invalidaccesserror">InvalidAccessError</a></code>
1.47 mike 7258: exception. Otherwise, if the new value isn't equal to what the
7259: attribute would currently return, the new value must be processed as
7260: follows:</p>
7261:
7262: <dl class="switch"><dt>If the new value is 0</dt>
7263:
7264: <dd>
7265:
7266: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7267: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7268: the <a href="#text-track-disabled">text track disabled</a> mode.</p>
7269:
7270: </dd>
7271:
7272: <dt>If the new value is 1</dt>
7273:
7274: <dd>
7275:
7276: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7277: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7278: the <a href="#text-track-hidden">text track hidden</a> mode.</p>
7279:
7280: </dd>
7281:
7282: <dt>If the new value is 2</dt>
7283:
7284: <dd>
7285:
7286: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7287: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7288: the <a href="#text-track-showing">text track showing</a> mode.</p>
7289:
7290: <p class="note">If the mode had been <a href="#text-track-showing-by-default" title="text track
7291: showing by default">showing by default</a>, this will change it
7292: to <a href="#text-track-showing" title="text track showing">showing</a>, even though
7293: the value of <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> would
7294: appear not to change.</p>
7295:
7296: </dd>
7297:
7298: </dl><p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7299: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
7300: not the <a href="#text-track-disabled">text track disabled</a> mode, then the <dfn id="dom-texttrack-cues" title="dom-TextTrack-cues"><code>cues</code></dfn> attribute must
1.104 mike 7301: return a <a href="infrastructure.html#live">live</a> <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that
7302: represents the subset of the <a href="#text-track-list-of-cues">text track list of cues</a> of
7303: the <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7304: represents whose <a href="#text-track-cue-start-time" title="text track cue start time">start
7305: times</a> occur at or after the <a href="#earliest-possible-position-when-the-script-started">earliest possible position
7306: when the script started</a>, in <a href="#text-track-cue-order">text track cue
7307: order</a>. Otherwise, it must return null. When an object is
7308: returned, the same object must be returned each time.</p>
1.47 mike 7309:
7310: <p>The <dfn id="earliest-possible-position-when-the-script-started">earliest possible position when the script started</dfn>
7311: is whatever the <a href="#earliest-possible-position">earliest possible position</a> was the last
7312: time the <a href="webappapis.html#event-loop">event loop</a> reached step 1.</p>
7313:
7314: <p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7315: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
7316: not the <a href="#text-track-disabled">text track disabled</a> mode, then the <dfn id="dom-texttrack-activecues" title="dom-TextTrack-activeCues"><code>activeCues</code></dfn>
7317: attribute must return a <a href="infrastructure.html#live">live</a>
7318: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that represents the subset of
7319: the <a href="#text-track-list-of-cues">text track list of cues</a> of the <a href="#text-track">text
7320: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents
7321: whose <a href="#active-flag-was-set-when-the-script-started">active flag was set when the script started</a>, in
7322: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
7323: null. When an object is returned, the same object must be returned
7324: each time.</p>
7325:
7326: <p>A <a href="#text-track-cue">text track cue</a>'s <dfn id="active-flag-was-set-when-the-script-started">active flag was set when
7327: the script started</dfn> if its <a href="#text-track-cue-active-flag">text track cue active
7328: flag</a> was set the last time the <a href="webappapis.html#event-loop">event loop</a>
7329: reached step 1.</p>
7330:
1.132 mike 7331: <hr><p>The <dfn id="dom-texttrack-addcue" title="dom-TextTrack-addCue"><code>addCue(<var title="">cue</var>)</code></dfn> method of <code><a href="#texttrack">TextTrack</a></code>
7332: objects, when invoked, must run the following steps:</p>
1.47 mike 7333:
1.132 mike 7334: <ol><li><p>If the given <var title="">cue</var> is already associated
7335: with a <a href="#text-track">text track</a> other than the method's
7336: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>, then throw
7337: an <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception and abort these
7338: steps.</p></li>
7339:
7340: <li><p>Associate <var title="">cue</var> with the method's
7341: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>, if it is
7342: not currently associated with a <a href="#text-track">text track</a>.</p></li>
7343:
7344: <li><p>If the given <var title="">cue</var> is already listed in
7345: the method's <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text
7346: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw an
7347: <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception.</p></li>
7348:
7349: <li><p>Add <var title="">cue</var> to the method's
7350: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>'s
7351: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7352:
7353: </ol><p>The <dfn id="dom-texttrack-removecue" title="dom-TextTrack-removeCue"><code>removeCue(<var title="">cue</var>)</code></dfn> method of
7354: <code><a href="#texttrack">TextTrack</a></code> objects, when invoked, must run the
7355: following steps:</p>
1.47 mike 7356:
1.132 mike 7357: <ol><li><p>If the given <var title="">cue</var> is not associated with
7358: the method's <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text
7359: track</a>, then throw an <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code>
7360: exception.</p></li>
1.47 mike 7361:
1.132 mike 7362: <li><p>If the given <var title="">cue</var> is not currently listed
7363: in the method's <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text
7364: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw a
7365: <code><a href="infrastructure.html#notfounderror">NotFoundError</a></code> exception.</p></li>
1.47 mike 7366:
1.132 mike 7367: <li><p>Remove <var title="">cue</var> from the method's
7368: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>'s
7369: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
1.47 mike 7370:
1.132 mike 7371: </ol><hr><p>The <dfn id="dom-media-addtexttrack" title="dom-media-addTextTrack"><code>addTextTrack(<var title="">kind</var>, <var title="">label</var>, <var title="">language</var>)</code></dfn> method of <a href="#media-element" title="media
1.47 mike 7372: element">media elements</a>, when invoked, must run the following
7373: steps:</p>
7374:
7375: <ol><li>
7376:
7377: <p>If <var title="">kind</var> is not one of the following
1.119 mike 7378: strings, then throw a <code><a href="infrastructure.html#syntaxerror">SyntaxError</a></code> exception and abort
1.47 mike 7379: these steps:</p>
7380:
7381: <ul class="brief"><li><code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code>
7382: </li><li><code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code>
7383: </li><li><code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code>
7384: </li><li><code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code>
7385: </li><li><code title="dom-TextTrack-kind-metadata"><a href="#dom-texttrack-kind-metadata">metadata</a></code>
7386: </li></ul></li>
7387:
7388: <li>
7389:
7390: <p>If the <var title="">label</var> argument was omitted, let <var title="">label</var> be the empty string.</p>
7391:
7392: </li>
7393:
7394: <li>
7395:
7396: <p>If the <var title="">language</var> argument was omitted, let
7397: <var title="">language</var> be the empty string.</p>
7398:
7399: </li>
7400:
7401: <li>
7402:
1.132 mike 7403: <p>Create a new <code><a href="#texttrack">TextTrack</a></code> object.</p>
1.102 mike 7404:
7405: </li>
7406:
7407: <li>
7408:
7409: <p>Create a new <a href="#text-track">text track</a> corresponding to the new
7410: object, and set its <a href="#text-track-kind">text track kind</a> to <var title="">kind</var>, its <a href="#text-track-label">text track label</a> to <var title="">label</var>, its <a href="#text-track-language">text track language</a> to <var title="">language</var>, its <a href="#text-track-readiness-state">text track readiness
7411: state</a> to the <a href="#text-track-loaded">text track loaded</a> state, its
7412: <a href="#text-track-mode">text track mode</a> to the <a href="#text-track-hidden">text track hidden</a>
7413: mode, and its <a href="#text-track-list-of-cues">text track list of cues</a> to an empty
7414: list.
1.47 mike 7415: </p>
7416:
7417: </li>
7418:
7419: <li>
7420:
7421: <p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
7422: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
7423:
1.102 mike 7424: </li>
7425:
7426: <li>
7427:
1.122 mike 7428: <p><a href="webappapis.html#queue-a-task">Queue a task</a> to fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and
7429: is not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
7430: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized to
1.132 mike 7431: the new <a href="#text-track">text track</a>'s <code><a href="#texttrack">TextTrack</a></code> object,
7432: at the <a href="#media-element">media element</a>'s <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> attribute's
1.122 mike 7433: <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
7434:
7435: </li>
7436:
7437: <li>
7438:
1.132 mike 7439: <p>Return the new <code><a href="#texttrack">TextTrack</a></code> object.</p>
1.102 mike 7440:
7441: </li>
7442:
1.47 mike 7443: </ol></div><div class="example">
7444:
7445: <p>In this example, an <code><a href="#the-audio-element">audio</a></code> element is used to play a
7446: specific sound-effect from a sound file containing many sound
7447: effects. A cue is used to pause the audio, so that it ends exactly
7448: at the end of the clip, even if the browser is busy running some
7449: script. If the page had relied on script to pause the audio, then
7450: the start of the next clip might be heard if the browser was not
7451: able to run the script at the exact time specified.</p>
7452:
7453: <pre>var sfx = new Audio('sfx.wav');
7454: var sounds = a.addTextTrack('metadata');
7455:
7456: // add sounds we care about
7457: sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
7458: sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));
7459:
7460: function playSound(id) {
7461: sfx.currentTime = sounds.getCueById(id).startTime;
7462: sfx.play();
7463: }
7464:
7465: sfx.oncanplaythrough = function () {
7466: playSound('dog bark');
7467: }
7468: window.onbeforeunload = function () {
7469: playSound('kitten mew');
7470: return 'Are you sure you want to leave this awesome page?';
7471: }</pre>
7472:
7473: </div><hr><pre class="idl">interface <dfn id="texttrackcuelist">TextTrackCueList</dfn> {
7474: readonly attribute unsigned long <a href="#dom-texttrackcuelist-length" title="dom-TextTrackCueList-length">length</a>;
1.101 mike 7475: getter <a href="#texttrackcue">TextTrackCue</a> (unsigned long index);
7476: <a href="#texttrackcue">TextTrackCue</a>? <a href="#dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById">getCueById</a>(DOMString id);
1.47 mike 7477: };</pre><dl class="domintro"><dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-length"><a href="#dom-texttrackcuelist-length">length</a></code></dt>
7478: <dd>
7479: <p>Returns the number of <a href="#text-track-cue" title="text track cue">cues</a> in the list.</p>
7480: </dd>
7481:
7482: <dt><var title="">cuelist</var>[<var title="">index</var>]</dt>
7483: <dd>
7484: <p>Returns the <a href="#text-track-cue">text track cue</a> with index <var title="">index</var> in the list. The cues are sorted in <a href="#text-track-cue-order">text track cue order</a>.</p>
7485: </dd>
7486:
7487: <dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-getCueById"><a href="#dom-texttrackcuelist-getcuebyid">getCueById</a></code>( <var title="">id</var> )</dt>
7488: <dd>
7489: <p>Returns the first <a href="#text-track-cue">text track cue</a> (in <a href="#text-track-cue-order">text track cue order</a>) with <a href="#text-track-cue-identifier">text track cue identifier</a> <var title="">id</var>.</p>
7490: <p>Returns null if none of the cues have the given identifier or if the argument is the empty string.</p>
7491: </dd>
7492:
7493: </dl><div class="impl">
7494:
7495: <p>A <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object represents a dynamically
7496: updating list of <a href="#text-track-cue" title="text track cue">text track
7497: cues</a> in a given order.</p>
7498:
7499: <p>The <dfn id="dom-texttrackcuelist-length" title="dom-TextTrackCueList-length"><code>length</code></dfn>
7500: attribute must return the number of <a href="#text-track-cue" title="text track
7501: cue">cues</a> in the list represented by the
7502: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7503:
1.76 mike 7504: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of a
1.47 mike 7505: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
7506: from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
7507: in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
7508: minus one, if any. If there are no <a href="#text-track-cue" title="text track
1.76 mike 7509: cue">cues</a> in the list, there are no <a href="infrastructure.html#supported-property-indices">supported property
7510: indices</a>.</p>
1.47 mike 7511:
1.76 mike 7512: <p>To <a href="infrastructure.html#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> for a
1.47 mike 7513: given index <var title="">index</var>, the user agent must return
7514: the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
7515: list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7516:
7517: <p>The <dfn id="dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById"><code>getCueById(<var title="">id</var>)</code></dfn> method, when called with an argument
7518: other than the empty string, must return the first <a href="#text-track-cue">text track
7519: cue</a> in the list represented by the
7520: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object whose <a href="#text-track-cue-identifier">text track cue
7521: identifier</a> is <var title="">id</var>, if any, or null
7522: otherwise. If the argument is the empty string, then the method must
7523: return null.</p>
7524:
7525: </div><hr><pre class="idl">
1.133 mike 7526: [<a href="#dom-texttrackcue" title="dom-TextTrackCue">Constructor</a>(DOMString id, double startTime, double endTime, DOMString text, optional DOMString settings, optional boolean pauseOnExit)]
1.86 mike 7527: interface <dfn id="texttrackcue">TextTrackCue</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.68 mike 7528: readonly attribute <a href="#texttrack">TextTrack</a>? <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a>;
1.47 mike 7529:
1.133 mike 7530: attribute DOMString <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a>;
7531: attribute double <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a>;
7532: attribute double <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a>;
7533: attribute boolean <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a>;
7534: attribute DOMString <a href="#dom-texttrackcue-direction" title="dom-TextTrackCue-direction">direction</a>;
7535: attribute boolean <a href="#dom-texttrackcue-snaptolines" title="dom-TextTrackCue-snapToLines">snapToLines</a>;
7536: attribute long <a href="#dom-texttrackcue-lineposition" title="dom-TextTrackCue-linePosition">linePosition</a>;
7537: attribute long <a href="#dom-texttrackcue-textposition" title="dom-TextTrackCue-textPosition">textPosition</a>;
7538: attribute long <a href="#dom-texttrackcue-size" title="dom-TextTrackCue-size">size</a>;
7539: attribute DOMString <a href="#dom-texttrackcue-alignment" title="dom-TextTrackCue-alignment">alignment</a>;
1.134 mike 7540: attribute DOMString <a href="#dom-texttrackcue-cueassource" title="dom-TextTrackCue-cueAsSource">cueAsSource</a>;
1.47 mike 7541: <a href="infrastructure.html#documentfragment">DocumentFragment</a> <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>();
7542:
1.118 mike 7543: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter">onenter</a>;
7544: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit">onexit</a>;
1.133 mike 7545: };</pre><dl class="domintro"><dt><var title="">cue</var> = new <code title="dom-TextTrackCue"><a href="#dom-texttrackcue">TextTrackCue</a></code>( <var title="">id</var>, <var title="">startTime</var>, <var title="">endTime</var>, <var title="">text</var> [, <var title="">settings</var> [, <var title="">pauseOnExit</var> ] ] )</dt>
1.132 mike 7546: <dd>
7547: <p>Returns a new <code><a href="#texttrackcue">TextTrackCue</a></code> object, for use with the <code title="dom-TextTrack-addCue"><a href="#dom-texttrack-addcue">addCue()</a></code> method.</p>
7548: <p>The <var title="">id</var> argument sets the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
7549: <p>The <var title="">startTime</var> argument sets the <a href="#text-track-cue-start-time">text track cue start time</a>.</p>
7550: <p>The <var title="">endTime</var> argument sets the <a href="#text-track-cue-end-time">text track cue end time</a>.</p>
7551: <p>The <var title="">text</var> argument sets the <a href="#text-track-cue-text">text track cue text</a>.</p>
7552: <p>The <var title="">settings</var> argument is a string in the format of <span>WebVTT cue settings</span>. If omitted, the empty string is assumed.</p>
7553: <p>The <var title="">pauseOnExit</var> argument sets the <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit flag</a>. If omitted, false is assumed.</p>
7554: </dd>
7555:
7556: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a></dt>
1.47 mike 7557: <dd>
7558: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object to which this
7559: <a href="#text-track-cue">text track cue</a> belongs, if any, or null
7560: otherwise.</p>
7561: </dd>
7562:
1.133 mike 7563: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a> [ = <var title="">value</var> ]</dt>
1.47 mike 7564: <dd>
7565: <p>Returns the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
1.133 mike 7566: <p>Can be set.</p>
1.47 mike 7567: </dd>
7568:
1.133 mike 7569: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a> [ = <var title="">value</var> ]</dt>
1.47 mike 7570: <dd>
7571: <p>Returns the <a href="#text-track-cue-start-time">text track cue start time</a>, in seconds.</p>
1.133 mike 7572: <p>Can be set.</p>
1.47 mike 7573: </dd>
7574:
1.133 mike 7575: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a> [ = <var title="">value</var> ]</dt>
1.47 mike 7576: <dd>
7577: <p>Returns the <a href="#text-track-cue-end-time">text track cue end time</a>, in seconds.</p>
1.133 mike 7578: <p>Can be set.</p>
1.47 mike 7579: </dd>
7580:
1.133 mike 7581: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a> [ = <var title="">value</var> ]</dt>
1.47 mike 7582: <dd>
7583: <p>Returns true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit flag</a> is set, false otherwise.</p>
1.133 mike 7584: <p>Can be set.</p>
7585: </dd>
7586:
7587: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-direction" title="dom-TextTrackCue-direction">direction</a> [ = <var title="">value</var> ]</dt>
7588: <dd>
7589: <p>Returns a string representing the <a href="#text-track-cue-writing-direction">text track cue writing direction</a>, as follows:</p>
7590: <dl class="switch"><dt>If it is <a href="#text-track-cue-horizontal-writing-direction" title="text track cue horizontal writing direction">horizontal</a></dt>
7591: <dd><p>The string "<code title="">horizontal</code>".</p></dd>
7592: <dt>If it is <a href="#text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical growing left writing direction">vertical growing left</a></dt>
7593: <dd><p>The string "<code title="">vertical</code>".</p></dd>
7594: <dt>If it is <a href="#text-track-cue-vertical-growing-right-writing-direction" title="text track cue vertical growing right writing direction">vertical growing right</a></dt>
7595: <dd><p>The string "<code title="">vertical-lr</code>".</p></dd>
7596: </dl><p>Can be set.</p>
7597: </dd>
7598:
7599: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-snaptolines" title="dom-TextTrackCue-snapToLines">snapToLines</a> [ = <var title="">value</var> ]</dt>
7600: <dd>
7601: <p>Returns true if the <span>text track cue snap-to-lines flag</span> is set, false otherwise.</p>
7602: <p>Can be set.</p>
7603: </dd>
7604:
7605: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-lineposition" title="dom-TextTrackCue-linePosition">linePosition</a> [ = <var title="">value</var> ]</dt>
7606: <dd>
7607: <p>Returns the <span>text track cue line position</span>. In the
7608: case of the value being <span title="text track cue automatic
7609: line position">auto</span>, the appropriate default is returned.</p>
7610: <p>Can be set.</p>
7611: </dd>
7612:
7613: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-textposition" title="dom-TextTrackCue-textPosition">textPosition</a> [ = <var title="">value</var> ]</dt>
7614: <dd>
7615: <p>Returns the <span>text track cue text position</span>.</p>
7616: <p>Can be set.</p>
7617: </dd>
7618:
7619: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-size" title="dom-TextTrackCue-size">size</a> [ = <var title="">value</var> ]</dt>
7620: <dd>
7621: <p>Returns the <a href="#text-track-cue-size">text track cue size</a>.</p>
7622: <p>Can be set.</p>
1.47 mike 7623: </dd>
7624:
1.133 mike 7625: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-alignment" title="dom-TextTrackCue-alignment">alignment</a> [ = <var title="">value</var> ]</dt>
7626: <dd>
7627: <p>Returns a string representing the <span>text track cue alignment</span>, as follows:</p>
7628: <dl class="switch"><dt>If it is <span title="text track cue start alignment">start alignment</span></dt>
7629: <dd><p>The string "<code title="">start</code>".</p></dd>
7630: <dt>If it is <span title="text track cue middle alignment">middle alignment</span></dt>
7631: <dd><p>The string "<code title="">middle</code>".</p></dd>
7632: <dt>If it is <span title="text track cue end alignment">end alignment</span></dt>
7633: <dd><p>The string "<code title="">end</code>".</p></dd>
7634: </dl><p>Can be set.</p>
7635: </dd>
1.47 mike 7636:
1.133 mike 7637: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-cueassource" title="dom-TextTrackCue-cueAsSource">cueAsSource</a> [ = <var title="">value</var> ]</dt>
1.47 mike 7638: <dd>
7639: <p>Returns the <a href="#text-track-cue-text">text track cue text</a> in raw unparsed form.</p>
1.133 mike 7640: <p>Can be set.</p>
1.47 mike 7641: </dd>
7642:
7643: <dt><var title="">fragment</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>()</dt>
7644: <dd>
7645: <p>Returns the <a href="#text-track-cue-text">text track cue text</a> as a <code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> of <a href="infrastructure.html#html-elements">HTML elements</a> and other DOM nodes.</p>
1.133 mike 7646: <p>Can be set.</p>
1.47 mike 7647: </dd>
7648:
7649: </dl><div class="impl">
7650:
1.133 mike 7651: <p>The <dfn id="dom-texttrackcue" title="dom-TextTrackCue"><code>TextTrackCue(<var title="">id</var>, <var title="">startTime</var>, <var title="">endTime</var>, <var title="">text</var>, <var title="">settings</var>, <var title="">pauseOnExit</var>)</code></dfn> constructor, when invoked,
7652: must run the following steps:</p>
7653:
7654: <ol><li><p>Create a new <a href="#text-track-cue">text track cue</a> that is not
7655: associated with any <a href="#text-track">text track</a>. Let <var title="">cue</var> be that <a href="#text-track-cue">text track cue</a>.</p></li>
1.47 mike 7656:
1.133 mike 7657: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-identifier">text track cue
7658: identifier</a> be the value of the <var title="">id</var>
7659: argument.</p></li>
7660:
7661: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-start-time">text track cue start
7662: time</a> be the value of the <var title="">startTime</var>
7663: argument, interpreted as a time in seconds.</p></li>
7664:
7665: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-end-time">text track cue end
7666: time</a> be the value of the <var title="">endTime</var>
7667: argument, interpreted as a time in seconds.</p></li>
7668:
7669: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-pause-on-exit-flag">text track cue
7670: pause-on-exit flag</a> be true if the <var title="">pauseOnExit</var> is present and true. Otherwise, let it
7671: be false.</p></li>
7672:
7673: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-text">text track cue
7674: text</a> be the value of the <var title="">text</var> argument,
7675: and let the rules for its interpretation be the <span>WebVTT cue
7676: text parsing rules</span>, the <a href="rendering.html#webvtt-cue-text-rendering-rules">WebVTT cue text rendering
7677: rules</a>, and the <span>WebVTT cue text DOM construction
7678: rules</span>.</p></li>
7679:
7680:
7681:
7682: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-writing-direction">text track cue
7683: writing direction</a> be <a href="#text-track-cue-horizontal-writing-direction" title="text track cue
7684: horizontal writing direction">horizontal</a>.</p></li>
7685:
7686: <li><p>Let <var title="">cue</var>'s <span>text track cue
7687: snap-to-lines flag</span> be true.</p></li>
7688:
7689: <li><p>Let <var title="">cue</var>'s <span>text track cue line
7690: position</span> be <span title="text track cue automatic line
7691: position">auto</span>.</p></li>
7692:
7693: <li><p>Let <var title="">cue</var>'s <span>text track cue
7694: text position</span> be 50.</p></li>
7695:
7696: <li><p>Let <var title="">cue</var>'s <a href="#text-track-cue-size">text track cue
7697: size</a> be 100.</p></li>
7698:
7699: <li><p>Let <var title="">cue</var>'s <span>text track cue
7700: alignment</span> be <span title="text track cue middle
7701: alignment">middle alignment</span>.</p></li>
7702:
7703: <li><p>Let <var title="">input</var> be the string given by the
7704: <var title="">settings</var> argument.</p></li>
7705:
7706: <li><p>Let <var title="">position</var> be a pointer into <var title="">input</var>, initially pointing at the start of the
7707: string.</p></li>
7708:
7709: <li><p><span>Parse the WebVTT settings</span> for <var title="">cue</var>.</p></li>
7710:
7711: <li><p>Return the <code><a href="#texttrackcue">TextTrackCue</a></code> object representing
7712: <var title="">cue</var>.</p></li>
7713:
7714: </ol><p>The <dfn id="dom-texttrackcue-track" title="dom-TextTrackCue-track"><code>track</code></dfn>
7715: attribute, on getting, must return the <code><a href="#texttrack">TextTrack</a></code> object
7716: of the <a href="#text-track">text track</a> with which the <a href="#text-track-cue">text track
7717: cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is
7718: associated, if any; or null otherwise.</p>
1.47 mike 7719:
7720: <p>The <dfn id="dom-texttrackcue-id" title="dom-TextTrackCue-id"><code>id</code></dfn>
1.133 mike 7721: attribute, on getting, must return the <a href="#text-track-cue-identifier">text track cue
7722: identifier</a> of the <a href="#text-track-cue">text track cue</a> that the
7723: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents. On setting, the <a href="#text-track-cue-identifier">text track cue
7724: identifier</a> must be set to the new value.</p>
1.47 mike 7725:
7726: <p>The <dfn id="dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime"><code>startTime</code></dfn>
1.133 mike 7727: attribute, on getting, must return the <a href="#text-track-cue-start-time">text track cue start
7728: time</a> of the <a href="#text-track-cue">text track cue</a> that the
7729: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents, in seconds. On setting, the <a href="#text-track-cue-start-time">text track cue start
7730: time</a> must be set to the new value, interpreted in seconds.</p>
1.47 mike 7731:
7732: <p>The <dfn id="dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime"><code>endTime</code></dfn>
1.133 mike 7733: attribute, on getting, must return the <a href="#text-track-cue-end-time">text track cue end
7734: time</a> of the <a href="#text-track-cue">text track cue</a> that the
7735: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents, in seconds. On setting, the <a href="#text-track-cue-end-time">text track cue end
7736: time</a> must be set to the new value, interpreted in seconds.</p>
1.47 mike 7737:
7738: <p>The <dfn id="dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit"><code>pauseOnExit</code></dfn>
1.133 mike 7739: attribute, on getting, must return true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue
1.47 mike 7740: pause-on-exit flag</a> of the <a href="#text-track-cue">text track cue</a> that
7741: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
1.133 mike 7742: otherwise. On setting, the <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
7743: flag</a> must be set if the new value is true, and must be unset
1.47 mike 7744: otherwise.</p>
7745:
7746: <p>The <dfn id="dom-texttrackcue-direction" title="dom-TextTrackCue-direction"><code>direction</code></dfn>
1.133 mike 7747: attribute, on getting, must return the string from the second cell
7748: of the row in the table below whose first cell is the <a href="#text-track-cue-writing-direction">text
7749: track cue writing direction</a> of the <a href="#text-track-cue">text track
7750: cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents:</p>
1.123 mike 7751:
7752: <table><thead><tr><th> <a href="#text-track-cue-writing-direction">Text track cue writing direction</a>
7753: </th><th> <code title="dom-TextTrackCue-direction"><a href="#dom-texttrackcue-direction">direction</a></code> value
7754: </th></tr></thead><tbody><tr><td> <a href="#text-track-cue-horizontal-writing-direction" title="text track cue horizontal writing direction">Horizontal</a>
7755: </td><td> "<code title="">horizontal</code>"
7756: </td></tr><tr><td> <a href="#text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical growing left writing direction">Vertical growing left</a>
7757: </td><td> "<code title="">vertical</code>"
7758: </td></tr><tr><td> <a href="#text-track-cue-vertical-growing-right-writing-direction" title="text track cue vertical growing right writing direction">Vertical growing right</a>
7759: </td><td> "<code title="">vertical-lr</code>"
1.133 mike 7760: </td></tr></tbody></table><p>On setting, the <a href="#text-track-cue-writing-direction">text track cue writing direction</a>
7761: must be set to the value given in the first cell of the row in the
7762: table above whose second cell is a <a href="infrastructure.html#case-sensitive">case-sensitive</a> match
7763: for the new value, if any. If none of the values match, then the
7764: user agent must instead throw a <code><a href="infrastructure.html#syntaxerror">SyntaxError</a></code>
7765: exception.</p>
7766:
7767: <p>The <dfn id="dom-texttrackcue-snaptolines" title="dom-TextTrackCue-snapToLines"><code>snapToLines</code></dfn>
7768: attribute, on getting, must return true if the <span>text track cue
7769: snap-to-lines flag</span> of the <a href="#text-track-cue">text track cue</a> that
7770: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
7771: otherwise. On setting, the <span>text track cue snap-to-lines
7772: flag</span> must be set if the new value is true, and must be unset
7773: otherwise.</p>
7774:
7775: <p>The <dfn id="dom-texttrackcue-lineposition" title="dom-TextTrackCue-linePosition"><code>linePosition</code></dfn>
1.140 mike 7776: attribute, on getting, must return the <span>text track cue computed
7777: line position</span> of the <a href="#text-track-cue">text track cue</a> that the
7778: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents. On setting, if the
7779: <span>text track cue snap-to-lines flag</span> is not set, and the
7780: new value is negative or greater than 100, then throw an
7781: <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exception. Otherwise, set the <span>text
7782: track cue line position</span> to the new value.</p>
1.133 mike 7783:
7784: <p class="note">There is no way to explicitly set the <span>text
7785: track cue line position</span> to the special default <span title="text track cue automatic line position">auto</span>
7786: value.</p>
7787:
7788: <p>The <dfn id="dom-texttrackcue-textposition" title="dom-TextTrackCue-textPosition"><code>textPosition</code></dfn>
7789: attribute, on getting, must return the <span>text track cue text
7790: position</span> of the <a href="#text-track-cue">text track cue</a> that the
7791: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents. On setting, if the new
7792: value is negative or greater than 100, then throw an
7793: <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exception. Otherwise, set the <span>text
7794: track cue text position</span> to the new value.</p>
7795:
7796: <p>The <dfn id="dom-texttrackcue-size" title="dom-TextTrackCue-size"><code>size</code></dfn>
7797: attribute, on getting, must return the <a href="#text-track-cue-size">text track cue
7798: size</a> of the <a href="#text-track-cue">text track cue</a> that the
7799: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents. On setting, if the new
7800: value is negative or greater than 100, then throw an
7801: <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exception. Otherwise, set the <a href="#text-track-cue-size">text
7802: track cue size</a> to the new value.</p>
7803:
7804: <p>The <dfn id="dom-texttrackcue-alignment" title="dom-TextTrackCue-alignment"><code>alignment</code></dfn>
7805: attribute, on getting, must return the string from the second cell
7806: of the row in the table below whose first cell is the <span>text
7807: track cue alignment</span> of the <a href="#text-track-cue">text track cue</a> that
7808: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents:</p>
7809:
7810: <table><thead><tr><th><span>Text track cue alignment</span> </th><th> <code title="dom-TextTrackCue-alignment"><a href="#dom-texttrackcue-alignment">alignment</a></code> value
7811: </th></tr></thead><tbody><tr><td><span title="text track cue start alignment">Start alignment</span> </td><td> "<code title="">start</code>"
7812: </td></tr><tr><td><span title="text track cue middle alignment">Middle alignment</span> </td><td> "<code title="">middle</code>"
7813: </td></tr><tr><td><span title="text track cue end alignment">End alignment</span> </td><td> "<code title="">end</code>"
7814: </td></tr></tbody></table><p>On setting, the <span>text track cue alignment</span> must be set
7815: to the value given in the first cell of the row in the table above
7816: whose second cell is a <a href="infrastructure.html#case-sensitive">case-sensitive</a> match for the new
7817: value, if any. If none of the values match, then the user agent must
7818: instead throw a <code><a href="infrastructure.html#syntaxerror">SyntaxError</a></code> exception.</p>
7819:
7820: <p>The <dfn id="dom-texttrackcue-cueassource" title="dom-TextTrackCue-cueAsSource"><code>cueAsSource</code></dfn>
7821: attribute, on getting, must return the raw <a href="#text-track-cue-text">text track cue
7822: text</a> of the <a href="#text-track-cue">text track cue</a> that the
7823: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents. On setting, the
7824: <a href="#text-track-cue-text">text track cue text</a> must be set to the new value.</p>
1.47 mike 7825:
7826: <p>The <dfn id="dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML"><code>getCueAsHTML()</code></dfn>
7827: method must convert the <a href="#text-track-cue-text">text track cue text</a> to a
7828: <code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> for the <a href="#media-element">media element</a>'s
7829: <code><a href="infrastructure.html#document">Document</a></code>, using the appropriate rules for doing
7830: so.
7831: </p>
7832:
1.91 mike 7833: </div><h6 id="text-tracks-describing-chapters"><span class="secno">4.8.10.12.5 </span>Text tracks describing chapters</h6><p>Chapters are segments of a <a href="#media-resource">media resource</a> with a
7834: given title. Chapters can be nested, in the same way that sections
7835: in a document outline can have subsections.</p><p>Each <a href="#text-track-cue">text track cue</a> in a <a href="#text-track">text track</a>
7836: being used for describing chapters has three key features: the
7837: <a href="#text-track-cue-start-time">text track cue start time</a>, giving the start time of the
7838: chapter, the <a href="#text-track-cue-end-time">text track cue end time</a>, giving the end
7839: time of the chapter, and the <a href="#text-track-cue-text">text track cue text</a> giving
7840: the chapter title.</p><div class="impl">
7841:
7842: <p>The <dfn id="rules-for-constructing-the-chapter-tree-from-a-text-track">rules for constructing the chapter tree from a text
7843: track</dfn> are as follows. They produce a potentially nested list
7844: of chapters, each of which have a start time, end time, title, and a
7845: list of nested chapters. This algorithm discards cues that do not
7846: correctly nest within each other, or that are out of order.</p>
7847:
7848: <ol><li><p>Let <var title="">list</var> be a copy of the <a href="#text-track-list-of-cues" title="text track list of cues">list of cues</a> of the
7849: <a href="#text-track">text track</a> being processed.</p></li>
7850:
7851: <li><p>Let <var title="">output</var> be an empty list of chapters,
7852: where a chapter is a record consisting of a start time, an end
7853: time, a title, and a (potentially empty) list of nested chapters.
7854: For the purpose of this algorithm, each chapter also has a parent
7855: chapter.</p></li>
7856:
7857: <li><p>Let <var title="">current chapter</var> be a stand-in
7858: chapter whose start time is negative infinity, whose end time is
7859: positive infinity, and whose list of nested chapters is <var title="">output</var>. (This is just used to make the algorithm
7860: easier to describe.)</p></li>
7861:
7862:
7863: <li><p><i>Loop</i>: If <var title="">list</var> is empty, jump to
7864: the step labeled <i>end</i>.</p></li>
7865:
7866:
7867: <li><p>Let <var title="">current cue</var> be the first cue in <var title="">list</var>, and then remove it from <var title="">list</var>.</p></li>
7868:
7869: <li><p>If <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track cue
7870: start time</a> is less than the start time of <var title="">current chapter</var>, then return to the step labeled
7871: <i>loop</i>.</p>
7872:
7873: </li><li><p>While <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track cue
7874: start time</a> is greater than or equal to <var title="">current
7875: chapter</var>'s end time, let <var title="">current chapter</var>
7876: be <var title="">current chapter</var>'s parent chapter.</p></li>
7877:
7878: <li><p>If <var title="">current cue</var>'s <a href="#text-track-cue-end-time">text track cue
7879: end time</a> is greater than the end time of <var title="">current chapter</var>, then return to the step labeled
7880: <i>loop</i>.</p>
7881:
7882: </li><li><p>Create a new chapter <var title="">new chapter</var>, whose
7883: start time is <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track
7884: cue start time</a>, whose end time is <var title="">current
7885: cue</var>'s <a href="#text-track-cue-end-time">text track cue end time</a>, whose title is
7886: <var title="">current cue</var>'s <a href="#text-track-cue-text">text track cue text</a>
7887: interpreted according to its rules for interpretation, and whose
7888: list of nested chapters is empty.</p></li>
7889:
7890: <li><p>Append <var title="">new chapter</var> to <var title="">current chapter</var>'s list of nested chapters, and let
7891: <var title="">current chapter</var> be <var title="">new
7892: chapter</var>'s parent.</p></li>
7893:
7894: <li><p>Let <var title="">current chapter</var> be <var title="">new
7895: chapter</var>.</p></li>
7896:
7897: <li><p>Return to the step labeled <i>loop</i>.</p></li>
7898:
7899:
7900: <li><p><i>End</i>: Return <var title="">output</var>.</p></li>
7901:
7902: </ol></div><div class="impl">
1.47 mike 7903:
1.91 mike 7904: <h6 id="cue-events"><span class="secno">4.8.10.12.6 </span>Event definitions</h6>
1.47 mike 7905:
1.121 mike 7906: <p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that (and their
7907: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
7908: event types</a>) must be
1.47 mike 7909: supported, as IDL attributes, by all objects implementing the
1.121 mike 7910: <code><a href="#texttracklist">TextTrackList</a></code> interface:</p>
7911:
7912: <table><thead><tr><th><a href="webappapis.html#event-handlers" title="event handlers">Event handler</a> </th><th><a href="webappapis.html#event-handler-event-type">Event handler event type</a>
7913: </th></tr></thead><tbody><tr><td><dfn id="handler-texttracklist-onaddtrack" title="handler-TextTrackList-onaddtrack"><code>onaddtrack</code></dfn> </td><td> <code title="event-addtrack">addtrack</code>
7914: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that (and their
7915: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
7916: event types</a>) must be supported, as IDL attributes, by all
7917: objects implementing the <code><a href="#texttrack">TextTrack</a></code> interface:</p>
1.47 mike 7918:
7919: <table><thead><tr><th><a href="webappapis.html#event-handlers" title="event handlers">Event handler</a> </th><th><a href="webappapis.html#event-handler-event-type">Event handler event type</a>
1.130 mike 7920: </th></tr></thead><tbody><tr><td><dfn id="handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange"><code>oncuechange</code></dfn> </td><td> <code title="event-cuechange">cuechange</code>
1.121 mike 7921: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that (and their
7922: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
7923: event types</a>) must be supported, as IDL attributes, by all
7924: objects implementing the <code><a href="#texttrackcue">TextTrackCue</a></code> interface:</p>
1.47 mike 7925:
7926: <table><thead><tr><th><a href="webappapis.html#event-handlers" title="event handlers">Event handler</a> </th><th><a href="webappapis.html#event-handler-event-type">Event handler event type</a>
7927: </th></tr></thead><tbody><tr><td><dfn id="handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter"><code>onenter</code></dfn> </td><td> <code title="event-enter">enter</code>
7928: </td></tr><tr><td><dfn id="handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit"><code>onexit</code></dfn> </td><td> <code title="event-exit">exit</code>
7929: </td></tr></tbody></table></div><h5 id="user-interface"><span class="secno">4.8.10.13 </span>User interface</h5><p>The <dfn id="attr-media-controls" title="attr-media-controls"><code>controls</code></dfn>
7930: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. If present, it
7931: indicates that the author has not provided a scripted controller and
7932: would like the user agent to provide its own set of controls.</p><div class="impl">
7933:
7934: <p>If the attribute is present, or if <a href="webappapis.html#concept-n-noscript" title="concept-n-noscript">scripting is disabled</a> for the
7935: <a href="#media-element">media element</a>, then the user agent should <dfn id="expose-a-user-interface-to-the-user">expose a
7936: user interface to the user</dfn>. This user interface should include
7937: features to begin playback, pause playback, seek to an arbitrary
7938: position in the content (if the content supports arbitrary seeking),
7939: change the volume, change the display of closed captions or embedded
7940: sign-language tracks, select different audio tracks or turn on audio
7941: descriptions, and show the media content in manners more suitable to
7942: the user (e.g. full-screen video or in an independent resizable
7943: window). Other controls may also be made available.</p>
7944:
7945: <p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7946: controller</a>, then the user agent should expose audio tracks
7947: from all the <a href="#slaved-media-elements">slaved media elements</a> (although avoiding
7948: duplicates if the same <a href="#media-resource">media resource</a> is being used
7949: several times). If a <a href="#media-resource">media resource</a>'s audio track
7950: exposed in this way has no known name, and it is the only audio
7951: track for a particular <a href="#media-element">media element</a>, the user agent
7952: should use the element's <code title="attr-title"><a href="elements.html#the-title-attribute">title</a></code>
7953: attribute, if any, as the name (or as part of the name) of that
7954: track.</p>
7955:
7956: <p>Even when the attribute is absent, however, user agents may
7957: provide controls to affect playback of the media resource
7958: (e.g. play, pause, seeking, and volume controls), but such features
7959: should not interfere with the page's normal rendering. For example,
7960: such features could be exposed in the <a href="#media-element">media element</a>'s
7961: context menu.</p>
7962:
7963: <p>Where possible (specifically, for starting, stopping, pausing,
7964: and unpausing playback, for seeking, for changing the rate of
7965: playback, for fast-forwarding or rewinding,
7966: for listing, enabling, and disabling text tracks,
7967: and for muting or changing the volume of the audio), user interface
7968: features exposed by the user agent must be implemented in terms of
7969: the DOM API described above, so that, e.g., all the same events
7970: fire.</p>
7971:
7972: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7973: controller</a>, the user agent's user interface for pausing and
7974: unpausing playback, for seeking, for changing the rate of playback,
7975: for fast-forwarding or rewinding, and for muting or changing the
7976: volume of audio of the entire group must be implemented in terms of
7977: the <code><a href="#mediacontroller">MediaController</a></code> API exposed on that <a href="#current-media-controller">current
7978: media controller</a>.</p>
7979:
7980: <p>The "play" function in the user agent's interface must set the
7981: <code title="">playbackRate</code> attribute to the value of the
7982: <code title="">defaultPlaybackRate</code> attribute before invoking
7983: the <code title="">play()</code> method.
7984: When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7985: controller</a>, the attributes and method with those names on
7986: that <code><a href="#mediacontroller">MediaController</a></code> object must be used. Otherwise,
7987: the attributes and method with those names on the <a href="#media-element">media
7988: element</a> itself must be used.
7989: </p>
7990:
7991: <p>Features such as fast-forward or rewind must be implemented by
7992: only changing the <code title="">playbackRate</code> attribute (and
7993: not the <code title="">defaultPlaybackRate</code> attribute).
7994: Again, when a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7995: controller</a>, the attributes with those names on that
7996: <code><a href="#mediacontroller">MediaController</a></code> object must be used; otherwise, the
7997: attributes with those names on the <a href="#media-element">media element</a> itself
7998: must be used.
7999: </p>
8000:
8001: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
8002: controller</a>, and all the <a href="#slaved-media-elements">slaved media elements</a> of
8003: that <code><a href="#mediacontroller">MediaController</a></code> are paused, the user agent should
8004: unpause all the <a href="#slaved-media-elements">slaved media elements</a> when the user
8005: invokes a user agent interface control for beginning playback.</p>
8006:
8007: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
1.80 mike 8008: controller</a>, seeking must be implemented in terms of the <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> attribute
8009: on that <code><a href="#mediacontroller">MediaController</a></code> object. Otherwise, the user
8010: agent must directly <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the
8011: requested position in the <a href="#media-element">media element</a>'s <a href="#media-timeline">media
1.47 mike 8012: timeline</a>.</p>
8013:
8014: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
8015: controller</a>, user agents may additionally provide the user
8016: with controls that directly manipulate an individual <a href="#media-element">media
8017: element</a> without affecting the <code><a href="#mediacontroller">MediaController</a></code>,
8018: but such features are considered relatively advanced and unlikely to
8019: be useful to most users.
8020:
8021: </p><p>For the purposes of listing chapters in the <a href="#media-resource">media
1.91 mike 8022: resource</a>, only <a href="#text-track" title="text track">text tracks</a> in
8023: the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>
8024: <a href="#text-track-showing" title="text track showing">showing</a> or <a href="#text-track-showing-by-default" title="text
8025: track showing by default">showing by default</a> and whose
8026: <a href="#text-track-kind">text track kind</a> is <code title="dom-timedtrack-kind-chapters">chapters</code> should be used.
8027: Such tracks must be interpreted according to the <a href="#rules-for-constructing-the-chapter-tree-from-a-text-track">rules for
8028: constructing the chapter tree from a text track</a>.</p>
1.47 mike 8029:
8030: <p>The <dfn id="dom-media-controls" title="dom-media-controls"><code>controls</code></dfn>
8031: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
8032: same name.</p>
8033:
8034: <hr></div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
8035:
8036: <dd>
8037:
8038: <p>Returns the current playback volume, as a number in the range
8039: 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.</p>
8040:
8041: <p>Can be set, to change the volume.</p>
8042:
1.119 mike 8043: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the new value is not
1.47 mike 8044: in the range 0.0 .. 1.0.</p>
8045:
8046: </dd>
8047:
8048: <dt><var title="">media</var> . <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
8049:
8050: <dd>
8051:
8052: <p>Returns true if audio is muted, overriding the <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute, and false if the
8053: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute is being
8054: honored.</p>
8055:
8056: <p>Can be set, to change whether the audio is muted or not.</p>
8057:
8058: </dd>
8059:
8060: </dl><div class="impl">
8061:
8062: <p>The <dfn id="dom-media-volume" title="dom-media-volume"><code>volume</code></dfn>
8063: attribute must return the playback volume of any audio portions of
8064: the <a href="#media-element">media element</a>, in the range 0.0 (silent) to 1.0
1.98 mike 8065: (loudest). Initially, the volume should be 1.0, but user agents may
1.47 mike 8066: remember the last set value across sessions, on a per-site basis or
8067: otherwise, so the volume may start at other values. On setting, if
1.98 mike 8068: the new value is in the range 0.0 to 1.0 inclusive, the playback
8069: volume of any audio portions of the <a href="#media-element">media element</a> must
8070: be set to the new value. If the new value is outside the range 0.0
1.119 mike 8071: to 1.0 inclusive, then, on setting, an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code>
1.98 mike 8072: exception must be raised instead.</p>
1.47 mike 8073:
8074: <p>The <dfn id="dom-media-muted" title="dom-media-muted"><code>muted</code></dfn>
1.98 mike 8075: attribute must return true if the audio output is muted and false
8076: otherwise. Initially, the audio output should not be muted (false),
8077: but user agents may remember the last set value across sessions, on
8078: a per-site basis or otherwise, so the muted state may start as muted
8079: (true). On setting, if the new value is true then the audio output
8080: should be muted and if the new value is false it should be
8081: unmuted.</p>
8082:
8083: <p>Whenever either of the values that would be returned by the <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> and <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> attributes change, the user
8084: agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
8085: event</a> named <code title="event-media-volumechange"><a href="#event-media-volumechange">volumechange</a></code> at the
8086: <a href="#media-element">media element</a>.</p>
1.47 mike 8087:
8088: <p>An element's <dfn id="effective-media-volume">effective media volume</dfn> is determined as
8089: follows:</p>
8090:
1.98 mike 8091: <ol><li><p>If the user has indicated that the user agent is to override
8092: the volume of the element, then the element's <a href="#effective-media-volume">effective media
8093: volume</a> is the volume desired by the user. Abort these
8094: steps.</p></li>
8095:
8096: <li><p>If the element's audio output is muted, the element's
8097: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
8098: steps.</p></li>
1.47 mike 8099:
8100: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>
8101: and that <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-mute-override">media
8102: controller mute override</a> is true, the element's
8103: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
8104: steps.</p></li>
8105:
1.98 mike 8106: <li><p>Let <var title="">volume</var> be the playback volume of the
8107: audio portions of the <a href="#media-element">media element</a>, in range 0.0
8108: (silent) to 1.0 (loudest).</p></li>
1.47 mike 8109:
8110: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>,
8111: multiply <var title="">volume</var> by that
8112: <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-volume-multiplier">media controller volume
8113: multiplier</a>.</p></li>
8114:
8115: <li><p>The element's <a href="#effective-media-volume">effective media volume</a> is <var title="">volume</var>, interpreted relative to the range 0.0 to
8116: 1.0, with 0.0 being silent, and 1.0 being the loudest setting,
8117: values in between increasing in loudness. The range need not be
8118: linear. The loudest setting may be lower than the system's loudest
8119: possible setting; for example the user could have set a maximum
8120: volume.</p></li>
8121:
8122: </ol></div><p>The <dfn id="attr-media-muted" title="attr-media-muted"><code>muted</code></dfn>
1.97 mike 8123: attribute on <a href="#media-element" title="media element">media elements</a> is a
8124: <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that controls the default state of
1.98 mike 8125: the audio output of the <a href="#media-resource">media resource</a>, potentially
1.97 mike 8126: overriding user preferences.</p><div class="impl">
1.47 mike 8127:
8128: <p>When a <a href="#media-element">media element</a> is created, if it has a <code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code> attribute specified, the user
1.98 mike 8129: agent must mute the <a href="#media-element">media element</a>'s audio output,
8130: overriding any user preference.</p>
1.47 mike 8131:
8132: <p>The <dfn id="dom-media-defaultmuted" title="dom-media-defaultMuted"><code>defaultMuted</code></dfn> IDL
8133: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code> content attribute.</p>
8134:
8135: </div><p class="note">This attribute has no dynamic effect (it only
8136: controls the default state of the element).</p><div class="example">
8137:
8138: <p>This video (an advertisment) autoplays, but to avoid annoying
8139: users, it does so without sound, and allows the user to turn the
8140: sound on.</p>
8141:
8142: <pre><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></pre>
8143:
8144: </div><h5 id="time-ranges"><span class="secno">4.8.10.14 </span>Time ranges</h5><p>Objects implementing the <code><a href="#timeranges">TimeRanges</a></code> interface
8145: represent a list of ranges (periods) of time.</p><pre class="idl">interface <dfn id="timeranges">TimeRanges</dfn> {
8146: readonly attribute unsigned long <a href="#dom-timeranges-length" title="dom-TimeRanges-length">length</a>;
1.101 mike 8147: double <a href="#dom-timeranges-start" title="dom-TimeRanges-start">start</a>(unsigned long index);
8148: double <a href="#dom-timeranges-end" title="dom-TimeRanges-end">end</a>(unsigned long index);
1.47 mike 8149: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-TimeRanges-length"><a href="#dom-timeranges-length">length</a></code></dt>
8150:
8151: <dd>
8152:
8153: <p>Returns the number of ranges in the object.</p>
8154:
8155: </dd>
8156:
8157: <dt><var title="">time</var> = <var title="">media</var> . <code title="dom-TimeRanges-start"><a href="#dom-timeranges-start">start</a></code>(<var title="">index</var>)</dt>
8158:
8159: <dd>
8160:
8161: <p>Returns the time for the start of the range with the given index.</p>
8162:
1.119 mike 8163: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the index is out of range.</p>
1.47 mike 8164:
8165: </dd>
8166:
8167: <dt><var title="">time</var> = <var title="">media</var> . <code title="dom-TimeRanges-end"><a href="#dom-timeranges-end">end</a></code>(<var title="">index</var>)</dt>
8168:
8169: <dd>
8170:
8171: <p>Returns the time for the end of the range with the given index.</p>
8172:
1.119 mike 8173: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the index is out of range.</p>
1.47 mike 8174:
8175: </dd>
8176:
8177: </dl><div class="impl">
8178:
8179: <p>The <dfn id="dom-timeranges-length" title="dom-TimeRanges-length"><code>length</code></dfn>
8180: IDL attribute must return the number of ranges represented by the object.</p>
8181:
8182: <p>The <dfn id="dom-timeranges-start" title="dom-TimeRanges-start"><code>start(<var title="">index</var>)</code></dfn> method must return the position
8183: of the start of the <var title="">index</var>th range represented by
8184: the object, in seconds measured from the start of the timeline that
8185: the object covers.</p>
8186:
8187: <p>The <dfn id="dom-timeranges-end" title="dom-TimeRanges-end"><code>end(<var title="">index</var>)</code></dfn> method must return the position
8188: of the end of the <var title="">index</var>th range represented by
8189: the object, in seconds measured from the start of the timeline that
8190: the object covers.</p>
8191:
1.119 mike 8192: <p>These methods must throw <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exceptions
1.47 mike 8193: if called with an <var title="">index</var> argument greater than or
8194: equal to the number of ranges represented by the object.</p>
8195:
8196: <p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said to be a
8197: <dfn id="normalized-timeranges-object">normalized <code>TimeRanges</code> object</dfn>, the ranges it
8198: represents must obey the following criteria:</p>
8199:
8200: <ul><li>The start of a range must be greater than the end of all
8201: earlier ranges.</li>
8202:
8203: <li>The start of a range must be less than the end of that same
8204: range.</li>
8205:
8206: </ul><p>In other words, the ranges in such an object are ordered, don't
8207: overlap, aren't empty, and don't touch (adjacent ranges are folded
8208: into one bigger range).</p>
8209:
1.62 mike 8210: <p>Ranges in a <code><a href="#timeranges">TimeRanges</a></code> object must be inclusive.</p>
8211:
8212: <p class="example">Thus, the end of a range would be equal to the
8213: start of a following adjacent (touching but not overlapping) range.
8214: Similarly, a range covering a whole timeline anchored at zero would
8215: have a start equal to zero and an end equal to the duration of the
8216: timeline.</p>
8217:
1.47 mike 8218: <p>The timelines used by the objects returned by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code>, <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> and <code title="dom-media-played"><a href="#dom-media-played">played</a></code> IDL attributes of <a href="#media-element" title="media element">media elements</a> must be that element's
8219: <a href="#media-timeline">media timeline</a>.</p>
8220:
1.121 mike 8221: </div><h5 id="event-definitions"><span class="secno">4.8.10.15 </span>Event definitions</h5><pre class="idl">[Constructor(DOMString type, optional <a href="#trackeventinit">TrackEventInit</a> eventInitDict)]
8222: interface <dfn id="trackevent">TrackEvent</dfn> : <a href="infrastructure.html#event">Event</a> {
8223: readonly attribute object? <a href="#dom-trackevent-track" title="dom-TrackEvent-track">track</a>;
8224: };
8225:
8226: dictionary <dfn id="trackeventinit">TrackEventInit</dfn> : <a href="infrastructure.html#eventinit">EventInit</a> {
8227: object? Track;
8228: };</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code></dt>
8229:
8230: <dd>
8231:
8232: <p>Returns the track object (<code><a href="#texttrack">TextTrack</a></code>,
8233: <code><a href="#audiotrack">AudioTrack</a></code>, or <code><a href="#videotrack">VideoTrack</a></code>) to which the
8234: event relates.</p>
8235:
8236: </dd>
8237:
8238: </dl><div class="impl">
8239:
8240: <p>The <dfn id="dom-trackevent-track" title="dom-TrackEvent-track"><code>track</code></dfn>
8241: attribute must return the value it was initialized to. When the
8242: object is created, this attribute must be initialized to null. It
8243: represents the context information for the event.</p>
8244:
8245: </div><h5 id="mediaevents"><span class="secno">4.8.10.16 </span>Event summary</h5><p><i>This section is non-normative.</i></p><p>The following events fire on <a href="#media-element" title="media element">media
1.47 mike 8246: elements</a> as part of the processing model described above:</p><table><thead><tr><th>Event name
8247: </th><th>Interface
1.64 mike 8248: </th><th>Fired when...
1.47 mike 8249: </th><th>Preconditions
8250:
8251: </th></tr></thead><tbody><tr><td><dfn id="event-media-loadstart" title="event-media-loadstart"><code>loadstart</code></dfn>
8252: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8253: </td><td>The user agent begins looking for <a href="#media-data">media data</a>, as part of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection algorithm</a>.
8254: </td><td><code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> equals <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>
8255: </td></tr><tr><td><dfn id="event-media-progress" title="event-media-progress"><code>progress</code></dfn>
8256: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8257: </td><td>The user agent is fetching <a href="#media-data">media data</a>.
8258: </td><td><code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> equals <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>
8259: </td></tr><tr><td><dfn id="event-media-suspend" title="event-media-suspend"><code>suspend</code></dfn>
8260: </td><td><code><a href="infrastructure.html#event">Event</a></code>
1.112 mike 8261: </td><td>The user agent is intentionally not currently fetching <a href="#media-data">media data</a>.
1.47 mike 8262: </td><td><code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> equals <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
8263: </td></tr><tr><td><dfn id="event-media-abort" title="event-media-abort"><code>abort</code></dfn>
8264: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8265: </td><td>The user agent stops fetching the <a href="#media-data">media data</a> before it is completely downloaded, but not due to an error.
8266: </td><td><code title="dom-media-error"><a href="#dom-media-error">error</a></code> is an object with the code <code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.
8267: <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> equals either <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> or <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>, depending on when the download was aborted.
8268: </td></tr><tr><td><dfn id="event-media-error" title="event-media-error"><code>error</code></dfn>
8269: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8270: </td><td>An error occurs while fetching the <a href="#media-data">media data</a>.
8271: </td><td><code title="dom-media-error"><a href="#dom-media-error">error</a></code> is an object with the code <code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code> or higher.
8272: <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> equals either <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> or <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>, depending on when the download was aborted.
8273: </td></tr><tr><td><dfn id="event-media-emptied" title="event-media-emptied"><code>emptied</code></dfn>
8274: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8275: </td><td>A <a href="#media-element">media element</a> whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> was previously not in the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> state has just switched to that state (either because of a fatal error during load that's about to be reported, or because the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code> method was invoked while the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection algorithm</a> was already running).
8276: </td><td><code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> is <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>; all the IDL attributes are in their initial states.
8277: </td></tr><tr><td><dfn id="event-media-stalled" title="event-media-stalled"><code>stalled</code></dfn>
8278: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8279: </td><td>The user agent is trying to fetch <a href="#media-data">media data</a>, but data is unexpectedly not forthcoming.
8280: </td><td><code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> is <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.
8281:
8282: </td></tr></tbody><tbody><tr><td><dfn id="event-media-loadedmetadata" title="event-media-loadedmetadata"><code>loadedmetadata</code></dfn>
8283: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8284: </td><td>The user agent has just determined the duration and dimensions of the <a href="#media-resource">media resource</a>
8285: and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>.
8286: </td><td><code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is newly equal to <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> or greater for the first time.
8287: </td></tr><tr><td><dfn id="event-media-loadeddata" title="event-media-loadeddata"><code>loadeddata</code></dfn>
8288: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8289: </td><td>The user agent can render the <a href="#media-data">media data</a> at the <a href="#current-playback-position">current playback position</a> for the first time.
8290: </td><td><code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> newly increased to <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or greater for the first time.
8291: </td></tr><tr><td><dfn id="event-media-canplay" title="event-media-canplay"><code>canplay</code></dfn>
8292: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8293: </td><td>The user agent can resume playback of the <a href="#media-data">media data</a>, but estimates that if playback were to be started now, the <a href="#media-resource">media resource</a> could not be rendered at the current playback rate up to its end without having to stop for further buffering of content.
8294: </td><td><code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> newly increased to <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or greater.
8295: </td></tr><tr><td><dfn id="event-media-canplaythrough" title="event-media-canplaythrough"><code>canplaythrough</code></dfn>
8296: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8297: </td><td>The user agent estimates that if playback were to be started now, the <a href="#media-resource">media resource</a> could be rendered at the current playback rate all the way to its end without having to stop for further buffering.
8298: </td><td><code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is newly equal to <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>.
8299: </td></tr><tr><td><dfn id="event-media-playing" title="event-media-playing"><code>playing</code></dfn>
8300: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8301: </td><td>Playback is ready to start after having been paused or delayed due to lack of <a href="#media-data">media data</a>.
8302: </td><td><code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is newly equal to or greater than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> and <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is false, or <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false and <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is equal to or greater than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>. Even if this event fires, the element might still not be <a href="#potentially-playing">potentially playing</a>, e.g. if
8303: the element is <a href="#blocked-on-its-media-controller">blocked on its media controller</a> (e.g. because the <a href="#current-media-controller">current media controller</a> is paused, or another <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a> is stalled somehow, or because the <a href="#media-resource">media resource</a> has no data corresponding to the <a href="#media-controller-position">media controller position</a>), or
8304: the element is <a href="#paused-for-user-interaction">paused for user interaction</a>.
8305: </td></tr><tr><td><dfn id="event-media-waiting" title="event-media-waiting"><code>waiting</code></dfn>
8306: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8307: </td><td>Playback has stopped because the next frame is not available, but the user agent expects that frame to become available in due course.
8308: </td><td><code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is equal to or less than <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>, and <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is false. Either <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true, or the <a href="#current-playback-position">current playback position</a> is not contained in any of the ranges in <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code>. It is possible for playback to stop for other reasons without <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> being false, but those reasons do not fire this event (and when those situations resolve, a separate <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> event is not fired either): e.g.
8309: the element is newly <a href="#blocked-on-its-media-controller">blocked on its media controller</a>, or
8310: <a href="#ended-playback" title="ended playback">playback ended</a>, or playback <a href="#stopped-due-to-errors">stopped due to errors</a>, or the element has <a href="#paused-for-user-interaction">paused for user interaction</a>.
8311: </td></tr></tbody><tbody><tr><td><dfn id="event-media-seeking" title="event-media-seeking"><code>seeking</code></dfn>
8312: </td><td><code><a href="infrastructure.html#event">Event</a></code>
1.73 mike 8313: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to true.
1.47 mike 8314: </td><td>
8315: </td></tr><tr><td><dfn id="event-media-seeked" title="event-media-seeked"><code>seeked</code></dfn>
8316: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8317: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to false.
8318: </td><td>
8319: </td></tr><tr><td><dfn id="event-media-ended" title="event-media-ended"><code>ended</code></dfn>
8320: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8321: </td><td>Playback has stopped because the end of the <a href="#media-resource">media resource</a> was reached.
8322: </td><td><code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> equals the end of the <a href="#media-resource">media resource</a>; <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> is true.
8323:
8324: </td></tr></tbody><tbody><tr><td><dfn id="event-media-durationchange" title="event-media-durationchange"><code>durationchange</code></dfn>
8325: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8326: </td><td>The <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute has just been updated.
8327: </td><td>
8328: </td></tr><tr><td><dfn id="event-media-timeupdate" title="event-media-timeupdate"><code>timeupdate</code></dfn>
8329: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8330: </td><td>The <a href="#current-playback-position">current playback position</a> changed as part of normal playback or in an especially interesting way, for example discontinuously.
8331: </td><td>
8332: </td></tr><tr><td><dfn id="event-media-play" title="event-media-play"><code>play</code></dfn>
8333: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8334: </td><td>The element is no longer paused. Fired after the <code title="dom-media-play"><a href="#dom-media-play">play()</a></code> method has returned, or when the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute has caused playback to begin.
8335: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false.
8336: </td></tr><tr><td><dfn id="event-media-pause" title="event-media-pause"><code>pause</code></dfn>
8337: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8338: </td><td>The element has been paused. Fired after the <code title="dom-media-pause"><a href="#dom-media-pause">pause()</a></code> method has returned.
8339: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly true.
8340: </td></tr><tr><td><dfn id="event-media-ratechange" title="event-media-ratechange"><code>ratechange</code></dfn>
8341: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8342: </td><td>Either the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute has just been updated.
8343: </td><td>
8344: </td></tr><tr><td><dfn id="event-media-volumechange" title="event-media-volumechange"><code>volumechange</code></dfn>
8345: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8346: </td><td>Either the <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute or the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> attribute has changed. Fired after the relevant attribute's setter has returned.
8347: </td><td>
8348: </td></tr></tbody></table><p>The following events fire on <code><a href="#mediacontroller">MediaController</a></code> objects:</p><table><thead><tr><th>Event name
8349: </th><th>Interface
1.64 mike 8350: </th><th>Fired when...
1.47 mike 8351:
8352: </th></tr></thead><tbody><tr><td><dfn id="event-mediacontroller-emptied" title="event-MediaController-emptied"><code>emptied</code></dfn>
8353: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8354: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> newly have <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> or greater, or there are no longer any <a href="#slaved-media-elements">slaved media elements</a>.
8355: </td></tr><tr><td><dfn id="event-mediacontroller-loadedmetadata" title="event-MediaController-loadedmetadata"><code>loadedmetadata</code></dfn>
8356: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8357: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> newly have <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> set to <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> or greater.
8358: </td></tr><tr><td><dfn id="event-mediacontroller-loadeddata" title="event-MediaController-loadeddata"><code>loadeddata</code></dfn>
8359: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8360: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> newly have <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> set to <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or greater.
8361: </td></tr><tr><td><dfn id="event-mediacontroller-canplay" title="event-MediaController-canplay"><code>canplay</code></dfn>
8362: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8363: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> newly have <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> set to <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or greater.
8364: </td></tr><tr><td><dfn id="event-mediacontroller-canplaythrough" title="event-MediaController-canplaythrough"><code>canplaythrough</code></dfn>
8365: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8366: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> newly have <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> set to <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> or greater.
8367: </td></tr><tr><td><dfn id="event-mediacontroller-playing" title="event-MediaController-playing"><code>playing</code></dfn>
8368: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8369: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is no longer a <a href="#blocked-media-controller">blocked media controller</a>.
1.75 mike 8370: </td></tr><tr><td><dfn id="event-mediacontroller-ended" title="event-MediaController-ended"><code>ended</code></dfn>
8371: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8372: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> has reached the end of all the <a href="#slaved-media-elements">slaved media elements</a>.
1.47 mike 8373: </td></tr><tr><td><dfn id="event-mediacontroller-waiting" title="event-MediaController-waiting"><code>waiting</code></dfn>
8374: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8375: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is now a <a href="#blocked-media-controller">blocked media controller</a>.
8376: </td></tr><tr><td><dfn id="event-mediacontcoller-ended" title="event-MediaContcoller-ended"><code>ended</code></dfn>
8377: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8378: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> have newly <a href="#ended-playback">ended playback</a>.
8379:
8380: </td></tr></tbody><tbody><tr><td><dfn id="event-mediacontroller-durationchange" title="event-MediaController-durationchange"><code>durationchange</code></dfn>
8381: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8382: </td><td>The <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code> attribute has just been updated.
8383: </td></tr><tr><td><dfn id="event-mediacontroller-timeupdate" title="event-MediaController-timeupdate"><code>timeupdate</code></dfn>
8384: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8385: </td><td>The <a href="#media-controller-position">media controller position</a> changed.
8386: </td></tr><tr><td><dfn id="event-mediacontroller-play" title="event-MediaController-play"><code>play</code></dfn>
8387: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8388: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly false.
8389: </td></tr><tr><td><dfn id="event-mediacontroller-pause" title="event-MediaController-pause"><code>pause</code></dfn>
8390: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8391: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly true.
8392: </td></tr><tr><td><dfn id="event-mediacontroller-ratechange" title="event-MediaController-ratechange"><code>ratechange</code></dfn>
8393: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8394: </td><td>Either the <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> attribute or the <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> attribute has just been updated.
8395: </td></tr><tr><td><dfn id="event-mediacontroller-volumechange" title="event-MediaController-volumechange"><code>volumechange</code></dfn>
8396: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8397: </td><td>Either the <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> attribute or the <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> attribute has just been updated.
8398: </td></tr></tbody></table><div class="impl">
8399:
1.121 mike 8400: <h5 id="security-and-privacy-considerations"><span class="secno">4.8.10.17 </span>Security and privacy considerations</h5>
1.47 mike 8401:
8402: <p>The main security and privacy implications of the
8403: <code><a href="#the-video-element">video</a></code> and <code><a href="#the-audio-element">audio</a></code> elements come from the
8404: ability to embed media cross-origin. There are two directions that
8405: threats can flow: from hostile content to a victim page, and from a
8406: hostile page to victim content.</p>
8407:
8408: <hr><p>If a victim page embeds hostile content, the threat is that the
8409: content might contain scripted code that attempts to interact with
8410: the <code><a href="infrastructure.html#document">Document</a></code> that embeds the content. To avoid this,
8411: user agents must ensure that there is no access from the content to
8412: the embedding page. In the case of media content that uses DOM
8413: concepts, the embedded content must be treated as if it was in its
8414: own unrelated <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>.</p>
8415:
8416: <p class="example">For instance, if an SVG animation was embedded in
8417: a <code><a href="#the-video-element">video</a></code> element, the user agent would not give it
8418: access to the DOM of the outer page. From the perspective of scripts
8419: in the SVG resource, the SVG file would appear to be in a lone
8420: top-level browsing context with no parent.</p>
8421:
8422: <hr><p>If a hostile page embeds victim content, the threat is that the
8423: embedding page could obtain information from the content that it
1.58 mike 8424: would not otherwise have access to. The API does expose some
8425: information: the existence of the media, its type, its duration, its
8426: size, and the performance characteristics of its host. Such
8427: information is already potentially problematic, but in practice the
8428: same information can more or less be obtained using the
8429: <code><a href="embedded-content-1.html#the-img-element">img</a></code> element, and so it has been deemed acceptable.</p>
8430:
8431: <p>However, significantly more sensitive information could be
8432: obtained if the user agent further exposes metadata within the
1.61 mike 8433: content such as subtitles or chapter titles. Such information is
8434: therefore only exposed if the video resource passes a CORS
8435: <a href="infrastructure.html#resource-sharing-check">resource sharing check</a>. The <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> attribute allows
1.101 mike 8436: authors to control how this check is performed. <a href="references.html#refsCORS">[CORS]</a></p>
1.61 mike 8437:
8438: <p class="example">Without this restriction, an attacker could trick
8439: a user running within a corporate network into visiting a site that
8440: attempts to load a video from a previously leaked location on the
8441: corporation's intranet. If such a video included confidential plans
8442: for a new product, then being able to read the subtitles would
8443: present a serious confidentiality breach.</p>
1.47 mike 8444:
1.121 mike 8445: </div><h5 id="best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.18 </span>Best practices for authors using media elements</h5><p><i>This section is non-normative.</i></p><p>Playing audio and video resources on small devices such as
1.47 mike 8446: set-top boxes or mobile phones is often constrained by limited
8447: hardware resources in the device. For example, a device might only
8448: support three simultaneous videos. For this reason, it is a good
8449: practice to release resources held by <a href="#media-element" title="media
8450: element">media elements</a> when they are done playing, either by
8451: being very careful about removing all references to the element and
8452: allowing it to be garbage collected, or, even better, by removing
8453: the element's <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and
8454: any <code><a href="#the-source-element">source</a></code> element descendants, and invoking the
8455: element's <code title="dom-media-load"><a href="#dom-media-load">load()</a></code> method.</p><p>Similarly, when the playback rate is not exactly 1.0, hardware,
8456: software, or format limitations can cause video frames to be dropped
8457: and audio to be choppy or muted.</p><div class="impl">
8458:
1.121 mike 8459: <h5 id="best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.19 </span>Best practices for implementors of media elements</h5>
1.47 mike 8460:
8461: <p><i>This section is non-normative.</i></p>
8462:
8463: <p>How accurately various aspects of the <a href="#media-element">media element</a>
8464: API are implemented is considered a quality-of-implementation issue.</p>
8465:
8466: <p>For example, when implementing the <code title="attr-media-buffered">buffered</code> attribute, how precise
8467: an implementation reports the ranges that have been buffered depends
8468: on how carefully the user agent inspects the data. Since the API
8469: reports ranges as times, but the data is obtained in byte streams, a
8470: user agent receiving a variable-bit-rate stream might only be able
8471: to determine precise times by actually decoding all of the data.
8472: User agents aren't required to do this, however; they can instead
8473: return estimates (e.g. based on the average bit rate seen so far)
8474: which get revised as more information becomes available.</p>
8475:
8476: <p>As a general rule, user agents are urged to be conservative
8477: rather than optimistic. For example, it would be bad to report that
8478: everything had been buffered when it had not.</p>
8479:
8480: <p>Another quality-of-implementation issue would be playing a video
8481: backwards when the codec is designed only for forward playback (e.g.
8482: there aren't many key frames, and they are far apart, and the
8483: intervening frames only have deltas from the previous frame). User
8484: agents could do a poor job, e.g. only showing key frames; however,
8485: better implementations would do more work and thus do a better job,
8486: e.g. actually decoding parts of the video forwards, storing the
8487: complete frames, and then playing the frames backwards.</p>
8488:
8489: <p>Similarly, while implementations are allowed to drop buffered
8490: data at any time (there is no requirement that a user agent keep all
8491: the media data obtained for the lifetime of the media element), it
8492: is again a quality of implementation issue: user agents with
8493: sufficient resources to keep all the data around are encouraged to
8494: do so, as this allows for a better user experience. For example, if
8495: the user is watching a live stream, a user agent could allow the
8496: user only to view the live video; however, a better user agent would
8497: buffer everything and allow the user to seek through the earlier
8498: material, pause it, play it forwards and backwards, etc.</p>
8499:
8500: <p>When multiple tracks are synchronised with a
8501: <code><a href="#mediacontroller">MediaController</a></code>, it is possible for scripts to add and
8502: remove media elements from the <code><a href="#mediacontroller">MediaController</a></code>'s list
8503: of <a href="#slaved-media-elements">slaved media elements</a>, even while these tracks are
8504: playing. How smoothly the media plays back in such situations is
8505: another quality-of-implementation issue.</p>
8506:
8507: <hr><p>When a <a href="#media-element">media element</a> that is paused is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">removed from a
8508: document</a> and not reinserted before the next time the
8509: <a href="webappapis.html#event-loop">event loop</a> spins, implementations that are resource
8510: constrained are encouraged to take that opportunity to release all
8511: hardware resources (like video planes, networking resources, and
8512: data buffers) used by the <a href="#media-element">media element</a>. (User agents
8513: still have to keep track of the playback position and so forth,
8514: though, in case playback is later restarted.)</p>
8515:
1.1 mike 8516: </div></body></html>
Webmaster
![[BACK]](/https/dev.w3.org/cvsweb/icons/back.gif){kind=icon}
Return to the-iframe-element.html CVS log ![[TXT]](/https/dev.w3.org/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/https/dev.w3.org/cvsweb/icons/dir.gif){kind=icon}
Up to [Public] / html5 / spec