Annotation of html5/spec/the-iframe-element.html, revision 1.97
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; }
55: dl.switch { padding-left: 2em; }
56: dl.switch > dt { text-indent: -1.5em; }
57: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
58: dl.triple { padding: 0 0 0 1em; }
59: dl.triple dt, dl.triple dd { margin: 0; display: inline }
60: dl.triple dt:after { content: ':'; }
61: dl.triple dd:after { content: '\A'; white-space: pre; }
62: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
63: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
64: a .diff-new { border-bottom: 1px blue solid; }
65:
66: h2 { page-break-before: always; }
67: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
68: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
69:
1.26 mike 70: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
71: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 mike 72:
73: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
74: div.head p { margin: 0; }
75: div.head h1 { margin: 0; }
76: div.head .logo { float: right; margin: 0 1em; }
77: div.head .logo img { border: none } /* remove border from top image */
78: div.head dl { margin: 1em 0; }
79: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
80:
81: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
82: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
83: body > .toc > li > * { margin-bottom: 0.5em; }
84: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
85: .toc, .toc li { list-style: none; }
86:
87: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
88: .brief li { margin: 0; padding: 0; }
89: .brief li p { margin: 0; padding: 0; }
90:
91: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
92: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
93: .category-list li { display: inline; }
94: .category-list li:not(:last-child)::after { content: ', '; }
95: .category-list li > span, .category-list li > a { text-transform: lowercase; }
96: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
97:
98: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
99: .XXX > :first-child { margin-top: 0; }
100: p .XXX { line-height: 3em; }
101: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
102: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
103: .annotation :link, .annotation :visited { color: inherit; }
104: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
105: .annotation span { border: none ! important; }
106: .note { color: green; background: transparent; font-family: sans-serif; }
107: .warning { color: red; background: transparent; }
108: .note, .warning { font-weight: bolder; font-style: italic; }
1.83 mike 109: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 mike 110: p.note, div.note { padding: 0.5em 2em; }
111: span.note { padding: 0 2em; }
112: .note p:first-child, .warning p:first-child { margin-top: 0; }
113: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
114: .warning:before { font-style: normal; }
115: p.note:before { content: 'Note: '; }
116: p.warning:before { content: '\26A0 Warning! '; }
117:
118: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
119: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
120: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.12 mike 121: .bookkeeping dt { margin: 0.5em 2em 0; }
122: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 mike 123:
124: h4 { position: relative; z-index: 3; }
125: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
126: .element {
127: background: #EEEEFF;
128: color: black;
129: margin: 0 0 1em 0.15em;
130: padding: 0 1em 0.25em 0.75em;
131: border-left: solid #9999FF 0.25em;
132: position: relative;
133: z-index: 1;
134: }
135: .element:before {
136: position: absolute;
137: z-index: 2;
138: top: 0;
139: left: -1.15em;
140: height: 2em;
141: width: 0.9em;
142: background: #EEEEFF;
143: content: ' ';
144: border-style: none none solid solid;
145: border-color: #9999FF;
146: border-width: 0.25em;
147: }
148:
149: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
150: td > .example:only-child { margin: 0 0 0 0.1em; }
151:
152: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
153: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
154: ul.domTree li li { list-style: none; }
155: 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; }
156: 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; }
157: ul.domTree span { font-style: italic; font-family: serif; }
158: ul.domTree .t1 code { color: purple; font-weight: bold; }
159: ul.domTree .t2 { font-style: normal; font-family: monospace; }
160: ul.domTree .t2 .name { color: black; font-weight: bold; }
161: ul.domTree .t2 .value { color: blue; font-weight: normal; }
162: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
163: ul.domTree .t7 code, .domTree .t8 code { color: green; }
164: ul.domTree .t10 code { color: teal; }
165:
166: body.dfnEnabled dfn { cursor: pointer; }
167: .dfnPanel {
168: display: inline;
169: position: absolute;
170: z-index: 10;
171: height: auto;
172: width: auto;
173: padding: 0.5em 0.75em;
174: font: small sans-serif, Droid Sans Fallback;
175: background: #DDDDDD;
176: color: black;
177: border: outset 0.2em;
178: }
179: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
180: .dfnPanel :link, .dfnPanel :visited { color: black; }
181: .dfnPanel p { font-weight: bolder; }
182: .dfnPanel * + p { margin-top: 0.25em; }
183: .dfnPanel li { list-style-position: inside; }
184:
185: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
186: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
187: #configUI p label { display: block; }
188: #configUI #updateUI, #configUI .loginUI { text-align: center; }
189: #configUI input[type=button] { display: block; margin: auto; }
1.11 mike 190:
1.30 mike 191: fieldset { margin: 1em; padding: 0.5em 1em; }
192: fieldset > legend + * { margin-top: 0; }
1.21 mike 193: fieldset > :last-child { margin-bottom: 0; }
1.30 mike 194: fieldset p { margin: 0.5em 0; }
195:
1.62 mike 196: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><style type="text/css">
1.1 mike 197:
198: .applies thead th > * { display: block; }
199: .applies thead code { display: block; }
200: .applies tbody th { whitespace: nowrap; }
201: .applies td { text-align: center; }
202: .applies .yes { background: yellow; }
203:
1.14 mike 204: .matrix, .matrix td { border: hidden; text-align: right; }
1.1 mike 205: .matrix { margin-left: 2em; }
206:
207: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
208: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
209: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
210:
1.17 mike 211: td.eg { border-width: thin; text-align: center; }
212:
1.1 mike 213: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
214: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
215: #table-example-1 caption { padding-bottom: 0.5em; }
216: #table-example-1 thead, #table-example-1 tbody { border: none; }
217: #table-example-1 th, #table-example-1 td { border: solid thin; }
218: #table-example-1 th { font-weight: normal; }
219: #table-example-1 td { border-style: none solid; vertical-align: top; }
220: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
221: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
222: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
223: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
224: #table-example-1 tbody td:first-child::after { content: leader(". "); }
225: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
226: #table-example-1 tbody td:first-child + td { width: 10em; }
227: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
228: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
229:
230: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
231: .apple-table-examples * { font-family: "Times", serif; }
232: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
233: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
234: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
235: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
236: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
237: .apple-table-examples td { text-align: right; vertical-align: top; }
238: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
239: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
240: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
241: .apple-table-examples sup { line-height: 0; }
242:
243: .details-example img { vertical-align: top; }
244:
1.40 mike 245: #base64-table {
246: white-space: nowrap;
247: font-size: 0.6em;
248: column-width: 6em;
249: column-count: 5;
250: column-gap: 1em;
251: -moz-column-width: 6em;
252: -moz-column-count: 5;
253: -moz-column-gap: 1em;
254: -webkit-column-width: 6em;
255: -webkit-column-count: 5;
256: -webkit-column-gap: 1em;
257: }
258: #base64-table thead { display: none; }
259: #base64-table * { border: none; }
260: #base64-table tbody td:first-child:after { content: ':'; }
261: #base64-table tbody td:last-child { text-align: right; }
262:
1.1 mike 263: #named-character-references-table {
1.19 mike 264: white-space: nowrap;
1.1 mike 265: font-size: 0.6em;
1.19 mike 266: column-width: 30em;
1.1 mike 267: column-gap: 1em;
1.19 mike 268: -moz-column-width: 30em;
1.1 mike 269: -moz-column-gap: 1em;
1.19 mike 270: -webkit-column-width: 30em;
1.1 mike 271: -webkit-column-gap: 1em;
272: }
1.19 mike 273: #named-character-references-table > table > tbody > tr > td:first-child + td,
1.1 mike 274: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
275: #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 276: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
1.1 mike 277:
1.2 mike 278: .glyph.control { color: red; }
279:
1.4 mike 280: @font-face {
281: font-family: 'Essays1743';
282: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
283: }
284: @font-face {
285: font-family: 'Essays1743';
286: font-weight: bold;
287: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
288: }
289: @font-face {
290: font-family: 'Essays1743';
291: font-style: italic;
292: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
293: }
294: @font-face {
295: font-family: 'Essays1743';
296: font-style: italic;
297: font-weight: bold;
298: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
299: }
300:
1.1 mike 301: </style><style type="text/css">
302: .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.61 mike 303: </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 304: function getCookie(name) {
305: var params = location.search.substr(1).split("&");
306: for (var index = 0; index < params.length; index++) {
307: if (params[index] == name)
308: return "1";
309: var data = params[index].split("=");
310: if (data[0] == name)
311: return unescape(data[1]);
312: }
313: var cookies = document.cookie.split("; ");
314: for (var index = 0; index < cookies.length; index++) {
315: var data = cookies[index].split("=");
316: if (data[0] == name)
317: return unescape(data[1]);
318: }
319: return null;
320: }
321: </script>
1.1 mike 322: <script src="link-fixup.js"></script>
1.36 mike 323: <link href="style.css" rel="stylesheet"><link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
1.1 mike 324: <link href="spec.html#contents" title="Table of contents" rel="index">
1.47 mike 325: <link href="the-canvas-element.html" title="4.8.11 The canvas element" rel="next">
1.54 mike 326: </head><body><div class="head" id="head">
1.1 mike 327: <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 328:
1.1 mike 329: <h1>HTML5</h1>
330: </div><div>
1.36 mike 331: <a href="embedded-content-1.html" class="prev">4.8 Embedded content</a> –
1.1 mike 332: <a href="spec.html#contents">Table of contents</a> –
1.47 mike 333: <a href="the-canvas-element.html" class="next">4.8.11 The canvas element</a>
334: <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 335: <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 336: <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 337: <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.91 mike 338: <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#mediaevents"><span class="secno">4.8.10.15 </span>Event summary</a></li><li><a href="the-iframe-element.html#security-and-privacy-considerations"><span class="secno">4.8.10.16 </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.17 </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.18 </span>Best practices for implementors of media elements</a></li></ol></li></ol></li></ol></li></ol></div>
1.1 mike 339:
1.25 mike 340: <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 341: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
342: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
343: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
344: <dd><a href="content-models.html#interactive-content">Interactive 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>
372: </dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
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.1 mike 381: the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
382: syntax</a> that consists of the following syntactic components,
383: in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
384: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
385:
386: <li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
387:
388: </li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
389: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
390:
1.47 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:
393: <li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
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
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
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
431: <a href="fetching-resources.html#content-type">Content-Type</a> is <code><a href="iana.html#text-html">text/html</a></code>, whose
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>
548: <p>Written by <a href="/users/cap">cap</a>.
549: <time pubdate>2009-08-21T23:32Z</time></p>
550: </footer>
551: <article>
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>
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>
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
566: <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute would
567: end prematurely), and the way raw ampersands (e.g. in URLs or in
568: prose) mentioned in the sandboxed content have to be
569: <em>doubly</em> escaped — once so that the ampersand is
570: preserved when originally parsing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and once more
571: to prevent the ampersand from being misinterpreted when parsing the
572: sandboxed content.</p>
573:
574: </div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
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
578: embedding of content.</p><p class="note">Due to restrictions of <span>the XML syntax</span>,
1.24 mike 579: in XML the U+003C LESS-THAN SIGN character (<) needs to be
580: 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
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
608: does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
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
620: <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
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
623: <a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
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
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
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.1 mike 642: context">browsing contexts</a>, and plugins are disabled. The
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
658: served using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME type.</p><div class="impl">
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>,
714: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
715: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
716: browsing context</a>.</p>
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:
754: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
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
838: sandboxed, it is treated by the user agent as being from a unique
839: origin, despite the content being served from the same site. Thus
840: it is affected by all the normal cross-site restrictions. In
841: addition, the embedded page has scripting disabled, plugins
842: disabled, forms disabled, and it cannot navigate any frames or
843: windows other than itself (or any frames or windows it itself
844: embeds).</p>
845:
846: <pre><p>We're not scared of you! Here is your content, unedited:</p>
847: <iframe sandbox src="getusercontent.cgi?id=12193"></iframe></pre>
848:
849: <p>Note that cookies are still sent to the server in the <code title="">getusercontent.cgi</code> request, though they are not
850: visible in the <code title="dom-document-cookie"><a href="dom.html#dom-document-cookie">document.cookie</a></code> IDL
851: attribute.</p>
852:
853: <p class="warning">It is important that the server serve the
854: user-provided HTML using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME
855: type so that if the attacker convinces the user to visit that page
856: directly, the page doesn't run in the context of the site's origin,
857: which would make the user vulnerable to any attack found in the
858: page.</p>
859:
860: </div><div class="example">
861:
862: <p>In this example, a gadget from another site is embedded. The
863: gadget has scripting and forms enabled, and the origin sandbox
864: restrictions are lifted, allowing the gadget to communicate with
865: its originating server. The sandbox is still useful, however, as it
866: disables plugins and popups, thus reducing the risk of the user
867: being exposed to malware and other annoyances.</p>
868:
869: <pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
870: src="http://maps.example.com/embedded.html"></iframe></pre>
871:
872: </div><div class="example">
873:
874: <p>Suppose a file A contained the following fragment:</p>
875:
876: <pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
877:
878: <p>Suppose that file B contained an iframe also:</p>
879:
880: <pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
881:
882: <p>Further, suppose that file C contained a link:</p>
883:
884: <pre><a href=D>Link</a></pre>
885:
886: <p>For this example, suppose all the files were served as
887: <code><a href="iana.html#text-html">text/html</a></code>.</p>
888:
889: <p>Page C in this scenario has all the sandboxing flags
890: set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
891: scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
892: keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
893: disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
894: have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
895: set.</p>
896:
897: <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 and
898: B. This would change nothing immediately. If the user clicked the
899: link in C, loading page D into the <code><a href="#the-iframe-element">iframe</a></code> in B, page D
900: would now act as if the <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>
901: and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
902: set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
903: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
904: loaded.</p>
905:
906: <p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
907: ill-advised, because it can make it quite hard to reason about what
908: will be allowed and what will not.</p>
909:
910: </div><p class="note">Potentially hostile files can be served from the
911: same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code> element
912: by labeling them as <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> instead of
913: <code><a href="iana.html#text-html">text/html</a></code>. This ensures that scripts in the files are
914: unable to attack the site (as if they were actually served from
915: another server), even if the user is tricked into visiting those
916: 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>
917: 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>
918: keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
919: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
920: "sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
921: reload itself, effectively breaking out of the sandbox
1.46 mike 922: altogether.</p><hr><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
1.1 mike 923: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
924: indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
925: context</a> is to be rendered in a manner that makes it appear to
926: be part of the containing document (seamlessly included in the
927: parent document). <span class="impl">Specifically, when the
928: attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
929: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
930: the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
931: <code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
932: <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
933: <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
934: document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
935: document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
936: address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
1.33 mike 937: <code><a href="#the-iframe-element">iframe</a></code> element's document, or the <a href="browsers.html#browsing-context">browsing
938: context</a>'s <a href="browsers.html#active-document">active document</a> is <a href="#an-iframe-srcdoc-document">an
939: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
940: document</a>, the following requirements apply:</span></p><div class="impl">
1.1 mike 941:
1.13 mike 942: <ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
943: flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
944: will <a href="history.html#seamlessLinks">cause links to open in the parent
945: browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
946: override</a> is used (<code title="">target="_self"</code>).</p></li>
1.1 mike 947:
948: <li><p>In a CSS-supporting user agent: the user agent must add all
949: the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
950: the cascade of the <a href="browsers.html#active-document">active document</a> of the
951: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
952: at the appropriate cascade levels, before any style sheets
953: specified by the document itself.</p></li>
954:
955: <li><p>In a CSS-supporting user agent: the user agent must, for the
956: purpose of CSS property inheritance only, treat the root element of
957: the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
958: element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
959: the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
960: root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
961: inherit the computed values of those properties on the
962: <code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
963: values.)</p></li>
964:
965: <li><p>In visual media, in a CSS-supporting user agent: the user agent
966: should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
967: width that the element would have if it was a non-replaced
968: block-level element with 'width: auto'.</p></li>
969:
970: <li><p>In visual media, in a CSS-supporting user agent: the user
971: agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
972: the height of the bounding box around the content rendered in the
973: <code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
974: bullet point), as it would be if the scrolling position was such
975: that the top of the viewport for the content rendered in the
976: <code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
977: canvas.</p></li>
978:
979: <li>
980:
981: <p>In visual media, in a CSS-supporting user agent: the user agent
982: must force the height of the initial containing block of the
983: <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
984: context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
985:
986: <p class="note">This is intended to get around the otherwise
987: circular dependency of percentage dimensions that depend on the
988: height of the containing block, thus affecting the height of the
989: document's bounding box, thus affecting the height of the
990: viewport, thus affecting the size of the initial containing
991: block.</p>
992:
993: </li>
994:
995: <li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
996: browsing context</a> without announcing that it is a separate
997: document.</p></li>
998:
999: <li>
1000:
1001: <p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
1002: document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
1003: context</a> was part of the document that the
1.35 mike 1004: <code><a href="#the-iframe-element">iframe</a></code> is in, if any.</p>
1.1 mike 1005:
1006: <p class="example">For example if the user agent supports listing
1007: all the links in a document, links in "seamlessly" nested
1008: documents would be included in that list without being
1009: significantly distinguished from links in the document itself.</p>
1010:
1011: </li>
1012:
1013: </ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
1014: conditions listed above are not met, then the user agent should
1015: render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
1016: clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
1017: and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
1018: false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
1019:
1020: <p class="warning">It is important that user agents recheck the
1021: above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
1022: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
1023: changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
1024: 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>
1025:
1026: </div><p class="note">The attribute can be set or removed dynamically,
1027: with the rendering updating in tandem.</p><div class="example">
1028:
1029: <p>In this example, the site's navigation is embedded using a
1030: client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
1031: <code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
1032: opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
1033: legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
1034: element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
1035: attribute with the value <code title="">_parent</code>. Similarly,
1036: in new user agents the styles of the parent page will be
1037: automatically applied to the contents of the frame, but to support
1038: legacy user agents authors might wish to include the styles
1039: explicitly.</p>
1040:
1041: <pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
1042:
1043: </div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1044: attributes</a> for cases where the embedded content has specific
1045: 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
1046: content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
1047: context</a>, regardless of whether the specified initial contents
1048: are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
1049: nothing. (In legacy user agents that do not support
1050: <code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
1.82 mike 1051: 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 1052: documents</a>, the allowed content model of <code><a href="#the-iframe-element">iframe</a></code>
1053: elements is text, except that invoking the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment
1054: parsing algorithm</a> with the <code><a href="#the-iframe-element">iframe</a></code> element as the
1.48 mike 1055: <var title="concept-frag-parse-context"><a href="the-end.html#concept-frag-parse-context">context</a></var> element and
1056: the text contents as the <var title="">input</var> must result in a
1057: list of nodes that are all <a href="content-models.html#phrasing-content">phrasing content</a>, with no
1058: <a href="parsing.html#parse-error" title="parse error">parse errors</a> having occurred, with
1059: no <code><a href="scripting-1.html#the-script-element">script</a></code> elements being anywhere in the list or as
1.18 mike 1060: descendants of elements in the list, and with all the elements in
1061: the list (including their descendants) being themselves
1.82 mike 1062: 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.1 mike 1063: documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
1064: <code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
1065:
1066: <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
1067: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1068: name.</p>
1069:
1070: <p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
1071: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1072: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
1073: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1074:
1075: <p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
1076: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1077: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
1078: context</a>.</p>
1079:
1080: </div><div class="example">
1081:
1082: <p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
1083: include advertising from an advertising broker:</p>
1084:
1085: <pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
1086: width="468" height="60"></iframe></pre>
1087:
1.46 mike 1088: </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 1089: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1090: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1091: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1092: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.16 mike 1093: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1094: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1095: <dt>Content model:</dt>
1096: <dd>Empty.</dd>
1097: <dt>Content attributes:</dt>
1098: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1099: <dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
1100: <dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
1101: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1102: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1103: <dd>Any other attribute that has no namespace (see prose).</dd>
1104: <dt>DOM interface:</dt>
1105: <dd>
1106: <pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1107: attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
1108: attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
1109: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1110: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1111: };</pre>
1112: <div class="impl">
1113: <p>Depending on the type of content instantiated by the
1114: <code><a href="#the-embed-element">embed</a></code> element, the node may also support other
1115: interfaces.</p>
1116: </div>
1117: </dd>
1118: </dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
1119: integration point for an external (typically non-HTML) application
1120: or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
1121: gives the address of the resource being embedded. The attribute, if
1122: present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
1123: surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
1124: attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
1125: plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
1126: 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
1127: <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
1128: same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
1129: 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">
1130:
1131: <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
1132: are removed such that neither attribute is present on the element
1.47 mike 1133: anymore, and when the element has a <a href="#media-element">media element</a>
1.1 mike 1134: ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
1135: element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
1136: content</a>, any plugins instantiated for the element must be
1137: removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
1138:
1139: <p id="sandboxPluginEmbed">If either:
1140:
1141: </p><ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1142: set on the <a href="browsers.html#browsing-context">browsing context</a> for which the
1143: <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> is the
1144: <a href="browsers.html#active-document">active document</a> when that <code><a href="infrastructure.html#document">Document</a></code> was
1145: created, or</li>
1146:
1147: <li>the <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1148: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1149: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1150: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1151:
1152: </ul><p>...then the user agent must render the <code><a href="#the-embed-element">embed</a></code> element
1153: in a manner that conveys that the <a href="infrastructure.html#plugin">plugin</a> was
1154: disabled. The user agent may offer the user the option to override
1155: the sandbox and instantiate the <a href="infrastructure.html#plugin">plugin</a> anyway; if the
1156: user invokes such an option, the user agent must act as if the
1157: conditions above did not apply for the purposes of this element.</p>
1158:
1159: <p class="warning">Plugins are disabled in sandboxed browsing
1160: contexts because they might not honor the restrictions imposed by
1161: the sandbox (e.g. they might allow scripting even when scripting in
1162: the sandbox is disabled). User agents should convey the danger of
1163: overriding the sandbox to the user if an option to do so is
1164: provided.</p>
1165:
1166: <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
1167: following conditions are all met simultaneously:</p>
1168:
1169: <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>
1170: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
1171: <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>
1172: <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>
1173: <li>The element is not in a <code><a href="infrastructure.html#document">Document</a></code> whose <a href="browsers.html#browsing-context">browsing context</a> had the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> set when the <code><a href="infrastructure.html#document">Document</a></code> was created (unless this has been overridden as described above).</li>
1174: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> was not parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> (unless this has been overridden as described above).</li>
1.47 mike 1175: <li>The element is not a descendant of a <a href="#media-element">media element</a>.</li>
1.1 mike 1176: <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>
1177: </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
1178: a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1179: <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
1180: removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1181: <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
1182: removed, the appropriate set of steps from the following is then
1183: applied:</p>
1184:
1185: <dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1186: attribute set</dt>
1187:
1188: <dd>
1189:
1190: <p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
1191: the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1192: attribute, relative to the element. If that is successful, the
1193: user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
1194: URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
1.46 mike 1195: origin</a> if it has one. The <a href="webappapis.html#concept-task" title="concept-task">task</a> that is
1.1 mike 1196: <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking
1197: task source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
1198: 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
1199: <a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
1.46 mike 1200: previously instantiated plugin for the element.</p>
1.1 mike 1201: <p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
1202: the element's document.</p>
1.46 mike 1203:
1204:
1.1 mike 1205: </dd>
1206:
1207: <dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1208: attribute set</dt>
1209:
1210: <dd><p>The user agent should find and instantiate an appropriate
1211: <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>
1212:
1213: </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
1214: <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
1215: <a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
1216: be unloaded.</p>
1217:
1218: <p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
1219: CSS 'display' property. The selected plugin is instantiated even if
1220: the element is hidden with a 'display:none' CSS style.</p>
1221:
1222: <p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
1223: being embedded is defined as follows:</p>
1224:
1225: <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
1226: value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
1227: of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
1228: <a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
1229:
1230: <li>
1231:
1.46 mike 1232:
1.1 mike 1233: <p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
1234: component of the <a href="urls.html#url">URL</a> of the specified resource (after
1235: any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1236: supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
1237: type</a> is the type that that plugin can handle.</p>
1238:
1239: <p class="example">For example, a plugin might say that it can
1240: handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
1241: components that end with the four character string "<code title="">.swf</code>".</p>
1242:
1.46 mike 1243:
1244:
1.1 mike 1245:
1246: </li>
1247:
1248: <li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
1249: that is the <a href="#concept-embed-type" title="concept-embed-type">content's
1250: type</a>.</p></li>
1251:
1252: <li><p>Otherwise, the content has no type and there can be no
1253: appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
1254:
1.46 mike 1255:
1.1 mike 1256:
1257: </ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
1258: content</a>. If the user agent can't find a suitable plugin, then
1259: the user agent must use a default plugin. (This default could be as
1260: simple as saying "Unsupported Format".)</p>
1261:
1262: <p>Whether the resource is fetched successfully or not (e.g. whether
1263: 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
1264: ignored when determining the resource's type and when handing the
1265: resource to the plugin.</p>
1266:
1267: <p class="note">This allows servers to return data for plugins even
1268: with error responses (e.g. HTTP 500 Internal Server Error codes can
1269: still contain plugin data).</p>
1270:
1.46 mike 1271: </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 1272: so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
1273: characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
1274: LATIN CAPITAL LETTER Z). These attributes are then passed as
1.82 mike 1275: 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 1276: lowercased automatically, so the restriction on uppercase letters
1277: doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
1278: that have side-effects beyond just sending parameters to the
1279: <a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
1280:
1281: <p>The user agent should pass the names and values of all the
1282: attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
1283: to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
1284:
1285: <p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
1286: <code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
1287: <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
1288: expose that interface while the element is instantiated.</p>
1289:
1290: </div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1291: attributes</a>.</p><div class="impl">
1292:
1293: <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
1294: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1295: name.</p>
1296:
1297: </div><div class="example">
1298:
1299: <p>Here's a way to embed a resource that requires a proprietary
1.69 mike 1300: plugin, like Flash:</p>
1.1 mike 1301:
1302: <pre><embed src="catgame.swf"></pre>
1303:
1.69 mike 1304: <p>If the user does not have the plugin (for example if the
1305: plugin vendor doesn't support the user's platform), then the user
1.1 mike 1306: will be unable to use the resource.</p>
1307:
1308: <p>To pass the plugin a parameter "quality" with the value "high",
1309: an attribute can be specified:</p>
1310:
1311: <pre><embed src="catgame.swf" quality="high"></pre>
1312:
1313: <p>This would be equivalent to the following, when using an
1314: <code><a href="#the-object-element">object</a></code> element instead:</p>
1315:
1316: <pre><object data="catgame.swf">
1317: <param name="quality" value="high">
1318: </object></pre>
1319:
1.15 mike 1320: </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 1321: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1322: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1323: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1.46 mike 1324: <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 1325: <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.16 mike 1326: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1327: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1328: <dt>Content model:</dt>
1329: <dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
1330: <dt>Content attributes:</dt>
1331: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1332: <dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
1333: <dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
1.69 mike 1334: <dd><code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code></dd>
1.1 mike 1335: <dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
1336: <dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
1337: <dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
1338: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1339: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1340: <dt>DOM interface:</dt>
1341: <dd>
1342: <pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1343: attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
1344: attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
1.69 mike 1345: attribute boolean <a href="#dom-object-typemustmatch" title="dom-object-typeMustMatch">typeMustMatch</a>;
1.1 mike 1346: attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
1347: attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
1.68 mike 1348: 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 1349: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1350: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1.68 mike 1351: readonly attribute Document? <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
1352: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a>? <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
1.1 mike 1353:
1354: readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
1355: 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>;
1356: readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
1357: boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
1358: void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(in DOMString error);
1359: };</pre>
1360: <div class="impl">
1361: <p>Depending on the type of content instantiated by the
1362: <code><a href="#the-object-element">object</a></code> element, the node also supports other
1363: interfaces.</p>
1364: </div>
1365: </dd>
1366: </dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
1367: resource, which, depending on the type of the resource, will either
1368: be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1369: or as an external resource to be processed by a
1370: <a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
1371: attribute, if present, specifies the address of the resource. If
1372: present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.69 mike 1373: 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
1374: use the <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1375: attribute defined below. Without that attribute, it is possible in
1376: certain cases for an attacker on the remote host to use the plugin
1377: mechanism to run arbitrary scripts, even if the author has used
1378: 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 1379: attribute, if present, specifies the type of the resource. If
1.69 mike 1380: 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 1381: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> whose presence
1.69 mike 1382: 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
1383: the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1384: attribute and the <a href="fetching-resources.html#content-type">Content-Type</a> of the aforementioned
1385: resource match.</p><p>The <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1386: 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 1387: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
1388: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
1389: browsing context</a>, if applicable.</p><div class="impl">
1390:
1391: <p>When the element is created, when it is popped off the
1392: <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
1393: or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
1394: <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
1395: document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
1396: document">removed from a document</a>; and whenever the element's
1397: <code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
1398: active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
1399: changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
1400: whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
1401: 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,
1402: whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
1403: 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
1404: its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
1405: changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
1406: to run the following steps to (re)determine what the
1407: <code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
1408: 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 1409: manipulation task source</a>.</p>
1.1 mike 1410: <ol><li>
1411:
1412: <p>If the user has indicated a preference that this
1413: <code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
1414: shown instead of the element's usual behavior, then jump to the
1415: last step in the overall set of steps (fallback).</p>
1416:
1417: <p class="note">For example, a user could ask for the element's
1418: <a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
1419: uses a format that the user finds more accessible.</p>
1420:
1421: </li>
1422:
1423: <li>
1424:
1.47 mike 1425: <p>If the element has an ancestor <a href="#media-element">media element</a>, or
1.1 mike 1426: has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
1427: showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
1428: not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
1429: with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
1430: <code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
1431: element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
1432: <a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
1433: the last step in the overall set of steps (fallback).</p>
1434:
1435: </li>
1436:
1437: <li>
1438:
1.46 mike 1439:
1.1 mike 1440: <p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
1441: attribute is present, and has a value that isn't the empty string,
1442: then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
1443: according to the value of the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute, and <a href="#sandboxPluginObject">plugins aren't being sandboxed</a>,
1444: then that <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be
1445: used</a>, and the value of the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute, if any, should be
1446: passed to the <a href="infrastructure.html#plugin">plugin</a>. If no suitable
1447: <a href="infrastructure.html#plugin">plugin</a> can be found, or if the <a href="infrastructure.html#plugin">plugin</a>
1448: reports an error, jump to the last step in the overall set of
1449: steps (fallback).</p>
1450:
1.46 mike 1451:
1.1 mike 1452: </li>
1453:
1.46 mike 1454:
1.1 mike 1455: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1456: is present and its value is not the empty string, then:</p>
1457:
1458: <ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1459: attribute is present and its value is not a type that the user
1460: agent supports, and is not a type that the user agent can find a
1461: <a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
1462: step in the overall set of steps (fallback) without fetching the
1463: content to examine its real type.</p></li>
1464:
1465: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
1466: <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
1467: element.</p></li>
1468:
1469: <li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1470: <code title="event-error">error</code> at the element, then jump
1471: to the last step in the overall set of steps (fallback).</p></li>
1472:
1473: <li>
1474:
1475: <p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
1476: from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
1.46 mike 1477: it has one.</p>
1.1 mike 1478:
1.46 mike 1479: <p>Fetching the resource
1.1 mike 1480: must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
1481: 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
1482: source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
1483:
1.41 mike 1484: <p>For the purposes of the <a href="offline.html#application-cache">application cache</a>
1485: networking model, this <a href="fetching-resources.html#fetch">fetch</a> operation is not for a
1486: <a href="browsers.html#child-browsing-context">child browsing context</a> (though it might end up
1487: being used for one after all, as defined below).</p>
1488:
1.1 mike 1489: </li>
1490:
1491: <li><p>If the resource is not yet available (e.g. because the
1492: resource was not available in the cache, so that loading the
1493: resource required making a request over the network), then jump
1494: to the last step in the overall set of steps (fallback). The
1495: <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue
1496: a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task source</a>
1497: once the resource is available must restart this algorithm from
1498: this step. Resources can load incrementally; user agents may opt
1499: to consider a resource "available" whenever enough data has been
1500: obtained to begin processing the resource.</p></li>
1501:
1502: <li><p>If the load failed (e.g. there was an HTTP 404 error,
1503: there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1504: <code title="event-error">error</code> at the element, then jump
1505: to the last step in the overall set of steps (fallback).</p></li>
1506:
1507: <li id="object-type-detection">
1508:
1509: <p>Determine the <var title="">resource type</var>, as follows:</p>
1510:
1511:
1512: <ol><li>
1513:
1514: <p>Let the <var title="">resource type</var> be unknown.</p>
1515:
1516: </li>
1517:
1518: <li>
1519:
1.69 mike 1520: <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>
1521: attribute, and the resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type metadata</a>,
1522: and the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1523: resource's Content-Type metadata</a> is an <a href="infrastructure.html#ascii-case-insensitive">ASCII
1524: case-insensitive</a> match for the value of the element's
1525: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, then let
1526: <var title="">resource type</var> be that type and jump to the
1527: step below labeled <i>handler</i>.</p>
1528:
1529:
1530: </li>
1531:
1532: <li>
1533:
1534: <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>
1535: attribute, jump to the step below labeled <i>handler</i>.</p>
1536:
1537: </li>
1538:
1539: <li>
1540:
1.46 mike 1541:
1.1 mike 1542:
1543: <p>If the user agent is configured to strictly obey
1544: Content-Type headers for this resource, and the resource has
1545: <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1546: metadata</a>, then let the <var title="">resource
1547: type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1548: metadata</a>, and jump to the step below labeled
1549: <i>handler</i>.</p>
1550:
1.69 mike 1551: <p class="warning">This can introduce a vulnerability, wherein
1552: a site is trying to embed a resource that uses a particular
1553: plugin, but the remote site overrides that and instead
1554: furnishes the user agent with a resource that triggers a
1555: different plugin with different security characteristics. </p>
1556:
1.1 mike 1557: </li>
1558:
1559: <li>
1560:
1561: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1562: attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
1563: attribute's value is not a type that the user agent supports,
1564: but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
1565: then let the <var title="">resource type</var> be the type
1566: specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1567: attribute, and jump to the step below labeled
1568: <i>handler</i>.</p>
1569:
1570: </li>
1571:
1572: <li>
1573:
1574: <p>Run the approprate set of steps from the following
1575: list:</p>
1576:
1577: <dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
1578: Content-Type metadata</a></dt>
1579:
1580: <dd>
1581:
1582: <ol><li>
1583:
1584: <p>Let <var title="">binary</var> be false.</p>
1585:
1586: </li>
1587:
1588: <li>
1589:
1590: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1591: resource's Content-Type metadata</a> is
1592: "<code>text/plain</code>", and the result of applying the
1593: <a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
1.49 mike 1594: for distinguishing if a resource is text or binary</a>
1.1 mike 1595: to the resource is that the resource is not
1596: <code>text/plain</code>, then set <var title="">binary</var> to true.</p>
1597:
1598: </li>
1599:
1600: <li>
1601:
1602: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1603: resource's Content-Type metadata</a> is
1604: "<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
1605:
1606: </li>
1607:
1608: <li>
1609:
1610: <p>If <var title="">binary</var> is false, then let the
1611: <var title="">resource type</var> be the type specified in
1612: <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1613: metadata</a>, and jump to the step below labeled
1614: <i>handler</i>.</p>
1615:
1616: </li>
1617:
1618: <li>
1619:
1620: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1621: the <code><a href="#the-object-element">object</a></code> element, and its value is not
1622: <code>application/octet-stream</code>, then run the
1623: following steps:</p>
1624:
1625: <ol><li>
1626:
1627: <p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
1628: 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>,
1629: 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>
1630:
1631: </li>
1632:
1633: <li>
1634:
1635: <p>Jump to the step below labeled <i>handler</i>.</p>
1636:
1637: </li>
1638:
1639: </ol></li>
1640:
1641: </ol></dd>
1642:
1643: <dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1644: metadata</a></dt>
1645:
1646: <dd>
1647:
1648: <ol><li>
1649:
1650: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1651: 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
1652: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1653:
1654: <p>Otherwise, let <var title="">tentative type</var> be the
1655: <a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
1656: resource</a>.</p>
1657:
1658: </li>
1659:
1660: <li>
1661:
1662: <p>If <var title="">tentative type</var> is <em>not</em>
1663: <code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
1664: type</var> and jump to the step below labeled
1665: <i>handler</i>.</p>
1666:
1667: </li>
1668:
1669: </ol></dd>
1670:
1671: </dl></li>
1672:
1673: <li>
1674:
1.46 mike 1675:
1.1 mike 1676: <p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
1677: of the <a href="urls.html#url">URL</a> of the specified resource (after any
1678: redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1679: supports, then let <var title="">resource type</var> be the
1680: type that that plugin can handle.</p>
1681:
1682: <p class="example">For example, a plugin might say that it can
1683: handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
1684: the four character string "<code title="">.swf</code>".</p>
1685:
1.46 mike 1686:
1687:
1.1 mike 1688:
1689: </li>
1690:
1.69 mike 1691: </ol><p class="note">It is possible for this step to finish, or for
1692: one of the substeps above to jump straight to the next step,
1693: with <var title="">resource type</var> still being unknown. In
1694: both cases, the next step will trigger fallback.</p>
1.1 mike 1695:
1696: </li>
1697:
1698: <li><p><i>Handler</i>: Handle the content as given by the first
1699: of the following cases that matches:</p>
1700:
1701: <dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
1702: the user agent supports, but it <em>is</em> a type that a
1703: <a href="infrastructure.html#plugin">plugin</a> supports</dt>
1704:
1705: <dd>
1706:
1707: <p>If <a href="#sandboxPluginObject">plugins are being
1708: sandboxed</a>, jump to the last step in the overall set of
1709: steps (fallback).</p>
1710:
1711: <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
1712: resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
1713: <a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
1714: step in the overall set of steps (fallback).</p>
1715:
1716: </dd>
1717:
1718:
1719: <dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
1720: type</a>, or
1.46 mike 1721:
1.1 mike 1722: if the <var title="">resource type</var> does not start with
1723: "<code>image/</code>"</dt>
1724:
1725: <dd>
1726:
1727: <p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
1728: newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
1729: not already have one.</p>
1730:
1731: <p>If the <a href="urls.html#url">URL</a> of the given resource is not
1732: <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 1733: context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that
1.34 mike 1734: resource, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
1.1 mike 1735: <code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
1.34 mike 1736: context</a> as the <a href="history.html#source-browsing-context">source browsing context</a>.
1737: (The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of
1738: the <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
1.1 mike 1739: browsing context gets further navigated to other
1740: locations.)</p>
1741:
1742: <p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
1743: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, the user agent must
1744: <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>
1745: named <code title="event-load">load</code> at the
1.66 mike 1746: <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
1747: <code><a href="fetching-resources.html#about:blank">about:blank</a></code> document itself.</span></p>
1.1 mike 1748:
1749: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1750: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1751:
1752: <p>If the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1753: is present, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1754: to the value of this attribute; otherwise, the <a href="browsers.html#browsing-context-name">browsing
1755: context name</a> must be set to the empty string.</p>
1756:
1.41 mike 1757: <p class="note">In certain situations, e.g. if the resource
1758: was <a href="fetching-resources.html#fetch" title="fetch">fetched</a> from an
1759: <a href="offline.html#application-cache">application cache</a> but it is an HTML file with a
1760: <code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> attribute
1761: that points to a different <a href="offline.html#concept-appcache-manifest" title="concept-appcache-manifest">application cache
1762: manifest</a>, the <a href="history.html#navigate" title="navigate">navigation</a>
1763: of the <a href="browsers.html#browsing-context">browsing context</a> will be restarted so as
1764: to load the resource afresh from the network or a different
1765: <a href="offline.html#application-cache">application cache</a>. Even if the resource is then
1766: found to have a different type, it is still used as part of a
1767: <a href="browsers.html#nested-browsing-context">nested browsing context</a>: only the
1768: <a href="history.html#navigate">navigate</a> algorithm is restarted, not this
1769: <code><a href="#the-object-element">object</a></code> algorithm.</p>
1.1 mike 1770:
1.46 mike 1771:
1.1 mike 1772:
1773: </dd>
1774:
1775:
1776: <dt>If the <var title="">resource type</var> starts with
1777: "<code>image/</code>", and support for images has not been
1778: disabled</dt>
1779:
1780: <dd>
1781:
1782: <p>Apply the <a href="fetching-resources.html#content-type-sniffing:-image" title="content-type sniffing: image">image
1783: sniffing</a> rules to determine the type of the image.</p>
1784:
1785: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1786: specified image. The image is not a <a href="browsers.html#nested-browsing-context">nested browsing
1787: context</a>.</p>
1788:
1789: <p>If the image cannot be rendered, e.g. because it is
1790: malformed or in an unsupported format, jump to the last step
1791: in the overall set of steps (fallback).</p>
1792:
1793: </dd>
1794:
1795:
1796: <dt>Otherwise</dt>
1797:
1798: <dd>
1799:
1800: <p>The given <var title="">resource type</var> is not
1801: supported. Jump to the last step in the overall set of steps
1802: (fallback).</p>
1803:
1804: <p class="note">If the previous step ended with the <var title="">resource type</var> being unknown, this is the case
1805: that is triggered.</p>
1806:
1807: </dd>
1808:
1809: </dl></li>
1810:
1811: <li><p>The element's contents are not part of what the
1812: <code><a href="#the-object-element">object</a></code> element represents.</p>
1813:
1814: </li><li>
1815:
1816: <p>Once the resource is completely loaded, <a href="webappapis.html#queue-a-task">queue a
1817: 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>
1818:
1.46 mike 1819: <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 1820: source</a>.</p>
1821:
1822: </li>
1823:
1824: </ol></li>
1825:
1826: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1827: is absent but the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1828: attribute is present, <a href="#sandboxPluginObject">plugins aren't
1829: being sandboxed</a>, and the user agent can find a
1830: <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, then that
1831: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
1832: no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
1833: <a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the next step
1834: (fallback).</p></li>
1835:
1836: <li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
1837: <a href="rendering.html#represents">represents</a> the element's children, ignoring any
1838: leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
1839: <a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
1840: <a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
1841:
1842: </ol><p id="object-plugin">When the algorithm above instantiates a
1843: <a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
1844: <a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
1845: on the element, in the order they were added to the element, with
1846: the attributes added by the parser being ordered in source order,
1847: followed by a parameter named "PARAM" whose value is null,
1848: followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
1849: <code><a href="#the-param-element">param</a></code> elements that are children of the
1850: <code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
1851: <a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
1852: <code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
1853: should expose that interface. The <code><a href="#the-object-element">object</a></code> element
1854: <a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
1855: <a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
1856: context</a>.</p>
1857:
1858: <p id="sandboxPluginObject">If either:</p>
1859:
1860: <ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1861: set on the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s
1862: <a href="browsers.html#browsing-context">browsing context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was
1863: created, or</li>
1864:
1865: <li>the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1866: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1867: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1868: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1869:
1870: </ul><p>...then the steps above must always act as if they had failed to
1871: find a <a href="infrastructure.html#plugin">plugin</a>, even if one would otherwise have been
1872: used.</p>
1873:
1874: <p class="note">The above algorithm is independent of CSS properties
1875: (including 'display', 'overflow', and 'visibility'). For example, it
1876: runs even if the element is hidden with a 'display:none' CSS style,
1877: and does not run <em>again</em> if the element's visibility
1878: changes.</p>
1879:
1880: <p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
1881: elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
1882: referenced resources can't be shown (e.g. because it returned a 404
1883: error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
1884: nested inside each other, targeting multiple user agents with
1885: different capabilities, with the user agent picking the first one it
1886: supports.</p>
1887:
1888: <p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1889: is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
1890: <a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
1891: name">name</a> must be changed to the new value. If the attribute
1892: is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
1893: context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1894: to the empty string.</p>
1895:
1896: </div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
1897: if present while the <code><a href="#the-object-element">object</a></code> element represents an
1898: image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
1899: map</a>. <span class="impl">The attribute must be ignored if the
1900: <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
1901: explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
1902: <a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
1903:
1904: <p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
1905: elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
1906: validation</a>.</p>
1907:
1908: </div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1909: attributes</a>.</p><div class="impl">
1910:
1911: <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>, <dfn id="dom-object-name" title="dom-object-name"><code>name</code></dfn>, and <dfn id="dom-object-usemap" title="dom-object-useMap"><code>useMap</code></dfn> each must
1912: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1913: name.</p>
1914:
1.69 mike 1915: <p>The <dfn id="dom-object-typemustmatch" title="dom-object-typeMustMatch"><code>typeMustMatch</code></dfn> IDL
1916: 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
1917: attribute.</p>
1918:
1.1 mike 1919: <p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
1920: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1921: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
1922: <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
1923: must return null.</p>
1924:
1925: <p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
1926: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1927: <code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1928: if it has one; otherwise, it must return null.</p>
1929:
1930: <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>
1931: 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>
1932: methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
1933: <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
1934: element's forms API.</p>
1935:
1936: </div><div class="example">
1937:
1938: <p>In the following example, a Java applet is embedded in a page
1939: using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
1940: better to avoid using applets like these and instead use native
1941: JavaScript and HTML to provide the functionality, since that way
1942: the application will work on all Web browsers without requiring a
1943: third-party plugin. Many devices, especially embedded devices, do
1944: not support third-party technologies like Java.)</p>
1945:
1946: <pre><figure>
1947: <object type="application/x-java-applet">
1948: <param name="code" value="MyJavaClass">
1949: <p>You do not have Java available, or it is disabled.</p>
1950: </object>
1951: <figcaption>My Java Clock</figcaption>
1952: </figure></pre>
1953:
1954: </div><div class="example">
1955:
1956: <p>In this example, an HTML page is embedded in another using the
1957: <code><a href="#the-object-element">object</a></code> element.</p>
1958:
1959: <pre><figure>
1960: <object data="clock.html"></object>
1961: <figcaption>My HTML Clock</figcaption>
1962: </figure></pre>
1963:
1964: </div><div class="example">
1965:
1966: <p>The following example shows how a plugin can be used in HTML (in
1967: this case the Flash plugin, to show a video file). Fallback is
1968: provided for users who do not have Flash enabled, in this case
1.47 mike 1969: using the <code><a href="#the-video-element">video</a></code> element to show the video for those
1970: using user agents that support <code><a href="#the-video-element">video</a></code>, and finally
1.1 mike 1971: providing a link to the video for those who have neither Flash nor
1.47 mike 1972: a <code><a href="#the-video-element">video</a></code>-capable browser.</p>
1.1 mike 1973:
1974: <pre><p>Look at my video:
1975: <object type="application/x-shockwave-flash">
1976: <param name=movie value="http://video.example.com/library/watch.swf">
1977: <param name=allowfullscreen value=true>
1978: <param name=flashvars value="http://video.example.com/vids/315981">
1979: <video controls src="http://video.example.com/vids/315981">
1980: <a href="http://video.example.com/vids/315981">View video</a>.
1981: </video>
1982: </object>
1983: </p></pre>
1984:
1.15 mike 1985: </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 1986: <dd>None.</dd>
1.16 mike 1987: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1988: <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>
1989: <dt>Content model:</dt>
1990: <dd>Empty.</dd>
1991: <dt>Content attributes:</dt>
1992: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1993: <dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
1994: <dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
1995: <dt>DOM interface:</dt>
1996: <dd>
1997: <pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1998: attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
1999: attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
2000: };</pre>
2001: </dd>
2002: </dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
2003: 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>
2004: attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
2005: attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
2006:
2007: <p>If both attributes are present, and if the parent element of the
2008: <code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
2009: element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
1.94 mike 2010: name-value pair.</p>
1.1 mike 2011:
1.23 mike 2012: <p>If either the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> defined by a
2013: <code><a href="#the-param-element">param</a></code> element that is the child of an
2014: <code><a href="#the-object-element">object</a></code> element that <a href="rendering.html#represents">represents</a> an
2015: instantiated <a href="infrastructure.html#plugin">plugin</a> changes, and if that
2016: <a href="infrastructure.html#plugin">plugin</a> is communicating with the user agent using an
2017: API that features the ability to update the <a href="infrastructure.html#plugin">plugin</a> when
2018: the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> so changes, then
2019: the user agent must appropriately exercise that ability to notify
2020: the <a href="infrastructure.html#plugin">plugin</a> of the change.</p>
2021:
1.1 mike 2022: <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
2023: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2024: name.</p>
2025:
2026: </div><div class="example">
2027:
2028: <p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
2029: can be used to pass a parameter to a plugin, in this case the O3D
2030: plugin.</p>
2031:
2032: <pre><!DOCTYPE HTML>
2033: <html lang="en">
1.6 mike 2034: <head>
2035: <title>O3D Utah Teapot</title>
2036: </head>
2037: <body>
2038: <p>
2039: <object type="application/vnd.o3d.auto">
2040: <strong><param name="o3d_features" value="FloatingPointTextures"></strong>
2041: <img src="o3d-teapot.png"
2042: title="3D Utah Teapot illustration rendered using O3D."
2043: alt="When O3D renders the Utah Teapot, it appears as a squat
2044: teapot with a shiny metallic finish on which the
2045: surroundings are reflected, with a faint shadow caused by
2046: the lighting.">
2047: <p>To see the teapot actually rendered by O3D on your
2048: computer, please download and install the <a
2049: href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
2050: </object>
2051: <script src="o3d-teapot.js"></script>
2052: </p>
2053: </body>
1.1 mike 2054: </html></pre>
2055:
1.47 mike 2056: </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>
2057: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2058: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2059: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2060: <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>
2061: <dt>Contexts in which this element can be used:</dt>
2062: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2063: <dt>Content model:</dt>
2064: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2065: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2066: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2067: <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
2068: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2069: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2070: <dt>Content attributes:</dt>
2071: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2072: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2073: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2074: <dd><code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code></dd>
2075: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2076: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2077: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2078: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2079: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2080: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2081: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
2082: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
2083: <dt>DOM interface:</dt>
2084: <dd>
2085: <pre class="idl">interface <dfn id="htmlvideoelement">HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {
2086: attribute unsigned long <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
2087: attribute unsigned long <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
2088: readonly attribute unsigned long <a href="#dom-video-videowidth" title="dom-video-videoWidth">videoWidth</a>;
2089: readonly attribute unsigned long <a href="#dom-video-videoheight" title="dom-video-videoHeight">videoHeight</a>;
2090: attribute DOMString <a href="#dom-video-poster" title="dom-video-poster">poster</a>;
2091: };</pre>
2092: </dd>
2093: </dl><p>A <code><a href="#the-video-element">video</a></code> element is used for playing videos or
2094: movies, and audio files with captions.</p><p>Content may be provided inside the <code><a href="#the-video-element">video</a></code>
2095: element<span class="impl">. User agents should not show this content
2096: to the user</span>; it is intended for older Web browsers which do
2097: not support <code><a href="#the-video-element">video</a></code>, so that legacy video plugins can be
2098: tried, or to show text to the users of these older browsers informing
2099: them of how to access the video contents.</p><p class="note">In particular, this content is not intended to
2100: address accessibility concerns. To make video content accessible to
2101: the blind, deaf, and those with other physical or cognitive
1.90 mike 2102: disabilities, a variety of features are available. Captions can be
2103: provided, either embedded in the video stream or as external files
2104: using the <code><a href="#the-track-element">track</a></code> element. Sign-language tracks can be
2105: provided, again either embedded in the video stream or by
2106: 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
2107: <code><a href="#mediacontroller">MediaController</a></code> object. Audio descriptions can be
2108: provided, either as a separate track embedded in the video stream,
2109: 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
2110: as the <code><a href="#the-video-element">video</a></code> element(s), or in text form using a
2111: <span>WebVTT file</span> referenced using the <code><a href="#the-track-element">track</a></code>
2112: element and synthesized into speech by the user agent. WebVTT can
2113: also be used to provide chapter titles. For users who would rather
2114: not use a media element at all, transcripts or other textual
2115: alternatives can be provided by simply linking to them in the prose
2116: 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 2117: whose <a href="#media-data">media data</a> is ostensibly video data, possibly
2118: 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>,
2119: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2120: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2121: <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
2122: elements</a>.</p><p>The <dfn id="attr-video-poster" title="attr-video-poster"><code>poster</code></dfn>
2123: attribute gives the address of an image file that the user agent can
2124: show while no video data is available. The attribute, if present,
2125: must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2126: spaces</a>.</p><div class="impl">
2127:
2128: <p>If the specified resource is to be used, then, when the element
2129: is created or when the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
2130: attribute is set, changed, or removed, the user agent must run the
2131: following steps to determine the element's <dfn id="poster-frame">poster
2132: frame</dfn>:</p>
2133: <ol><li><p>If there is an existing instance of this algorithm running
2134: for this <code><a href="#the-video-element">video</a></code> element, abort that instance of this
2135: algorithm without changing the <a href="#poster-frame">poster frame</a>.</p></li>
2136:
2137: <li><p>If the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
1.51 mike 2138: attribute's value is the empty string or if the attribute is
2139: absent, then there is no <a href="#poster-frame">poster frame</a>; abort these
2140: steps.</p></li>
1.47 mike 2141:
2142: <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
2143: to the element. If this fails, then there is no <a href="#poster-frame">poster
2144: frame</a>; abort these steps.</p></li>
2145:
2146: <li><p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
2147: from the element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>.
2148: This must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's
2149: document.</p></li>
2150:
2151:
2152:
2153: <li><p>If an image is thus obtained, the <a href="#poster-frame">poster frame</a>
2154: is that image. Otherwise, there is no <a href="#poster-frame">poster
2155: frame</a>.</p></li>
2156:
2157: </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
2158: frame</a></i>, is intended to be a representative frame of the video
2159: (typically one of the first non-blank frames) that gives the user an
2160: idea of what the video is like.</p><div class="impl">
2161:
2162: <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
2163: <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
2164: 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
2165: subsequent value but the <a href="#media-resource">media resource</a> does not have a
2166: video channel), the <code><a href="#the-video-element">video</a></code> element
1.94 mike 2167: <a href="rendering.html#represents">represents</a> the <a href="#poster-frame">poster frame</a>.</p>
1.47 mike 2168:
2169: <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
2170: playback position">current playback position</a> is the first
1.94 mike 2171: frame of video, the element <a href="rendering.html#represents">represents</a> the <a href="#poster-frame">poster
2172: frame</a>, unless a frame of video has already been shown, in
2173: which case the element <a href="rendering.html#represents">represents</a> the frame of video
2174: corresponding to the <a href="#current-playback-position" title="current playback position">current
2175: playback position</a>.</p>
1.47 mike 2176:
2177: <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
2178: the <a href="#media-resource">media resource</a> has a video channel, the element
2179: <a href="rendering.html#represents">represents</a> the frame of video corresponding to the
2180: <a href="#current-playback-position" title="current playback position">current playback
2181: position</a>, or, if that is not yet available (e.g. because the
2182: video is seeking or buffering), the last frame of the video to have
2183: been rendered.</p>
2184:
2185: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2186: resource</a> has a video channel is <a href="#potentially-playing">potentially
2187: playing</a>, it <a href="rendering.html#represents">represents</a> the frame of video at the
2188: continuously increasing <a href="#current-playback-position" title="current playback
2189: position">"current" position</a>. When the <a href="#current-playback-position">current playback
2190: position</a> changes such that the last frame rendered is no
2191: longer the frame corresponding to the <a href="#current-playback-position">current playback
2192: position</a> in the video, the new frame must be rendered.
2193:
2194: Similarly, any audio associated with the <a href="#media-resource">media resource</a>
2195: must, if played, be played synchronized with the <a href="#current-playback-position">current
2196: playback position</a>, at the element's <a href="#effective-media-volume">effective media
2197: volume</a>.</p>
2198:
2199: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2200: resource</a> has a video channel is neither <a href="#potentially-playing">potentially
2201: playing</a> nor <a href="#dom-media-paused" title="dom-media-paused">paused</a>
2202: (e.g. when seeking or stalled), the element <a href="rendering.html#represents">represents</a>
2203: the last frame of the video to have been rendered.</p>
2204:
2205: <p class="note">Which frame in a video stream corresponds to a
2206: particular playback position is defined by the video stream's
2207: format.</p>
2208:
2209: <p>The <code><a href="#the-video-element">video</a></code> element also <a href="rendering.html#represents">represents</a> any
2210: <a href="#text-track-cue" title="text track cue">text track cues</a> whose
2211: <a href="#text-track-cue-active-flag">text track cue active flag</a> is set and whose
2212: <a href="#text-track">text track</a> is in the <a href="#text-track-showing" title="text track
2213: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track showing by
2214: default">showing by default</a> modes.</p>
2215:
2216: <p>In addition to the above, the user agent may provide messages to
2217: the user (such as "buffering", "no video loaded", "error", or more
2218: detailed information) by overlaying text or icons on the video or
2219: other areas of the element's playback area, or in another
2220: appropriate manner.</p>
2221:
2222: <p>User agents that cannot render the video may instead make the
2223: element <a href="rendering.html#represents" title="represents">represent</a> a link to an
2224: external video playback utility or to the video data itself.</p>
2225:
2226: <hr></div><dl class="domintro"><dt><var title="">video</var> . <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code></dt>
2227: <dt><var title="">video</var> . <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code></dt>
2228:
2229: <dd>
2230:
2231: <p>These attributes return the intrinsic dimensions of the video,
2232: or zero if the dimensions are not known.</p>
2233:
2234: </dd>
2235:
2236: </dl><div class="impl">
2237:
2238: <p>The <dfn id="concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2239: width</dfn> and <dfn id="concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</dfn> of the
2240: <a href="#media-resource">media resource</a> are the dimensions of the resource in
2241: CSS pixels after taking into account the resource's dimensions,
2242: aspect ratio, clean aperture, resolution, and so forth, as defined
2243: for the format used by the resource. If an anamorphic format does
2244: not define how to apply the aspect ratio to the video data's
2245: dimensions to obtain the "correct" dimensions, then the user agent
2246: must apply the ratio by increasing one dimension and leaving the
2247: other unchanged.</p>
2248:
2249: <p>The <dfn id="dom-video-videowidth" title="dom-video-videoWidth"><code>videoWidth</code></dfn> IDL
2250: attribute must return the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> of the
2251: video in CSS pixels. The <dfn id="dom-video-videoheight" title="dom-video-videoHeight"><code>videoHeight</code></dfn> IDL
2252: attribute must return the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> of
2253: 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
2254: attributes must return 0.</p>
2255:
2256: </div><p>The <code><a href="#the-video-element">video</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
2257: attributes</a>.</p><div class="impl">
2258:
2259: <p>In the absence of style rules to the contrary, video content
2260: should be rendered inside the element's playback area such that the
2261: video content is shown centered in the playback area at the largest
2262: possible size that fits completely within it, with the video
2263: content's aspect ratio being preserved. Thus, if the aspect ratio of
2264: the playback area does not match the aspect ratio of the video, the
2265: video will be shown letterboxed or pillarboxed. Areas of the
2266: element's playback area that do not contain the video represent
2267: nothing.</p>
2268:
2269: <p class="note">In user agents that implement CSS, the above
2270: requirement can be implemented by using the <a href="rendering.html#video-object-fit">style rule suggested in the rendering
2271: section</a>.</p>
2272:
2273: <p>The intrinsic width of a <code><a href="#the-video-element">video</a></code> element's playback
2274: area is the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2275: width</a> of the video resource, if that is available; otherwise
2276: it is the intrinsic width of the <a href="#poster-frame">poster frame</a>, if that
2277: is available; otherwise it is 300 CSS pixels.</p>
2278:
2279: <p>The intrinsic height of a <code><a href="#the-video-element">video</a></code> element's playback
2280: area is the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic
2281: height</a> of the video resource, if that is available; otherwise
2282: it is the intrinsic height of the <a href="#poster-frame">poster frame</a>, if that
2283: is available; otherwise it is 150 CSS pixels.</p>
2284:
2285: <hr><p>User agents should provide controls to enable or disable the
2286: display of closed captions, audio description tracks, and other
2287: additional data associated with the video stream, though such
2288: features should, again, not interfere with the page's normal
2289: rendering.</p>
2290:
2291: <p>User agents may allow users to view the video content in manners
2292: more suitable to the user (e.g. full-screen or in an independent
2293: resizable window). As for the other user interface features,
2294: controls to enable this should not interfere with the page's normal
2295: rendering unless the user agent is <a href="#expose-a-user-interface-to-the-user" title="expose a user
2296: interface to the user">exposing a user interface</a>. In such an
2297: independent context, however, user agents may make full user
2298: interfaces visible, with, e.g., play, pause, seeking, and volume
2299: controls, even if the <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute is absent.</p>
2300:
2301: <p>User agents may allow video playback to affect system features
2302: that could interfere with the user's experience; for example, user
2303: agents could disable screensavers while video playback is in
2304: progress.</p>
2305:
2306: <hr><p>The <dfn id="dom-video-poster" title="dom-video-poster"><code>poster</code></dfn> IDL
2307: 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>
2308:
2309: </div><div class="example">
2310:
2311: <p>This example shows how to detect when a video has failed to play
2312: correctly:</p>
2313:
2314: <pre><script>
2315: function failed(e) {
2316: // video playback failed - show a message saying why
2317: switch (e.target.error.code) {
2318: case e.target.error.MEDIA_ERR_ABORTED:
2319: alert('You aborted the video playback.');
2320: break;
2321: case e.target.error.MEDIA_ERR_NETWORK:
2322: alert('A network error caused the video download to fail part-way.');
2323: break;
2324: case e.target.error.MEDIA_ERR_DECODE:
2325: alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
2326: break;
2327: case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
2328: alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
2329: break;
2330: default:
2331: alert('An unknown error occurred.');
2332: break;
2333: }
2334: }
2335: </script>
2336: <p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
2337: <p><a href="tgif.vid">Download the video file</a>.</p></pre>
2338:
2339: </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>
2340: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2341: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2342: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2343: <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>
2344: <dt>Contexts in which this element can be used:</dt>
2345: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2346: <dt>Content model:</dt>
2347: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2348: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2349: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2350: <dd>If the element does not have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute: one or more <code><a href="#the-source-element">source</a></code> elements, then
2351: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2352: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2353: <dt>Content attributes:</dt>
2354: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2355: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2356: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2357: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2358: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2359: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2360: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2361: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2362: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2363: <dt>DOM interface:</dt>
2364: <dd>
2365: <pre class="idl">[NamedConstructor=<a href="#dom-audio" title="dom-Audio">Audio</a>(),
2366: NamedConstructor=<a href="#dom-audio-s" title="dom-Audio-s">Audio</a>(in DOMString src)]
2367: interface <dfn id="htmlaudioelement">HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {};</pre>
2368: </dd>
2369: </dl><p>An <code><a href="#the-audio-element">audio</a></code> element <a href="rendering.html#represents">represents</a> a sound or
2370: audio stream.</p><p>Content may be provided inside the <code><a href="#the-audio-element">audio</a></code>
2371: element<span class="impl">. User agents should not show this content
2372: to the user</span>; it is intended for older Web browsers which do
2373: not support <code><a href="#the-audio-element">audio</a></code>, so that legacy audio plugins can be
2374: tried, or to show text to the users of these older browsers informing
2375: them of how to access the audio contents.</p><p class="note">In particular, this content is not intended to
2376: address accessibility concerns. To make audio content accessible to
2377: the deaf or to those with other physical or cognitive disabilities,
1.90 mike 2378: a variety of features are available. If captions or a sign language
2379: video are available, the <code><a href="#the-video-element">video</a></code> element can be used
2380: instead of the <code><a href="#the-audio-element">audio</a></code> element to play the audio,
2381: allowing users to enable the visual alternatives. Chapter titles can
2382: be provided to aid navigation, using the <code><a href="#the-track-element">track</a></code> element
2383: and a WebVTT file. And, naturally, transcripts or other textual
2384: alternatives can be provided by simply linking to them in the prose
2385: 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 2386: 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>,
2387: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2388: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2389: <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
2390: elements</a>.</p><div class="impl">
2391:
2392: <p>When an <code><a href="#the-audio-element">audio</a></code> element is <a href="#potentially-playing">potentially
2393: playing</a>, it must have its audio data played synchronized with
2394: the <a href="#current-playback-position">current playback position</a>, at the element's
2395: <a href="#effective-media-volume">effective media volume</a>.</p>
2396:
2397: <p>When an <code><a href="#the-audio-element">audio</a></code> element is not <a href="#potentially-playing">potentially
2398: playing</a>, audio must not play for the element.</p>
2399:
2400: </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>
2401:
2402: <dd>
2403:
2404: <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
2405: passed in the argument, if applicable.</p>
2406:
2407: </dd>
2408:
2409: </dl><div class="impl">
2410:
2411: <p>Two constructors are provided for creating
2412: <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> objects (in addition to the factory
2413: 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,
2414: these must return a new <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new
2415: <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
2416: 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
2417: its <code title="attr-media-src"><a href="#attr-media-src">src</a></code> content attribute set to
2418: the provided value, and the user agent must invoke the object's
2419: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2420: algorithm</a> before returning. The element's document must be
2421: the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
2422: context</a> of the <code><a href="browsers.html#window">Window</a></code> object on which the
2423: interface object of the invoked constructor is found.</p>
2424:
2425: </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>
2426: <dd>None.</dd>
2427: <dt>Contexts in which this element can be used:</dt>
2428: <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>
2429: or <code><a href="#the-track-element">track</a></code> elements.</dd>
2430: <dt>Content model:</dt>
2431: <dd>Empty.</dd>
2432: <dt>Content attributes:</dt>
2433: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2434: <dd><code title="attr-source-src"><a href="#attr-source-src">src</a></code></dd>
2435: <dd><code title="attr-source-type"><a href="#attr-source-type">type</a></code></dd>
2436: <dd><code title="attr-source-media"><a href="#attr-source-media">media</a></code></dd>
2437: <dt>DOM interface:</dt>
2438: <dd>
2439: <pre class="idl">interface <dfn id="htmlsourceelement">HTMLSourceElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2440: attribute DOMString <a href="#dom-source-src" title="dom-source-src">src</a>;
2441: attribute DOMString <a href="#dom-source-type" title="dom-source-type">type</a>;
2442: attribute DOMString <a href="#dom-source-media" title="dom-source-media">media</a>;
2443: };</pre>
2444: </dd>
2445: </dl><p>The <code><a href="#the-source-element">source</a></code> element allows authors to specify
2446: multiple alternative <a href="#media-resource" title="media resource">media
2447: resources</a> for <a href="#media-element" title="media element">media
2448: 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
2449: gives the address of the <a href="#media-resource">media resource</a>. The value must
2450: be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2451: spaces</a>. This attribute must be present.</p><p class="note">Dynamically modifying a <code><a href="#the-source-element">source</a></code> element
2452: and its attribute when the element is already inserted in a
2453: <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 2454: 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
2455: element</a> directly, possibly making use of the <code title="dom-navigator-canPlayType"><a href="#dom-navigator-canplaytype">canPlayType()</a></code> method to
2456: pick from amongst available resources. Generally, manipulating
2457: <code><a href="#the-source-element">source</a></code> elements manually after the document has been
2458: 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 2459: attribute gives the type of the <a href="#media-resource">media resource</a>, to help
2460: the user agent determine if it can play this <a href="#media-resource">media
2461: resource</a> before fetching it. If specified, its value must be
2462: a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>. The <code title="">codecs</code>
2463: parameter, which certain MIME types define, might be necessary to
2464: specify exactly how the resource is encoded. <a href="references.html#refsRFC4281">[RFC4281]</a></p><div class="example">
2465:
2466: <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>
2467:
2468: <dl><dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2469: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></pre></dd>
2470:
2471: <dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2472: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></pre></dd>
2473:
2474: <dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
2475: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></pre></dd>
2476:
2477: <dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2478: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></pre></dd>
2479:
2480:
2481: <dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2482: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></pre></dd>
2483:
2484: <dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2485: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></pre></dd>
2486:
2487: <dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
2488: <dd><pre><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></pre></dd>
2489:
2490:
2491: <dt>Theora video and Vorbis audio in Ogg container</dt>
2492: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></pre></dd>
2493:
2494: <dt>Theora video and Speex audio in Ogg container</dt>
2495: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></pre></dd>
2496:
2497: <dt>Vorbis audio alone in Ogg container</dt>
2498: <dd><pre><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></pre></dd>
2499:
2500: <dt>Speex audio alone in Ogg container</dt>
2501: <dd><pre><source src='audio.spx' type='audio/ogg; codecs=speex'></pre></dd>
2502:
2503: <dt>FLAC audio alone in Ogg container</dt>
2504: <dd><pre><source src='audio.oga' type='audio/ogg; codecs=flac'></pre></dd>
2505:
2506: <dt>Dirac video and Vorbis audio in Ogg container</dt>
2507: <dd><pre><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></pre></dd>
2508:
2509:
2510:
2511:
2512:
2513:
2514: </dl></div><p>The <dfn id="attr-source-media" title="attr-source-media"><code>media</code></dfn>
2515: attribute gives the intended media type of the <a href="#media-resource">media
2516: resource</a>, to help the user agent determine if this
2517: <a href="#media-resource">media resource</a> is useful to the user before fetching
2518: 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
2519: "<code title="">all</code>", meaning that by default the <a href="#media-resource">media
2520: resource</a> is suitable for all media.</p><div class="impl">
2521:
2522: <p>If a <code><a href="#the-source-element">source</a></code> element is inserted as a child of a
2523: <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
2524: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, the user
2525: 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
2526: algorithm</a>.</p>
2527:
2528: <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
2529: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2530: name.</p>
2531:
2532: </div><div class="example">
2533:
2534: <p>If the author isn't sure if the user agents will all be able to
2535: render the media resources provided, the author can listen to the
2536: <code title="event-error">error</code> event on the last
2537: <code><a href="#the-source-element">source</a></code> element and trigger fallback behavior:</p>
2538:
2539: <pre><script>
2540: function fallback(video) {
2541: // replace <video> with its contents
2542: while (video.hasChildNodes()) {
2543: if (video.firstChild instanceof HTMLSourceElement)
2544: video.removeChild(video.firstChild);
2545: else
2546: video.parentNode.insertBefore(video.firstChild, video);
2547: }
2548: video.parentNode.removeChild(video);
2549: }
2550: </script>
2551: <video controls autoplay>
2552: <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
2553: <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
2554: onerror="fallback(parentNode)">
2555: ...
2556: </video></pre>
2557:
2558: </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>
2559: <dd>None.</dd>
2560: <dt>Contexts in which this element can be used:</dt>
2561: <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>
2562: <dt>Content model:</dt>
2563: <dd>Empty.</dd>
2564: <dt>Content attributes:</dt>
2565: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2566: <dd><code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code></dd>
2567: <dd><code title="attr-track-src"><a href="#attr-track-src">src</a></code></dd>
2568: <dd><code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code></dd>
2569: <dd><code title="attr-track-label"><a href="#attr-track-label">label</a></code></dd>
2570: <dd><code title="attr-track-default"><a href="#attr-track-default">default</a></code></dd>
2571: <dt>DOM interface:</dt>
2572: <dd>
2573: <pre class="idl">interface <dfn id="htmltrackelement">HTMLTrackElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2574: attribute DOMString <a href="#dom-track-kind" title="dom-track-kind">kind</a>;
2575: attribute DOMString <a href="#dom-track-src" title="dom-track-src">src</a>;
2576: attribute DOMString <a href="#dom-track-srclang" title="dom-track-srclang">srclang</a>;
2577: attribute DOMString <a href="#dom-track-label" title="dom-track-label">label</a>;
2578: attribute boolean <a href="#dom-track-default" title="dom-track-default">default</a>;
2579:
2580: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-track-track" title="dom-track-track">track</a>;
2581: };</pre>
2582: </dd>
2583: </dl><p>The <code><a href="#the-track-element">track</a></code> element allows authors to specify explicit
2584: 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>
2585: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following
2586: table lists the keywords defined for this attribute. The keyword
2587: given in the first cell of each row maps to the state given in the
2588: second cell.</p><table><thead><tr><th>Keyword
2589: </th><th>State
2590: </th><th>Brief description
2591: </th></tr></thead><tbody><tr><td><dfn id="attr-track-kind-keyword-subtitles" title="attr-track-kind-keyword-subtitles"><code>subtitles</code></dfn>
2592: </td><td><dfn id="attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</dfn>
2593: </td><td>
2594: 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 soundtrack).
2595: Displayed over the video.
2596: </td></tr><tr><td><dfn id="attr-track-kind-keyword-captions" title="attr-track-kind-keyword-captions"><code>captions</code></dfn>
2597: </td><td><dfn id="attr-track-kind-captions" title="attr-track-kind-captions">Captions</dfn>
2598: </td><td>
1.95 mike 2599: Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when the soundtrack is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf).
1.47 mike 2600: Displayed over the video; labeled as appropriate for the hard-of-hearing.
2601: </td></tr><tr><td><dfn id="attr-track-kind-keyword-descriptions" title="attr-track-kind-keyword-descriptions"><code>descriptions</code></dfn>
2602: </td><td><dfn id="attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</dfn>
2603: </td><td>
1.95 mike 2604: 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).
2605: Synthesized as audio.
1.47 mike 2606: </td></tr><tr><td><dfn id="attr-track-kind-keyword-chapters" title="attr-track-kind-keyword-chapters"><code>chapters</code></dfn>
2607: </td><td><dfn id="attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</dfn>
2608: </td><td>
2609: Chapter titles, intended to be used for navigating the <a href="#media-resource">media resource</a>.
1.91 mike 2610: Displayed as an interactive (potentially nested) list in the user agent's interface.
1.47 mike 2611: </td></tr><tr><td><dfn id="attr-track-kind-keyword-metadata" title="attr-track-kind-keyword-metadata"><code>metadata</code></dfn>
2612: </td><td><dfn id="attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</dfn>
2613: </td><td>
2614: Tracks intended for use from script.
2615: Not displayed by the user agent.
2616: </td></tr></tbody></table><p>The attribute may be omitted. The <i>missing value default</i> is
2617: 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
2618: gives the address of the text track data. The value must be a
2619: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2620: spaces</a>. This attribute must be present.</p><div class="impl">
2621:
2622: <p>If the element has a <code title="attr-track-src"><a href="#attr-track-src">src</a></code>
2623: attribute whose value is not the empty string and whose value, when
2624: the attribute was set, could be successfully <a href="urls.html#resolve-a-url" title="resolve a
2625: url">resolved</a> relative to the element, then the element's
2626: <dfn id="track-url">track URL</dfn> is the resulting <a href="urls.html#absolute-url">absolute
2627: URL</a>. Otherwise, the element's <a href="#track-url">track URL</a> is the
2628: empty string.</p>
2629:
2630: </div><p>The <dfn id="attr-track-srclang" title="attr-track-srclang"><code>srclang</code></dfn>
2631: attribute gives the language of the text track data. The value must
2632: be a valid BCP 47 language tag. This attribute must be present if
2633: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute is
2634: in the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a>
2635: state. <a href="references.html#refsBCP47">[BCP47]</a></p><div class="impl">
2636:
2637: <p>If the element has a <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attribute whose value is
2638: not the empty string, then the element's <dfn id="track-language">track language</dfn>
2639: is the value of the attribute. Otherwise, the element has no
2640: <a href="#track-language">track language</a>.</p>
2641:
2642: </div><p>The <dfn id="attr-track-label" title="attr-track-label"><code>label</code></dfn>
2643: attribute gives a user-readable title for the track. This title is
2644: 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
2645: in their user interface.</p><p>The value of the <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2646: attribute, if the attribute is present, must not be the empty
2647: string. Furthermore, there must not be two <code><a href="#the-track-element">track</a></code>
2648: 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
2649: state, whose <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code>
2650: attributes are both missing or have values that represent the same
2651: language, and whose <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2652: attributes are again both missing or both have the same value.</p><div class="impl">
2653:
2654: <p>If the element has a <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2655: attribute whose value is not the empty string, then the element's
2656: <dfn id="track-label">track label</dfn> is the value of the attribute. Otherwise, the
2657: element's <a href="#track-label">track label</a> is a user-agent defined string
2658: (e.g. the string "untitled" in the user's locale, or a value
2659: automatically generated from the other attributes).</p>
2660:
2661: </div><p>The <dfn id="attr-track-default" title="attr-track-default"><code>default</code></dfn>
2662: attribute, if specified, indicates that the track is to be enabled
2663: if the user's preferences do not indicate that another track would
2664: be more appropriate. There must not be more than one
2665: <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-track"><a href="#dom-track-track">track</a></code></dt>
2666:
2667: <dd>
2668:
2669: <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>
2670:
2671: </dd>
2672:
2673: </dl><div class="impl">
2674:
2675: <p>The <dfn id="dom-track-track" title="dom-track-track"><code>track</code></dfn> IDL
2676: attribute must, on getting, return the <code><a href="#the-track-element">track</a></code> element's
2677: <a href="#text-track">text track</a>'s corresponding <code><a href="#texttrack">TextTrack</a></code>
2678: object.</p>
2679:
2680: <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
2681: must <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the
2682: same name. The <dfn id="dom-track-kind" title="dom-track-kind"><code>kind</code></dfn>
2683: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
2684: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
2685:
2686: </div><div class="example">
2687:
2688: <p>This video has subtitles in several languages:</p>
2689:
2690: <pre><video src="brave.webm">
2691: <track kind=subtitles src=brave.en.vtt srclang=en label="English">
2692: <track kind=captions src=brave.en.vtt srclang=en label="English for the Hard of Hearing">
1.73 mike 2693: <track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
2694: <track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
1.47 mike 2695: </video></pre>
2696:
2697: </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>
2698: (<code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>, in this specification)
2699: implement the following interface:</p><pre class="idl">interface <dfn id="htmlmediaelement">HTMLMediaElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2700:
2701: // error state
1.68 mike 2702: readonly attribute <a href="#mediaerror">MediaError</a>? <a href="#dom-media-error" title="dom-media-error">error</a>;
1.47 mike 2703:
2704: // network state
2705: attribute DOMString <a href="#dom-media-src" title="dom-media-src">src</a>;
2706: readonly attribute DOMString <a href="#dom-media-currentsrc" title="dom-media-currentSrc">currentSrc</a>;
1.61 mike 2707: attribute DOMString <a href="#dom-media-crossorigin" title="dom-media-crossOrigin">crossOrigin</a>;
1.47 mike 2708: const unsigned short <a href="#dom-media-network_empty" title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</a> = 0;
2709: const unsigned short <a href="#dom-media-network_idle" title="dom-media-NETWORK_IDLE">NETWORK_IDLE</a> = 1;
2710: const unsigned short <a href="#dom-media-network_loading" title="dom-media-NETWORK_LOADING">NETWORK_LOADING</a> = 2;
2711: const unsigned short <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a> = 3;
2712: readonly attribute unsigned short <a href="#dom-media-networkstate" title="dom-media-networkState">networkState</a>;
2713: attribute DOMString <a href="#dom-media-preload" title="dom-media-preload">preload</a>;
2714: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-buffered" title="dom-media-buffered">buffered</a>;
2715: void <a href="#dom-media-load" title="dom-media-load">load</a>();
2716: DOMString <a href="#dom-navigator-canplaytype" title="dom-navigator-canPlayType">canPlayType</a>(in DOMString type);
2717:
2718: // ready state
2719: const unsigned short <a href="#dom-media-have_nothing" title="dom-media-HAVE_NOTHING">HAVE_NOTHING</a> = 0;
2720: const unsigned short <a href="#dom-media-have_metadata" title="dom-media-HAVE_METADATA">HAVE_METADATA</a> = 1;
2721: const unsigned short <a href="#dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</a> = 2;
2722: const unsigned short <a href="#dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</a> = 3;
2723: const unsigned short <a href="#dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</a> = 4;
2724: readonly attribute unsigned short <a href="#dom-media-readystate" title="dom-media-readyState">readyState</a>;
2725: readonly attribute boolean <a href="#dom-media-seeking" title="dom-media-seeking">seeking</a>;
2726:
2727: // playback state
2728: attribute double <a href="#dom-media-currenttime" title="dom-media-currentTime">currentTime</a>;
2729: readonly attribute double <a href="#dom-media-initialtime" title="dom-media-initialTime">initialTime</a>;
2730: readonly attribute double <a href="#dom-media-duration" title="dom-media-duration">duration</a>;
2731: readonly attribute <span>Date</span> <a href="#dom-media-startoffsettime" title="dom-media-startOffsetTime">startOffsetTime</a>;
2732: readonly attribute boolean <a href="#dom-media-paused" title="dom-media-paused">paused</a>;
2733: attribute double <a href="#dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate">defaultPlaybackRate</a>;
2734: attribute double <a href="#dom-media-playbackrate" title="dom-media-playbackRate">playbackRate</a>;
2735: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-played" title="dom-media-played">played</a>;
2736: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-seekable" title="dom-media-seekable">seekable</a>;
2737: readonly attribute boolean <a href="#dom-media-ended" title="dom-media-ended">ended</a>;
2738: attribute boolean <a href="#dom-media-autoplay" title="dom-media-autoplay">autoplay</a>;
2739: attribute boolean <a href="#dom-media-loop" title="dom-media-loop">loop</a>;
2740: void <a href="#dom-media-play" title="dom-media-play">play</a>();
2741: void <a href="#dom-media-pause" title="dom-media-pause">pause</a>();
2742:
2743: // media controller
2744: attribute <span>DOMString</span> <a href="#dom-media-mediagroup" title="dom-media-mediaGroup">mediaGroup</a>;
1.68 mike 2745: attribute <a href="#mediacontroller">MediaController</a>? <a href="#dom-media-controller" title="dom-media-controller">controller</a>;
1.47 mike 2746:
2747: // controls
2748: attribute boolean <a href="#dom-media-controls" title="dom-media-controls">controls</a>;
2749: attribute double <a href="#dom-media-volume" title="dom-media-volume">volume</a>;
2750: attribute boolean <a href="#dom-media-muted" title="dom-media-muted">muted</a>;
2751: attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
2752:
2753: // tracks
1.76 mike 2754: readonly attribute <a href="#audiotracklist">AudioTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
2755: readonly attribute <a href="#videotracklist">VideoTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
2756: readonly attribute <a href="#texttracklist">TextTrackList</a> <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
1.47 mike 2757: <a href="#mutabletexttrack">MutableTextTrack</a> <a href="#dom-media-addtexttrack" title="dom-media-addTextTrack">addTextTrack</a>(in DOMString kind, in optional DOMString label, in optional DOMString language);
1.61 mike 2758: };</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 2759: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2760: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2761: <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
2762: this section.</p><p><a href="#media-element" title="media element">Media elements</a> are used to
2763: present audio data, or video and audio data, to the user. This is
2764: referred to as <dfn id="media-data">media data</dfn> in this section, since this
2765: section applies equally to <a href="#media-element" title="media element">media
1.56 mike 2766: elements</a> for audio or for video.
1.85 mike 2767:
1.56 mike 2768: The term <dfn id="media-resource">media resource</dfn> is used to refer to the complete
2769: set of media data, e.g. the complete video file, or complete audio
2770: file.
1.85 mike 2771:
1.56 mike 2772: </p><p>A <a href="#media-resource">media resource</a> can have multiple audio and video
1.47 mike 2773: tracks. For the purposes of a <a href="#media-element">media element</a>, the video
2774: data of the <a href="#media-resource">media resource</a> is only that of the
2775: 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
2776: audio data of the <a href="#media-resource">media resource</a> is the result of
2777: mixing all the currently enabled tracks (if any) given by the
2778: element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>
2779: 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>
2780: elements can be used for both audio and video. The main difference
2781: between the two is simply that the <code><a href="#the-audio-element">audio</a></code> element has no
2782: playback area for visual content (such as video or captions),
2783: whereas the <code><a href="#the-video-element">video</a></code> element does.</p><div class="impl">
2784:
2785: <p>Except where otherwise specified, the <a href="webappapis.html#task-source">task source</a>
2786: for all the tasks <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> in this
2787: section and its subsections is the <dfn id="media-element-event-task-source">media element event task
2788: source</dfn>.</p>
2789:
2790: </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>
2791:
2792: <dd>
2793:
2794: <p>Returns a <code><a href="#mediaerror">MediaError</a></code> object representing the
2795: current error state of the element.</p>
2796:
2797: <p>Returns null if there is no error.</p>
2798:
2799: </dd>
2800:
2801: </dl><div class="impl">
2802:
2803: <p>All <a href="#media-element" title="media element">media elements</a> have an
2804: associated error status, which records the last error the element
2805: encountered since its <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2806: algorithm</a> was last invoked. The <dfn id="dom-media-error" title="dom-media-error"><code>error</code></dfn> attribute, on
2807: getting, must return the <code><a href="#mediaerror">MediaError</a></code> object created for
2808: this last error, or null if there has not been an error.</p>
2809:
2810: </div><pre class="idl">interface <dfn id="mediaerror">MediaError</dfn> {
2811: const unsigned short <a href="#dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</a> = 1;
2812: const unsigned short <a href="#dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</a> = 2;
2813: const unsigned short <a href="#dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</a> = 3;
2814: 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;
2815: readonly attribute unsigned short <a href="#dom-mediaerror-code" title="dom-MediaError-code">code</a>;
2816: };</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>
2817:
2818: <dd>
2819:
2820: <p>Returns the current error's error code, from the list below.</p>
2821:
2822: </dd>
2823:
2824: </dl><div class="impl">
2825:
2826: <p>The <dfn id="dom-mediaerror-code" title="dom-MediaError-code"><code>code</code></dfn>
2827: attribute of a <code><a href="#mediaerror">MediaError</a></code> object must return the code
2828: for the error, which must be one of the following:</p>
2829:
2830: </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>
2831:
2832: <dd>The fetching process for the <a href="#media-resource">media resource</a> was
2833: aborted by the user agent at the user's request.</dd>
2834:
2835: <dt><dfn id="dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK"><code>MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
2836:
2837: <dd>A network error of some description caused the user agent to
2838: stop fetching the <a href="#media-resource">media resource</a>, after the resource
2839: was established to be usable.</dd>
2840:
2841: <dt><dfn id="dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE"><code>MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
2842:
2843: <dd>An error of some description occurred while decoding the
2844: <a href="#media-resource">media resource</a>, after the resource was established to
2845: be usable.</dd>
2846:
2847: <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>
2848:
2849: <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>
2850:
2851: </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
2852: attribute on <a href="#media-element" title="media element">media elements</a> gives
2853: the address of the media resource (video, audio) to show. The
2854: attribute, if present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.61 mike 2855: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-media-crossorigin" title="attr-media-crossorigin"><code>crossorigin</code></dfn>
2856: content attribute on <a href="#media-element" title="media element">media
2857: elements</a> is a <a href="fetching-resources.html#cors-settings-attribute">CORS settings attribute</a>.</p><div class="impl">
1.47 mike 2858:
2859: <p>If a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute of a
2860: <a href="#media-element">media element</a> is set or changed, the user agent must
2861: invoke the <a href="#media-element">media element</a>'s <a href="#media-element-load-algorithm">media element load
2862: 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
2863: if there are <code><a href="#the-source-element">source</a></code> elements present.)</p>
2864:
2865: <p>The <dfn id="dom-media-src" title="dom-media-src"><code>src</code></dfn> IDL
2866: attribute on <a href="#media-element" title="media element">media elements</a> must
2867: <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the same name.</p>
2868:
1.61 mike 2869: <p>The <dfn id="dom-media-crossorigin" title="dom-media-crossOrigin"><code>crossOrigin</code></dfn> IDL
2870: 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
2871: attribute.</p>
2872:
1.47 mike 2873: </div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code></dt>
2874:
2875: <dd>
2876:
2877: <p>Returns the address of the current <a href="#media-resource">media resource</a>.</p>
2878:
2879: <p>Returns the empty string when there is no <a href="#media-resource">media resource</a>.</p>
2880:
2881: </dd>
2882:
2883: </dl><div class="impl">
2884:
2885: <p>The <dfn id="dom-media-currentsrc" title="dom-media-currentSrc"><code>currentSrc</code></dfn> IDL
2886: attribute is initially the empty string. Its value is changed by the
2887: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2888: algorithm</a> defined below.</p>
2889:
2890: </div><p class="note">There are two ways to specify a <a href="#media-resource">media
2891: resource</a>, the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
2892: attribute, or <code><a href="#the-source-element">source</a></code> elements. The attribute overrides
1.53 mike 2893: 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 2894: <em>type</em>, specifically a <a href="infrastructure.html#mime-type">MIME type</a>, in some cases
2895: with a <code title="">codecs</code> parameter. (Whether the <code title="">codecs</code> parameter is allowed or not depends on the
2896: MIME type.) <a href="references.html#refsRFC4281">[RFC4281]</a></p><p>Types are usually somewhat incomplete descriptions; for example
2897: "<code title="">video/mpeg</code>" doesn't say anything except what
2898: the container type is, and even a type like "<code title="">video/mp4; codecs="avc1.42E01E,
2899: mp4a.40.2"</code>" doesn't include information like the actual
2900: bitrate (only the maximum bitrate). Thus, given a type, a user agent
2901: can often only know whether it <em>might</em> be able to play
2902: media of that type (with varying levels of confidence), or whether
2903: 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
2904: one that describes a resource that the user agent definitely does
2905: not support, for example because it doesn't recognize the container
2906: type, or it doesn't support the listed codecs.</p><p>The <a href="infrastructure.html#mime-type">MIME type</a>
2907: "<code>application/octet-stream</code>" with no parameters is never
2908: <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user agent knows it cannot render</a>. User
2909: agents must treat that type as equivalent to the lack of any
2910: explicit <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a>
2911: when it is used to label a potential <a href="#media-resource">media
2912: resource</a>.</p><p class="note">
2913: "<code>application/octet-stream</code>"
2914: is special-cased here; if any parameter appears with it, it
2915: should
2916:
2917: be treated just like any other <a href="infrastructure.html#mime-type">MIME type</a>.
2918:
2919: This is a deviation from the rule that unknown <a href="infrastructure.html#mime-type">MIME type</a> parameters
2920: should be ignored.
2921:
2922:
2923: </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>
2924:
2925: <dd>
2926:
2927: <p>Returns the empty string (a negative response), "maybe", or
2928: "probably" based on how confident the user agent is that it can
2929: play media resources of the given type.</p>
2930:
2931: </dd>
2932:
2933: </dl><div class="impl">
2934:
2935: <p>The <dfn id="dom-navigator-canplaytype" title="dom-navigator-canPlayType"><code>canPlayType(<var title="">type</var>)</code></dfn> method must return the empty
2936: string if <var title="">type</var> is <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user
2937: agent knows it cannot render</a> or is the type
2938: "<code>application/octet-stream</code>"; it must return "<code title="">probably</code>" if the user agent is confident that the
2939: type represents a <a href="#media-resource">media resource</a> that it can render if
2940: used in with this <code><a href="#the-audio-element">audio</a></code> or <code><a href="#the-video-element">video</a></code> element;
2941: and it must return "<code title="">maybe</code>" otherwise.
2942: Implementors are encouraged to return "<code title="">maybe</code>"
2943: unless the type can be confidently established as being supported or
2944: 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
2945: present.</p>
2946:
2947: </div><div class="example">
2948:
2949: <p>This script tests to see if the user agent supports a
2950: (fictional) new format to dynamically decide whether to use a
2951: <code><a href="#the-video-element">video</a></code> element or a plugin:</p>
2952:
2953: <pre><section id="video">
2954: <p><a href="playing-cats.nfv">Download video</a></p>
2955: </section>
2956: <script>
2957: var videoSection = document.getElementById('video');
2958: var videoElement = document.createElement('video');
2959: var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
1.69 mike 2960: if (support != "probably" && "New Fictional Video Plugin" in navigator.plugins) {
1.47 mike 2961: // not confident of browser support
2962: // but we have a plugin
2963: // so use plugin instead
2964: videoElement = document.createElement("embed");
2965: } else if (support == "") {
2966: // no support from browser and no plugin
2967: // do nothing
2968: videoElement = null;
2969: }
2970: if (videoElement) {
2971: while (videoSection.hasChildNodes())
2972: videoSection.removeChild(videoSection.firstChild);
2973: videoElement.setAttribute("src", "playing-cats.nfv");
2974: videoSection.appendChild(videoElement);
2975: }
2976: </script></pre>
2977:
2978: </div><p class="note">The <code title="attr-source-type"><a href="#attr-source-type">type</a></code>
2979: attribute of the <code><a href="#the-source-element">source</a></code> element allows the user agent
2980: to avoid downloading resources that use formats it cannot
2981: 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>
2982:
2983: <dd>
2984:
2985: <p>Returns the current state of network activity for the element,
2986: from the codes in the list below.</p>
2987:
2988: </dd>
2989:
2990: </dl><div class="impl">
2991:
2992: <p>As <a href="#media-element" title="media element">media elements</a> interact
2993: with the network, their current network activity is represented by
2994: the <dfn id="dom-media-networkstate" title="dom-media-networkState"><code>networkState</code></dfn>
2995: attribute. On getting, it must return the current network state of
2996: the element, which must be one of the following values:</p>
2997:
2998: </div><dl><dt><dfn id="dom-media-network_empty" title="dom-media-NETWORK_EMPTY"><code>NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
2999:
3000: <dd>The element has not yet been initialized. All attributes are in
3001: their initial states.</dd>
3002:
3003: <dt><dfn id="dom-media-network_idle" title="dom-media-NETWORK_IDLE"><code>NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
3004:
3005: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3006: algorithm</a> is active and</span> has selected a <a href="#media-resource" title="media resource">resource</a>, but it is not actually
3007: using the network at this time.</dd>
3008:
3009: <dt><dfn id="dom-media-network_loading" title="dom-media-NETWORK_LOADING"><code>NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
3010:
3011: <dd>The user agent is actively trying to download data.</dd>
3012:
3013: <dt><dfn id="dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE"><code>NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
3014:
3015: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3016: algorithm</a> is active, but it</span> has not yet found a <a href="#media-resource" title="media resource">resource</a> to use.</dd>
3017:
3018: </dl><div class="impl">
3019:
3020: <p>The <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3021: algorithm</a> defined below describes exactly when the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute changes
3022: value and what events fire to indicate changes in this state.</p>
3023:
3024: </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>
3025:
3026: <dd>
3027:
3028: <p>Causes the element to reset and start selecting and loading a
3029: new <a href="#media-resource">media resource</a> from scratch.</p>
3030:
3031: </dd>
3032:
3033: </dl><div class="impl">
3034:
3035: <p>All <a href="#media-element" title="media element">media elements</a> have an
3036: <dfn id="autoplaying-flag">autoplaying flag</dfn>, which must begin in the true state, and
3037: a <dfn id="delaying-the-load-event-flag">delaying-the-load-event flag</dfn>, which must begin in the
3038: false state. While the <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> is
3039: true, the element must <a href="the-end.html#delay-the-load-event">delay the load event</a> of its
3040: document.</p>
3041:
3042: <p>When the <dfn id="dom-media-load" title="dom-media-load"><code>load()</code></dfn>
3043: method on a <a href="#media-element">media element</a> is invoked, the user agent
3044: must run the <a href="#media-element-load-algorithm">media element load algorithm</a>.</p>
3045:
3046: <p>The <dfn id="media-element-load-algorithm">media element load algorithm</dfn> consists of the
3047: following steps.</p>
3048:
3049: <ol><li><p>Abort any already-running instance of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3050: algorithm</a> for this element.</p></li>
3051:
3052: <li>
3053:
3054: <p>If there are any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> from
3055: the <a href="#media-element">media element</a>'s <a href="#media-element-event-task-source">media element event task
3056: source</a> in one of the <a href="webappapis.html#task-queue" title="task queue">task
3057: queues</a>, then remove those tasks.</p>
3058:
3059: <p class="note">Basically, pending events and callbacks for the
3060: media element are discarded when the media element starts loading
3061: a new resource.</p>
3062:
3063: </li>
3064:
3065: <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
3066: 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
3067: element</a>.</p></li>
3068:
3069: <li>
3070:
3071: <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
3072: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, then
3073: run these substeps:</p>
3074:
3075: <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
3076: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the <a href="#media-element">media
3077: element</a>.</p></li>
3078:
3079: <li><p>If a fetching process is in progress for the <a href="#media-element">media
3080: element</a>, the user agent should stop it.</p></li>
3081:
3082: <li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3083: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>.</p></li>
3084:
3085: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3086: text tracks</a>.</p></li>
3087:
3088: <li><p>If <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is
3089: not set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then set it
3090: to that state.
3091:
3092: </p></li>
3093:
3094: <li><p>If the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
3095: attribute is false, then set it to true.</p></li>
3096:
3097: <li><p>If <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true,
3098: set it to false.</p></li>
3099:
3100: <li>
3101:
3102: <p>Set the <a href="#current-playback-position">current playback position</a> to 0.</p>
3103:
3104: <p>If this changed the <a href="#current-playback-position">current playback position</a>,
3105: then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3106: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
3107: <a href="#media-element">media element</a>.</p>
3108:
3109: </li>
3110:
3111: <li><p>Set the <a href="#initial-playback-position">initial playback position</a> to
3112: 0.</p></li>
3113:
3114: <li><p>Set the <a href="#timeline-offset">timeline offset</a> to Not-a-Number
3115: (NaN).</p></li>
3116:
3117: <li>
3118:
3119: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3120: attribute to Not-a-Number (NaN).</p>
3121:
3122: <p class="note">The user agent <a href="#durationChange">will
3123: not</a> fire a <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event
3124: for this particular change of the duration.</p>
3125:
3126: </li>
3127:
3128: </ol></li>
3129:
3130: <li><p>Set the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute to the
3131: value of the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
3132: attribute.</p></li>
3133:
3134: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code> attribute
3135: to null and the <a href="#autoplaying-flag">autoplaying flag</a> to true.</p></li>
3136:
3137: <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
3138: algorithm</a>.</p></li>
3139:
3140: <li>
3141:
3142: <p class="note">Playback of any previously playing <a href="#media-resource">media
3143: resource</a> for this element stops.</p>
3144:
3145: </li>
3146:
3147: </ol><p>The <dfn id="concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3148: algorithm</dfn> for a <a href="#media-element">media element</a> is as follows. This
3149: algorithm is always invoked synchronously, but one of the first
3150: steps in the algorithm is to return and continue running the
3151: remaining steps asynchronously, meaning that it runs in the
3152: background with scripts and other <a href="webappapis.html#concept-task" title="concept-task">tasks</a> running in parallel. In addition,
3153: this algorithm interacts closely with the <a href="webappapis.html#event-loop">event loop</a>
3154: mechanism; in particular, it has <a href="webappapis.html#synchronous-section" title="synchronous
3155: section">synchronous sections</a> (which are triggered as part of
3156: the <a href="webappapis.html#event-loop">event loop</a> algorithm). Steps in such sections are
3157: marked with ⌛.</p>
3158:
3159: <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>
3160:
3161: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
3162: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that invoked this
3163: algorithm to continue. The <a href="webappapis.html#synchronous-section">synchronous section</a>
3164: consists of all the remaining steps of this algorithm until the
3165: algorithm says the <a href="webappapis.html#synchronous-section">synchronous section</a> has
3166: ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous
3167: sections</a> are marked with ⌛.)</p></li>
3168:
3169: <li>
3170:
3171: <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>
3172:
3173: <p>⌛ Otherwise, if the <a href="#media-element">media element</a> does not
3174: have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute but has a
3175: <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>
3176: element child in <a href="infrastructure.html#tree-order">tree order</a>.</p>
3177:
3178: <p>⌛ Otherwise the <a href="#media-element">media element</a> has neither a
3179: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute nor a
3180: <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
3181: these steps; the <a href="webappapis.html#synchronous-section">synchronous section</a> ends.</p>
3182:
3183: </li>
3184:
3185: <li><p>⌛ Set the <a href="#media-element">media element</a>'s
3186: <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
3187: its <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3188: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3189:
3190: <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
3191: event</a> named <code title="event-media-loadstart"><a href="#event-media-loadstart">loadstart</a></code> at the <a href="#media-element">media
3192: element</a>.</p></li>
3193:
3194: <li>
3195:
3196: <p>If <var title="">mode</var> is <i title="">attribute</i>, then
3197: run these substeps:</p>
3198:
3199: <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
3200: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3201: down to the <i title="">failed</i> step below.</p></li>
3202:
3203: <li><p>⌛ Let <var title="">absolute URL</var> be the
3204: <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>
3205: specified by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
3206: attribute's value relative to the <a href="#media-element">media element</a> when
3207: the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was last
3208: changed.</p>
3209: </li><li><p>⌛ If <var title="">absolute URL</var> was obtained
3210: 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>
3211:
3212: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3213: remaining steps asynchronously.</p></li>
3214:
3215: <li><p>If <var title="">absolute URL</var> was obtained
3216: successfully, run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3217: algorithm</a> with <var title="">absolute URL</var>. If that
3218: algorithm returns without aborting <em>this</em> one, then the
3219: load failed.</p></li>
3220:
3221: <li>
3222:
3223: <p><i>Failed</i>: Reaching this step indicates that the media
3224: resource failed to load or that the given <a href="urls.html#url">URL</a> could
3225: not be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a>. In one
3226: atomic operation, run the following steps:</p>
3227:
3228: <ol><li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3229: 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
3230: <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>
3231:
3232: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3233: text tracks</a>.</p></li>
3234:
3235: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3236: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3237: value.</p></li>
3238:
3239: </ol></li>
3240:
3241: <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
3242: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3243: at the <a href="#media-element">media element</a>.</p></li>
3244:
3245: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a>
3246: to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying
3247: the load event</a>.</p></li>
3248:
3249: <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
3250: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute is changed, the
3251: element won't attempt to load another resource.</p></li>
3252:
3253:
3254: </ol><p>Otherwise, the <code><a href="#the-source-element">source</a></code> elements will be used; run
3255: these substeps:</p>
3256:
3257: <ol><li>
3258:
3259: <p>⌛ Let <var title="">pointer</var> be a position
3260: defined by two adjacent nodes in the <a href="#media-element">media
3261: element</a>'s child list, treating the start of the list
3262: (before the first child in the list, if any) and end of the list
3263: (after the last child in the list, if any) as nodes in their own
3264: right. One node is the node before <var title="">pointer</var>,
3265: 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
3266: any, or the end of the list, if it is the last node.</p>
3267:
3268: <p>As nodes are inserted and removed into the <a href="#media-element">media
3269: element</a>, <var title="">pointer</var> must be updated as
3270: follows:</p>
3271:
3272: <dl><dt>If a new node is inserted between the two nodes that
3273: define <var title="">pointer</var></dt>
3274:
3275: <dd>Let <var title="">pointer</var> be the point between the
3276: node before <var title="">pointer</var> and the new node. In
3277: other words, insertions at <var title="">pointer</var> go after
3278: <var title="">pointer</var>.</dd>
3279:
3280: <dt>If the node before <var title="">pointer</var> is removed</dt>
3281:
3282: <dd>Let <var title="">pointer</var> be the point between the
3283: node after <var title="">pointer</var> and the node before the
3284: node after <var title="">pointer</var>. In other words, <var title="">pointer</var> doesn't move relative to the remaining
3285: nodes.</dd>
3286:
3287: <dt>If the node after <var title="">pointer</var> is removed</dt>
3288:
3289: <dd>Let <var title="">pointer</var> be the point between the
3290: node before <var title="">pointer</var> and the node after the
3291: node before <var title="">pointer</var>. Just as with the
3292: previous case, <var title="">pointer</var> doesn't move
3293: relative to the remaining nodes.</dd>
3294:
3295: </dl><p>Other changes don't affect <var title="">pointer</var>.</p>
3296:
3297: </li>
3298:
3299: <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
3300: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3301: down to the <i title="">failed</i> step below.</p></li>
3302:
3303: <li><p>⌛ Let <var title="">absolute URL</var> be the
3304: <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>
3305: 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
3306: the <var title="">candidate</var> when the <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute was last
3307: changed.</p>
3308: </li><li><p>⌛ If <var title="">absolute URL</var> was not
3309: obtained successfully, then end the <a href="webappapis.html#synchronous-section">synchronous
3310: section</a>, and jump down to the <i title="">failed</i> step
3311: below.</p></li>
3312:
3313: <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
3314: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3315: described by the <code title="">codecs</code> parameter, for
3316: types that define that parameter), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3317: the user agent knows it cannot render</a>, then end the
3318: <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
3319:
3320: <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
3321: not <a href="common-microsyntaxes.html#matches-the-environment" title="matches the environment">match the
3322: environment</a>, then end the <a href="webappapis.html#synchronous-section">synchronous
3323: section</a>, and jump down to the <i title="">failed</i> step
3324: below.</p></li>
3325:
3326: <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>
3327:
3328: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3329: remaining steps asynchronously.</p></li>
3330:
3331: <li><p>Run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource
3332: fetch algorithm</a> with <var title="">absolute URL</var>. If
3333: that algorithm returns without aborting <em>this</em> one, then
3334: the load failed.</p></li>
3335:
3336: <li><p><i title="">Failed</i>: <a href="webappapis.html#queue-a-task">Queue a task</a> to
3337: <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
3338: obtain <var title="">candidate</var>'s corresponding <a href="#media-resource">media
3339: resource</a> in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3340: algorithm</a>.</p></li>
3341:
3342: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3343: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3344: steps of this algorithm until the algorithm says the
3345: <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
3346: marked with ⌛.)</p></li>
3347:
3348: <li><p>⌛ <a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's
3349: media-resource-specific text tracks</a>.</p></li>
3350:
3351: <li><p>⌛ <i title="">Find next candidate</i>: Let <var title="">candidate</var> be null.</p></li>
3352:
3353: <li><p>⌛ <i title="">Search loop</i>: If the node after
3354: <var title="">pointer</var> is the end of the list, then jump to
3355: the <i title="">waiting</i> step below.</p></li>
3356:
3357: <li><p>⌛ If the node after <var title="">pointer</var> is
3358: a <code><a href="#the-source-element">source</a></code> element, let <var title="">candidate</var>
3359: be that element.</p></li>
3360:
3361: <li><p>⌛ Advance <var title="">pointer</var> so that the
3362: node before <var title="">pointer</var> is now the node that was
3363: after <var title="">pointer</var>, and the node after <var title="">pointer</var> is the node after the node that used to be
3364: after <var title="">pointer</var>, if any.</p></li>
3365:
3366: <li><p>⌛ If <var title="">candidate</var> is null, jump
3367: back to the <i title="">search loop</i> step. Otherwise, jump
3368: back to the <i title="">process candidate</i> step.</p></li>
3369:
3370: <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
3371: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3372: value.</p></li>
3373:
3374: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3375: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3376: event">delaying the load event</a>.</p></li>
3377:
3378: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3379: remaining steps asynchronously.</p></li>
3380:
3381: <li><p>Wait until the node after <var title="">pointer</var> is a
3382: node other than the end of the list. (This step might wait
3383: forever.)</p></li>
3384:
3385: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3386: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3387: steps of this algorithm until the algorithm says the
3388: <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
3389: marked with ⌛.)</p></li>
3390:
3391: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3392: flag</a> back to true (this <a href="the-end.html#delay-the-load-event" title="delay the load
3393: event">delays the load event</a> again, in case it hasn't been
3394: fired yet).</p>
3395:
3396: </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>
3397:
3398: <li><p>⌛ Jump back to the <i title="">find next
3399: candidate</i> step above.</p></li>
3400:
3401: </ol></li>
3402:
3403: </ol><p>The <dfn id="concept-media-load-resource" title="concept-media-load-resource">resource fetch
3404: algorithm</dfn> for a <a href="#media-element">media element</a> and a given
3405: <a href="urls.html#absolute-url">absolute URL</a> is as follows:</p>
3406:
3407: <ol><li><p>Let the <var title="">current media resource</var> be the
3408: resource given by the <a href="urls.html#absolute-url">absolute URL</a> passed to this
3409: algorithm. This is now the element's <a href="#media-resource">media
3410: resource</a>.</p></li>
3411:
1.84 mike 3412: <li><p>Optionally, run the following substeps. This is the expected
3413: behavior if the user agent intends to not attempt to fetch the
3414: resource until the use requests it explicitly (e.g. as a way to
3415: implement the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>
3416: attribute's <code title="attr-media-preload-none"><a href="#attr-media-preload-none">none</a></code>
3417: keyword).</p>
3418:
3419: <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>
3420:
3421: <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
3422: event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the
3423: element.</p></li>
3424:
3425: <li><p>Wait for an implementation-defined event (e.g. the user
3426: requesting that the media element begin playback).</p></li>
3427:
3428: <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>
3429:
3430: </ol></li>
3431:
1.47 mike 3432: <li>
3433:
1.61 mike 3434: <p>Perform a <a href="fetching-resources.html#potentially-cors-enabled-fetch">potentially CORS-enabled fetch</a> of the
3435: <var title="">current media resource</var>'s <a href="urls.html#absolute-url">absolute
3436: URL</a>, with the <i>mode</i> being the state of the
3437: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
3438: attribute, the <i><a href="origin-0.html#origin">origin</a></i> being the <a href="origin-0.html#origin">origin</a> of the
3439: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
3440: <i>default origin behaviour</i> set to <i>taint</i>.</p>
3441:
3442: <p>The resource obtained in this fashion, if any, contains the
3443: <a href="#media-data">media data</a>. It can be <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>
3444: or <a href="fetching-resources.html#cors-cross-origin">CORS-cross-origin</a>; this affects whether subtitles
3445: referenced in the <a href="#media-data">media data</a> are exposed in the API
3446: and, for <code><a href="#the-video-element">video</a></code> elements, whether a
3447: <code><a href="the-canvas-element.html#the-canvas-element">canvas</a></code> gets tainted when the video is drawn on
3448: it.</p>
3449:
1.47 mike 3450: <p>Every 350ms (±200ms) or for every byte received, whichever
3451: is <em>least</em> frequent, <a href="webappapis.html#queue-a-task">queue a task</a> to
3452: <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 element.</p>
3453:
3454: <p>The <dfn id="stall-timeout">stall timeout</dfn> is a user-agent defined length of
3455: time, which should be about three seconds. When a <a href="#media-element">media
3456: element</a> that is actively attempting to obtain <a href="#media-data">media
3457: data</a> has failed to receive any data for a duration equal to
3458: the <a href="#stall-timeout">stall timeout</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a
3459: 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>
3460:
3461: <p>User agents may allow users to selectively block or slow
3462: <a href="#media-data">media data</a> downloads. When a <a href="#media-element">media
3463: element</a>'s download has been blocked altogether, the user
3464: agent must act as if it was stalled (as opposed to acting as if
3465: the connection was closed). The rate of the download may also be
3466: throttled automatically by the user agent, e.g. to balance the
3467: download with other connections sharing the same bandwidth.</p>
3468:
3469: <p>User agents may decide to not download more content at any
3470: time, e.g. after buffering five minutes of a one hour media
3471: resource, while waiting for the user to decide whether to play the
3472: resource or not, or while waiting for user input in an interactive
3473: resource. When a <a href="#media-element">media element</a>'s download has been
3474: suspended, the user agent must 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#queue-a-task">queue
3475: a task</a> to <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 element. If and
3476: when downloading of the resource resumes, the user agent must set
3477: the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3478: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p>
3479:
3480: <p class="note">The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute provides a
3481: hint regarding how much buffering the author thinks is advisable,
3482: even in the absence of the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute.</p>
3483:
3484: <p>When a user agent decides to completely stall a download,
3485: e.g. if it is waiting until the user starts playback before
3486: downloading any further content, the element's
3487: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> must be set to
3488: false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the
3489: load event</a>.</p>
3490:
3491: <p>The user agent may use whatever means necessary to fetch the
3492: resource (within the constraints put forward by this and other
3493: specifications); for example, reconnecting to the server in the
3494: face of network errors, using HTTP range retrieval requests, or
3495: switching to a streaming protocol. The user agent must consider a
3496: resource erroneous only if it has given up trying to fetch it.</p>
3497:
3498: <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
3499: being fetched must, when appropriate, include the relevant
3500: substeps from the following list:</p>
3501:
3502: <dl class="switch"><dt>If the <a href="#media-data">media data</a> cannot be fetched at all, due
3503: to network errors, causing the user agent to give up trying to
3504: fetch the resource</dt>
3505:
3506: <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
3507: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3508: described by the <code title="">codecs</code> parameter, if the
3509: parameter is defined for that type), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3510: the user agent knows it cannot render</a> (even if the actual
3511: <a href="#media-data">media data</a> is in a supported format)</dt>
3512:
3513: <dt>If the <a href="#media-data">media data</a> can be fetched but is found by
3514: inspection to be in an unsupported format, or can otherwise not
3515: be rendered at all</dt>
3516:
3517: <dd>
3518:
3519: <p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in
3520: other protocols), and other fatal network errors that occur
3521: before the user agent has established whether the <var title="">current media resource</var> is usable, as well as
3522: the file using an unsupported container format, or using
3523: unsupported codecs for all the data, must cause the user agent
3524: to execute the following steps:</p>
3525:
3526: <ol><li><p>The user agent should cancel the fetching
3527: process.</p></li>
3528:
3529: <li><p>Abort this subalgorithm, returning to the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3530: algorithm</a>.</p>
3531:
3532: </li></ol></dd>
3533:
3534:
3535:
3536:
3537:
3538: <dt id="getting-media-metadata">Once enough of the <a href="#media-data">media
3539: data</a> has been fetched to determine the duration of the
3540: <a href="#media-resource">media resource</a>, its dimensions, and other
3541: metadata,
3542: and once <a href="#the-text-tracks-are-ready">the text tracks are ready</a>
3543: </dt>
3544:
3545: <dd>
3546:
3547: <p>This indicates that the resource is usable. The user agent
3548: must follow these substeps:</p>
3549:
3550: <ol><li>
3551:
3552: <p><a href="#defineTimeline">Establish the media timeline</a> for the purposes
3553: of the <a href="#current-playback-position">current playback position</a>, the
3554: <a href="#earliest-possible-position">earliest possible position</a>, and the <a href="#initial-playback-position">initial
3555: playback position</a>, based on the <a href="#media-data">media
3556: data</a>.</p>
3557:
3558: </li>
3559:
3560: <li>
3561:
3562: <p>Update the <a href="#timeline-offset">timeline offset</a> to the date and
3563: time that corresponds to the zero time in the <a href="#media-timeline">media
3564: timeline</a> established in the previous step, if any. If
3565: no explicit time and date is given by the <a href="#media-resource">media
3566: resource</a>, the <a href="#timeline-offset">timeline offset</a> must be set
3567: to Not-a-Number (NaN).</p>
3568:
3569: </li>
3570:
3571: <li><p>Set the <a href="#current-playback-position">current playback position</a> to the
3572: <a href="#earliest-possible-position">earliest possible position</a>.</p></li>
3573:
3574: <li>
3575:
3576: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3577: attribute with the time of the last frame of the resource, if
3578: known, on the <a href="#media-timeline">media timeline</a> established above.
3579: If it is not known (e.g. a stream that is in principle
3580: infinite), update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute to the
3581: value positive Infinity.</p>
3582:
3583: <p class="note">The user agent <a href="#durationChange">will</a> <a href="webappapis.html#queue-a-task">queue a task</a> to
3584: <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
3585: element at this point.</p>
3586:
3587: </li>
3588:
3589: <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>
3590: attributes.</p></li>
3591:
3592: <li>
3593:
3594: <p>Set the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to
3595: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>.</p>
3596:
3597: <p class="note">A <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> DOM
3598: event <a href="#fire-loadedmetadata">will be fired</a> as part
3599: of setting the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to a
3600: new value.</p>
3601:
3602:
3603:
3604: </li>
3605:
3606: <li><p>Let <var title="">jumped</var> be false.</p></li>
3607:
3608: <li>
3609:
3610: <p>If either the <a href="#media-resource">media resource</a> or the address of
3611: the <var title="">current media resource</var> indicate a
3612: particular start time, then set the <a href="#initial-playback-position">initial playback
3613: position</a> to that time, <a href="#dom-media-seek" title="dom-media-seek">seek</a> to that time, and let <var title="">jumped</var> be true. Ignore any resulting exceptions
3614: (if the position is out of range, it is effectively
3615: ignored).</p>
3616:
3617: <p class="example">For example, with media formats that
3618: support the <cite>Media Fragments URI</cite> fragment
3619: identifier syntax, the fragment identifier can be used to
3620: indicate a start position. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
3621:
3622: </li>
3623:
1.74 mike 3624: <li>
3625:
3626: <p>If either the <a href="#media-resource">media resource</a> or the address of
3627: the <var title="">current media resource</var> indicate a
3628: particular set of audio or video tracks to enable, then the
3629: 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,
3630: of the selected video tracks, the one that is listed first in
3631: the element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> object must
3632: be selected.</p>
3633:
3634: </li>
1.47 mike 3635:
3636: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
3637: media controller</a>, then: if <var title="">jumped</var> is
3638: true and the <a href="#initial-playback-position">initial playback position</a>, relative
3639: to the <a href="#current-media-controller">current media controller</a>'s timeline, is
3640: greater than the <a href="#current-media-controller">current media controller</a>'s
3641: <a href="#media-controller-position">media controller position</a>, then <a href="#seek-the-media-controller">seek the
3642: media controller</a> to the <a href="#media-element">media element</a>'s
3643: <a href="#initial-playback-position">initial playback position</a>, relative to the
3644: <a href="#current-media-controller">current media controller</a>'s timeline; otherwise,
3645: <a href="#dom-media-seek" title="dom-media-seek">seek</a> the <a href="#media-element">media
3646: element</a> to the <a href="#media-controller-position">media controller position</a>,
3647: relative to the <a href="#media-element">media element</a>'s timeline,
3648: discarding any resulting exceptions.</p></li>
3649: <li>
3650:
3651: <p>Once the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
3652: reaches <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
3653: <a href="#fire-loadeddata">after the <code title="event-media-loadeddata">loadeddata</code> event has been
3654: fired</a>, set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3655: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3656: event">delaying the load event</a>.</p>
3657:
3658: <p class="note">A user agent that is attempting to reduce
3659: network usage while still fetching the metadata for each
3660: <a href="#media-resource">media resource</a> would also stop buffering at this
3661: point, causing the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute
3662: to switch to the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> value.</p>
3663:
3664: </li>
3665:
3666: </ol><p class="note">The user agent is <em>required</em> to
3667: determine the duration of the <a href="#media-resource">media resource</a> and
3668: go through this step before playing.</p>
3669: </dd>
3670:
3671:
3672: <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
3673: has been decoded)</dt>
3674:
3675: <dd>
3676:
3677: <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>
3678: named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the
3679: <a href="#media-element">media element</a>.</p>
3680:
3681: </dd>
3682:
3683:
1.84 mike 3684: <dt>If the connection is interrupted after some <a href="#media-data">media data</a> has been received, causing the user agent to
1.47 mike 3685: give up trying to fetch the resource</dt>
3686:
3687: <dd>
3688:
3689: <p>Fatal network errors that occur after the user agent has
3690: established whether the <var title="">current media
1.84 mike 3691: resource</var> is usable (i.e. once the <a href="#media-element">media
3692: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is no
3693: longer <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>)
3694: must cause the user agent to execute the following steps:</p>
1.47 mike 3695:
3696: <ol><li><p>The user agent should cancel the fetching
3697: process.</p></li>
3698:
3699: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3700: 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
3701: <code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code>.</p></li>
3702:
3703: <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
3704: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3705: at the <a href="#media-element">media element</a>.</p></li>
3706:
1.84 mike 3707: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3708: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3709: value.</p></li>
3710:
3711: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3712: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3713: event">delaying the load event</a>.</p></li>
3714:
3715: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3716: algorithm</a>.</p></li>
3717:
3718: </ol></dd>
3719:
3720:
3721: <dt id="fatal-decode-error">If the <a href="#media-data">media data</a> is
3722: corrupted</dt>
3723:
3724: <dd>
3725:
3726: <p>Fatal errors in decoding the <a href="#media-data">media data</a> that
3727: occur after the user agent has established whether the <var title="">current media resource</var> is usable must cause the
3728: user agent to execute the following steps:</p>
3729:
3730: <ol><li><p>The user agent should cancel the fetching
3731: process.</p></li>
3732:
3733: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3734: 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
3735: <code title="dom-MediaError-MEDIA_ERR_DECODE"><a href="#dom-mediaerror-media_err_decode">MEDIA_ERR_DECODE</a></code>.</p></li>
3736:
3737: <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
3738: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3739: at the <a href="#media-element">media element</a>.</p></li>
3740:
3741: <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
3742: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3743: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3744: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3745: value and <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3746: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3747: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3748: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3749: value.</p></li>
3750:
3751: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3752: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3753: event">delaying the load event</a>.</p></li>
3754:
3755: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3756: algorithm</a>.</p></li>
3757:
3758: </ol></dd>
3759:
3760:
3761: <dt>If the <a href="#media-data">media data</a> fetching process is aborted by
3762: the user</dt>
3763:
3764: <dd>
3765:
3766: <p>The fetching process is aborted by the user, e.g. because the
3767: user navigated the browsing context to another page, the user
3768: agent must execute the following steps. These steps are not
3769: followed if the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code>
3770: method itself is invoked while these steps are running, as the
3771: steps above handle that particular kind of abort.</p>
3772:
3773: <ol><li><p>The user agent should cancel the fetching
3774: process.</p></li>
3775:
3776: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3777: 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
3778: <code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.</p></li>
3779:
3780: <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
3781: event</a> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code>
3782: at the <a href="#media-element">media element</a>.</p></li>
3783:
3784: <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
3785: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3786: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3787: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3788: value and <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3789: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3790: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3791: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3792: value.</p></li>
3793:
3794: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3795: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3796: event">delaying the load event</a>.</p></li>
3797:
3798: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3799: algorithm</a>.</p></li>
3800:
3801: </ol></dd>
3802:
3803:
3804: <dt id="non-fatal-media-error">If the <a href="#media-data">media data</a> can
3805: be fetched but has non-fatal errors or uses, in part, codecs that
3806: are unsupported, preventing the user agent from rendering the
3807: content completely correctly but not preventing playback
3808: altogether</dt>
3809:
3810: <dd>
3811:
3812: <p>The server returning data that is partially usable but cannot
3813: be optimally rendered must cause the user agent to render just
3814: the bits it can handle, and ignore the rest.</p>
3815:
3816:
3817:
3818: </dd>
3819:
3820:
3821: <dt id="found-a-media-resource-specific-timed-track">If the <a href="#media-resource">media resource</a> is found to declare a <a href="#media-resource-specific-text-track">media-resource-specific text track</a> that the user agent supports</dt>
3822:
3823: <dd>
3824:
1.61 mike 3825: <p>If the <a href="#media-data">media data</a> is
3826: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>, <a href="webappapis.html#queue-a-task">queue a task</a> to run
3827: the <a href="#steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text
3828: track</a> with the relevant data.</p>
3829:
3830: <p class="note">Cross-origin videos do not expose their
3831: subtitles, since that would allow attacks such as hostile sites
3832: reading subtitles from confidential videos on a user's
3833: intranet.</p>
1.47 mike 3834:
3835: </dd>
3836:
3837: </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>
3838: (i.e. once the download has completed), if the fetching process
3839: completes without errors, including decoding the media data, and
3840: if all of the data is available to the user agent without network
3841: access, then, the user agent must move on to the next step. This
3842: might never happen, e.g. when streaming an infinite resource such
3843: as Web radio, or if the resource is longer than the user agent's
3844: ability to cache data.</p>
3845:
3846: <p>While the user agent might still need network access to obtain
3847: parts of the <a href="#media-resource">media resource</a>, the user agent must
3848: remain on this step.</p>
3849:
3850: <p class="example">For example, if the user agent has discarded
3851: the first half of a video, the user agent will remain at this step
3852: even once the <a href="#ended-playback" title="ended playback">playback has
3853: ended</a>, because there is always the chance the user will
3854: 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.64 mike 3855: will end up firing a <code title="event-media-stalled"><a href="#event-media-stalled">stalled</a></code> event, as described
1.47 mike 3856: earlier.</p>
3857:
3858: </li>
3859:
3860: <li><p>If the user agent ever reaches this step (which can only
3861: happen if the entire resource gets loaded and kept available):
3862: abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3863: algorithm</a>.</p></li>
3864:
3865: </ol></div><hr><p>The <dfn id="attr-media-preload" title="attr-media-preload"><code>preload</code></dfn>
3866: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following table
3867: lists the keywords and states for the attribute — the keywords
3868: in the left column map to the states in the cell in the second
3869: column on the same row as the keyword.</p><table><thead><tr><th> Keyword
3870: </th><th> State
3871: </th><th> Brief description
3872: </th></tr></thead><tbody><tr><td><dfn id="attr-media-preload-none" title="attr-media-preload-none"><code>none</code></dfn>
3873: </td><td><dfn id="attr-media-preload-none-state" title="attr-media-preload-none-state">None</dfn>
3874: </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.
3875: </td></tr><tr><td><dfn id="attr-media-preload-metadata" title="attr-media-preload-metadata"><code>metadata</code></dfn>
3876: </td><td><dfn id="attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</dfn>
1.62 mike 3877: </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 3878: </td></tr><tr><td><dfn id="attr-media-preload-auto" title="attr-media-preload-auto"><code>auto</code></dfn>
3879: </td><td><dfn id="attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</dfn>
3880: </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.
3881: </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
3882: attribute's <i>missing value default</i> is user-agent defined,
3883: though the <a href="#attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</a> state is
3884: suggested as a compromise between reducing server load and providing
3885: an optimal user experience.</p><div class="impl">
3886:
3887: <p>The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute is
3888: intended to provide a hint to the user agent about what the author
3889: thinks will lead to the best user experience. The attribute may be
3890: ignored altogether, for example based on explicit user preferences
3891: or based on the available connectivity.</p>
3892:
3893: <p>The <dfn id="dom-media-preload" title="dom-media-preload"><code>preload</code></dfn> IDL
3894: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
3895: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
3896:
3897: </div><p class="note">The <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute can override
3898: the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute (since
3899: if the media plays, it naturally has to buffer first, regardless of
3900: the hint given by the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute). Including
3901: 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>
3902:
3903: <dd>
3904:
3905: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
3906: ranges of the <a href="#media-resource">media resource</a> that the user agent has
3907: buffered.</p>
3908:
3909: </dd>
3910:
3911: </dl><div class="impl">
3912:
3913: <p>The <dfn id="dom-media-buffered" title="dom-media-buffered"><code>buffered</code></dfn>
3914: attribute must return a new static <a href="#normalized-timeranges-object">normalized
3915: <code>TimeRanges</code> object</a> that represents the ranges of
3916: the <a href="#media-resource">media resource</a>, if any, that the user agent has
3917: buffered, at the time the attribute is evaluated. Users agents must
3918: accurately determine the ranges available, even for media streams
3919: where this can only be determined by tedious inspection.</p>
3920:
3921: <p class="note">Typically this will be a single range anchored at
3922: the zero point, but if, e.g. the user agent uses HTTP range requests
3923: in response to seeking, then there could be multiple ranges.</p>
3924:
3925: <p>User agents may discard previously buffered data.</p>
3926:
3927: <p class="note">Thus, a time position included within a range of the
3928: objects return by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code> attribute at one time can
3929: end up being not included in the range(s) of objects returned by the
3930: same attribute at later times.</p>
3931:
3932: </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>
3933:
3934: <dd>
3935:
3936: <p>Returns the length of the <a href="#media-resource">media resource</a>, in
3937: seconds, assuming that the start of the <a href="#media-resource">media
3938: resource</a> is at time zero.</p>
3939:
3940: <p>Returns NaN if the duration isn't available.</p><p>
3941:
3942: </p><p>Returns Infinity for unbounded streams.</p>
3943:
3944: </dd>
3945:
3946: <dt><var title="">media</var> . <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
3947:
3948: <dd>
3949:
3950: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds.</p>
3951:
3952: <p>Can be set, to seek to the given time.</p><p>
3953:
1.78 mike 3954: </p><p>Will throw an <code><a href="infrastructure.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception if there
1.47 mike 3955: is no selected <a href="#media-resource">media resource</a>
1.71 mike 3956: or if there is a <a href="#current-media-controller">current media controller</a>.</p>
1.47 mike 3957:
3958: </dd>
3959:
3960: <dt><var title="">media</var> . <code title="dom-media-initialTime"><a href="#dom-media-initialtime">initialTime</a></code></dt>
3961:
3962: <dd>
3963:
3964: <p>Returns the <a href="#initial-playback-position">initial playback position</a>, that is, time
3965: to which the <a href="#media-resource">media resource</a> was automatically seeked
3966: when it was loaded. Returns zero if the <a href="#initial-playback-position">initial playback
3967: position</a> is still unknown.</p>
3968:
3969: </dd>
3970:
3971: </dl><div class="impl">
3972:
3973: <p>A <a href="#media-resource">media resource</a> has a <dfn id="media-timeline">media timeline</dfn>
3974: that maps times (in seconds) to positions in the <a href="#media-resource">media
3975: resource</a>. The origin of a timeline is its earliest defined
3976: position. The duration of a timeline is its last defined
3977: position.</p>
3978:
3979: <p><dfn id="defineTimeline" title="establish the media
3980: timeline">Establishing the media timeline</dfn>: If the <a href="#media-resource">media
3981: resource</a> somehow specifies an explicit timeline whose origin
3982: is not negative, then the <a href="#media-timeline">media timeline</a> should be that
3983: timeline. (Whether the <a href="#media-resource">media resource</a> can specify a
3984: timeline or not depends on the <a href="#media-resource" title="media resource">media
3985: resource's</a> format.) If the <a href="#media-resource">media resource</a>
3986: specifies an explicit start time <em>and date</em>, then that time
3987: and date should be considered the zero point in the <a href="#media-timeline">media
3988: timeline</a>; the <a href="#timeline-offset">timeline offset</a> will be the time
3989: and date, exposed using the <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
3990: attribute.</p>
3991:
3992: <p>If the <a href="#media-resource">media resource</a> has a discontinuous timeline,
3993: the user agent must extend the timeline used at the start of the
3994: resource across the entire resource, so that the <a href="#media-timeline">media
3995: timeline</a> of the <a href="#media-resource">media resource</a> increases
3996: linearly starting from the <a href="#earliest-possible-position">earliest possible position</a>
3997: (as defined below), even if the underlying <a href="#media-data">media data</a>
3998: has out-of-order or even overlapping time codes.</p>
3999:
4000: <p class="example">For example, if two clips have been concatenated
4001: into one video file, but the video format exposes the original times
4002: for the two clips, the video data might expose a timeline that goes,
4003: say, 00:15..00:29 and then 00:05..00:38. However, the user agent
4004: would not expose those times; it would instead expose the times as
4005: 00:15..00:29 and 00:29..01:02, as a single video.</p>
4006:
4007: <p>In the absence of an explicit timeline, the zero time on the
4008: <a href="#media-timeline">media timeline</a> should correspond to the first frame of
4009: the <a href="#media-resource">media resource</a>. For static audio and video files
4010: this is generally trivial. For streaming resources, if the user
4011: agent will be able to seek to an earlier point than the first frame
4012: originally provided by the server, then the zero time should
4013: correspond to the earliest seekable time of the <a href="#media-resource">media
4014: resource</a>; otherwise, it should correspond to the first frame
4015: received from the server (the point in the <a href="#media-resource">media
4016: resource</a> at which the user agent began receiving the
4017: stream).</p>
4018:
4019: <p class="example">Another example would be a stream that carries a
4020: video with several concatenated fragments, broadcast by a server
4021: that does not allow user agents to request specific times but
4022: instead just streams the video data in a predetermined order. If a
4023: user agent connects to this stream and receives fragments defined as
4024: covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
4025: UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
4026: expose this with a <a href="#media-timeline">media timeline</a> starting at 0s and
4027: extending to 3,600s (one hour). Assuming the streaming server
4028: 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
4029: return 3,600. The <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code> attribute
4030: would return a <code>Date</code> object with a time corresponding to
4031: 2010-03-20 23:15:00 UTC. However, if a different user agent
4032: connected five minutes later, <em>it</em> would (presumably) receive
4033: fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
4034: 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
4035: and would expose this with a <a href="#media-timeline">media timeline</a> starting at
4036: 0s and extending to 3,300s (fifty five minutes). In this case, the
4037: <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
4038: attribute would return a <code>Date</code> object with a time
4039: corresponding to 2010-03-20 23:20:00 UTC.</p>
4040:
4041: <p>In any case, the user agent must ensure that the <a href="#earliest-possible-position">earliest
4042: possible position</a> (as defined below) using the established
4043: <a href="#media-timeline">media timeline</a>, is greater than or equal to zero.</p>
4044:
4045: <p>The <a href="#media-timeline">media timeline</a> also has an associated clock.
4046: Which clock is used is user-agent defined, and may be <a href="#media-resource">media
4047: resource</a>-dependent, but it should approximate the user's wall
4048: clock.</p>
4049:
4050: <p class="note">All the <a href="#media-element" title="media element">media
4051: elements</a> that share <a href="#current-media-controller">current media controller</a> use
4052: the same clock for their <a href="#media-timeline">media timeline</a>.</p>
4053:
4054: <p><a href="#media-element" title="media element">Media elements</a> have a
4055: <dfn id="current-playback-position">current playback position</dfn>, which must initially (i.e. in
4056: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4057: <a href="#current-playback-position">current playback position</a> is a time on the <a href="#media-timeline">media
4058: timeline</a>.</p>
4059:
4060: <p>The <dfn id="dom-media-currenttime" title="dom-media-currentTime"><code>currentTime</code></dfn>
4061: attribute must, on getting, return the <a href="#current-playback-position">current playback
4062: position</a>, expressed in seconds. On setting,
4063: if the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4064: controller</a>, then it must throw an
1.78 mike 4065: <code><a href="infrastructure.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception; otherwise,
1.47 mike 4066: the user agent
4067: must <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the new value
4068: (which might raise an exception).</p>
4069:
4070: <p><a href="#media-element" title="media element">Media elements</a> have an
4071: <dfn id="initial-playback-position">initial playback position</dfn>, which must initially (i.e. in
4072: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4073: <a href="#initial-playback-position">initial playback position</a> is updated when a <a href="#media-resource">media
4074: resource</a> is loaded. The <a href="#initial-playback-position">initial playback
4075: position</a> is a time on the <a href="#media-timeline">media timeline</a>.</p>
4076:
1.50 mike 4077: <p>The <dfn id="dom-media-initialtime" title="dom-media-initialTime"><code>initialTime</code></dfn>
1.47 mike 4078: attribute must, on getting, return the <a href="#initial-playback-position">initial playback
4079: position</a>, expressed in seconds.</p>
4080:
4081: <p>If the <a href="#media-resource">media resource</a> is a streaming resource, then
4082: the user agent might be unable to obtain certain parts of the
4083: resource after it has expired from its buffer. Similarly, some <a href="#media-resource" title="media resource">media resources</a> might have a
4084: <a href="#media-timeline">media timeline</a> that doesn't start at zero. The
4085: <dfn id="earliest-possible-position">earliest possible position</dfn> is the earliest position in
4086: the stream or resource that the user agent can ever obtain
4087: again. It is also a time on the <a href="#media-timeline">media timeline</a>.</p>
4088:
4089: <p class="note">The <a href="#earliest-possible-position">earliest possible position</a> is not
4090: explicitly exposed in the API; it corresponds to the start time of
4091: the first range in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute's
4092: <code><a href="#timeranges">TimeRanges</a></code> object, if any, or the <a href="#current-playback-position">current
4093: playback position</a> otherwise.</p>
4094:
4095: <p>When the <a href="#earliest-possible-position">earliest possible position</a> changes, then:
4096: if the <a href="#current-playback-position">current playback position</a> is before the
4097: <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
4098: 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
4099: element in the past 15 to 250ms and is not still running event
4100: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4101: 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>
4102:
4103: <p class="note">Because of the above requirement and the requirement
4104: in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
4105: algorithm</a> that kicks in <a href="#getting-media-metadata">when the metadata of the clip becomes
4106: known</a>, the <a href="#current-playback-position">current playback position</a> can never be
4107: less than the <a href="#earliest-possible-position">earliest possible position</a>.</p>
4108:
4109: <p>The <dfn id="dom-media-duration" title="dom-media-duration"><code>duration</code></dfn>
4110: attribute must return the time of the end of the <a href="#media-resource">media
4111: resource</a>, in seconds, on the <a href="#media-timeline">media timeline</a>. If
4112: no <a href="#media-data">media data</a> is available, then the attributes must
4113: return the Not-a-Number (NaN) value. If the <a href="#media-resource">media
1.62 mike 4114: resource</a> is not known to be bounded (e.g. streaming radio, or
4115: a live event with no announced end time), then the attribute must
4116: return the positive Infinity value.</p>
1.47 mike 4117:
4118: <p>The user agent must determine the duration of the <a href="#media-resource">media
4119: resource</a> before playing any part of the <a href="#media-data">media
4120: data</a> and before setting <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> to a value equal to
4121: or greater than <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, even if doing
4122: so requires fetching multiple parts of the resource.</p>
4123:
4124: <p id="durationChange">When the length of the <a href="#media-resource">media
4125: resource</a> changes to a known value (e.g. from being unknown to
4126: known, or from a previously established length to a new length) the
4127: 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
4128: event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
4129: <a href="#media-element">media element</a>. (The event is not fired when the
1.63 mike 4130: duration is reset as part of loading a new media resource.) If the
4131: duration is changed such that the <a href="#current-playback-position">current playback
4132: position</a> ends up being greater than the time of the end of
4133: 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
4134: <a href="#media-resource">media resource</a>.</p>
1.47 mike 4135:
4136: <p class="example">If an "infinite" stream ends for some reason,
4137: then the duration would change from positive Infinity to the time of
4138: 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
4139: be fired. Similarly, if the user agent initially estimated the
4140: <a href="#media-resource">media resource</a>'s duration instead of determining it
4141: precisely, and later revises the estimate based on new information,
4142: then the duration would change and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
4143: be fired.</p>
4144:
4145: <p>Some video files also have an explicit date and time
4146: corresponding to the zero time in the <a href="#media-timeline">media timeline</a>,
4147: known as the <dfn id="timeline-offset">timeline offset</dfn>. Initially, the
4148: <a href="#timeline-offset">timeline offset</a> must be set to Not-a-Number (NaN).</p>
4149:
4150: <p>The <dfn id="dom-media-startoffsettime" title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
4151: attribute must return a new <code>Date</code> object representing
4152: the current <a href="#timeline-offset">timeline offset</a>.</p>
4153:
4154: </div><hr><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn>
4155: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that, if specified,
4156: indicates that the <a href="#media-element">media element</a> is to seek back to the
4157: 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
4158: effect while the element has a <a href="#current-media-controller">current media
4159: controller</a>.</p><div class="impl">
4160:
4161: <p>The <dfn id="dom-media-loop" title="dom-media-loop"><code>loop</code></dfn> IDL
4162: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4163: same name.</p>
4164:
1.65 mike 4165: </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 4166:
4167: <dd>
4168:
4169: <p>Returns a value that expresses the current state of the element
4170: with respect to rendering the <a href="#current-playback-position">current playback
4171: position</a>, from the codes in the list below.</p>
4172:
4173: </dd>
4174:
4175: </dl><div class="impl">
4176:
4177: <p><a href="#media-element" title="media element">Media elements</a> have a
4178: <i>ready state</i>, which describes to what degree they are ready
4179: to be rendered at the <a href="#current-playback-position">current playback position</a>. The
4180: possible values are as follows; the ready state of a media element
4181: at any particular time is the greatest value describing the state of
4182: the element:</p>
4183:
4184: </div><dl><dt><dfn id="dom-media-have_nothing" title="dom-media-HAVE_NOTHING"><code>HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
4185:
4186: <dd>No information regarding the <a href="#media-resource">media resource</a> is
4187: available. No data for the <a href="#current-playback-position">current playback position</a>
4188: is available. <a href="#media-element" title="media element">Media elements</a>
4189: whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code>
4190: attribute are set to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> are always in
4191: the <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>
4192: state.</dd>
4193:
4194: <dt><dfn id="dom-media-have_metadata" title="dom-media-HAVE_METADATA"><code>HAVE_METADATA</code></dfn> (numeric value 1)</dt>
4195:
4196: <dd>Enough of the resource has been obtained that the duration of
4197: the resource is available. In the case of a <code><a href="#the-video-element">video</a></code>
4198: element, the dimensions of the video are also available. The API
4199: will no longer raise an exception when seeking. No <a href="#media-data">media
4200: data</a> is available for the immediate <a href="#current-playback-position">current playback
4201: position</a>.
4202: The <a href="#text-track" title="text track">text tracks</a>
4203: are <a href="#the-text-tracks-are-ready" title="the text tracks are ready">ready</a>.
4204: </dd>
4205:
4206: <dt><dfn id="dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA"><code>HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
4207:
4208: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4209: is available, but either not enough data is available that the user
4210: agent could successfully advance the <a href="#current-playback-position">current playback
4211: position</a> in the <a href="#direction-of-playback">direction of playback</a> at all
4212: without immediately reverting to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4213: there is no more data to obtain in the <a href="#direction-of-playback">direction of
4214: playback</a>. For example, in video this corresponds to the user
1.62 mike 4215: agent having data from the current frame, but not the next frame,
4216: when the <a href="#current-playback-position">current playback position</a> is at the end of
4217: the current frame; and to when <a href="#ended-playback" title="ended
4218: playback">playback has ended</a>.</dd>
1.47 mike 4219:
4220: <dt><dfn id="dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA"><code>HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
4221:
4222: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4223: is available, as well as enough data for the user agent to advance
4224: the <a href="#current-playback-position">current playback position</a> in the <a href="#direction-of-playback">direction
4225: of playback</a> at least a little without immediately reverting
4226: to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
4227: state. For example, in video this corresponds to the user agent
1.62 mike 4228: having data for at least the current frame and the next frame when
4229: the <a href="#current-playback-position">current playback position</a> is at the instant in
4230: time between the two frames, or to the user agent having the video
4231: data for the current frame and audio data to keep playing at least
4232: a little when the <a href="#current-playback-position">current playback position</a> is in the
4233: middle of a frame. The user agent cannot be in this state if <a href="#ended-playback" title="ended playback">playback has ended</a>, as the
4234: <a href="#current-playback-position">current playback position</a> can never advance in this
4235: case.</dd>
1.47 mike 4236:
4237: <dt><dfn id="dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA"><code>HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
4238:
4239: <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
4240: are met, and, in addition, the user agent estimates that data is
4241: being fetched at a rate where the <a href="#current-playback-position">current playback
4242: position</a>, if it were to advance at the <a href="#effective-playback-rate">effective
4243: playback rate</a>, would not overtake the available data before
4244: playback reaches the end of the <a href="#media-resource">media resource</a>.</dd>
4245:
1.62 mike 4246: </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
4247: negligible. Really the only time the difference is relevant is when
4248: 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>,
4249: 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
4250: 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).
4251: Similarly, the difference between <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> (only
4252: 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
4253: this frame and the next) can be negligible (in the extreme, only one
4254: frame). The only time that distinction really matters is when a page
4255: provides an interface for "frame-by-frame" navigation.</p><div class="impl">
1.47 mike 4256:
4257: <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
4258: user agent must follow the steps given below:</p>
4259:
4260: <ol><li>
4261:
4262: <p>Apply the first applicable set of substeps from the following
4263: list:</p>
4264:
4265:
4266: <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
4267: ready state is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code></dt>
4268:
4269: <dd id="fire-loadedmetadata">
4270:
4271: <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>
4272: named <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> at the
4273: element.</p>
4274:
4275: <p class="note">Before this task is run, as part of the event
4276: loop mechanism, the rendering will have been updated to resize
4277: the <code><a href="#the-video-element">video</a></code> element if appropriate.</p>
4278:
4279: </dd>
4280:
4281:
4282:
4283: <dt id="handling-first-frame-available">If the previous ready state
4284: was <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and
4285: 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
4286: greater</dt>
4287:
4288: <dd>
4289:
4290: <p id="fire-loadeddata">If this is the first time this occurs for
4291: 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,
4292: 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
4293: simple event</a> named <code title="event-media-loadeddata"><a href="#event-media-loadeddata">loadeddata</a></code> at the element.</p>
4294:
4295: <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
4296: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>,
4297: then the relevant steps below must then be run also.</p>
4298:
4299: </dd>
4300:
4301:
4302: <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,
4303: 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
4304: less</dt>
4305:
4306: <dd>
4307:
4308: <p id="fire-waiting-when-waiting">If the <a href="#media-element">media
4309: element</a> was <a href="#potentially-playing">potentially playing</a> before its
4310: <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
4311: 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
4312: the element has not <a href="#ended-playback">ended playback</a>, and playback
4313: has not <a href="#stopped-due-to-errors">stopped due to errors</a>, and playback has not
4314: <a href="#paused-for-user-interaction">paused for user interaction</a>, the user agent must
4315: <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>
4316: named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at
4317: 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
4318: simple event</a> named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the element.</p>
4319:
4320: </dd>
4321:
4322:
4323: <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
4324: 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>
4325:
4326: <dd>
4327:
4328: <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
4329: simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>.</p>
4330:
4331: <p>If the element's <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4332: attribute is false, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
4333: 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>
4334:
4335: </dd>
4336:
4337:
4338: <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>
4339:
4340: <dd>
4341:
4342: <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
4343: 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
4344: a simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>, and, if the element's
4345: <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false,
4346: <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>
4347: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4348:
4349: <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
4350: <a href="#media-element">media element</a> has an <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute specified,
4351: and the <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s
4352: <a href="browsers.html#browsing-context">browsing context</a> did not have the <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed
4353: automatic features browsing context flag</a> set when the
4354: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent may also
4355: set the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute to
4356: false, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4357: event</a> named <code title="event-media-play"><a href="#event-media-play">play</a></code>, and
4358: <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>
4359: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4360:
4361: <p class="note">User agents do not need to support autoplay,
4362: and it is suggested that user agents honor user preferences on the
4363: matter. Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
4364: using script to force the video to play, so as to allow the user
4365: to override the behavior if so desired.</p>
4366:
4367: <p>In any case, the user agent must finally <a href="webappapis.html#queue-a-task">queue a
4368: 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>
4369:
4370: </dd>
4371:
4372: </dl></li>
4373:
4374: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4375: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4376: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4377: controller</a>.</p></li>
4378:
4379: </ol></div><p class="note">It is possible for the ready state of a media
4380: element to jump between these states discontinuously. For example,
4381: 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
4382: passing through the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> and
4383: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>
4384: states.</p><div class="impl">
4385:
4386: <p>The <dfn id="dom-media-readystate" title="dom-media-readyState"><code>readyState</code></dfn> IDL
4387: attribute must, on getting, return the value described above that
4388: describes the current ready state of the <a href="#media-element">media
4389: element</a>.</p>
4390:
4391: </div><p>The <dfn id="attr-media-autoplay" title="attr-media-autoplay"><code>autoplay</code></dfn>
4392: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When present, the
4393: user agent <span class="impl">(as described in the algorithm
4394: described herein)</span> will automatically begin playback of the
4395: <a href="#media-resource">media resource</a> as soon as it can do so without
4396: 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
4397: using script to trigger automatic playback, as this allows the user
4398: to override the automatic playback when it is not desired, e.g. when
4399: using a screen reader. Authors are also encouraged to consider not
4400: using the automatic playback behavior at all, and instead to let the
4401: user agent wait for the user to start playback explicitly.</p><div class="impl">
4402:
4403: <p>The <dfn id="dom-media-autoplay" title="dom-media-autoplay"><code>autoplay</code></dfn>
4404: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4405: same name.</p>
4406:
4407: </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>
4408:
4409: <dd>
4410:
4411: <p>Returns true if playback is paused; false otherwise.</p>
4412:
4413: </dd>
4414:
4415: <dt><var title="">media</var> . <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code></dt>
4416:
4417: <dd>
4418:
4419: <p>Returns true if playback has reached the end of the <a href="#media-resource">media resource</a>.</p>
4420:
4421: </dd>
4422:
4423: <dt><var title="">media</var> . <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
4424:
4425: <dd>
4426:
4427: <p>Returns the default rate of playback, for when the user is not
4428: fast-forwarding or reversing through the <a href="#media-resource">media
4429: resource</a>.</p>
4430:
4431: <p>Can be set, to change the default rate of playback.</p>
4432:
4433: <p>The default rate has no direct effect on playback, but if the
4434: user switches to a fast-forward mode, when they return to the
4435: normal playback mode, it is expected that the rate of playback
4436: will be returned to the default rate of playback.</p>
4437:
4438: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4439: the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
4440: attribute is ignored and the <a href="#current-media-controller">current media
4441: controller</a>'s <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code>
4442: is used instead.</p>
4443:
4444: </dd>
4445:
4446: <dt><var title="">media</var> . <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
4447:
4448: <dd>
4449:
4450: <p>Returns the current rate playback, where 1.0 is normal speed.</p>
4451:
4452: <p>Can be set, to change the rate of playback.</p>
4453:
4454: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4455: the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>
4456: attribute is ignored and the <a href="#current-media-controller">current media
4457: controller</a>'s <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> is
4458: used instead.</p>
4459:
4460: </dd>
4461:
4462: <dt><var title="">media</var> . <code title="dom-media-played"><a href="#dom-media-played">played</a></code></dt>
4463:
4464: <dd>
4465:
4466: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4467: ranges of the <a href="#media-resource">media resource</a> that the user agent has
4468: played.</p>
4469:
4470: </dd>
4471:
4472: <dt><var title="">media</var> . <code title="dom-media-play"><a href="#dom-media-play">play</a></code>()</dt>
4473:
4474: <dd>
4475:
4476: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4477: to false, loading the <a href="#media-resource">media resource</a> and beginning
4478: playback if necessary. If the playback had ended, will restart it
4479: from the start.</p>
4480:
4481: </dd>
4482:
4483: <dt><var title="">media</var> . <code title="dom-media-pause"><a href="#dom-media-pause">pause</a></code>()</dt>
4484:
4485: <dd>
4486:
4487: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4488: to true, loading the <a href="#media-resource">media resource</a> if necessary.</p>
4489:
4490: </dd>
4491:
4492: </dl><div class="impl">
4493:
4494: <p>The <dfn id="dom-media-paused" title="dom-media-paused"><code>paused</code></dfn>
4495: attribute represents whether the <a href="#media-element">media element</a> is
4496: paused or not. The attribute must initially be true.</p>
4497:
4498: <p>A <a href="#media-element">media element</a> is a <dfn id="blocked-media-element">blocked media
4499: element</dfn> if its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is in the
1.62 mike 4500: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> state, the
4501: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4502: the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> state,
4503: or if the element has <a href="#paused-for-user-interaction">paused for user interaction</a>.</p>
1.47 mike 4504:
4505: <p>A <a href="#media-element">media element</a> is said to be <dfn id="potentially-playing">potentially
4506: playing</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4507: attribute is false, the element has not <a href="#ended-playback">ended playback</a>,
4508: playback has not <a href="#stopped-due-to-errors">stopped due to errors</a>,
4509: the element either has no <a href="#current-media-controller">current media controller</a> or
4510: has a <a href="#current-media-controller">current media controller</a> but is not <a href="#blocked-on-its-media-controller">blocked
4511: on its media controller</a>,
4512: and the element is not a <a href="#blocked-media-element">blocked media element</a>.</p>
4513:
4514: <p>A <a href="#media-element">media element</a> is said to have <dfn id="ended-playback">ended
4515: playback</dfn> when:</p>
4516:
4517: <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,
4518: and
4519:
4520: </li><li>
4521:
4522: <p>Either:
4523:
4524: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the end of the
4525: <a href="#media-resource">media resource</a>, and
4526:
4527: </li><li>The <a href="#direction-of-playback">direction of playback</a> is forwards, and
4528:
4529: </li><li>
4530: Either
4531: 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,
4532: or the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4533: controller</a>.
4534:
4535: </li></ul><p>Or:
4536:
4537: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the
4538: <a href="#earliest-possible-position">earliest possible position</a>, and
4539:
4540: </li><li>The <a href="#direction-of-playback">direction of playback</a> is backwards.
4541:
4542: </li></ul></li>
4543:
4544: </ul><p>The <dfn id="dom-media-ended" title="dom-media-ended"><code>ended</code></dfn>
4545: attribute must return true if the <a href="#media-element">media element</a> has
4546: <a href="#ended-playback">ended playback</a> and the <a href="#direction-of-playback">direction of
4547: playback</a> is forwards, and false otherwise.</p>
4548:
4549: <p>A <a href="#media-element">media element</a> is said to have <dfn id="stopped-due-to-errors">stopped due to
4550: 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
4551: the user agent <a href="#non-fatal-media-error">encounters a
4552: non-fatal error</a> during the processing of the <a href="#media-data">media
4553: data</a>, and due to that error, is not able to play the content
4554: at the <a href="#current-playback-position">current playback position</a>.</p>
4555:
4556: <p>A <a href="#media-element">media element</a> is said to have <dfn id="paused-for-user-interaction">paused for user
4557: 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
4558: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4559: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> and
4560: the user agent has reached a point in the <a href="#media-resource">media
4561: resource</a> where the user has to make a selection for the
4562: resource to continue.
4563: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4564: controller</a> when this happens, then the user agent must
4565: <a href="#report-the-controller-state">report the controller state</a> for the <a href="#media-element">media
4566: element</a>'s <a href="#current-media-controller">current media controller</a>. If If the
4567: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4568: controller</a> when the user makes a selection, allowing playback
4569: to resume, the user agent must similarly <a href="#report-the-controller-state">report the controller
4570: state</a> for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current
4571: media controller</a>.
4572: </p>
4573:
4574: <p>It is possible for a <a href="#media-element">media element</a> to have both
4575: <a href="#ended-playback">ended playback</a> and <a href="#paused-for-user-interaction">paused for user
4576: interaction</a> at the same time.</p>
4577:
4578: <p>When a <a href="#media-element">media element</a> that is <a href="#potentially-playing">potentially
4579: playing</a> stops playing because it has <a href="#paused-for-user-interaction">paused for user
4580: interaction</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
4581: <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>
4582:
4583: <p class="note">A <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code>
4584: DOM event <a href="#fire-waiting-when-waiting">can be fired</a> as a
4585: result of an element that is <a href="#potentially-playing">potentially playing</a>
4586: stopping playback due to its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute changing to
4587: a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.</p>
4588:
4589: <p>When the <a href="#current-playback-position">current playback position</a> reaches the end
4590: of the <a href="#media-resource">media resource</a> when the <a href="#direction-of-playback">direction of
4591: playback</a> is forwards, then the user agent must follow these
4592: steps:</p>
4593:
4594: <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
4595: and does not have a <a href="#current-media-controller">current media controller</a>,
4596: then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4597: possible position</a> of the <a href="#media-resource">media resource</a> and
4598: abort these steps.</p></li>
4599: <li><p>Stop playback.</p><p class="note">The <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> attribute becomes
4600: true.</p></li>
4601:
4602: <li><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
4603: a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
4604:
4605: <li><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
4606: a simple event</a> named <code title="event-media-ended"><a href="#event-media-ended">ended</a></code>
4607: at the element.</p></li>
4608:
4609: </ol><p>When the <a href="#current-playback-position">current playback position</a> reaches the
4610: <a href="#earliest-possible-position">earliest possible position</a> of the <a href="#media-resource">media
4611: resource</a> when the <a href="#direction-of-playback">direction of playback</a> is
4612: backwards, then the user agent must follow these steps:</p>
4613:
4614: <ol><li><p>Stop playback.</p></li>
4615:
4616: <li><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
4617: a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
4618:
4619: </ol><hr><p>The <dfn id="dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
4620: attribute gives the desired speed at which the <a href="#media-resource">media
4621: resource</a> is to play, as a multiple of its intrinsic
4622: speed. The attribute is mutable: on getting it must return the last
4623: value it was set to, or 1.0 if it hasn't yet been set; on setting
4624: the attribute must be set to the new value.</p>
4625:
4626: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> is
4627: used by the user agent when it <a href="#expose-a-user-interface-to-the-user" title="expose a user interface
4628: to the user">exposes a user interface to the user</a>.</p>
4629:
4630: <p>The <dfn id="dom-media-playbackrate" title="dom-media-playbackRate"><code>playbackRate</code></dfn>
4631: attribute gives the <a href="#effective-playback-rate">effective playback rate</a>
4632: (assuming there is no <a href="#current-media-controller">current media controller</a> overriding it),
4633: which is the speed at which the <a href="#media-resource">media resource</a> plays,
4634: as a multiple of its intrinsic speed. If it is not equal to the
4635: <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>,
4636: then the implication is that the user is using a feature such as
4637: fast forward or slow motion playback. The attribute is mutable: on
4638: getting it must return the last value it was set to, or 1.0 if it
4639: hasn't yet been set; on setting the attribute must be set to the new
4640: value, and the playback will change speed
4641: (if the element is <a href="#potentially-playing">potentially playing</a> and there is no
4642: <a href="#current-media-controller">current media controller</a>).</p>
4643:
4644: <p id="rateUpdate">When the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or
4645: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4646: change value (either by being set by script or by being changed
4647: directly by the user agent, e.g. in response to user control) the
4648: 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
4649: event</a> named <code title="event-media-ratechange"><a href="#event-media-ratechange">ratechange</a></code> at the <a href="#media-element">media
4650: element</a>.</p>
4651:
4652: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> and
4653: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4654: have no effect when the <a href="#media-element">media element</a> has a
4655: <a href="#current-media-controller">current media controller</a>; the namesake attributes on
4656: the <code><a href="#mediacontroller">MediaController</a></code> object are used instead in that
4657: situation.</p>
4658:
4659: <hr><p>The <dfn id="dom-media-played" title="dom-media-played"><code>played</code></dfn>
4660: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4661: <code>TimeRanges</code> object</a> that represents the ranges of
4662: the <a href="#media-resource">media resource</a>, if any, that the user agent has so
4663: far rendered, at the time the attribute is evaluated.</p>
4664:
4665: <hr><p>When the <dfn id="dom-media-play" title="dom-media-play"><code>play()</code></dfn>
4666: method on a <a href="#media-element">media element</a> is invoked, the user agent
4667: must run the following steps.</p>
4668:
4669: <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
4670: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4671: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4672: algorithm</a>.</p></li>
4673:
4674: <li>
4675:
4676: <p>If the <a href="#ended-playback" title="ended playback">playback has ended</a>
4677: and the <a href="#direction-of-playback">direction of playback</a> is forwards,
4678: and the <a href="#media-element">media element</a> does not have a <a href="#current-media-controller">current
4679: media controller</a>,
4680: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4681: possible position</a> of the <a href="#media-resource">media resource</a>.</p>
4682:
4683: <p class="note">This <a href="#seekUpdate">will cause</a> the user
4684: 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
4685: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the <a href="#media-element">media
4686: element</a>.</p>
4687: </li>
4688:
4689: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
4690: media controller</a>, then <a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">bring the media element up
4691: to speed with its new media controller</a>.</p>
4692:
4693: </li><li>
4694:
4695: <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
4696: the following substeps:</p>
4697:
4698: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to false.</p></li>
4699:
4700: <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>
4701: named <code title="event-media-play"><a href="#event-media-play">play</a></code> at the element.</p></li>
4702:
4703: <li>
4704:
4705: <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
4706: value <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>,
4707: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, or
4708: <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
4709: <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>
4710: named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the
4711: element.</p>
4712:
4713: <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
4714: value <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4715: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>:
4716: <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>
4717: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> at the
4718: element.</p>
4719:
4720: </li>
4721:
4722: </ol></li>
4723:
4724: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4725: flag</a> to false.</p></li>
4726:
4727: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4728: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4729: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4730: controller</a>.</p></li>
4731:
4732: </ol><hr><p>When the <dfn id="dom-media-pause" title="dom-media-pause"><code>pause()</code></dfn>
4733: method is invoked, and when the user agent is required to pause the
4734: <a href="#media-element">media element</a>, the user agent must run the following
4735: steps:</p>
4736:
4737: <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
4738: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4739: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4740: algorithm</a>.</p></li>
4741:
4742: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4743: flag</a> to false.</p></li>
4744:
4745: <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
4746: following steps:</p>
4747:
4748: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to true.</p></li>
4749:
4750: <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
4751: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4752: element.</p></li>
4753:
4754: <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
4755: event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code>
4756: at the element.</p></li>
4757:
4758: </ol></li>
4759:
4760: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4761: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4762: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4763: controller</a>.</p></li>
4764:
4765: </ol><hr><p>The
4766: <dfn id="effective-playback-rate">effective playback rate</dfn> is not necessarily the element's
4767: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>. When a
4768: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4769: controller</a>, its <a href="#effective-playback-rate">effective playback rate</a> is the
4770: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
4771: rate</a>. Otherwise, the
4772: <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>.
4773: Thus, the <a href="#current-media-controller">current media controller</a> overrides the
4774: <a href="#media-element">media element</a>.
4775: </p>
4776:
4777: <p>If the <a href="#effective-playback-rate">effective playback rate</a> is positive or zero,
4778: then the <dfn id="direction-of-playback">direction of playback</dfn> is forwards. Otherwise, it
4779: is backwards.</p>
4780:
4781: <p id="media-playback">When a <a href="#media-element">media element</a> is
4782: <a href="#potentially-playing">potentially playing</a> and its <code><a href="infrastructure.html#document">Document</a></code> is a
4783: <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
4784: playback position</a> must increase monotonically at
4785: <a href="#effective-playback-rate">effective playback rate</a> units of media time per unit time
4786: of the <a href="#media-timeline">media timeline</a>'s clock.</p>
4787:
4788: <p class="note">The <a href="#effective-playback-rate">effective playback rate</a> can be 0.0,
4789: in which case the <a href="#current-playback-position">current playback position</a> doesn't
4790: 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
4791: <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> event doesn't
4792: fire).</p>
4793:
4794: <p class="note">This specification doesn't define how the user agent
4795: achieves the appropriate playback rate — depending on the
4796: protocol and media available, it is plausible that the user agent
4797: could negotiate with the server to have the server provide the media
4798: data at the appropriate rate, so that (except for the period between
4799: when the rate is changed and when the server updates the stream's
4800: playback rate) the client doesn't actually have to drop or
4801: interpolate any frames.</p>
4802:
4803: <p>When the <a href="#direction-of-playback">direction of playback</a> is backwards, any
4804: corresponding audio must be muted. When the <a href="#effective-playback-rate">effective playback
4805: rate</a> is so low or so high that the user agent cannot play
4806: audio usefully, the corresponding audio must also be muted. If the
4807: <a href="#effective-playback-rate">effective playback rate</a> is not 1.0, the user agent may
4808: apply pitch adjustments to the audio as necessary to render it
4809: faithfully.</p>
4810:
4811: <p><a href="#media-element" title="media element">Media elements</a> that are
4812: <a href="#potentially-playing">potentially playing</a> while not <a href="infrastructure.html#in-a-document">in a
4813: <code>Document</code></a> must not play any video, but should
4814: play any audio component. Media elements must not stop playing just
4815: because all references to them have been removed; only once a media
4816: element is in a state where no further audio could ever be played by
4817: that element may the element be garbage collected.</p>
4818:
4819: <p class="note">It is possible for an element to which no explicit
4820: references exist to play audio, even if such an element is not still
4821: actively playing: for instance, it could have a <a href="#current-media-controller">current media
4822: controller</a> that still has references and can still be
4823: unpaused, or it could be unpaused but stalled waiting for content to
4824: buffer.</p>
4825:
4826: <hr><p>When the <a href="#current-playback-position">current playback position</a> of a <a href="#media-element">media
4827: element</a> changes (e.g. due to playback or seeking), the user
4828: agent must run the following steps. If the <a href="#current-playback-position">current playback
4829: position</a> changes while the steps are running, then the user
4830: agent must wait for the steps to complete, and then must immediately
4831: rerun the steps.
4832: (These steps are thus run as often as possible or needed — if
4833: 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
4834: agent rushes ahead to "catch up".)
4835: </p>
4836:
4837: <ol><li><p>Let <var title="">current cues</var> be an ordered list of
4838: <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
4839: all the <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
4840: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
4841: default">showing by default</a> <a href="#text-track" title="text track">text
4842: 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
4843: or equal to the <a href="#current-playback-position">current playback position</a> and whose
4844: <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are greater
4845: than the <a href="#current-playback-position">current playback position</a>, in <a href="#text-track-cue-order">text
4846: track cue order</a>.</p></li>
4847:
4848: <li><p>Let <var title="">other cues</var> be an ordered list of
4849: <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
4850: all the <a href="#text-track-cue" title="text track cue">cues</a> of <a href="#text-track-hidden" title="text track hidden">hidden</a>, <a href="#text-track-showing" title="text track
4851: showing">showing</a>, and <a href="#text-track-showing-by-default" title="text track showing by
4852: default">showing by default</a> <a href="#text-track" title="text track">text
4853: tracks</a> of the <a href="#media-element">media element</a> that are not
4854: present in <var title="">current cues</var>, also in <a href="#text-track-cue-order">text
4855: track cue order</a>.</p></li>
4856:
4857: <li><p>If the time was reached through the usual monotonic increase
4858: of the <a href="#current-playback-position">current playback position</a> during normal
4859: 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
4860: element in the past 15 to 250ms and is not still running event
4861: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4862: 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.
4863: (In the other cases, such as explicit seeks, relevant events get
4864: fired as part of the overall process of changing the <a href="#current-playback-position">current
4865: playback position</a>.)</p>
4866:
4867: <p class="note">The event thus is not to be fired faster than about
4868: 66Hz or slower than 4Hz (assuming the event handlers don't take
4869: longer than 250ms to run). User agents are encouraged to vary the
4870: frequency of the event based on the system load and the average
4871: cost of processing the event each time, so that the UI updates are
4872: not any more frequent than the user agent can comfortably handle
4873: while decoding the video.</p></li>
4874:
4875: <li><p>If all of the <a href="#text-track-cue" title="text track cue">cues</a> in
4876: <var title="">current cues</var> have their <a href="#text-track-cue-active-flag">text track cue
4877: active flag</a> set, and none of the <a href="#text-track-cue" title="text track
4878: cue">cues</a> in <var title="">other cues</var> have their
4879: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, then abort these
4880: steps.</p></li>
4881:
4882: <li><p>If the time was reached through the usual monotonic increase
4883: of the <a href="#current-playback-position">current playback position</a> during normal
4884: playback, and there are <a href="#text-track-cue" title="text track cue">cues</a> in
4885: <var title="">other cues</var> that have both their <a href="#text-track-cue-active-flag">text
4886: track cue active flag</a> set and their <a href="#text-track-cue-pause-on-exit-flag">text track cue
4887: pause-on-exit flag</a> set, then immediately <a href="#dom-media-pause" title="dom-media-pause">pause</a> the <a href="#media-element">media
4888: element</a>. (In the other cases, such as explicit
4889: seeks, 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
4890: track cue">cue</a> has its <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
4891: flag</a> set.)</p></li>
4892:
4893: <li><p>Let <var title="">affected tracks</var> be a list of <a href="#text-track" title="text track">text tracks</a>, initially empty.</p></li>
4894:
4895: <li><p>For each <a href="#text-track-cue" title="text track cue">text track
4896: cue</a> in <var title="">other cues</var> that has its
4897: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
4898: <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
4899: <code title="event-exit">exit</code> at the
4900: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
4901: track cue">cue</a>'s <a href="#text-track">text track</a> to <var title="">affected tracks</var>, if it's not already in the
4902: list.</p></li>
4903:
4904: <li><p>For each <a href="#text-track-cue" title="text track cue">text track
4905: cue</a> in <var title="">current cues</var> that does not have
4906: its <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
4907: <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
4908: <code title="event-enter">enter</code> at the
4909: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
4910: track cue">cue</a>'s <a href="#text-track">text track</a> to <var title="">affected tracks</var>, if it's not already in the
4911: list.</p></li>
4912:
4913: <li><p>For each <a href="#text-track">text track</a> in <var title="">affected
4914: tracks</var>, in the order they were added to the list (which will
4915: match the relative order of the <a href="#text-track" title="text track">text
4916: tracks</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
4917: text tracks</a>), <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
4918: simple event</a> named <code title="event-cuechange">cuechange</code> at the
4919: <code><a href="#texttrack">TextTrack</a></code> object, and, if the <a href="#text-track">text
4920: track</a> has a corresponding <code><a href="#the-track-element">track</a></code> element, to
4921: then <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-cuechange">cuechange</code> at the <code><a href="#the-track-element">track</a></code>
4922: element as well.</p></li>
4923:
4924: <li><p>Set the <a href="#text-track-cue-active-flag">text track cue active flag</a> of all the
4925: <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
4926: active flag</a> of all the <a href="#text-track-cue" title="text track
4927: cue">cues</a> in the <var title="">other cues</var>.</p></li>
4928:
4929: <li><p>Run the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
4930: rendering</a> of each of the <a href="#text-track" title="text track">text
4931: 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
4932: track showing by default">showing by default</a>.
4933: </p></li>
4934:
4935: </ol><p>For the purposes of the algorithm above, a <a href="#text-track-cue">text track
4936: cue</a> is considered to be part of a <a href="#text-track">text track</a>
4937: only if it is listed in the <a href="#text-track-list-of-cues">text track list of cues</a>,
4938: not merely if it is associated with the <a href="#text-track">text
4939: track</a>.</p>
4940:
4941: <p class="note">If the <a href="#media-element">media element</a>'s
4942: <code><a href="infrastructure.html#document">Document</a></code> stops being a <a href="browsers.html#fully-active">fully active</a>
4943: document, then the playback will <a href="#media-playback">stop</a>
4944: until the document is active again.</p>
4945:
4946: <p>When a <a href="#media-element">media element</a> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an
4947: element from a document">removed from a
4948: <code>Document</code></a>, the user agent must run
4949: the following steps:</p>
4950:
4951: <ol><li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
4952: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that removed the
4953: <a href="#media-element">media element</a> from the <code><a href="infrastructure.html#document">Document</a></code> to
4954: continue. The <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the
4955: remaining steps of this algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous
4956: section</a> are marked with ⌛.)</p></li>
4957:
4958: <li><p>⌛ If the <a href="#media-element">media element</a> is <a href="infrastructure.html#in-a-document">in a
4959: <code>Document</code></a>, abort these steps.</p></li>
4960:
4961: <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
4962: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, abort these
4963: steps.</p></li>
4964:
4965: <li><p>⌛ <a href="#dom-media-pause" title="dom-media-pause">Pause</a> the
4966: <a href="#media-element">media element</a>.</p>
4967:
4968: </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>
4969:
4970: <dd>
4971:
4972: <p>Returns true if the user agent is currently seeking.</p>
4973:
4974: </dd>
4975:
4976: <dt><var title="">media</var> . <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code></dt>
4977:
4978: <dd>
4979:
4980: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4981: ranges of the <a href="#media-resource">media resource</a> to which it is possible
4982: for the user agent to seek.</p>
4983:
4984: </dd>
4985:
4986: </dl><div class="impl">
4987:
4988: <p>The <dfn id="dom-media-seeking" title="dom-media-seeking"><code>seeking</code></dfn>
4989: attribute must initially have the value false.</p>
4990:
4991: <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
4992: playback position</var> in the <a href="#media-resource">media resource</a>, it means
4993: that the user agent must run the following steps. This algorithm
4994: interacts closely with the <a href="webappapis.html#event-loop">event loop</a> mechanism; in
4995: particular, it has a <a href="webappapis.html#synchronous-section">synchronous
4996: section</a> (which is triggered as part of the <a href="webappapis.html#event-loop">event
4997: loop</a> algorithm). Steps in that section are marked with
4998: ⌛.</p>
4999:
5000: <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>, then raise an
1.78 mike 5001: <code><a href="infrastructure.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception (if the seek was in
1.47 mike 5002: response to a DOM method call or setting of an IDL attribute), and
5003: abort these steps.</p></li>
5004:
5005: <li><p>If the element's <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute is true,
5006: then another instance of this algorithm is already running. Abort
5007: that other instance of the algorithm without waiting for the step
5008: that it is running to complete.</p></li>
5009:
5010: <li><p>Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL
5011: attribute to true.</p></li>
5012:
5013: <li><p>If the seek was in response to a DOM method call or setting
5014: of an IDL attribute, then continue the script. The remainder of
5015: these steps must be run asynchronously. With the exception of the
5016: steps marked with ⌛, they could be aborted at any time by
5017: another instance of this algorithm being invoked.</p></li>
5018:
5019: <li><p>If the <var title="">new playback position</var> is later
5020: than the end of the <a href="#media-resource">media resource</a>, then let it be the
5021: end of the <a href="#media-resource">media resource</a> instead.</p></li>
5022:
5023: <li><p>If the <var title="">new playback position</var> is less
5024: than the <a href="#earliest-possible-position">earliest possible position</a>, let it be that
5025: position instead.</p></li>
5026:
5027: <li><p>If the (possibly now changed) <var title="">new playback
5028: 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
5029: 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
5030: nearest to the <var title="">new playback position</var>. If two
5031: positions both satisfy that constraint (i.e. the <var title="">new
5032: playback position</var> is exactly in the middle between two ranges
5033: in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute)
5034: then use the position that is closest to the <a href="#current-playback-position">current playback
5035: 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
5036: <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
5037: false and abort these steps.</p></li>
5038:
5039: <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
5040: event</a> named <code title="event-media-seeking"><a href="#event-media-seeking">seeking</a></code>
5041: at the element.</p></li>
5042:
5043: <li>
5044:
5045: <p>Set the <a href="#current-playback-position">current playback position</a> to the given
5046: <var title="">new playback position</var>.</p>
5047:
5048: <p class="note">If the <a href="#media-element">media element</a> was
5049: <a href="#potentially-playing">potentially playing</a> immediately before it started
5050: seeking, but seeking caused its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to change
5051: 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
5052: <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
5053: element.</p>
5054:
5055:
5056: </li>
5057:
5058: <li><p>Wait until the user agent has established whether or not the
5059: <a href="#media-data">media data</a> for the <var title="">new playback
5060: position</var> is available, and, if it is, until it has decoded
5061: enough data to play back that position.</p>
5062: </li>
5063:
5064: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
5065: section</a> consists of all the remaining steps of this
5066: algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous section</a> are
5067: marked with ⌛.)</p></li>
5068:
5069: <li><p>⌛ Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
5070: false.</p></li>
5071:
5072: <li id="seekUpdate"><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
5073: simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
5074: element.</p></li>
5075:
5076: <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
5077: event</a> named <code title="event-media-seeked"><a href="#event-media-seeked">seeked</a></code>
5078: at the element.</p></li>
5079:
5080: </ol><p>The <dfn id="dom-media-seekable" title="dom-media-seekable"><code>seekable</code></dfn>
5081: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5082: <code>TimeRanges</code> object</a> that represents the ranges of
5083: the <a href="#media-resource">media resource</a>, if any, that the user agent is able
5084: to seek to, at the time the attribute is evaluated.</p>
5085:
5086: <p class="note">If the user agent can seek to anywhere in the
5087: <a href="#media-resource">media resource</a>, e.g. because it is a simple movie file
5088: and the user agent and the server support HTTP Range requests, then
5089: the attribute would return an object with one range, whose start is
5090: the time of the first frame (the <a href="#earliest-possible-position">earliest possible
5091: position</a>, typically zero), and whose end is the same as the
5092: time of the first frame plus the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute's value (which
5093: would equal the time of the last frame, and might be positive
5094: Infinity).</p>
5095:
5096: <p class="note">The range might be continuously changing, e.g. if
5097: the user agent is buffering a sliding window on an infinite
5098: stream. This is the behavior seen with DVRs viewing live TV, for
5099: instance.</p>
5100:
5101: <p><a href="#media-resource" title="media resource">Media resources</a> might be
5102: internally scripted or interactive. Thus, a <a href="#media-element">media
5103: element</a> could play in a non-linear fashion. If this happens,
5104: 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
5105: <a href="#current-playback-position">current playback position</a> changes in a discontinuous
5106: fashion (so that the relevant events fire).
5107: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
5108: controller</a>, then the user agent must <a href="#seek-the-media-controller">seek the media
5109: controller</a> appropriately instead.
5110: </p>
5111:
5112: </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
5113: and video tracks. For example, in addition to the primary video and
5114: audio tracks, a <a href="#media-resource">media resource</a> could have
5115: foreign-language dubbed dialogues, director's commentaries, audio
5116: 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>
5117:
5118: <dd>
5119:
1.76 mike 5120: <p>Returns an <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
1.47 mike 5121: the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
5122:
5123: </dd>
5124:
5125: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code></dt>
5126:
5127: <dd>
5128:
1.76 mike 5129: <p>Returns an <code><a href="#videotracklist">VideoTrackList</a></code> object representing
1.47 mike 5130: the video tracks available in the <a href="#media-resource">media resource</a>.</p>
5131:
5132: </dd>
5133:
5134: </dl><div class="impl">
5135:
5136: <p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
5137: attribute of a <a href="#media-element">media element</a> must return a
1.76 mike 5138: <a href="infrastructure.html#live">live</a> <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
1.47 mike 5139: the audio tracks available in the <a href="#media-element">media element</a>'s
5140: <a href="#media-resource">media resource</a>. The same object must be returned each
5141: time.</p>
5142:
5143: <p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
5144: attribute of a <a href="#media-element">media element</a> must return a
1.76 mike 5145: <a href="infrastructure.html#live">live</a> <code><a href="#videotracklist">VideoTrackList</a></code> object
1.47 mike 5146: representing the video tracks available in the <a href="#media-element">media
5147: element</a>'s <a href="#media-resource">media resource</a>. The same object must
5148: be returned each time.</p>
5149:
1.76 mike 5150: <p class="note">There are only ever one <code><a href="#audiotracklist">AudioTrackList</a></code>
5151: object and one <code><a href="#videotracklist">VideoTrackList</a></code> object per <a href="#media-element">media
1.47 mike 5152: element</a>, even if another <a href="#media-resource">media resource</a> is
1.76 mike 5153: loaded into the element: the objects are reused. (The
5154: <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects are
5155: not, though.)</p>
1.47 mike 5156:
1.67 mike 5157: </div><div class="example">
5158:
5159: <p>In this example, a script defines a function that takes a URL to
5160: a video and a reference to an element where the video is to be
5161: placed. That function then tries to load the video, and, once it is
5162: loaded, checks to see if there is a sign-language track available.
5163: If there is, it also displays that track. Both tracks are just
5164: placed in the given container; it's assumed that styles have been
5165: applied to make this work in a pretty way!</p>
5166:
5167: <pre><script>
5168: function loadVideo(url, container) {
5169: var controller = new MediaController();
5170: var video = document.createElement('video');
5171: video.src = url;
5172: video.autoplay = true;
5173: video.controls = true;
5174: video.controller = controller;
5175: container.appendChild(video);
5176: video.onloadedmetadata = function (event) {
5177: for (var i = 0; i < video.videoTracks.length; i += 1) {
1.76 mike 5178: if (video.videoTracks[i].kind == 'sign') {
1.67 mike 5179: var sign = document.createElement('video');
1.76 mike 5180: sign.src = url + '#track=' + video.videoTracks[i].id;
1.67 mike 5181: sign.autoplay = true;
5182: sign.controller = controller;
5183: container.appendChild(sign);
5184: return;
5185: }
5186: }
5187: };
5188: }
5189: </script></pre>
5190:
1.76 mike 5191: </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>
5192: interfaces are used by attributes defined in the previous
5193: section.</p><pre class="idl">interface <dfn id="audiotracklist">AudioTrackList</dfn> {
5194: readonly attribute unsigned long <a href="#dom-audiotracklist-length" title="dom-AudioTrackList-length">length</a>;
5195: getter <a href="#audiotrack">AudioTrack</a> (in unsigned long index);
5196: <a href="#audiotrack">AudioTrack</a>? <a href="#dom-audiotracklist-gettrackbyid" title="dom-AudioTrackList-getTrackById">getTrackById</a>(in DOMString id);
5197: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
5198: };
1.47 mike 5199:
1.76 mike 5200: interface <dfn id="audiotrack">AudioTrack</dfn> {
5201: readonly attribute DOMString <a href="#dom-audiotrack-id" title="dom-AudioTrack-id">id</a>;
5202: readonly attribute DOMString <a href="#dom-audiotrack-kind" title="dom-AudioTrack-kind">kind</a>;
5203: readonly attribute DOMString <a href="#dom-audiotrack-label" title="dom-AudioTrack-label">label</a>;
5204: readonly attribute DOMString <a href="#dom-audiotrack-language" title="dom-AudioTrack-language">language</a>;
5205: attribute boolean <a href="#dom-audiotrack-enabled" title="dom-AudioTrack-enabled">enabled</a>;
1.47 mike 5206: };
5207:
1.76 mike 5208: interface <dfn id="videotracklist">VideoTrackList</dfn> {
5209: readonly attribute unsigned long <a href="#dom-videotracklist-length" title="dom-VideoTrackList-length">length</a>;
5210: getter <a href="#videotrack">VideoTrack</a> (in unsigned long index);
5211: <a href="#videotrack">VideoTrack</a>? <a href="#dom-videotracklist-gettrackbyid" title="dom-VideoTrackList-getTrackById">getTrackById</a>(in DOMString id);
5212: readonly attribute long <a href="#dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex">selectedIndex</a>;
5213: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
1.47 mike 5214: };
5215:
1.76 mike 5216: interface <dfn id="videotrack">VideoTrack</dfn> {
5217: readonly attribute DOMString <a href="#dom-videotrack-id" title="dom-VideoTrack-id">id</a>;
5218: readonly attribute DOMString <a href="#dom-videotrack-kind" title="dom-VideoTrack-kind">kind</a>;
5219: readonly attribute DOMString <a href="#dom-videotrack-label" title="dom-VideoTrack-label">label</a>;
5220: readonly attribute DOMString <a href="#dom-videotrack-language" title="dom-VideoTrack-language">language</a>;
5221: attribute boolean <a href="#dom-videotrack-selected" title="dom-VideoTrack-selected">selected</a>;
5222: };</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>
5223: <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 5224:
5225: <dd>
5226:
5227: <p>Returns the number of tracks in the list.</p>
5228:
5229: </dd>
5230:
1.76 mike 5231: <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>
5232: <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 5233:
5234: <dd>
5235:
1.76 mike 5236: <p>Returns the specified <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object.</p>
1.47 mike 5237:
5238: </dd>
5239:
1.76 mike 5240: <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>
5241: <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 5242:
5243: <dd>
5244:
1.76 mike 5245: <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 5246:
5247: </dd>
5248:
1.76 mike 5249: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-id"><a href="#dom-audiotrack-id">id</a></code></dt>
5250: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-id"><a href="#dom-videotrack-id">id</a></code></dt>
1.47 mike 5251:
5252: <dd>
5253:
1.76 mike 5254: <p>Returns the ID of the given track. This is the ID that can be
5255: used with a fragment identifier if the format supports the
5256: <cite>Media Fragments URI</cite> syntax, and that can be used with
1.93 mike 5257: the <code title="">getTrackById()</code> method. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5258:
5259: </dd>
5260:
1.76 mike 5261: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-kind"><a href="#dom-audiotrack-kind">kind</a></code></dt>
5262: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-kind"><a href="#dom-videotrack-kind">kind</a></code></dt>
1.47 mike 5263:
5264: <dd>
5265:
1.76 mike 5266: <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 5267:
5268: </dd>
5269:
1.76 mike 5270: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-label"><a href="#dom-audiotrack-label">label</a></code></dt>
5271: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-label"><a href="#dom-videotrack-label">label</a></code></dt>
1.47 mike 5272:
5273: <dd>
5274:
1.76 mike 5275: <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
1.47 mike 5276:
5277: </dd>
5278:
1.76 mike 5279: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-language"><a href="#dom-audiotrack-language">language</a></code></dt>
5280: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-language"><a href="#dom-videotrack-language">language</a></code></dt>
1.47 mike 5281:
5282: <dd>
5283:
1.76 mike 5284: <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
1.47 mike 5285:
5286: </dd>
5287:
1.76 mike 5288: <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 5289:
5290: <dd>
5291:
1.76 mike 5292: <p>Returns true if the given track is active, and false otherwise.</p>
5293:
5294: <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 5295:
5296: </dd>
5297:
1.76 mike 5298: <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 5299:
5300: <dd>
5301:
5302: <p>Returns the index of the currently selected track, if any, or −1 otherwise.</p>
5303:
5304: </dd>
5305:
1.76 mike 5306: <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 5307:
5308: <dd>
5309:
1.76 mike 5310: <p>Returns true if the given track is active, and false otherwise.</p>
5311:
5312: <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 5313:
5314: </dd>
5315:
5316: </dl><div class="impl">
5317:
1.76 mike 5318: <p>An <code><a href="#audiotracklist">AudioTrackList</a></code> object represents a dynamic list
5319: of zero or more audio tracks, of which zero or more can be enabled
5320: at a time. Each audio track is represented by an
5321: <code><a href="#audiotrack">AudioTrack</a></code> object.</p>
5322:
5323: <p>A <code><a href="#videotracklist">VideoTrackList</a></code> object represents a dynamic list of
5324: zero or more video tracks, of which zero or one can be selected at a
5325: time. Each video track is represented by a <code><a href="#videotrack">VideoTrack</a></code>
5326: object.</p>
5327:
5328: <p>Tracks in <code><a href="#audiotracklist">AudioTrackList</a></code> and
5329: <code><a href="#videotracklist">VideoTrackList</a></code> objects must be consistently ordered. If
5330: the <a href="#media-resource">media resource</a> is in a format that defines an
5331: order, then that order must be used; otherwise, the order must be
5332: the relative order in which the tracks are declared in the
5333: <a href="#media-resource">media resource</a>. The order used is called the <i>natural
5334: order</i> of the list.</p>
5335:
5336: <p class="note">Each track in a <code>TrackList</code> thus has an
5337: index; the first has the index 0, and each subsequent track is
5338: numbered one higher than the previous one. If a <a href="#media-resource">media
5339: resource</a> dynamically adds or removes audio or video tracks,
5340: then the indices of the tracks will change dynamically. If the
5341: <a href="#media-resource">media resource</a> changes entirely, then all the previous
5342: tracks will be removed and replaced with new tracks.</p>
5343:
5344: <p>The <dfn id="dom-audiotracklist-length" title="dom-AudioTrackList-length"><code>AudioTrackList.length</code></dfn>
5345: and <dfn id="dom-videotracklist-length" title="dom-VideoTrackList-length"><code>VideoTrackList.length</code></dfn>
5346: attributes must return the number of tracks represented by their
5347: objects at the time of getting.</p>
5348:
5349: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of
5350: <code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code> objects
5351: at any instant are the numbers from zero to the number of tracks
5352: represented by the respective object minus one, if any tracks are
5353: represented. If a <code><a href="#audiotracklist">AudioTrackList</a></code> or
5354: <code><a href="#videotracklist">VideoTrackList</a></code> object represents no tracks, it has no
5355: <a href="infrastructure.html#supported-property-indices">supported property indices</a>.</p>
5356:
5357: <p>To <a href="infrastructure.html#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> for a
5358: given index <var title="">index</var> in an
5359: <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> object
5360: <var title="">list</var>, the user agent must return the
5361: <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object that
5362: represents the <var title="">index</var>th track in <var title="">list</var>.</p>
5363:
5364: <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
5365: <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object
5366: (respectively) in the <code><a href="#audiotrack">AudioTrack</a></code> or
5367: <code><a href="#videotrack">VideoTrack</a></code> object (respectively) whose identifier is
5368: equal to the value of the <var title="">id</var> argument (in the
5369: natural order of the list, as defined above). When no tracks match
5370: the given argument, the methods must return null.</p>
5371:
5372: <p>The <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects
5373: represent specific tracks of a <a href="#media-resource">media resource</a>. Each
5374: track can have an identifier, category, label, and language. These
5375: aspects of a track are permanent for the lifetime of the track; even
5376: if a track is removed from a <a href="#media-resource">media resource</a>'s
5377: <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> objects,
5378: those aspects do not change.</p>
5379:
5380: <p>In addition, <code><a href="#audiotrack">AudioTrack</a></code> objects can each be enabled
5381: or disabled; this is the audio track's <i>enabled state</i>. When an
5382: <code><a href="#audiotrack">AudioTrack</a></code> is created, its <i>enabled state</i> must be
5383: set to false (disabled). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
5384: can override this.</p>
5385:
5386: <p>Similarly, a single <code><a href="#videotrack">VideoTrack</a></code> object per
5387: <code><a href="#videotracklist">VideoTrackList</a></code> object can be selected, this is the
5388: video track's <i>selection state</i>. When an
5389: <code><a href="#videotrack">VideoTrack</a></code> is created, its <i>selection state</i> must
5390: be set to false (not selected). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
5391: can override this.</p>
5392:
5393: <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>
5394: attributes must return the identifier of the track, if it has one,
5395: or the empty string otherwise. If the <a href="#media-resource">media resource</a> is
5396: in a format that supports the <cite>Media Fragments URI</cite>
5397: fragment identifier syntax, the identifier returned for a particular
5398: track must be the same identifier that would enable the track if
5399: used as the name of a track in the track dimension of such a
1.47 mike 5400: fragment identifier. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
5401:
1.76 mike 5402: <p>The <dfn id="dom-audiotrack-kind" title="dom-AudioTrack-kind"><code>AudioTrack.kind</code></dfn> and
5403: <dfn id="dom-videotrack-kind" title="dom-VideoTrack-kind"><code>VideoTrack.kind</code></dfn>
5404: attributes must return the category of the track, if it has one, or
5405: the empty string otherwise.</p>
1.47 mike 5406:
5407: <p>The category of a track is the string given in the first column
5408: of the table below that is the most appropriate for the track based
5409: on the definitions in the table's second and third columns, as
5410: determined by the metadata included in the track in the <a href="#media-resource">media
5411: resource</a>. For Ogg files, the Role header of the track gives
5412: the relevant metadata. The cell in the third column of a row says
5413: what the category given in the cell in the first column of that row
5414: applies to; a category is only appropriate for an audio track if it
5415: applies to audio tracks, and a category is only appropriate for
1.76 mike 5416: video tracks if it applies to video tracks. Categories must only be
5417: returned for <code><a href="#audiotrack">AudioTrack</a></code> objects if they are appropriate
5418: for audio, and must only be returned for <code><a href="#videotrack">VideoTrack</a></code>
5419: objects if they are appropriate for video.</p>
1.47 mike 5420:
1.76 mike 5421: </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 5422: <thead><tr><th>Category
5423: </th><th>Definition
5424: </th><th>Applies to...</th>
5425: <th>Examples
1.76 mike 5426: </th></tr></thead><tbody><tr><td>"<dfn id="value-track-kind-alternate" title="value-track-kind-alternate"><code>alternative</code></dfn>"
1.47 mike 5427: </td><td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
5428: </td><td>Audio and video.
1.89 mike 5429: </td><td>Ogg: "audio/alternate" or "video/alternate".
1.47 mike 5430:
1.76 mike 5431: </td></tr><tr><td>"<dfn id="value-track-kind-description" title="value-track-kind-description"><code>description</code></dfn>"
1.47 mike 5432: </td><td>An audio description of a video track.
5433: </td><td>Audio only.
5434: </td><td>Ogg: "audio/audiodesc".
5435:
1.76 mike 5436: </td></tr><tr><td>"<dfn id="value-track-kind-main" title="value-track-kind-main"><code>main</code></dfn>"
1.47 mike 5437: </td><td>The primary audio or video track.
5438: </td><td>Audio and video.
5439: </td><td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
5440:
1.76 mike 5441: </td></tr><tr><td>"<dfn id="value-track-kind-sign" title="value-track-kind-sign"><code>sign</code></dfn>"
1.47 mike 5442: </td><td>A sign-language interpretation of an audio track.
5443: </td><td>Video only.
5444: </td><td>Ogg: "video/sign".
5445:
1.76 mike 5446: </td></tr><tr><td>"<dfn id="value-track-kind-translation" title="value-track-kind-translation"><code>translation</code></dfn>"
1.47 mike 5447: </td><td>A translated version of the main track.
5448: </td><td>Audio only.
5449: </td><td>Ogg: "audio/dub".
5450:
1.76 mike 5451: </td></tr><tr><td>"<dfn id="value-track-kind-commentary" title="value-track-kind-commentary"><code>commentary</code></dfn>"
5452: </td><td>Commentary on the primary audio or video track, e.g. a director's commentary.
5453: </td><td>Audio and video.
5454: </td><td>No known formats expose this category at this time.
5455:
5456: </td></tr><tr><td>"<dfn id="value-track-kind-none" title="value-track-kind-none"><code></code></dfn>" (empty string)
1.47 mike 5457: </td><td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
5458: </td><td>Audio and video.
5459: </td><td>Any other track type or track role.
5460:
5461: </td></tr></tbody></table><div class="impl">
5462:
1.76 mike 5463: <p>The <dfn id="dom-audiotrack-label" title="dom-AudioTrack-label"><code>AudioTrack.label</code></dfn> and
5464: <dfn id="dom-videotrack-label" title="dom-VideoTrack-label"><code>VideoTrack.label</code></dfn>
5465: attributes must return the label of the track, if it has one, or the
5466: empty string otherwise.</p>
5467:
5468: <p>The <dfn id="dom-audiotrack-language" title="dom-AudioTrack-language"><code>AudioTrack.language</code></dfn>
5469: and <dfn id="dom-videotrack-language" title="dom-VideoTrack-language"><code>VideoTrack.language</code></dfn>
5470: attributes must return the BCP 47 language tag of the language of
5471: the track, if it has one, or the empty string otherwise. If the user
1.47 mike 5472: agent is not able to express that language as a BCP 47 language tag
5473: (for example because the language information in the <a href="#media-resource">media
5474: resource</a>'s format is a free-form string without a defined
1.76 mike 5475: interpretation), then the method must return the empty string, as if
5476: the track had no language.</p>
1.47 mike 5477:
1.76 mike 5478: <p>The <dfn id="dom-audiotrack-enabled" title="dom-AudioTrack-enabled"><code>AudioTrack.enabled</code></dfn>
5479: attribute, on getting, must return true if the track is currently
5480: enabled, and false otherwise. On setting, it must enable the track
5481: if the new value is true, and disable it otherwise. (If the track is
5482: no longer in an <code><a href="#audiotracklist">AudioTrackList</a></code> object, then the track
5483: being enabled or disabled has no effect beyond changing the value of
5484: the attribute on the <code><a href="#audiotrack">AudioTrack</a></code> object.)</p>
5485:
5486: <p>Whenever an audio track in an <code><a href="#audiotracklist">AudioTrackList</a></code> is
5487: enabled or disabled, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
5488: to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-change">change</code> at the
5489: <code><a href="#audiotracklist">AudioTrackList</a></code> object.</p>
5490:
5491: <p>The <dfn id="dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex"><code>VideoTrackList.selectedIndex</code></dfn>
5492: attribute must return the index of the currently selected track, if
5493: any. If the <code><a href="#videotracklist">VideoTrackList</a></code> object does not currently
5494: represent any tracks, or if none of the tracks are selected, it must
5495: instead return −1.</p>
5496:
5497: <p>The <dfn id="dom-videotrack-selected" title="dom-VideoTrack-selected"><code>VideoTrack.selected</code></dfn>
5498: attribute, on getting, must return true if the track is currently
5499: selected, and false otherwise. On setting, it must select the track
5500: if the new value is true, and unselect it otherwise. If the track is
5501: in a <code><a href="#videotracklist">VideoTrackList</a></code>, then all the other
5502: <code><a href="#videotrack">VideoTrack</a></code> objects in that list must be unselected. (If
5503: the track is no longer in a <code><a href="#videotracklist">VideoTrackList</a></code> object, then
5504: the track being selected or unselected has no effect beyond changing
5505: the value of the attribute on the <code><a href="#videotrack">VideoTrack</a></code>
5506: object.)</p>
5507:
5508: <p>Whenever a track in a <code><a href="#videotracklist">VideoTrackList</a></code> that was
5509: previously not selected is selected, the user agent must <a href="webappapis.html#queue-a-task">queue
5510: 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
5511: <code><a href="#videotracklist">VideoTrackList</a></code> object.</p>
1.47 mike 5512:
5513: <hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
5514: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
5515: event types</a>) that must be supported, as IDL attributes, by
1.76 mike 5516: all objects implementing the <code><a href="#audiotracklist">AudioTrackList</a></code> and
5517: <code><a href="#videotracklist">VideoTrackList</a></code> interfaces:</p>
1.47 mike 5518:
5519: <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>
5520: </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>
5521: </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
5522: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5523:
5524:
5525:
5526: </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
5527: <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attributes
5528: allow scripts to select which track should play, but it is also
5529: possible to select specific tracks declaratively, by specifying
5530: particular tracks in the fragment identifier of the <a href="urls.html#url">URL</a>
5531: of the <a href="#media-resource">media resource</a>. The format of the fragment
5532: identifier depends on the <a href="infrastructure.html#mime-type">MIME type</a> of the <a href="#media-resource">media
5533: resource</a>. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3986">[RFC3986]</a></p><div class="example">
5534:
5535: <p>In this example, a video that uses a format that supports the
5536: <cite>Media Fragments URI</cite> fragment identifier syntax is
5537: embedded in such a way that the alternative angles labeled
5538: "Alternative" are enabled instead of the default video track. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
5539:
5540: <pre><video src="myvideo#track=Alternative"></video></pre>
5541:
5542:
5543: </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
5544: <code><a href="#mediacontroller">MediaController</a></code>. A <code><a href="#mediacontroller">MediaController</a></code> is an
5545: object that coordinates the playback of multiple <a href="#media-element" title="media
5546: element">media elements</a>, for instance so that a sign-language
5547: interpreter track can be overlaid on a video track, with the two
5548: being kept in sync.</p><p>By default, a <a href="#media-element">media element</a> has no
5549: <code><a href="#mediacontroller">MediaController</a></code>. An implicit
5550: <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.
5551: An explicit <code><a href="#mediacontroller">MediaController</a></code> can be assigned directly
5552: using the <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> IDL
5553: attribute.</p><p><a href="#media-element" title="media element">Media elements</a> with a
5554: <code><a href="#mediacontroller">MediaController</a></code> are said to be <i>slaved</i> to their
5555: controller. The <code><a href="#mediacontroller">MediaController</a></code> modifies the playback
5556: rate and the playback volume of each of the <a href="#media-element" title="media
5557: element">media elements</a> slaved to it, and ensures that when
5558: any of its slaved <a href="#media-element" title="media element">media elements</a>
5559: 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
5560: <code><a href="#mediacontroller">MediaController</a></code>, its playback rate is fixed to that of
5561: the other tracks in the same <code><a href="#mediacontroller">MediaController</a></code>, and any
5562: 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>]
5563: interface <dfn id="mediacontroller">MediaController</dfn> {
5564: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-buffered" title="dom-MediaController-buffered">buffered</a>;
5565: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-seekable" title="dom-MediaController-seekable">seekable</a>;
5566: readonly attribute double <a href="#dom-mediacontroller-duration" title="dom-MediaController-duration">duration</a>;
5567: attribute double <a href="#dom-mediacontroller-currenttime" title="dom-MediaController-currentTime">currentTime</a>;
5568:
5569: readonly attribute boolean <a href="#dom-mediacontroller-paused" title="dom-MediaController-paused">paused</a>;
5570: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-played" title="dom-MediaController-played">played</a>;
5571: void <a href="#dom-mediacontroller-play" title="dom-MediaController-play">play</a>();
5572: void <a href="#dom-mediacontroller-pause" title="dom-MediaController-pause">pause</a>();
5573:
5574: attribute double <a href="#dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate">defaultPlaybackRate</a>;
5575: attribute double <a href="#dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate">playbackRate</a>;
5576:
5577: attribute double <a href="#dom-mediacontroller-volume" title="dom-MediaController-volume">volume</a>;
5578: attribute boolean <a href="#dom-mediacontroller-muted" title="dom-MediaController-muted">muted</a>;
5579:
1.68 mike 5580: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onemptied" title="handler-MediaController-onemptied">onemptied</a>;
5581: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata">onloadedmetadata</a>;
5582: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata">onloadeddata</a>;
5583: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay">oncanplay</a>;
5584: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough">oncanplaythrough</a>;
5585: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onplaying" title="handler-MediaController-onplaying">onplaying</a>;
1.75 mike 5586: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onended" title="handler-MediaController-onended">onended</a>;
1.68 mike 5587: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting">onwaiting</a>;
5588:
5589: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange">ondurationchange</a>;
5590: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate">ontimeupdate</a>;
5591: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onplay" title="handler-MediaController-onplay">onplay</a>;
5592: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onpause" title="handler-MediaController-onpause">onpause</a>;
5593: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onratechange" title="handler-MediaController-onratechange">onratechange</a>;
5594: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange">onvolumechange</a>;
1.47 mike 5595: };</pre><dl class="domintro"><dt><var title="">controller</var> = new <code title="dom-MediaController"><a href="#dom-mediacontroller">MediaController</a></code>()</dt>
5596:
5597: <dd>
5598:
5599: <p>Returns a new <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5600:
5601: </dd>
5602:
5603: <dt><var title="">media</var> . <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> [ = <var title="">controller</var> ]</dt>
5604:
5605: <dd>
5606:
5607: <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>
5608:
5609: <p>Can be set, to set an explicit <code><a href="#mediacontroller">MediaController</a></code>.
5610: Doing so removes the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if
5611: any.</p>
5612:
5613: </dd>
5614:
5615: <dt><var title="">controller</var> . <code title="dom-MediaController-buffered"><a href="#dom-mediacontroller-buffered">buffered</a></code></dt>
5616:
5617: <dd>
5618:
5619: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5620: intersection of the time ranges for which the user agent has all
5621: relevant media data for all the slaved <a href="#media-element" title="media
5622: element">media elements</a>.</p>
5623:
5624: </dd>
5625:
5626: <dt><var title="">controller</var> . <code title="dom-MediaController-seekable"><a href="#dom-mediacontroller-seekable">seekable</a></code></dt>
5627:
5628: <dd>
5629:
5630: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5631: intersection of the time ranges into which the user agent can seek
5632: for all the slaved <a href="#media-element" title="media element">media
5633: elements</a>.</p>
5634:
5635: </dd>
5636:
5637: <dt><var title="">controller</var> . <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code></dt>
5638:
5639: <dd>
5640:
5641: <p>Returns the difference between the earliest playable moment and
5642: the latest playable moment (not considering whether the data in
5643: question is actually buffered or directly seekable, but not
5644: including time in the future for infinite streams). Will return
5645: zero if there is no media.</p>
5646:
5647: </dd>
5648:
5649: <dt><var title="">controller</var> . <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
5650:
5651: <dd>
5652:
5653: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds,
5654: as a position between zero time and the current <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code>.</p>
5655:
5656: <p>Can be set, to seek to the given time.</p><p>
5657:
5658: </p></dd>
5659:
5660: <dt><var title="">controller</var> . <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code></dt>
5661:
5662: <dd>
5663:
5664: <p>Returns true if playback is paused; false otherwise. When this
5665: attribute is true, any <a href="#media-element">media element</a> slaved to this
5666: controller will be stopped.</p>
5667:
5668: </dd>
5669:
5670: <dt><var title="">controller</var> . <code title="dom-MediaController-played"><a href="#dom-mediacontroller-played">played</a></code></dt>
5671:
5672: <dd>
5673:
5674: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5675: union of the time ranges in all the slaved <a href="#media-element" title="media
5676: element">media elements</a> that have been played.</p>
5677:
5678: </dd>
5679:
5680: <dt><var title="">controller</var> . <code title="dom-MediaController-play"><a href="#dom-mediacontroller-play">play</a></code>()</dt>
5681:
5682: <dd>
5683:
5684: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5685: attribute to false.</p>
5686:
5687: </dd>
5688:
5689: <dt><var title="">controller</var> . <code title="dom-MediaController-pause"><a href="#dom-mediacontroller-pause">pause</a></code>()</dt>
5690:
5691: <dd>
5692:
5693: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5694: attribute to true.</p>
5695:
5696: </dd>
5697:
5698: <dt><var title="">controller</var> . <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
5699:
5700: <dd>
5701:
5702: <p>Returns the default rate of playback.</p>
5703:
5704: <p>Can be set, to change the default rate of playback.</p>
5705:
5706: <p>This default rate has no direct effect on playback, but if the
5707: user switches to a fast-forward mode, when they return to the
5708: normal playback mode, it is expected that rate of playback (<code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code>) will
5709: be returned to this default rate.</p>
5710:
5711: </dd>
5712:
5713: <dt><var title="">controller</var> . <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
5714:
5715: <dd>
5716:
5717: <p>Returns the current rate of playback.</p>
5718:
5719: <p>Can be set, to change the rate of playback.</p>
5720:
5721: </dd>
5722:
5723: <dt><var title="">controller</var> . <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
5724:
5725: <dd>
5726:
5727: <p>Returns the current playback volume multiplier, as a number in
5728: the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the
5729: loudest.</p>
5730:
5731: <p>Can be set, to change the volume multiplier.</p>
5732:
1.78 mike 5733: <p>Throws an <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
1.47 mike 5734: in the range 0.0 .. 1.0.</p>
5735:
5736: </dd>
5737:
5738: <dt><var title="">controller</var> . <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
5739:
5740: <dd>
5741:
5742: <p>Returns true if all audio is muted (regardless of other
5743: attributes either on the controller or on any <a href="#media-element" title="media
5744: element">media elements</a> slaved to this controller), and
5745: false otherwise.</p>
5746:
5747: <p>Can be set, to change whether the audio is muted or not.</p>
5748:
5749: </dd>
5750:
5751: </dl><div class="impl">
5752:
5753: <p>A <a href="#media-element">media element</a> can have a <dfn id="current-media-controller">current media
5754: controller</dfn>, which is a <code><a href="#mediacontroller">MediaController</a></code> object.
5755: 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
5756: not have a <a href="#current-media-controller">current media controller</a>. (If it is created
5757: <em>with</em> such an attribute, then that attribute initializes the
5758: <a href="#current-media-controller">current media controller</a>, as defined below.)</p>
5759:
5760: <p>The <dfn id="slaved-media-elements">slaved media elements</dfn> of a
5761: <code><a href="#mediacontroller">MediaController</a></code> are the <a href="#media-element" title="media
5762: element">media elements</a> whose <a href="#current-media-controller">current media
5763: controller</a> is that <code><a href="#mediacontroller">MediaController</a></code>. All the
5764: <a href="#slaved-media-elements">slaved media elements</a> of a <code><a href="#mediacontroller">MediaController</a></code>
5765: must use the same clock for their definition of their <a href="#media-timeline">media
5766: timeline</a>'s unit time.</p>
5767:
5768: <hr><p>The <dfn id="dom-media-controller" title="dom-media-controller"><code>controller</code></dfn> attribute
5769: on a <a href="#media-element">media element</a>, on getting, must return the
5770: element's <a href="#current-media-controller">current media controller</a>, if any, or null
5771: 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,
5772: and then set the <a href="#current-media-controller">current media controller</a> to the given
5773: value. If the given value is null, the element no longer has a
5774: <a href="#current-media-controller">current media controller</a>; if it is not null, then the
5775: 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
5776: new media controller</a>.</p>
5777:
5778: <hr><p>The <dfn id="dom-mediacontroller" title="dom-MediaController"><code>MediaController()</code></dfn>
5779: constructor, when invoked, must return a newly created
5780: <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5781:
5782: <hr><p>The <dfn id="dom-mediacontroller-seekable" title="dom-MediaController-seekable"><code>seekable</code></dfn>
5783: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5784: <code>TimeRanges</code> object</a> that represents the
5785: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5786: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5787: user agent is able to seek to, at the time the attribute is
5788: evaluated.</p>
5789:
5790: <p>The <dfn id="dom-mediacontroller-buffered" title="dom-MediaController-buffered"><code>buffered</code></dfn>
5791: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5792: <code>TimeRanges</code> object</a> that represents the
5793: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5794: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5795: user agent has buffered, at the time the attribute is evaluated.
5796: Users agents must accurately determine the ranges available, even
5797: for media streams where this can only be determined by tedious
5798: inspection.</p>
5799:
5800: <p>The <dfn id="dom-mediacontroller-duration" title="dom-MediaController-duration"><code>duration</code></dfn>
5801: attribute must return the <a href="#media-controller-duration">media controller
5802: duration</a>.</p>
5803:
5804: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5805: <a href="#media-controller-duration">media controller duration</a> changes, whichever happens
5806: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5807: <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>
5808: at the <code><a href="#mediacontroller">MediaController</a></code>. If the
5809: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-duration">media controller
5810: duration</a> decreases such that the <a href="#media-controller-position">media controller
5811: position</a> is greater than the <a href="#media-controller-duration">media controller
5812: duration</a>, the user agent must immediately <a href="#seek-the-media-controller">seek the
5813: media controller</a> to <a href="#media-controller-duration">media controller
5814: duration</a>.</p>
5815:
5816: <p>The <dfn id="dom-mediacontroller-currenttime" title="dom-MediaController-currentTime"><code>currentTime</code></dfn>
5817: attribute must return the <a href="#media-controller-position">media controller position</a> on
5818: getting, and on setting must <a href="#seek-the-media-controller">seek the media controller</a>
5819: to the new value.</p>
5820:
5821: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5822: <a href="#media-controller-position">media controller position</a> changes, whichever happens
5823: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5824: <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
5825: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5826:
5827: <hr><p>When a <code><a href="#mediacontroller">MediaController</a></code> is created it is a
5828: <dfn id="playing-media-controller">playing media controller</dfn>. It can be changed into a
5829: <dfn id="paused-media-controller">paused media controller</dfn> and back either via the user
5830: agent's user interface (when the element is <a href="#expose-a-user-interface-to-the-user" title="expose a
5831: user interface to the user">exposing a user interface to the
5832: user</a>) or by script using the APIs defined in this section
5833: (see below).</p>
5834:
5835: <p>The <dfn id="dom-mediacontroller-paused" title="dom-MediaController-paused"><code>paused</code></dfn>
5836: attribute must return true if the <code><a href="#mediacontroller">MediaController</a></code>
5837: object is a <a href="#paused-media-controller">paused media controller</a>, and false
5838: otherwise.</p>
5839:
5840: <p>The <dfn id="dom-mediacontroller-played" title="dom-MediaController-played"><code>played</code></dfn>
5841: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5842: <code>TimeRanges</code> object</a> that represents the union of
5843: the ranges of the <a href="#media-resource" title="media resource">media
5844: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5845: user agent has so far rendered, at the time the attribute is
5846: evaluated.</p>
5847:
5848: <p>When the <dfn id="dom-mediacontroller-pause" title="dom-MediaController-pause"><code>pause()</code></dfn> method
5849: is invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#playing-media-controller">playing
5850: media controller</a> then the user agent must change the
5851: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#paused-media-controller">paused media
5852: 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
5853: event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
5854: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
5855: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5856:
5857: <p>When the <dfn id="dom-mediacontroller-play" title="dom-MediaController-play"><code>play()</code></dfn> method is
5858: invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#paused-media-controller">paused media
5859: controller</a>, the user agent must change the
5860: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#playing-media-controller">playing media
5861: 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
5862: event</a> named <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code> at the
5863: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
5864: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5865:
5866: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-default-playback-rate">media controller
5867: default playback rate</dfn> and a <dfn id="media-controller-playback-rate">media controller playback
5868: rate</dfn>, which must both be set to 1.0 when the
5869: <code><a href="#mediacontroller">MediaController</a></code> object is created.</p>
5870:
5871: <p>The <dfn id="dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
5872: attribute, on getting, must return the
5873: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
5874: playback rate</a>, and on setting, must set the
5875: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
5876: playback rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a
5877: 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
5878: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5879:
5880: <p>The <dfn id="dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate"><code>playbackRate</code></dfn>
5881: attribute, on getting, must return the
5882: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
5883: rate</a>, and on setting, must set the
5884: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
5885: rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a task</a> to
5886: <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
5887: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5888:
5889: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-volume-multiplier">media controller volume
5890: multiplier</dfn>, which must be set to 1.0 when the
5891: <code><a href="#mediacontroller">MediaController</a></code> object is created, and a <dfn id="media-controller-mute-override">media
5892: controller mute override</dfn>, much must initially be false.</p>
5893:
5894: <p>The <dfn id="dom-mediacontroller-volume" title="dom-MediaController-volume"><code>volume</code></dfn>
5895: attribute, on getting, must return the
5896: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-volume-multiplier">media controller volume
5897: multiplier</a>, and on setting, if the new value is in the range
5898: 0.0 to 1.0 inclusive, must set the <code><a href="#mediacontroller">MediaController</a></code>'s
5899: <a href="#media-controller-volume-multiplier">media controller volume multiplier</a> to the new value and
5900: <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
5901: <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
5902: at the <code><a href="#mediacontroller">MediaController</a></code>. If the new value is outside the
5903: range 0.0 to 1.0 inclusive, then, on setting, an
1.78 mike 5904: <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
1.47 mike 5905:
5906: <p>The <dfn id="dom-mediacontroller-muted" title="dom-MediaController-muted"><code>muted</code></dfn>
5907: attribute, on getting, must return the
5908: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
5909: override</a>, and on setting, must set the
5910: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
5911: override</a> to the new value and <a href="webappapis.html#queue-a-task">queue a task</a> to
5912: <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
5913: the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5914:
5915: <hr><p>The <a href="#media-resource" title="media resource">media resources</a> of all
5916: the <a href="#slaved-media-elements">slaved media elements</a> of a
5917: <code><a href="#mediacontroller">MediaController</a></code> have a defined temporal relationship
5918: which provides relative offsets between the zero time of each such
5919: <a href="#media-resource">media resource</a>: for <a href="#media-resource" title="media resource">media
5920: resources</a> with a <a href="#timeline-offset">timeline offset</a>, their relative
5921: offsets are the difference between their <a href="#timeline-offset">timeline
5922: offset</a>; the zero times of all the <a href="#media-resource" title="media
5923: resource">media resources</a> without a <a href="#timeline-offset">timeline
5924: offset</a> are not offset from each other (i.e. the origins of
5925: their timelines are cotemporal); and finally, the zero time of the
5926: <a href="#media-resource">media resource</a> with the earliest <a href="#timeline-offset">timeline
5927: offset</a> (if any) is not offset from the zero times of the
5928: <a href="#media-resource" title="media resource">media resources</a> without a
5929: <a href="#timeline-offset">timeline offset</a> (i.e. the origins of <a href="#media-resource" title="media
5930: resource">media resources</a> without a <a href="#timeline-offset">timeline
5931: offset</a> are further cotemporal with the earliest defined point
5932: on the timeline of the <a href="#media-resource">media resource</a> with the earliest
5933: <a href="#timeline-offset">timeline offset</a>).</p>
5934:
5935: <p>The <dfn id="media-resource-end-position">media resource end position</dfn> of a <a href="#media-resource">media
5936: resource</a> in a <a href="#media-element">media element</a> is defined as
5937: follows: if the <a href="#media-resource">media resource</a> has a finite and known
5938: duration, the <a href="#media-resource-end-position">media resource end position</a> is the
5939: duration of the <a href="#media-resource">media resource</a>'s timeline (the last
5940: defined position on that timeline); otherwise, the <a href="#media-resource">media
5941: resource</a>'s duration is infinite or unknown, and the
5942: <a href="#media-resource-end-position">media resource end position</a> is the time of the last
5943: frame of <a href="#media-data">media data</a> currently available for that
5944: <a href="#media-resource">media resource</a>.</p>
5945:
5946: <p>Each <code><a href="#mediacontroller">MediaController</a></code> also has its own defined
5947: timeline. On this timeline, all the <a href="#media-resource" title="media
5948: resource">media resources</a> of all the <a href="#slaved-media-elements">slaved media
5949: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code> are temporally
5950: aligned according to their defined offsets. The <dfn id="media-controller-duration">media
5951: controller duration</dfn> of that <code><a href="#mediacontroller">MediaController</a></code> is
5952: the time from the earliest <a href="#earliest-possible-position">earliest possible position</a>,
5953: relative to this <code><a href="#mediacontroller">MediaController</a></code> timeline, of any of
5954: the <a href="#media-resource" title="media resource">media resources</a> of the
5955: <a href="#slaved-media-elements">slaved media elements</a> of the
5956: <code><a href="#mediacontroller">MediaController</a></code>, to the time of the latest <a href="#media-resource-end-position">media
5957: resource end position</a> of the <a href="#media-resource" title="media
5958: resource">media resources</a> of the <a href="#slaved-media-elements">slaved media
5959: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code>, again relative
5960: to this <code><a href="#mediacontroller">MediaController</a></code> timeline.</p>
5961:
5962: <p>Each <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-position">media controller
5963: position</dfn>. This is the time on the
5964: <code><a href="#mediacontroller">MediaController</a></code>'s timeline at which the user agent is
5965: trying to play the <a href="#slaved-media-elements">slaved media elements</a>. When a
5966: <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#media-controller-position">media controller
5967: position</a> is initially zero.</p>
5968:
5969: <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
5970: to speed with its new media controller">bring a media element up to
5971: 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>
5972: to the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-position">media controller
5973: position</a> relative to the <a href="#media-element">media element</a>'s
5974: timeline, discarding any resulting exceptions.</p>
5975:
5976: <p>When the user agent is to <dfn id="seek-the-media-controller">seek the media controller</dfn> to
5977: a particular <var title="">new playback position</var>, it must
5978: follow these steps:</p>
5979:
5980: <ol><li><p>If the <var title="">new playback position</var> is less
5981: than zero, then set it to zero.</p></li>
5982:
5983: <li><p>If the <var title="">new playback position</var> is greater
5984: than the <a href="#media-controller-duration">media controller duration</a>, then set it to the
5985: <a href="#media-controller-duration">media controller duration</a>.</p></li>
5986:
5987: <li><p>Set the <a href="#media-controller-position">media controller position</a> to the <var title="">new playback position</var>.</p></li>
5988:
5989: <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
5990: <var title="">new playback position</var> relative to the
5991: <a href="#media-element">media element</a> timeline, discarding any resulting
5992: exceptions.</p></li>
5993: </ol><p>A <code><a href="#mediacontroller">MediaController</a></code> is a <dfn id="blocked-media-controller">blocked media
5994: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
5995: <a href="#paused-media-controller">paused media controller</a>, or if any of its <a href="#slaved-media-elements">slaved
5996: media elements</a> are <a href="#blocked-media-element" title="blocked media
5997: element">blocked media elements</a>, or if any of its
5998: <a href="#slaved-media-elements">slaved media elements</a> whose <a href="#autoplaying-flag">autoplaying
1.70 mike 5999: 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 6000: 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>
6001:
6002: <p>A <a href="#media-element">media element</a> is <dfn id="blocked-on-its-media-controller">blocked on its media
6003: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
6004: <a href="#blocked-media-controller">blocked media controller</a>, or if its <a href="#media-controller-position">media
6005: controller position</a> is either before the <a href="#media-resource">media
6006: resource</a>'s <a href="#earliest-possible-position">earliest possible position</a> relative
6007: to the <code><a href="#mediacontroller">MediaController</a></code>'s timeline or after the end of
6008: the <a href="#media-resource">media resource</a> relative to the
6009: <code><a href="#mediacontroller">MediaController</a></code>'s timeline.</p>
6010:
6011: <p id="controller-playback">When a <code><a href="#mediacontroller">MediaController</a></code> is
6012: not a <a href="#blocked-media-controller">blocked media controller</a> and it has at least one
6013: <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a>
6014: whose <code><a href="infrastructure.html#document">Document</a></code> is a <a href="browsers.html#fully-active">fully active</a>
6015: <code><a href="infrastructure.html#document">Document</a></code>, the <code><a href="#mediacontroller">MediaController</a></code>'s
6016: <a href="#media-controller-position">media controller position</a> must increase monotonically
6017: at <a href="#media-controller-playback-rate">media controller playback rate</a> units of time on the
6018: <code><a href="#mediacontroller">MediaController</a></code>'s timeline per unit time of the clock
6019: used by its <a href="#slaved-media-elements">slaved media elements</a>.</p>
6020:
6021: <p>When the zero point on the timeline of a
6022: <code><a href="#mediacontroller">MediaController</a></code> moves relative to the timelines of the
6023: <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
6024: <a href="#media-controller-position">media controller position</a> must be decremented by <var title="">ΔT</var>.</p>
6025:
6026: <p class="note">In some situations, e.g. when playing back a live
6027: stream without buffering anything, the <a href="#media-controller-position">media controller
6028: position</a> would increase motonically as described above at the
6029: same rate as the <var title="">ΔT</var> described in the
6030: previous paragraph decreases it, with the end result that for all
6031: intents and purposes, the <a href="#media-controller-position">media controller position</a>
6032: would appear to remain constant (probably with the value 0).</p>
6033:
6034: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="most-recently-reported-readiness-state">most recently reported
6035: readiness state</dfn>, which is a number from 0 to 4 derived from
6036: the numbers used for the <a href="#media-element">media element</a> <code title="attr-media-readyState">readyState</code> attribute, and a
6037: <dfn id="most-recently-reported-playback-state">most recently reported playback state</dfn>, which is either
6038: <i>playing</i>, <i>waiting</i>, or <i>ended</i>.</p>
6039:
6040: <p>When a <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#most-recently-reported-readiness-state">most
6041: recently reported readiness state</a> must be set to 0, and its
6042: <a href="#most-recently-reported-playback-state">most recently reported playback state</a> must be set to
6043: <i>waiting</i>.</p>
6044:
6045: <p>When a user agent is required to <dfn id="report-the-controller-state">report the controller
6046: state</dfn> for a <code><a href="#mediacontroller">MediaController</a></code>, the user agent must
6047: run the following steps:</p>
6048:
6049: <ol><li>
6050:
6051: <p>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved media
6052: elements</a>, let <var title="">new readiness state</var> be
6053: 0.</p>
6054:
6055: <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
6056: all of its <a href="#slaved-media-elements">slaved media elements</a>.</p>
6057:
6058: </li>
6059:
6060: <li>
6061:
6062: <p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
6063: reported readiness state</a> is not equal to <var title="">new
6064: 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
6065: a simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
6066: whose name is the event name corresponding to the value of <var title="">new readiness state</var> given in the table below:</p>
6067:
6068:
6069: <table><thead><tr><th>Value of <var title="">new readiness state</var>
6070: </th><th>Event name
6071:
6072: </th></tr></thead><tbody><tr><td> 0
6073: </td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
6074:
6075: </td></tr><tr><td> 1
6076: </td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
6077:
6078: </td></tr><tr><td> 2
6079: </td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
6080:
6081: </td></tr><tr><td> 3
6082: </td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
6083:
6084: </td></tr><tr><td> 4
6085: </td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
6086:
6087: </td></tr></tbody></table></li>
6088:
6089: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
6090: reported readiness state</a> be <var title="">new readiness
6091: state</var>.</p></li>
6092:
6093: <li>
6094:
6095: <p>Initialize <var title="">new playback state</var> by setting it
6096: to the state given for the first matching condition from the
6097: following list:</p>
6098:
6099: <dl class="switch"><dt>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved
6100: media elements</a></dt>
6101:
6102: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
6103:
6104: <dt>If all of the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#slaved-media-elements">slaved
6105: media elements</a> have <a href="#ended-playback">ended playback</a> and the
6106: <a href="#media-controller-playback-rate">media controller playback rate</a> is positive or
6107: zero</dt>
6108:
6109: <dd>Let <var title="">new playback state</var> be <i>ended</i>.</dd>
6110:
6111: <dt>If the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#blocked-media-controller">blocked media
6112: controller</a></dt>
6113:
6114: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
6115:
6116: <dt>Otherwise</dt>
6117:
6118: <dd>Let <var title="">new playback state</var> be <i>playing</i>.</dd>
6119:
6120: </dl></li>
6121:
6122: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6123: reported playback state</a> is not equal to <var title="">new
6124: 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
6125: simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
1.75 mike 6126: 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 6127: otherwise.</p></li>
6128:
6129: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6130: reported playback state</a> be <var title="">new playback
6131: state</var>.</p></li>
6132:
6133: </ol><hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
6134: supported, as IDL attributes, by all objects implementing the
6135: <code><a href="#mediacontroller">MediaController</a></code> interface:</p>
6136:
6137: <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>
6138: </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>
6139: </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>
6140: </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>
6141: </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>
6142: </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>
6143: </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 6144: </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 6145: </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>
6146: </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 6147: </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 6148: </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>
6149: </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>
6150: </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>
6151: </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>
6152: </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
6153: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
6154:
6155: </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
6156: attribute on <a href="#media-element" title="media element">media elements</a> can
6157: be used to link multiple <a href="#media-element" title="media element">media
6158: elements</a> together by implicitly creating a
6159: <code><a href="#mediacontroller">MediaController</a></code>.</p><div class="impl">
6160:
6161: <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
6162: 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,
6163: changed, or removed, the user agent must run the following
6164: steps:</p>
6165:
6166: <ol><li><p>Let <var title="">m</var> be the <a href="#media-element">media element</a>
6167: in question.</p></li>
6168:
6169: <li><p>Let <var title="">m</var> have no <a href="#current-media-controller">current
6170: media controller</a>, if it currently has one.</p></li>
6171:
6172: <li><p>If <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is being
6173: removed, then abort these steps.</p></li>
6174:
6175: <li>
6176:
6177: <p>If there is another <a href="#media-element">media element</a> whose
6178: <code><a href="infrastructure.html#document">Document</a></code> is the same as <var title="">m</var>'s
6179: <code><a href="infrastructure.html#document">Document</a></code> (even if one or both of these elements are
6180: not actually <a href="infrastructure.html#in-a-document" title="in a Document"><em>in</em> the
6181: <code>Document</code></a>), and which also has a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and
6182: whose <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>
6183: 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
6184: let <var title="">controller</var> be that <a href="#media-element">media
6185: element</a>'s <a href="#current-media-controller">current media controller</a>.</p>
6186:
6187: <p>Otherwise, let <var title="">controller</var> be a newly created
6188: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6189:
6190: </li>
6191:
6192: <li><p>Let <var title="">m</var>'s <a href="#current-media-controller">current media
6193: controller</a> be <var title="">controller</var>.</p></li>
6194:
6195: <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
6196: controller</a>.</p></li>
6197:
6198: </ol><p>The <dfn id="dom-media-mediagroup" title="dom-media-mediaGroup"><code>mediaGroup</code></dfn> IDL
6199: attribute on <a href="#media-element" title="media element">media elements</a> must
6200: <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content
6201: attribute.</p>
6202:
6203: </div><div class="example">
6204:
6205: <p>Multiple <a href="#media-element" title="media element">media elements</a>
6206: referencing the same <a href="#media-resource">media resource</a> will share a
6207: single network request. This can be used to efficiently play two
6208: (video) tracks from the same <a href="#media-resource">media resource</a> in two
6209: different places on the screen. Used with the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, these
6210: elements can also be kept synchronised.</p>
6211:
6212: <p>In this example, a sign-languge interpreter track from a movie
6213: file is overlaid on the primary video track of that same video file
6214: using two <code><a href="#the-video-element">video</a></code> elements, some CSS, and an implicit
6215: <code><a href="#mediacontroller">MediaController</a></code>:</p>
6216:
6217: <pre><article>
6218: <style scoped>
6219: div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
6220: video { position; absolute; bottom: 0; right: 0; }
6221: video:first-child { width: 100%; height: 100%; }
6222: video:last-child { width: 30%; }
6223: </style>
6224: <div>
6225: <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
6226: <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
6227: </div>
6228: </article></pre>
6229:
6230: </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
6231: 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
6232: to <code><a href="#the-track-element">track</a></code> element children of the <a href="#media-element">media
6233: element</a>, in <a href="infrastructure.html#tree-order">tree order</a>.</li>
6234:
6235: <li>Any <a href="#text-track" title="text track">text tracks</a> added using
6236: the <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack()</a></code> method, in
6237: the order they were added, oldest first.</li>
6238:
6239: <li>Any <a href="#media-resource-specific-text-track" title="media-resource-specific text
6240: track">media-resource-specific text tracks</a> (<a href="#text-track" title="text track">text tracks</a> corresponding to data in
6241: the <a href="#media-resource">media resource</a>), in the order defined by the
6242: <a href="#media-resource">media resource</a>'s format specification.</li>
6243:
6244: </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>
6245:
6246: </dt><dd>
6247:
6248: <p>This decides how the track is handled by the user agent. The
6249: kind is represented by a string. The possible strings are:</p>
6250:
6251: <ul class="brief"><li><dfn id="dom-texttrack-kind-subtitles" title="dom-TextTrack-kind-subtitles"><code>subtitles</code></dfn>
6252: </li><li><dfn id="dom-texttrack-kind-captions" title="dom-TextTrack-kind-captions"><code>captions</code></dfn>
6253: </li><li><dfn id="dom-texttrack-kind-descriptions" title="dom-TextTrack-kind-descriptions"><code>descriptions</code></dfn>
6254: </li><li><dfn id="dom-texttrack-kind-chapters" title="dom-TextTrack-kind-chapters"><code>chapters</code></dfn>
6255: </li><li><dfn id="dom-texttrack-kind-metadata" title="dom-TextTrack-kind-metadata"><code>metadata</code></dfn>
6256: </li></ul><p>The <a href="#text-track-kind" title="text track kind">kind of track</a> can
6257: change dynamically, in the case of a <a href="#text-track">text track</a>
6258: corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6259:
6260: </dd>
6261:
6262: <dt><dfn id="text-track-label" title="text track label">A label</dfn>
6263:
6264: </dt><dd>
6265:
6266: <p>This is a human-readable string intended to identify the track
6267: for the user. In certain cases, the label might be generated
6268: automatically.</p>
6269:
6270: <p>The <a href="#text-track-label" title="text track label">label of a track</a> can
6271: change dynamically, in the case of a <a href="#text-track">text track</a>
6272: corresponding to a <code><a href="#the-track-element">track</a></code> element or in the case of an
6273: automatically-generated label whose value depends on variable
6274: factors such as the user's preferred user interface language.</p>
6275:
6276: </dd>
6277:
6278: <dt><dfn id="text-track-language" title="text track language">A language</dfn>
6279:
6280: </dt><dd>
6281:
6282: <p>This is a string (a BCP 47 language tag) representing the
6283: language of the text track's cues. <a href="references.html#refsBCP47">[BCP47]</a></p>
6284:
6285: <p>The <a href="#text-track-language" title="text track language">language of a text
6286: track</a> can change dynamically, in the case of a <a href="#text-track">text
6287: track</a> corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6288:
6289: </dd>
6290:
6291: <dt><dfn id="text-track-readiness-state" title="text track readiness state">A readiness state</dfn>
6292:
6293: </dt><dd>
6294:
6295: <p>One of the following:</p>
6296:
6297: <dl><dt><dfn id="text-track-not-loaded" title="text track not loaded">Not loaded</dfn>
6298:
6299: </dt><dd>
6300:
6301: <p>Indicates that the text track is known to exist (e.g. it has
6302: been declared with a <code><a href="#the-track-element">track</a></code> element), but its cues
6303: have not been obtained.</p>
6304:
6305: </dd>
6306:
6307: <dt><dfn id="text-track-loading" title="text track loading">Loading</dfn>
6308:
6309: </dt><dd>
6310:
6311: <p>Indicates that the text track is loading and there have been
6312: no fatal errors encountered so far. Further cues might still be
6313: added to the track.</p>
6314:
6315: </dd>
6316:
6317: <dt><dfn id="text-track-loaded" title="text track loaded">Loaded</dfn>
6318:
6319: </dt><dd>
6320:
6321: <p>Indicates that the text track has been loaded with no fatal
6322: errors. No new cues will be added to the track except if the
6323: <a href="#text-track">text track</a> corresponds to a
6324: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object.</p>
6325:
6326: </dd>
6327:
6328: <dt><dfn id="text-track-failed-to-load" title="text track failed to load">Failed to load</dfn>
6329:
6330: </dt><dd>
6331:
6332: <p>Indicates that the text track was enabled, but when the user
6333: agent attempted to obtain it, this failed in some way
6334: (e.g. <a href="urls.html#url">URL</a> could not be <a href="urls.html#resolve-a-url" title="resolve a
6335: url">resolved</a>, network error, unknown text track
6336: format). Some or all of the cues are likely missing and will not
6337: be obtained.</p>
6338:
6339: </dd>
6340:
6341: </dl><p>The <a href="#text-track-readiness-state" title="text track readiness state">readiness
6342: state</a> of a <a href="#text-track">text track</a> changes dynamically as
6343: the track is obtained.</p>
6344:
6345: </dd>
6346:
6347: <dt><dfn id="text-track-mode" title="text track mode">A mode</dfn>
6348:
6349: </dt><dd>
6350:
6351: <p>One of the following:</p>
6352:
6353: <dl><dt><dfn id="text-track-disabled" title="text track disabled">Disabled</dfn>
6354:
6355: </dt><dd>
6356:
6357: <p>Indicates that the text track is not active. Other than for
6358: the purposes of exposing the track in the DOM, the user agent is
6359: ignoring the text track. No cues are active, no events are
6360: fired, and the user agent will not attempt to obtain the track's
6361: cues.</p>
6362:
6363: </dd>
6364:
6365: <dt><dfn id="text-track-hidden" title="text track hidden">Hidden</dfn>
6366:
6367: </dt><dd>
6368:
6369: <p>Indicates that the text track is active, but that the user
6370: agent is not actively displaying the cues. If no attempt has yet
6371: been made to obtain the track's cues, the user agent will
6372: perform such an attempt momentarily. The user agent is
6373: maintaining a list of which cues are active, and events are
6374: being fired accordingly.</p>
6375:
6376: </dd>
6377:
6378: <dt><dfn id="text-track-showing" title="text track showing">Showing</dfn>
6379: <dt><dfn id="text-track-showing-by-default" title="text track showing by default">Showing by default</dfn>
6380:
6381: </dt></dt><dd>
6382:
6383: <p>Indicates that the text track is active. If no attempt has
6384: yet been made to obtain the track's cues, the user agent will
6385: perform such an attempt momentarily. The user agent is
6386: maintaining a list of which cues are active, and events are
6387: being fired accordingly. In addition, for text tracks whose
6388: <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
6389: are being displayed over the video as appropriate; for text
6390: tracks whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-descriptions">descriptions</code>,
6391: the user agent is making the cues available to the user in a
6392: non-visual fashion; and for text tracks whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-chapters">chapters</code>, the user
6393: agent is making available to the user a mechanism by which the
6394: user can navigate to any point in the <a href="#media-resource">media
6395: resource</a> by selecting a cue.</p>
6396:
6397: <p>The <a href="#text-track-showing-by-default" title="text track showing by default">showing by
6398: default</a> state is used in conjunction with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute on
6399: <code><a href="#the-track-element">track</a></code> elements to indicate that the text track was
6400: enabled due to that attribute. This allows the user agent to
6401: override the state if a later track is discovered that is more
6402: appropriate per the user's preferences.</p>
6403:
6404: </dd>
6405:
6406: </dl></dd>
6407:
6408: <dt><dfn id="text-track-list-of-cues" title="text track list of cues">A list of zero or more cues</dfn>
6409:
6410: </dt><dd>
6411:
6412: <p>A list of <a href="#text-track-cue" title="text track cue">text track
6413: cues</a>, along with <dfn id="rules-for-updating-the-text-track-rendering">rules for updating the text track
6414: rendering</dfn>.
6415: </p>
6416:
6417: <p>The <a href="#text-track-list-of-cues" title="text track list of cues">list of cues of a
6418: text track</a> can change dynamically, either because the
6419: <a href="#text-track">text track</a> has <a href="#text-track-not-loaded" title="text track not
6420: loaded">not yet been loaded</a> or is still <a href="#text-track-loading" title="text
6421: track loading">loading</a>, or because the <a href="#text-track">text
6422: track</a> corresponds to a <code><a href="#mutabletexttrack">MutableTextTrack</a></code>
6423: object, whose API allows individual cues can be added or removed
6424: dynamically.</p>
6425:
6426: </dd>
6427:
6428: </dl><p>Each <a href="#text-track">text track</a> has a corresponding
6429: <code><a href="#texttrack">TextTrack</a></code> object.</p><p>The <a href="#text-track" title="text track">text tracks</a> of a
6430: <a href="#media-element">media element</a> are <dfn id="the-text-tracks-are-ready" title="the text tracks are
6431: ready">ready</dfn> if all the <a href="#text-track" title="text track">text
6432: tracks</a> whose <a href="#text-track-mode" title="text track mode">mode</a> was
6433: not in the <a href="#text-track-disabled" title="text track disabled">disabled</a> state
6434: when the element's <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
6435: algorithm</a> last started now have a <a href="#text-track-readiness-state">text track readiness
6436: state</a> of <a href="#text-track-loaded" title="text track loaded">loaded</a> or
6437: <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
6438: in a <a href="#text-track">text track</a>, corresponding for instance for
6439: subtitles and captions to the text that appears at a particular time
6440: 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>
6441: </dt><dd>
6442: <p>An arbitrary string.</p>
6443: </dd>
6444:
6445: <dt><dfn id="text-track-cue-start-time" title="text track cue start time">A start time</dfn>
6446: </dt><dd>
6447: <p>A time, in seconds and fractions of a second, at which the cue
6448: becomes relevant.</p>
6449: </dd>
6450:
6451: <dt><dfn id="text-track-cue-end-time" title="text track cue end time">An end time</dfn>
6452: </dt><dd>
6453: <p>A time, in seconds and fractions of a second, at which the cue
6454: stops being relevant.</p>
6455: </dd>
6456:
6457: <dt><dfn id="text-track-cue-pause-on-exit-flag" title="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
6458: </dt><dd>
6459: <p>A boolean indicating whether playback of the <a href="#media-resource">media
6460: resource</a> is to pause when the cue stops being relevant.</p>
6461: </dd>
6462:
6463: <dt><dfn id="text-track-cue-writing-direction" title="text track cue writing direction">A writing direction</dfn>
6464: </dt><dd>
6465: <p>A writing direction, either <dfn id="text-track-cue-horizontal-writing-direction" title="text track cue
6466: horizontal writing direction">horizontal</dfn> (a line extends
6467: horizontally and is positioned vertically, with consecutive lines
6468: displayed below each other), <dfn id="text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical
6469: growing left writing direction">vertical growing left</dfn> (a
6470: line extends vertically and is positioned horizontally, with
6471: 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
6472: growing right writing direction">vertical growing right</dfn> (a
6473: line extends vertically and is positioned horizontally, with
6474: consecutive lines displayed to the right of each other).</p>
6475:
6476:
6477: </dd>
6478:
6479:
6480: <dt><dfn id="text-track-cue-size" title="text track cue size">A size</dfn>
6481: </dt><dd>
6482: <p>A number giving the size of the box within which the text of
6483: each line of the cue is to be aligned, to be interpreted as a
6484: percentage of the video, as defined by the <a href="#text-track-cue-writing-direction" title="text
6485: track cue writing direction">writing direction</a>.</p>
6486: </dd>
6487:
6488:
6489: <dt><dfn id="text-track-cue-text" title="text track cue text">The text of the cue</dfn>
6490: </dt><dd>
6491: <p>The raw text of the cue, and rules for its interpretation,
6492: allowing the text to be rendered and converted to a DOM fragment.</p>
6493: </dd>
6494:
6495: </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
6496: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and can be associated with a
6497: particular <a href="#text-track">text track</a>. Once a <a href="#text-track-cue">text track
6498: cue</a> is associated with a particular <a href="#text-track">text track</a>,
6499: the association is permanent.</p><p>In addition, each <a href="#text-track-cue">text track cue</a> has two pieces of
6500: dynamic information:</p><dl><dt>The <dfn id="text-track-cue-active-flag" title="text track cue active flag">active flag</dfn>
6501: </dt><dd>
6502:
6503: <p>This flag must be initially unset. The flag is used to ensure
6504: events are fired appropriately when the cue becomes active or
6505: inactive, and to make sure the right cues are rendered.</p>
6506:
6507: <p>The user agent must synchronously unset this flag whenever the
6508: <a href="#text-track-cue">text track cue</a> is removed from its <a href="#text-track">text
6509: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>; whenever the
6510: <a href="#text-track">text track</a> itself is removed from its <a href="#media-element">media
6511: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> or has its
6512: <a href="#text-track-mode">text track mode</a> changed to <a href="#text-track-disabled" title="text track
6513: disabled">disabled</a>; and whenever the <a href="#media-element">media
6514: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is changed back to
6515: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>. When the
6516: 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
6517: track showing by default">showing by default</a> prior to the
6518: relevant incident, the user agent must, after having unset the
6519: flag for all the affected cues, apply the <a href="#rules-for-updating-the-text-track-rendering">rules for updating
6520: the text track rendering</a> of those <a href="#text-track" title="text
6521: track">text tracks</a>.
6522: </p></dd>
6523:
6524: <dt>The <dfn id="text-track-cue-display-state" title="text track cue display state">display state</dfn>
6525: </dt><dd>
6526:
6527: <p>This is used as part of the rendering model, to keep cues in a
6528: consistent position. It must initially be empty. Whenever the
6529: <a href="#text-track-cue-active-flag">text track cue active flag</a> is unset, the user agent
6530: must empty the <a href="#text-track-cue-display-state">text track cue display state</a>.</p>
6531:
6532: </dd>
6533:
6534: </dl><p>The <a href="#text-track-cue" title="text track cue">text track cues</a> of a
6535: <a href="#media-element">media element</a>'s <a href="#text-track" title="text track">text
6536: tracks</a> are ordered relative to each other in the <dfn id="text-track-cue-order">text
6537: track cue order</dfn>, which is determined as follows: first group
6538: the <a href="#text-track-cue" title="text track cue">cues</a> by their <a href="#text-track">text
6539: track</a>, with the groups being sorted in the same order as
6540: their <a href="#text-track" title="text track">text tracks</a> appear in the
6541: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>;
6542: then, within each group, <a href="#text-track-cue" title="text track cue">cues</a>
6543: must be sorted by their <a href="#text-track-cue-start-time" title="text track cue start
6544: 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
6545: track cue start time">start time</a> must be sorted by their
6546: <a href="#text-track-cue-end-time" title="text track cue end time">end time</a>, earliest
6547: first; and finally, any <a href="#text-track-cue" title="text track cue">cues</a>
6548: with identical <a href="#text-track-cue-end-time" title="text track cue end time">end
6549: times</a> must be sorted in the order they were created (so
6550: e.g. for cues from a <span>WebVTT</span> file, that would be the
6551: 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
6552: track</a> that corresponds to data found in the <a href="#media-resource">media
6553: resource</a>.</p><div class="impl">
6554:
6555: <p>Rules for processing and rendering such data are defined by the
6556: relevant specifications, e.g. the specification of the video format
6557: if the <a href="#media-resource">media resource</a> is a video.</p>
6558:
6559: <p>When a <a href="#media-resource">media resource</a> contains data that the user
6560: agent recognises and supports as being equivalent to a <a href="#text-track">text
6561: track</a>, the user agent <a href="#found-a-media-resource-specific-timed-track">runs</a> the
6562: <dfn id="steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text track</dfn>
6563: with the relevant data, as follows:</p>
6564:
6565: <ol><li><p>Associate the relevant data with a new <a href="#text-track">text
6566: track</a> and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6567: object. The <a href="#text-track">text track</a> is a
6568: <a href="#media-resource-specific-text-track">media-resource-specific text track</a>.</p></li>
6569:
6570: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-kind" title="text track
6571: kind">kind</a>, <a href="#text-track-label" title="text track label">label</a>,
6572: and <a href="#text-track-language" title="text track language">language</a> based on the
6573: semantics of the relevant data, as defined by the relevant
6574: specification.</p></li>
6575:
6576: <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
6577: parsed so far, folllowing the <span>guidelines for exposing
6578: cues</span>, and begin updating it dynamically as
6579: necessary.</p></li>
6580:
6581: <li>
6582:
6583: <p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-readiness-state" title="text track
6584: readiness state">readiness state</a> to the value that most
6585: correctly describes the current state, and begin updating it
6586: dynamically as necessary.</p>
6587:
6588: <p class="example">For example, if the relevant data in the
6589: <a href="#media-resource">media resource</a> has been fully parsed and completely
6590: describes the cues, then the <a href="#text-track">text track</a> would be
6591: <a href="#text-track-loaded" title="text track loaded">loaded</a>. On the other hand,
6592: if the data for the cues is interleaved with the <a href="#media-data">media
6593: data</a>, and the <a href="#media-resource">media resource</a> as a whole is
6594: still being downloaded, then the <a href="#text-track-loading" title="text track
6595: loading">loading</a> state might be more accurate.</p>
6596:
6597: </li>
6598:
6599: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-mode" title="text
6600: track mode">mode</a> to the mode consistent with the user's
6601: preferences and the requirements of the relevant specification for
6602: the data.</p></li>
6603:
6604: <li><p>Leave the <a href="#text-track-list-of-cues">text track list of cues</a> empty, and
6605: associate with it the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
6606: rendering</a> appropriate for the format in question.</p>
6607:
6608: </li><li><p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6609: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p></li>
6610:
6611: </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
6612: element's media-resource-specific text tracks</dfn>, the user
6613: agent must remove from the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list
6614: of text tracks</a> all the <a href="#media-resource-specific-text-track" title="media-resource-specific
6615: text track">media-resource-specific text tracks</a>.</p>
6616:
6617: </div><div class="impl">
6618:
6619: <h6 id="sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</h6>
6620:
6621: <p>When a <code><a href="#the-track-element">track</a></code> element is created, it must be
6622: associated with a new <a href="#text-track">text track</a> (with its value set
6623: as defined below) and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6624: object.</p>
6625:
6626: <p>The <a href="#text-track-kind">text track kind</a> is determined from the state of
6627: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute
6628: according to the following table; for a state given in a cell of the
6629: first column, the <a href="#text-track-kind" title="text track kind">kind</a> is the
6630: string given in the second column:</p>
6631:
6632: <table><thead><tr><th>State
6633: </th><th>String
6634: </th></tr></thead><tbody><tr><td><a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</a>
6635: </td><td><code title="dom-timedtrack-kind-subtitles">subtitles</code>
6636: </td></tr><tr><td><a href="#attr-track-kind-captions" title="attr-track-kind-captions">Captions</a>
6637: </td><td><code title="dom-timedtrack-kind-captions">captions</code>
6638: </td></tr><tr><td><a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</a>
6639: </td><td><code title="dom-timedtrack-kind-descriptions">descriptions</code>
6640: </td></tr><tr><td><a href="#attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</a>
6641: </td><td><code title="dom-timedtrack-kind-chapters">chapters</code>
6642: </td></tr><tr><td><a href="#attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</a>
6643: </td><td><code title="dom-timedtrack-kind-metadata">metadata</code>
6644: </td></tr></tbody></table><p>The <a href="#text-track-label">text track label</a> is the element's <a href="#track-label">track
6645: label</a>.</p>
6646:
6647: <p>The <a href="#text-track-language">text track language</a> is the element's
6648: <a href="#track-language">track language</a>, if any, or the empty string
6649: otherwise.</p>
6650:
6651: <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,
6652: changed, or removed, the <a href="#text-track">text track</a> must update
6653: accordingly, as per the definitions above.</p>
6654:
6655: <p class="note">Changes to the <a href="#track-url">track URL</a> are handled in
6656: the algorithm below.</p>
6657:
6658: <p>The <a href="#text-track-list-of-cues">text track list of cues</a> is initially empty. It
6659: is dynamically modified when the referenced file is parsed.
6660: Associated with the list are the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text
6661: track rendering</a> appropriate for the format in question; for
6662: <span>WebVTT</span>, this is the <a href="rendering.html#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the
6663: display of WebVTT text tracks</a>.</p>
6664:
6665: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6666: the new parent is a <a href="#media-element">media element</a>, then the user agent
6667: must add the <code><a href="#the-track-element">track</a></code> element's corresponding <a href="#text-track">text
6668: track</a> to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
6669: tracks</a>.</p>
6670:
6671: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6672: the old parent was a <a href="#media-element">media element</a>, then the user agent
6673: must remove the <code><a href="#the-track-element">track</a></code> element's corresponding
6674: <a href="#text-track">text track</a> from the <a href="#media-element">media element</a>'s
6675: <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6676:
6677: <p>When a <a href="#text-track">text track</a> corresponding to a
6678: <code><a href="#the-track-element">track</a></code> element is added to a <a href="#media-element">media
6679: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, the user agent
6680: must set the <a href="#text-track-mode">text track mode</a> appropriately, as
6681: determined by the following conditions:</p>
6682:
6683: <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
6684: has indicated an interest in having a track with this <a href="#text-track-kind">text
6685: track kind</a>, <a href="#text-track-language">text track language</a>, and
6686: <a href="#text-track-label">text track label</a> enabled, and there is no other
6687: <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6688: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6689: 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
6690: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6691: showing">showing</a></dt>
6692:
6693: <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
6694: the user has indicated an interest in having text descriptions with
6695: this <a href="#text-track-language">text track language</a> and <a href="#text-track-label">text track
6696: label</a> enabled, and there is no other <a href="#text-track">text
6697: track</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
6698: 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
6699: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6700: showing">showing</a></dt>
6701:
1.62 mike 6702: <dd>
6703: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6704: track showing">showing</a>.</p>
6705:
6706: <p>If there is a <a href="#text-track">text track</a> in the <a href="#media-element">media
6707: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6708: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing-by-default" title="text track showing
6709: by default">showing by default</a>, the user agent must
6710: furthermore change <em>that</em> <a href="#text-track">text track</a>'s
6711: <a href="#text-track-mode">text track mode</a> to <a href="#text-track-hidden" title="text track
6712: hidden">hidden</a>.</p>
6713: </dd>
6714:
1.47 mike 6715: <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
6716: <a href="#text-track-language">text track language</a> is one that the user agent has
6717: reason to believe is appropriate for the user, and there is no
6718: other <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6719: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6720: kind</a> of <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> whose
6721: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6722: showing">showing</a></dt>
6723:
6724: <dd>
6725: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6726: track showing">showing</a>.</p>
6727: </dd>
6728:
6729: <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
6730: there is no other <a href="#text-track">text track</a> in the <a href="#media-element">media
6731: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6732: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6733: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track
6734: showing by default">showing by default</a></dt>
6735:
6736: <dd>
6737: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing-by-default" title="text
6738: track showing by default">showing by default</a>.</p>
6739: </dd>
6740:
6741: <dt>Otherwise</dt>
6742:
6743: <dd>
6744: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-disabled" title="text
6745: track disabled">disabled</a>.</p>
6746: </dd>
6747:
6748: </dl><p>When a <a href="#text-track">text track</a> corresponding to a
6749: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6750: mode</a> set to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6751: <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>,
6752: and when a <a href="#text-track">text track</a> corresponding to a
6753: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6754: mode</a> set to <a href="#text-track-disabled" title="text track
6755: disabled">disabled</a> and subsequently changes its <a href="#text-track-mode">text
6756: track mode</a> to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6757: <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
6758: the first time, the user agent must immediately and synchronously
6759: run the following algorithm. This algorithm interacts closely with
6760: the <a href="webappapis.html#event-loop">event loop</a> mechanism; in particular, it has a
6761: <a href="webappapis.html#synchronous-section">synchronous section</a> (which is triggered as part of the
6762: <a href="webappapis.html#event-loop">event loop</a> algorithm). The step in that section is
6763: marked with ⌛.</p>
6764:
6765: <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>
6766:
6767: <li><p>Let <var title="">URL</var> be the <a href="#track-url">track URL</a> of
6768: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6769:
6770: <li><p>Asynchronously run the remaining steps, while continuing
6771: with whatever task was responsible for creating the <a href="#text-track">text
6772: track</a> or changing the <a href="#text-track-mode">text track
6773: mode</a>.</p></li>
6774:
6775: <li>
6776:
1.61 mike 6777: <p><i>Download</i>: At this point, the text track is downloaded.</p>
6778:
6779: <p>If <var title="">URL</var> is not the empty string, perform a
6780: <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
6781: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
6782: attribute, the <i><a href="origin-0.html#origin">origin</a></i> being the <a href="origin-0.html#origin">origin</a> of the
6783: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
6784: <i>default origin behaviour</i> set to <i>fail</i>.</p>
6785:
6786: <p>The resource obtained in this fashion, if any, contains the
6787: text track data. If any data is obtained, it is by definition
6788: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a> (cross-origin resources that are not
6789: suitably CORS-enabled do not get this far).</p>
6790:
1.47 mike 6791: <p>The <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue
6792: a task">queued</a> by the <a href="fetching-resources.html#fetch" title="fetch">fetching
6793: algorithm</a> on the <a href="webappapis.html#networking-task-source">networking task source</a> to
6794: process the data as it is being fetched must examine the
6795: resource's <a href="fetching-resources.html#content-type" title="Content-Type">Content Type
6796: metadata</a>, once it is available, if it ever is. If no <a href="fetching-resources.html#content-type" title="Content-Type">Content Type metadata</a> is ever
6797: available, or if the type is not recognised as a text track
6798: format, then the resource's format must be assumed to be
6799: unsupported (this causes the load to fail, as described below). If
6800: a type is obtained, and represents a supported text track format,
6801: then the resource's data must be passed to the appropriate parser
6802: as it is received, with the <a href="#text-track-list-of-cues">text
6803: track list of cues</a> being used for that parser's output.</p>
6804:
6805: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> fails for
6806: any reason (network error, the server returns an error code, a
1.61 mike 6807: cross-origin check fails, etc), if <var title="">URL</var> is the
6808: empty string, or if the fetched resource is not in a supported
6809: format, then <a href="webappapis.html#queue-a-task">queue a task</a> to first change the
6810: <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-failed-to-load" title="text track
6811: failed to load">failed to load</a> and then <a href="webappapis.html#fire-a-simple-event">fire a simple
6812: event</a> named <code title="event-error">error</code> at the
6813: <code><a href="#the-track-element">track</a></code> 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 6814: task">queued</a>, move on to the step below labeled
6815: <i>monitoring</i>.</p>
6816:
6817: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> does not
6818: fail, then, when it completes, <a href="webappapis.html#queue-a-task">queue a task</a> to first
6819: change the <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-loaded" title="text track loaded">loaded</a> and then <a href="webappapis.html#fire-a-simple-event">fire a
6820: simple event</a> named <code title="event-load">load</code> at
6821: the <code><a href="#the-track-element">track</a></code> 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
6822: task">queued</a>, move on to the step below labeled
6823: <i>monitoring</i>.</p>
6824:
6825: <p>If, while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> is
6826: active, either:</p>
6827:
6828: <ul><li>the <a href="#track-url">track URL</a> changes so that it is no longer
6829: equal to <var title="">URL</var>, while the <a href="#text-track-mode">text track
6830: mode</a> is set to <a href="#text-track-hidden" title="text track
6831: hidden">hidden</a>, <a href="#text-track-showing" title="text track
6832: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
6833: default">showing by default</a>; or</li>
6834:
6835: <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
6836: track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track
6837: showing by default">showing by default</a>, while the
6838: <a href="#track-url">track URL</a> is not equal to <var title="">URL</var></li>
6839:
6840: </ul><p>...then the user agent must run the following steps:</p>
6841:
6842: <ol><li><p>Abort the <a href="fetching-resources.html#fetch" title="fetch">fetching
6843: algorithm</a>.</p></li>
6844:
6845: <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
6846: event</a> named <code title="event-abort">abort</code> at
6847: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6848:
6849: <li><p>Let <var title="">URL</var> be the new <a href="#track-url">track
6850: URL</a>.</p></li>
6851:
6852: <li><p>Jump back to the top of the step labeled
6853: <i>download</i>.</p></li>
6854:
6855: </ol><p>Until one of the above circumstances occurs, the user agent
6856: must remain on this step.</p>
6857:
6858: </li>
6859:
6860: <li><p><i>Monitoring</i>: Wait until the <a href="#track-url">track URL</a> is
6861: no longer equal to <var title="">URL</var>, at the same time as the
6862: <a href="#text-track-mode">text track mode</a> is set to <a href="#text-track-hidden" title="text track
6863: hidden">hidden</a>, <a href="#text-track-showing" title="text track
6864: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
6865: default">showing by default</a>.</p></li>
6866:
6867: <li><p>Wait until the <a href="#text-track-readiness-state">text track readiness state</a> is
6868: no longer set to <a href="#text-track-loading" title="text track
6869: loading">loading</a>.</p></li>
6870:
6871: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
6872: section</a> consists of the following step. (The step in the
6873: <a href="webappapis.html#synchronous-section">synchronous section</a> is marked with ⌛.)</p></li>
6874:
6875: <li><p>⌛ Set the <a href="#text-track-readiness-state">text track readiness state</a> to
6876: <a href="#text-track-loading" title="text track loading">loading</a>.</p></li>
6877:
6878:
6879: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
6880: remaining steps asynchronously.</p></li>
6881:
6882: <li><p>Jump to the step labeled <i>download</i>.</p></li>
6883:
6884: </ol></div><h6 id="text-track-api"><span class="secno">4.8.10.12.4 </span>Text track API</h6><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>
6885: <dd>
6886: <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>
6887: </dd>
6888:
6889: <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>
6890: <dd>
6891: <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>
6892: </dd>
6893:
6894: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
6895: <dd>
6896: <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>
6897: </dd>
6898:
6899: </dl><div class="impl">
6900:
6901: <p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn>
6902: attribute of <a href="#media-element" title="media element">media elements</a> must
1.92 mike 6903: return an <a href="infrastructure.html#platform-array-objects" title="platform array objects">platform array object</a>
1.47 mike 6904: for objects of type <code><a href="#texttrack">TextTrack</a></code> that is <i>fixed
6905: length</i> and <i>read only</i>. The same object must be returned
6906: each time the attribute is accessed. <a href="references.html#refsWEBIDL">[WEBIDL]</a></p>
6907:
6908: <p>The array must contain the <code><a href="#texttrack">TextTrack</a></code> objects of the
6909: <a href="#text-track" title="text track">text tracks</a> in the <a href="#media-element">media
6910: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, in the same
6911: order as in the <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6912:
1.86 mike 6913: </div><hr><pre class="idl">interface <dfn id="texttrack">TextTrack</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.47 mike 6914: readonly attribute DOMString <a href="#dom-texttrack-kind" title="dom-TextTrack-kind">kind</a>;
6915: readonly attribute DOMString <a href="#dom-texttrack-label" title="dom-TextTrack-label">label</a>;
6916: readonly attribute DOMString <a href="#dom-texttrack-language" title="dom-TextTrack-language">language</a>;
6917:
6918: const unsigned short <a href="#dom-texttrack-none" title="dom-TextTrack-NONE">NONE</a> = 0;
6919: const unsigned short <a href="#dom-texttrack-loading" title="dom-TextTrack-LOADING">LOADING</a> = 1;
6920: const unsigned short <a href="#dom-texttrack-loaded" title="dom-TextTrack-LOADED">LOADED</a> = 2;
6921: const unsigned short <a href="#dom-texttrack-error" title="dom-TextTrack-ERROR">ERROR</a> = 3;
6922: readonly attribute unsigned short <a href="#dom-texttrack-readystate" title="dom-TextTrack-readyState">readyState</a>;
1.68 mike 6923: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrack-onload" title="handler-TextTrack-onload">onload</a>;
6924: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrack-onerror" title="handler-TextTrack-onerror">onerror</a>;
1.47 mike 6925:
6926: const unsigned short <a href="#dom-texttrack-off" title="dom-TextTrack-OFF">OFF</a> = 0;
6927: const unsigned short <a href="#dom-texttrack-hidden" title="dom-TextTrack-HIDDEN">HIDDEN</a> = 1;
6928: const unsigned short <a href="#dom-texttrack-showing" title="dom-TextTrack-SHOWING">SHOWING</a> = 2;
6929: attribute unsigned short <a href="#dom-texttrack-mode" title="dom-TextTrack-mode">mode</a>;
6930:
1.68 mike 6931: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a>? <a href="#dom-texttrack-cues" title="dom-TextTrack-cues">cues</a>;
6932: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a>? <a href="#dom-texttrack-activecues" title="dom-TextTrack-activeCues">activeCues</a>;
1.47 mike 6933:
1.68 mike 6934: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
1.47 mike 6935: };
1.76 mike 6936:
6937: typedef <a href="#texttrack">TextTrack</a>[] <dfn id="texttracklist">TextTrackList</dfn>;</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 6938: <dd>
6939: <p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
6940: </dd>
6941:
6942: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-label"><a href="#dom-texttrack-label">label</a></code></dt>
6943: <dd>
6944: <p>Returns the <a href="#text-track-label">text track label</a>.</p>
6945: </dd>
6946:
6947: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-language"><a href="#dom-texttrack-language">language</a></code></dt>
6948: <dd>
6949: <p>Returns the <a href="#text-track-language">text track language</a> string.</p>
6950: </dd>
6951:
6952: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-readyState"><a href="#dom-texttrack-readystate">readyState</a></code></dt>
6953: <dd>
6954: <p>Returns the <a href="#text-track-readiness-state">text track readiness state</a>,
6955: represented by a number from the following list:</p>
6956: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-NONE"><a href="#dom-texttrack-none">NONE</a></code> (0)</dt>
6957: <dd>
6958: <p>The <a href="#text-track-not-loaded">text track not loaded</a> state.</p>
6959: </dd>
6960: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADING"><a href="#dom-texttrack-loading">LOADING</a></code> (1)</dt>
6961: <dd>
6962: <p>The <a href="#text-track-loading">text track loading</a> state.</p>
6963: </dd>
6964: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADED"><a href="#dom-texttrack-loaded">LOADED</a></code> (2)</dt>
6965: <dd>
6966: <p>The <a href="#text-track-loaded">text track loaded</a> state.</p>
6967: </dd>
6968: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-ERROR"><a href="#dom-texttrack-error">ERROR</a></code> (3)</dt>
6969: <dd>
6970: <p>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</p>
6971: </dd>
6972: </dl></dd>
6973:
6974: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code></dt>
6975: <dd>
6976: <p>Returns the <a href="#text-track-mode">text track mode</a>, represented by a
6977: number from the following list:</p>
6978: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-OFF"><a href="#dom-texttrack-off">OFF</a></code> (0)</dt>
6979: <dd>
6980: <p>The <a href="#text-track-disabled">text track disabled</a> mode.</p>
6981: </dd>
6982: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-HIDDEN"><a href="#dom-texttrack-hidden">HIDDEN</a></code> (1)</dt>
6983: <dd>
6984: <p>The <a href="#text-track-hidden">text track hidden</a> mode.</p>
6985: </dd>
6986: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-SHOWING"><a href="#dom-texttrack-showing">SHOWING</a></code> (2)</dt>
6987: <dd>
6988: <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>
6989: </dd>
6990: </dl><p>Can be set, to change the mode.</p>
6991: </dd>
6992:
6993: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-cues"><a href="#dom-texttrack-cues">cues</a></code></dt>
6994: <dd>
6995: <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>
6996: </dd>
6997:
6998: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-activeCues"><a href="#dom-texttrack-activecues">activeCues</a></code></dt>
6999: <dd>
7000: <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>
7001: </dd>
7002:
7003: </dl><div class="impl">
7004:
7005: <p>The <dfn id="dom-texttrack-kind" title="dom-TextTrack-kind"><code>kind</code></dfn>
7006: attribute must return the <a href="#text-track-kind">text track kind</a> of the
7007: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7008: represents.</p>
7009:
7010: <p>The <dfn id="dom-texttrack-label" title="dom-TextTrack-label"><code>label</code></dfn>
7011: attribute must return the <a href="#text-track-label">text track label</a> of the
7012: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7013: represents.</p>
7014:
7015: <p>The <dfn id="dom-texttrack-language" title="dom-TextTrack-language"><code>language</code></dfn>
7016: attribute must return the <a href="#text-track-language">text track language</a> of the
7017: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7018: represents.</p>
7019:
7020: <p>The <dfn id="dom-texttrack-readystate" title="dom-TextTrack-readyState"><code>readyState</code></dfn>
7021: attribute must return the numeric value corresponding to the
7022: <a href="#text-track-readiness-state">text track readiness state</a> of the <a href="#text-track">text
7023: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents, as
7024: defined by the following list:</p>
7025:
7026: <dl><dt><dfn id="dom-texttrack-none" title="dom-TextTrack-NONE"><code>NONE</code></dfn> (numeric value 0)</dt>
7027: <dd>The <a href="#text-track-not-loaded">text track not loaded</a> state.</dd>
7028: <dt><dfn id="dom-texttrack-loading" title="dom-TextTrack-LOADING"><code>LOADING</code></dfn> (numeric value 1)</dt>
7029: <dd>The <a href="#text-track-loading">text track loading</a> state.</dd>
7030: <dt><dfn id="dom-texttrack-loaded" title="dom-TextTrack-LOADED"><code>LOADED</code></dfn> (numeric value 2)</dt>
7031: <dd>The <a href="#text-track-loaded">text track loaded</a> state.</dd>
7032: <dt><dfn id="dom-texttrack-error" title="dom-TextTrack-ERROR"><code>ERROR</code></dfn> (numeric value 3)</dt>
7033: <dd>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</dd>
7034: </dl><p>The <dfn id="dom-texttrack-mode" title="dom-TextTrack-mode"><code>mode</code></dfn>
7035: attribute, on getting, must return the numeric value corresponding
7036: to the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text track</a>
7037: that the <code><a href="#texttrack">TextTrack</a></code> object represents, as defined by
7038: the following list:</p>
7039:
7040: <dl><dt><dfn id="dom-texttrack-off" title="dom-TextTrack-OFF"><code>OFF</code></dfn> (numeric value 0)</dt>
7041: <dd>The <a href="#text-track-disabled">text track disabled</a> mode.</dd>
7042: <dt><dfn id="dom-texttrack-hidden" title="dom-TextTrack-HIDDEN"><code>HIDDEN</code></dfn> (numeric value 1)</dt>
7043: <dd>The <a href="#text-track-hidden">text track hidden</a> mode.</dd>
7044: <dt><dfn id="dom-texttrack-showing" title="dom-TextTrack-SHOWING"><code>SHOWING</code></dfn> (numeric value 2)</dt>
7045: <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>
7046: </dl><p>On setting, if the new value is not either 0, 1, or 2, the user
1.78 mike 7047: agent must throw an <code><a href="infrastructure.html#invalid_access_err">INVALID_ACCESS_ERR</a></code>
1.47 mike 7048: exception. Otherwise, if the new value isn't equal to what the
7049: attribute would currently return, the new value must be processed as
7050: follows:</p>
7051:
7052: <dl class="switch"><dt>If the new value is 0</dt>
7053:
7054: <dd>
7055:
7056: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7057: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7058: the <a href="#text-track-disabled">text track disabled</a> mode.</p>
7059:
7060: </dd>
7061:
7062: <dt>If the new value is 1</dt>
7063:
7064: <dd>
7065:
7066: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7067: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7068: the <a href="#text-track-hidden">text track hidden</a> mode.</p>
7069:
7070: </dd>
7071:
7072: <dt>If the new value is 2</dt>
7073:
7074: <dd>
7075:
7076: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7077: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7078: the <a href="#text-track-showing">text track showing</a> mode.</p>
7079:
7080: <p class="note">If the mode had been <a href="#text-track-showing-by-default" title="text track
7081: showing by default">showing by default</a>, this will change it
7082: to <a href="#text-track-showing" title="text track showing">showing</a>, even though
7083: the value of <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> would
7084: appear not to change.</p>
7085:
7086: </dd>
7087:
7088: </dl><p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7089: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
7090: 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
7091: return a <a href="infrastructure.html#live">live</a> <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
7092: that represents the subset of the <a href="#text-track-list-of-cues">text track list of
7093: cues</a> of the <a href="#text-track">text track</a> that the
7094: <code><a href="#texttrack">TextTrack</a></code> object represents whose <a href="#text-track-cue-start-time" title="text
7095: track cue start time">start times</a> occur before the
7096: <a href="#earliest-possible-position-when-the-script-started">earliest possible position when the script started</a>, in
7097: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
7098: null. When an object is returned, the same object must be returned
7099: each time.</p>
7100:
7101: <p>The <dfn id="earliest-possible-position-when-the-script-started">earliest possible position when the script started</dfn>
7102: is whatever the <a href="#earliest-possible-position">earliest possible position</a> was the last
7103: time the <a href="webappapis.html#event-loop">event loop</a> reached step 1.</p>
7104:
7105: <p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7106: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
7107: 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>
7108: attribute must return a <a href="infrastructure.html#live">live</a>
7109: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that represents the subset of
7110: the <a href="#text-track-list-of-cues">text track list of cues</a> of the <a href="#text-track">text
7111: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents
7112: whose <a href="#active-flag-was-set-when-the-script-started">active flag was set when the script started</a>, in
7113: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
7114: null. When an object is returned, the same object must be returned
7115: each time.</p>
7116:
7117: <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
7118: the script started</dfn> if its <a href="#text-track-cue-active-flag">text track cue active
7119: flag</a> was set the last time the <a href="webappapis.html#event-loop">event loop</a>
7120: reached step 1.</p>
7121:
7122: </div><hr><pre class="idl">interface <dfn id="mutabletexttrack">MutableTextTrack</dfn> : <a href="#texttrack">TextTrack</a> {
7123: void <a href="#dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue">addCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
7124: void <a href="#dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue">removeCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
7125: };</pre><dl class="domintro"><dt><var title="">mutableTextTrack</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>
7126:
7127: <dd>
7128: <p>Creates and returns a new <code><a href="#mutabletexttrack">MutableTextTrack</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>
7129: </dd>
7130:
7131: <dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-addCue"><a href="#dom-mutabletexttrack-addcue">addCue</a></code>( <var title="">cue</var> )</dt>
7132: <dd>
7133: <p>Adds the given cue to <var title="">mutableTextTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
1.68 mike 7134: <p>Raises an exception if the argument is associated with another <a href="#text-track">text track</a> or already in the list of cues.</p>
1.47 mike 7135: </dd>
7136:
7137: <dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-removeCue"><a href="#dom-mutabletexttrack-removecue">removeCue</a></code>( <var title="">cue</var> )</dt>
7138: <dd>
7139: <p>Removes the given cue from <var title="">mutableTextTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
1.68 mike 7140: <p>Raises an exception if the argument is associated with another <a href="#text-track">text track</a> or not in the list of cues.</p>
1.47 mike 7141: </dd>
7142:
7143: </dl><div class="impl">
7144:
7145: <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
7146: element">media elements</a>, when invoked, must run the following
7147: steps:</p>
7148:
7149: <ol><li>
7150:
7151: <p>If <var title="">kind</var> is not one of the following
1.78 mike 7152: strings, then throw a <code><a href="infrastructure.html#syntax_err">SYNTAX_ERR</a></code> exception and abort
1.47 mike 7153: these steps:</p>
7154:
7155: <ul class="brief"><li><code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code>
7156: </li><li><code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code>
7157: </li><li><code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code>
7158: </li><li><code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code>
7159: </li><li><code title="dom-TextTrack-kind-metadata"><a href="#dom-texttrack-kind-metadata">metadata</a></code>
7160: </li></ul></li>
7161:
7162: <li>
7163:
7164: <p>If the <var title="">label</var> argument was omitted, let <var title="">label</var> be the empty string.</p>
7165:
7166: </li>
7167:
7168: <li>
7169:
7170: <p>If the <var title="">language</var> argument was omitted, let
7171: <var title="">language</var> be the empty string.</p>
7172:
7173: </li>
7174:
7175: <li>
7176:
7177: <p>Create a new <a href="#text-track">text track</a>, and set its <a href="#text-track-kind">text
7178: track kind</a> to <var title="">kind</var>, its <a href="#text-track-label">text
7179: track label</a> to <var title="">label</var>, its <a href="#text-track-language">text
7180: track language</a> to <var title="">language</var>, its
7181: <a href="#text-track-readiness-state">text track readiness state</a> to the <a href="#text-track-loaded">text track
7182: loaded</a> state, its <a href="#text-track-mode">text track mode</a> to the
7183: <a href="#text-track-hidden">text track hidden</a> mode, and its <a href="#text-track-list-of-cues">text track
7184: list of cues</a> to an empty list.
7185: </p>
7186:
7187: </li>
7188:
7189: <li>
7190:
7191: <p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
7192: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
7193:
7194: </li></ol><p>The <dfn id="dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue"><code>addCue(<var title="">cue</var>)</code></dfn> method of
7195: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
7196: following steps:</p>
7197:
1.68 mike 7198: <ol><li><p>If the given <var title="">cue</var> is already associated
1.47 mike 7199: with a <a href="#text-track">text track</a> other than the method's
7200: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
1.78 mike 7201: then throw an <code><a href="infrastructure.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception and abort
1.47 mike 7202: these steps.</p></li>
7203:
7204: <li><p>Associate <var title="">cue</var> with the method's
7205: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
7206: if it is not currently associated with a <a href="#text-track">text
7207: track</a>.</p></li>
7208:
7209: <li><p>If the given <var title="">cue</var> is already listed in
7210: the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7211: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw an
1.78 mike 7212: <code><a href="infrastructure.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception.</p></li>
1.47 mike 7213:
7214: <li><p>Add <var title="">cue</var> to the method's
7215: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
7216: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7217:
7218: </ol><p>The <dfn id="dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue"><code>removeCue(<var title="">cue</var>)</code></dfn> method of
7219: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
7220: following steps:</p>
7221:
1.68 mike 7222: <ol><li><p>If the given <var title="">cue</var> is not associated with
1.47 mike 7223: the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
1.78 mike 7224: track</a>, then throw an <code><a href="infrastructure.html#invalid_state_err">INVALID_STATE_ERR</a></code>
1.47 mike 7225: exception.</p></li>
7226:
7227: <li><p>If the given <var title="">cue</var> is not currently listed
7228: in the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7229: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw a
1.78 mike 7230: <code><a href="infrastructure.html#not_found_err">NOT_FOUND_ERR</a></code> exception.</p></li>
1.47 mike 7231:
7232: <li><p>Remove <var title="">cue</var> from the method's
7233: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
7234: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7235:
7236: </ol></div><div class="example">
7237:
7238: <p>In this example, an <code><a href="#the-audio-element">audio</a></code> element is used to play a
7239: specific sound-effect from a sound file containing many sound
7240: effects. A cue is used to pause the audio, so that it ends exactly
7241: at the end of the clip, even if the browser is busy running some
7242: script. If the page had relied on script to pause the audio, then
7243: the start of the next clip might be heard if the browser was not
7244: able to run the script at the exact time specified.</p>
7245:
7246: <pre>var sfx = new Audio('sfx.wav');
7247: var sounds = a.addTextTrack('metadata');
7248:
7249: // add sounds we care about
7250: sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
7251: sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));
7252:
7253: function playSound(id) {
7254: sfx.currentTime = sounds.getCueById(id).startTime;
7255: sfx.play();
7256: }
7257:
7258: sfx.oncanplaythrough = function () {
7259: playSound('dog bark');
7260: }
7261: window.onbeforeunload = function () {
7262: playSound('kitten mew');
7263: return 'Are you sure you want to leave this awesome page?';
7264: }</pre>
7265:
7266: </div><hr><pre class="idl">interface <dfn id="texttrackcuelist">TextTrackCueList</dfn> {
7267: readonly attribute unsigned long <a href="#dom-texttrackcuelist-length" title="dom-TextTrackCueList-length">length</a>;
7268: getter <a href="#texttrackcue">TextTrackCue</a> (in unsigned long index);
1.68 mike 7269: <a href="#texttrackcue">TextTrackCue</a>? <a href="#dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById">getCueById</a>(in DOMString id);
1.47 mike 7270: };</pre><dl class="domintro"><dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-length"><a href="#dom-texttrackcuelist-length">length</a></code></dt>
7271: <dd>
7272: <p>Returns the number of <a href="#text-track-cue" title="text track cue">cues</a> in the list.</p>
7273: </dd>
7274:
7275: <dt><var title="">cuelist</var>[<var title="">index</var>]</dt>
7276: <dd>
7277: <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>
7278: </dd>
7279:
7280: <dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-getCueById"><a href="#dom-texttrackcuelist-getcuebyid">getCueById</a></code>( <var title="">id</var> )</dt>
7281: <dd>
7282: <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>
7283: <p>Returns null if none of the cues have the given identifier or if the argument is the empty string.</p>
7284: </dd>
7285:
7286: </dl><div class="impl">
7287:
7288: <p>A <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object represents a dynamically
7289: updating list of <a href="#text-track-cue" title="text track cue">text track
7290: cues</a> in a given order.</p>
7291:
7292: <p>The <dfn id="dom-texttrackcuelist-length" title="dom-TextTrackCueList-length"><code>length</code></dfn>
7293: attribute must return the number of <a href="#text-track-cue" title="text track
7294: cue">cues</a> in the list represented by the
7295: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7296:
1.76 mike 7297: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of a
1.47 mike 7298: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
7299: from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
7300: in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
7301: minus one, if any. If there are no <a href="#text-track-cue" title="text track
1.76 mike 7302: cue">cues</a> in the list, there are no <a href="infrastructure.html#supported-property-indices">supported property
7303: indices</a>.</p>
1.47 mike 7304:
1.76 mike 7305: <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 7306: given index <var title="">index</var>, the user agent must return
7307: the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
7308: list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7309:
7310: <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
7311: other than the empty string, must return the first <a href="#text-track-cue">text track
7312: cue</a> in the list represented by the
7313: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object whose <a href="#text-track-cue-identifier">text track cue
7314: identifier</a> is <var title="">id</var>, if any, or null
7315: otherwise. If the argument is the empty string, then the method must
7316: return null.</p>
7317:
7318: </div><hr><pre class="idl">
1.86 mike 7319: interface <dfn id="texttrackcue">TextTrackCue</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.68 mike 7320: readonly attribute <a href="#texttrack">TextTrack</a>? <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a>;
1.47 mike 7321: readonly attribute DOMString <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a>;
7322:
7323: readonly attribute double <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a>;
7324: readonly attribute double <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a>;
7325: readonly attribute boolean <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a>;
7326:
7327:
7328: DOMString <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>();
7329: <a href="infrastructure.html#documentfragment">DocumentFragment</a> <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>();
7330:
1.68 mike 7331: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter">onenter</a>;
7332: attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit">onexit</a>;
1.86 mike 7333: };</pre><dl class="domintro"><dt><var title="">cue</var> . <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a></dt>
1.47 mike 7334: <dd>
7335: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object to which this
7336: <a href="#text-track-cue">text track cue</a> belongs, if any, or null
7337: otherwise.</p>
7338: </dd>
7339:
7340: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a></dt>
7341: <dd>
7342: <p>Returns the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
7343: </dd>
7344:
7345: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a></dt>
7346: <dd>
7347: <p>Returns the <a href="#text-track-cue-start-time">text track cue start time</a>, in seconds.</p>
7348: </dd>
7349:
7350: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a></dt>
7351: <dd>
7352: <p>Returns the <a href="#text-track-cue-end-time">text track cue end time</a>, in seconds.</p>
7353: </dd>
7354:
7355: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a></dt>
7356: <dd>
7357: <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>
7358: </dd>
7359:
7360:
7361: <dt><var title="">source</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>()</dt>
7362: <dd>
7363: <p>Returns the <a href="#text-track-cue-text">text track cue text</a> in raw unparsed form.</p>
7364: </dd>
7365:
7366: <dt><var title="">fragment</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>()</dt>
7367: <dd>
7368: <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>
7369: </dd>
7370:
7371: </dl><div class="impl">
7372:
7373:
7374: <p>The <dfn id="dom-texttrackcue-track" title="dom-TextTrackCue-track"><code>track</code></dfn>
7375: attribute must return the <code><a href="#texttrack">TextTrack</a></code> object of the
7376: <a href="#text-track">text track</a> with which the <a href="#text-track-cue">text track cue</a>
7377: that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is associated,
7378: if any; or null otherwise.</p>
7379:
7380: <p>The <dfn id="dom-texttrackcue-id" title="dom-TextTrackCue-id"><code>id</code></dfn>
7381: attribute must return the <a href="#text-track-cue-identifier">text track cue identifier</a> of
7382: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7383: object represents.</p>
7384:
7385: <p>The <dfn id="dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime"><code>startTime</code></dfn>
7386: attribute must return the <a href="#text-track-cue-start-time">text track cue start time</a> of
7387: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7388: object represents, in seconds.</p>
7389:
7390: <p>The <dfn id="dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime"><code>endTime</code></dfn>
7391: attribute must return the <a href="#text-track-cue-end-time">text track cue end time</a> of
7392: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7393: object represents, in seconds.</p>
7394:
7395: <p>The <dfn id="dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit"><code>pauseOnExit</code></dfn>
7396: attribute must return true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue
7397: pause-on-exit flag</a> of the <a href="#text-track-cue">text track cue</a> that
7398: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
7399: otherwise.</p>
7400:
7401: <p>The <dfn id="dom-texttrackcue-direction" title="dom-TextTrackCue-direction"><code>direction</code></dfn>
7402: attribute must return the <a href="#text-track-cue-writing-direction">text track cue writing
7403: direction</a> of the <a href="#text-track-cue">text track cue</a> that the
7404: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents.</p>
7405:
7406:
7407: <p>The <dfn id="dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource"><code>getCueAsSource()</code></dfn>
7408: method must return the raw <a href="#text-track-cue-text">text track cue text</a>.</p>
7409:
7410: <p>The <dfn id="dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML"><code>getCueAsHTML()</code></dfn>
7411: method must convert the <a href="#text-track-cue-text">text track cue text</a> to a
7412: <code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> for the <a href="#media-element">media element</a>'s
7413: <code><a href="infrastructure.html#document">Document</a></code>, using the appropriate rules for doing
7414: so.
7415: </p>
7416:
1.91 mike 7417: </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
7418: given title. Chapters can be nested, in the same way that sections
7419: 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>
7420: being used for describing chapters has three key features: the
7421: <a href="#text-track-cue-start-time">text track cue start time</a>, giving the start time of the
7422: chapter, the <a href="#text-track-cue-end-time">text track cue end time</a>, giving the end
7423: time of the chapter, and the <a href="#text-track-cue-text">text track cue text</a> giving
7424: the chapter title.</p><div class="impl">
7425:
7426: <p>The <dfn id="rules-for-constructing-the-chapter-tree-from-a-text-track">rules for constructing the chapter tree from a text
7427: track</dfn> are as follows. They produce a potentially nested list
7428: of chapters, each of which have a start time, end time, title, and a
7429: list of nested chapters. This algorithm discards cues that do not
7430: correctly nest within each other, or that are out of order.</p>
7431:
7432: <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
7433: <a href="#text-track">text track</a> being processed.</p></li>
7434:
7435: <li><p>Let <var title="">output</var> be an empty list of chapters,
7436: where a chapter is a record consisting of a start time, an end
7437: time, a title, and a (potentially empty) list of nested chapters.
7438: For the purpose of this algorithm, each chapter also has a parent
7439: chapter.</p></li>
7440:
7441: <li><p>Let <var title="">current chapter</var> be a stand-in
7442: chapter whose start time is negative infinity, whose end time is
7443: positive infinity, and whose list of nested chapters is <var title="">output</var>. (This is just used to make the algorithm
7444: easier to describe.)</p></li>
7445:
7446:
7447: <li><p><i>Loop</i>: If <var title="">list</var> is empty, jump to
7448: the step labeled <i>end</i>.</p></li>
7449:
7450:
7451: <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>
7452:
7453: <li><p>If <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track cue
7454: start time</a> is less than the start time of <var title="">current chapter</var>, then return to the step labeled
7455: <i>loop</i>.</p>
7456:
7457: </li><li><p>While <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track cue
7458: start time</a> is greater than or equal to <var title="">current
7459: chapter</var>'s end time, let <var title="">current chapter</var>
7460: be <var title="">current chapter</var>'s parent chapter.</p></li>
7461:
7462: <li><p>If <var title="">current cue</var>'s <a href="#text-track-cue-end-time">text track cue
7463: end time</a> is greater than the end time of <var title="">current chapter</var>, then return to the step labeled
7464: <i>loop</i>.</p>
7465:
7466: </li><li><p>Create a new chapter <var title="">new chapter</var>, whose
7467: start time is <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track
7468: cue start time</a>, whose end time is <var title="">current
7469: cue</var>'s <a href="#text-track-cue-end-time">text track cue end time</a>, whose title is
7470: <var title="">current cue</var>'s <a href="#text-track-cue-text">text track cue text</a>
7471: interpreted according to its rules for interpretation, and whose
7472: list of nested chapters is empty.</p></li>
7473:
7474: <li><p>Append <var title="">new chapter</var> to <var title="">current chapter</var>'s list of nested chapters, and let
7475: <var title="">current chapter</var> be <var title="">new
7476: chapter</var>'s parent.</p></li>
7477:
7478: <li><p>Let <var title="">current chapter</var> be <var title="">new
7479: chapter</var>.</p></li>
7480:
7481: <li><p>Return to the step labeled <i>loop</i>.</p></li>
7482:
7483:
7484: <li><p><i>End</i>: Return <var title="">output</var>.</p></li>
7485:
7486: </ol></div><div class="impl">
1.47 mike 7487:
1.91 mike 7488: <h6 id="cue-events"><span class="secno">4.8.10.12.6 </span>Event definitions</h6>
1.47 mike 7489:
7490: <p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
7491: supported, as IDL attributes, by all objects implementing the
7492: <code><a href="#texttrack">TextTrack</a></code> interface:</p>
7493:
7494: <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>
7495: </th></tr></thead><tbody><tr><td><dfn id="handler-texttrack-onload" title="handler-TextTrack-onload"><code>onload</code></dfn> </td><td> <code title="event-load">load</code>
7496: </td></tr><tr><td><dfn id="handler-texttrack-onerror" title="handler-TextTrack-onerror"><code>onerror</code></dfn> </td><td> <code title="event-error">error</code>
7497: </td></tr><tr><td><dfn id="handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange"><code>oncuechange</code></dfn> </td><td> <code title="event-cuechange">cuechange</code>
7498: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
7499: supported, as IDL attributes, by all objects implementing the
7500: <code><a href="#texttrackcue">TextTrackCue</a></code> interface:</p>
7501:
7502: <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>
7503: </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>
7504: </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>
7505: </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>
7506: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. If present, it
7507: indicates that the author has not provided a scripted controller and
7508: would like the user agent to provide its own set of controls.</p><div class="impl">
7509:
7510: <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
7511: <a href="#media-element">media element</a>, then the user agent should <dfn id="expose-a-user-interface-to-the-user">expose a
7512: user interface to the user</dfn>. This user interface should include
7513: features to begin playback, pause playback, seek to an arbitrary
7514: position in the content (if the content supports arbitrary seeking),
7515: change the volume, change the display of closed captions or embedded
7516: sign-language tracks, select different audio tracks or turn on audio
7517: descriptions, and show the media content in manners more suitable to
7518: the user (e.g. full-screen video or in an independent resizable
7519: window). Other controls may also be made available.</p>
7520:
7521: <p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7522: controller</a>, then the user agent should expose audio tracks
7523: from all the <a href="#slaved-media-elements">slaved media elements</a> (although avoiding
7524: duplicates if the same <a href="#media-resource">media resource</a> is being used
7525: several times). If a <a href="#media-resource">media resource</a>'s audio track
7526: exposed in this way has no known name, and it is the only audio
7527: track for a particular <a href="#media-element">media element</a>, the user agent
7528: should use the element's <code title="attr-title"><a href="elements.html#the-title-attribute">title</a></code>
7529: attribute, if any, as the name (or as part of the name) of that
7530: track.</p>
7531:
7532: <p>Even when the attribute is absent, however, user agents may
7533: provide controls to affect playback of the media resource
7534: (e.g. play, pause, seeking, and volume controls), but such features
7535: should not interfere with the page's normal rendering. For example,
7536: such features could be exposed in the <a href="#media-element">media element</a>'s
7537: context menu.</p>
7538:
7539: <p>Where possible (specifically, for starting, stopping, pausing,
7540: and unpausing playback, for seeking, for changing the rate of
7541: playback, for fast-forwarding or rewinding,
7542: for listing, enabling, and disabling text tracks,
7543: and for muting or changing the volume of the audio), user interface
7544: features exposed by the user agent must be implemented in terms of
7545: the DOM API described above, so that, e.g., all the same events
7546: fire.</p>
7547:
7548: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7549: controller</a>, the user agent's user interface for pausing and
7550: unpausing playback, for seeking, for changing the rate of playback,
7551: for fast-forwarding or rewinding, and for muting or changing the
7552: volume of audio of the entire group must be implemented in terms of
7553: the <code><a href="#mediacontroller">MediaController</a></code> API exposed on that <a href="#current-media-controller">current
7554: media controller</a>.</p>
7555:
7556: <p>The "play" function in the user agent's interface must set the
7557: <code title="">playbackRate</code> attribute to the value of the
7558: <code title="">defaultPlaybackRate</code> attribute before invoking
7559: the <code title="">play()</code> method.
7560: When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7561: controller</a>, the attributes and method with those names on
7562: that <code><a href="#mediacontroller">MediaController</a></code> object must be used. Otherwise,
7563: the attributes and method with those names on the <a href="#media-element">media
7564: element</a> itself must be used.
7565: </p>
7566:
7567: <p>Features such as fast-forward or rewind must be implemented by
7568: only changing the <code title="">playbackRate</code> attribute (and
7569: not the <code title="">defaultPlaybackRate</code> attribute).
7570: Again, when a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7571: controller</a>, the attributes with those names on that
7572: <code><a href="#mediacontroller">MediaController</a></code> object must be used; otherwise, the
7573: attributes with those names on the <a href="#media-element">media element</a> itself
7574: must be used.
7575: </p>
7576:
7577: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7578: controller</a>, and all the <a href="#slaved-media-elements">slaved media elements</a> of
7579: that <code><a href="#mediacontroller">MediaController</a></code> are paused, the user agent should
7580: unpause all the <a href="#slaved-media-elements">slaved media elements</a> when the user
7581: invokes a user agent interface control for beginning playback.</p>
7582:
7583: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
1.80 mike 7584: controller</a>, seeking must be implemented in terms of the <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> attribute
7585: on that <code><a href="#mediacontroller">MediaController</a></code> object. Otherwise, the user
7586: agent must directly <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the
7587: requested position in the <a href="#media-element">media element</a>'s <a href="#media-timeline">media
1.47 mike 7588: timeline</a>.</p>
7589:
7590: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7591: controller</a>, user agents may additionally provide the user
7592: with controls that directly manipulate an individual <a href="#media-element">media
7593: element</a> without affecting the <code><a href="#mediacontroller">MediaController</a></code>,
7594: but such features are considered relatively advanced and unlikely to
7595: be useful to most users.
7596:
7597: </p><p>For the purposes of listing chapters in the <a href="#media-resource">media
1.91 mike 7598: resource</a>, only <a href="#text-track" title="text track">text tracks</a> in
7599: the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>
7600: <a href="#text-track-showing" title="text track showing">showing</a> or <a href="#text-track-showing-by-default" title="text
7601: track showing by default">showing by default</a> and whose
7602: <a href="#text-track-kind">text track kind</a> is <code title="dom-timedtrack-kind-chapters">chapters</code> should be used.
7603: Such tracks must be interpreted according to the <a href="#rules-for-constructing-the-chapter-tree-from-a-text-track">rules for
7604: constructing the chapter tree from a text track</a>.</p>
1.47 mike 7605:
7606: <p>The <dfn id="dom-media-controls" title="dom-media-controls"><code>controls</code></dfn>
7607: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
7608: same name.</p>
7609:
7610: <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>
7611:
7612: <dd>
7613:
7614: <p>Returns the current playback volume, as a number in the range
7615: 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.</p>
7616:
7617: <p>Can be set, to change the volume.</p>
7618:
1.78 mike 7619: <p>Throws an <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
1.47 mike 7620: in the range 0.0 .. 1.0.</p>
7621:
7622: </dd>
7623:
7624: <dt><var title="">media</var> . <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
7625:
7626: <dd>
7627:
7628: <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
7629: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute is being
7630: honored.</p>
7631:
7632: <p>Can be set, to change whether the audio is muted or not.</p>
7633:
7634: </dd>
7635:
7636: </dl><div class="impl">
7637:
7638: <p>The <dfn id="dom-media-volume" title="dom-media-volume"><code>volume</code></dfn>
7639: attribute must return the playback volume of any audio portions of
7640: the <a href="#media-element">media element</a>, in the range 0.0 (silent) to 1.0
7641: (loudest). Initially, the volume must be 1.0, but user agents may
7642: remember the last set value across sessions, on a per-site basis or
7643: otherwise, so the volume may start at other values. On setting, if
7644: the new value is in the range 0.0 to 1.0 inclusive, the attribute
7645: must be set to the new value. If the new value is outside the range
7646: 0.0 to 1.0 inclusive, then, on setting, an
1.78 mike 7647: <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
1.47 mike 7648:
7649: <p>The <dfn id="dom-media-muted" title="dom-media-muted"><code>muted</code></dfn>
7650: attribute must return true if the audio channels are muted and false
7651: otherwise. Initially, the audio channels should not be muted
7652: (false), but user agents may remember the last set value across
7653: sessions, on a per-site basis or otherwise, so the muted state may
7654: start as muted (true). On setting, the attribute must be set to the
7655: new value.</p>
7656:
7657: <p>Whenever either the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> or
7658: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attributes are changed,
7659: 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 simple
7660: event</a> named <code title="event-media-volumechange"><a href="#event-media-volumechange">volumechange</a></code> at the <a href="#media-element">media
7661: element</a>.</p>
7662:
7663: <p>An element's <dfn id="effective-media-volume">effective media volume</dfn> is determined as
7664: follows:</p>
7665:
7666: <ol><li><p>If the element's <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code>
7667: attribute is true, the element's <a href="#effective-media-volume">effective media
7668: volume</a> is zero. Abort these steps.</p></li>
7669:
7670: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>
7671: and that <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-mute-override">media
7672: controller mute override</a> is true, the element's
7673: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
7674: steps.</p></li>
7675:
7676: <li><p>Let <var title="">volume</var> be the value of the element's
7677: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute.</p></li>
7678:
7679: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>,
7680: multiply <var title="">volume</var> by that
7681: <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-volume-multiplier">media controller volume
7682: multiplier</a>.</p></li>
7683:
7684: <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
7685: 1.0, with 0.0 being silent, and 1.0 being the loudest setting,
7686: values in between increasing in loudness. The range need not be
7687: linear. The loudest setting may be lower than the system's loudest
7688: possible setting; for example the user could have set a maximum
7689: volume.</p></li>
7690:
7691: </ol></div><p>The <dfn id="attr-media-muted" title="attr-media-muted"><code>muted</code></dfn>
1.97 ! mike 7692: attribute on <a href="#media-element" title="media element">media elements</a> is a
! 7693: <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that controls the default state of
! 7694: the audio channel of the <a href="#media-resource">media resource</a>, potentially
! 7695: overriding user preferences.</p><div class="impl">
1.47 mike 7696:
7697: <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
7698: agent must set the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> IDL
7699: attribute to true, overriding any user preference.</p>
7700:
7701: <p>The <dfn id="dom-media-defaultmuted" title="dom-media-defaultMuted"><code>defaultMuted</code></dfn> IDL
7702: 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>
7703:
7704: </div><p class="note">This attribute has no dynamic effect (it only
7705: controls the default state of the element).</p><div class="example">
7706:
7707: <p>This video (an advertisment) autoplays, but to avoid annoying
7708: users, it does so without sound, and allows the user to turn the
7709: sound on.</p>
7710:
7711: <pre><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></pre>
7712:
7713: </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
7714: represent a list of ranges (periods) of time.</p><pre class="idl">interface <dfn id="timeranges">TimeRanges</dfn> {
7715: readonly attribute unsigned long <a href="#dom-timeranges-length" title="dom-TimeRanges-length">length</a>;
7716: double <a href="#dom-timeranges-start" title="dom-TimeRanges-start">start</a>(in unsigned long index);
7717: double <a href="#dom-timeranges-end" title="dom-TimeRanges-end">end</a>(in unsigned long index);
7718: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-TimeRanges-length"><a href="#dom-timeranges-length">length</a></code></dt>
7719:
7720: <dd>
7721:
7722: <p>Returns the number of ranges in the object.</p>
7723:
7724: </dd>
7725:
7726: <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>
7727:
7728: <dd>
7729:
7730: <p>Returns the time for the start of the range with the given index.</p>
7731:
1.78 mike 7732: <p>Throws an <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> if the index is out of range.</p>
1.47 mike 7733:
7734: </dd>
7735:
7736: <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>
7737:
7738: <dd>
7739:
7740: <p>Returns the time for the end of the range with the given index.</p>
7741:
1.78 mike 7742: <p>Throws an <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> if the index is out of range.</p>
1.47 mike 7743:
7744: </dd>
7745:
7746: </dl><div class="impl">
7747:
7748: <p>The <dfn id="dom-timeranges-length" title="dom-TimeRanges-length"><code>length</code></dfn>
7749: IDL attribute must return the number of ranges represented by the object.</p>
7750:
7751: <p>The <dfn id="dom-timeranges-start" title="dom-TimeRanges-start"><code>start(<var title="">index</var>)</code></dfn> method must return the position
7752: of the start of the <var title="">index</var>th range represented by
7753: the object, in seconds measured from the start of the timeline that
7754: the object covers.</p>
7755:
7756: <p>The <dfn id="dom-timeranges-end" title="dom-TimeRanges-end"><code>end(<var title="">index</var>)</code></dfn> method must return the position
7757: of the end of the <var title="">index</var>th range represented by
7758: the object, in seconds measured from the start of the timeline that
7759: the object covers.</p>
7760:
1.78 mike 7761: <p>These methods must raise <code><a href="infrastructure.html#index_size_err">INDEX_SIZE_ERR</a></code> exceptions
1.47 mike 7762: if called with an <var title="">index</var> argument greater than or
7763: equal to the number of ranges represented by the object.</p>
7764:
7765: <p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said to be a
7766: <dfn id="normalized-timeranges-object">normalized <code>TimeRanges</code> object</dfn>, the ranges it
7767: represents must obey the following criteria:</p>
7768:
7769: <ul><li>The start of a range must be greater than the end of all
7770: earlier ranges.</li>
7771:
7772: <li>The start of a range must be less than the end of that same
7773: range.</li>
7774:
7775: </ul><p>In other words, the ranges in such an object are ordered, don't
7776: overlap, aren't empty, and don't touch (adjacent ranges are folded
7777: into one bigger range).</p>
7778:
1.62 mike 7779: <p>Ranges in a <code><a href="#timeranges">TimeRanges</a></code> object must be inclusive.</p>
7780:
7781: <p class="example">Thus, the end of a range would be equal to the
7782: start of a following adjacent (touching but not overlapping) range.
7783: Similarly, a range covering a whole timeline anchored at zero would
7784: have a start equal to zero and an end equal to the duration of the
7785: timeline.</p>
7786:
1.47 mike 7787: <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
7788: <a href="#media-timeline">media timeline</a>.</p>
7789:
7790: </div><h5 id="mediaevents"><span class="secno">4.8.10.15 </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
7791: elements</a> as part of the processing model described above:</p><table><thead><tr><th>Event name
7792: </th><th>Interface
1.64 mike 7793: </th><th>Fired when...
1.47 mike 7794: </th><th>Preconditions
7795:
7796: </th></tr></thead><tbody><tr><td><dfn id="event-media-loadstart" title="event-media-loadstart"><code>loadstart</code></dfn>
7797: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7798: </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>.
7799: </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>
7800: </td></tr><tr><td><dfn id="event-media-progress" title="event-media-progress"><code>progress</code></dfn>
7801: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7802: </td><td>The user agent is fetching <a href="#media-data">media data</a>.
7803: </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>
7804: </td></tr><tr><td><dfn id="event-media-suspend" title="event-media-suspend"><code>suspend</code></dfn>
7805: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7806: </td><td>The user agent is intentionally not currently fetching <a href="#media-data">media data</a>, but does not have the entire <a href="#media-resource">media resource</a> downloaded.
7807: </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>
7808: </td></tr><tr><td><dfn id="event-media-abort" title="event-media-abort"><code>abort</code></dfn>
7809: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7810: </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.
7811: </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>.
7812: <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.
7813: </td></tr><tr><td><dfn id="event-media-error" title="event-media-error"><code>error</code></dfn>
7814: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7815: </td><td>An error occurs while fetching the <a href="#media-data">media data</a>.
7816: </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.
7817: <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.
7818: </td></tr><tr><td><dfn id="event-media-emptied" title="event-media-emptied"><code>emptied</code></dfn>
7819: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7820: </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).
7821: </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.
7822: </td></tr><tr><td><dfn id="event-media-stalled" title="event-media-stalled"><code>stalled</code></dfn>
7823: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7824: </td><td>The user agent is trying to fetch <a href="#media-data">media data</a>, but data is unexpectedly not forthcoming.
7825: </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>.
7826:
7827: </td></tr></tbody><tbody><tr><td><dfn id="event-media-loadedmetadata" title="event-media-loadedmetadata"><code>loadedmetadata</code></dfn>
7828: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7829: </td><td>The user agent has just determined the duration and dimensions of the <a href="#media-resource">media resource</a>
7830: and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>.
7831: </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.
7832: </td></tr><tr><td><dfn id="event-media-loadeddata" title="event-media-loadeddata"><code>loadeddata</code></dfn>
7833: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7834: </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.
7835: </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.
7836: </td></tr><tr><td><dfn id="event-media-canplay" title="event-media-canplay"><code>canplay</code></dfn>
7837: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7838: </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.
7839: </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.
7840: </td></tr><tr><td><dfn id="event-media-canplaythrough" title="event-media-canplaythrough"><code>canplaythrough</code></dfn>
7841: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7842: </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.
7843: </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>.
7844: </td></tr><tr><td><dfn id="event-media-playing" title="event-media-playing"><code>playing</code></dfn>
7845: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7846: </td><td>Playback is ready to start after having been paused or delayed due to lack of <a href="#media-data">media data</a>.
7847: </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
7848: 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
7849: the element is <a href="#paused-for-user-interaction">paused for user interaction</a>.
7850: </td></tr><tr><td><dfn id="event-media-waiting" title="event-media-waiting"><code>waiting</code></dfn>
7851: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7852: </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.
7853: </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.
7854: the element is newly <a href="#blocked-on-its-media-controller">blocked on its media controller</a>, or
7855: <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>.
7856: </td></tr></tbody><tbody><tr><td><dfn id="event-media-seeking" title="event-media-seeking"><code>seeking</code></dfn>
7857: </td><td><code><a href="infrastructure.html#event">Event</a></code>
1.73 mike 7858: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to true.
1.47 mike 7859: </td><td>
7860: </td></tr><tr><td><dfn id="event-media-seeked" title="event-media-seeked"><code>seeked</code></dfn>
7861: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7862: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to false.
7863: </td><td>
7864: </td></tr><tr><td><dfn id="event-media-ended" title="event-media-ended"><code>ended</code></dfn>
7865: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7866: </td><td>Playback has stopped because the end of the <a href="#media-resource">media resource</a> was reached.
7867: </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.
7868:
7869: </td></tr></tbody><tbody><tr><td><dfn id="event-media-durationchange" title="event-media-durationchange"><code>durationchange</code></dfn>
7870: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7871: </td><td>The <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute has just been updated.
7872: </td><td>
7873: </td></tr><tr><td><dfn id="event-media-timeupdate" title="event-media-timeupdate"><code>timeupdate</code></dfn>
7874: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7875: </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.
7876: </td><td>
7877: </td></tr><tr><td><dfn id="event-media-play" title="event-media-play"><code>play</code></dfn>
7878: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7879: </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.
7880: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false.
7881: </td></tr><tr><td><dfn id="event-media-pause" title="event-media-pause"><code>pause</code></dfn>
7882: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7883: </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.
7884: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly true.
7885: </td></tr><tr><td><dfn id="event-media-ratechange" title="event-media-ratechange"><code>ratechange</code></dfn>
7886: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7887: </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.
7888: </td><td>
7889: </td></tr><tr><td><dfn id="event-media-volumechange" title="event-media-volumechange"><code>volumechange</code></dfn>
7890: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7891: </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.
7892: </td><td>
7893: </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
7894: </th><th>Interface
1.64 mike 7895: </th><th>Fired when...
1.47 mike 7896:
7897: </th></tr></thead><tbody><tr><td><dfn id="event-mediacontroller-emptied" title="event-MediaController-emptied"><code>emptied</code></dfn>
7898: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7899: </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>.
7900: </td></tr><tr><td><dfn id="event-mediacontroller-loadedmetadata" title="event-MediaController-loadedmetadata"><code>loadedmetadata</code></dfn>
7901: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7902: </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.
7903: </td></tr><tr><td><dfn id="event-mediacontroller-loadeddata" title="event-MediaController-loadeddata"><code>loadeddata</code></dfn>
7904: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7905: </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.
7906: </td></tr><tr><td><dfn id="event-mediacontroller-canplay" title="event-MediaController-canplay"><code>canplay</code></dfn>
7907: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7908: </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.
7909: </td></tr><tr><td><dfn id="event-mediacontroller-canplaythrough" title="event-MediaController-canplaythrough"><code>canplaythrough</code></dfn>
7910: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7911: </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.
7912: </td></tr><tr><td><dfn id="event-mediacontroller-playing" title="event-MediaController-playing"><code>playing</code></dfn>
7913: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7914: </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 7915: </td></tr><tr><td><dfn id="event-mediacontroller-ended" title="event-MediaController-ended"><code>ended</code></dfn>
7916: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7917: </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 7918: </td></tr><tr><td><dfn id="event-mediacontroller-waiting" title="event-MediaController-waiting"><code>waiting</code></dfn>
7919: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7920: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is now a <a href="#blocked-media-controller">blocked media controller</a>.
7921: </td></tr><tr><td><dfn id="event-mediacontcoller-ended" title="event-MediaContcoller-ended"><code>ended</code></dfn>
7922: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7923: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> have newly <a href="#ended-playback">ended playback</a>.
7924:
7925: </td></tr></tbody><tbody><tr><td><dfn id="event-mediacontroller-durationchange" title="event-MediaController-durationchange"><code>durationchange</code></dfn>
7926: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7927: </td><td>The <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code> attribute has just been updated.
7928: </td></tr><tr><td><dfn id="event-mediacontroller-timeupdate" title="event-MediaController-timeupdate"><code>timeupdate</code></dfn>
7929: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7930: </td><td>The <a href="#media-controller-position">media controller position</a> changed.
7931: </td></tr><tr><td><dfn id="event-mediacontroller-play" title="event-MediaController-play"><code>play</code></dfn>
7932: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7933: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly false.
7934: </td></tr><tr><td><dfn id="event-mediacontroller-pause" title="event-MediaController-pause"><code>pause</code></dfn>
7935: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7936: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly true.
7937: </td></tr><tr><td><dfn id="event-mediacontroller-ratechange" title="event-MediaController-ratechange"><code>ratechange</code></dfn>
7938: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7939: </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.
7940: </td></tr><tr><td><dfn id="event-mediacontroller-volumechange" title="event-MediaController-volumechange"><code>volumechange</code></dfn>
7941: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7942: </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.
7943: </td></tr></tbody></table><div class="impl">
7944:
7945: <h5 id="security-and-privacy-considerations"><span class="secno">4.8.10.16 </span>Security and privacy considerations</h5>
7946:
7947: <p>The main security and privacy implications of the
7948: <code><a href="#the-video-element">video</a></code> and <code><a href="#the-audio-element">audio</a></code> elements come from the
7949: ability to embed media cross-origin. There are two directions that
7950: threats can flow: from hostile content to a victim page, and from a
7951: hostile page to victim content.</p>
7952:
7953: <hr><p>If a victim page embeds hostile content, the threat is that the
7954: content might contain scripted code that attempts to interact with
7955: the <code><a href="infrastructure.html#document">Document</a></code> that embeds the content. To avoid this,
7956: user agents must ensure that there is no access from the content to
7957: the embedding page. In the case of media content that uses DOM
7958: concepts, the embedded content must be treated as if it was in its
7959: own unrelated <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>.</p>
7960:
7961: <p class="example">For instance, if an SVG animation was embedded in
7962: a <code><a href="#the-video-element">video</a></code> element, the user agent would not give it
7963: access to the DOM of the outer page. From the perspective of scripts
7964: in the SVG resource, the SVG file would appear to be in a lone
7965: top-level browsing context with no parent.</p>
7966:
7967: <hr><p>If a hostile page embeds victim content, the threat is that the
7968: embedding page could obtain information from the content that it
1.58 mike 7969: would not otherwise have access to. The API does expose some
7970: information: the existence of the media, its type, its duration, its
7971: size, and the performance characteristics of its host. Such
7972: information is already potentially problematic, but in practice the
7973: same information can more or less be obtained using the
7974: <code><a href="embedded-content-1.html#the-img-element">img</a></code> element, and so it has been deemed acceptable.</p>
7975:
7976: <p>However, significantly more sensitive information could be
7977: obtained if the user agent further exposes metadata within the
1.61 mike 7978: content such as subtitles or chapter titles. Such information is
7979: therefore only exposed if the video resource passes a CORS
7980: <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
7981: authors to control how this check is performed. <a href="references.html#refsCORS">[CORS]</a></p>
7982:
7983: <p class="example">Without this restriction, an attacker could trick
7984: a user running within a corporate network into visiting a site that
7985: attempts to load a video from a previously leaked location on the
7986: corporation's intranet. If such a video included confidential plans
7987: for a new product, then being able to read the subtitles would
7988: present a serious confidentiality breach.</p>
1.47 mike 7989:
7990: </div><h5 id="best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.17 </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
7991: set-top boxes or mobile phones is often constrained by limited
7992: hardware resources in the device. For example, a device might only
7993: support three simultaneous videos. For this reason, it is a good
7994: practice to release resources held by <a href="#media-element" title="media
7995: element">media elements</a> when they are done playing, either by
7996: being very careful about removing all references to the element and
7997: allowing it to be garbage collected, or, even better, by removing
7998: the element's <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and
7999: any <code><a href="#the-source-element">source</a></code> element descendants, and invoking the
8000: 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,
8001: software, or format limitations can cause video frames to be dropped
8002: and audio to be choppy or muted.</p><div class="impl">
8003:
8004: <h5 id="best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.18 </span>Best practices for implementors of media elements</h5>
8005:
8006: <p><i>This section is non-normative.</i></p>
8007:
8008: <p>How accurately various aspects of the <a href="#media-element">media element</a>
8009: API are implemented is considered a quality-of-implementation issue.</p>
8010:
8011: <p>For example, when implementing the <code title="attr-media-buffered">buffered</code> attribute, how precise
8012: an implementation reports the ranges that have been buffered depends
8013: on how carefully the user agent inspects the data. Since the API
8014: reports ranges as times, but the data is obtained in byte streams, a
8015: user agent receiving a variable-bit-rate stream might only be able
8016: to determine precise times by actually decoding all of the data.
8017: User agents aren't required to do this, however; they can instead
8018: return estimates (e.g. based on the average bit rate seen so far)
8019: which get revised as more information becomes available.</p>
8020:
8021: <p>As a general rule, user agents are urged to be conservative
8022: rather than optimistic. For example, it would be bad to report that
8023: everything had been buffered when it had not.</p>
8024:
8025: <p>Another quality-of-implementation issue would be playing a video
8026: backwards when the codec is designed only for forward playback (e.g.
8027: there aren't many key frames, and they are far apart, and the
8028: intervening frames only have deltas from the previous frame). User
8029: agents could do a poor job, e.g. only showing key frames; however,
8030: better implementations would do more work and thus do a better job,
8031: e.g. actually decoding parts of the video forwards, storing the
8032: complete frames, and then playing the frames backwards.</p>
8033:
8034: <p>Similarly, while implementations are allowed to drop buffered
8035: data at any time (there is no requirement that a user agent keep all
8036: the media data obtained for the lifetime of the media element), it
8037: is again a quality of implementation issue: user agents with
8038: sufficient resources to keep all the data around are encouraged to
8039: do so, as this allows for a better user experience. For example, if
8040: the user is watching a live stream, a user agent could allow the
8041: user only to view the live video; however, a better user agent would
8042: buffer everything and allow the user to seek through the earlier
8043: material, pause it, play it forwards and backwards, etc.</p>
8044:
8045: <p>When multiple tracks are synchronised with a
8046: <code><a href="#mediacontroller">MediaController</a></code>, it is possible for scripts to add and
8047: remove media elements from the <code><a href="#mediacontroller">MediaController</a></code>'s list
8048: of <a href="#slaved-media-elements">slaved media elements</a>, even while these tracks are
8049: playing. How smoothly the media plays back in such situations is
8050: another quality-of-implementation issue.</p>
8051:
8052: <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
8053: document</a> and not reinserted before the next time the
8054: <a href="webappapis.html#event-loop">event loop</a> spins, implementations that are resource
8055: constrained are encouraged to take that opportunity to release all
8056: hardware resources (like video planes, networking resources, and
8057: data buffers) used by the <a href="#media-element">media element</a>. (User agents
8058: still have to keep track of the playback position and so forth,
8059: though, in case playback is later restarted.)</p>
8060:
1.1 mike 8061: </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