Annotation of html5/spec/the-iframe-element.html, revision 1.132
1.1 mike 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
1.61 mike 2: <!DOCTYPE html>
1.46 mike 3: <html lang="en-US-x-Hixie" class="split chapter"><head><title>4.8.2 The iframe element — HTML5 </title><style type="text/css">
1.1 mike 4: pre { margin-left: 2em; white-space: pre-wrap; }
5: h2 { margin: 3em 0 1em 0; }
6: h3 { margin: 2.5em 0 1em 0; }
7: h4 { margin: 2.5em 0 0.75em 0; }
8: h5, h6 { margin: 2.5em 0 1em; }
9: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
10: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
11: p { margin: 1em 0; }
12: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
13: dl, dd { margin-top: 0; margin-bottom: 0; }
14: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
15: dt + dt { margin-top: 0; }
16: dd dt { margin-top: 0.25em; margin-bottom: 0; }
17: dd p { margin-top: 0; }
18: dd dl + p { margin-top: 1em; }
19: dd table + p { margin-top: 1em; }
20: p + * > li, dd li { margin: 1em 0; }
21: dt, dfn { font-weight: bold; font-style: normal; }
1.83 mike 22: i, em { font-style: italic; }
1.1 mike 23: dt dfn { font-style: italic; }
24: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
25: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
26: pre em { font-weight: bolder; font-style: normal; }
27: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
28: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
29: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
30: table thead, table tbody { border-bottom: solid; }
31: table tbody th:first-child { border-left: solid; }
32: table tbody th { text-align: left; }
33: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
34: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
35:
36: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
37: .matrix, .matrix td { border: none; text-align: right; }
38: .matrix { margin-left: 2em; }
39: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
40: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
41: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
42:
43: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
1.96 mike 44: img.extra, p.overview { float: right; }
1.94 mike 45: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; position: relative; }
1.1 mike 46: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
1.94 mike 47: pre.idl::before { content: "IDL"; font: bold small sans-serif; padding: 0.5em; background: white; position: absolute; top: 0; margin: -1px 0 0 -4em; width: 1.5em; border: thin solid; border-radius: 0 0 0 0.5em }
1.1 mike 48: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
49: pre.css:first-line { color: #AAAA50; }
50: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
51: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
52: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
53: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
54: dl.domintro dd p { margin: 0.5em 0; }
1.124 mike 55: dl.domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
1.1 mike 56: dl.switch { padding-left: 2em; }
57: dl.switch > dt { text-indent: -1.5em; }
58: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
59: dl.triple { padding: 0 0 0 1em; }
60: dl.triple dt, dl.triple dd { margin: 0; display: inline }
61: dl.triple dt:after { content: ':'; }
62: dl.triple dd:after { content: '\A'; white-space: pre; }
63: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
64: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
65: a .diff-new { border-bottom: 1px blue solid; }
66:
67: h2 { page-break-before: always; }
68: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
69: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
70:
1.26 mike 71: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
72: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 mike 73:
74: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
75: div.head p { margin: 0; }
76: div.head h1 { margin: 0; }
77: div.head .logo { float: right; margin: 0 1em; }
78: div.head .logo img { border: none } /* remove border from top image */
79: div.head dl { margin: 1em 0; }
80: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
81:
82: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
83: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
84: body > .toc > li > * { margin-bottom: 0.5em; }
85: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
86: .toc, .toc li { list-style: none; }
87:
88: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
89: .brief li { margin: 0; padding: 0; }
90: .brief li p { margin: 0; padding: 0; }
91:
92: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
93: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
94: .category-list li { display: inline; }
95: .category-list li:not(:last-child)::after { content: ', '; }
96: .category-list li > span, .category-list li > a { text-transform: lowercase; }
97: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
98:
99: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
100: .XXX > :first-child { margin-top: 0; }
101: p .XXX { line-height: 3em; }
102: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
103: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
104: .annotation :link, .annotation :visited { color: inherit; }
105: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
106: .annotation span { border: none ! important; }
107: .note { color: green; background: transparent; font-family: sans-serif; }
108: .warning { color: red; background: transparent; }
109: .note, .warning { font-weight: bolder; font-style: italic; }
1.83 mike 110: .note em, .warning em, .note i, .warning i { font-style: normal; }
1.1 mike 111: p.note, div.note { padding: 0.5em 2em; }
112: span.note { padding: 0 2em; }
113: .note p:first-child, .warning p:first-child { margin-top: 0; }
114: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
115: .warning:before { font-style: normal; }
116: p.note:before { content: 'Note: '; }
117: p.warning:before { content: '\26A0 Warning! '; }
118:
119: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
120: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
121: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.12 mike 122: .bookkeeping dt { margin: 0.5em 2em 0; }
123: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 mike 124:
125: h4 { position: relative; z-index: 3; }
126: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
127: .element {
128: background: #EEEEFF;
129: color: black;
130: margin: 0 0 1em 0.15em;
131: padding: 0 1em 0.25em 0.75em;
132: border-left: solid #9999FF 0.25em;
133: position: relative;
134: z-index: 1;
135: }
136: .element:before {
137: position: absolute;
138: z-index: 2;
139: top: 0;
140: left: -1.15em;
141: height: 2em;
142: width: 0.9em;
143: background: #EEEEFF;
144: content: ' ';
145: border-style: none none solid solid;
146: border-color: #9999FF;
147: border-width: 0.25em;
148: }
149:
150: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
151: td > .example:only-child { margin: 0 0 0 0.1em; }
152:
153: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
154: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
155: ul.domTree li li { list-style: none; }
156: ul.domTree li:first-child::before { position: absolute; top: 0; height: 0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
157: ul.domTree li:not(:last-child)::after { position: absolute; top: 0; bottom: -0.6em; left: -0.75em; width: 0.5em; border-style: none none solid solid; content: ''; border-width: 0.1em; }
158: ul.domTree span { font-style: italic; font-family: serif; }
159: ul.domTree .t1 code { color: purple; font-weight: bold; }
160: ul.domTree .t2 { font-style: normal; font-family: monospace; }
161: ul.domTree .t2 .name { color: black; font-weight: bold; }
162: ul.domTree .t2 .value { color: blue; font-weight: normal; }
163: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
164: ul.domTree .t7 code, .domTree .t8 code { color: green; }
165: ul.domTree .t10 code { color: teal; }
166:
167: body.dfnEnabled dfn { cursor: pointer; }
168: .dfnPanel {
169: display: inline;
170: position: absolute;
171: z-index: 10;
172: height: auto;
173: width: auto;
174: padding: 0.5em 0.75em;
175: font: small sans-serif, Droid Sans Fallback;
176: background: #DDDDDD;
177: color: black;
178: border: outset 0.2em;
179: }
180: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
181: .dfnPanel :link, .dfnPanel :visited { color: black; }
182: .dfnPanel p { font-weight: bolder; }
183: .dfnPanel * + p { margin-top: 0.25em; }
184: .dfnPanel li { list-style-position: inside; }
185:
186: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
187: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
188: #configUI p label { display: block; }
189: #configUI #updateUI, #configUI .loginUI { text-align: center; }
190: #configUI input[type=button] { display: block; margin: auto; }
1.11 mike 191:
1.30 mike 192: fieldset { margin: 1em; padding: 0.5em 1em; }
193: fieldset > legend + * { margin-top: 0; }
1.21 mike 194: fieldset > :last-child { margin-bottom: 0; }
1.30 mike 195: fieldset p { margin: 0.5em 0; }
196:
1.62 mike 197: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><style type="text/css">
1.1 mike 198:
199: .applies thead th > * { display: block; }
200: .applies thead code { display: block; }
201: .applies tbody th { whitespace: nowrap; }
202: .applies td { text-align: center; }
203: .applies .yes { background: yellow; }
204:
1.14 mike 205: .matrix, .matrix td { border: hidden; text-align: right; }
1.1 mike 206: .matrix { margin-left: 2em; }
207:
208: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
209: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
210: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
211:
1.17 mike 212: td.eg { border-width: thin; text-align: center; }
213:
1.1 mike 214: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
215: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
216: #table-example-1 caption { padding-bottom: 0.5em; }
217: #table-example-1 thead, #table-example-1 tbody { border: none; }
218: #table-example-1 th, #table-example-1 td { border: solid thin; }
219: #table-example-1 th { font-weight: normal; }
220: #table-example-1 td { border-style: none solid; vertical-align: top; }
221: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
222: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
223: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
224: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
225: #table-example-1 tbody td:first-child::after { content: leader(". "); }
226: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
227: #table-example-1 tbody td:first-child + td { width: 10em; }
228: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
229: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
230:
231: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
232: .apple-table-examples * { font-family: "Times", serif; }
233: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
234: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
235: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
236: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
237: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
238: .apple-table-examples td { text-align: right; vertical-align: top; }
239: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
240: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
241: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
242: .apple-table-examples sup { line-height: 0; }
243:
244: .details-example img { vertical-align: top; }
245:
1.40 mike 246: #base64-table {
247: white-space: nowrap;
248: font-size: 0.6em;
249: column-width: 6em;
250: column-count: 5;
251: column-gap: 1em;
252: -moz-column-width: 6em;
253: -moz-column-count: 5;
254: -moz-column-gap: 1em;
255: -webkit-column-width: 6em;
256: -webkit-column-count: 5;
257: -webkit-column-gap: 1em;
258: }
259: #base64-table thead { display: none; }
260: #base64-table * { border: none; }
261: #base64-table tbody td:first-child:after { content: ':'; }
262: #base64-table tbody td:last-child { text-align: right; }
263:
1.1 mike 264: #named-character-references-table {
1.19 mike 265: white-space: nowrap;
1.1 mike 266: font-size: 0.6em;
1.19 mike 267: column-width: 30em;
1.1 mike 268: column-gap: 1em;
1.19 mike 269: -moz-column-width: 30em;
1.1 mike 270: -moz-column-gap: 1em;
1.19 mike 271: -webkit-column-width: 30em;
1.1 mike 272: -webkit-column-gap: 1em;
273: }
1.19 mike 274: #named-character-references-table > table > tbody > tr > td:first-child + td,
1.1 mike 275: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
276: #named-character-references-table > table > tbody > tr > td:last-child:hover > span { position: absolute; top: auto; left: auto; margin-left: 0.5em; line-height: 1.2; font-size: 5em; border: outset; padding: 0.25em 0.5em; background: white; width: 1.25em; height: auto; text-align: center; }
1.19 mike 277: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
1.1 mike 278:
1.2 mike 279: .glyph.control { color: red; }
280:
1.4 mike 281: @font-face {
282: font-family: 'Essays1743';
283: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
284: }
285: @font-face {
286: font-family: 'Essays1743';
287: font-weight: bold;
288: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
289: }
290: @font-face {
291: font-family: 'Essays1743';
292: font-style: italic;
293: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
294: }
295: @font-face {
296: font-family: 'Essays1743';
297: font-style: italic;
298: font-weight: bold;
299: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
300: }
301:
1.61 mike 302: </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script type="text/javascript">
1.45 mike 303: function getCookie(name) {
304: var params = location.search.substr(1).split("&");
305: for (var index = 0; index < params.length; index++) {
306: if (params[index] == name)
307: return "1";
308: var data = params[index].split("=");
309: if (data[0] == name)
310: return unescape(data[1]);
311: }
312: var cookies = document.cookie.split("; ");
313: for (var index = 0; index < cookies.length; index++) {
314: var data = cookies[index].split("=");
315: if (data[0] == name)
316: return unescape(data[1]);
317: }
318: return null;
319: }
320: </script>
1.1 mike 321: <script src="link-fixup.js"></script>
1.36 mike 322: <link href="style.css" rel="stylesheet"><link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
1.1 mike 323: <link href="spec.html#contents" title="Table of contents" rel="index">
1.47 mike 324: <link href="the-canvas-element.html" title="4.8.11 The canvas element" rel="next">
1.54 mike 325: </head><body><div class="head" id="head">
1.1 mike 326: <p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
1.3 mike 327:
1.1 mike 328: <h1>HTML5</h1>
329: </div><div>
1.36 mike 330: <a href="embedded-content-1.html" class="prev">4.8 Embedded content</a> –
1.1 mike 331: <a href="spec.html#contents">Table of contents</a> –
1.47 mike 332: <a href="the-canvas-element.html" class="next">4.8.11 The canvas element</a>
333: <ol class="toc"><li><ol><li><ol><li><a href="the-iframe-element.html#the-iframe-element"><span class="secno">4.8.2 </span>The <code>iframe</code> element</a></li><li><a href="the-iframe-element.html#the-embed-element"><span class="secno">4.8.3 </span>The <code>embed</code> element</a></li><li><a href="the-iframe-element.html#the-object-element"><span class="secno">4.8.4 </span>The <code>object</code> element</a></li><li><a href="the-iframe-element.html#the-param-element"><span class="secno">4.8.5 </span>The <code>param</code> element</a></li><li><a href="the-iframe-element.html#the-video-element"><span class="secno">4.8.6 </span>The <code>video</code> element</a></li><li><a href="the-iframe-element.html#the-audio-element"><span class="secno">4.8.7 </span>The <code>audio</code> element</a></li><li><a href="the-iframe-element.html#the-source-element"><span class="secno">4.8.8 </span>The <code>source</code> element</a></li><li><a href="the-iframe-element.html#the-track-element"><span class="secno">4.8.9 </span>The <code>track</code> element</a></li><li><a href="the-iframe-element.html#media-elements"><span class="secno">4.8.10 </span>Media elements</a>
1.65 mike 334: <ol><li><a href="the-iframe-element.html#error-codes"><span class="secno">4.8.10.1 </span>Error codes</a></li><li><a href="the-iframe-element.html#location-of-the-media-resource"><span class="secno">4.8.10.2 </span>Location of the media resource</a></li><li><a href="the-iframe-element.html#mime-types"><span class="secno">4.8.10.3 </span>MIME types</a></li><li><a href="the-iframe-element.html#network-states"><span class="secno">4.8.10.4 </span>Network states</a></li><li><a href="the-iframe-element.html#loading-the-media-resource"><span class="secno">4.8.10.5 </span>Loading the media resource</a></li><li><a href="the-iframe-element.html#offsets-into-the-media-resource"><span class="secno">4.8.10.6 </span>Offsets into the media resource</a></li><li><a href="the-iframe-element.html#ready-states"><span class="secno">4.8.10.7 </span>Ready states</a></li><li><a href="the-iframe-element.html#playing-the-media-resource"><span class="secno">4.8.10.8 </span>Playing the media resource</a></li><li><a href="the-iframe-element.html#seeking"><span class="secno">4.8.10.9 </span>Seeking</a></li><li><a href="the-iframe-element.html#media-resources-with-multiple-media-tracks"><span class="secno">4.8.10.10 </span>Media resources with multiple media tracks</a>
1.76 mike 335: <ol><li><a href="the-iframe-element.html#audiotracklist-and-videotracklist-objects"><span class="secno">4.8.10.10.1 </span><code>AudioTrackList</code> and <code>VideoTrackList</code> objects</a></li><li><a href="the-iframe-element.html#selecting-specific-audio-and-video-tracks-declaratively"><span class="secno">4.8.10.10.2 </span>Selecting specific audio and video tracks declaratively</a></li></ol></li><li><a href="the-iframe-element.html#synchronising-multiple-media-elements"><span class="secno">4.8.10.11 </span>Synchronising multiple media elements</a>
1.47 mike 336: <ol><li><a href="the-iframe-element.html#introduction-0"><span class="secno">4.8.10.11.1 </span>Introduction</a></li><li><a href="the-iframe-element.html#media-controllers"><span class="secno">4.8.10.11.2 </span>Media controllers</a></li><li><a href="the-iframe-element.html#assigning-a-media-controller-declaratively"><span class="secno">4.8.10.11.3 </span>Assigning a media controller declaratively</a></li></ol></li><li><a href="the-iframe-element.html#timed-text-tracks"><span class="secno">4.8.10.12 </span>Timed text tracks</a>
1.121 mike 337: <ol><li><a href="the-iframe-element.html#text-track-model"><span class="secno">4.8.10.12.1 </span>Text track model</a></li><li><a href="the-iframe-element.html#sourcing-in-band-text-tracks"><span class="secno">4.8.10.12.2 </span>Sourcing in-band text tracks</a></li><li><a href="the-iframe-element.html#sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</a></li><li><a href="the-iframe-element.html#text-track-api"><span class="secno">4.8.10.12.4 </span>Text track API</a></li><li><a href="the-iframe-element.html#text-tracks-describing-chapters"><span class="secno">4.8.10.12.5 </span>Text tracks describing chapters</a></li><li><a href="the-iframe-element.html#cue-events"><span class="secno">4.8.10.12.6 </span>Event definitions</a></li></ol></li><li><a href="the-iframe-element.html#user-interface"><span class="secno">4.8.10.13 </span>User interface</a></li><li><a href="the-iframe-element.html#time-ranges"><span class="secno">4.8.10.14 </span>Time ranges</a></li><li><a href="the-iframe-element.html#event-definitions"><span class="secno">4.8.10.15 </span>Event definitions</a></li><li><a href="the-iframe-element.html#mediaevents"><span class="secno">4.8.10.16 </span>Event summary</a></li><li><a href="the-iframe-element.html#security-and-privacy-considerations"><span class="secno">4.8.10.17 </span>Security and privacy considerations</a></li><li><a href="the-iframe-element.html#best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.18 </span>Best practices for authors using media elements</a></li><li><a href="the-iframe-element.html#best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.19 </span>Best practices for implementors of media elements</a></li></ol></li></ol></li></ol></li></ol></div>
1.1 mike 338:
1.25 mike 339: <h4 id="the-iframe-element"><span class="secno">4.8.2 </span>The <dfn><code>iframe</code></dfn> element</h4><dl class="element"><dt>Categories</dt>
1.1 mike 340: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
341: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
342: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
343: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 344: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.16 mike 345: <dt>Contexts in which this element can be used:</dt>
1.1 mike 346: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
347: <dt>Content model:</dt>
1.18 mike 348: <dd>Text that conforms to <a href="#iframe-content-model">the requirements given in the prose</a>.</dd>
1.1 mike 349: <dt>Content attributes:</dt>
350: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
351: <dd><code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code></dd>
352: <dd><code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code></dd>
353: <dd><code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code></dd>
354: <dd><code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code></dd>
355: <dd><code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code></dd>
356: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
357: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
358: <dt>DOM interface:</dt>
359: <dd>
360: <pre class="idl">interface <dfn id="htmliframeelement">HTMLIFrameElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
361: attribute DOMString <a href="#dom-iframe-src" title="dom-iframe-src">src</a>;
362: attribute DOMString <a href="#dom-iframe-srcdoc" title="dom-iframe-srcdoc">srcdoc</a>;
363: attribute DOMString <a href="#dom-iframe-name" title="dom-iframe-name">name</a>;
1.81 mike 364: [PutForwards=<span title="dom-DOMSettableTokenList-value">value</span>] readonly attribute <a href="infrastructure.html#domsettabletokenlist">DOMSettableTokenList</a> <a href="#dom-iframe-sandbox" title="dom-iframe-sandbox">sandbox</a>;
1.1 mike 365: attribute boolean <a href="#dom-iframe-seamless" title="dom-iframe-seamless">seamless</a>;
366: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
367: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1.68 mike 368: readonly attribute Document? <a href="#dom-iframe-contentdocument" title="dom-iframe-contentDocument">contentDocument</a>;
369: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a>? <a href="#dom-iframe-contentwindow" title="dom-iframe-contentWindow">contentWindow</a>;
1.1 mike 370: };</pre>
371: </dd>
1.101 mike 372: </dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
1.1 mike 373: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p><p>The <dfn id="attr-iframe-src" title="attr-iframe-src"><code>src</code></dfn> attribute
374: gives the address of a page that the <a href="browsers.html#nested-browsing-context">nested browsing
375: context</a> is to contain. The attribute, if present, must be a
376: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
377: spaces</a>.</p><p>The <dfn id="attr-iframe-srcdoc" title="attr-iframe-srcdoc"><code>srcdoc</code></dfn>
378: attribute gives the content of the page that the <a href="browsers.html#nested-browsing-context">nested
1.32 mike 379: browsing context</a> is to contain. The value of the attribute is
1.82 mike 380: the source of <dfn id="an-iframe-srcdoc-document">an <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code> document</dfn>.</p><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="infrastructure.html#html-documents">HTML documents</a>,
1.101 mike 381: the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
1.1 mike 382: syntax</a> that consists of the following syntactic components,
1.101 mike 383: in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
1.1 mike 384: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
385:
1.101 mike 386: <li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
1.1 mike 387:
1.101 mike 388: </li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
1.1 mike 389: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
390:
1.101 mike 391: <li>The root element, in the form of an <code><a href="semantics.html#the-html-element">html</a></code> <a href="syntax.html#syntax-elements" title="syntax-elements">element</a>.</li>
1.1 mike 392:
1.101 mike 393: <li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
1.1 mike 394: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
395:
1.82 mike 396: </ol><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="infrastructure.html#xml-documents">XML documents</a>,
1.1 mike 397: the attribute, if present, must have a value that matches the
398: production labeled <code><a href="infrastructure.html#document">document</a></code> in the XML
1.101 mike 399: specification. <a href="references.html#refsXML">[XML]</a></p><p>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute and the
1.1 mike 400: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute are both
401: specified together, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code>
402: attribute takes priority. This allows authors to provide a fallback
403: <a href="urls.html#url">URL</a> for legacy user agents that do not support the
404: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute.</p><div class="impl">
405:
406: <p>When an <code><a href="#the-iframe-element">iframe</a></code> element is first <a href="infrastructure.html#insert-an-element-into-a-document" title="insert
407: an element into a document">inserted into a document</a>, the
408: user agent must create a <a href="browsers.html#nested-browsing-context">nested browsing context</a>, and
409: then <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> for the
410: first time.</p>
411:
412: <p>Whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a <a href="browsers.html#nested-browsing-context">nested
1.32 mike 413: browsing context</a> has its <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute set, changed, or
414: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.1 mike 415: attributes</a>.</p>
416:
417: <p>Similarly, whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a
418: <a href="browsers.html#nested-browsing-context">nested browsing context</a> but with no <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute specified has its
1.32 mike 419: <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute set, changed, or
420: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.46 mike 421: attributes</a>.</p>
1.1 mike 422: <p>When the user agent is to <dfn id="process-the-iframe-attributes">process the <code>iframe</code>
423: attributes</dfn>, it must run the first appropriate steps from the
424: following list:</p>
425:
426: <dl class="switch"><dt>If the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute
427: is specified</dt>
428:
1.46 mike 429: <dd><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 430: <a href="browsers.html#browsing-context">browsing context</a> to a resource whose
1.101 mike 431: <a href="fetching-resources.html#content-type">Content-Type</a> is <code><a href="iana.html#text-html">text/html</a></code>, whose
1.34 mike 432: <a href="urls.html#url">URL</a> is <code><a href="urls.html#about:srcdoc">about:srcdoc</a></code>, and whose data
433: consists of the value of the attribute. The resulting
434: <code><a href="infrastructure.html#document">Document</a></code> must be considered <a href="#an-iframe-srcdoc-document">an
435: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
436: document</a>.</p></dd>
1.1 mike 437:
438: <dt>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code>
439: attribute is specified but the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not</dt>
440:
441: <dd>
442:
443: <ol><li><p>If the value of the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is the empty string,
444: jump to the <i title="">empty</i> step below.</p></li>
445:
446: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of
447: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute, relative
448: to the <code><a href="#the-iframe-element">iframe</a></code> element.</p></li>
449:
450: <li><p>If that is not successful, then jump to the <i title="">empty</i> step below.</p></li>
451:
452: <li><p>If the resulting <a href="urls.html#absolute-url">absolute URL</a> is an
453: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for the string
454: "<code><a href="fetching-resources.html#about:blank">about:blank</a></code>", and the user agent is processing this
455: <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first time, then jump to
456: the <i title="">empty</i> step below. (In cases other than the
457: first time, <code><a href="fetching-resources.html#about:blank">about:blank</a></code> is loaded
458: normally.)</p></li>
459:
1.46 mike 460: <li><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 461: <a href="browsers.html#browsing-context">browsing context</a> to the resulting <a href="urls.html#absolute-url">absolute
1.1 mike 462: URL</a>.</p></li>
463:
464: </ol><p><i>Empty</i>: When the steps above require the user agent to
465: jump to the <i title="">empty</i> step, if the user agent is
466: processing this <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first
467: time, then the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
1.66 mike 468: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-load">load</code> at the <code><a href="#the-iframe-element">iframe</a></code> element.
469: (After jumping to this step, the above steps are not resumed.)
470: <span class="note">No <code title="event-load">load</code> event
471: is fired at the <code><a href="fetching-resources.html#about:blank">about:blank</a></code> document
472: itself.</span></p>
1.1 mike 473:
474: </dd>
475:
476: <dt>Otherwise</dt>
477:
478: <dd>
479:
480: <p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
481: named <code title="event-load">load</code> at the
482: <code><a href="#the-iframe-element">iframe</a></code> element.</p>
483:
484: </dd>
485:
486: </dl><p>Any <a href="history.html#navigate" title="navigate">navigation</a> required of the user
487: agent in the <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a>
488: algorithm must be completed with the <code><a href="#the-iframe-element">iframe</a></code> element's
489: document's <a href="browsers.html#browsing-context">browsing context</a> as the <a href="history.html#source-browsing-context">source
490: browsing context</a>.</p>
491:
1.8 mike 492: <p>Furthermore, if the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="history.html#session-history">session
493: history</a> contained only one <code><a href="infrastructure.html#document">Document</a></code> when the
494: <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> algorithm
495: was invoked, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
496: <code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
497: was created, then any <a href="history.html#navigate" title="navigate">navigation</a>
498: required of the user agent in that algorithm must be completed with
1.46 mike 499: <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
1.1 mike 500: </div><p class="note">If, when the element is created, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not set, and
501: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is either
502: also not set or set but its value cannot be <a href="urls.html#resolve-a-url" title="resolve a
503: url">resolved</a>, the browsing context will remain at the
504: initial <code><a href="fetching-resources.html#about:blank">about:blank</a></code> page.</p><p class="note">If the user <a href="history.html#navigate" title="navigate">navigates</a>
505: away from this page, the <code><a href="#the-iframe-element">iframe</a></code>'s corresponding
506: <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object will proxy new <code><a href="browsers.html#window">Window</a></code>
1.9 mike 507: objects for new <code><a href="infrastructure.html#document">Document</a></code> objects, but the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute will not change.</p><div class="impl">
508:
509: <div class="note">
510:
511: <p><a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">Removing</a>
512: an <code><a href="#the-iframe-element">iframe</a></code> from a <code><a href="infrastructure.html#document">Document</a></code> does not cause
513: its <a href="browsers.html#browsing-context">browsing context</a> to be discarded. Indeed, an
514: <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> can survive its
515: original parent <code><a href="infrastructure.html#document">Document</a></code> if its <code><a href="#the-iframe-element">iframe</a></code> is
516: moved to another <code><a href="infrastructure.html#document">Document</a></code>.</p>
517:
1.10 mike 518: <p>On the other hand, if an <code><a href="#the-iframe-element">iframe</a></code> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">removed</a> from a
519: <code><a href="infrastructure.html#document">Document</a></code> and is then subsequently garbage collected,
520: this will likely mean (in the absence of other references) that the
521: <a href="browsers.html#child-browsing-context">child browsing context</a>'s <code><a href="browsers.html#windowproxy">WindowProxy</a></code>
522: object will become eligble for garbage collection, which will then
523: lead to that <a href="browsers.html#browsing-context">browsing context</a> being <a href="browsers.html#a-browsing-context-is-discarded" title="a
524: browsing context is discarded">discarded</a>, which will then
525: lead to its <code><a href="infrastructure.html#document">Document</a></code> being <a href="browsers.html#discard-a-document" title="discard a
1.9 mike 526: document">discarded</a> also. This happens without notice to any
527: scripts running in that <code><a href="infrastructure.html#document">Document</a></code>; for example, no
528: <code title="event-unload">unload</code> events are fired (the
1.10 mike 529: "<a href="history.html#unload-a-document">unload a document</a>" steps are not run).</p>
1.9 mike 530:
531: </div>
532:
533: </div><div class="example">
1.1 mike 534:
535: <p>Here a blog uses the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute in conjunction
536: with the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> and <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attributes described
537: below to provide users of user agents that support this feature
538: with an extra layer of protection from script injection in the blog
539: post comments:</p>
540:
541: <pre><article>
542: <h1>I got my own magazine!</h1>
543: <p>After much effort, I've finally found a publisher, and so now I
544: have my own magazine! Isn't that awesome?! The first issue will come
545: out in September, and we have articles about getting food, and about
546: getting in boxes, it's going to be great!</p>
547: <footer>
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
1.101 mike 566: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute would end
567: prematurely), and the way raw ampersands (e.g. in URLs or in prose)
568: mentioned in the sandboxed content have to be <em>doubly</em>
569: escaped — once so that the ampersand is preserved when
570: originally parsing the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute, and once more
1.1 mike 571: to prevent the ampersand from being misinterpreted when parsing the
572: sandboxed content.</p>
573:
1.101 mike 574: </div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
1.1 mike 575: remember to use U+0022 QUOTATION MARK characters (") to wrap the
576: attribute contents and then to escape all U+0022 QUOTATION MARK (")
577: and U+0026 AMPERSAND (&) characters, and to specify the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, to ensure safe
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
1.101 mike 584: escaped. <a href="references.html#refsXML">[XML]</a></p><hr><p>The <dfn id="attr-iframe-name" title="attr-iframe-name"><code>name</code></dfn>
1.1 mike 585: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
586: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
587: browsing context</a>. <span class="impl">When the browsing
588: context is created, if the attribute is present, the <a href="browsers.html#browsing-context-name">browsing
589: context name</a> must be set to the value of this attribute;
590: otherwise, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set to the
591: empty string.</span></p><div class="impl">
592:
593: <p>Whenever the <code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code> attribute
594: is set, the nested <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#browsing-context-name" title="browsing context name">name</a> must be changed to the new
595: value. If the attribute is removed, the <a href="browsers.html#browsing-context-name">browsing context
596: name</a> must be set to the empty string.</p>
597:
598: <p>When content loads in an <code><a href="#the-iframe-element">iframe</a></code>, after any <code title="event-load">load</code> events are fired within the content
599: itself, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
600: a simple event</a> named <code title="event-load">load</code> at
601: the <code><a href="#the-iframe-element">iframe</a></code> element. When content whose <a href="urls.html#url">URL</a>
602: has the <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code>
603: element's <code><a href="infrastructure.html#document">Document</a></code> fails to load (e.g. due to a DNS
604: error, network error, or if the server returned a 4xx or 5xx status
605: code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or
606: equivalent</a>), then the user agent must <a href="webappapis.html#queue-a-task">queue a
607: task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the element instead. (This event
1.101 mike 608: does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
1.1 mike 609: script errors, or any errors for cross-origin resources.)</p>
610:
611: <p>The <a href="webappapis.html#task-source">task source</a> for these <a href="webappapis.html#concept-task" title="concept-task">tasks</a> is the <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation
612: task source</a>.</p>
613:
614: <p class="note">A <code title="event-load">load</code> event is also
615: fired at the <code><a href="#the-iframe-element">iframe</a></code> element when it is created if no
616: other data is loaded in it.</p>
617:
618: <p>When there is an <a href="dom.html#active-parser">active parser</a> in the
619: <code><a href="#the-iframe-element">iframe</a></code>, and when anything in the <code><a href="#the-iframe-element">iframe</a></code> is
1.101 mike 620: <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
1.1 mike 621: the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a>'s
622: <a href="browsers.html#active-document">active document</a>, the <code><a href="#the-iframe-element">iframe</a></code> must
1.101 mike 623: <a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
1.1 mike 624:
625: <p class="note">If, during the handling of the <code title="event-load">load</code> event, the <a href="browsers.html#browsing-context">browsing
1.101 mike 626: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> is again <a href="history.html#navigate" title="navigate">navigated</a>, that will further <a href="the-end.html#delay-the-load-event">delay the
1.1 mike 627: load event</a>.</p>
628:
629: </div><hr><p>The <dfn id="attr-iframe-sandbox" title="attr-iframe-sandbox"><code>sandbox</code></dfn>
630: attribute, when specified, enables a set of extra restrictions on
631: any content hosted by the <code><a href="#the-iframe-element">iframe</a></code>. Its value must be an
1.20 mike 632: <a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique space-separated tokens</a> that are
1.77 mike 633: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a>. The allowed values are
1.1 mike 634: <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code>,
1.77 mike 635: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>,
636: <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>, and
637: <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>.
638:
639: When the attribute is set, the content is treated as being from a
640: unique <a href="origin-0.html#origin">origin</a>, forms and scripts are disabled, links
641: are prevented from targeting other <a href="browsers.html#browsing-context" title="browsing
1.114 mike 642: context">browsing contexts</a>, and plugins are secured. The
1.1 mike 643: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
644: keyword allows the content to be treated as being from the same
645: origin instead of forcing it into a unique origin, the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
646: keyword allows the content to <a href="history.html#navigate">navigate</a> its
647: <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>, and the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> and <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
648: keywords re-enable forms and scripts respectively (though scripts
1.77 mike 649: are still prevented from creating popups).</p><p class="warning">Setting both the
650: <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code> and
1.1 mike 651: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
652: keywords together when the embedded page has the <a href="origin-0.html#same-origin">same
653: origin</a> as the page containing the <code><a href="#the-iframe-element">iframe</a></code> allows
654: the embedded page to simply remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">Sandboxing hostile content is of minimal help if
655: an attacker can convince the user to just visit the hostile content
656: directly, rather than in the <code><a href="#the-iframe-element">iframe</a></code>. To limit the
657: damage that can be caused by hostile HTML content, it should be
1.127 mike 658: served from a separate dedicated domain.</p><div class="impl">
1.1 mike 659:
1.46 mike 660:
1.1 mike 661: <p>While the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
662: attribute is specified, the <code><a href="#the-iframe-element">iframe</a></code> element's
663: <a href="browsers.html#nested-browsing-context">nested browsing context</a> must have the flags given in
664: the following list set. In addition, any browsing contexts <a href="browsers.html#nested-browsing-context" title="nested browsing context">nested</a> within an
665: <code><a href="#the-iframe-element">iframe</a></code>, either directly or indirectly, must have all
666: the flags set on them as were set on the <code><a href="#the-iframe-element">iframe</a></code>'s
667: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> when the
668: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
669:
670: <dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
671:
672: <dd>
673:
674: <p>This flag <a href="history.html#sandboxLinks">prevents content from
675: navigating browsing contexts other than the sandboxed browsing
676: context itself</a> (or browsing contexts further nested inside
677: it), and the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> (which is
678: protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
679: context flag</a> defined next).</p>
680:
681: <p>This flag also <a href="browsers.html#sandboxWindowOpen">prevents content
682: from creating new auxiliary browsing contexts</a>, e.g. using the
1.72 mike 683: <code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute, the
684: <code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> method, or the <code title="dom-showModalDialog"><a href="timers.html#dom-showmodaldialog">showModalDialog()</a></code> method.</p>
1.1 mike 685:
686: </dd>
687:
688:
689: <dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
690: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
691: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
692: found to have the <dfn id="attr-iframe-sandbox-allow-top-navigation" title="attr-iframe-sandbox-allow-top-navigation"><code>allow-top-navigation</code></dfn>
693: keyword set</dt>
694:
695: <dd>
696:
697: <p>This flag <a href="history.html#sandboxLinks">prevents content from
698: navigating their <span>top-level browsing context</span></a>.</p>
699:
700: <p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
701: is set, content can navigate its <a href="browsers.html#top-level-browsing-context">top-level browsing
702: context</a>, but other <a href="browsers.html#browsing-context" title="browsing context">browsing
703: contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
704: navigation browsing context flag</a> defined above.</p>
705:
706: </dd>
707:
708:
709: <dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
710:
711: <dd>
712:
713: <p>This flag prevents content from instantiating <a href="infrastructure.html#plugin" title="plugin">plugins</a>, whether using <a href="#sandboxPluginEmbed">the <code>embed</code> element</a>, <a href="#sandboxPluginObject">the <code>object</code> element</a>,
1.101 mike 714: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
1.1 mike 715: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
1.114 mike 716: browsing context</a>, unless those <a href="infrastructure.html#plugin" title="plugin">plugins</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>.</p>
1.1 mike 717:
718: </dd>
719:
720:
721: <dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
722:
723: <dd>
724:
725: <p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attribute on
726: descendant <code><a href="#the-iframe-element">iframe</a></code> elements.</p>
727:
728: <p class="note">This prevents a page inserted using the <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
729: keyword from using a CSS-selector-based method of probing the DOM
730: of other pages on the same site (in particular, pages that contain
731: user-sensitive information).</p>
732:
1.46 mike 733:
1.1 mike 734:
735: </dd>
736:
737:
738: <dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn>, unless
739: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
740: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
741: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-same-origin" title="attr-iframe-sandbox-allow-same-origin"><code>allow-same-origin</code></dfn>
742: keyword set</dt>
743:
744: <dd>
745:
746: <p>This flag <a href="origin-0.html#sandboxOrigin">forces content into a unique
747: origin</a>, thus preventing it from accessing other content from
748: the same <a href="origin-0.html#origin">origin</a>.</p>
749:
750: <p>This flag also <a href="dom.html#sandboxCookies">prevents script from
751: reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
1.38 mike 752: attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code>.
1.1 mike 753:
1.101 mike 754: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
1.1 mike 755:
756: </p>
757:
758: <div class="note">
759:
760: <p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
761: attribute is intended for two cases.</p>
762:
763: <p>First, it can be used to allow content from the same site to
764: be sandboxed to disable scripting, while still allowing access to
765: the DOM of the sandboxed content.</p>
766:
767: <p>Second, it can be used to embed content from a third-party
768: site, sandboxed to prevent that site from opening popup windows,
769: etc, without preventing the embedded page from communicating back
770: to its originating site, using the database APIs to store data,
771: etc.</p>
772:
773: </div>
774:
775: </dd>
776:
777:
778: <dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn>, unless
779: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
780: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
781: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-forms" title="attr-iframe-sandbox-allow-forms"><code>allow-forms</code></dfn>
782: keyword set</dt>
783:
784: <dd>
785:
786: <p>This flag <a href="association-of-controls-and-forms.html#sandboxSubmitBlocked">blocks form
787: submission</a>.</p>
788:
789: </dd>
790:
791:
792: <dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn>, unless
793: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
794: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
795: spaces</a>, is found to have the <dfn id="attr-iframe-sandbox-allow-scripts" title="attr-iframe-sandbox-allow-scripts"><code>allow-scripts</code></dfn>
796: keyword set</dt>
797:
798: <dd>
799:
800: <p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
801: execution</a>.</p>
802:
803: </dd>
804:
805:
806: <dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
807: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
808: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
809: found to have the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
810: keyword (defined above) set</dt>
811:
812: <dd>
813:
814: <p>This flag blocks features that trigger automatically, such as
1.47 mike 815: <a href="#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
1.1 mike 816: video</a> or <a href="association-of-controls-and-forms.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
817: focusing a form control</a>. It is relaxed by the same flag as
818: scripts, because when scripts are enabled these features are
819: trivially possible anyway, and it would be unfortunate to force
820: authors to use script to do them when sandboxed rather than
821: allowing them to use the declarative features.</p>
822:
823: </dd>
824:
825: </dl><p>These flags must not be set unless the conditions listed above
826: define them as being set.</p>
827:
828: <p class="warning">These flags only take effect when the
829: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code> is
1.15 mike 830: <a href="history.html#navigate" title="navigate">navigated</a>. Removing them, or removing
1.1 mike 831: the entire <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
832: attribute, has no effect on an already-loaded page.</p>
833:
834: </div><div class="example">
835:
836: <p>In this example, some completely-unknown, potentially hostile,
837: user-provided HTML content is embedded in a page. Because it is
1.127 mike 838: served from a separate domain, it is affected by all the normal
839: cross-site restrictions. In addition, the embedded page has
840: scripting disabled, plugins disabled, forms disabled, and it cannot
841: navigate any frames or windows other than itself (or any frames or
842: windows it itself embeds).</p>
1.1 mike 843:
844: <pre><p>We're not scared of you! Here is your content, unedited:</p>
1.127 mike 845: <iframe sandbox src="http://usercontent.example.net/getusercontent.cgi?id=12193"></iframe></pre>
1.1 mike 846:
1.127 mike 847: <p class="warning">It is important to use a separate domain so that
848: if the attacker convinces the user to visit that page directly, the
849: page doesn't run in the context of the site's origin, which would
850: make the user vulnerable to any attack found in the page.</p>
1.1 mike 851:
852: </div><div class="example">
853:
854: <p>In this example, a gadget from another site is embedded. The
855: gadget has scripting and forms enabled, and the origin sandbox
856: restrictions are lifted, allowing the gadget to communicate with
857: its originating server. The sandbox is still useful, however, as it
858: disables plugins and popups, thus reducing the risk of the user
859: being exposed to malware and other annoyances.</p>
860:
861: <pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
862: src="http://maps.example.com/embedded.html"></iframe></pre>
863:
864: </div><div class="example">
865:
866: <p>Suppose a file A contained the following fragment:</p>
867:
868: <pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
869:
870: <p>Suppose that file B contained an iframe also:</p>
871:
872: <pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
873:
874: <p>Further, suppose that file C contained a link:</p>
875:
876: <pre><a href=D>Link</a></pre>
877:
878: <p>For this example, suppose all the files were served as
1.101 mike 879: <code><a href="iana.html#text-html">text/html</a></code>.</p>
1.1 mike 880:
881: <p>Page C in this scenario has all the sandboxing flags
882: set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
883: scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
884: keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
885: disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
886: have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
887: set.</p>
888:
889: <p>Suppose now that a script in A removes all the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attributes in A and
890: B. This would change nothing immediately. If the user clicked the
891: link in C, loading page D into the <code><a href="#the-iframe-element">iframe</a></code> in B, page D
892: 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>
893: and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
894: set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
895: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
896: loaded.</p>
897:
898: <p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
899: ill-advised, because it can make it quite hard to reason about what
900: will be allowed and what will not.</p>
901:
1.127 mike 902: </div><p class="note">Potentially hostile files should not be served from
903: the same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code>
904: element. Using a different domain ensures that scripts in the files
905: are unable to attack the site, even if the user is tricked into
906: visiting those pages directly, without the protection of the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">If the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
1.1 mike 907: 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>
908: keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
909: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
910: "sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
911: reload itself, effectively breaking out of the sandbox
1.46 mike 912: altogether.</p><hr><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
1.1 mike 913: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
914: indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
915: context</a> is to be rendered in a manner that makes it appear to
916: be part of the containing document (seamlessly included in the
917: parent document). <span class="impl">Specifically, when the
918: attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
919: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
920: the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
921: <code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
922: <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
923: <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
924: document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
925: document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
926: address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
1.33 mike 927: <code><a href="#the-iframe-element">iframe</a></code> element's document, or the <a href="browsers.html#browsing-context">browsing
928: context</a>'s <a href="browsers.html#active-document">active document</a> is <a href="#an-iframe-srcdoc-document">an
929: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
930: document</a>, the following requirements apply:</span></p><div class="impl">
1.1 mike 931:
1.13 mike 932: <ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
933: flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
934: will <a href="history.html#seamlessLinks">cause links to open in the parent
935: browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
936: override</a> is used (<code title="">target="_self"</code>).</p></li>
1.1 mike 937:
938: <li><p>In a CSS-supporting user agent: the user agent must add all
939: the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
940: the cascade of the <a href="browsers.html#active-document">active document</a> of the
941: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
942: at the appropriate cascade levels, before any style sheets
943: specified by the document itself.</p></li>
944:
945: <li><p>In a CSS-supporting user agent: the user agent must, for the
946: purpose of CSS property inheritance only, treat the root element of
947: the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
948: element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
949: the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
950: root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
951: inherit the computed values of those properties on the
952: <code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
953: values.)</p></li>
954:
955: <li><p>In visual media, in a CSS-supporting user agent: the user agent
956: should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
957: width that the element would have if it was a non-replaced
958: block-level element with 'width: auto'.</p></li>
959:
960: <li><p>In visual media, in a CSS-supporting user agent: the user
961: agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
962: the height of the bounding box around the content rendered in the
963: <code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
964: bullet point), as it would be if the scrolling position was such
965: that the top of the viewport for the content rendered in the
966: <code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
967: canvas.</p></li>
968:
969: <li>
970:
971: <p>In visual media, in a CSS-supporting user agent: the user agent
972: must force the height of the initial containing block of the
973: <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
974: context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
975:
976: <p class="note">This is intended to get around the otherwise
977: circular dependency of percentage dimensions that depend on the
978: height of the containing block, thus affecting the height of the
979: document's bounding box, thus affecting the height of the
980: viewport, thus affecting the size of the initial containing
981: block.</p>
982:
983: </li>
984:
985: <li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
986: browsing context</a> without announcing that it is a separate
987: document.</p></li>
988:
989: <li>
990:
991: <p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
992: document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
993: context</a> was part of the document that the
1.35 mike 994: <code><a href="#the-iframe-element">iframe</a></code> is in, if any.</p>
1.1 mike 995:
996: <p class="example">For example if the user agent supports listing
997: all the links in a document, links in "seamlessly" nested
998: documents would be included in that list without being
999: significantly distinguished from links in the document itself.</p>
1000:
1001: </li>
1002:
1003: </ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
1004: conditions listed above are not met, then the user agent should
1005: render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
1006: clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
1007: and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
1008: false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
1009:
1010: <p class="warning">It is important that user agents recheck the
1011: above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
1012: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
1013: changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
1014: 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>
1015:
1016: </div><p class="note">The attribute can be set or removed dynamically,
1017: with the rendering updating in tandem.</p><div class="example">
1018:
1019: <p>In this example, the site's navigation is embedded using a
1020: client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
1021: <code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
1022: opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
1023: legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
1024: element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
1025: attribute with the value <code title="">_parent</code>. Similarly,
1026: in new user agents the styles of the parent page will be
1027: automatically applied to the contents of the frame, but to support
1028: legacy user agents authors might wish to include the styles
1029: explicitly.</p>
1030:
1031: <pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
1032:
1033: </div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1034: attributes</a> for cases where the embedded content has specific
1035: 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
1036: content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
1037: context</a>, regardless of whether the specified initial contents
1038: are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
1039: nothing. (In legacy user agents that do not support
1040: <code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
1.82 mike 1041: 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 1042: documents</a>, the allowed content model of <code><a href="#the-iframe-element">iframe</a></code>
1.101 mike 1043: elements is text, except that invoking the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment
1.18 mike 1044: parsing algorithm</a> with the <code><a href="#the-iframe-element">iframe</a></code> element as the
1.101 mike 1045: <var title="concept-frag-parse-context"><a href="the-end.html#concept-frag-parse-context">context</a></var> element and
1.48 mike 1046: the text contents as the <var title="">input</var> must result in a
1047: list of nodes that are all <a href="content-models.html#phrasing-content">phrasing content</a>, with no
1.101 mike 1048: <a href="parsing.html#parse-error" title="parse error">parse errors</a> having occurred, with
1.48 mike 1049: no <code><a href="scripting-1.html#the-script-element">script</a></code> elements being anywhere in the list or as
1.18 mike 1050: descendants of elements in the list, and with all the elements in
1051: the list (including their descendants) being themselves
1.82 mike 1052: conforming.</p><p>The <code><a href="#the-iframe-element">iframe</a></code> element must be empty in <a href="infrastructure.html#xml-documents">XML
1.101 mike 1053: documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
1.1 mike 1054: <code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
1055:
1056: <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
1057: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1058: name.</p>
1059:
1060: <p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
1061: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1062: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
1063: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1064:
1065: <p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
1066: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1067: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
1068: context</a>.</p>
1069:
1070: </div><div class="example">
1071:
1072: <p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
1073: include advertising from an advertising broker:</p>
1074:
1075: <pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
1076: width="468" height="60"></iframe></pre>
1077:
1.46 mike 1078: </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 1079: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1080: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1081: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1082: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 1083: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.16 mike 1084: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1085: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1086: <dt>Content model:</dt>
1087: <dd>Empty.</dd>
1088: <dt>Content attributes:</dt>
1089: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1090: <dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
1091: <dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
1092: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1093: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1094: <dd>Any other attribute that has no namespace (see prose).</dd>
1095: <dt>DOM interface:</dt>
1096: <dd>
1097: <pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1098: attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
1099: attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
1100: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1101: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1102: };</pre>
1103: <div class="impl">
1104: <p>Depending on the type of content instantiated by the
1105: <code><a href="#the-embed-element">embed</a></code> element, the node may also support other
1106: interfaces.</p>
1107: </div>
1108: </dd>
1.101 mike 1109: </dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
1.1 mike 1110: integration point for an external (typically non-HTML) application
1111: or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
1112: gives the address of the resource being embedded. The attribute, if
1113: present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
1114: surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
1115: attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
1116: plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
1117: 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
1118: <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
1119: same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
1120: 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">
1121:
1122: <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
1123: are removed such that neither attribute is present on the element
1.47 mike 1124: anymore, and when the element has a <a href="#media-element">media element</a>
1.1 mike 1125: ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
1126: element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
1127: content</a>, any plugins instantiated for the element must be
1128: removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
1129:
1130: <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
1131: following conditions are all met simultaneously:</p>
1132:
1133: <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>
1134: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
1135: <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>
1136: <li>The element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute is either absent or its value is the empty string.</li>
1.47 mike 1137: <li>The element is not a descendant of a <a href="#media-element">media element</a>.</li>
1.1 mike 1138: <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>
1139: </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
1140: a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1141: <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
1142: removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1143: <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
1144: removed, the appropriate set of steps from the following is then
1145: applied:</p>
1146:
1147: <dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1148: attribute set</dt>
1149:
1150: <dd>
1151:
1152: <p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
1153: the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1154: attribute, relative to the element. If that is successful, the
1155: user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
1156: URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
1.46 mike 1157: origin</a> if it has one. The <a href="webappapis.html#concept-task" title="concept-task">task</a> that is
1.1 mike 1158: <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking
1159: task source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
1160: 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
1161: <a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
1.46 mike 1162: previously instantiated plugin for the element.</p>
1.101 mike 1163: <p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
1.1 mike 1164: the element's document.</p>
1.46 mike 1165:
1166:
1.1 mike 1167: </dd>
1168:
1169: <dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1170: attribute set</dt>
1171:
1172: <dd><p>The user agent should find and instantiate an appropriate
1173: <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>
1174:
1175: </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
1176: <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
1177: <a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
1178: be unloaded.</p>
1179:
1.114 mike 1180: <p id="sandboxPluginEmbed">When a <a href="infrastructure.html#plugin">plugin</a> is to be
1.127 mike 1181: instantiated but it cannot be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a> and the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed
1182: plugins browsing context flag</a> was set on the <a href="browsers.html#browsing-context">browsing
1183: context</a> for which the <code><a href="#the-embed-element">embed</a></code> element's
1184: <code><a href="infrastructure.html#document">Document</a></code> is the <a href="browsers.html#active-document">active document</a> when that
1185: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent must not
1186: instantiate the <a href="infrastructure.html#plugin">plugin</a>, and must instead render the
1187: <code><a href="#the-embed-element">embed</a></code> element in a manner that conveys that the
1188: <a href="infrastructure.html#plugin">plugin</a> was disabled. The user agent may offer the user
1189: the option to override the sandbox and instantiate the
1190: <a href="infrastructure.html#plugin">plugin</a> anyway; if the user invokes such an option, the
1191: user agent must act as if the conditions above did not apply for the
1192: purposes of this element.</p>
1.114 mike 1193:
1194: <p class="warning">Plugins that cannot be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a> are disabled in
1195: sandboxed browsing contexts because they might not honor the
1196: restrictions imposed by the sandbox (e.g. they might allow scripting
1197: even when scripting in the sandbox is disabled). User agents should
1198: convey the danger of overriding the sandbox to the user if an option
1199: to do so is provided.</p>
1200:
1.1 mike 1201: <p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
1202: CSS 'display' property. The selected plugin is instantiated even if
1203: the element is hidden with a 'display:none' CSS style.</p>
1204:
1205: <p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
1206: being embedded is defined as follows:</p>
1207:
1208: <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
1209: value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
1210: of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
1211: <a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
1212:
1213: <li>
1214:
1.46 mike 1215:
1.1 mike 1216: <p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
1217: component of the <a href="urls.html#url">URL</a> of the specified resource (after
1218: any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1219: supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
1220: type</a> is the type that that plugin can handle.</p>
1221:
1222: <p class="example">For example, a plugin might say that it can
1223: handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
1224: components that end with the four character string "<code title="">.swf</code>".</p>
1225:
1.46 mike 1226:
1227:
1.1 mike 1228:
1229: </li>
1230:
1231: <li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
1232: that is the <a href="#concept-embed-type" title="concept-embed-type">content's
1233: type</a>.</p></li>
1234:
1235: <li><p>Otherwise, the content has no type and there can be no
1236: appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
1237:
1.46 mike 1238:
1.1 mike 1239:
1240: </ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
1241: content</a>. If the user agent can't find a suitable plugin, then
1242: the user agent must use a default plugin. (This default could be as
1243: simple as saying "Unsupported Format".)</p>
1244:
1245: <p>Whether the resource is fetched successfully or not (e.g. whether
1246: 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
1247: ignored when determining the resource's type and when handing the
1248: resource to the plugin.</p>
1249:
1250: <p class="note">This allows servers to return data for plugins even
1251: with error responses (e.g. HTTP 500 Internal Server Error codes can
1252: still contain plugin data).</p>
1253:
1.101 mike 1254: </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 1255: so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
1256: characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
1257: LATIN CAPITAL LETTER Z). These attributes are then passed as
1.82 mike 1258: 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 1259: lowercased automatically, so the restriction on uppercase letters
1260: doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
1261: that have side-effects beyond just sending parameters to the
1262: <a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
1263:
1264: <p>The user agent should pass the names and values of all the
1265: attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
1266: to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
1267:
1268: <p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
1269: <code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
1270: <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
1271: expose that interface while the element is instantiated.</p>
1272:
1273: </div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1274: attributes</a>.</p><div class="impl">
1275:
1276: <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
1277: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1278: name.</p>
1279:
1280: </div><div class="example">
1281:
1282: <p>Here's a way to embed a resource that requires a proprietary
1.69 mike 1283: plugin, like Flash:</p>
1.1 mike 1284:
1285: <pre><embed src="catgame.swf"></pre>
1286:
1.69 mike 1287: <p>If the user does not have the plugin (for example if the
1288: plugin vendor doesn't support the user's platform), then the user
1.1 mike 1289: will be unable to use the resource.</p>
1290:
1291: <p>To pass the plugin a parameter "quality" with the value "high",
1292: an attribute can be specified:</p>
1293:
1294: <pre><embed src="catgame.swf" quality="high"></pre>
1295:
1296: <p>This would be equivalent to the following, when using an
1297: <code><a href="#the-object-element">object</a></code> element instead:</p>
1298:
1299: <pre><object data="catgame.swf">
1300: <param name="quality" value="high">
1301: </object></pre>
1302:
1.15 mike 1303: </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 1304: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1305: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1306: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1.46 mike 1307: <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 1308: <dd><a href="forms.html#category-listed" title="category-listed">Listed</a>, <a href="forms.html#category-submit" title="category-submit">submittable</a>, <a href="forms.html#form-associated-element">form-associated element</a>.</dd>
1.126 mike 1309: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.16 mike 1310: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1311: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1312: <dt>Content model:</dt>
1313: <dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
1314: <dt>Content attributes:</dt>
1315: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1316: <dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
1317: <dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
1.69 mike 1318: <dd><code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code></dd>
1.1 mike 1319: <dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
1320: <dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
1321: <dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
1322: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1323: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1324: <dt>DOM interface:</dt>
1325: <dd>
1326: <pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1327: attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
1328: attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
1.69 mike 1329: attribute boolean <a href="#dom-object-typemustmatch" title="dom-object-typeMustMatch">typeMustMatch</a>;
1.1 mike 1330: attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
1331: attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
1.68 mike 1332: 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 1333: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1334: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1.68 mike 1335: readonly attribute Document? <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
1336: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a>? <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
1.1 mike 1337:
1338: readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
1339: 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>;
1340: readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
1341: boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
1.101 mike 1342: void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(DOMString error);
1.1 mike 1343: };</pre>
1344: <div class="impl">
1345: <p>Depending on the type of content instantiated by the
1346: <code><a href="#the-object-element">object</a></code> element, the node also supports other
1347: interfaces.</p>
1348: </div>
1349: </dd>
1350: </dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
1351: resource, which, depending on the type of the resource, will either
1352: be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1353: or as an external resource to be processed by a
1354: <a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
1355: attribute, if present, specifies the address of the resource. If
1356: present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.69 mike 1357: 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
1358: use the <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1359: attribute defined below. Without that attribute, it is possible in
1360: certain cases for an attacker on the remote host to use the plugin
1361: mechanism to run arbitrary scripts, even if the author has used
1362: 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 1363: attribute, if present, specifies the type of the resource. If
1.69 mike 1364: 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 1365: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> whose presence
1.69 mike 1366: 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
1367: the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1368: attribute and the <a href="fetching-resources.html#content-type">Content-Type</a> of the aforementioned
1369: resource match.</p><p>The <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code>
1370: 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 1371: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
1372: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
1373: browsing context</a>, if applicable.</p><div class="impl">
1374:
1375: <p>When the element is created, when it is popped off the
1.101 mike 1376: <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
1377: or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
1.1 mike 1378: <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
1379: document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
1380: document">removed from a document</a>; and whenever the element's
1381: <code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
1382: active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
1383: changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
1.101 mike 1384: whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
1385: changed, or removed; and, when its <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is not present,
1.1 mike 1386: whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
1.101 mike 1387: set, changed, or removed; and, when neither its <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute nor its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute are present, whenever
1.1 mike 1388: its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
1389: changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
1390: to run the following steps to (re)determine what the
1391: <code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
1392: 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 1393: manipulation task source</a>.</p>
1.1 mike 1394: <ol><li>
1395:
1396: <p>If the user has indicated a preference that this
1397: <code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
1398: shown instead of the element's usual behavior, then jump to the
1399: last step in the overall set of steps (fallback).</p>
1400:
1401: <p class="note">For example, a user could ask for the element's
1402: <a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
1403: uses a format that the user finds more accessible.</p>
1404:
1405: </li>
1406:
1407: <li>
1408:
1.47 mike 1409: <p>If the element has an ancestor <a href="#media-element">media element</a>, or
1.1 mike 1410: has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
1411: showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
1412: not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
1413: with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
1414: <code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
1.101 mike 1415: element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
1416: <a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
1.1 mike 1417: the last step in the overall set of steps (fallback).</p>
1418:
1419: </li>
1420:
1421: <li>
1422:
1.46 mike 1423:
1.101 mike 1424: <p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
1.1 mike 1425: attribute is present, and has a value that isn't the empty string,
1426: then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
1.114 mike 1427: according to the value of the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute, and either
1428: <a href="#sandboxPluginObject">plugins aren't being sandboxed</a>
1429: or that <a href="infrastructure.html#plugin">plugin</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>, then that
1430: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>,
1431: and the value of the <code title="attr-object-data"><a href="#attr-object-data">data</a></code>
1432: attribute, if any, should be passed to the <a href="infrastructure.html#plugin">plugin</a>. If
1433: no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
1434: <a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the last step in the
1435: overall set of steps (fallback).</p>
1.1 mike 1436:
1.46 mike 1437:
1.1 mike 1438: </li>
1439:
1.46 mike 1440:
1.1 mike 1441: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1442: is present and its value is not the empty string, then:</p>
1443:
1444: <ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1445: attribute is present and its value is not a type that the user
1446: agent supports, and is not a type that the user agent can find a
1447: <a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
1448: step in the overall set of steps (fallback) without fetching the
1449: content to examine its real type.</p></li>
1450:
1451: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
1452: <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
1453: element.</p></li>
1454:
1455: <li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1456: <code title="event-error">error</code> at the element, then jump
1457: to the last step in the overall set of steps (fallback).</p></li>
1458:
1459: <li>
1460:
1461: <p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
1462: from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
1.46 mike 1463: it has one.</p>
1.1 mike 1464:
1.46 mike 1465: <p>Fetching the resource
1.101 mike 1466: must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
1.1 mike 1467: 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
1468: source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
1469:
1.41 mike 1470: <p>For the purposes of the <a href="offline.html#application-cache">application cache</a>
1471: networking model, this <a href="fetching-resources.html#fetch">fetch</a> operation is not for a
1472: <a href="browsers.html#child-browsing-context">child browsing context</a> (though it might end up
1473: being used for one after all, as defined below).</p>
1474:
1.1 mike 1475: </li>
1476:
1477: <li><p>If the resource is not yet available (e.g. because the
1478: resource was not available in the cache, so that loading the
1479: resource required making a request over the network), then jump
1480: to the last step in the overall set of steps (fallback). The
1481: <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue
1482: a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task source</a>
1483: once the resource is available must restart this algorithm from
1484: this step. Resources can load incrementally; user agents may opt
1485: to consider a resource "available" whenever enough data has been
1486: obtained to begin processing the resource.</p></li>
1487:
1488: <li><p>If the load failed (e.g. there was an HTTP 404 error,
1489: there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1490: <code title="event-error">error</code> at the element, then jump
1491: to the last step in the overall set of steps (fallback).</p></li>
1492:
1493: <li id="object-type-detection">
1494:
1495: <p>Determine the <var title="">resource type</var>, as follows:</p>
1496:
1497:
1498: <ol><li>
1499:
1500: <p>Let the <var title="">resource type</var> be unknown.</p>
1501:
1502: </li>
1503:
1504: <li>
1505:
1.69 mike 1506: <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>
1507: attribute, and the resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type metadata</a>,
1508: and the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1509: resource's Content-Type metadata</a> is an <a href="infrastructure.html#ascii-case-insensitive">ASCII
1510: case-insensitive</a> match for the value of the element's
1511: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, then let
1512: <var title="">resource type</var> be that type and jump to the
1513: step below labeled <i>handler</i>.</p>
1514:
1515:
1516: </li>
1517:
1518: <li>
1519:
1520: <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>
1521: attribute, jump to the step below labeled <i>handler</i>.</p>
1522:
1523: </li>
1524:
1525: <li>
1526:
1.46 mike 1527:
1.1 mike 1528:
1529: <p>If the user agent is configured to strictly obey
1530: Content-Type headers for this resource, and the resource has
1531: <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1532: metadata</a>, then let the <var title="">resource
1533: type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1534: metadata</a>, and jump to the step below labeled
1535: <i>handler</i>.</p>
1536:
1.69 mike 1537: <p class="warning">This can introduce a vulnerability, wherein
1538: a site is trying to embed a resource that uses a particular
1539: plugin, but the remote site overrides that and instead
1540: furnishes the user agent with a resource that triggers a
1541: different plugin with different security characteristics. </p>
1542:
1.1 mike 1543: </li>
1544:
1545: <li>
1546:
1547: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1548: attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
1549: attribute's value is not a type that the user agent supports,
1550: but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
1551: then let the <var title="">resource type</var> be the type
1552: specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1553: attribute, and jump to the step below labeled
1554: <i>handler</i>.</p>
1555:
1556: </li>
1557:
1558: <li>
1559:
1560: <p>Run the approprate set of steps from the following
1561: list:</p>
1562:
1563: <dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
1564: Content-Type metadata</a></dt>
1565:
1566: <dd>
1567:
1568: <ol><li>
1569:
1570: <p>Let <var title="">binary</var> be false.</p>
1571:
1572: </li>
1573:
1574: <li>
1575:
1576: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1577: resource's Content-Type metadata</a> is
1578: "<code>text/plain</code>", and the result of applying the
1579: <a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
1.49 mike 1580: for distinguishing if a resource is text or binary</a>
1.1 mike 1581: to the resource is that the resource is not
1582: <code>text/plain</code>, then set <var title="">binary</var> to true.</p>
1583:
1584: </li>
1585:
1586: <li>
1587:
1588: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1589: resource's Content-Type metadata</a> is
1590: "<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
1591:
1592: </li>
1593:
1594: <li>
1595:
1596: <p>If <var title="">binary</var> is false, then let the
1597: <var title="">resource type</var> be the type specified in
1598: <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1599: metadata</a>, and jump to the step below labeled
1600: <i>handler</i>.</p>
1601:
1602: </li>
1603:
1604: <li>
1605:
1606: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1607: the <code><a href="#the-object-element">object</a></code> element, and its value is not
1608: <code>application/octet-stream</code>, then run the
1609: following steps:</p>
1610:
1611: <ol><li>
1612:
1613: <p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
1614: 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>,
1615: 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>
1616:
1617: </li>
1618:
1619: <li>
1620:
1621: <p>Jump to the step below labeled <i>handler</i>.</p>
1622:
1623: </li>
1624:
1625: </ol></li>
1626:
1627: </ol></dd>
1628:
1629: <dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1630: metadata</a></dt>
1631:
1632: <dd>
1633:
1634: <ol><li>
1635:
1636: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1637: 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
1638: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1639:
1640: <p>Otherwise, let <var title="">tentative type</var> be the
1641: <a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
1642: resource</a>.</p>
1643:
1644: </li>
1645:
1646: <li>
1647:
1648: <p>If <var title="">tentative type</var> is <em>not</em>
1649: <code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
1650: type</var> and jump to the step below labeled
1651: <i>handler</i>.</p>
1652:
1653: </li>
1654:
1655: </ol></dd>
1656:
1657: </dl></li>
1658:
1659: <li>
1660:
1.46 mike 1661:
1.1 mike 1662: <p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
1663: of the <a href="urls.html#url">URL</a> of the specified resource (after any
1664: redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1665: supports, then let <var title="">resource type</var> be the
1666: type that that plugin can handle.</p>
1667:
1668: <p class="example">For example, a plugin might say that it can
1669: handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
1670: the four character string "<code title="">.swf</code>".</p>
1671:
1.46 mike 1672:
1673:
1.1 mike 1674:
1675: </li>
1676:
1.69 mike 1677: </ol><p class="note">It is possible for this step to finish, or for
1678: one of the substeps above to jump straight to the next step,
1679: with <var title="">resource type</var> still being unknown. In
1680: both cases, the next step will trigger fallback.</p>
1.1 mike 1681:
1682: </li>
1683:
1684: <li><p><i>Handler</i>: Handle the content as given by the first
1685: of the following cases that matches:</p>
1686:
1687: <dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
1688: the user agent supports, but it <em>is</em> a type that a
1689: <a href="infrastructure.html#plugin">plugin</a> supports</dt>
1690:
1691: <dd>
1692:
1693: <p>If <a href="#sandboxPluginObject">plugins are being
1.114 mike 1694: sandboxed</a> and the plugin that supports <var title="">resource type</var> cannot be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>, jump to the last
1695: step in the overall set of steps (fallback).</p>
1.1 mike 1696:
1697: <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
1698: resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
1699: <a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
1700: step in the overall set of steps (fallback).</p>
1701:
1702: </dd>
1703:
1704:
1705: <dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
1706: type</a>, or
1.46 mike 1707:
1.1 mike 1708: if the <var title="">resource type</var> does not start with
1709: "<code>image/</code>"</dt>
1710:
1711: <dd>
1712:
1713: <p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
1714: newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
1715: not already have one.</p>
1716:
1717: <p>If the <a href="urls.html#url">URL</a> of the given resource is not
1718: <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 1719: context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that
1.34 mike 1720: resource, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
1.1 mike 1721: <code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
1.34 mike 1722: context</a> as the <a href="history.html#source-browsing-context">source browsing context</a>.
1723: (The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of
1724: the <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
1.1 mike 1725: browsing context gets further navigated to other
1726: locations.)</p>
1727:
1728: <p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
1729: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, the user agent must
1730: <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>
1731: named <code title="event-load">load</code> at the
1.66 mike 1732: <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
1733: <code><a href="fetching-resources.html#about:blank">about:blank</a></code> document itself.</span></p>
1.1 mike 1734:
1.101 mike 1735: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1.1 mike 1736: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1737:
1738: <p>If the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1739: is present, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1740: to the value of this attribute; otherwise, the <a href="browsers.html#browsing-context-name">browsing
1741: context name</a> must be set to the empty string.</p>
1742:
1.41 mike 1743: <p class="note">In certain situations, e.g. if the resource
1744: was <a href="fetching-resources.html#fetch" title="fetch">fetched</a> from an
1745: <a href="offline.html#application-cache">application cache</a> but it is an HTML file with a
1746: <code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> attribute
1747: that points to a different <a href="offline.html#concept-appcache-manifest" title="concept-appcache-manifest">application cache
1748: manifest</a>, the <a href="history.html#navigate" title="navigate">navigation</a>
1749: of the <a href="browsers.html#browsing-context">browsing context</a> will be restarted so as
1750: to load the resource afresh from the network or a different
1751: <a href="offline.html#application-cache">application cache</a>. Even if the resource is then
1752: found to have a different type, it is still used as part of a
1753: <a href="browsers.html#nested-browsing-context">nested browsing context</a>: only the
1754: <a href="history.html#navigate">navigate</a> algorithm is restarted, not this
1755: <code><a href="#the-object-element">object</a></code> algorithm.</p>
1.1 mike 1756:
1.46 mike 1757:
1.1 mike 1758:
1759: </dd>
1760:
1761:
1762: <dt>If the <var title="">resource type</var> starts with
1763: "<code>image/</code>", and support for images has not been
1764: disabled</dt>
1765:
1766: <dd>
1767:
1768: <p>Apply the <a href="fetching-resources.html#content-type-sniffing:-image" title="content-type sniffing: image">image
1769: sniffing</a> rules to determine the type of the image.</p>
1770:
1.101 mike 1771: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1.1 mike 1772: specified image. The image is not a <a href="browsers.html#nested-browsing-context">nested browsing
1773: context</a>.</p>
1774:
1775: <p>If the image cannot be rendered, e.g. because it is
1776: malformed or in an unsupported format, jump to the last step
1777: in the overall set of steps (fallback).</p>
1778:
1779: </dd>
1780:
1781:
1782: <dt>Otherwise</dt>
1783:
1784: <dd>
1785:
1786: <p>The given <var title="">resource type</var> is not
1787: supported. Jump to the last step in the overall set of steps
1788: (fallback).</p>
1789:
1790: <p class="note">If the previous step ended with the <var title="">resource type</var> being unknown, this is the case
1791: that is triggered.</p>
1792:
1793: </dd>
1794:
1795: </dl></li>
1796:
1797: <li><p>The element's contents are not part of what the
1798: <code><a href="#the-object-element">object</a></code> element represents.</p>
1799:
1800: </li><li>
1801:
1802: <p>Once the resource is completely loaded, <a href="webappapis.html#queue-a-task">queue a
1803: 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>
1804:
1.46 mike 1805: <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 1806: source</a>.</p>
1807:
1808: </li>
1809:
1810: </ol></li>
1811:
1812: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1813: is absent but the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1.114 mike 1814: attribute is present, and the user agent can find a
1815: <a href="infrastructure.html#plugin">plugin</a> suitable according to the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, and either <a href="#sandboxPluginObject">plugins aren't being sandboxed</a> or
1816: the <a href="infrastructure.html#plugin">plugin</a> can be <a href="infrastructure.html#concept-plugin-secure" title="concept-plugin-secure">secured</a>, then that
1.1 mike 1817: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
1.114 mike 1818: these conditions cannot be met, or if the <a href="infrastructure.html#plugin">plugin</a>
1819: reports an error, jump to the next step (fallback).</p></li>
1.1 mike 1820:
1821: <li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
1.101 mike 1822: <a href="rendering.html#represents">represents</a> the element's children, ignoring any
1.1 mike 1823: leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
1824: <a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
1825: <a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
1826:
1827: </ol><p id="object-plugin">When the algorithm above instantiates a
1828: <a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
1829: <a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
1830: on the element, in the order they were added to the element, with
1831: the attributes added by the parser being ordered in source order,
1832: followed by a parameter named "PARAM" whose value is null,
1833: followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
1834: <code><a href="#the-param-element">param</a></code> elements that are children of the
1835: <code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
1836: <a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
1837: <code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
1838: should expose that interface. The <code><a href="#the-object-element">object</a></code> element
1.101 mike 1839: <a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
1.1 mike 1840: <a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
1841: context</a>.</p>
1842:
1.114 mike 1843: <p id="sandboxPluginObject">Plugins are considered sandboxed for the
1.127 mike 1844: purpose of an <code><a href="#the-object-element">object</a></code> element if the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed
1845: plugins browsing context flag</a> was set on the
1846: <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing
1847: context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
1.1 mike 1848:
1.127 mike 1849: <p class="note">The above algorithm is independent of CSS properties
1.1 mike 1850: (including 'display', 'overflow', and 'visibility'). For example, it
1851: runs even if the element is hidden with a 'display:none' CSS style,
1852: and does not run <em>again</em> if the element's visibility
1853: changes.</p>
1854:
1855: <p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
1856: elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
1857: referenced resources can't be shown (e.g. because it returned a 404
1858: error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
1859: nested inside each other, targeting multiple user agents with
1860: different capabilities, with the user agent picking the first one it
1861: supports.</p>
1862:
1863: <p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1864: is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
1865: <a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
1866: name">name</a> must be changed to the new value. If the attribute
1867: is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
1868: context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1869: to the empty string.</p>
1870:
1871: </div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
1872: if present while the <code><a href="#the-object-element">object</a></code> element represents an
1873: image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
1874: map</a>. <span class="impl">The attribute must be ignored if the
1875: <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
1876: explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
1877: <a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
1878:
1879: <p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
1880: elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
1881: validation</a>.</p>
1882:
1883: </div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1884: attributes</a>.</p><div class="impl">
1885:
1.131 mike 1886: <p>The IDL attributes <dfn id="dom-object-data" title="dom-object-data"><code>data</code></dfn>, <dfn id="dom-object-type" title="dom-object-type"><code>type</code></dfn> and <dfn id="dom-object-name" title="dom-object-name"><code>name</code></dfn> each must
1.1 mike 1887: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1.131 mike 1888: name. The <dfn id="dom-object-typemustmatch" title="dom-object-typeMustMatch"><code>typeMustMatch</code></dfn>
1889: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-object-typemustmatch"><a href="#attr-object-typemustmatch">typemustmatch</a></code> content
1890: attribute. The <dfn id="dom-object-usemap" title="dom-object-useMap"><code>useMap</code></dfn> IDL attribute
1891: must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-object-usemap">usemap</code> content attribute.</p>
1.69 mike 1892:
1.1 mike 1893: <p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
1894: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1895: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
1896: <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
1897: must return null.</p>
1898:
1899: <p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
1900: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1901: <code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1902: if it has one; otherwise, it must return null.</p>
1903:
1904: <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>
1905: 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>
1906: methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
1907: <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
1908: element's forms API.</p>
1909:
1910: </div><div class="example">
1911:
1912: <p>In the following example, a Java applet is embedded in a page
1913: using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
1914: better to avoid using applets like these and instead use native
1915: JavaScript and HTML to provide the functionality, since that way
1916: the application will work on all Web browsers without requiring a
1917: third-party plugin. Many devices, especially embedded devices, do
1918: not support third-party technologies like Java.)</p>
1919:
1920: <pre><figure>
1921: <object type="application/x-java-applet">
1922: <param name="code" value="MyJavaClass">
1923: <p>You do not have Java available, or it is disabled.</p>
1924: </object>
1925: <figcaption>My Java Clock</figcaption>
1926: </figure></pre>
1927:
1928: </div><div class="example">
1929:
1930: <p>In this example, an HTML page is embedded in another using the
1931: <code><a href="#the-object-element">object</a></code> element.</p>
1932:
1933: <pre><figure>
1934: <object data="clock.html"></object>
1935: <figcaption>My HTML Clock</figcaption>
1936: </figure></pre>
1937:
1938: </div><div class="example">
1939:
1940: <p>The following example shows how a plugin can be used in HTML (in
1941: this case the Flash plugin, to show a video file). Fallback is
1942: provided for users who do not have Flash enabled, in this case
1.47 mike 1943: using the <code><a href="#the-video-element">video</a></code> element to show the video for those
1944: using user agents that support <code><a href="#the-video-element">video</a></code>, and finally
1.1 mike 1945: providing a link to the video for those who have neither Flash nor
1.47 mike 1946: a <code><a href="#the-video-element">video</a></code>-capable browser.</p>
1.1 mike 1947:
1948: <pre><p>Look at my video:
1949: <object type="application/x-shockwave-flash">
1950: <param name=movie value="http://video.example.com/library/watch.swf">
1951: <param name=allowfullscreen value=true>
1952: <param name=flashvars value="http://video.example.com/vids/315981">
1953: <video controls src="http://video.example.com/vids/315981">
1954: <a href="http://video.example.com/vids/315981">View video</a>.
1955: </video>
1956: </object>
1957: </p></pre>
1958:
1.15 mike 1959: </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 1960: <dd>None.</dd>
1.16 mike 1961: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1962: <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>
1963: <dt>Content model:</dt>
1964: <dd>Empty.</dd>
1965: <dt>Content attributes:</dt>
1966: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1967: <dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
1968: <dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
1969: <dt>DOM interface:</dt>
1970: <dd>
1971: <pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1972: attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
1973: attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
1974: };</pre>
1975: </dd>
1976: </dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
1.101 mike 1977: invoked by <code><a href="#the-object-element">object</a></code> elements. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-param-name" title="attr-param-name"><code>name</code></dfn>
1.1 mike 1978: attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
1979: attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
1980:
1981: <p>If both attributes are present, and if the parent element of the
1982: <code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
1983: element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
1.94 mike 1984: name-value pair.</p>
1.1 mike 1985:
1.23 mike 1986: <p>If either the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> defined by a
1987: <code><a href="#the-param-element">param</a></code> element that is the child of an
1.101 mike 1988: <code><a href="#the-object-element">object</a></code> element that <a href="rendering.html#represents">represents</a> an
1.23 mike 1989: instantiated <a href="infrastructure.html#plugin">plugin</a> changes, and if that
1990: <a href="infrastructure.html#plugin">plugin</a> is communicating with the user agent using an
1991: API that features the ability to update the <a href="infrastructure.html#plugin">plugin</a> when
1992: the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> so changes, then
1993: the user agent must appropriately exercise that ability to notify
1994: the <a href="infrastructure.html#plugin">plugin</a> of the change.</p>
1995:
1.1 mike 1996: <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
1997: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1998: name.</p>
1999:
2000: </div><div class="example">
2001:
2002: <p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
2003: can be used to pass a parameter to a plugin, in this case the O3D
2004: plugin.</p>
2005:
2006: <pre><!DOCTYPE HTML>
2007: <html lang="en">
1.6 mike 2008: <head>
2009: <title>O3D Utah Teapot</title>
2010: </head>
2011: <body>
2012: <p>
2013: <object type="application/vnd.o3d.auto">
2014: <strong><param name="o3d_features" value="FloatingPointTextures"></strong>
2015: <img src="o3d-teapot.png"
2016: title="3D Utah Teapot illustration rendered using O3D."
2017: alt="When O3D renders the Utah Teapot, it appears as a squat
2018: teapot with a shiny metallic finish on which the
2019: surroundings are reflected, with a faint shadow caused by
2020: the lighting.">
2021: <p>To see the teapot actually rendered by O3D on your
2022: computer, please download and install the <a
2023: href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
2024: </object>
2025: <script src="o3d-teapot.js"></script>
2026: </p>
2027: </body>
1.1 mike 2028: </html></pre>
2029:
1.47 mike 2030: </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>
2031: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2032: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2033: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2034: <dd>If the element has a <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute: <a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 2035: <dd><a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.47 mike 2036: <dt>Contexts in which this element can be used:</dt>
2037: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2038: <dt>Content model:</dt>
2039: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2040: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2041: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2042: <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
2043: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2044: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2045: <dt>Content attributes:</dt>
2046: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2047: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2048: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2049: <dd><code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code></dd>
2050: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2051: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2052: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2053: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2054: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2055: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2056: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
2057: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
2058: <dt>DOM interface:</dt>
2059: <dd>
2060: <pre class="idl">interface <dfn id="htmlvideoelement">HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {
2061: attribute unsigned long <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
2062: attribute unsigned long <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
2063: readonly attribute unsigned long <a href="#dom-video-videowidth" title="dom-video-videoWidth">videoWidth</a>;
2064: readonly attribute unsigned long <a href="#dom-video-videoheight" title="dom-video-videoHeight">videoHeight</a>;
2065: attribute DOMString <a href="#dom-video-poster" title="dom-video-poster">poster</a>;
2066: };</pre>
2067: </dd>
2068: </dl><p>A <code><a href="#the-video-element">video</a></code> element is used for playing videos or
2069: movies, and audio files with captions.</p><p>Content may be provided inside the <code><a href="#the-video-element">video</a></code>
2070: element<span class="impl">. User agents should not show this content
2071: to the user</span>; it is intended for older Web browsers which do
2072: not support <code><a href="#the-video-element">video</a></code>, so that legacy video plugins can be
2073: tried, or to show text to the users of these older browsers informing
2074: them of how to access the video contents.</p><p class="note">In particular, this content is not intended to
2075: address accessibility concerns. To make video content accessible to
2076: the blind, deaf, and those with other physical or cognitive
1.90 mike 2077: disabilities, a variety of features are available. Captions can be
2078: provided, either embedded in the video stream or as external files
2079: using the <code><a href="#the-track-element">track</a></code> element. Sign-language tracks can be
2080: provided, again either embedded in the video stream or by
2081: 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
2082: <code><a href="#mediacontroller">MediaController</a></code> object. Audio descriptions can be
2083: provided, either as a separate track embedded in the video stream,
2084: 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
2085: as the <code><a href="#the-video-element">video</a></code> element(s), or in text form using a
2086: <span>WebVTT file</span> referenced using the <code><a href="#the-track-element">track</a></code>
2087: element and synthesized into speech by the user agent. WebVTT can
2088: also be used to provide chapter titles. For users who would rather
2089: not use a media element at all, transcripts or other textual
2090: alternatives can be provided by simply linking to them in the prose
2091: 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 2092: whose <a href="#media-data">media data</a> is ostensibly video data, possibly
2093: 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>,
2094: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2095: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2096: <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
2097: elements</a>.</p><p>The <dfn id="attr-video-poster" title="attr-video-poster"><code>poster</code></dfn>
2098: attribute gives the address of an image file that the user agent can
2099: show while no video data is available. The attribute, if present,
2100: must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2101: spaces</a>.</p><div class="impl">
2102:
2103: <p>If the specified resource is to be used, then, when the element
2104: is created or when the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
2105: attribute is set, changed, or removed, the user agent must run the
2106: following steps to determine the element's <dfn id="poster-frame">poster
2107: frame</dfn>:</p>
2108: <ol><li><p>If there is an existing instance of this algorithm running
2109: for this <code><a href="#the-video-element">video</a></code> element, abort that instance of this
2110: algorithm without changing the <a href="#poster-frame">poster frame</a>.</p></li>
2111:
2112: <li><p>If the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
1.51 mike 2113: attribute's value is the empty string or if the attribute is
2114: absent, then there is no <a href="#poster-frame">poster frame</a>; abort these
2115: steps.</p></li>
1.47 mike 2116:
2117: <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
2118: to the element. If this fails, then there is no <a href="#poster-frame">poster
2119: frame</a>; abort these steps.</p></li>
2120:
2121: <li><p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
2122: from the element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>.
1.101 mike 2123: This must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's
1.47 mike 2124: document.</p></li>
2125:
2126:
2127:
2128: <li><p>If an image is thus obtained, the <a href="#poster-frame">poster frame</a>
2129: is that image. Otherwise, there is no <a href="#poster-frame">poster
2130: frame</a>.</p></li>
2131:
2132: </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
2133: frame</a></i>, is intended to be a representative frame of the video
2134: (typically one of the first non-blank frames) that gives the user an
2135: idea of what the video is like.</p><div class="impl">
2136:
2137: <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
2138: <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
2139: 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
2140: subsequent value but the <a href="#media-resource">media resource</a> does not have a
2141: video channel), the <code><a href="#the-video-element">video</a></code> element
1.101 mike 2142: <a href="rendering.html#represents">represents</a> the <a href="#poster-frame">poster frame</a>.</p>
1.47 mike 2143:
2144: <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
2145: playback position">current playback position</a> is the first
1.101 mike 2146: frame of video, the element <a href="rendering.html#represents">represents</a> the <a href="#poster-frame">poster
1.94 mike 2147: frame</a>, unless a frame of video has already been shown, in
1.101 mike 2148: which case the element <a href="rendering.html#represents">represents</a> the frame of video
1.94 mike 2149: corresponding to the <a href="#current-playback-position" title="current playback position">current
2150: playback position</a>.</p>
1.47 mike 2151:
2152: <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
2153: the <a href="#media-resource">media resource</a> has a video channel, the element
1.101 mike 2154: <a href="rendering.html#represents">represents</a> the frame of video corresponding to the
1.47 mike 2155: <a href="#current-playback-position" title="current playback position">current playback
2156: position</a>, or, if that is not yet available (e.g. because the
2157: video is seeking or buffering), the last frame of the video to have
2158: been rendered.</p>
2159:
2160: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2161: resource</a> has a video channel is <a href="#potentially-playing">potentially
1.101 mike 2162: playing</a>, it <a href="rendering.html#represents">represents</a> the frame of video at the
1.47 mike 2163: continuously increasing <a href="#current-playback-position" title="current playback
2164: position">"current" position</a>. When the <a href="#current-playback-position">current playback
2165: position</a> changes such that the last frame rendered is no
2166: longer the frame corresponding to the <a href="#current-playback-position">current playback
2167: position</a> in the video, the new frame must be rendered.
2168:
2169: Similarly, any audio associated with the <a href="#media-resource">media resource</a>
2170: must, if played, be played synchronized with the <a href="#current-playback-position">current
2171: playback position</a>, at the element's <a href="#effective-media-volume">effective media
2172: volume</a>.</p>
2173:
2174: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2175: resource</a> has a video channel is neither <a href="#potentially-playing">potentially
2176: playing</a> nor <a href="#dom-media-paused" title="dom-media-paused">paused</a>
1.101 mike 2177: (e.g. when seeking or stalled), the element <a href="rendering.html#represents">represents</a>
1.47 mike 2178: the last frame of the video to have been rendered.</p>
2179:
2180: <p class="note">Which frame in a video stream corresponds to a
2181: particular playback position is defined by the video stream's
2182: format.</p>
2183:
1.101 mike 2184: <p>The <code><a href="#the-video-element">video</a></code> element also <a href="rendering.html#represents">represents</a> any
1.47 mike 2185: <a href="#text-track-cue" title="text track cue">text track cues</a> whose
2186: <a href="#text-track-cue-active-flag">text track cue active flag</a> is set and whose
2187: <a href="#text-track">text track</a> is in the <a href="#text-track-showing" title="text track
2188: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track showing by
2189: default">showing by default</a> modes.</p>
2190:
2191: <p>In addition to the above, the user agent may provide messages to
2192: the user (such as "buffering", "no video loaded", "error", or more
2193: detailed information) by overlaying text or icons on the video or
2194: other areas of the element's playback area, or in another
2195: appropriate manner.</p>
2196:
2197: <p>User agents that cannot render the video may instead make the
1.101 mike 2198: element <a href="rendering.html#represents" title="represents">represent</a> a link to an
1.47 mike 2199: external video playback utility or to the video data itself.</p>
2200:
1.105 mike 2201: <p>When a <code><a href="#the-video-element">video</a></code> element's <a href="#media-resource">media resource</a>
2202: has a video channel, the element <a href="infrastructure.html#provides-a-paint-source">provides a paint
2203: source</a> whose width is the <a href="#media-resource">media resource</a>'s <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a>, whose
2204: height is the <a href="#media-resource">media resource</a>'s <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a>, and
2205: whose appearance is the frame of video corresponding to the <a href="#current-playback-position" title="current playback position">current playback position</a>,
2206: if that is available, or else (e.g. when the video is seeking or
2207: buffering) its previous appearance, if any, or else (e.g. because
2208: the video is still loading the first frame) blackness.</p>
2209:
1.47 mike 2210: <hr></div><dl class="domintro"><dt><var title="">video</var> . <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code></dt>
2211: <dt><var title="">video</var> . <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code></dt>
2212:
2213: <dd>
2214:
2215: <p>These attributes return the intrinsic dimensions of the video,
2216: or zero if the dimensions are not known.</p>
2217:
2218: </dd>
2219:
2220: </dl><div class="impl">
2221:
2222: <p>The <dfn id="concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2223: width</dfn> and <dfn id="concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</dfn> of the
2224: <a href="#media-resource">media resource</a> are the dimensions of the resource in
2225: CSS pixels after taking into account the resource's dimensions,
2226: aspect ratio, clean aperture, resolution, and so forth, as defined
2227: for the format used by the resource. If an anamorphic format does
2228: not define how to apply the aspect ratio to the video data's
2229: dimensions to obtain the "correct" dimensions, then the user agent
2230: must apply the ratio by increasing one dimension and leaving the
2231: other unchanged.</p>
2232:
2233: <p>The <dfn id="dom-video-videowidth" title="dom-video-videoWidth"><code>videoWidth</code></dfn> IDL
2234: attribute must return the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> of the
2235: video in CSS pixels. The <dfn id="dom-video-videoheight" title="dom-video-videoHeight"><code>videoHeight</code></dfn> IDL
2236: attribute must return the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> of
2237: 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
2238: attributes must return 0.</p>
2239:
2240: </div><p>The <code><a href="#the-video-element">video</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
2241: attributes</a>.</p><div class="impl">
2242:
2243: <p>In the absence of style rules to the contrary, video content
2244: should be rendered inside the element's playback area such that the
2245: video content is shown centered in the playback area at the largest
2246: possible size that fits completely within it, with the video
2247: content's aspect ratio being preserved. Thus, if the aspect ratio of
2248: the playback area does not match the aspect ratio of the video, the
2249: video will be shown letterboxed or pillarboxed. Areas of the
2250: element's playback area that do not contain the video represent
2251: nothing.</p>
2252:
2253: <p class="note">In user agents that implement CSS, the above
1.101 mike 2254: requirement can be implemented by using the <a href="rendering.html#video-object-fit">style rule suggested in the rendering
1.47 mike 2255: section</a>.</p>
2256:
2257: <p>The intrinsic width of a <code><a href="#the-video-element">video</a></code> element's playback
2258: area is the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2259: width</a> of the video resource, if that is available; otherwise
2260: it is the intrinsic width of the <a href="#poster-frame">poster frame</a>, if that
2261: is available; otherwise it is 300 CSS pixels.</p>
2262:
2263: <p>The intrinsic height of a <code><a href="#the-video-element">video</a></code> element's playback
2264: area is the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic
2265: height</a> of the video resource, if that is available; otherwise
2266: it is the intrinsic height of the <a href="#poster-frame">poster frame</a>, if that
2267: is available; otherwise it is 150 CSS pixels.</p>
2268:
2269: <hr><p>User agents should provide controls to enable or disable the
2270: display of closed captions, audio description tracks, and other
2271: additional data associated with the video stream, though such
2272: features should, again, not interfere with the page's normal
2273: rendering.</p>
2274:
2275: <p>User agents may allow users to view the video content in manners
2276: more suitable to the user (e.g. full-screen or in an independent
2277: resizable window). As for the other user interface features,
2278: controls to enable this should not interfere with the page's normal
2279: rendering unless the user agent is <a href="#expose-a-user-interface-to-the-user" title="expose a user
2280: interface to the user">exposing a user interface</a>. In such an
2281: independent context, however, user agents may make full user
2282: interfaces visible, with, e.g., play, pause, seeking, and volume
2283: controls, even if the <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute is absent.</p>
2284:
2285: <p>User agents may allow video playback to affect system features
2286: that could interfere with the user's experience; for example, user
2287: agents could disable screensavers while video playback is in
2288: progress.</p>
2289:
2290: <hr><p>The <dfn id="dom-video-poster" title="dom-video-poster"><code>poster</code></dfn> IDL
2291: 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>
2292:
2293: </div><div class="example">
2294:
2295: <p>This example shows how to detect when a video has failed to play
2296: correctly:</p>
2297:
2298: <pre><script>
2299: function failed(e) {
2300: // video playback failed - show a message saying why
2301: switch (e.target.error.code) {
2302: case e.target.error.MEDIA_ERR_ABORTED:
2303: alert('You aborted the video playback.');
2304: break;
2305: case e.target.error.MEDIA_ERR_NETWORK:
2306: alert('A network error caused the video download to fail part-way.');
2307: break;
2308: case e.target.error.MEDIA_ERR_DECODE:
2309: alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
2310: break;
2311: case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
2312: alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
2313: break;
2314: default:
2315: alert('An unknown error occurred.');
2316: break;
2317: }
2318: }
2319: </script>
2320: <p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
2321: <p><a href="tgif.vid">Download the video file</a>.</p></pre>
2322:
2323: </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>
2324: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2325: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2326: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2327: <dd>If the element has a <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute: <a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.126 mike 2328: <dd>If the element has a <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute: <a href="content-models.html#palpable-content">Palpable content</a>.</dd>
1.47 mike 2329: <dt>Contexts in which this element can be used:</dt>
2330: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2331: <dt>Content model:</dt>
2332: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2333: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2334: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
1.103 mike 2335: <dd>If the element does not have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute: zero or more <code><a href="#the-source-element">source</a></code> elements, then
1.47 mike 2336: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2337: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2338: <dt>Content attributes:</dt>
2339: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2340: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2341: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2342: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2343: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2344: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2345: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2346: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2347: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2348: <dt>DOM interface:</dt>
2349: <dd>
2350: <pre class="idl">[NamedConstructor=<a href="#dom-audio" title="dom-Audio">Audio</a>(),
1.101 mike 2351: NamedConstructor=<a href="#dom-audio-s" title="dom-Audio-s">Audio</a>(DOMString src)]
1.47 mike 2352: interface <dfn id="htmlaudioelement">HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {};</pre>
2353: </dd>
1.101 mike 2354: </dl><p>An <code><a href="#the-audio-element">audio</a></code> element <a href="rendering.html#represents">represents</a> a sound or
1.47 mike 2355: audio stream.</p><p>Content may be provided inside the <code><a href="#the-audio-element">audio</a></code>
2356: element<span class="impl">. User agents should not show this content
2357: to the user</span>; it is intended for older Web browsers which do
2358: not support <code><a href="#the-audio-element">audio</a></code>, so that legacy audio plugins can be
2359: tried, or to show text to the users of these older browsers informing
2360: them of how to access the audio contents.</p><p class="note">In particular, this content is not intended to
2361: address accessibility concerns. To make audio content accessible to
2362: the deaf or to those with other physical or cognitive disabilities,
1.90 mike 2363: a variety of features are available. If captions or a sign language
2364: video are available, the <code><a href="#the-video-element">video</a></code> element can be used
2365: instead of the <code><a href="#the-audio-element">audio</a></code> element to play the audio,
2366: allowing users to enable the visual alternatives. Chapter titles can
2367: be provided to aid navigation, using the <code><a href="#the-track-element">track</a></code> element
2368: and a WebVTT file. And, naturally, transcripts or other textual
2369: alternatives can be provided by simply linking to them in the prose
2370: 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 2371: 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>,
2372: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2373: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2374: <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
2375: elements</a>.</p><div class="impl">
2376:
2377: <p>When an <code><a href="#the-audio-element">audio</a></code> element is <a href="#potentially-playing">potentially
2378: playing</a>, it must have its audio data played synchronized with
2379: the <a href="#current-playback-position">current playback position</a>, at the element's
2380: <a href="#effective-media-volume">effective media volume</a>.</p>
2381:
2382: <p>When an <code><a href="#the-audio-element">audio</a></code> element is not <a href="#potentially-playing">potentially
2383: playing</a>, audio must not play for the element.</p>
2384:
2385: </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>
2386:
2387: <dd>
2388:
2389: <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
2390: passed in the argument, if applicable.</p>
2391:
2392: </dd>
2393:
2394: </dl><div class="impl">
2395:
2396: <p>Two constructors are provided for creating
2397: <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> objects (in addition to the factory
2398: 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,
2399: these must return a new <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new
2400: <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
2401: 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
2402: its <code title="attr-media-src"><a href="#attr-media-src">src</a></code> content attribute set to
2403: the provided value, and the user agent must invoke the object's
2404: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2405: algorithm</a> before returning. The element's document must be
2406: the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
2407: context</a> of the <code><a href="browsers.html#window">Window</a></code> object on which the
2408: interface object of the invoked constructor is found.</p>
2409:
2410: </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>
2411: <dd>None.</dd>
2412: <dt>Contexts in which this element can be used:</dt>
2413: <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>
2414: or <code><a href="#the-track-element">track</a></code> elements.</dd>
2415: <dt>Content model:</dt>
2416: <dd>Empty.</dd>
2417: <dt>Content attributes:</dt>
2418: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2419: <dd><code title="attr-source-src"><a href="#attr-source-src">src</a></code></dd>
2420: <dd><code title="attr-source-type"><a href="#attr-source-type">type</a></code></dd>
2421: <dd><code title="attr-source-media"><a href="#attr-source-media">media</a></code></dd>
2422: <dt>DOM interface:</dt>
2423: <dd>
2424: <pre class="idl">interface <dfn id="htmlsourceelement">HTMLSourceElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2425: attribute DOMString <a href="#dom-source-src" title="dom-source-src">src</a>;
2426: attribute DOMString <a href="#dom-source-type" title="dom-source-type">type</a>;
2427: attribute DOMString <a href="#dom-source-media" title="dom-source-media">media</a>;
2428: };</pre>
2429: </dd>
2430: </dl><p>The <code><a href="#the-source-element">source</a></code> element allows authors to specify
2431: multiple alternative <a href="#media-resource" title="media resource">media
2432: resources</a> for <a href="#media-element" title="media element">media
1.101 mike 2433: elements</a>. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-source-src" title="attr-source-src"><code>src</code></dfn> attribute
1.47 mike 2434: gives the address of the <a href="#media-resource">media resource</a>. The value must
2435: be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2436: spaces</a>. This attribute must be present.</p><p class="note">Dynamically modifying a <code><a href="#the-source-element">source</a></code> element
2437: and its attribute when the element is already inserted in a
2438: <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 2439: 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
2440: element</a> directly, possibly making use of the <code title="dom-navigator-canPlayType"><a href="#dom-navigator-canplaytype">canPlayType()</a></code> method to
2441: pick from amongst available resources. Generally, manipulating
2442: <code><a href="#the-source-element">source</a></code> elements manually after the document has been
2443: 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 2444: attribute gives the type of the <a href="#media-resource">media resource</a>, to help
2445: the user agent determine if it can play this <a href="#media-resource">media
2446: resource</a> before fetching it. If specified, its value must be
2447: a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>. The <code title="">codecs</code>
2448: parameter, which certain MIME types define, might be necessary to
1.101 mike 2449: specify exactly how the resource is encoded. <a href="references.html#refsRFC4281">[RFC4281]</a></p><div class="example">
1.47 mike 2450:
2451: <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>
2452:
2453: <dl><dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2454: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></pre></dd>
2455:
2456: <dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2457: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></pre></dd>
2458:
2459: <dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
2460: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></pre></dd>
2461:
2462: <dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2463: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></pre></dd>
2464:
2465:
2466: <dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2467: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></pre></dd>
2468:
2469: <dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2470: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></pre></dd>
2471:
2472: <dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
2473: <dd><pre><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></pre></dd>
2474:
2475:
2476: <dt>Theora video and Vorbis audio in Ogg container</dt>
2477: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></pre></dd>
2478:
2479: <dt>Theora video and Speex audio in Ogg container</dt>
2480: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></pre></dd>
2481:
2482: <dt>Vorbis audio alone in Ogg container</dt>
2483: <dd><pre><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></pre></dd>
2484:
2485: <dt>Speex audio alone in Ogg container</dt>
2486: <dd><pre><source src='audio.spx' type='audio/ogg; codecs=speex'></pre></dd>
2487:
2488: <dt>FLAC audio alone in Ogg container</dt>
2489: <dd><pre><source src='audio.oga' type='audio/ogg; codecs=flac'></pre></dd>
2490:
2491: <dt>Dirac video and Vorbis audio in Ogg container</dt>
2492: <dd><pre><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></pre></dd>
2493:
2494:
2495:
2496:
2497:
2498:
2499: </dl></div><p>The <dfn id="attr-source-media" title="attr-source-media"><code>media</code></dfn>
2500: attribute gives the intended media type of the <a href="#media-resource">media
2501: resource</a>, to help the user agent determine if this
2502: <a href="#media-resource">media resource</a> is useful to the user before fetching
2503: 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
2504: "<code title="">all</code>", meaning that by default the <a href="#media-resource">media
2505: resource</a> is suitable for all media.</p><div class="impl">
2506:
2507: <p>If a <code><a href="#the-source-element">source</a></code> element is inserted as a child of a
2508: <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
2509: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, the user
2510: 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
2511: algorithm</a>.</p>
2512:
2513: <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
2514: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2515: name.</p>
2516:
2517: </div><div class="example">
2518:
2519: <p>If the author isn't sure if the user agents will all be able to
2520: render the media resources provided, the author can listen to the
2521: <code title="event-error">error</code> event on the last
2522: <code><a href="#the-source-element">source</a></code> element and trigger fallback behavior:</p>
2523:
2524: <pre><script>
2525: function fallback(video) {
2526: // replace <video> with its contents
2527: while (video.hasChildNodes()) {
2528: if (video.firstChild instanceof HTMLSourceElement)
2529: video.removeChild(video.firstChild);
2530: else
2531: video.parentNode.insertBefore(video.firstChild, video);
2532: }
2533: video.parentNode.removeChild(video);
2534: }
2535: </script>
2536: <video controls autoplay>
2537: <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
2538: <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
2539: onerror="fallback(parentNode)">
2540: ...
2541: </video></pre>
2542:
2543: </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>
2544: <dd>None.</dd>
2545: <dt>Contexts in which this element can be used:</dt>
2546: <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>
2547: <dt>Content model:</dt>
2548: <dd>Empty.</dd>
2549: <dt>Content attributes:</dt>
2550: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2551: <dd><code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code></dd>
2552: <dd><code title="attr-track-src"><a href="#attr-track-src">src</a></code></dd>
2553: <dd><code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code></dd>
2554: <dd><code title="attr-track-label"><a href="#attr-track-label">label</a></code></dd>
2555: <dd><code title="attr-track-default"><a href="#attr-track-default">default</a></code></dd>
2556: <dt>DOM interface:</dt>
2557: <dd>
2558: <pre class="idl">interface <dfn id="htmltrackelement">HTMLTrackElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2559: attribute DOMString <a href="#dom-track-kind" title="dom-track-kind">kind</a>;
2560: attribute DOMString <a href="#dom-track-src" title="dom-track-src">src</a>;
2561: attribute DOMString <a href="#dom-track-srclang" title="dom-track-srclang">srclang</a>;
2562: attribute DOMString <a href="#dom-track-label" title="dom-track-label">label</a>;
2563: attribute boolean <a href="#dom-track-default" title="dom-track-default">default</a>;
2564:
1.130 mike 2565: const unsigned short <a href="#dom-track-none" title="dom-track-NONE">NONE</a> = 0;
2566: const unsigned short <a href="#dom-track-loading" title="dom-track-LOADING">LOADING</a> = 1;
2567: const unsigned short <a href="#dom-track-loaded" title="dom-track-LOADED">LOADED</a> = 2;
2568: const unsigned short <a href="#dom-track-error" title="dom-track-ERROR">ERROR</a> = 3;
2569: readonly attribute unsigned short <a href="#dom-track-readystate" title="dom-track-readyState">readyState</a>;
2570:
1.47 mike 2571: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-track-track" title="dom-track-track">track</a>;
2572: };</pre>
2573: </dd>
2574: </dl><p>The <code><a href="#the-track-element">track</a></code> element allows authors to specify explicit
1.101 mike 2575: external timed <a href="#text-track" title="text track">text tracks</a> for <a href="#media-element" title="media element">media elements</a>. It does not <a href="rendering.html#represents" title="represents">represent</a> anything on its own.</p><p>The <dfn id="attr-track-kind" title="attr-track-kind"><code>kind</code></dfn>
1.47 mike 2576: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following
2577: table lists the keywords defined for this attribute. The keyword
2578: given in the first cell of each row maps to the state given in the
2579: second cell.</p><table><thead><tr><th>Keyword
2580: </th><th>State
2581: </th><th>Brief description
2582: </th></tr></thead><tbody><tr><td><dfn id="attr-track-kind-keyword-subtitles" title="attr-track-kind-keyword-subtitles"><code>subtitles</code></dfn>
2583: </td><td><dfn id="attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</dfn>
2584: </td><td>
1.123 mike 2585: Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the <a href="#media-resource">media resource</a>'s audio track).
1.115 mike 2586: Overlaid on the video.
1.47 mike 2587: </td></tr><tr><td><dfn id="attr-track-kind-keyword-captions" title="attr-track-kind-keyword-captions"><code>captions</code></dfn>
2588: </td><td><dfn id="attr-track-kind-captions" title="attr-track-kind-captions">Captions</dfn>
2589: </td><td>
1.123 mike 2590: Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when sound is unavailable or not clearly audible (e.g. because it is muted, drowned-out by ambient noise, or because the user is deaf).
1.115 mike 2591: Overlaid on the video; labeled as appropriate for the hard-of-hearing.
1.47 mike 2592: </td></tr><tr><td><dfn id="attr-track-kind-keyword-descriptions" title="attr-track-kind-keyword-descriptions"><code>descriptions</code></dfn>
2593: </td><td><dfn id="attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</dfn>
2594: </td><td>
1.95 mike 2595: 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).
2596: Synthesized as audio.
1.47 mike 2597: </td></tr><tr><td><dfn id="attr-track-kind-keyword-chapters" title="attr-track-kind-keyword-chapters"><code>chapters</code></dfn>
2598: </td><td><dfn id="attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</dfn>
2599: </td><td>
2600: Chapter titles, intended to be used for navigating the <a href="#media-resource">media resource</a>.
1.91 mike 2601: Displayed as an interactive (potentially nested) list in the user agent's interface.
1.47 mike 2602: </td></tr><tr><td><dfn id="attr-track-kind-keyword-metadata" title="attr-track-kind-keyword-metadata"><code>metadata</code></dfn>
2603: </td><td><dfn id="attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</dfn>
2604: </td><td>
2605: Tracks intended for use from script.
2606: Not displayed by the user agent.
2607: </td></tr></tbody></table><p>The attribute may be omitted. The <i>missing value default</i> is
2608: 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
2609: gives the address of the text track data. The value must be a
2610: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2611: spaces</a>. This attribute must be present.</p><div class="impl">
2612:
2613: <p>If the element has a <code title="attr-track-src"><a href="#attr-track-src">src</a></code>
2614: attribute whose value is not the empty string and whose value, when
2615: the attribute was set, could be successfully <a href="urls.html#resolve-a-url" title="resolve a
2616: url">resolved</a> relative to the element, then the element's
2617: <dfn id="track-url">track URL</dfn> is the resulting <a href="urls.html#absolute-url">absolute
2618: URL</a>. Otherwise, the element's <a href="#track-url">track URL</a> is the
2619: empty string.</p>
2620:
2621: </div><p>The <dfn id="attr-track-srclang" title="attr-track-srclang"><code>srclang</code></dfn>
2622: attribute gives the language of the text track data. The value must
2623: be a valid BCP 47 language tag. This attribute must be present if
2624: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute is
2625: in the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a>
1.101 mike 2626: state. <a href="references.html#refsBCP47">[BCP47]</a></p><div class="impl">
1.47 mike 2627:
2628: <p>If the element has a <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attribute whose value is
2629: not the empty string, then the element's <dfn id="track-language">track language</dfn>
2630: is the value of the attribute. Otherwise, the element has no
2631: <a href="#track-language">track language</a>.</p>
2632:
2633: </div><p>The <dfn id="attr-track-label" title="attr-track-label"><code>label</code></dfn>
2634: attribute gives a user-readable title for the track. This title is
2635: 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
2636: in their user interface.</p><p>The value of the <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2637: attribute, if the attribute is present, must not be the empty
2638: string. Furthermore, there must not be two <code><a href="#the-track-element">track</a></code>
2639: 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
2640: state, whose <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code>
2641: attributes are both missing or have values that represent the same
2642: language, and whose <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2643: attributes are again both missing or both have the same value.</p><div class="impl">
2644:
2645: <p>If the element has a <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2646: attribute whose value is not the empty string, then the element's
2647: <dfn id="track-label">track label</dfn> is the value of the attribute. Otherwise, the
2648: element's <a href="#track-label">track label</a> is a user-agent defined string
2649: (e.g. the string "untitled" in the user's locale, or a value
2650: automatically generated from the other attributes).</p>
2651:
2652: </div><p>The <dfn id="attr-track-default" title="attr-track-default"><code>default</code></dfn>
2653: attribute, if specified, indicates that the track is to be enabled
2654: if the user's preferences do not indicate that another track would
2655: be more appropriate. There must not be more than one
1.130 mike 2656: <code><a href="#the-track-element">track</a></code> element with the same parent node with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute specified.</p><dl class="domintro"><dt><var title="">track</var> . <code title="dom-track-readyState"><a href="#dom-track-readystate">readyState</a></code></dt>
2657: <dd>
2658: <p>Returns the <a href="#text-track-readiness-state">text track readiness state</a>,
2659: represented by a number from the following list:</p>
2660: <dl><dt><var title="">track</var> . <code title="dom-track-NONE"><a href="#dom-track-none">NONE</a></code> (0)</dt>
2661: <dd>
2662: <p>The <a href="#text-track-not-loaded">text track not loaded</a> state.</p>
2663: </dd>
2664: <dt><var title="">track</var> . <code title="dom-track-LOADING"><a href="#dom-track-loading">LOADING</a></code> (1)</dt>
2665: <dd>
2666: <p>The <a href="#text-track-loading">text track loading</a> state.</p>
2667: </dd>
2668: <dt><var title="">track</var> . <code title="dom-track-LOADED"><a href="#dom-track-loaded">LOADED</a></code> (2)</dt>
2669: <dd>
2670: <p>The <a href="#text-track-loaded">text track loaded</a> state.</p>
2671: </dd>
2672: <dt><var title="">track</var> . <code title="dom-track-ERROR"><a href="#dom-track-error">ERROR</a></code> (3)</dt>
2673: <dd>
2674: <p>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</p>
2675: </dd>
2676: </dl></dd>
2677:
2678: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
1.47 mike 2679:
2680: <dd>
2681:
2682: <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>
2683:
2684: </dd>
2685:
2686: </dl><div class="impl">
2687:
1.130 mike 2688: <p>The <dfn id="dom-track-readystate" title="dom-track-readyState"><code>readyState</code></dfn> attribute
2689: must return the numeric value corresponding to the <a href="#text-track-readiness-state">text track
2690: readiness state</a> of the <code><a href="#the-track-element">track</a></code> element's
2691: <a href="#text-track">text track</a>, as defined by the following list:</p>
2692:
2693: <dl><dt><dfn id="dom-track-none" title="dom-track-NONE"><code>NONE</code></dfn> (numeric value 0)</dt>
2694: <dd>The <a href="#text-track-not-loaded">text track not loaded</a> state.</dd>
2695: <dt><dfn id="dom-track-loading" title="dom-track-LOADING"><code>LOADING</code></dfn> (numeric value 1)</dt>
2696: <dd>The <a href="#text-track-loading">text track loading</a> state.</dd>
2697: <dt><dfn id="dom-track-loaded" title="dom-track-LOADED"><code>LOADED</code></dfn> (numeric value 2)</dt>
2698: <dd>The <a href="#text-track-loaded">text track loaded</a> state.</dd>
2699: <dt><dfn id="dom-track-error" title="dom-track-ERROR"><code>ERROR</code></dfn> (numeric value 3)</dt>
2700: <dd>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</dd>
2701: </dl><p>The <dfn id="dom-track-track" title="dom-track-track"><code>track</code></dfn> IDL
1.47 mike 2702: attribute must, on getting, return the <code><a href="#the-track-element">track</a></code> element's
2703: <a href="#text-track">text track</a>'s corresponding <code><a href="#texttrack">TextTrack</a></code>
2704: object.</p>
2705:
2706: <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
2707: must <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the
2708: same name. The <dfn id="dom-track-kind" title="dom-track-kind"><code>kind</code></dfn>
2709: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
2710: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
2711:
2712: </div><div class="example">
2713:
2714: <p>This video has subtitles in several languages:</p>
2715:
2716: <pre><video src="brave.webm">
2717: <track kind=subtitles src=brave.en.vtt srclang=en label="English">
1.123 mike 2718: <track kind=captions src=brave.en.hoh.vtt srclang=en label="English for the Hard of Hearing">
1.73 mike 2719: <track kind=subtitles src=brave.fr.vtt srclang=fr lang=fr label="Français">
2720: <track kind=subtitles src=brave.de.vtt srclang=de lang=de label="Deutsch">
1.47 mike 2721: </video></pre>
2722:
2723: </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>
2724: (<code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>, in this specification)
2725: implement the following interface:</p><pre class="idl">interface <dfn id="htmlmediaelement">HTMLMediaElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2726:
2727: // error state
1.68 mike 2728: readonly attribute <a href="#mediaerror">MediaError</a>? <a href="#dom-media-error" title="dom-media-error">error</a>;
1.47 mike 2729:
2730: // network state
2731: attribute DOMString <a href="#dom-media-src" title="dom-media-src">src</a>;
2732: readonly attribute DOMString <a href="#dom-media-currentsrc" title="dom-media-currentSrc">currentSrc</a>;
1.61 mike 2733: attribute DOMString <a href="#dom-media-crossorigin" title="dom-media-crossOrigin">crossOrigin</a>;
1.47 mike 2734: const unsigned short <a href="#dom-media-network_empty" title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</a> = 0;
2735: const unsigned short <a href="#dom-media-network_idle" title="dom-media-NETWORK_IDLE">NETWORK_IDLE</a> = 1;
2736: const unsigned short <a href="#dom-media-network_loading" title="dom-media-NETWORK_LOADING">NETWORK_LOADING</a> = 2;
2737: const unsigned short <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a> = 3;
2738: readonly attribute unsigned short <a href="#dom-media-networkstate" title="dom-media-networkState">networkState</a>;
2739: attribute DOMString <a href="#dom-media-preload" title="dom-media-preload">preload</a>;
2740: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-buffered" title="dom-media-buffered">buffered</a>;
2741: void <a href="#dom-media-load" title="dom-media-load">load</a>();
1.101 mike 2742: DOMString <a href="#dom-navigator-canplaytype" title="dom-navigator-canPlayType">canPlayType</a>(DOMString type);
1.47 mike 2743:
2744: // ready state
2745: const unsigned short <a href="#dom-media-have_nothing" title="dom-media-HAVE_NOTHING">HAVE_NOTHING</a> = 0;
2746: const unsigned short <a href="#dom-media-have_metadata" title="dom-media-HAVE_METADATA">HAVE_METADATA</a> = 1;
2747: const unsigned short <a href="#dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</a> = 2;
2748: const unsigned short <a href="#dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</a> = 3;
2749: const unsigned short <a href="#dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</a> = 4;
2750: readonly attribute unsigned short <a href="#dom-media-readystate" title="dom-media-readyState">readyState</a>;
2751: readonly attribute boolean <a href="#dom-media-seeking" title="dom-media-seeking">seeking</a>;
2752:
2753: // playback state
2754: attribute double <a href="#dom-media-currenttime" title="dom-media-currentTime">currentTime</a>;
2755: readonly attribute double <a href="#dom-media-initialtime" title="dom-media-initialTime">initialTime</a>;
2756: readonly attribute double <a href="#dom-media-duration" title="dom-media-duration">duration</a>;
2757: readonly attribute <span>Date</span> <a href="#dom-media-startoffsettime" title="dom-media-startOffsetTime">startOffsetTime</a>;
2758: readonly attribute boolean <a href="#dom-media-paused" title="dom-media-paused">paused</a>;
2759: attribute double <a href="#dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate">defaultPlaybackRate</a>;
2760: attribute double <a href="#dom-media-playbackrate" title="dom-media-playbackRate">playbackRate</a>;
2761: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-played" title="dom-media-played">played</a>;
2762: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-seekable" title="dom-media-seekable">seekable</a>;
2763: readonly attribute boolean <a href="#dom-media-ended" title="dom-media-ended">ended</a>;
2764: attribute boolean <a href="#dom-media-autoplay" title="dom-media-autoplay">autoplay</a>;
2765: attribute boolean <a href="#dom-media-loop" title="dom-media-loop">loop</a>;
2766: void <a href="#dom-media-play" title="dom-media-play">play</a>();
2767: void <a href="#dom-media-pause" title="dom-media-pause">pause</a>();
2768:
2769: // media controller
2770: attribute <span>DOMString</span> <a href="#dom-media-mediagroup" title="dom-media-mediaGroup">mediaGroup</a>;
1.68 mike 2771: attribute <a href="#mediacontroller">MediaController</a>? <a href="#dom-media-controller" title="dom-media-controller">controller</a>;
1.47 mike 2772:
2773: // controls
2774: attribute boolean <a href="#dom-media-controls" title="dom-media-controls">controls</a>;
2775: attribute double <a href="#dom-media-volume" title="dom-media-volume">volume</a>;
2776: attribute boolean <a href="#dom-media-muted" title="dom-media-muted">muted</a>;
2777: attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
2778:
2779: // tracks
1.76 mike 2780: readonly attribute <a href="#audiotracklist">AudioTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
2781: readonly attribute <a href="#videotracklist">VideoTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
1.121 mike 2782: readonly attribute <a href="#texttracklist">TextTrackList</a> <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
1.132 ! mike 2783: <a href="#texttrack">TextTrack</a> <a href="#dom-media-addtexttrack" title="dom-media-addTextTrack">addTextTrack</a>(DOMString kind, optional DOMString label, optional DOMString language);
1.61 mike 2784: };</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 2785: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2786: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2787: <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
2788: this section.</p><p><a href="#media-element" title="media element">Media elements</a> are used to
2789: present audio data, or video and audio data, to the user. This is
2790: referred to as <dfn id="media-data">media data</dfn> in this section, since this
2791: section applies equally to <a href="#media-element" title="media element">media
1.56 mike 2792: elements</a> for audio or for video.
1.85 mike 2793:
1.56 mike 2794: The term <dfn id="media-resource">media resource</dfn> is used to refer to the complete
2795: set of media data, e.g. the complete video file, or complete audio
2796: file.
1.85 mike 2797:
1.56 mike 2798: </p><p>A <a href="#media-resource">media resource</a> can have multiple audio and video
1.47 mike 2799: tracks. For the purposes of a <a href="#media-element">media element</a>, the video
2800: data of the <a href="#media-resource">media resource</a> is only that of the
2801: 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
2802: audio data of the <a href="#media-resource">media resource</a> is the result of
2803: mixing all the currently enabled tracks (if any) given by the
2804: element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>
2805: 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>
2806: elements can be used for both audio and video. The main difference
2807: between the two is simply that the <code><a href="#the-audio-element">audio</a></code> element has no
2808: playback area for visual content (such as video or captions),
2809: whereas the <code><a href="#the-video-element">video</a></code> element does.</p><div class="impl">
2810:
2811: <p>Except where otherwise specified, the <a href="webappapis.html#task-source">task source</a>
2812: for all the tasks <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> in this
2813: section and its subsections is the <dfn id="media-element-event-task-source">media element event task
2814: source</dfn>.</p>
2815:
2816: </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>
2817:
2818: <dd>
2819:
2820: <p>Returns a <code><a href="#mediaerror">MediaError</a></code> object representing the
2821: current error state of the element.</p>
2822:
2823: <p>Returns null if there is no error.</p>
2824:
2825: </dd>
2826:
2827: </dl><div class="impl">
2828:
2829: <p>All <a href="#media-element" title="media element">media elements</a> have an
2830: associated error status, which records the last error the element
2831: encountered since its <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2832: algorithm</a> was last invoked. The <dfn id="dom-media-error" title="dom-media-error"><code>error</code></dfn> attribute, on
2833: getting, must return the <code><a href="#mediaerror">MediaError</a></code> object created for
2834: this last error, or null if there has not been an error.</p>
2835:
2836: </div><pre class="idl">interface <dfn id="mediaerror">MediaError</dfn> {
2837: const unsigned short <a href="#dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</a> = 1;
2838: const unsigned short <a href="#dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</a> = 2;
2839: const unsigned short <a href="#dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</a> = 3;
2840: 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;
2841: readonly attribute unsigned short <a href="#dom-mediaerror-code" title="dom-MediaError-code">code</a>;
2842: };</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>
2843:
2844: <dd>
2845:
2846: <p>Returns the current error's error code, from the list below.</p>
2847:
2848: </dd>
2849:
2850: </dl><div class="impl">
2851:
2852: <p>The <dfn id="dom-mediaerror-code" title="dom-MediaError-code"><code>code</code></dfn>
2853: attribute of a <code><a href="#mediaerror">MediaError</a></code> object must return the code
2854: for the error, which must be one of the following:</p>
2855:
2856: </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>
2857:
2858: <dd>The fetching process for the <a href="#media-resource">media resource</a> was
2859: aborted by the user agent at the user's request.</dd>
2860:
2861: <dt><dfn id="dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK"><code>MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
2862:
2863: <dd>A network error of some description caused the user agent to
2864: stop fetching the <a href="#media-resource">media resource</a>, after the resource
2865: was established to be usable.</dd>
2866:
2867: <dt><dfn id="dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE"><code>MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
2868:
2869: <dd>An error of some description occurred while decoding the
2870: <a href="#media-resource">media resource</a>, after the resource was established to
2871: be usable.</dd>
2872:
2873: <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>
2874:
2875: <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>
2876:
2877: </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
2878: attribute on <a href="#media-element" title="media element">media elements</a> gives
2879: the address of the media resource (video, audio) to show. The
2880: attribute, if present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.61 mike 2881: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-media-crossorigin" title="attr-media-crossorigin"><code>crossorigin</code></dfn>
2882: content attribute on <a href="#media-element" title="media element">media
2883: elements</a> is a <a href="fetching-resources.html#cors-settings-attribute">CORS settings attribute</a>.</p><div class="impl">
1.47 mike 2884:
2885: <p>If a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute of a
2886: <a href="#media-element">media element</a> is set or changed, the user agent must
2887: invoke the <a href="#media-element">media element</a>'s <a href="#media-element-load-algorithm">media element load
2888: 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
2889: if there are <code><a href="#the-source-element">source</a></code> elements present.)</p>
2890:
2891: <p>The <dfn id="dom-media-src" title="dom-media-src"><code>src</code></dfn> IDL
2892: attribute on <a href="#media-element" title="media element">media elements</a> must
2893: <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the same name.</p>
2894:
1.61 mike 2895: <p>The <dfn id="dom-media-crossorigin" title="dom-media-crossOrigin"><code>crossOrigin</code></dfn> IDL
2896: 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
2897: attribute.</p>
2898:
1.47 mike 2899: </div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code></dt>
2900:
2901: <dd>
2902:
2903: <p>Returns the address of the current <a href="#media-resource">media resource</a>.</p>
2904:
2905: <p>Returns the empty string when there is no <a href="#media-resource">media resource</a>.</p>
2906:
2907: </dd>
2908:
2909: </dl><div class="impl">
2910:
2911: <p>The <dfn id="dom-media-currentsrc" title="dom-media-currentSrc"><code>currentSrc</code></dfn> IDL
2912: attribute is initially the empty string. Its value is changed by the
2913: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2914: algorithm</a> defined below.</p>
2915:
2916: </div><p class="note">There are two ways to specify a <a href="#media-resource">media
2917: resource</a>, the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
2918: attribute, or <code><a href="#the-source-element">source</a></code> elements. The attribute overrides
1.53 mike 2919: 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 2920: <em>type</em>, specifically a <a href="infrastructure.html#mime-type">MIME type</a>, in some cases
2921: with a <code title="">codecs</code> parameter. (Whether the <code title="">codecs</code> parameter is allowed or not depends on the
1.101 mike 2922: MIME type.) <a href="references.html#refsRFC4281">[RFC4281]</a></p><p>Types are usually somewhat incomplete descriptions; for example
1.47 mike 2923: "<code title="">video/mpeg</code>" doesn't say anything except what
2924: the container type is, and even a type like "<code title="">video/mp4; codecs="avc1.42E01E,
2925: mp4a.40.2"</code>" doesn't include information like the actual
2926: bitrate (only the maximum bitrate). Thus, given a type, a user agent
2927: can often only know whether it <em>might</em> be able to play
2928: media of that type (with varying levels of confidence), or whether
2929: 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
2930: one that describes a resource that the user agent definitely does
2931: not support, for example because it doesn't recognize the container
2932: type, or it doesn't support the listed codecs.</p><p>The <a href="infrastructure.html#mime-type">MIME type</a>
2933: "<code>application/octet-stream</code>" with no parameters is never
2934: <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user agent knows it cannot render</a>. User
2935: agents must treat that type as equivalent to the lack of any
2936: explicit <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a>
2937: when it is used to label a potential <a href="#media-resource">media
2938: resource</a>.</p><p class="note">
2939: "<code>application/octet-stream</code>"
2940: is special-cased here; if any parameter appears with it, it
2941: should
2942:
2943: be treated just like any other <a href="infrastructure.html#mime-type">MIME type</a>.
2944:
2945: This is a deviation from the rule that unknown <a href="infrastructure.html#mime-type">MIME type</a> parameters
2946: should be ignored.
2947:
2948:
2949: </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>
2950:
2951: <dd>
2952:
2953: <p>Returns the empty string (a negative response), "maybe", or
2954: "probably" based on how confident the user agent is that it can
2955: play media resources of the given type.</p>
2956:
2957: </dd>
2958:
2959: </dl><div class="impl">
2960:
2961: <p>The <dfn id="dom-navigator-canplaytype" title="dom-navigator-canPlayType"><code>canPlayType(<var title="">type</var>)</code></dfn> method must return the empty
2962: string if <var title="">type</var> is <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user
2963: agent knows it cannot render</a> or is the type
2964: "<code>application/octet-stream</code>"; it must return "<code title="">probably</code>" if the user agent is confident that the
2965: type represents a <a href="#media-resource">media resource</a> that it can render if
2966: used in with this <code><a href="#the-audio-element">audio</a></code> or <code><a href="#the-video-element">video</a></code> element;
2967: and it must return "<code title="">maybe</code>" otherwise.
2968: Implementors are encouraged to return "<code title="">maybe</code>"
2969: unless the type can be confidently established as being supported or
2970: 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
2971: present.</p>
2972:
2973: </div><div class="example">
2974:
2975: <p>This script tests to see if the user agent supports a
2976: (fictional) new format to dynamically decide whether to use a
2977: <code><a href="#the-video-element">video</a></code> element or a plugin:</p>
2978:
2979: <pre><section id="video">
2980: <p><a href="playing-cats.nfv">Download video</a></p>
2981: </section>
2982: <script>
2983: var videoSection = document.getElementById('video');
2984: var videoElement = document.createElement('video');
2985: var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
1.69 mike 2986: if (support != "probably" && "New Fictional Video Plugin" in navigator.plugins) {
1.47 mike 2987: // not confident of browser support
2988: // but we have a plugin
2989: // so use plugin instead
2990: videoElement = document.createElement("embed");
2991: } else if (support == "") {
2992: // no support from browser and no plugin
2993: // do nothing
2994: videoElement = null;
2995: }
2996: if (videoElement) {
2997: while (videoSection.hasChildNodes())
2998: videoSection.removeChild(videoSection.firstChild);
2999: videoElement.setAttribute("src", "playing-cats.nfv");
3000: videoSection.appendChild(videoElement);
3001: }
3002: </script></pre>
3003:
3004: </div><p class="note">The <code title="attr-source-type"><a href="#attr-source-type">type</a></code>
3005: attribute of the <code><a href="#the-source-element">source</a></code> element allows the user agent
3006: to avoid downloading resources that use formats it cannot
3007: 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>
3008:
3009: <dd>
3010:
3011: <p>Returns the current state of network activity for the element,
3012: from the codes in the list below.</p>
3013:
3014: </dd>
3015:
3016: </dl><div class="impl">
3017:
3018: <p>As <a href="#media-element" title="media element">media elements</a> interact
3019: with the network, their current network activity is represented by
3020: the <dfn id="dom-media-networkstate" title="dom-media-networkState"><code>networkState</code></dfn>
3021: attribute. On getting, it must return the current network state of
3022: the element, which must be one of the following values:</p>
3023:
3024: </div><dl><dt><dfn id="dom-media-network_empty" title="dom-media-NETWORK_EMPTY"><code>NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
3025:
3026: <dd>The element has not yet been initialized. All attributes are in
3027: their initial states.</dd>
3028:
3029: <dt><dfn id="dom-media-network_idle" title="dom-media-NETWORK_IDLE"><code>NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
3030:
3031: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3032: algorithm</a> is active and</span> has selected a <a href="#media-resource" title="media resource">resource</a>, but it is not actually
3033: using the network at this time.</dd>
3034:
3035: <dt><dfn id="dom-media-network_loading" title="dom-media-NETWORK_LOADING"><code>NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
3036:
3037: <dd>The user agent is actively trying to download data.</dd>
3038:
3039: <dt><dfn id="dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE"><code>NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
3040:
3041: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3042: algorithm</a> is active, but it</span> has not yet found a <a href="#media-resource" title="media resource">resource</a> to use.</dd>
3043:
3044: </dl><div class="impl">
3045:
3046: <p>The <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3047: algorithm</a> defined below describes exactly when the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute changes
3048: value and what events fire to indicate changes in this state.</p>
3049:
3050: </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>
3051:
3052: <dd>
3053:
3054: <p>Causes the element to reset and start selecting and loading a
3055: new <a href="#media-resource">media resource</a> from scratch.</p>
3056:
3057: </dd>
3058:
3059: </dl><div class="impl">
3060:
3061: <p>All <a href="#media-element" title="media element">media elements</a> have an
3062: <dfn id="autoplaying-flag">autoplaying flag</dfn>, which must begin in the true state, and
3063: a <dfn id="delaying-the-load-event-flag">delaying-the-load-event flag</dfn>, which must begin in the
3064: false state. While the <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> is
1.101 mike 3065: true, the element must <a href="the-end.html#delay-the-load-event">delay the load event</a> of its
1.47 mike 3066: document.</p>
3067:
3068: <p>When the <dfn id="dom-media-load" title="dom-media-load"><code>load()</code></dfn>
3069: method on a <a href="#media-element">media element</a> is invoked, the user agent
3070: must run the <a href="#media-element-load-algorithm">media element load algorithm</a>.</p>
3071:
3072: <p>The <dfn id="media-element-load-algorithm">media element load algorithm</dfn> consists of the
3073: following steps.</p>
3074:
3075: <ol><li><p>Abort any already-running instance of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3076: algorithm</a> for this element.</p></li>
3077:
3078: <li>
3079:
3080: <p>If there are any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> from
3081: the <a href="#media-element">media element</a>'s <a href="#media-element-event-task-source">media element event task
3082: source</a> in one of the <a href="webappapis.html#task-queue" title="task queue">task
3083: queues</a>, then remove those tasks.</p>
3084:
3085: <p class="note">Basically, pending events and callbacks for the
3086: media element are discarded when the media element starts loading
3087: a new resource.</p>
3088:
3089: </li>
3090:
3091: <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
3092: 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
3093: element</a>.</p></li>
3094:
3095: <li>
3096:
3097: <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
3098: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, then
3099: run these substeps:</p>
3100:
3101: <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
3102: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the <a href="#media-element">media
3103: element</a>.</p></li>
3104:
3105: <li><p>If a fetching process is in progress for the <a href="#media-element">media
3106: element</a>, the user agent should stop it.</p></li>
3107:
3108: <li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3109: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>.</p></li>
3110:
3111: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3112: text tracks</a>.</p></li>
3113:
3114: <li><p>If <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is
3115: not set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then set it
3116: to that state.
3117:
3118: </p></li>
3119:
3120: <li><p>If the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
3121: attribute is false, then set it to true.</p></li>
3122:
3123: <li><p>If <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true,
3124: set it to false.</p></li>
3125:
3126: <li>
3127:
3128: <p>Set the <a href="#current-playback-position">current playback position</a> to 0.</p>
3129:
1.107 mike 3130: <p>Set the <a href="#official-playback-position">official playback position</a> to 0.</p>
3131:
3132: <p>If this changed the <a href="#official-playback-position">official playback position</a>,
1.47 mike 3133: then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3134: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
3135: <a href="#media-element">media element</a>.</p>
3136:
3137: </li>
3138:
3139: <li><p>Set the <a href="#initial-playback-position">initial playback position</a> to
3140: 0.</p></li>
3141:
3142: <li><p>Set the <a href="#timeline-offset">timeline offset</a> to Not-a-Number
3143: (NaN).</p></li>
3144:
3145: <li>
3146:
3147: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3148: attribute to Not-a-Number (NaN).</p>
3149:
3150: <p class="note">The user agent <a href="#durationChange">will
3151: not</a> fire a <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event
3152: for this particular change of the duration.</p>
3153:
3154: </li>
3155:
3156: </ol></li>
3157:
3158: <li><p>Set the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute to the
3159: value of the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
3160: attribute.</p></li>
3161:
3162: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code> attribute
3163: to null and the <a href="#autoplaying-flag">autoplaying flag</a> to true.</p></li>
3164:
3165: <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
3166: algorithm</a>.</p></li>
3167:
3168: <li>
3169:
3170: <p class="note">Playback of any previously playing <a href="#media-resource">media
3171: resource</a> for this element stops.</p>
3172:
3173: </li>
3174:
3175: </ol><p>The <dfn id="concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3176: algorithm</dfn> for a <a href="#media-element">media element</a> is as follows. This
3177: algorithm is always invoked synchronously, but one of the first
3178: steps in the algorithm is to return and continue running the
3179: remaining steps asynchronously, meaning that it runs in the
3180: background with scripts and other <a href="webappapis.html#concept-task" title="concept-task">tasks</a> running in parallel. In addition,
3181: this algorithm interacts closely with the <a href="webappapis.html#event-loop">event loop</a>
3182: mechanism; in particular, it has <a href="webappapis.html#synchronous-section" title="synchronous
3183: section">synchronous sections</a> (which are triggered as part of
3184: the <a href="webappapis.html#event-loop">event loop</a> algorithm). Steps in such sections are
3185: marked with ⌛.</p>
3186:
3187: <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>
3188:
3189: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
3190: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that invoked this
3191: algorithm to continue. The <a href="webappapis.html#synchronous-section">synchronous section</a>
3192: consists of all the remaining steps of this algorithm until the
3193: algorithm says the <a href="webappapis.html#synchronous-section">synchronous section</a> has
3194: ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous
3195: sections</a> are marked with ⌛.)</p></li>
3196:
3197: <li>
3198:
3199: <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>
3200:
3201: <p>⌛ Otherwise, if the <a href="#media-element">media element</a> does not
3202: have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute but has a
3203: <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>
3204: element child in <a href="infrastructure.html#tree-order">tree order</a>.</p>
3205:
3206: <p>⌛ Otherwise the <a href="#media-element">media element</a> has neither a
3207: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute nor a
3208: <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
3209: these steps; the <a href="webappapis.html#synchronous-section">synchronous section</a> ends.</p>
3210:
3211: </li>
3212:
3213: <li><p>⌛ Set the <a href="#media-element">media element</a>'s
1.101 mike 3214: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> to true (this <a href="the-end.html#delay-the-load-event" title="delay the load event">delays the load event</a>), and set
1.47 mike 3215: its <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3216: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3217:
3218: <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
3219: event</a> named <code title="event-media-loadstart"><a href="#event-media-loadstart">loadstart</a></code> at the <a href="#media-element">media
3220: element</a>.</p></li>
3221:
3222: <li>
3223:
3224: <p>If <var title="">mode</var> is <i title="">attribute</i>, then
3225: run these substeps:</p>
3226:
3227: <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
3228: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3229: down to the <i title="">failed</i> step below.</p></li>
3230:
3231: <li><p>⌛ Let <var title="">absolute URL</var> be the
3232: <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>
3233: specified by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
3234: attribute's value relative to the <a href="#media-element">media element</a> when
3235: the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was last
3236: changed.</p>
3237: </li><li><p>⌛ If <var title="">absolute URL</var> was obtained
3238: 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>
3239:
3240: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3241: remaining steps asynchronously.</p></li>
3242:
3243: <li><p>If <var title="">absolute URL</var> was obtained
3244: successfully, run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3245: algorithm</a> with <var title="">absolute URL</var>. If that
3246: algorithm returns without aborting <em>this</em> one, then the
3247: load failed.</p></li>
3248:
3249: <li>
3250:
3251: <p><i>Failed</i>: Reaching this step indicates that the media
3252: resource failed to load or that the given <a href="urls.html#url">URL</a> could
3253: not be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a>. In one
3254: atomic operation, run the following steps:</p>
3255:
3256: <ol><li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3257: 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
3258: <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>
3259:
3260: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3261: text tracks</a>.</p></li>
3262:
3263: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3264: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3265: value.</p></li>
3266:
3267: </ol></li>
3268:
3269: <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
3270: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3271: at the <a href="#media-element">media element</a>.</p></li>
3272:
3273: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a>
1.101 mike 3274: to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying
1.47 mike 3275: the load event</a>.</p></li>
3276:
3277: <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
3278: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute is changed, the
3279: element won't attempt to load another resource.</p></li>
3280:
3281:
3282: </ol><p>Otherwise, the <code><a href="#the-source-element">source</a></code> elements will be used; run
3283: these substeps:</p>
3284:
3285: <ol><li>
3286:
3287: <p>⌛ Let <var title="">pointer</var> be a position
3288: defined by two adjacent nodes in the <a href="#media-element">media
3289: element</a>'s child list, treating the start of the list
3290: (before the first child in the list, if any) and end of the list
3291: (after the last child in the list, if any) as nodes in their own
3292: right. One node is the node before <var title="">pointer</var>,
3293: 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
3294: any, or the end of the list, if it is the last node.</p>
3295:
3296: <p>As nodes are inserted and removed into the <a href="#media-element">media
3297: element</a>, <var title="">pointer</var> must be updated as
3298: follows:</p>
3299:
3300: <dl><dt>If a new node is inserted between the two nodes that
3301: define <var title="">pointer</var></dt>
3302:
3303: <dd>Let <var title="">pointer</var> be the point between the
3304: node before <var title="">pointer</var> and the new node. In
3305: other words, insertions at <var title="">pointer</var> go after
3306: <var title="">pointer</var>.</dd>
3307:
3308: <dt>If the node before <var title="">pointer</var> is removed</dt>
3309:
3310: <dd>Let <var title="">pointer</var> be the point between the
3311: node after <var title="">pointer</var> and the node before the
3312: node after <var title="">pointer</var>. In other words, <var title="">pointer</var> doesn't move relative to the remaining
3313: nodes.</dd>
3314:
3315: <dt>If the node after <var title="">pointer</var> is removed</dt>
3316:
3317: <dd>Let <var title="">pointer</var> be the point between the
3318: node before <var title="">pointer</var> and the node after the
3319: node before <var title="">pointer</var>. Just as with the
3320: previous case, <var title="">pointer</var> doesn't move
3321: relative to the remaining nodes.</dd>
3322:
3323: </dl><p>Other changes don't affect <var title="">pointer</var>.</p>
3324:
3325: </li>
3326:
3327: <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
3328: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3329: down to the <i title="">failed</i> step below.</p></li>
3330:
3331: <li><p>⌛ Let <var title="">absolute URL</var> be the
3332: <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>
3333: 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
3334: the <var title="">candidate</var> when the <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute was last
3335: changed.</p>
3336: </li><li><p>⌛ If <var title="">absolute URL</var> was not
3337: obtained successfully, then end the <a href="webappapis.html#synchronous-section">synchronous
3338: section</a>, and jump down to the <i title="">failed</i> step
3339: below.</p></li>
3340:
3341: <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
3342: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3343: described by the <code title="">codecs</code> parameter, for
3344: types that define that parameter), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3345: the user agent knows it cannot render</a>, then end the
3346: <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
3347:
3348: <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
3349: not <a href="common-microsyntaxes.html#matches-the-environment" title="matches the environment">match the
3350: environment</a>, then end the <a href="webappapis.html#synchronous-section">synchronous
3351: section</a>, and jump down to the <i title="">failed</i> step
3352: below.</p></li>
3353:
3354: <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>
3355:
3356: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3357: remaining steps asynchronously.</p></li>
3358:
3359: <li><p>Run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource
3360: fetch algorithm</a> with <var title="">absolute URL</var>. If
3361: that algorithm returns without aborting <em>this</em> one, then
3362: the load failed.</p></li>
3363:
3364: <li><p><i title="">Failed</i>: <a href="webappapis.html#queue-a-task">Queue a task</a> to
3365: <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
3366: obtain <var title="">candidate</var>'s corresponding <a href="#media-resource">media
3367: resource</a> in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3368: algorithm</a>.</p></li>
3369:
3370: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3371: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3372: steps of this algorithm until the algorithm says the
3373: <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
3374: marked with ⌛.)</p></li>
3375:
3376: <li><p>⌛ <a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's
3377: media-resource-specific text tracks</a>.</p></li>
3378:
3379: <li><p>⌛ <i title="">Find next candidate</i>: Let <var title="">candidate</var> be null.</p></li>
3380:
3381: <li><p>⌛ <i title="">Search loop</i>: If the node after
3382: <var title="">pointer</var> is the end of the list, then jump to
3383: the <i title="">waiting</i> step below.</p></li>
3384:
3385: <li><p>⌛ If the node after <var title="">pointer</var> is
3386: a <code><a href="#the-source-element">source</a></code> element, let <var title="">candidate</var>
3387: be that element.</p></li>
3388:
3389: <li><p>⌛ Advance <var title="">pointer</var> so that the
3390: node before <var title="">pointer</var> is now the node that was
3391: after <var title="">pointer</var>, and the node after <var title="">pointer</var> is the node after the node that used to be
3392: after <var title="">pointer</var>, if any.</p></li>
3393:
3394: <li><p>⌛ If <var title="">candidate</var> is null, jump
3395: back to the <i title="">search loop</i> step. Otherwise, jump
3396: back to the <i title="">process candidate</i> step.</p></li>
3397:
3398: <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
3399: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3400: value.</p></li>
3401:
3402: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3403: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3404: event">delaying the load event</a>.</p></li>
3405:
3406: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3407: remaining steps asynchronously.</p></li>
3408:
3409: <li><p>Wait until the node after <var title="">pointer</var> is a
3410: node other than the end of the list. (This step might wait
3411: forever.)</p></li>
3412:
3413: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3414: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3415: steps of this algorithm until the algorithm says the
3416: <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
3417: marked with ⌛.)</p></li>
3418:
3419: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3420: flag</a> back to true (this <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3421: event">delays the load event</a> again, in case it hasn't been
3422: fired yet).</p>
3423:
3424: </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>
3425:
3426: <li><p>⌛ Jump back to the <i title="">find next
3427: candidate</i> step above.</p></li>
3428:
3429: </ol></li>
3430:
3431: </ol><p>The <dfn id="concept-media-load-resource" title="concept-media-load-resource">resource fetch
3432: algorithm</dfn> for a <a href="#media-element">media element</a> and a given
3433: <a href="urls.html#absolute-url">absolute URL</a> is as follows:</p>
3434:
3435: <ol><li><p>Let the <var title="">current media resource</var> be the
3436: resource given by the <a href="urls.html#absolute-url">absolute URL</a> passed to this
3437: algorithm. This is now the element's <a href="#media-resource">media
3438: resource</a>.</p></li>
3439:
1.84 mike 3440: <li><p>Optionally, run the following substeps. This is the expected
3441: behavior if the user agent intends to not attempt to fetch the
3442: resource until the use requests it explicitly (e.g. as a way to
3443: implement the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>
3444: attribute's <code title="attr-media-preload-none"><a href="#attr-media-preload-none">none</a></code>
3445: keyword).</p>
3446:
3447: <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>
3448:
3449: <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
3450: event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the
3451: element.</p></li>
3452:
1.109 mike 3453: <li><p>Wait for the task to be run.</p></li>
3454:
1.84 mike 3455: <li><p>Wait for an implementation-defined event (e.g. the user
3456: requesting that the media element begin playback).</p></li>
3457:
3458: <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>
3459:
3460: </ol></li>
3461:
1.47 mike 3462: <li>
3463:
1.61 mike 3464: <p>Perform a <a href="fetching-resources.html#potentially-cors-enabled-fetch">potentially CORS-enabled fetch</a> of the
3465: <var title="">current media resource</var>'s <a href="urls.html#absolute-url">absolute
3466: URL</a>, with the <i>mode</i> being the state of the
3467: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
1.128 mike 3468: attribute, the <i title="">origin</i> being the <a href="origin-0.html#origin">origin</a> of the
1.61 mike 3469: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
3470: <i>default origin behaviour</i> set to <i>taint</i>.</p>
3471:
3472: <p>The resource obtained in this fashion, if any, contains the
3473: <a href="#media-data">media data</a>. It can be <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>
3474: or <a href="fetching-resources.html#cors-cross-origin">CORS-cross-origin</a>; this affects whether subtitles
3475: referenced in the <a href="#media-data">media data</a> are exposed in the API
3476: and, for <code><a href="#the-video-element">video</a></code> elements, whether a
3477: <code><a href="the-canvas-element.html#the-canvas-element">canvas</a></code> gets tainted when the video is drawn on
3478: it.</p>
3479:
1.109 mike 3480: <p>While the load is not suspended (see below), every 350ms
3481: (±200ms) or for every byte received, whichever is
3482: <em>least</em> frequent, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
3483: simple event</a> named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the element.</p>
1.47 mike 3484:
3485: <p>The <dfn id="stall-timeout">stall timeout</dfn> is a user-agent defined length of
3486: time, which should be about three seconds. When a <a href="#media-element">media
3487: element</a> that is actively attempting to obtain <a href="#media-data">media
3488: data</a> has failed to receive any data for a duration equal to
3489: the <a href="#stall-timeout">stall timeout</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a
3490: 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>
3491:
3492: <p>User agents may allow users to selectively block or slow
3493: <a href="#media-data">media data</a> downloads. When a <a href="#media-element">media
3494: element</a>'s download has been blocked altogether, the user
3495: agent must act as if it was stalled (as opposed to acting as if
3496: the connection was closed). The rate of the download may also be
3497: throttled automatically by the user agent, e.g. to balance the
3498: download with other connections sharing the same bandwidth.</p>
3499:
1.109 mike 3500: <p id="resourceSuspend">User agents may decide to not download
3501: more content at any time, e.g. after buffering five minutes of a
3502: one hour media resource, while waiting for the user to decide
3503: whether to play the resource or not, or while waiting for user
3504: input in an interactive resource. When a <a href="#media-element">media
3505: element</a>'s download has been suspended, the user agent must
3506: <a href="webappapis.html#queue-a-task">queue a task</a> to set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> and <a href="webappapis.html#fire-a-simple-event">fire
3507: a simple event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the element. If and
3508: when downloading of the resource resumes, the user agent must
3509: <a href="webappapis.html#queue-a-task">queue a task</a> to set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>. Between
3510: the queuing of these tasks, the load is suspended (so <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> events don't fire, as
3511: described above).</p>
1.47 mike 3512:
3513: <p class="note">The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute provides a
3514: hint regarding how much buffering the author thinks is advisable,
3515: even in the absence of the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute.</p>
3516:
3517: <p>When a user agent decides to completely stall a download,
3518: e.g. if it is waiting until the user starts playback before
3519: downloading any further content, the element's
3520: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> must be set to
1.101 mike 3521: false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the
1.47 mike 3522: load event</a>.</p>
3523:
3524: <p>The user agent may use whatever means necessary to fetch the
3525: resource (within the constraints put forward by this and other
3526: specifications); for example, reconnecting to the server in the
3527: face of network errors, using HTTP range retrieval requests, or
3528: switching to a streaming protocol. The user agent must consider a
3529: resource erroneous only if it has given up trying to fetch it.</p>
3530:
3531: <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
3532: being fetched must, when appropriate, include the relevant
3533: substeps from the following list:</p>
3534:
3535: <dl class="switch"><dt>If the <a href="#media-data">media data</a> cannot be fetched at all, due
3536: to network errors, causing the user agent to give up trying to
3537: fetch the resource</dt>
3538:
3539: <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
3540: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3541: described by the <code title="">codecs</code> parameter, if the
3542: parameter is defined for that type), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3543: the user agent knows it cannot render</a> (even if the actual
3544: <a href="#media-data">media data</a> is in a supported format)</dt>
3545:
3546: <dt>If the <a href="#media-data">media data</a> can be fetched but is found by
3547: inspection to be in an unsupported format, or can otherwise not
3548: be rendered at all</dt>
3549:
3550: <dd>
3551:
3552: <p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in
3553: other protocols), and other fatal network errors that occur
3554: before the user agent has established whether the <var title="">current media resource</var> is usable, as well as
3555: the file using an unsupported container format, or using
3556: unsupported codecs for all the data, must cause the user agent
3557: to execute the following steps:</p>
3558:
3559: <ol><li><p>The user agent should cancel the fetching
3560: process.</p></li>
3561:
3562: <li><p>Abort this subalgorithm, returning to the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3563: algorithm</a>.</p>
3564:
3565: </li></ol></dd>
3566:
3567:
3568:
3569:
3570:
1.122 mike 3571: <dt id="found-another-audio-track">If the <a href="#media-resource">media
3572: resource</a> is found to have an audio track</dt>
3573:
3574: <dd>
3575:
3576: <ol><li><p>Create a <code><a href="#audiotrack">AudioTrack</a></code> object to represent the
3577: audio track.</p></li>
3578:
3579: <li><p>Update the <a href="#media-element">media element</a>'s <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code> attribute's
3580: <code><a href="#audiotracklist">AudioTrackList</a></code> object with the new
3581: <code><a href="#audiotrack">AudioTrack</a></code> object.</p></li>
3582:
3583: <li><p>Fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and
3584: is not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
3585: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized
3586: to the new <code><a href="#audiotrack">AudioTrack</a></code> object, at this
3587: <code><a href="#audiotracklist">AudioTrackList</a></code> object.</p></li>
3588:
3589: </ol></dd>
3590:
3591:
3592: <dt id="found-another-video-track">If the <a href="#media-resource">media
3593: resource</a> is found to have a video track</dt>
3594:
3595: <dd>
3596:
3597: <ol><li><p>Create a <code><a href="#videotrack">VideoTrack</a></code> object to represent the
3598: video track.</p></li>
3599:
3600: <li><p>Update the <a href="#media-element">media element</a>'s <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attribute's
3601: <code><a href="#videotracklist">VideoTrackList</a></code> object with the new
3602: <code><a href="#videotrack">VideoTrack</a></code> object.</p></li>
3603:
3604: <li><p>Fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and
3605: is not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
3606: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized
3607: to the new <code><a href="#videotrack">VideoTrack</a></code> object, at this
3608: <code><a href="#videotracklist">VideoTrackList</a></code> object.</p></li>
3609:
3610: </ol></dd>
3611:
3612:
1.47 mike 3613: <dt id="getting-media-metadata">Once enough of the <a href="#media-data">media
3614: data</a> has been fetched to determine the duration of the
1.116 mike 3615: <a href="#media-resource">media resource</a>, its dimensions, and other metadata,
3616: and once <a href="#the-text-tracks-are-ready">the text tracks are ready</a> </dt>
1.47 mike 3617:
3618: <dd>
3619:
3620: <p>This indicates that the resource is usable. The user agent
3621: must follow these substeps:</p>
3622:
3623: <ol><li>
3624:
3625: <p><a href="#defineTimeline">Establish the media timeline</a> for the purposes
3626: of the <a href="#current-playback-position">current playback position</a>, the
3627: <a href="#earliest-possible-position">earliest possible position</a>, and the <a href="#initial-playback-position">initial
3628: playback position</a>, based on the <a href="#media-data">media
3629: data</a>.</p>
3630:
3631: </li>
3632:
3633: <li>
3634:
3635: <p>Update the <a href="#timeline-offset">timeline offset</a> to the date and
3636: time that corresponds to the zero time in the <a href="#media-timeline">media
3637: timeline</a> established in the previous step, if any. If
3638: no explicit time and date is given by the <a href="#media-resource">media
3639: resource</a>, the <a href="#timeline-offset">timeline offset</a> must be set
3640: to Not-a-Number (NaN).</p>
3641:
3642: </li>
3643:
1.107 mike 3644: <li><p>Set the <a href="#current-playback-position">current playback position</a> and the
3645: <a href="#official-playback-position">official playback position</a> to the <a href="#earliest-possible-position">earliest
3646: possible position</a>.</p></li>
1.47 mike 3647:
3648: <li>
3649:
3650: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3651: attribute with the time of the last frame of the resource, if
3652: known, on the <a href="#media-timeline">media timeline</a> established above.
3653: If it is not known (e.g. a stream that is in principle
3654: infinite), update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute to the
3655: value positive Infinity.</p>
3656:
3657: <p class="note">The user agent <a href="#durationChange">will</a> <a href="webappapis.html#queue-a-task">queue a task</a> to
3658: <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
3659: element at this point.</p>
3660:
3661: </li>
3662:
3663: <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>
3664: attributes.</p></li>
3665:
3666: <li>
3667:
3668: <p>Set the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to
3669: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>.</p>
3670:
3671: <p class="note">A <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> DOM
3672: event <a href="#fire-loadedmetadata">will be fired</a> as part
3673: of setting the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to a
3674: new value.</p>
3675:
3676:
3677:
3678: </li>
3679:
3680: <li><p>Let <var title="">jumped</var> be false.</p></li>
3681:
1.116 mike 3682: <li><p>If the <a href="#media-element">media element</a>'s <a href="#default-playback-start-position">default playback
3683: start position</a> is greater than zero, then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to that time, and let <var title="">jumped</var> be true.</p></li>
3684:
3685: <li><p>Let the <a href="#media-element">media element</a>'s <a href="#default-playback-start-position">default playback
3686: start position</a> be zero.</p></li>
3687:
1.47 mike 3688: <li>
3689:
3690: <p>If either the <a href="#media-resource">media resource</a> or the address of
3691: the <var title="">current media resource</var> indicate a
3692: particular start time, then set the <a href="#initial-playback-position">initial playback
1.116 mike 3693: position</a> to that time and, if <var title="">jumped</var> is still false, <a href="#dom-media-seek" title="dom-media-seek">seek</a> to that time and let <var title="">jumped</var> be true.</p>
1.47 mike 3694:
3695: <p class="example">For example, with media formats that
3696: support the <cite>Media Fragments URI</cite> fragment
3697: identifier syntax, the fragment identifier can be used to
1.101 mike 3698: indicate a start position. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 3699:
3700: </li>
3701:
1.74 mike 3702: <li>
3703:
3704: <p>If either the <a href="#media-resource">media resource</a> or the address of
3705: the <var title="">current media resource</var> indicate a
3706: particular set of audio or video tracks to enable, then the
3707: 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,
3708: of the selected video tracks, the one that is listed first in
3709: the element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> object must
3710: be selected.</p>
3711:
3712: </li>
1.47 mike 3713:
3714: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
3715: media controller</a>, then: if <var title="">jumped</var> is
3716: true and the <a href="#initial-playback-position">initial playback position</a>, relative
3717: to the <a href="#current-media-controller">current media controller</a>'s timeline, is
3718: greater than the <a href="#current-media-controller">current media controller</a>'s
3719: <a href="#media-controller-position">media controller position</a>, then <a href="#seek-the-media-controller">seek the
3720: media controller</a> to the <a href="#media-element">media element</a>'s
3721: <a href="#initial-playback-position">initial playback position</a>, relative to the
3722: <a href="#current-media-controller">current media controller</a>'s timeline; otherwise,
3723: <a href="#dom-media-seek" title="dom-media-seek">seek</a> the <a href="#media-element">media
3724: element</a> to the <a href="#media-controller-position">media controller position</a>,
1.107 mike 3725: relative to the <a href="#media-element">media element</a>'s timeline.</p></li>
3726:
1.116 mike 3727: </ol><p>Once the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
3728: reaches <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
3729: <a href="#fire-loadeddata">after the <code title="event-media-loadeddata">loadeddata</code> event has been
3730: fired</a>, set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3731: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3732: event">delaying the load event</a>.</p>
3733:
3734: <p class="note">A user agent that is attempting to reduce
3735: network usage while still fetching the metadata for each
3736: <a href="#media-resource">media resource</a> would also stop buffering at this
3737: point, following <a href="#resourceSuspend">the rules
3738: described previously</a>, which involve the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute
3739: switching to the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> value and a
3740: <code title="event-suspend">suspend</code> event firing.</p>
1.47 mike 3741:
1.116 mike 3742: <p class="note">The user agent is <em>required</em> to
1.47 mike 3743: determine the duration of the <a href="#media-resource">media resource</a> and
3744: go through this step before playing.</p>
3745: </dd>
3746:
3747:
3748: <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
3749: has been decoded)</dt>
3750:
3751: <dd>
3752:
1.116 mike 3753: <p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the <a href="#media-element">media
3754: element</a>.</p>
1.47 mike 3755:
1.116 mike 3756: <p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> and
1.109 mike 3757: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the <a href="#media-element">media
1.108 mike 3758: element</a>.</p>
3759:
1.109 mike 3760: <p>If the user agent ever discards any <a href="#media-data">media data</a>
3761: and then needs to resume the network activity to obtain it
1.116 mike 3762: again, then it must <a href="webappapis.html#queue-a-task">queue a task</a> to set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p>
1.109 mike 3763:
3764: <p class="note">If the user agent can keep the <a href="#media-resource">media
3765: resource</a> loaded, then the algorithm will continue to its
3766: final step below, which aborts the algorithm.</p>
1.47 mike 3767: </dd>
3768:
3769:
1.116 mike 3770: <dt>If the connection is interrupted after some <a href="#media-data">media
3771: data</a> has been received, causing the user agent to give up
3772: trying to fetch the resource</dt>
1.47 mike 3773:
3774: <dd>
3775:
3776: <p>Fatal network errors that occur after the user agent has
3777: established whether the <var title="">current media
1.84 mike 3778: resource</var> is usable (i.e. once the <a href="#media-element">media
3779: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is no
3780: longer <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>)
3781: must cause the user agent to execute the following steps:</p>
1.47 mike 3782:
3783: <ol><li><p>The user agent should cancel the fetching
3784: process.</p></li>
3785:
3786: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3787: 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
3788: <code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code>.</p></li>
3789:
1.116 mike 3790: <li><p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code> at the <a href="#media-element">media
3791: element</a>.</p></li>
1.47 mike 3792:
1.84 mike 3793: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3794: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3795: value.</p></li>
3796:
3797: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3798: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3799: event">delaying the load event</a>.</p></li>
3800:
3801: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3802: algorithm</a>.</p></li>
3803:
3804: </ol></dd>
3805:
3806:
3807: <dt id="fatal-decode-error">If the <a href="#media-data">media data</a> is
3808: corrupted</dt>
3809:
3810: <dd>
3811:
3812: <p>Fatal errors in decoding the <a href="#media-data">media data</a> that
3813: occur after the user agent has established whether the <var title="">current media resource</var> is usable must cause the
3814: user agent to execute the following steps:</p>
3815:
3816: <ol><li><p>The user agent should cancel the fetching
3817: process.</p></li>
3818:
3819: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3820: 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
3821: <code title="dom-MediaError-MEDIA_ERR_DECODE"><a href="#dom-mediaerror-media_err_decode">MEDIA_ERR_DECODE</a></code>.</p></li>
3822:
1.116 mike 3823: <li><p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code> at the <a href="#media-element">media
3824: element</a>.</p></li>
1.47 mike 3825:
3826: <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
3827: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3828: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3829: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
1.116 mike 3830: value and <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the element.
3831: Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3832: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3833: value.</p></li>
3834:
3835: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3836: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3837: event">delaying the load event</a>.</p></li>
3838:
3839: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3840: algorithm</a>.</p></li>
3841:
3842: </ol></dd>
3843:
3844:
3845: <dt>If the <a href="#media-data">media data</a> fetching process is aborted by
3846: the user</dt>
3847:
3848: <dd>
3849:
3850: <p>The fetching process is aborted by the user, e.g. because the
3851: user navigated the browsing context to another page, the user
3852: agent must execute the following steps. These steps are not
3853: followed if the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code>
3854: method itself is invoked while these steps are running, as the
3855: steps above handle that particular kind of abort.</p>
3856:
3857: <ol><li><p>The user agent should cancel the fetching
3858: process.</p></li>
3859:
3860: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3861: 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
3862: <code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.</p></li>
3863:
1.116 mike 3864: <li><p><a href="webappapis.html#fire-a-simple-event">Fire a simple event</a> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code> at the <a href="#media-element">media
3865: element</a>.</p></li>
1.47 mike 3866:
3867: <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
3868: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3869: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3870: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
1.116 mike 3871: value and <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the element.
3872: Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
1.47 mike 3873: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3874: value.</p></li>
3875:
3876: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
1.101 mike 3877: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
1.47 mike 3878: event">delaying the load event</a>.</p></li>
3879:
3880: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3881: algorithm</a>.</p></li>
3882:
3883: </ol></dd>
3884:
3885:
3886: <dt id="non-fatal-media-error">If the <a href="#media-data">media data</a> can
3887: be fetched but has non-fatal errors or uses, in part, codecs that
3888: are unsupported, preventing the user agent from rendering the
3889: content completely correctly but not preventing playback
3890: altogether</dt>
3891:
3892: <dd>
3893:
3894: <p>The server returning data that is partially usable but cannot
3895: be optimally rendered must cause the user agent to render just
3896: the bits it can handle, and ignore the rest.</p>
3897:
3898:
3899:
3900: </dd>
3901:
3902:
1.116 mike 3903: <dt id="found-a-media-resource-specific-timed-track">If the
3904: <a href="#media-resource">media resource</a> is found to declare a
3905: <a href="#media-resource-specific-text-track">media-resource-specific text track</a> that the user
3906: agent supports</dt>
1.47 mike 3907:
3908: <dd>
3909:
1.61 mike 3910: <p>If the <a href="#media-data">media data</a> is
1.116 mike 3911: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>, run the <a href="#steps-to-expose-a-media-resource-specific-text-track">steps to expose a
3912: media-resource-specific text track</a> with the relevant
3913: data.</p>
1.61 mike 3914:
3915: <p class="note">Cross-origin videos do not expose their
3916: subtitles, since that would allow attacks such as hostile sites
3917: reading subtitles from confidential videos on a user's
3918: intranet.</p>
1.47 mike 3919:
3920: </dd>
3921:
3922: </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>
3923: (i.e. once the download has completed), if the fetching process
3924: completes without errors, including decoding the media data, and
3925: if all of the data is available to the user agent without network
3926: access, then, the user agent must move on to the next step. This
3927: might never happen, e.g. when streaming an infinite resource such
3928: as Web radio, or if the resource is longer than the user agent's
3929: ability to cache data.</p>
3930:
3931: <p>While the user agent might still need network access to obtain
3932: parts of the <a href="#media-resource">media resource</a>, the user agent must
3933: remain on this step.</p>
3934:
3935: <p class="example">For example, if the user agent has discarded
3936: the first half of a video, the user agent will remain at this step
3937: even once the <a href="#ended-playback" title="ended playback">playback has
3938: ended</a>, because there is always the chance the user will
3939: seek back to the start. In fact, in this situation, once <a href="#ended-playback" title="ended playback">playback has ended</a>, the user agent
1.116 mike 3940: will end up firing a <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> event, as described
1.47 mike 3941: earlier.</p>
3942:
3943: </li>
3944:
1.109 mike 3945:
1.47 mike 3946: <li><p>If the user agent ever reaches this step (which can only
3947: happen if the entire resource gets loaded and kept available):
3948: abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3949: algorithm</a>.</p></li>
3950:
3951: </ol></div><hr><p>The <dfn id="attr-media-preload" title="attr-media-preload"><code>preload</code></dfn>
3952: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following table
3953: lists the keywords and states for the attribute — the keywords
3954: in the left column map to the states in the cell in the second
3955: column on the same row as the keyword.</p><table><thead><tr><th> Keyword
3956: </th><th> State
3957: </th><th> Brief description
3958: </th></tr></thead><tbody><tr><td><dfn id="attr-media-preload-none" title="attr-media-preload-none"><code>none</code></dfn>
3959: </td><td><dfn id="attr-media-preload-none-state" title="attr-media-preload-none-state">None</dfn>
3960: </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.
3961: </td></tr><tr><td><dfn id="attr-media-preload-metadata" title="attr-media-preload-metadata"><code>metadata</code></dfn>
3962: </td><td><dfn id="attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</dfn>
1.62 mike 3963: </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 3964: </td></tr><tr><td><dfn id="attr-media-preload-auto" title="attr-media-preload-auto"><code>auto</code></dfn>
3965: </td><td><dfn id="attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</dfn>
3966: </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.
3967: </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
3968: attribute's <i>missing value default</i> is user-agent defined,
3969: though the <a href="#attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</a> state is
3970: suggested as a compromise between reducing server load and providing
3971: an optimal user experience.</p><div class="impl">
3972:
3973: <p>The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute is
3974: intended to provide a hint to the user agent about what the author
3975: thinks will lead to the best user experience. The attribute may be
3976: ignored altogether, for example based on explicit user preferences
3977: or based on the available connectivity.</p>
3978:
3979: <p>The <dfn id="dom-media-preload" title="dom-media-preload"><code>preload</code></dfn> IDL
3980: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
3981: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
3982:
3983: </div><p class="note">The <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute can override
3984: the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute (since
3985: if the media plays, it naturally has to buffer first, regardless of
3986: the hint given by the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute). Including
3987: 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>
3988:
3989: <dd>
3990:
3991: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
3992: ranges of the <a href="#media-resource">media resource</a> that the user agent has
3993: buffered.</p>
3994:
3995: </dd>
3996:
3997: </dl><div class="impl">
3998:
3999: <p>The <dfn id="dom-media-buffered" title="dom-media-buffered"><code>buffered</code></dfn>
4000: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4001: <code>TimeRanges</code> object</a> that represents the ranges of
4002: the <a href="#media-resource">media resource</a>, if any, that the user agent has
4003: buffered, at the time the attribute is evaluated. Users agents must
4004: accurately determine the ranges available, even for media streams
4005: where this can only be determined by tedious inspection.</p>
4006:
4007: <p class="note">Typically this will be a single range anchored at
4008: the zero point, but if, e.g. the user agent uses HTTP range requests
4009: in response to seeking, then there could be multiple ranges.</p>
4010:
4011: <p>User agents may discard previously buffered data.</p>
4012:
4013: <p class="note">Thus, a time position included within a range of the
4014: objects return by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code> attribute at one time can
4015: end up being not included in the range(s) of objects returned by the
4016: same attribute at later times.</p>
4017:
4018: </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>
4019:
4020: <dd>
4021:
4022: <p>Returns the length of the <a href="#media-resource">media resource</a>, in
4023: seconds, assuming that the start of the <a href="#media-resource">media
4024: resource</a> is at time zero.</p>
4025:
4026: <p>Returns NaN if the duration isn't available.</p><p>
4027:
4028: </p><p>Returns Infinity for unbounded streams.</p>
4029:
4030: </dd>
4031:
4032: <dt><var title="">media</var> . <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
4033:
4034: <dd>
4035:
1.107 mike 4036: <p>Returns the <a href="#official-playback-position">official playback position</a>, in seconds.</p>
1.47 mike 4037:
4038: <p>Can be set, to seek to the given time.</p><p>
4039:
1.119 mike 4040: </p><p>Will throw an <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception if there
1.47 mike 4041: is no selected <a href="#media-resource">media resource</a>
1.71 mike 4042: or if there is a <a href="#current-media-controller">current media controller</a>.</p>
1.47 mike 4043:
4044: </dd>
4045:
4046: <dt><var title="">media</var> . <code title="dom-media-initialTime"><a href="#dom-media-initialtime">initialTime</a></code></dt>
4047:
4048: <dd>
4049:
4050: <p>Returns the <a href="#initial-playback-position">initial playback position</a>, that is, time
4051: to which the <a href="#media-resource">media resource</a> was automatically seeked
4052: when it was loaded. Returns zero if the <a href="#initial-playback-position">initial playback
4053: position</a> is still unknown.</p>
4054:
4055: </dd>
4056:
4057: </dl><div class="impl">
4058:
4059: <p>A <a href="#media-resource">media resource</a> has a <dfn id="media-timeline">media timeline</dfn>
4060: that maps times (in seconds) to positions in the <a href="#media-resource">media
4061: resource</a>. The origin of a timeline is its earliest defined
4062: position. The duration of a timeline is its last defined
4063: position.</p>
4064:
4065: <p><dfn id="defineTimeline" title="establish the media
4066: timeline">Establishing the media timeline</dfn>: If the <a href="#media-resource">media
4067: resource</a> somehow specifies an explicit timeline whose origin
4068: is not negative, then the <a href="#media-timeline">media timeline</a> should be that
4069: timeline. (Whether the <a href="#media-resource">media resource</a> can specify a
4070: timeline or not depends on the <a href="#media-resource" title="media resource">media
4071: resource's</a> format.) If the <a href="#media-resource">media resource</a>
4072: specifies an explicit start time <em>and date</em>, then that time
4073: and date should be considered the zero point in the <a href="#media-timeline">media
4074: timeline</a>; the <a href="#timeline-offset">timeline offset</a> will be the time
4075: and date, exposed using the <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
4076: attribute.</p>
4077:
4078: <p>If the <a href="#media-resource">media resource</a> has a discontinuous timeline,
4079: the user agent must extend the timeline used at the start of the
4080: resource across the entire resource, so that the <a href="#media-timeline">media
4081: timeline</a> of the <a href="#media-resource">media resource</a> increases
4082: linearly starting from the <a href="#earliest-possible-position">earliest possible position</a>
4083: (as defined below), even if the underlying <a href="#media-data">media data</a>
4084: has out-of-order or even overlapping time codes.</p>
4085:
4086: <p class="example">For example, if two clips have been concatenated
4087: into one video file, but the video format exposes the original times
4088: for the two clips, the video data might expose a timeline that goes,
4089: say, 00:15..00:29 and then 00:05..00:38. However, the user agent
4090: would not expose those times; it would instead expose the times as
4091: 00:15..00:29 and 00:29..01:02, as a single video.</p>
4092:
4093: <p>In the absence of an explicit timeline, the zero time on the
4094: <a href="#media-timeline">media timeline</a> should correspond to the first frame of
4095: the <a href="#media-resource">media resource</a>. For static audio and video files
4096: this is generally trivial. For streaming resources, if the user
4097: agent will be able to seek to an earlier point than the first frame
4098: originally provided by the server, then the zero time should
4099: correspond to the earliest seekable time of the <a href="#media-resource">media
4100: resource</a>; otherwise, it should correspond to the first frame
4101: received from the server (the point in the <a href="#media-resource">media
4102: resource</a> at which the user agent began receiving the
4103: stream).</p>
4104:
4105: <p class="example">Another example would be a stream that carries a
4106: video with several concatenated fragments, broadcast by a server
4107: that does not allow user agents to request specific times but
4108: instead just streams the video data in a predetermined order. If a
4109: user agent connects to this stream and receives fragments defined as
4110: covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
4111: UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
4112: expose this with a <a href="#media-timeline">media timeline</a> starting at 0s and
4113: extending to 3,600s (one hour). Assuming the streaming server
4114: 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
4115: return 3,600. The <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code> attribute
4116: would return a <code>Date</code> object with a time corresponding to
4117: 2010-03-20 23:15:00 UTC. However, if a different user agent
4118: connected five minutes later, <em>it</em> would (presumably) receive
4119: fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
4120: 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
4121: and would expose this with a <a href="#media-timeline">media timeline</a> starting at
4122: 0s and extending to 3,300s (fifty five minutes). In this case, the
4123: <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
4124: attribute would return a <code>Date</code> object with a time
4125: corresponding to 2010-03-20 23:20:00 UTC.</p>
4126:
4127: <p>In any case, the user agent must ensure that the <a href="#earliest-possible-position">earliest
4128: possible position</a> (as defined below) using the established
4129: <a href="#media-timeline">media timeline</a>, is greater than or equal to zero.</p>
4130:
4131: <p>The <a href="#media-timeline">media timeline</a> also has an associated clock.
4132: Which clock is used is user-agent defined, and may be <a href="#media-resource">media
4133: resource</a>-dependent, but it should approximate the user's wall
4134: clock.</p>
4135:
4136: <p class="note">All the <a href="#media-element" title="media element">media
4137: elements</a> that share <a href="#current-media-controller">current media controller</a> use
4138: the same clock for their <a href="#media-timeline">media timeline</a>.</p>
4139:
4140: <p><a href="#media-element" title="media element">Media elements</a> have a
4141: <dfn id="current-playback-position">current playback position</dfn>, which must initially (i.e. in
4142: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4143: <a href="#current-playback-position">current playback position</a> is a time on the <a href="#media-timeline">media
4144: timeline</a>.</p>
4145:
1.107 mike 4146: <p><a href="#media-element" title="media element">Media elements</a> also have an
4147: <dfn id="official-playback-position">official playback position</dfn>, which must initially be set
4148: to zero seconds. The <a href="#official-playback-position">official playback position</a> is an
4149: approximation of the <a href="#current-playback-position">current playback position</a>
4150: that is kept stable while scripts are running.</p>
4151:
1.116 mike 4152: <p><a href="#media-element" title="media element">Media elements</a> also have a
4153: <dfn id="default-playback-start-position">default playback start position</dfn>, which must initially be
4154: set to zero seconds. This time is used to allow the element to be
4155: seeked even before the media is loaded.</p>
4156:
1.47 mike 4157: <p>The <dfn id="dom-media-currenttime" title="dom-media-currentTime"><code>currentTime</code></dfn>
1.116 mike 4158: attribute must, on getting, return the <a href="#media-element">media element</a>'s
4159: <a href="#default-playback-start-position">default playback start position</a>, unless that is zero,
4160: in which case it must return the element's <a href="#official-playback-position">official playback
4161: position</a>. The returned value must be expressed in seconds. On
4162: setting, if the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
1.107 mike 4163: controller</a>, then the user agent must throw an
1.119 mike 4164: <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception; otherwise, if the
1.116 mike 4165: <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then it must set
4166: the <a href="#media-element">media element</a>'s <a href="#default-playback-start-position">default playback start
4167: position</a> to the new value; otherwise, it must set the
4168: <a href="#official-playback-position">official playback position</a> to the new value and then
4169: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the new value. The new
4170: value must be interpreted as being in seconds.</p>
1.47 mike 4171:
4172: <p><a href="#media-element" title="media element">Media elements</a> have an
4173: <dfn id="initial-playback-position">initial playback position</dfn>, which must initially (i.e. in
4174: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4175: <a href="#initial-playback-position">initial playback position</a> is updated when a <a href="#media-resource">media
4176: resource</a> is loaded. The <a href="#initial-playback-position">initial playback
4177: position</a> is a time on the <a href="#media-timeline">media timeline</a>.</p>
4178:
1.50 mike 4179: <p>The <dfn id="dom-media-initialtime" title="dom-media-initialTime"><code>initialTime</code></dfn>
1.47 mike 4180: attribute must, on getting, return the <a href="#initial-playback-position">initial playback
4181: position</a>, expressed in seconds.</p>
4182:
4183: <p>If the <a href="#media-resource">media resource</a> is a streaming resource, then
4184: the user agent might be unable to obtain certain parts of the
4185: resource after it has expired from its buffer. Similarly, some <a href="#media-resource" title="media resource">media resources</a> might have a
4186: <a href="#media-timeline">media timeline</a> that doesn't start at zero. The
4187: <dfn id="earliest-possible-position">earliest possible position</dfn> is the earliest position in
4188: the stream or resource that the user agent can ever obtain
4189: again. It is also a time on the <a href="#media-timeline">media timeline</a>.</p>
4190:
4191: <p class="note">The <a href="#earliest-possible-position">earliest possible position</a> is not
4192: explicitly exposed in the API; it corresponds to the start time of
4193: the first range in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute's
4194: <code><a href="#timeranges">TimeRanges</a></code> object, if any, or the <a href="#current-playback-position">current
4195: playback position</a> otherwise.</p>
4196:
4197: <p>When the <a href="#earliest-possible-position">earliest possible position</a> changes, then:
4198: if the <a href="#current-playback-position">current playback position</a> is before the
4199: <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
4200: 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
4201: element in the past 15 to 250ms and is not still running event
4202: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4203: 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>
4204:
4205: <p class="note">Because of the above requirement and the requirement
4206: in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
4207: algorithm</a> that kicks in <a href="#getting-media-metadata">when the metadata of the clip becomes
4208: known</a>, the <a href="#current-playback-position">current playback position</a> can never be
4209: less than the <a href="#earliest-possible-position">earliest possible position</a>.</p>
4210:
4211: <p>The <dfn id="dom-media-duration" title="dom-media-duration"><code>duration</code></dfn>
4212: attribute must return the time of the end of the <a href="#media-resource">media
4213: resource</a>, in seconds, on the <a href="#media-timeline">media timeline</a>. If
4214: no <a href="#media-data">media data</a> is available, then the attributes must
4215: return the Not-a-Number (NaN) value. If the <a href="#media-resource">media
1.62 mike 4216: resource</a> is not known to be bounded (e.g. streaming radio, or
4217: a live event with no announced end time), then the attribute must
4218: return the positive Infinity value.</p>
1.47 mike 4219:
4220: <p>The user agent must determine the duration of the <a href="#media-resource">media
4221: resource</a> before playing any part of the <a href="#media-data">media
4222: data</a> and before setting <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> to a value equal to
4223: or greater than <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, even if doing
4224: so requires fetching multiple parts of the resource.</p>
4225:
4226: <p id="durationChange">When the length of the <a href="#media-resource">media
4227: resource</a> changes to a known value (e.g. from being unknown to
4228: known, or from a previously established length to a new length) the
4229: 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
4230: event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
4231: <a href="#media-element">media element</a>. (The event is not fired when the
1.63 mike 4232: duration is reset as part of loading a new media resource.) If the
4233: duration is changed such that the <a href="#current-playback-position">current playback
4234: position</a> ends up being greater than the time of the end of
4235: 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
4236: <a href="#media-resource">media resource</a>.</p>
1.47 mike 4237:
4238: <p class="example">If an "infinite" stream ends for some reason,
4239: then the duration would change from positive Infinity to the time of
4240: 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
4241: be fired. Similarly, if the user agent initially estimated the
4242: <a href="#media-resource">media resource</a>'s duration instead of determining it
4243: precisely, and later revises the estimate based on new information,
4244: then the duration would change and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
4245: be fired.</p>
4246:
4247: <p>Some video files also have an explicit date and time
4248: corresponding to the zero time in the <a href="#media-timeline">media timeline</a>,
4249: known as the <dfn id="timeline-offset">timeline offset</dfn>. Initially, the
4250: <a href="#timeline-offset">timeline offset</a> must be set to Not-a-Number (NaN).</p>
4251:
4252: <p>The <dfn id="dom-media-startoffsettime" title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
4253: attribute must return a new <code>Date</code> object representing
4254: the current <a href="#timeline-offset">timeline offset</a>.</p>
4255:
4256: </div><hr><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn>
4257: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that, if specified,
4258: indicates that the <a href="#media-element">media element</a> is to seek back to the
4259: 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
4260: effect while the element has a <a href="#current-media-controller">current media
4261: controller</a>.</p><div class="impl">
4262:
4263: <p>The <dfn id="dom-media-loop" title="dom-media-loop"><code>loop</code></dfn> IDL
4264: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4265: same name.</p>
4266:
1.65 mike 4267: </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 4268:
4269: <dd>
4270:
4271: <p>Returns a value that expresses the current state of the element
4272: with respect to rendering the <a href="#current-playback-position">current playback
4273: position</a>, from the codes in the list below.</p>
4274:
4275: </dd>
4276:
4277: </dl><div class="impl">
4278:
4279: <p><a href="#media-element" title="media element">Media elements</a> have a
4280: <i>ready state</i>, which describes to what degree they are ready
4281: to be rendered at the <a href="#current-playback-position">current playback position</a>. The
4282: possible values are as follows; the ready state of a media element
4283: at any particular time is the greatest value describing the state of
4284: the element:</p>
4285:
4286: </div><dl><dt><dfn id="dom-media-have_nothing" title="dom-media-HAVE_NOTHING"><code>HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
4287:
4288: <dd>No information regarding the <a href="#media-resource">media resource</a> is
4289: available. No data for the <a href="#current-playback-position">current playback position</a>
4290: is available. <a href="#media-element" title="media element">Media elements</a>
4291: whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code>
4292: attribute are set to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> are always in
4293: the <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>
4294: state.</dd>
4295:
4296: <dt><dfn id="dom-media-have_metadata" title="dom-media-HAVE_METADATA"><code>HAVE_METADATA</code></dfn> (numeric value 1)</dt>
4297:
4298: <dd>Enough of the resource has been obtained that the duration of
4299: the resource is available. In the case of a <code><a href="#the-video-element">video</a></code>
4300: element, the dimensions of the video are also available. The API
1.119 mike 4301: will no longer throw an exception when seeking. No <a href="#media-data">media
1.47 mike 4302: data</a> is available for the immediate <a href="#current-playback-position">current playback
4303: position</a>.
4304: The <a href="#text-track" title="text track">text tracks</a>
4305: are <a href="#the-text-tracks-are-ready" title="the text tracks are ready">ready</a>.
4306: </dd>
4307:
4308: <dt><dfn id="dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA"><code>HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
4309:
4310: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4311: is available, but either not enough data is available that the user
4312: agent could successfully advance the <a href="#current-playback-position">current playback
4313: position</a> in the <a href="#direction-of-playback">direction of playback</a> at all
4314: without immediately reverting to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4315: there is no more data to obtain in the <a href="#direction-of-playback">direction of
4316: playback</a>. For example, in video this corresponds to the user
1.62 mike 4317: agent having data from the current frame, but not the next frame,
4318: when the <a href="#current-playback-position">current playback position</a> is at the end of
4319: the current frame; and to when <a href="#ended-playback" title="ended
4320: playback">playback has ended</a>.</dd>
1.47 mike 4321:
4322: <dt><dfn id="dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA"><code>HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
4323:
4324: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4325: is available, as well as enough data for the user agent to advance
4326: the <a href="#current-playback-position">current playback position</a> in the <a href="#direction-of-playback">direction
4327: of playback</a> at least a little without immediately reverting
4328: to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
4329: state. For example, in video this corresponds to the user agent
1.62 mike 4330: having data for at least the current frame and the next frame when
4331: the <a href="#current-playback-position">current playback position</a> is at the instant in
4332: time between the two frames, or to the user agent having the video
4333: data for the current frame and audio data to keep playing at least
4334: a little when the <a href="#current-playback-position">current playback position</a> is in the
4335: 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
4336: <a href="#current-playback-position">current playback position</a> can never advance in this
4337: case.</dd>
1.47 mike 4338:
4339: <dt><dfn id="dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA"><code>HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
4340:
4341: <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
4342: are met, and, in addition, the user agent estimates that data is
4343: being fetched at a rate where the <a href="#current-playback-position">current playback
4344: position</a>, if it were to advance at the <a href="#effective-playback-rate">effective
4345: playback rate</a>, would not overtake the available data before
4346: playback reaches the end of the <a href="#media-resource">media resource</a>.</dd>
4347:
1.62 mike 4348: </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
4349: negligible. Really the only time the difference is relevant is when
4350: 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>,
4351: 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
4352: 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).
4353: Similarly, the difference between <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> (only
4354: 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
4355: this frame and the next) can be negligible (in the extreme, only one
4356: frame). The only time that distinction really matters is when a page
4357: provides an interface for "frame-by-frame" navigation.</p><div class="impl">
1.47 mike 4358:
4359: <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
4360: user agent must follow the steps given below:</p>
4361:
4362: <ol><li>
4363:
4364: <p>Apply the first applicable set of substeps from the following
4365: list:</p>
4366:
4367:
4368: <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
4369: ready state is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code></dt>
4370:
4371: <dd id="fire-loadedmetadata">
4372:
4373: <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>
4374: named <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> at the
4375: element.</p>
4376:
4377: <p class="note">Before this task is run, as part of the event
4378: loop mechanism, the rendering will have been updated to resize
4379: the <code><a href="#the-video-element">video</a></code> element if appropriate.</p>
4380:
4381: </dd>
4382:
4383:
4384:
4385: <dt id="handling-first-frame-available">If the previous ready state
4386: was <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and
4387: 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
4388: greater</dt>
4389:
4390: <dd>
4391:
4392: <p id="fire-loadeddata">If this is the first time this occurs for
4393: 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,
4394: 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
4395: simple event</a> named <code title="event-media-loadeddata"><a href="#event-media-loadeddata">loadeddata</a></code> at the element.</p>
4396:
4397: <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
4398: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>,
4399: then the relevant steps below must then be run also.</p>
4400:
4401: </dd>
4402:
4403:
4404: <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,
4405: 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
4406: less</dt>
4407:
4408: <dd>
4409:
4410: <p id="fire-waiting-when-waiting">If the <a href="#media-element">media
4411: element</a> was <a href="#potentially-playing">potentially playing</a> before its
4412: <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
4413: 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
4414: the element has not <a href="#ended-playback">ended playback</a>, and playback
4415: has not <a href="#stopped-due-to-errors">stopped due to errors</a>, and playback has not
4416: <a href="#paused-for-user-interaction">paused for user interaction</a>, the user agent must
4417: <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>
4418: named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at
4419: 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
4420: simple event</a> named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the element.</p>
4421:
4422: </dd>
4423:
4424:
4425: <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
4426: 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>
4427:
4428: <dd>
4429:
4430: <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
4431: simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>.</p>
4432:
4433: <p>If the element's <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4434: attribute is false, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
4435: 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>
4436:
4437: </dd>
4438:
4439:
4440: <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>
4441:
4442: <dd>
4443:
4444: <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
4445: 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
4446: a simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>, and, if the element's
4447: <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false,
4448: <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>
4449: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4450:
4451: <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
4452: <a href="#media-element">media element</a> has an <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute specified,
4453: and the <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s
4454: <a href="browsers.html#browsing-context">browsing context</a> did not have the <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed
4455: automatic features browsing context flag</a> set when the
4456: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent may also
4457: set the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute to
4458: false, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4459: event</a> named <code title="event-media-play"><a href="#event-media-play">play</a></code>, and
4460: <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>
4461: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4462:
4463: <p class="note">User agents do not need to support autoplay,
4464: and it is suggested that user agents honor user preferences on the
4465: matter. Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
4466: using script to force the video to play, so as to allow the user
4467: to override the behavior if so desired.</p>
4468:
4469: <p>In any case, the user agent must finally <a href="webappapis.html#queue-a-task">queue a
4470: 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>
4471:
4472: </dd>
4473:
4474: </dl></li>
4475:
4476: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4477: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4478: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4479: controller</a>.</p></li>
4480:
4481: </ol></div><p class="note">It is possible for the ready state of a media
4482: element to jump between these states discontinuously. For example,
4483: 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
4484: passing through the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> and
4485: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>
4486: states.</p><div class="impl">
4487:
4488: <p>The <dfn id="dom-media-readystate" title="dom-media-readyState"><code>readyState</code></dfn> IDL
4489: attribute must, on getting, return the value described above that
4490: describes the current ready state of the <a href="#media-element">media
4491: element</a>.</p>
4492:
4493: </div><p>The <dfn id="attr-media-autoplay" title="attr-media-autoplay"><code>autoplay</code></dfn>
4494: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When present, the
4495: user agent <span class="impl">(as described in the algorithm
4496: described herein)</span> will automatically begin playback of the
4497: <a href="#media-resource">media resource</a> as soon as it can do so without
4498: 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
4499: using script to trigger automatic playback, as this allows the user
4500: to override the automatic playback when it is not desired, e.g. when
4501: using a screen reader. Authors are also encouraged to consider not
4502: using the automatic playback behavior at all, and instead to let the
4503: user agent wait for the user to start playback explicitly.</p><div class="impl">
4504:
4505: <p>The <dfn id="dom-media-autoplay" title="dom-media-autoplay"><code>autoplay</code></dfn>
4506: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4507: same name.</p>
4508:
4509: </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>
4510:
4511: <dd>
4512:
4513: <p>Returns true if playback is paused; false otherwise.</p>
4514:
4515: </dd>
4516:
4517: <dt><var title="">media</var> . <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code></dt>
4518:
4519: <dd>
4520:
4521: <p>Returns true if playback has reached the end of the <a href="#media-resource">media resource</a>.</p>
4522:
4523: </dd>
4524:
4525: <dt><var title="">media</var> . <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
4526:
4527: <dd>
4528:
4529: <p>Returns the default rate of playback, for when the user is not
4530: fast-forwarding or reversing through the <a href="#media-resource">media
4531: resource</a>.</p>
4532:
4533: <p>Can be set, to change the default rate of playback.</p>
4534:
4535: <p>The default rate has no direct effect on playback, but if the
4536: user switches to a fast-forward mode, when they return to the
4537: normal playback mode, it is expected that the rate of playback
4538: will be returned to the default rate of playback.</p>
4539:
4540: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4541: the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
4542: attribute is ignored and the <a href="#current-media-controller">current media
4543: controller</a>'s <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code>
4544: is used instead.</p>
4545:
4546: </dd>
4547:
4548: <dt><var title="">media</var> . <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
4549:
4550: <dd>
4551:
4552: <p>Returns the current rate playback, where 1.0 is normal speed.</p>
4553:
4554: <p>Can be set, to change the rate of playback.</p>
4555:
4556: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4557: the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>
4558: attribute is ignored and the <a href="#current-media-controller">current media
4559: controller</a>'s <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> is
4560: used instead.</p>
4561:
4562: </dd>
4563:
4564: <dt><var title="">media</var> . <code title="dom-media-played"><a href="#dom-media-played">played</a></code></dt>
4565:
4566: <dd>
4567:
4568: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4569: ranges of the <a href="#media-resource">media resource</a> that the user agent has
4570: played.</p>
4571:
4572: </dd>
4573:
4574: <dt><var title="">media</var> . <code title="dom-media-play"><a href="#dom-media-play">play</a></code>()</dt>
4575:
4576: <dd>
4577:
4578: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4579: to false, loading the <a href="#media-resource">media resource</a> and beginning
4580: playback if necessary. If the playback had ended, will restart it
4581: from the start.</p>
4582:
4583: </dd>
4584:
4585: <dt><var title="">media</var> . <code title="dom-media-pause"><a href="#dom-media-pause">pause</a></code>()</dt>
4586:
4587: <dd>
4588:
4589: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4590: to true, loading the <a href="#media-resource">media resource</a> if necessary.</p>
4591:
4592: </dd>
4593:
4594: </dl><div class="impl">
4595:
4596: <p>The <dfn id="dom-media-paused" title="dom-media-paused"><code>paused</code></dfn>
4597: attribute represents whether the <a href="#media-element">media element</a> is
4598: paused or not. The attribute must initially be true.</p>
4599:
4600: <p>A <a href="#media-element">media element</a> is a <dfn id="blocked-media-element">blocked media
4601: element</dfn> if its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is in the
1.62 mike 4602: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> state, the
4603: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4604: the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> state,
4605: or if the element has <a href="#paused-for-user-interaction">paused for user interaction</a>.</p>
1.47 mike 4606:
4607: <p>A <a href="#media-element">media element</a> is said to be <dfn id="potentially-playing">potentially
4608: playing</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4609: attribute is false, the element has not <a href="#ended-playback">ended playback</a>,
4610: playback has not <a href="#stopped-due-to-errors">stopped due to errors</a>,
4611: the element either has no <a href="#current-media-controller">current media controller</a> or
4612: has a <a href="#current-media-controller">current media controller</a> but is not <a href="#blocked-on-its-media-controller">blocked
4613: on its media controller</a>,
4614: and the element is not a <a href="#blocked-media-element">blocked media element</a>.</p>
4615:
4616: <p>A <a href="#media-element">media element</a> is said to have <dfn id="ended-playback">ended
4617: playback</dfn> when:</p>
4618:
4619: <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,
4620: and
4621:
4622: </li><li>
4623:
4624: <p>Either:
4625:
4626: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the end of the
4627: <a href="#media-resource">media resource</a>, and
4628:
4629: </li><li>The <a href="#direction-of-playback">direction of playback</a> is forwards, and
4630:
4631: </li><li>
4632: Either
4633: 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,
4634: or the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4635: controller</a>.
4636:
4637: </li></ul><p>Or:
4638:
4639: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the
4640: <a href="#earliest-possible-position">earliest possible position</a>, and
4641:
4642: </li><li>The <a href="#direction-of-playback">direction of playback</a> is backwards.
4643:
4644: </li></ul></li>
4645:
4646: </ul><p>The <dfn id="dom-media-ended" title="dom-media-ended"><code>ended</code></dfn>
1.113 mike 4647: attribute must return true if, the last time the <a href="webappapis.html#event-loop">event
4648: loop</a> reached step 1, the <a href="#media-element">media element</a> had
1.47 mike 4649: <a href="#ended-playback">ended playback</a> and the <a href="#direction-of-playback">direction of
1.113 mike 4650: playback</a> was forwards, and false otherwise.</p>
1.47 mike 4651:
4652: <p>A <a href="#media-element">media element</a> is said to have <dfn id="stopped-due-to-errors">stopped due to
4653: 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
4654: the user agent <a href="#non-fatal-media-error">encounters a
4655: non-fatal error</a> during the processing of the <a href="#media-data">media
4656: data</a>, and due to that error, is not able to play the content
4657: at the <a href="#current-playback-position">current playback position</a>.</p>
4658:
4659: <p>A <a href="#media-element">media element</a> is said to have <dfn id="paused-for-user-interaction">paused for user
4660: 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
4661: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4662: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> and
4663: the user agent has reached a point in the <a href="#media-resource">media
4664: resource</a> where the user has to make a selection for the
4665: resource to continue.
4666: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4667: controller</a> when this happens, then the user agent must
4668: <a href="#report-the-controller-state">report the controller state</a> for the <a href="#media-element">media
1.113 mike 4669: element</a>'s <a href="#current-media-controller">current media controller</a>. If the
1.47 mike 4670: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4671: controller</a> when the user makes a selection, allowing playback
4672: to resume, the user agent must similarly <a href="#report-the-controller-state">report the controller
4673: state</a> for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current
4674: media controller</a>.
4675: </p>
4676:
4677: <p>It is possible for a <a href="#media-element">media element</a> to have both
4678: <a href="#ended-playback">ended playback</a> and <a href="#paused-for-user-interaction">paused for user
4679: interaction</a> at the same time.</p>
4680:
4681: <p>When a <a href="#media-element">media element</a> that is <a href="#potentially-playing">potentially
4682: playing</a> stops playing because it has <a href="#paused-for-user-interaction">paused for user
4683: interaction</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
4684: <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>
4685:
4686: <p class="note">A <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code>
4687: DOM event <a href="#fire-waiting-when-waiting">can be fired</a> as a
4688: result of an element that is <a href="#potentially-playing">potentially playing</a>
4689: stopping playback due to its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute changing to
4690: a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.</p>
4691:
4692: <p>When the <a href="#current-playback-position">current playback position</a> reaches the end
4693: of the <a href="#media-resource">media resource</a> when the <a href="#direction-of-playback">direction of
4694: playback</a> is forwards, then the user agent must follow these
4695: steps:</p>
4696:
4697: <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
4698: and does not have a <a href="#current-media-controller">current media controller</a>,
4699: then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4700: possible position</a> of the <a href="#media-resource">media resource</a> and
4701: abort these steps.</p></li>
1.113 mike 4702: <li><p>As defined above, the <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> IDL attribute starts returning
4703: true once the <a href="webappapis.html#event-loop">event loop</a>'s current <a href="webappapis.html#concept-task" title="concept-task">task</a> ends.</p></li>
1.47 mike 4704:
1.113 mike 4705: <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
4706: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the <a href="#media-element">media
4707: element</a>.</p></li>
4708:
4709: <li><p><a href="webappapis.html#queue-a-task">Queue a task</a> that, if the <a href="#media-element">media
4710: element</a> does not have a <a href="#current-media-controller">current media
4711: controller</a>, and the <a href="#media-element">media element</a> has still
4712: <a href="#ended-playback">ended playback</a>, and the <a href="#direction-of-playback">direction of
4713: playback</a> is still forwards, and <a href="#dom-media-paused" title="dom-media-paused">paused</a> is false, changes <a href="#dom-media-paused" title="dom-media-paused">paused</a> to true and <a href="webappapis.html#fire-a-simple-event" title="fire a simple event">fires a simple event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> at the <a href="#media-element">media
4714: element</a>.</p></li>
4715:
4716: <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
4717: event</a> named <code title="event-media-ended"><a href="#event-media-ended">ended</a></code> at
4718: the <a href="#media-element">media element</a>.</p></li>
1.47 mike 4719:
1.113 mike 4720: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4721: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4722: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4723: controller</a>.</p></li>
1.47 mike 4724:
4725: </ol><p>When the <a href="#current-playback-position">current playback position</a> reaches the
4726: <a href="#earliest-possible-position">earliest possible position</a> of the <a href="#media-resource">media
4727: resource</a> when the <a href="#direction-of-playback">direction of playback</a> is
1.113 mike 4728: backwards, then the user agent must only <a href="webappapis.html#queue-a-task">queue a task</a>
4729: to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p>
1.47 mike 4730:
1.113 mike 4731: <hr><p>The <dfn id="dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
1.47 mike 4732: attribute gives the desired speed at which the <a href="#media-resource">media
4733: resource</a> is to play, as a multiple of its intrinsic
4734: speed. The attribute is mutable: on getting it must return the last
4735: value it was set to, or 1.0 if it hasn't yet been set; on setting
4736: the attribute must be set to the new value.</p>
4737:
4738: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> is
4739: used by the user agent when it <a href="#expose-a-user-interface-to-the-user" title="expose a user interface
4740: to the user">exposes a user interface to the user</a>.</p>
4741:
4742: <p>The <dfn id="dom-media-playbackrate" title="dom-media-playbackRate"><code>playbackRate</code></dfn>
4743: attribute gives the <a href="#effective-playback-rate">effective playback rate</a>
4744: (assuming there is no <a href="#current-media-controller">current media controller</a> overriding it),
4745: which is the speed at which the <a href="#media-resource">media resource</a> plays,
4746: as a multiple of its intrinsic speed. If it is not equal to the
4747: <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>,
4748: then the implication is that the user is using a feature such as
4749: fast forward or slow motion playback. The attribute is mutable: on
4750: getting it must return the last value it was set to, or 1.0 if it
4751: hasn't yet been set; on setting the attribute must be set to the new
4752: value, and the playback will change speed
4753: (if the element is <a href="#potentially-playing">potentially playing</a> and there is no
4754: <a href="#current-media-controller">current media controller</a>).</p>
4755:
4756: <p id="rateUpdate">When the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or
4757: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4758: change value (either by being set by script or by being changed
4759: directly by the user agent, e.g. in response to user control) the
4760: 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
4761: event</a> named <code title="event-media-ratechange"><a href="#event-media-ratechange">ratechange</a></code> at the <a href="#media-element">media
4762: element</a>.</p>
4763:
4764: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> and
4765: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4766: have no effect when the <a href="#media-element">media element</a> has a
4767: <a href="#current-media-controller">current media controller</a>; the namesake attributes on
4768: the <code><a href="#mediacontroller">MediaController</a></code> object are used instead in that
4769: situation.</p>
4770:
4771: <hr><p>The <dfn id="dom-media-played" title="dom-media-played"><code>played</code></dfn>
4772: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4773: <code>TimeRanges</code> object</a> that represents the ranges of
4774: the <a href="#media-resource">media resource</a>, if any, that the user agent has so
4775: far rendered, at the time the attribute is evaluated.</p>
4776:
4777: <hr><p>When the <dfn id="dom-media-play" title="dom-media-play"><code>play()</code></dfn>
4778: method on a <a href="#media-element">media element</a> is invoked, the user agent
4779: must run the following steps.</p>
4780:
4781: <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
4782: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4783: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4784: algorithm</a>.</p></li>
4785:
4786: <li>
4787:
4788: <p>If the <a href="#ended-playback" title="ended playback">playback has ended</a>
4789: and the <a href="#direction-of-playback">direction of playback</a> is forwards,
4790: and the <a href="#media-element">media element</a> does not have a <a href="#current-media-controller">current
4791: media controller</a>,
4792: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4793: possible position</a> of the <a href="#media-resource">media resource</a>.</p>
4794:
4795: <p class="note">This <a href="#seekUpdate">will cause</a> the user
4796: agent to <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
1.107 mike 4797: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4798: <a href="#media-element">media element</a>.</p>
1.47 mike 4799: </li>
4800:
4801: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
4802: media controller</a>, then <a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">bring the media element up
4803: to speed with its new media controller</a>.</p>
4804:
4805: </li><li>
4806:
4807: <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
4808: the following substeps:</p>
4809:
4810: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to false.</p></li>
4811:
4812: <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>
4813: named <code title="event-media-play"><a href="#event-media-play">play</a></code> at the element.</p></li>
4814:
4815: <li>
4816:
4817: <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
4818: value <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>,
4819: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, or
4820: <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
4821: <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>
4822: named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the
4823: element.</p>
4824:
4825: <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
4826: value <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4827: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>:
4828: <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>
4829: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> at the
4830: element.</p>
4831:
4832: </li>
4833:
4834: </ol></li>
4835:
4836: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4837: flag</a> to false.</p></li>
4838:
4839: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4840: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4841: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4842: controller</a>.</p></li>
4843:
4844: </ol><hr><p>When the <dfn id="dom-media-pause" title="dom-media-pause"><code>pause()</code></dfn>
4845: method is invoked, and when the user agent is required to pause the
4846: <a href="#media-element">media element</a>, the user agent must run the following
4847: steps:</p>
4848:
4849: <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
4850: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4851: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4852: algorithm</a>.</p></li>
4853:
4854: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4855: flag</a> to false.</p></li>
4856:
4857: <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
4858: following steps:</p>
4859:
4860: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to true.</p></li>
4861:
4862: <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
4863: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4864: element.</p></li>
4865:
4866: <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
4867: event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code>
4868: at the element.</p></li>
4869:
1.107 mike 4870: <li><p>Set the <a href="#official-playback-position">official playback position</a> to the
4871: <a href="#current-playback-position">current playback position</a>.</p></li>
4872:
1.47 mike 4873: </ol></li>
4874:
4875: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4876: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4877: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4878: controller</a>.</p></li>
4879:
4880: </ol><hr><p>The
4881: <dfn id="effective-playback-rate">effective playback rate</dfn> is not necessarily the element's
4882: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>. When a
4883: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4884: controller</a>, its <a href="#effective-playback-rate">effective playback rate</a> is the
4885: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
4886: rate</a>. Otherwise, the
4887: <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>.
4888: Thus, the <a href="#current-media-controller">current media controller</a> overrides the
4889: <a href="#media-element">media element</a>.
4890: </p>
4891:
4892: <p>If the <a href="#effective-playback-rate">effective playback rate</a> is positive or zero,
4893: then the <dfn id="direction-of-playback">direction of playback</dfn> is forwards. Otherwise, it
4894: is backwards.</p>
4895:
4896: <p id="media-playback">When a <a href="#media-element">media element</a> is
4897: <a href="#potentially-playing">potentially playing</a> and its <code><a href="infrastructure.html#document">Document</a></code> is a
4898: <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
4899: playback position</a> must increase monotonically at
4900: <a href="#effective-playback-rate">effective playback rate</a> units of media time per unit time
4901: of the <a href="#media-timeline">media timeline</a>'s clock.</p>
4902:
4903: <p class="note">The <a href="#effective-playback-rate">effective playback rate</a> can be 0.0,
4904: in which case the <a href="#current-playback-position">current playback position</a> doesn't
4905: 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
4906: <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> event doesn't
4907: fire).</p>
4908:
4909: <p class="note">This specification doesn't define how the user agent
4910: achieves the appropriate playback rate — depending on the
4911: protocol and media available, it is plausible that the user agent
4912: could negotiate with the server to have the server provide the media
4913: data at the appropriate rate, so that (except for the period between
4914: when the rate is changed and when the server updates the stream's
4915: playback rate) the client doesn't actually have to drop or
4916: interpolate any frames.</p>
4917:
1.107 mike 4918: <p>Any time the user agent <a href="webappapis.html#provide-a-stable-state" title="provide a stable
4919: state">provides a stable state</a>, the <a href="#official-playback-position">official playback
4920: position</a> must be set to the <a href="#current-playback-position">current playback
4921: position</a>.</p>
4922:
1.47 mike 4923: <p>When the <a href="#direction-of-playback">direction of playback</a> is backwards, any
4924: corresponding audio must be muted. When the <a href="#effective-playback-rate">effective playback
4925: rate</a> is so low or so high that the user agent cannot play
4926: audio usefully, the corresponding audio must also be muted. If the
4927: <a href="#effective-playback-rate">effective playback rate</a> is not 1.0, the user agent may
4928: apply pitch adjustments to the audio as necessary to render it
4929: faithfully.</p>
4930:
4931: <p><a href="#media-element" title="media element">Media elements</a> that are
4932: <a href="#potentially-playing">potentially playing</a> while not <a href="infrastructure.html#in-a-document">in a
4933: <code>Document</code></a> must not play any video, but should
4934: play any audio component. Media elements must not stop playing just
4935: because all references to them have been removed; only once a media
4936: element is in a state where no further audio could ever be played by
4937: that element may the element be garbage collected.</p>
4938:
4939: <p class="note">It is possible for an element to which no explicit
4940: references exist to play audio, even if such an element is not still
4941: actively playing: for instance, it could have a <a href="#current-media-controller">current media
4942: controller</a> that still has references and can still be
4943: unpaused, or it could be unpaused but stalled waiting for content to
4944: buffer.</p>
4945:
4946: <hr><p>When the <a href="#current-playback-position">current playback position</a> of a <a href="#media-element">media
4947: element</a> changes (e.g. due to playback or seeking), the user
4948: agent must run the following steps. If the <a href="#current-playback-position">current playback
4949: position</a> changes while the steps are running, then the user
4950: agent must wait for the steps to complete, and then must immediately
4951: rerun the steps.
4952: (These steps are thus run as often as possible or needed — if
4953: 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
4954: agent rushes ahead to "catch up".)
4955: </p>
4956:
1.104 mike 4957: <ol><li><p>Let <var title="">current cues</var> be a list of <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain all the
4958: <a href="#text-track-cue" title="text track cue">cues</a> of all the <a href="#text-track-hidden" title="text track hidden">hidden</a>, <a href="#text-track-showing" title="text track
1.47 mike 4959: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
4960: default">showing by default</a> <a href="#text-track" title="text track">text
4961: 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
4962: or equal to the <a href="#current-playback-position">current playback position</a> and whose
4963: <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are greater
1.104 mike 4964: than the <a href="#current-playback-position">current playback position</a>.</p></li>
1.47 mike 4965:
1.104 mike 4966: <li><p>Let <var title="">other cues</var> be a list of <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain all the
4967: <a href="#text-track-cue" title="text track cue">cues</a> of <a href="#text-track-hidden" title="text track
4968: hidden">hidden</a>, <a href="#text-track-showing" title="text track
1.47 mike 4969: showing">showing</a>, and <a href="#text-track-showing-by-default" title="text track showing by
4970: default">showing by default</a> <a href="#text-track" title="text track">text
4971: tracks</a> of the <a href="#media-element">media element</a> that are not
1.104 mike 4972: present in <var title="">current cues</var>.</p></li>
4973:
4974: <li><p>Let <var title="">last time</var> be the <a href="#current-playback-position">current
4975: playback position</a> at the time this algorithm was last run
4976: for this <a href="#media-element">media element</a>, if this is not the first time
4977: it has run.</p></li>
4978:
4979: <li><p>If the <a href="#current-playback-position">current playback position</a> has, since the
4980: last time this algorithm was run, only changed through its usual
4981: monotonic increase during normal playback, then let <var title="">missed cues</var> be the list of <a href="#text-track-cue" title="text track
4982: cue">cues</a> in <var title="">other cues</var> whose <a href="#text-track-cue-start-time" title="text track cue start time">start times</a> are greater
4983: than or equal to <var title="">last time</var> and whose <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are less than or
4984: equal to the <a href="#current-playback-position">current playback position</a>. Otherwise, let
4985: <var title="">missed cues</var> be an empty list.</p></li>
1.47 mike 4986:
4987: <li><p>If the time was reached through the usual monotonic increase
4988: of the <a href="#current-playback-position">current playback position</a> during normal
4989: 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
4990: element in the past 15 to 250ms and is not still running event
4991: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4992: 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.
4993: (In the other cases, such as explicit seeks, relevant events get
4994: fired as part of the overall process of changing the <a href="#current-playback-position">current
4995: playback position</a>.)</p>
4996:
4997: <p class="note">The event thus is not to be fired faster than about
4998: 66Hz or slower than 4Hz (assuming the event handlers don't take
4999: longer than 250ms to run). User agents are encouraged to vary the
5000: frequency of the event based on the system load and the average
5001: cost of processing the event each time, so that the UI updates are
5002: not any more frequent than the user agent can comfortably handle
5003: while decoding the video.</p></li>
5004:
5005: <li><p>If all of the <a href="#text-track-cue" title="text track cue">cues</a> in
5006: <var title="">current cues</var> have their <a href="#text-track-cue-active-flag">text track cue
1.104 mike 5007: active flag</a> set, none of the <a href="#text-track-cue" title="text track
1.47 mike 5008: cue">cues</a> in <var title="">other cues</var> have their
1.104 mike 5009: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, and <var title="">missed cues</var> is empty, then abort these
1.47 mike 5010: steps.</p></li>
5011:
1.104 mike 5012: <li>
5013:
5014: <p>If the time was reached through the usual monotonic increase of
5015: the <a href="#current-playback-position">current playback position</a> during normal playback,
5016: and there are <a href="#text-track-cue" title="text track cue">cues</a> in <var title="">other cues</var> that have their <a href="#text-track-cue-pause-on-exit-flag">text track cue
5017: pause-on-exit flag</a> set and that either have their
5018: <a href="#text-track-cue-active-flag">text track cue active flag</a> set or are also in <var title="">missed cues</var>, then immediately <a href="#dom-media-pause" title="dom-media-pause">pause</a> the <a href="#media-element">media
5019: element</a>. </p>
5020:
5021: <p class="note">In the other cases, such as explicit seeks,
5022: 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
5023: track cue">cue</a> has its <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
5024: flag</a> set.</p>
5025:
5026: </li>
5027:
5028: <li>
5029:
5030: <p>Let <var title="">events</var> be a list of <a href="webappapis.html#concept-task" title="concept-task">tasks</a>, initially empty. Each <a href="webappapis.html#concept-task" title="concept-task">task</a> in this list will be associated
5031: with a <a href="#text-track">text track</a>, a <a href="#text-track-cue">text track cue</a>, and
5032: a time, which are used to sort the list before the <a href="webappapis.html#concept-task" title="concept-task">tasks</a> are queued.</p>
5033:
5034: <p>Let <var title="">affected tracks</var> be a list of <a href="#text-track" title="text track">text tracks</a>, initially empty.</p>
5035:
5036: <p>When the steps below say to <dfn id="prepare-an-event">prepare an event</dfn> named
5037: <var title="">event</var> for a <a href="#text-track-cue">text track cue</a> <var title="">target</var> with a time <var title="">time</var>, the
5038: user agent must run these substeps:</p>
5039:
5040: <ol><li><p>Let <var title="">track</var> be the <a href="#text-track">text
5041: track</a> with which the <a href="#text-track-cue">text track cue</a> <var title="">target</var> is associated.</p></li>
5042:
5043: <li><p>Create a <a href="webappapis.html#concept-task" title="concept-task">task</a> to
5044: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <var title="">event</var>
5045: at <var title="">target</var>.</p></li>
5046:
5047: <li><p>Add to the newly create <a href="webappapis.html#concept-task" title="concept-task">task</a> to <var title="">events</var>,
5048: associated with the time <var title="">time</var>, the <a href="#text-track">text
5049: track</a> <var title="">track</var>, and the <a href="#text-track-cue">text track
5050: cue</a> <var title="">target</var>.</p></li>
5051:
5052: <li><p>Add <var title="">track</var> to <var title="">affected
5053: tracks</var>.</p></li>
5054:
5055: </ol></li>
5056:
5057: <li><p>For each <a href="#text-track-cue" title="text track cue">text track cue</a>
5058: in <var title="">missed cues</var>, <a href="#prepare-an-event">prepare an event</a>
5059: named <code title="event-enter">enter</code> for the
5060: <code><a href="#texttrackcue">TextTrackCue</a></code> object with the <a href="#text-track-cue-start-time">text track cue
5061: start time</a>.</p></li>
5062:
5063: <li><p>For each <a href="#text-track-cue" title="text track cue">text track cue</a>
5064: in <var title="">other cues</var> that either has its <a href="#text-track-cue-active-flag">text
5065: track cue active flag</a> set or is in <var title="">missed
5066: cues</var>, <a href="#prepare-an-event">prepare an event</a> named <code title="event-exit">exit</code> for the <code><a href="#texttrackcue">TextTrackCue</a></code>
5067: object with the <a href="#text-track-cue-end-time">text track cue end time</a>.</p></li>
5068:
5069: <li><p>For each <a href="#text-track-cue" title="text track cue">text track cue</a>
5070: in <var title="">current cues</var> that does not have its
5071: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, <a href="#prepare-an-event">prepare an
5072: event</a> named <code title="event-enter">enter</code> for the
5073: <code><a href="#texttrackcue">TextTrackCue</a></code> object with the <a href="#text-track-cue-start-time">text track cue
5074: start time</a>.</p></li>
5075:
5076: <li>
5077:
5078: <p>Sort the <a href="webappapis.html#concept-task" title="concept-task">tasks</a> in <var title="">events</var> in ascending time order (<a href="webappapis.html#concept-task" title="concept-task">tasks</a> with earlier times
5079: first).</p>
5080:
1.111 mike 5081: <p>Further sort <a href="webappapis.html#concept-task" title="concept-task">tasks</a> in <var title="">events</var> that have the same time by the relative
5082: <a href="#text-track-cue-order">text track cue order</a> of the <a href="#text-track-cue" title="text track
5083: cue">text track cues</a> associated with these <a href="webappapis.html#concept-task" title="concept-task">tasks</a>.</p>
1.104 mike 5084:
5085: </li>
5086:
5087: <li><p><a href="webappapis.html#queue-a-task" title="queue a task">Queue</a> each <a href="webappapis.html#concept-task" title="concept-task">task</a> in <var title="">events</var>, in
5088: list order.</p></li>
5089:
5090: <li><p>Sort <var title="">affected tracks</var> in the same order
5091: as the <a href="#text-track" title="text track">text tracks</a> appear in the
5092: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, and
5093: remove duplicates.</p>
5094:
5095: </li><li><p>For each <a href="#text-track">text track</a> in <var title="">affected
5096: tracks</var>, in the list order, <a href="webappapis.html#queue-a-task">queue a task</a> to
5097: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-cuechange">cuechange</code> at the
5098: <code><a href="#texttrack">TextTrack</a></code> object, and, if the <a href="#text-track">text track</a>
5099: has a corresponding <code><a href="#the-track-element">track</a></code> element, to then <a href="webappapis.html#fire-a-simple-event">fire
5100: a simple event</a> named <code title="event-cuechange">cuechange</code> at the <code><a href="#the-track-element">track</a></code>
1.47 mike 5101: element as well.</p></li>
5102:
5103: <li><p>Set the <a href="#text-track-cue-active-flag">text track cue active flag</a> of all the
5104: <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
5105: active flag</a> of all the <a href="#text-track-cue" title="text track
5106: cue">cues</a> in the <var title="">other cues</var>.</p></li>
5107:
5108: <li><p>Run the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
5109: rendering</a> of each of the <a href="#text-track" title="text track">text
5110: 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
5111: track showing by default">showing by default</a>.
5112: </p></li>
5113:
5114: </ol><p>For the purposes of the algorithm above, a <a href="#text-track-cue">text track
5115: cue</a> is considered to be part of a <a href="#text-track">text track</a>
5116: only if it is listed in the <a href="#text-track-list-of-cues">text track list of cues</a>,
5117: not merely if it is associated with the <a href="#text-track">text
5118: track</a>.</p>
5119:
5120: <p class="note">If the <a href="#media-element">media element</a>'s
5121: <code><a href="infrastructure.html#document">Document</a></code> stops being a <a href="browsers.html#fully-active">fully active</a>
5122: document, then the playback will <a href="#media-playback">stop</a>
5123: until the document is active again.</p>
5124:
5125: <p>When a <a href="#media-element">media element</a> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an
5126: element from a document">removed from a
5127: <code>Document</code></a>, the user agent must run
5128: the following steps:</p>
5129:
5130: <ol><li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
5131: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that removed the
5132: <a href="#media-element">media element</a> from the <code><a href="infrastructure.html#document">Document</a></code> to
5133: continue. The <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the
5134: remaining steps of this algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous
5135: section</a> are marked with ⌛.)</p></li>
5136:
5137: <li><p>⌛ If the <a href="#media-element">media element</a> is <a href="infrastructure.html#in-a-document">in a
5138: <code>Document</code></a>, abort these steps.</p></li>
5139:
5140: <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
5141: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, abort these
5142: steps.</p></li>
5143:
5144: <li><p>⌛ <a href="#dom-media-pause" title="dom-media-pause">Pause</a> the
5145: <a href="#media-element">media element</a>.</p>
5146:
5147: </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>
5148:
5149: <dd>
5150:
5151: <p>Returns true if the user agent is currently seeking.</p>
5152:
5153: </dd>
5154:
5155: <dt><var title="">media</var> . <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code></dt>
5156:
5157: <dd>
5158:
5159: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5160: ranges of the <a href="#media-resource">media resource</a> to which it is possible
5161: for the user agent to seek.</p>
5162:
5163: </dd>
5164:
5165: </dl><div class="impl">
5166:
5167: <p>The <dfn id="dom-media-seeking" title="dom-media-seeking"><code>seeking</code></dfn>
5168: attribute must initially have the value false.</p>
5169:
5170: <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
5171: playback position</var> in the <a href="#media-resource">media resource</a>, it means
5172: that the user agent must run the following steps. This algorithm
5173: interacts closely with the <a href="webappapis.html#event-loop">event loop</a> mechanism; in
5174: particular, it has a <a href="webappapis.html#synchronous-section">synchronous
5175: section</a> (which is triggered as part of the <a href="webappapis.html#event-loop">event
5176: loop</a> algorithm). Steps in that section are marked with
5177: ⌛.</p>
5178:
1.107 mike 5179: <ol><li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, abort these
5180: steps.</p></li>
1.47 mike 5181:
5182: <li><p>If the element's <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute is true,
5183: then another instance of this algorithm is already running. Abort
5184: that other instance of the algorithm without waiting for the step
5185: that it is running to complete.</p></li>
5186:
5187: <li><p>Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL
5188: attribute to true.</p></li>
5189:
5190: <li><p>If the seek was in response to a DOM method call or setting
5191: of an IDL attribute, then continue the script. The remainder of
5192: these steps must be run asynchronously. With the exception of the
5193: steps marked with ⌛, they could be aborted at any time by
5194: another instance of this algorithm being invoked.</p></li>
5195:
5196: <li><p>If the <var title="">new playback position</var> is later
5197: than the end of the <a href="#media-resource">media resource</a>, then let it be the
5198: end of the <a href="#media-resource">media resource</a> instead.</p></li>
5199:
5200: <li><p>If the <var title="">new playback position</var> is less
5201: than the <a href="#earliest-possible-position">earliest possible position</a>, let it be that
5202: position instead.</p></li>
5203:
5204: <li><p>If the (possibly now changed) <var title="">new playback
5205: 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
5206: 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
5207: nearest to the <var title="">new playback position</var>. If two
5208: positions both satisfy that constraint (i.e. the <var title="">new
5209: playback position</var> is exactly in the middle between two ranges
5210: in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute)
5211: then use the position that is closest to the <a href="#current-playback-position">current playback
5212: 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
5213: <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
5214: false and abort these steps.</p></li>
5215:
5216: <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
5217: event</a> named <code title="event-media-seeking"><a href="#event-media-seeking">seeking</a></code>
5218: at the element.</p></li>
5219:
5220: <li>
5221:
5222: <p>Set the <a href="#current-playback-position">current playback position</a> to the given
5223: <var title="">new playback position</var>.</p>
5224:
5225: <p class="note">If the <a href="#media-element">media element</a> was
5226: <a href="#potentially-playing">potentially playing</a> immediately before it started
5227: seeking, but seeking caused its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to change
5228: 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
5229: <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
5230: element.</p>
5231:
5232:
1.107 mike 5233: <p class="note">The <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> attribute does
5234: not get updated asynchronously, as it returns the <a href="#official-playback-position">official
5235: playback position</a>, not the <a href="#current-playback-position">current playback
5236: position</a>.</p>
5237:
1.47 mike 5238: </li>
5239:
5240: <li><p>Wait until the user agent has established whether or not the
5241: <a href="#media-data">media data</a> for the <var title="">new playback
5242: position</var> is available, and, if it is, until it has decoded
5243: enough data to play back that position.</p>
5244: </li>
5245:
5246: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
5247: section</a> consists of all the remaining steps of this
5248: algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous section</a> are
5249: marked with ⌛.)</p></li>
5250:
5251: <li><p>⌛ Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
5252: false.</p></li>
5253:
1.120 mike 5254: <li id="seekUpdate"><p>⌛ <a href="webappapis.html#queue-a-task">Queue a task</a> to
5255: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
1.47 mike 5256: element.</p></li>
5257:
5258: <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
5259: event</a> named <code title="event-media-seeked"><a href="#event-media-seeked">seeked</a></code>
5260: at the element.</p></li>
5261:
5262: </ol><p>The <dfn id="dom-media-seekable" title="dom-media-seekable"><code>seekable</code></dfn>
5263: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5264: <code>TimeRanges</code> object</a> that represents the ranges of
5265: the <a href="#media-resource">media resource</a>, if any, that the user agent is able
5266: to seek to, at the time the attribute is evaluated.</p>
5267:
5268: <p class="note">If the user agent can seek to anywhere in the
5269: <a href="#media-resource">media resource</a>, e.g. because it is a simple movie file
5270: and the user agent and the server support HTTP Range requests, then
5271: the attribute would return an object with one range, whose start is
5272: the time of the first frame (the <a href="#earliest-possible-position">earliest possible
5273: position</a>, typically zero), and whose end is the same as the
5274: time of the first frame plus the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute's value (which
5275: would equal the time of the last frame, and might be positive
5276: Infinity).</p>
5277:
5278: <p class="note">The range might be continuously changing, e.g. if
5279: the user agent is buffering a sliding window on an infinite
5280: stream. This is the behavior seen with DVRs viewing live TV, for
5281: instance.</p>
5282:
5283: <p><a href="#media-resource" title="media resource">Media resources</a> might be
5284: internally scripted or interactive. Thus, a <a href="#media-element">media
5285: element</a> could play in a non-linear fashion. If this happens,
5286: 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
5287: <a href="#current-playback-position">current playback position</a> changes in a discontinuous
5288: fashion (so that the relevant events fire).
5289: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
5290: controller</a>, then the user agent must <a href="#seek-the-media-controller">seek the media
5291: controller</a> appropriately instead.
5292: </p>
5293:
5294: </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
5295: and video tracks. For example, in addition to the primary video and
5296: audio tracks, a <a href="#media-resource">media resource</a> could have
5297: foreign-language dubbed dialogues, director's commentaries, audio
5298: 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>
5299:
5300: <dd>
5301:
1.76 mike 5302: <p>Returns an <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
1.47 mike 5303: the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
5304:
5305: </dd>
5306:
5307: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code></dt>
5308:
5309: <dd>
5310:
1.106 mike 5311: <p>Returns a <code><a href="#videotracklist">VideoTrackList</a></code> object representing
1.47 mike 5312: the video tracks available in the <a href="#media-resource">media resource</a>.</p>
5313:
5314: </dd>
5315:
5316: </dl><div class="impl">
5317:
5318: <p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
5319: attribute of a <a href="#media-element">media element</a> must return a
1.76 mike 5320: <a href="infrastructure.html#live">live</a> <code><a href="#audiotracklist">AudioTrackList</a></code> object representing
1.47 mike 5321: the audio tracks available in the <a href="#media-element">media element</a>'s
5322: <a href="#media-resource">media resource</a>. The same object must be returned each
5323: time.</p>
5324:
5325: <p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
5326: attribute of a <a href="#media-element">media element</a> must return a
1.76 mike 5327: <a href="infrastructure.html#live">live</a> <code><a href="#videotracklist">VideoTrackList</a></code> object
1.47 mike 5328: representing the video tracks available in the <a href="#media-element">media
5329: element</a>'s <a href="#media-resource">media resource</a>. The same object must
5330: be returned each time.</p>
5331:
1.76 mike 5332: <p class="note">There are only ever one <code><a href="#audiotracklist">AudioTrackList</a></code>
5333: object and one <code><a href="#videotracklist">VideoTrackList</a></code> object per <a href="#media-element">media
1.47 mike 5334: element</a>, even if another <a href="#media-resource">media resource</a> is
1.76 mike 5335: loaded into the element: the objects are reused. (The
5336: <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects are
5337: not, though.)</p>
1.47 mike 5338:
1.67 mike 5339: </div><div class="example">
5340:
5341: <p>In this example, a script defines a function that takes a URL to
5342: a video and a reference to an element where the video is to be
5343: placed. That function then tries to load the video, and, once it is
5344: loaded, checks to see if there is a sign-language track available.
5345: If there is, it also displays that track. Both tracks are just
5346: placed in the given container; it's assumed that styles have been
5347: applied to make this work in a pretty way!</p>
5348:
5349: <pre><script>
5350: function loadVideo(url, container) {
5351: var controller = new MediaController();
5352: var video = document.createElement('video');
5353: video.src = url;
5354: video.autoplay = true;
5355: video.controls = true;
5356: video.controller = controller;
5357: container.appendChild(video);
5358: video.onloadedmetadata = function (event) {
5359: for (var i = 0; i < video.videoTracks.length; i += 1) {
1.76 mike 5360: if (video.videoTracks[i].kind == 'sign') {
1.67 mike 5361: var sign = document.createElement('video');
1.76 mike 5362: sign.src = url + '#track=' + video.videoTracks[i].id;
1.67 mike 5363: sign.autoplay = true;
5364: sign.controller = controller;
5365: container.appendChild(sign);
5366: return;
5367: }
5368: }
5369: };
5370: }
5371: </script></pre>
5372:
1.76 mike 5373: </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>
5374: interfaces are used by attributes defined in the previous
5375: section.</p><pre class="idl">interface <dfn id="audiotracklist">AudioTrackList</dfn> {
5376: readonly attribute unsigned long <a href="#dom-audiotracklist-length" title="dom-AudioTrackList-length">length</a>;
1.101 mike 5377: getter <a href="#audiotrack">AudioTrack</a> (unsigned long index);
5378: <a href="#audiotrack">AudioTrack</a>? <a href="#dom-audiotracklist-gettrackbyid" title="dom-AudioTrackList-getTrackById">getTrackById</a>(DOMString id);
1.121 mike 5379:
1.118 mike 5380: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
1.121 mike 5381: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onaddtrack" title="handler-TrackList-onaddtrack">onaddtrack</a>;
1.76 mike 5382: };
1.47 mike 5383:
1.76 mike 5384: interface <dfn id="audiotrack">AudioTrack</dfn> {
5385: readonly attribute DOMString <a href="#dom-audiotrack-id" title="dom-AudioTrack-id">id</a>;
5386: readonly attribute DOMString <a href="#dom-audiotrack-kind" title="dom-AudioTrack-kind">kind</a>;
5387: readonly attribute DOMString <a href="#dom-audiotrack-label" title="dom-AudioTrack-label">label</a>;
5388: readonly attribute DOMString <a href="#dom-audiotrack-language" title="dom-AudioTrack-language">language</a>;
5389: attribute boolean <a href="#dom-audiotrack-enabled" title="dom-AudioTrack-enabled">enabled</a>;
1.47 mike 5390: };
5391:
1.76 mike 5392: interface <dfn id="videotracklist">VideoTrackList</dfn> {
5393: readonly attribute unsigned long <a href="#dom-videotracklist-length" title="dom-VideoTrackList-length">length</a>;
1.101 mike 5394: getter <a href="#videotrack">VideoTrack</a> (unsigned long index);
5395: <a href="#videotrack">VideoTrack</a>? <a href="#dom-videotracklist-gettrackbyid" title="dom-VideoTrackList-getTrackById">getTrackById</a>(DOMString id);
1.76 mike 5396: readonly attribute long <a href="#dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex">selectedIndex</a>;
1.121 mike 5397:
1.118 mike 5398: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
1.121 mike 5399: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-tracklist-onaddtrack" title="handler-TrackList-onaddtrack">onaddtrack</a>;
1.47 mike 5400: };
5401:
1.76 mike 5402: interface <dfn id="videotrack">VideoTrack</dfn> {
5403: readonly attribute DOMString <a href="#dom-videotrack-id" title="dom-VideoTrack-id">id</a>;
5404: readonly attribute DOMString <a href="#dom-videotrack-kind" title="dom-VideoTrack-kind">kind</a>;
5405: readonly attribute DOMString <a href="#dom-videotrack-label" title="dom-VideoTrack-label">label</a>;
5406: readonly attribute DOMString <a href="#dom-videotrack-language" title="dom-VideoTrack-language">language</a>;
5407: attribute boolean <a href="#dom-videotrack-selected" title="dom-VideoTrack-selected">selected</a>;
5408: };</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>
5409: <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 5410:
5411: <dd>
5412:
5413: <p>Returns the number of tracks in the list.</p>
5414:
5415: </dd>
5416:
1.76 mike 5417: <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>
5418: <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 5419:
5420: <dd>
5421:
1.76 mike 5422: <p>Returns the specified <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object.</p>
1.47 mike 5423:
5424: </dd>
5425:
1.76 mike 5426: <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>
5427: <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 5428:
5429: <dd>
5430:
1.76 mike 5431: <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 5432:
5433: </dd>
5434:
1.76 mike 5435: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-id"><a href="#dom-audiotrack-id">id</a></code></dt>
5436: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-id"><a href="#dom-videotrack-id">id</a></code></dt>
1.47 mike 5437:
5438: <dd>
5439:
1.76 mike 5440: <p>Returns the ID of the given track. This is the ID that can be
5441: used with a fragment identifier if the format supports the
5442: <cite>Media Fragments URI</cite> syntax, and that can be used with
1.101 mike 5443: the <code title="">getTrackById()</code> method. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5444:
5445: </dd>
5446:
1.76 mike 5447: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-kind"><a href="#dom-audiotrack-kind">kind</a></code></dt>
5448: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-kind"><a href="#dom-videotrack-kind">kind</a></code></dt>
1.47 mike 5449:
5450: <dd>
5451:
1.76 mike 5452: <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 5453:
5454: </dd>
5455:
1.76 mike 5456: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-label"><a href="#dom-audiotrack-label">label</a></code></dt>
5457: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-label"><a href="#dom-videotrack-label">label</a></code></dt>
1.47 mike 5458:
5459: <dd>
5460:
1.76 mike 5461: <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
1.47 mike 5462:
5463: </dd>
5464:
1.76 mike 5465: <dt><var title="">audioTrack</var> . <code title="dom-AudioTrack-language"><a href="#dom-audiotrack-language">language</a></code></dt>
5466: <dt><var title="">videoTrack</var> . <code title="dom-VideoTrack-language"><a href="#dom-videotrack-language">language</a></code></dt>
1.47 mike 5467:
5468: <dd>
5469:
1.76 mike 5470: <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
1.47 mike 5471:
5472: </dd>
5473:
1.76 mike 5474: <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 5475:
5476: <dd>
5477:
1.76 mike 5478: <p>Returns true if the given track is active, and false otherwise.</p>
5479:
5480: <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 5481:
5482: </dd>
5483:
1.76 mike 5484: <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 5485:
5486: <dd>
5487:
5488: <p>Returns the index of the currently selected track, if any, or −1 otherwise.</p>
5489:
5490: </dd>
5491:
1.76 mike 5492: <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 5493:
5494: <dd>
5495:
1.76 mike 5496: <p>Returns true if the given track is active, and false otherwise.</p>
5497:
5498: <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 5499:
5500: </dd>
5501:
5502: </dl><div class="impl">
5503:
1.76 mike 5504: <p>An <code><a href="#audiotracklist">AudioTrackList</a></code> object represents a dynamic list
5505: of zero or more audio tracks, of which zero or more can be enabled
5506: at a time. Each audio track is represented by an
5507: <code><a href="#audiotrack">AudioTrack</a></code> object.</p>
5508:
5509: <p>A <code><a href="#videotracklist">VideoTrackList</a></code> object represents a dynamic list of
5510: zero or more video tracks, of which zero or one can be selected at a
5511: time. Each video track is represented by a <code><a href="#videotrack">VideoTrack</a></code>
5512: object.</p>
5513:
5514: <p>Tracks in <code><a href="#audiotracklist">AudioTrackList</a></code> and
5515: <code><a href="#videotracklist">VideoTrackList</a></code> objects must be consistently ordered. If
5516: the <a href="#media-resource">media resource</a> is in a format that defines an
5517: order, then that order must be used; otherwise, the order must be
5518: the relative order in which the tracks are declared in the
5519: <a href="#media-resource">media resource</a>. The order used is called the <i>natural
5520: order</i> of the list.</p>
5521:
5522: <p class="note">Each track in a <code>TrackList</code> thus has an
5523: index; the first has the index 0, and each subsequent track is
5524: numbered one higher than the previous one. If a <a href="#media-resource">media
5525: resource</a> dynamically adds or removes audio or video tracks,
5526: then the indices of the tracks will change dynamically. If the
5527: <a href="#media-resource">media resource</a> changes entirely, then all the previous
5528: tracks will be removed and replaced with new tracks.</p>
5529:
5530: <p>The <dfn id="dom-audiotracklist-length" title="dom-AudioTrackList-length"><code>AudioTrackList.length</code></dfn>
5531: and <dfn id="dom-videotracklist-length" title="dom-VideoTrackList-length"><code>VideoTrackList.length</code></dfn>
5532: attributes must return the number of tracks represented by their
5533: objects at the time of getting.</p>
5534:
5535: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of
5536: <code><a href="#audiotracklist">AudioTrackList</a></code> and <code><a href="#videotracklist">VideoTrackList</a></code> objects
5537: at any instant are the numbers from zero to the number of tracks
5538: represented by the respective object minus one, if any tracks are
5539: represented. If a <code><a href="#audiotracklist">AudioTrackList</a></code> or
5540: <code><a href="#videotracklist">VideoTrackList</a></code> object represents no tracks, it has no
5541: <a href="infrastructure.html#supported-property-indices">supported property indices</a>.</p>
5542:
5543: <p>To <a href="infrastructure.html#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> for a
5544: given index <var title="">index</var> in an
5545: <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> object
5546: <var title="">list</var>, the user agent must return the
5547: <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object that
5548: represents the <var title="">index</var>th track in <var title="">list</var>.</p>
5549:
5550: <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
5551: <code><a href="#audiotrack">AudioTrack</a></code> or <code><a href="#videotrack">VideoTrack</a></code> object
5552: (respectively) in the <code><a href="#audiotrack">AudioTrack</a></code> or
5553: <code><a href="#videotrack">VideoTrack</a></code> object (respectively) whose identifier is
5554: equal to the value of the <var title="">id</var> argument (in the
5555: natural order of the list, as defined above). When no tracks match
5556: the given argument, the methods must return null.</p>
5557:
5558: <p>The <code><a href="#audiotrack">AudioTrack</a></code> and <code><a href="#videotrack">VideoTrack</a></code> objects
5559: represent specific tracks of a <a href="#media-resource">media resource</a>. Each
5560: track can have an identifier, category, label, and language. These
5561: aspects of a track are permanent for the lifetime of the track; even
5562: if a track is removed from a <a href="#media-resource">media resource</a>'s
5563: <code><a href="#audiotracklist">AudioTrackList</a></code> or <code><a href="#videotracklist">VideoTrackList</a></code> objects,
5564: those aspects do not change.</p>
5565:
5566: <p>In addition, <code><a href="#audiotrack">AudioTrack</a></code> objects can each be enabled
5567: or disabled; this is the audio track's <i>enabled state</i>. When an
5568: <code><a href="#audiotrack">AudioTrack</a></code> is created, its <i>enabled state</i> must be
5569: set to false (disabled). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
5570: can override this.</p>
5571:
5572: <p>Similarly, a single <code><a href="#videotrack">VideoTrack</a></code> object per
5573: <code><a href="#videotracklist">VideoTrackList</a></code> object can be selected, this is the
1.120 mike 5574: video track's <i>selection state</i>. When a
1.76 mike 5575: <code><a href="#videotrack">VideoTrack</a></code> is created, its <i>selection state</i> must
5576: be set to false (not selected). The <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch algorithm</a>
5577: can override this.</p>
5578:
5579: <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>
5580: attributes must return the identifier of the track, if it has one,
5581: or the empty string otherwise. If the <a href="#media-resource">media resource</a> is
5582: in a format that supports the <cite>Media Fragments URI</cite>
5583: fragment identifier syntax, the identifier returned for a particular
5584: track must be the same identifier that would enable the track if
5585: used as the name of a track in the track dimension of such a
1.101 mike 5586: fragment identifier. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5587:
1.76 mike 5588: <p>The <dfn id="dom-audiotrack-kind" title="dom-AudioTrack-kind"><code>AudioTrack.kind</code></dfn> and
5589: <dfn id="dom-videotrack-kind" title="dom-VideoTrack-kind"><code>VideoTrack.kind</code></dfn>
5590: attributes must return the category of the track, if it has one, or
5591: the empty string otherwise.</p>
1.47 mike 5592:
5593: <p>The category of a track is the string given in the first column
5594: of the table below that is the most appropriate for the track based
5595: on the definitions in the table's second and third columns, as
5596: determined by the metadata included in the track in the <a href="#media-resource">media
5597: resource</a>. For Ogg files, the Role header of the track gives
5598: the relevant metadata. The cell in the third column of a row says
5599: what the category given in the cell in the first column of that row
5600: applies to; a category is only appropriate for an audio track if it
5601: applies to audio tracks, and a category is only appropriate for
1.76 mike 5602: video tracks if it applies to video tracks. Categories must only be
5603: returned for <code><a href="#audiotrack">AudioTrack</a></code> objects if they are appropriate
5604: for audio, and must only be returned for <code><a href="#videotrack">VideoTrack</a></code>
5605: objects if they are appropriate for video.</p>
1.47 mike 5606:
1.76 mike 5607: </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 5608: <thead><tr><th>Category
5609: </th><th>Definition
5610: </th><th>Applies to...</th>
5611: <th>Examples
1.76 mike 5612: </th></tr></thead><tbody><tr><td>"<dfn id="value-track-kind-alternate" title="value-track-kind-alternate"><code>alternative</code></dfn>"
1.47 mike 5613: </td><td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
5614: </td><td>Audio and video.
1.89 mike 5615: </td><td>Ogg: "audio/alternate" or "video/alternate".
1.47 mike 5616:
1.76 mike 5617: </td></tr><tr><td>"<dfn id="value-track-kind-description" title="value-track-kind-description"><code>description</code></dfn>"
1.47 mike 5618: </td><td>An audio description of a video track.
5619: </td><td>Audio only.
5620: </td><td>Ogg: "audio/audiodesc".
5621:
1.76 mike 5622: </td></tr><tr><td>"<dfn id="value-track-kind-main" title="value-track-kind-main"><code>main</code></dfn>"
1.47 mike 5623: </td><td>The primary audio or video track.
5624: </td><td>Audio and video.
5625: </td><td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
5626:
1.76 mike 5627: </td></tr><tr><td>"<dfn id="value-track-kind-sign" title="value-track-kind-sign"><code>sign</code></dfn>"
1.47 mike 5628: </td><td>A sign-language interpretation of an audio track.
5629: </td><td>Video only.
5630: </td><td>Ogg: "video/sign".
5631:
1.76 mike 5632: </td></tr><tr><td>"<dfn id="value-track-kind-translation" title="value-track-kind-translation"><code>translation</code></dfn>"
1.47 mike 5633: </td><td>A translated version of the main track.
5634: </td><td>Audio only.
5635: </td><td>Ogg: "audio/dub".
5636:
1.76 mike 5637: </td></tr><tr><td>"<dfn id="value-track-kind-commentary" title="value-track-kind-commentary"><code>commentary</code></dfn>"
5638: </td><td>Commentary on the primary audio or video track, e.g. a director's commentary.
5639: </td><td>Audio and video.
5640: </td><td>No known formats expose this category at this time.
5641:
5642: </td></tr><tr><td>"<dfn id="value-track-kind-none" title="value-track-kind-none"><code></code></dfn>" (empty string)
1.47 mike 5643: </td><td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
5644: </td><td>Audio and video.
5645: </td><td>Any other track type or track role.
5646:
5647: </td></tr></tbody></table><div class="impl">
5648:
1.76 mike 5649: <p>The <dfn id="dom-audiotrack-label" title="dom-AudioTrack-label"><code>AudioTrack.label</code></dfn> and
5650: <dfn id="dom-videotrack-label" title="dom-VideoTrack-label"><code>VideoTrack.label</code></dfn>
5651: attributes must return the label of the track, if it has one, or the
5652: empty string otherwise.</p>
5653:
5654: <p>The <dfn id="dom-audiotrack-language" title="dom-AudioTrack-language"><code>AudioTrack.language</code></dfn>
5655: and <dfn id="dom-videotrack-language" title="dom-VideoTrack-language"><code>VideoTrack.language</code></dfn>
5656: attributes must return the BCP 47 language tag of the language of
5657: the track, if it has one, or the empty string otherwise. If the user
1.47 mike 5658: agent is not able to express that language as a BCP 47 language tag
5659: (for example because the language information in the <a href="#media-resource">media
5660: resource</a>'s format is a free-form string without a defined
1.76 mike 5661: interpretation), then the method must return the empty string, as if
5662: the track had no language.</p>
1.47 mike 5663:
1.76 mike 5664: <p>The <dfn id="dom-audiotrack-enabled" title="dom-AudioTrack-enabled"><code>AudioTrack.enabled</code></dfn>
5665: attribute, on getting, must return true if the track is currently
5666: enabled, and false otherwise. On setting, it must enable the track
5667: if the new value is true, and disable it otherwise. (If the track is
5668: no longer in an <code><a href="#audiotracklist">AudioTrackList</a></code> object, then the track
5669: being enabled or disabled has no effect beyond changing the value of
5670: the attribute on the <code><a href="#audiotrack">AudioTrack</a></code> object.)</p>
5671:
5672: <p>Whenever an audio track in an <code><a href="#audiotracklist">AudioTrackList</a></code> is
5673: enabled or disabled, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
5674: to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-change">change</code> at the
5675: <code><a href="#audiotracklist">AudioTrackList</a></code> object.</p>
5676:
5677: <p>The <dfn id="dom-videotracklist-selectedindex" title="dom-VideoTrackList-selectedIndex"><code>VideoTrackList.selectedIndex</code></dfn>
5678: attribute must return the index of the currently selected track, if
5679: any. If the <code><a href="#videotracklist">VideoTrackList</a></code> object does not currently
5680: represent any tracks, or if none of the tracks are selected, it must
5681: instead return −1.</p>
5682:
5683: <p>The <dfn id="dom-videotrack-selected" title="dom-VideoTrack-selected"><code>VideoTrack.selected</code></dfn>
5684: attribute, on getting, must return true if the track is currently
5685: selected, and false otherwise. On setting, it must select the track
5686: if the new value is true, and unselect it otherwise. If the track is
5687: in a <code><a href="#videotracklist">VideoTrackList</a></code>, then all the other
5688: <code><a href="#videotrack">VideoTrack</a></code> objects in that list must be unselected. (If
5689: the track is no longer in a <code><a href="#videotracklist">VideoTrackList</a></code> object, then
5690: the track being selected or unselected has no effect beyond changing
5691: the value of the attribute on the <code><a href="#videotrack">VideoTrack</a></code>
5692: object.)</p>
5693:
5694: <p>Whenever a track in a <code><a href="#videotracklist">VideoTrackList</a></code> that was
5695: previously not selected is selected, the user agent must <a href="webappapis.html#queue-a-task">queue
5696: 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
5697: <code><a href="#videotracklist">VideoTrackList</a></code> object.</p>
1.47 mike 5698:
5699: <hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
5700: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
5701: event types</a>) that must be supported, as IDL attributes, by
1.76 mike 5702: all objects implementing the <code><a href="#audiotracklist">AudioTrackList</a></code> and
5703: <code><a href="#videotracklist">VideoTrackList</a></code> interfaces:</p>
1.47 mike 5704:
5705: <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>
5706: </th></tr></thead><tbody><tr><td><dfn id="handler-tracklist-onchange" title="handler-TrackList-onchange"><code>onchange</code></dfn> </td><td> <code title="event-change">change</code>
1.121 mike 5707: </td></tr><tr><td><dfn id="handler-tracklist-onaddtrack" title="handler-TrackList-onaddtrack"><code>onaddtrack</code></dfn> </td><td> <code title="event-addtrack">addtrack</code>
1.47 mike 5708: </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
5709: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5710:
5711:
5712:
5713: </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
5714: <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attributes
5715: allow scripts to select which track should play, but it is also
5716: possible to select specific tracks declaratively, by specifying
5717: particular tracks in the fragment identifier of the <a href="urls.html#url">URL</a>
5718: of the <a href="#media-resource">media resource</a>. The format of the fragment
5719: identifier depends on the <a href="infrastructure.html#mime-type">MIME type</a> of the <a href="#media-resource">media
1.101 mike 5720: resource</a>. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3986">[RFC3986]</a></p><div class="example">
1.47 mike 5721:
5722: <p>In this example, a video that uses a format that supports the
5723: <cite>Media Fragments URI</cite> fragment identifier syntax is
5724: embedded in such a way that the alternative angles labeled
1.101 mike 5725: "Alternative" are enabled instead of the default video track. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5726:
5727: <pre><video src="myvideo#track=Alternative"></video></pre>
5728:
5729:
5730: </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
5731: <code><a href="#mediacontroller">MediaController</a></code>. A <code><a href="#mediacontroller">MediaController</a></code> is an
5732: object that coordinates the playback of multiple <a href="#media-element" title="media
5733: element">media elements</a>, for instance so that a sign-language
5734: interpreter track can be overlaid on a video track, with the two
5735: being kept in sync.</p><p>By default, a <a href="#media-element">media element</a> has no
5736: <code><a href="#mediacontroller">MediaController</a></code>. An implicit
5737: <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.
5738: An explicit <code><a href="#mediacontroller">MediaController</a></code> can be assigned directly
5739: using the <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> IDL
5740: attribute.</p><p><a href="#media-element" title="media element">Media elements</a> with a
5741: <code><a href="#mediacontroller">MediaController</a></code> are said to be <i>slaved</i> to their
5742: controller. The <code><a href="#mediacontroller">MediaController</a></code> modifies the playback
5743: rate and the playback volume of each of the <a href="#media-element" title="media
5744: element">media elements</a> slaved to it, and ensures that when
5745: any of its slaved <a href="#media-element" title="media element">media elements</a>
5746: 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
5747: <code><a href="#mediacontroller">MediaController</a></code>, its playback rate is fixed to that of
5748: the other tracks in the same <code><a href="#mediacontroller">MediaController</a></code>, and any
5749: 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>]
5750: interface <dfn id="mediacontroller">MediaController</dfn> {
5751: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-buffered" title="dom-MediaController-buffered">buffered</a>;
5752: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-seekable" title="dom-MediaController-seekable">seekable</a>;
5753: readonly attribute double <a href="#dom-mediacontroller-duration" title="dom-MediaController-duration">duration</a>;
5754: attribute double <a href="#dom-mediacontroller-currenttime" title="dom-MediaController-currentTime">currentTime</a>;
5755:
5756: readonly attribute boolean <a href="#dom-mediacontroller-paused" title="dom-MediaController-paused">paused</a>;
5757: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-played" title="dom-MediaController-played">played</a>;
5758: void <a href="#dom-mediacontroller-play" title="dom-MediaController-play">play</a>();
5759: void <a href="#dom-mediacontroller-pause" title="dom-MediaController-pause">pause</a>();
5760:
5761: attribute double <a href="#dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate">defaultPlaybackRate</a>;
5762: attribute double <a href="#dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate">playbackRate</a>;
5763:
5764: attribute double <a href="#dom-mediacontroller-volume" title="dom-MediaController-volume">volume</a>;
5765: attribute boolean <a href="#dom-mediacontroller-muted" title="dom-MediaController-muted">muted</a>;
5766:
1.118 mike 5767: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onemptied" title="handler-MediaController-onemptied">onemptied</a>;
5768: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata">onloadedmetadata</a>;
5769: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata">onloadeddata</a>;
5770: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay">oncanplay</a>;
5771: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough">oncanplaythrough</a>;
5772: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onplaying" title="handler-MediaController-onplaying">onplaying</a>;
5773: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onended" title="handler-MediaController-onended">onended</a>;
5774: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting">onwaiting</a>;
5775:
5776: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange">ondurationchange</a>;
5777: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate">ontimeupdate</a>;
5778: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onplay" title="handler-MediaController-onplay">onplay</a>;
5779: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onpause" title="handler-MediaController-onpause">onpause</a>;
5780: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onratechange" title="handler-MediaController-onratechange">onratechange</a>;
5781: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange">onvolumechange</a>;
1.47 mike 5782: };</pre><dl class="domintro"><dt><var title="">controller</var> = new <code title="dom-MediaController"><a href="#dom-mediacontroller">MediaController</a></code>()</dt>
5783:
5784: <dd>
5785:
5786: <p>Returns a new <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5787:
5788: </dd>
5789:
5790: <dt><var title="">media</var> . <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> [ = <var title="">controller</var> ]</dt>
5791:
5792: <dd>
5793:
5794: <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>
5795:
5796: <p>Can be set, to set an explicit <code><a href="#mediacontroller">MediaController</a></code>.
5797: Doing so removes the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if
5798: any.</p>
5799:
5800: </dd>
5801:
5802: <dt><var title="">controller</var> . <code title="dom-MediaController-buffered"><a href="#dom-mediacontroller-buffered">buffered</a></code></dt>
5803:
5804: <dd>
5805:
5806: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5807: intersection of the time ranges for which the user agent has all
5808: relevant media data for all the slaved <a href="#media-element" title="media
5809: element">media elements</a>.</p>
5810:
5811: </dd>
5812:
5813: <dt><var title="">controller</var> . <code title="dom-MediaController-seekable"><a href="#dom-mediacontroller-seekable">seekable</a></code></dt>
5814:
5815: <dd>
5816:
5817: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5818: intersection of the time ranges into which the user agent can seek
5819: for all the slaved <a href="#media-element" title="media element">media
5820: elements</a>.</p>
5821:
5822: </dd>
5823:
5824: <dt><var title="">controller</var> . <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code></dt>
5825:
5826: <dd>
5827:
5828: <p>Returns the difference between the earliest playable moment and
5829: the latest playable moment (not considering whether the data in
5830: question is actually buffered or directly seekable, but not
5831: including time in the future for infinite streams). Will return
5832: zero if there is no media.</p>
5833:
5834: </dd>
5835:
5836: <dt><var title="">controller</var> . <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
5837:
5838: <dd>
5839:
5840: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds,
5841: as a position between zero time and the current <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code>.</p>
5842:
5843: <p>Can be set, to seek to the given time.</p><p>
5844:
5845: </p></dd>
5846:
5847: <dt><var title="">controller</var> . <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code></dt>
5848:
5849: <dd>
5850:
5851: <p>Returns true if playback is paused; false otherwise. When this
5852: attribute is true, any <a href="#media-element">media element</a> slaved to this
5853: controller will be stopped.</p>
5854:
5855: </dd>
5856:
1.113 mike 5857: <dt><var title="">controller</var> . <code title="dom-MediaController-play"><a href="#dom-mediacontroller-play">play</a></code>()</dt>
1.47 mike 5858:
5859: <dd>
5860:
1.113 mike 5861: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5862: attribute to false.</p>
1.47 mike 5863:
5864: </dd>
5865:
1.113 mike 5866: <dt><var title="">controller</var> . <code title="dom-MediaController-pause"><a href="#dom-mediacontroller-pause">pause</a></code>()</dt>
1.47 mike 5867:
5868: <dd>
5869:
5870: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
1.113 mike 5871: attribute to true.</p>
1.47 mike 5872:
5873: </dd>
5874:
1.113 mike 5875: <dt><var title="">controller</var> . <code title="dom-MediaController-played"><a href="#dom-mediacontroller-played">played</a></code></dt>
1.47 mike 5876:
5877: <dd>
5878:
1.113 mike 5879: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5880: union of the time ranges in all the slaved <a href="#media-element" title="media
5881: element">media elements</a> that have been played.</p>
1.47 mike 5882:
5883: </dd>
5884:
5885: <dt><var title="">controller</var> . <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
5886:
5887: <dd>
5888:
5889: <p>Returns the default rate of playback.</p>
5890:
5891: <p>Can be set, to change the default rate of playback.</p>
5892:
5893: <p>This default rate has no direct effect on playback, but if the
5894: user switches to a fast-forward mode, when they return to the
5895: normal playback mode, it is expected that rate of playback (<code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code>) will
5896: be returned to this default rate.</p>
5897:
5898: </dd>
5899:
5900: <dt><var title="">controller</var> . <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
5901:
5902: <dd>
5903:
5904: <p>Returns the current rate of playback.</p>
5905:
5906: <p>Can be set, to change the rate of playback.</p>
5907:
5908: </dd>
5909:
5910: <dt><var title="">controller</var> . <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
5911:
5912: <dd>
5913:
5914: <p>Returns the current playback volume multiplier, as a number in
5915: the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the
5916: loudest.</p>
5917:
5918: <p>Can be set, to change the volume multiplier.</p>
5919:
1.119 mike 5920: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the new value is not
1.47 mike 5921: in the range 0.0 .. 1.0.</p>
5922:
5923: </dd>
5924:
5925: <dt><var title="">controller</var> . <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
5926:
5927: <dd>
5928:
5929: <p>Returns true if all audio is muted (regardless of other
5930: attributes either on the controller or on any <a href="#media-element" title="media
5931: element">media elements</a> slaved to this controller), and
5932: false otherwise.</p>
5933:
5934: <p>Can be set, to change whether the audio is muted or not.</p>
5935:
5936: </dd>
5937:
5938: </dl><div class="impl">
5939:
5940: <p>A <a href="#media-element">media element</a> can have a <dfn id="current-media-controller">current media
5941: controller</dfn>, which is a <code><a href="#mediacontroller">MediaController</a></code> object.
5942: 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
5943: not have a <a href="#current-media-controller">current media controller</a>. (If it is created
5944: <em>with</em> such an attribute, then that attribute initializes the
5945: <a href="#current-media-controller">current media controller</a>, as defined below.)</p>
5946:
5947: <p>The <dfn id="slaved-media-elements">slaved media elements</dfn> of a
5948: <code><a href="#mediacontroller">MediaController</a></code> are the <a href="#media-element" title="media
5949: element">media elements</a> whose <a href="#current-media-controller">current media
5950: controller</a> is that <code><a href="#mediacontroller">MediaController</a></code>. All the
5951: <a href="#slaved-media-elements">slaved media elements</a> of a <code><a href="#mediacontroller">MediaController</a></code>
5952: must use the same clock for their definition of their <a href="#media-timeline">media
5953: timeline</a>'s unit time.</p>
5954:
5955: <hr><p>The <dfn id="dom-media-controller" title="dom-media-controller"><code>controller</code></dfn> attribute
5956: on a <a href="#media-element">media element</a>, on getting, must return the
5957: element's <a href="#current-media-controller">current media controller</a>, if any, or null
5958: 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,
5959: and then set the <a href="#current-media-controller">current media controller</a> to the given
5960: value. If the given value is null, the element no longer has a
5961: <a href="#current-media-controller">current media controller</a>; if it is not null, then the
5962: 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
5963: new media controller</a>.</p>
5964:
5965: <hr><p>The <dfn id="dom-mediacontroller" title="dom-MediaController"><code>MediaController()</code></dfn>
5966: constructor, when invoked, must return a newly created
5967: <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5968:
5969: <hr><p>The <dfn id="dom-mediacontroller-seekable" title="dom-MediaController-seekable"><code>seekable</code></dfn>
5970: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5971: <code>TimeRanges</code> object</a> that represents the
5972: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5973: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5974: user agent is able to seek to, at the time the attribute is
5975: evaluated.</p>
5976:
5977: <p>The <dfn id="dom-mediacontroller-buffered" title="dom-MediaController-buffered"><code>buffered</code></dfn>
5978: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5979: <code>TimeRanges</code> object</a> that represents the
5980: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5981: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5982: user agent has buffered, at the time the attribute is evaluated.
5983: Users agents must accurately determine the ranges available, even
5984: for media streams where this can only be determined by tedious
5985: inspection.</p>
5986:
5987: <p>The <dfn id="dom-mediacontroller-duration" title="dom-MediaController-duration"><code>duration</code></dfn>
5988: attribute must return the <a href="#media-controller-duration">media controller
5989: duration</a>.</p>
5990:
5991: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5992: <a href="#media-controller-duration">media controller duration</a> changes, whichever happens
5993: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5994: <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>
5995: at the <code><a href="#mediacontroller">MediaController</a></code>. If the
5996: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-duration">media controller
5997: duration</a> decreases such that the <a href="#media-controller-position">media controller
5998: position</a> is greater than the <a href="#media-controller-duration">media controller
5999: duration</a>, the user agent must immediately <a href="#seek-the-media-controller">seek the
6000: media controller</a> to <a href="#media-controller-duration">media controller
6001: duration</a>.</p>
6002:
6003: <p>The <dfn id="dom-mediacontroller-currenttime" title="dom-MediaController-currentTime"><code>currentTime</code></dfn>
6004: attribute must return the <a href="#media-controller-position">media controller position</a> on
6005: getting, and on setting must <a href="#seek-the-media-controller">seek the media controller</a>
6006: to the new value.</p>
6007:
6008: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
6009: <a href="#media-controller-position">media controller position</a> changes, whichever happens
6010: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
6011: <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
6012: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6013:
6014: <hr><p>When a <code><a href="#mediacontroller">MediaController</a></code> is created it is a
6015: <dfn id="playing-media-controller">playing media controller</dfn>. It can be changed into a
6016: <dfn id="paused-media-controller">paused media controller</dfn> and back either via the user
6017: agent's user interface (when the element is <a href="#expose-a-user-interface-to-the-user" title="expose a
6018: user interface to the user">exposing a user interface to the
6019: user</a>) or by script using the APIs defined in this section
6020: (see below).</p>
6021:
6022: <p>The <dfn id="dom-mediacontroller-paused" title="dom-MediaController-paused"><code>paused</code></dfn>
6023: attribute must return true if the <code><a href="#mediacontroller">MediaController</a></code>
6024: object is a <a href="#paused-media-controller">paused media controller</a>, and false
6025: otherwise.</p>
6026:
6027: <p>When the <dfn id="dom-mediacontroller-pause" title="dom-MediaController-pause"><code>pause()</code></dfn> method
6028: is invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#playing-media-controller">playing
6029: media controller</a> then the user agent must change the
6030: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#paused-media-controller">paused media
6031: 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
6032: event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
6033: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
6034: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
6035:
6036: <p>When the <dfn id="dom-mediacontroller-play" title="dom-MediaController-play"><code>play()</code></dfn> method is
6037: invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#paused-media-controller">paused media
6038: controller</a>, the user agent must change the
6039: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#playing-media-controller">playing media
6040: 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
6041: event</a> named <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code> at the
6042: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
6043: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
6044:
1.113 mike 6045: <p>The <dfn id="dom-mediacontroller-played" title="dom-MediaController-played"><code>played</code></dfn>
6046: attribute must return a new static <a href="#normalized-timeranges-object">normalized
6047: <code>TimeRanges</code> object</a> that represents the union of
6048: the ranges of the <a href="#media-resource" title="media resource">media
6049: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
6050: user agent has so far rendered, at the time the attribute is
6051: evaluated.</p>
6052:
1.47 mike 6053: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-default-playback-rate">media controller
6054: default playback rate</dfn> and a <dfn id="media-controller-playback-rate">media controller playback
6055: rate</dfn>, which must both be set to 1.0 when the
6056: <code><a href="#mediacontroller">MediaController</a></code> object is created.</p>
6057:
6058: <p>The <dfn id="dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
6059: attribute, on getting, must return the
6060: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
6061: playback rate</a>, and on setting, must set the
6062: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
6063: playback rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a
6064: 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
6065: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6066:
6067: <p>The <dfn id="dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate"><code>playbackRate</code></dfn>
6068: attribute, on getting, must return the
6069: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
6070: rate</a>, and on setting, must set the
6071: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
6072: rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a task</a> to
6073: <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
6074: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6075:
6076: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-volume-multiplier">media controller volume
6077: multiplier</dfn>, which must be set to 1.0 when the
6078: <code><a href="#mediacontroller">MediaController</a></code> object is created, and a <dfn id="media-controller-mute-override">media
6079: controller mute override</dfn>, much must initially be false.</p>
6080:
6081: <p>The <dfn id="dom-mediacontroller-volume" title="dom-MediaController-volume"><code>volume</code></dfn>
6082: attribute, on getting, must return the
6083: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-volume-multiplier">media controller volume
6084: multiplier</a>, and on setting, if the new value is in the range
6085: 0.0 to 1.0 inclusive, must set the <code><a href="#mediacontroller">MediaController</a></code>'s
6086: <a href="#media-controller-volume-multiplier">media controller volume multiplier</a> to the new value and
6087: <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
6088: <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
6089: at the <code><a href="#mediacontroller">MediaController</a></code>. If the new value is outside the
6090: range 0.0 to 1.0 inclusive, then, on setting, an
1.119 mike 6091: <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exception must be raised instead.</p>
1.47 mike 6092:
6093: <p>The <dfn id="dom-mediacontroller-muted" title="dom-MediaController-muted"><code>muted</code></dfn>
6094: attribute, on getting, must return the
6095: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
6096: override</a>, and on setting, must set the
6097: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
6098: override</a> to the new value and <a href="webappapis.html#queue-a-task">queue a task</a> to
6099: <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
6100: the <code><a href="#mediacontroller">MediaController</a></code>.</p>
6101:
6102: <hr><p>The <a href="#media-resource" title="media resource">media resources</a> of all
6103: the <a href="#slaved-media-elements">slaved media elements</a> of a
6104: <code><a href="#mediacontroller">MediaController</a></code> have a defined temporal relationship
6105: which provides relative offsets between the zero time of each such
6106: <a href="#media-resource">media resource</a>: for <a href="#media-resource" title="media resource">media
6107: resources</a> with a <a href="#timeline-offset">timeline offset</a>, their relative
6108: offsets are the difference between their <a href="#timeline-offset">timeline
6109: offset</a>; the zero times of all the <a href="#media-resource" title="media
6110: resource">media resources</a> without a <a href="#timeline-offset">timeline
6111: offset</a> are not offset from each other (i.e. the origins of
6112: their timelines are cotemporal); and finally, the zero time of the
6113: <a href="#media-resource">media resource</a> with the earliest <a href="#timeline-offset">timeline
6114: offset</a> (if any) is not offset from the zero times of the
6115: <a href="#media-resource" title="media resource">media resources</a> without a
6116: <a href="#timeline-offset">timeline offset</a> (i.e. the origins of <a href="#media-resource" title="media
6117: resource">media resources</a> without a <a href="#timeline-offset">timeline
6118: offset</a> are further cotemporal with the earliest defined point
6119: on the timeline of the <a href="#media-resource">media resource</a> with the earliest
6120: <a href="#timeline-offset">timeline offset</a>).</p>
6121:
6122: <p>The <dfn id="media-resource-end-position">media resource end position</dfn> of a <a href="#media-resource">media
6123: resource</a> in a <a href="#media-element">media element</a> is defined as
6124: follows: if the <a href="#media-resource">media resource</a> has a finite and known
6125: duration, the <a href="#media-resource-end-position">media resource end position</a> is the
6126: duration of the <a href="#media-resource">media resource</a>'s timeline (the last
6127: defined position on that timeline); otherwise, the <a href="#media-resource">media
6128: resource</a>'s duration is infinite or unknown, and the
6129: <a href="#media-resource-end-position">media resource end position</a> is the time of the last
6130: frame of <a href="#media-data">media data</a> currently available for that
6131: <a href="#media-resource">media resource</a>.</p>
6132:
6133: <p>Each <code><a href="#mediacontroller">MediaController</a></code> also has its own defined
6134: timeline. On this timeline, all the <a href="#media-resource" title="media
6135: resource">media resources</a> of all the <a href="#slaved-media-elements">slaved media
6136: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code> are temporally
6137: aligned according to their defined offsets. The <dfn id="media-controller-duration">media
6138: controller duration</dfn> of that <code><a href="#mediacontroller">MediaController</a></code> is
6139: the time from the earliest <a href="#earliest-possible-position">earliest possible position</a>,
6140: relative to this <code><a href="#mediacontroller">MediaController</a></code> timeline, of any of
6141: the <a href="#media-resource" title="media resource">media resources</a> of the
6142: <a href="#slaved-media-elements">slaved media elements</a> of the
6143: <code><a href="#mediacontroller">MediaController</a></code>, to the time of the latest <a href="#media-resource-end-position">media
6144: resource end position</a> of the <a href="#media-resource" title="media
6145: resource">media resources</a> of the <a href="#slaved-media-elements">slaved media
6146: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code>, again relative
6147: to this <code><a href="#mediacontroller">MediaController</a></code> timeline.</p>
6148:
6149: <p>Each <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-position">media controller
6150: position</dfn>. This is the time on the
6151: <code><a href="#mediacontroller">MediaController</a></code>'s timeline at which the user agent is
6152: trying to play the <a href="#slaved-media-elements">slaved media elements</a>. When a
6153: <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#media-controller-position">media controller
6154: position</a> is initially zero.</p>
6155:
6156: <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
6157: to speed with its new media controller">bring a media element up to
6158: 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>
6159: to the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-position">media controller
6160: position</a> relative to the <a href="#media-element">media element</a>'s
1.107 mike 6161: timeline.</p>
1.47 mike 6162:
6163: <p>When the user agent is to <dfn id="seek-the-media-controller">seek the media controller</dfn> to
6164: a particular <var title="">new playback position</var>, it must
6165: follow these steps:</p>
6166:
6167: <ol><li><p>If the <var title="">new playback position</var> is less
6168: than zero, then set it to zero.</p></li>
6169:
6170: <li><p>If the <var title="">new playback position</var> is greater
6171: than the <a href="#media-controller-duration">media controller duration</a>, then set it to the
6172: <a href="#media-controller-duration">media controller duration</a>.</p></li>
6173:
6174: <li><p>Set the <a href="#media-controller-position">media controller position</a> to the <var title="">new playback position</var>.</p></li>
6175:
6176: <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
6177: <var title="">new playback position</var> relative to the
1.107 mike 6178: <a href="#media-element">media element</a> timeline.</p></li>
1.47 mike 6179: </ol><p>A <code><a href="#mediacontroller">MediaController</a></code> is a <dfn id="blocked-media-controller">blocked media
6180: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
6181: <a href="#paused-media-controller">paused media controller</a>, or if any of its <a href="#slaved-media-elements">slaved
6182: media elements</a> are <a href="#blocked-media-element" title="blocked media
6183: element">blocked media elements</a>, or if any of its
6184: <a href="#slaved-media-elements">slaved media elements</a> whose <a href="#autoplaying-flag">autoplaying
1.70 mike 6185: 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 6186: 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>
6187:
6188: <p>A <a href="#media-element">media element</a> is <dfn id="blocked-on-its-media-controller">blocked on its media
6189: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
6190: <a href="#blocked-media-controller">blocked media controller</a>, or if its <a href="#media-controller-position">media
6191: controller position</a> is either before the <a href="#media-resource">media
6192: resource</a>'s <a href="#earliest-possible-position">earliest possible position</a> relative
6193: to the <code><a href="#mediacontroller">MediaController</a></code>'s timeline or after the end of
6194: the <a href="#media-resource">media resource</a> relative to the
6195: <code><a href="#mediacontroller">MediaController</a></code>'s timeline.</p>
6196:
6197: <p id="controller-playback">When a <code><a href="#mediacontroller">MediaController</a></code> is
6198: not a <a href="#blocked-media-controller">blocked media controller</a> and it has at least one
6199: <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a>
6200: whose <code><a href="infrastructure.html#document">Document</a></code> is a <a href="browsers.html#fully-active">fully active</a>
6201: <code><a href="infrastructure.html#document">Document</a></code>, the <code><a href="#mediacontroller">MediaController</a></code>'s
6202: <a href="#media-controller-position">media controller position</a> must increase monotonically
6203: at <a href="#media-controller-playback-rate">media controller playback rate</a> units of time on the
6204: <code><a href="#mediacontroller">MediaController</a></code>'s timeline per unit time of the clock
6205: used by its <a href="#slaved-media-elements">slaved media elements</a>.</p>
6206:
6207: <p>When the zero point on the timeline of a
6208: <code><a href="#mediacontroller">MediaController</a></code> moves relative to the timelines of the
6209: <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
6210: <a href="#media-controller-position">media controller position</a> must be decremented by <var title="">ΔT</var>.</p>
6211:
6212: <p class="note">In some situations, e.g. when playing back a live
6213: stream without buffering anything, the <a href="#media-controller-position">media controller
1.125 mike 6214: position</a> would increase monotonically as described above at the
1.47 mike 6215: same rate as the <var title="">ΔT</var> described in the
6216: previous paragraph decreases it, with the end result that for all
6217: intents and purposes, the <a href="#media-controller-position">media controller position</a>
6218: would appear to remain constant (probably with the value 0).</p>
6219:
6220: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="most-recently-reported-readiness-state">most recently reported
6221: readiness state</dfn>, which is a number from 0 to 4 derived from
6222: the numbers used for the <a href="#media-element">media element</a> <code title="attr-media-readyState">readyState</code> attribute, and a
6223: <dfn id="most-recently-reported-playback-state">most recently reported playback state</dfn>, which is either
6224: <i>playing</i>, <i>waiting</i>, or <i>ended</i>.</p>
6225:
6226: <p>When a <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#most-recently-reported-readiness-state">most
6227: recently reported readiness state</a> must be set to 0, and its
6228: <a href="#most-recently-reported-playback-state">most recently reported playback state</a> must be set to
6229: <i>waiting</i>.</p>
6230:
6231: <p>When a user agent is required to <dfn id="report-the-controller-state">report the controller
6232: state</dfn> for a <code><a href="#mediacontroller">MediaController</a></code>, the user agent must
6233: run the following steps:</p>
6234:
6235: <ol><li>
6236:
6237: <p>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved media
6238: elements</a>, let <var title="">new readiness state</var> be
6239: 0.</p>
6240:
6241: <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
6242: all of its <a href="#slaved-media-elements">slaved media elements</a>.</p>
6243:
6244: </li>
6245:
6246: <li>
6247:
6248: <p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
6249: reported readiness state</a> is not equal to <var title="">new
6250: 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
6251: a simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
6252: whose name is the event name corresponding to the value of <var title="">new readiness state</var> given in the table below:</p>
6253:
6254:
6255: <table><thead><tr><th>Value of <var title="">new readiness state</var>
6256: </th><th>Event name
6257:
6258: </th></tr></thead><tbody><tr><td> 0
6259: </td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
6260:
6261: </td></tr><tr><td> 1
6262: </td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
6263:
6264: </td></tr><tr><td> 2
6265: </td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
6266:
6267: </td></tr><tr><td> 3
6268: </td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
6269:
6270: </td></tr><tr><td> 4
6271: </td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
6272:
6273: </td></tr></tbody></table></li>
6274:
6275: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
6276: reported readiness state</a> be <var title="">new readiness
6277: state</var>.</p></li>
6278:
6279: <li>
6280:
6281: <p>Initialize <var title="">new playback state</var> by setting it
6282: to the state given for the first matching condition from the
6283: following list:</p>
6284:
6285: <dl class="switch"><dt>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved
6286: media elements</a></dt>
6287:
6288: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
6289:
6290: <dt>If all of the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#slaved-media-elements">slaved
6291: media elements</a> have <a href="#ended-playback">ended playback</a> and the
6292: <a href="#media-controller-playback-rate">media controller playback rate</a> is positive or
6293: zero</dt>
6294:
6295: <dd>Let <var title="">new playback state</var> be <i>ended</i>.</dd>
6296:
6297: <dt>If the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#blocked-media-controller">blocked media
6298: controller</a></dt>
6299:
6300: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
6301:
6302: <dt>Otherwise</dt>
6303:
6304: <dd>Let <var title="">new playback state</var> be <i>playing</i>.</dd>
6305:
6306: </dl></li>
6307:
6308: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6309: reported playback state</a> is not equal to <var title="">new
1.113 mike 6310: playback state</var> and the <var title="">new playback state</var>
6311: is <i>ended</i>, then <a href="webappapis.html#queue-a-task">queue a task</a> that, if the
6312: <code><a href="#mediacontroller">MediaController</a></code> object is a <a href="#playing-media-controller">playing media
6313: controller</a>, and all of the <code><a href="#mediacontroller">MediaController</a></code>'s
6314: <a href="#slaved-media-elements">slaved media elements</a> have still <a href="#ended-playback">ended
6315: playback</a>, and the <a href="#media-controller-playback-rate">media controller playback
6316: rate</a> is still positive or zero, changes the
6317: <code><a href="#mediacontroller">MediaController</a></code> object to a <a href="#paused-media-controller">paused media
6318: controller</a> and then <a href="webappapis.html#fire-a-simple-event" title="fire a simple event">fires
6319: a simple event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
6320: <code><a href="#mediacontroller">MediaController</a></code> object.</p></li>
6321:
6322: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6323: reported playback state</a> is not equal to <var title="">new
1.47 mike 6324: 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
6325: simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
1.75 mike 6326: 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 6327: otherwise.</p></li>
6328:
6329: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
6330: reported playback state</a> be <var title="">new playback
6331: state</var>.</p></li>
6332:
1.121 mike 6333: </ol><hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
6334: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
6335: event types</a>) that must be supported, as IDL attributes, by
6336: all objects implementing the <code><a href="#mediacontroller">MediaController</a></code>
6337: interface:</p>
1.47 mike 6338:
6339: <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>
6340: </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>
6341: </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>
6342: </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>
6343: </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>
6344: </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>
6345: </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 6346: </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 6347: </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>
6348: </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 6349: </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 6350: </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>
6351: </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>
6352: </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>
6353: </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>
6354: </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
6355: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
6356:
6357: </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
6358: attribute on <a href="#media-element" title="media element">media elements</a> can
6359: be used to link multiple <a href="#media-element" title="media element">media
6360: elements</a> together by implicitly creating a
1.126 mike 6361: <code><a href="#mediacontroller">MediaController</a></code>. The value is text; <a href="#media-element" title="media
6362: element">media elements</a> with the same value are automatically
6363: linked by the user agent.</p><div class="impl">
1.47 mike 6364:
6365: <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
6366: 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,
6367: changed, or removed, the user agent must run the following
6368: steps:</p>
6369:
6370: <ol><li><p>Let <var title="">m</var> be the <a href="#media-element">media element</a>
6371: in question.</p></li>
6372:
6373: <li><p>Let <var title="">m</var> have no <a href="#current-media-controller">current
6374: media controller</a>, if it currently has one.</p></li>
6375:
6376: <li><p>If <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is being
6377: removed, then abort these steps.</p></li>
6378:
6379: <li>
6380:
6381: <p>If there is another <a href="#media-element">media element</a> whose
6382: <code><a href="infrastructure.html#document">Document</a></code> is the same as <var title="">m</var>'s
6383: <code><a href="infrastructure.html#document">Document</a></code> (even if one or both of these elements are
6384: not actually <a href="infrastructure.html#in-a-document" title="in a Document"><em>in</em> the
6385: <code>Document</code></a>), and which also has a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and
6386: whose <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>
6387: 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
6388: let <var title="">controller</var> be that <a href="#media-element">media
6389: element</a>'s <a href="#current-media-controller">current media controller</a>.</p>
6390:
6391: <p>Otherwise, let <var title="">controller</var> be a newly created
6392: <code><a href="#mediacontroller">MediaController</a></code>.</p>
6393:
6394: </li>
6395:
6396: <li><p>Let <var title="">m</var>'s <a href="#current-media-controller">current media
6397: controller</a> be <var title="">controller</var>.</p></li>
6398:
6399: <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
6400: controller</a>.</p></li>
6401:
6402: </ol><p>The <dfn id="dom-media-mediagroup" title="dom-media-mediaGroup"><code>mediaGroup</code></dfn> IDL
6403: attribute on <a href="#media-element" title="media element">media elements</a> must
6404: <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content
6405: attribute.</p>
6406:
6407: </div><div class="example">
6408:
6409: <p>Multiple <a href="#media-element" title="media element">media elements</a>
6410: referencing the same <a href="#media-resource">media resource</a> will share a
6411: single network request. This can be used to efficiently play two
6412: (video) tracks from the same <a href="#media-resource">media resource</a> in two
6413: different places on the screen. Used with the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, these
6414: elements can also be kept synchronised.</p>
6415:
6416: <p>In this example, a sign-languge interpreter track from a movie
6417: file is overlaid on the primary video track of that same video file
6418: using two <code><a href="#the-video-element">video</a></code> elements, some CSS, and an implicit
6419: <code><a href="#mediacontroller">MediaController</a></code>:</p>
6420:
6421: <pre><article>
6422: <style scoped>
6423: div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
6424: video { position; absolute; bottom: 0; right: 0; }
6425: video:first-child { width: 100%; height: 100%; }
6426: video:last-child { width: 30%; }
6427: </style>
6428: <div>
6429: <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
6430: <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
6431: </div>
6432: </article></pre>
6433:
6434: </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
6435: 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
6436: to <code><a href="#the-track-element">track</a></code> element children of the <a href="#media-element">media
6437: element</a>, in <a href="infrastructure.html#tree-order">tree order</a>.</li>
6438:
6439: <li>Any <a href="#text-track" title="text track">text tracks</a> added using
6440: the <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack()</a></code> method, in
6441: the order they were added, oldest first.</li>
6442:
6443: <li>Any <a href="#media-resource-specific-text-track" title="media-resource-specific text
6444: track">media-resource-specific text tracks</a> (<a href="#text-track" title="text track">text tracks</a> corresponding to data in
6445: the <a href="#media-resource">media resource</a>), in the order defined by the
6446: <a href="#media-resource">media resource</a>'s format specification.</li>
6447:
6448: </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>
6449:
6450: </dt><dd>
6451:
6452: <p>This decides how the track is handled by the user agent. The
6453: kind is represented by a string. The possible strings are:</p>
6454:
6455: <ul class="brief"><li><dfn id="dom-texttrack-kind-subtitles" title="dom-TextTrack-kind-subtitles"><code>subtitles</code></dfn>
6456: </li><li><dfn id="dom-texttrack-kind-captions" title="dom-TextTrack-kind-captions"><code>captions</code></dfn>
6457: </li><li><dfn id="dom-texttrack-kind-descriptions" title="dom-TextTrack-kind-descriptions"><code>descriptions</code></dfn>
6458: </li><li><dfn id="dom-texttrack-kind-chapters" title="dom-TextTrack-kind-chapters"><code>chapters</code></dfn>
6459: </li><li><dfn id="dom-texttrack-kind-metadata" title="dom-TextTrack-kind-metadata"><code>metadata</code></dfn>
6460: </li></ul><p>The <a href="#text-track-kind" title="text track kind">kind of track</a> can
6461: change dynamically, in the case of a <a href="#text-track">text track</a>
6462: corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6463:
6464: </dd>
6465:
6466: <dt><dfn id="text-track-label" title="text track label">A label</dfn>
6467:
6468: </dt><dd>
6469:
6470: <p>This is a human-readable string intended to identify the track
6471: for the user. In certain cases, the label might be generated
6472: automatically.</p>
6473:
6474: <p>The <a href="#text-track-label" title="text track label">label of a track</a> can
6475: change dynamically, in the case of a <a href="#text-track">text track</a>
6476: corresponding to a <code><a href="#the-track-element">track</a></code> element or in the case of an
6477: automatically-generated label whose value depends on variable
6478: factors such as the user's preferred user interface language.</p>
6479:
6480: </dd>
6481:
6482: <dt><dfn id="text-track-language" title="text track language">A language</dfn>
6483:
6484: </dt><dd>
6485:
6486: <p>This is a string (a BCP 47 language tag) representing the
1.101 mike 6487: language of the text track's cues. <a href="references.html#refsBCP47">[BCP47]</a></p>
1.47 mike 6488:
6489: <p>The <a href="#text-track-language" title="text track language">language of a text
6490: track</a> can change dynamically, in the case of a <a href="#text-track">text
6491: track</a> corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6492:
6493: </dd>
6494:
6495: <dt><dfn id="text-track-readiness-state" title="text track readiness state">A readiness state</dfn>
6496:
6497: </dt><dd>
6498:
6499: <p>One of the following:</p>
6500:
6501: <dl><dt><dfn id="text-track-not-loaded" title="text track not loaded">Not loaded</dfn>
6502:
6503: </dt><dd>
6504:
1.132 ! mike 6505: <p>Indicates that the text track's cues have not been
! 6506: obtained.</p>
1.47 mike 6507:
6508: </dd>
6509:
6510: <dt><dfn id="text-track-loading" title="text track loading">Loading</dfn>
6511:
6512: </dt><dd>
6513:
6514: <p>Indicates that the text track is loading and there have been
6515: no fatal errors encountered so far. Further cues might still be
1.132 ! mike 6516: added to the track by the parser.</p>
1.47 mike 6517:
6518: </dd>
6519:
6520: <dt><dfn id="text-track-loaded" title="text track loaded">Loaded</dfn>
6521:
6522: </dt><dd>
6523:
6524: <p>Indicates that the text track has been loaded with no fatal
1.132 ! mike 6525: errors.</p>
1.47 mike 6526:
6527: </dd>
6528:
6529: <dt><dfn id="text-track-failed-to-load" title="text track failed to load">Failed to load</dfn>
6530:
6531: </dt><dd>
6532:
6533: <p>Indicates that the text track was enabled, but when the user
6534: agent attempted to obtain it, this failed in some way
6535: (e.g. <a href="urls.html#url">URL</a> could not be <a href="urls.html#resolve-a-url" title="resolve a
6536: url">resolved</a>, network error, unknown text track
6537: format). Some or all of the cues are likely missing and will not
6538: be obtained.</p>
6539:
6540: </dd>
6541:
6542: </dl><p>The <a href="#text-track-readiness-state" title="text track readiness state">readiness
6543: state</a> of a <a href="#text-track">text track</a> changes dynamically as
6544: the track is obtained.</p>
6545:
6546: </dd>
6547:
6548: <dt><dfn id="text-track-mode" title="text track mode">A mode</dfn>
6549:
6550: </dt><dd>
6551:
6552: <p>One of the following:</p>
6553:
6554: <dl><dt><dfn id="text-track-disabled" title="text track disabled">Disabled</dfn>
6555:
6556: </dt><dd>
6557:
6558: <p>Indicates that the text track is not active. Other than for
6559: the purposes of exposing the track in the DOM, the user agent is
6560: ignoring the text track. No cues are active, no events are
6561: fired, and the user agent will not attempt to obtain the track's
6562: cues.</p>
6563:
6564: </dd>
6565:
6566: <dt><dfn id="text-track-hidden" title="text track hidden">Hidden</dfn>
6567:
6568: </dt><dd>
6569:
6570: <p>Indicates that the text track is active, but that the user
6571: agent is not actively displaying the cues. If no attempt has yet
6572: been made to obtain the track's cues, the user agent will
6573: perform such an attempt momentarily. The user agent is
6574: maintaining a list of which cues are active, and events are
6575: being fired accordingly.</p>
6576:
6577: </dd>
6578:
6579: <dt><dfn id="text-track-showing" title="text track showing">Showing</dfn>
6580: <dt><dfn id="text-track-showing-by-default" title="text track showing by default">Showing by default</dfn>
6581:
6582: </dt></dt><dd>
6583:
6584: <p>Indicates that the text track is active. If no attempt has
6585: yet been made to obtain the track's cues, the user agent will
6586: perform such an attempt momentarily. The user agent is
6587: maintaining a list of which cues are active, and events are
6588: being fired accordingly. In addition, for text tracks whose
6589: <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-subtitles">subtitles</code> or <code title="dom-mediatrack-kind-captions">captions</code>, the cues
1.115 mike 6590: are being overlaid on the video as appropriate; for text tracks
6591: whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-descriptions">descriptions</code>,
1.47 mike 6592: the user agent is making the cues available to the user in a
1.115 mike 6593: non-visual fashion; and for text tracks whose <a href="#text-track-kind" title="text
6594: track kind">kind</a> is <code title="dom-mediatrack-kind-chapters">chapters</code>, the user
1.47 mike 6595: agent is making available to the user a mechanism by which the
6596: user can navigate to any point in the <a href="#media-resource">media
6597: resource</a> by selecting a cue.</p>
6598:
6599: <p>The <a href="#text-track-showing-by-default" title="text track showing by default">showing by
6600: default</a> state is used in conjunction with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute on
6601: <code><a href="#the-track-element">track</a></code> elements to indicate that the text track was
6602: enabled due to that attribute. This allows the user agent to
6603: override the state if a later track is discovered that is more
6604: appropriate per the user's preferences.</p>
6605:
6606: </dd>
6607:
6608: </dl></dd>
6609:
6610: <dt><dfn id="text-track-list-of-cues" title="text track list of cues">A list of zero or more cues</dfn>
6611:
6612: </dt><dd>
6613:
6614: <p>A list of <a href="#text-track-cue" title="text track cue">text track
6615: cues</a>, along with <dfn id="rules-for-updating-the-text-track-rendering">rules for updating the text track
6616: rendering</dfn>.
6617: </p>
6618:
6619: <p>The <a href="#text-track-list-of-cues" title="text track list of cues">list of cues of a
6620: text track</a> can change dynamically, either because the
6621: <a href="#text-track">text track</a> has <a href="#text-track-not-loaded" title="text track not
6622: loaded">not yet been loaded</a> or is still <a href="#text-track-loading" title="text
1.132 ! mike 6623: track loading">loading</a>, or due to DOM manipulation.</p>
1.47 mike 6624:
6625: </dd>
6626:
6627: </dl><p>Each <a href="#text-track">text track</a> has a corresponding
6628: <code><a href="#texttrack">TextTrack</a></code> object.</p><p>The <a href="#text-track" title="text track">text tracks</a> of a
6629: <a href="#media-element">media element</a> are <dfn id="the-text-tracks-are-ready" title="the text tracks are
6630: ready">ready</dfn> if all the <a href="#text-track" title="text track">text
6631: tracks</a> whose <a href="#text-track-mode" title="text track mode">mode</a> was
6632: not in the <a href="#text-track-disabled" title="text track disabled">disabled</a> state
6633: when the element's <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
6634: algorithm</a> last started now have a <a href="#text-track-readiness-state">text track readiness
6635: state</a> of <a href="#text-track-loaded" title="text track loaded">loaded</a> or
6636: <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
6637: in a <a href="#text-track">text track</a>, corresponding for instance for
6638: subtitles and captions to the text that appears at a particular time
6639: 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>
6640: </dt><dd>
6641: <p>An arbitrary string.</p>
6642: </dd>
6643:
6644: <dt><dfn id="text-track-cue-start-time" title="text track cue start time">A start time</dfn>
6645: </dt><dd>
1.129 mike 6646: <p>The time, in seconds and fractions of a second, that describes
6647: the beginning of the range of the <a href="#media-data">media data</a> to which
6648: the cue applies.</p>
1.47 mike 6649: </dd>
6650:
6651: <dt><dfn id="text-track-cue-end-time" title="text track cue end time">An end time</dfn>
6652: </dt><dd>
1.129 mike 6653: <p>The time, in seconds and fractions of a second, that describes
6654: the end of the range of the <a href="#media-data">media data</a> to which the
6655: cue applies.</p>
1.47 mike 6656: </dd>
6657:
6658: <dt><dfn id="text-track-cue-pause-on-exit-flag" title="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
6659: </dt><dd>
6660: <p>A boolean indicating whether playback of the <a href="#media-resource">media
6661: resource</a> is to pause when the cue stops being relevant.</p>
6662: </dd>
6663:
6664: <dt><dfn id="text-track-cue-writing-direction" title="text track cue writing direction">A writing direction</dfn>
6665: </dt><dd>
6666: <p>A writing direction, either <dfn id="text-track-cue-horizontal-writing-direction" title="text track cue
6667: horizontal writing direction">horizontal</dfn> (a line extends
6668: horizontally and is positioned vertically, with consecutive lines
6669: displayed below each other), <dfn id="text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical
6670: growing left writing direction">vertical growing left</dfn> (a
6671: line extends vertically and is positioned horizontally, with
6672: consecutive lines displayed to the left of each other), or <dfn id="text-track-cue-vertical-growing-right-writing-direction" title="text track cue vertical
6673: growing right writing direction">vertical growing right</dfn> (a
6674: line extends vertically and is positioned horizontally, with
6675: consecutive lines displayed to the right of each other).</p>
6676:
6677:
6678: </dd>
6679:
6680:
6681: <dt><dfn id="text-track-cue-size" title="text track cue size">A size</dfn>
6682: </dt><dd>
6683: <p>A number giving the size of the box within which the text of
6684: each line of the cue is to be aligned, to be interpreted as a
6685: percentage of the video, as defined by the <a href="#text-track-cue-writing-direction" title="text
6686: track cue writing direction">writing direction</a>.</p>
6687: </dd>
6688:
6689:
6690: <dt><dfn id="text-track-cue-text" title="text track cue text">The text of the cue</dfn>
6691: </dt><dd>
6692: <p>The raw text of the cue, and rules for its interpretation,
6693: allowing the text to be rendered and converted to a DOM fragment.</p>
6694: </dd>
6695:
6696: </dl><p>A <a href="#text-track-cue">text track cue</a> is immutable.</p><p>Each <a href="#text-track-cue">text track cue</a> has a corresponding
6697: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and can be associated with a
6698: particular <a href="#text-track">text track</a>. Once a <a href="#text-track-cue">text track
6699: cue</a> is associated with a particular <a href="#text-track">text track</a>,
6700: the association is permanent.</p><p>In addition, each <a href="#text-track-cue">text track cue</a> has two pieces of
6701: dynamic information:</p><dl><dt>The <dfn id="text-track-cue-active-flag" title="text track cue active flag">active flag</dfn>
6702: </dt><dd>
6703:
6704: <p>This flag must be initially unset. The flag is used to ensure
6705: events are fired appropriately when the cue becomes active or
6706: inactive, and to make sure the right cues are rendered.</p>
6707:
6708: <p>The user agent must synchronously unset this flag whenever the
6709: <a href="#text-track-cue">text track cue</a> is removed from its <a href="#text-track">text
6710: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>; whenever the
6711: <a href="#text-track">text track</a> itself is removed from its <a href="#media-element">media
6712: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> or has its
6713: <a href="#text-track-mode">text track mode</a> changed to <a href="#text-track-disabled" title="text track
6714: disabled">disabled</a>; and whenever the <a href="#media-element">media
6715: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is changed back to
6716: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>. When the
6717: flag is unset in this way for one or more cues in <a href="#text-track" title="text track">text tracks</a> that were <a href="#text-track-showing" title="text track showing">showing</a> or <a href="#text-track-showing-by-default" title="text
6718: track showing by default">showing by default</a> prior to the
6719: relevant incident, the user agent must, after having unset the
6720: flag for all the affected cues, apply the <a href="#rules-for-updating-the-text-track-rendering">rules for updating
6721: the text track rendering</a> of those <a href="#text-track" title="text
6722: track">text tracks</a>.
6723: </p></dd>
6724:
6725: <dt>The <dfn id="text-track-cue-display-state" title="text track cue display state">display state</dfn>
6726: </dt><dd>
6727:
6728: <p>This is used as part of the rendering model, to keep cues in a
6729: consistent position. It must initially be empty. Whenever the
6730: <a href="#text-track-cue-active-flag">text track cue active flag</a> is unset, the user agent
6731: must empty the <a href="#text-track-cue-display-state">text track cue display state</a>.</p>
6732:
6733: </dd>
6734:
6735: </dl><p>The <a href="#text-track-cue" title="text track cue">text track cues</a> of a
6736: <a href="#media-element">media element</a>'s <a href="#text-track" title="text track">text
6737: tracks</a> are ordered relative to each other in the <dfn id="text-track-cue-order">text
6738: track cue order</dfn>, which is determined as follows: first group
6739: the <a href="#text-track-cue" title="text track cue">cues</a> by their <a href="#text-track">text
6740: track</a>, with the groups being sorted in the same order as
6741: their <a href="#text-track" title="text track">text tracks</a> appear in the
6742: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>;
6743: then, within each group, <a href="#text-track-cue" title="text track cue">cues</a>
6744: must be sorted by their <a href="#text-track-cue-start-time" title="text track cue start
6745: time">start time</a>, earliest first; then, any <a href="#text-track-cue" title="text track cue">cues</a> with the same <a href="#text-track-cue-start-time" title="text
6746: track cue start time">start time</a> must be sorted by their
1.111 mike 6747: <a href="#text-track-cue-end-time" title="text track cue end time">end time</a>, latest
1.47 mike 6748: first; and finally, any <a href="#text-track-cue" title="text track cue">cues</a>
6749: with identical <a href="#text-track-cue-end-time" title="text track cue end time">end
6750: times</a> must be sorted in the order they were created (so
6751: e.g. for cues from a <span>WebVTT</span> file, that would be the
6752: order in which the cues were listed in the file).</p><h6 id="sourcing-in-band-text-tracks"><span class="secno">4.8.10.12.2 </span>Sourcing in-band text tracks</h6><p>A <dfn id="media-resource-specific-text-track">media-resource-specific text track</dfn> is a <a href="#text-track">text
6753: track</a> that corresponds to data found in the <a href="#media-resource">media
6754: resource</a>.</p><div class="impl">
6755:
6756: <p>Rules for processing and rendering such data are defined by the
6757: relevant specifications, e.g. the specification of the video format
6758: if the <a href="#media-resource">media resource</a> is a video.</p>
6759:
6760: <p>When a <a href="#media-resource">media resource</a> contains data that the user
6761: agent recognises and supports as being equivalent to a <a href="#text-track">text
6762: track</a>, the user agent <a href="#found-a-media-resource-specific-timed-track">runs</a> the
6763: <dfn id="steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text track</dfn>
1.122 mike 6764: with the relevant data, as follows.</p>
6765:
6766:
1.47 mike 6767:
6768: <ol><li><p>Associate the relevant data with a new <a href="#text-track">text
6769: track</a> and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6770: object. The <a href="#text-track">text track</a> is a
6771: <a href="#media-resource-specific-text-track">media-resource-specific text track</a>.</p></li>
6772:
6773: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-kind" title="text track
6774: kind">kind</a>, <a href="#text-track-label" title="text track label">label</a>,
6775: and <a href="#text-track-language" title="text track language">language</a> based on the
6776: semantics of the relevant data, as defined by the relevant
6777: specification.</p></li>
6778:
6779: <li><p>Populate the new <a href="#text-track">text track</a>'s <a href="#text-track-list-of-cues" title="text track list of cues">list of cues</a> with the cues
6780: parsed so far, folllowing the <span>guidelines for exposing
6781: cues</span>, and begin updating it dynamically as
6782: necessary.</p></li>
6783:
6784: <li>
6785:
6786: <p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-readiness-state" title="text track
6787: readiness state">readiness state</a> to the value that most
6788: correctly describes the current state, and begin updating it
6789: dynamically as necessary.</p>
6790:
6791: <p class="example">For example, if the relevant data in the
6792: <a href="#media-resource">media resource</a> has been fully parsed and completely
6793: describes the cues, then the <a href="#text-track">text track</a> would be
6794: <a href="#text-track-loaded" title="text track loaded">loaded</a>. On the other hand,
6795: if the data for the cues is interleaved with the <a href="#media-data">media
6796: data</a>, and the <a href="#media-resource">media resource</a> as a whole is
6797: still being downloaded, then the <a href="#text-track-loading" title="text track
6798: loading">loading</a> state might be more accurate.</p>
6799:
6800: </li>
6801:
6802: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-mode" title="text
6803: track mode">mode</a> to the mode consistent with the user's
6804: preferences and the requirements of the relevant specification for
6805: the data.</p></li>
6806:
6807: <li><p>Leave the <a href="#text-track-list-of-cues">text track list of cues</a> empty, and
6808: associate with it the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
6809: rendering</a> appropriate for the format in question.</p>
6810:
6811: </li><li><p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6812: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p></li>
6813:
1.122 mike 6814: <li><p>Fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and is
6815: not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
6816: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code>
6817: attribute initialized to the <a href="#text-track">text track</a>'s
6818: <code><a href="#texttrack">TextTrack</a></code> object, at the <a href="#media-element">media element</a>'s
6819: <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> attribute's
6820: <code><a href="#texttracklist">TextTrackList</a></code> object.</p></li>
6821:
1.47 mike 6822: </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
6823: element's media-resource-specific text tracks</dfn>, the user
6824: agent must remove from the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list
6825: of text tracks</a> all the <a href="#media-resource-specific-text-track" title="media-resource-specific
6826: text track">media-resource-specific text tracks</a>.</p>
6827:
6828: </div><div class="impl">
6829:
6830: <h6 id="sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</h6>
6831:
6832: <p>When a <code><a href="#the-track-element">track</a></code> element is created, it must be
6833: associated with a new <a href="#text-track">text track</a> (with its value set
6834: as defined below) and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6835: object.</p>
6836:
6837: <p>The <a href="#text-track-kind">text track kind</a> is determined from the state of
6838: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute
6839: according to the following table; for a state given in a cell of the
6840: first column, the <a href="#text-track-kind" title="text track kind">kind</a> is the
6841: string given in the second column:</p>
6842:
6843: <table><thead><tr><th>State
6844: </th><th>String
6845: </th></tr></thead><tbody><tr><td><a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</a>
6846: </td><td><code title="dom-timedtrack-kind-subtitles">subtitles</code>
6847: </td></tr><tr><td><a href="#attr-track-kind-captions" title="attr-track-kind-captions">Captions</a>
6848: </td><td><code title="dom-timedtrack-kind-captions">captions</code>
6849: </td></tr><tr><td><a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</a>
6850: </td><td><code title="dom-timedtrack-kind-descriptions">descriptions</code>
6851: </td></tr><tr><td><a href="#attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</a>
6852: </td><td><code title="dom-timedtrack-kind-chapters">chapters</code>
6853: </td></tr><tr><td><a href="#attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</a>
6854: </td><td><code title="dom-timedtrack-kind-metadata">metadata</code>
6855: </td></tr></tbody></table><p>The <a href="#text-track-label">text track label</a> is the element's <a href="#track-label">track
6856: label</a>.</p>
6857:
6858: <p>The <a href="#text-track-language">text track language</a> is the element's
6859: <a href="#track-language">track language</a>, if any, or the empty string
6860: otherwise.</p>
6861:
6862: <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,
6863: changed, or removed, the <a href="#text-track">text track</a> must update
6864: accordingly, as per the definitions above.</p>
6865:
6866: <p class="note">Changes to the <a href="#track-url">track URL</a> are handled in
6867: the algorithm below.</p>
6868:
6869: <p>The <a href="#text-track-list-of-cues">text track list of cues</a> is initially empty. It
6870: is dynamically modified when the referenced file is parsed.
6871: Associated with the list are the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text
6872: track rendering</a> appropriate for the format in question; for
1.101 mike 6873: <span>WebVTT</span>, this is the <a href="rendering.html#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the
1.47 mike 6874: display of WebVTT text tracks</a>.</p>
6875:
6876: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6877: the new parent is a <a href="#media-element">media element</a>, then the user agent
6878: must add the <code><a href="#the-track-element">track</a></code> element's corresponding <a href="#text-track">text
6879: track</a> to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
1.122 mike 6880: tracks</a>, and then <a href="webappapis.html#queue-a-task">queue a task</a> to fire an event
6881: with the name <code title="event-addtrack">addtrack</code>, that
6882: does not bubble and is not cancelable, and that uses the
6883: <code><a href="#trackevent">TrackEvent</a></code> interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized to
6884: the <a href="#text-track">text track</a>'s <code><a href="#texttrack">TextTrack</a></code> object, at the
6885: <a href="#media-element">media element</a>'s <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> attribute's
6886: <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
1.47 mike 6887:
6888: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6889: the old parent was a <a href="#media-element">media element</a>, then the user agent
6890: must remove the <code><a href="#the-track-element">track</a></code> element's corresponding
6891: <a href="#text-track">text track</a> from the <a href="#media-element">media element</a>'s
1.122 mike 6892: <a href="#list-of-text-tracks">list of text tracks</a>.</p>
1.47 mike 6893:
6894: <p>When a <a href="#text-track">text track</a> corresponding to a
6895: <code><a href="#the-track-element">track</a></code> element is added to a <a href="#media-element">media
6896: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, the user agent
6897: must set the <a href="#text-track-mode">text track mode</a> appropriately, as
6898: determined by the following conditions:</p>
6899:
6900: <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
6901: has indicated an interest in having a track with this <a href="#text-track-kind">text
6902: track kind</a>, <a href="#text-track-language">text track language</a>, and
6903: <a href="#text-track-label">text track label</a> enabled, and there is no other
6904: <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6905: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6906: 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
6907: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6908: showing">showing</a></dt>
6909:
6910: <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
6911: the user has indicated an interest in having text descriptions with
6912: this <a href="#text-track-language">text track language</a> and <a href="#text-track-label">text track
6913: label</a> enabled, and there is no other <a href="#text-track">text
6914: track</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
6915: 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
6916: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6917: showing">showing</a></dt>
6918:
1.62 mike 6919: <dd>
6920: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6921: track showing">showing</a>.</p>
6922:
6923: <p>If there is a <a href="#text-track">text track</a> in the <a href="#media-element">media
6924: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6925: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing-by-default" title="text track showing
6926: by default">showing by default</a>, the user agent must
6927: furthermore change <em>that</em> <a href="#text-track">text track</a>'s
6928: <a href="#text-track-mode">text track mode</a> to <a href="#text-track-hidden" title="text track
6929: hidden">hidden</a>.</p>
6930: </dd>
6931:
1.47 mike 6932: <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
6933: <a href="#text-track-language">text track language</a> is one that the user agent has
6934: reason to believe is appropriate for the user, and there is no
6935: other <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6936: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6937: kind</a> of <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> whose
6938: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6939: showing">showing</a></dt>
6940:
6941: <dd>
6942: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6943: track showing">showing</a>.</p>
6944: </dd>
6945:
6946: <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
6947: there is no other <a href="#text-track">text track</a> in the <a href="#media-element">media
6948: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6949: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6950: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track
6951: showing by default">showing by default</a></dt>
6952:
6953: <dd>
6954: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing-by-default" title="text
6955: track showing by default">showing by default</a>.</p>
6956: </dd>
6957:
6958: <dt>Otherwise</dt>
6959:
6960: <dd>
6961: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-disabled" title="text
6962: track disabled">disabled</a>.</p>
6963: </dd>
6964:
6965: </dl><p>When a <a href="#text-track">text track</a> corresponding to a
6966: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6967: mode</a> set to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6968: <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>,
6969: and when a <a href="#text-track">text track</a> corresponding to a
6970: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6971: mode</a> set to <a href="#text-track-disabled" title="text track
6972: disabled">disabled</a> and subsequently changes its <a href="#text-track-mode">text
6973: track mode</a> to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6974: <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
6975: the first time, the user agent must immediately and synchronously
6976: run the following algorithm. This algorithm interacts closely with
6977: the <a href="webappapis.html#event-loop">event loop</a> mechanism; in particular, it has a
6978: <a href="webappapis.html#synchronous-section">synchronous section</a> (which is triggered as part of the
6979: <a href="webappapis.html#event-loop">event loop</a> algorithm). The step in that section is
6980: marked with ⌛.</p>
6981:
6982: <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>
6983:
6984: <li><p>Let <var title="">URL</var> be the <a href="#track-url">track URL</a> of
6985: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6986:
6987: <li><p>Asynchronously run the remaining steps, while continuing
6988: with whatever task was responsible for creating the <a href="#text-track">text
6989: track</a> or changing the <a href="#text-track-mode">text track
6990: mode</a>.</p></li>
6991:
6992: <li>
6993:
1.61 mike 6994: <p><i>Download</i>: At this point, the text track is downloaded.</p>
6995:
6996: <p>If <var title="">URL</var> is not the empty string, perform a
6997: <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
6998: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
1.128 mike 6999: attribute, the <i title="">origin</i> being the <a href="origin-0.html#origin">origin</a> of the
1.61 mike 7000: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
7001: <i>default origin behaviour</i> set to <i>fail</i>.</p>
7002:
7003: <p>The resource obtained in this fashion, if any, contains the
7004: text track data. If any data is obtained, it is by definition
7005: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a> (cross-origin resources that are not
7006: suitably CORS-enabled do not get this far).</p>
7007:
1.47 mike 7008: <p>The <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue
7009: a task">queued</a> by the <a href="fetching-resources.html#fetch" title="fetch">fetching
7010: algorithm</a> on the <a href="webappapis.html#networking-task-source">networking task source</a> to
7011: process the data as it is being fetched must examine the
7012: resource's <a href="fetching-resources.html#content-type" title="Content-Type">Content Type
7013: 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
7014: available, or if the type is not recognised as a text track
7015: format, then the resource's format must be assumed to be
7016: unsupported (this causes the load to fail, as described below). If
7017: a type is obtained, and represents a supported text track format,
7018: then the resource's data must be passed to the appropriate parser
7019: as it is received, with the <a href="#text-track-list-of-cues">text
7020: track list of cues</a> being used for that parser's output.</p>
7021:
7022: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> fails for
7023: any reason (network error, the server returns an error code, a
1.61 mike 7024: cross-origin check fails, etc), if <var title="">URL</var> is the
7025: empty string, or if the fetched resource is not in a supported
7026: format, then <a href="webappapis.html#queue-a-task">queue a task</a> to first change the
7027: <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-failed-to-load" title="text track
7028: failed to load">failed to load</a> and then <a href="webappapis.html#fire-a-simple-event">fire a simple
7029: event</a> named <code title="event-error">error</code> at the
7030: <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 7031: task">queued</a>, move on to the step below labeled
7032: <i>monitoring</i>.</p>
7033:
7034: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> does not
1.99 mike 7035: fail, then, when it completes, <a href="webappapis.html#queue-a-task">queue a task</a> to run
7036: the following steps:</p>
7037:
7038: <ol><li><p>Change the <a href="#text-track-readiness-state">text track readiness state</a> to
7039: <a href="#text-track-loaded" title="text track loaded">loaded</a>.</p></li>
7040:
7041: <li>
7042:
7043: <p>If the file was successfully processed, <a href="webappapis.html#fire-a-simple-event">fire a simple
7044: event</a> named <code title="event-load">load</code> at the
7045: <code><a href="#the-track-element">track</a></code> element.</p>
7046:
7047: <p>If the file was not successfully processed, e.g. the format
7048: in question is an XML format and the file contained a
7049: well-formedness error that the XML specification requires be
7050: detected and reported to the application, then <a href="webappapis.html#fire-a-simple-event">fire a
7051: simple event</a> named <code title="event-error">error</code>
7052: at the <code><a href="#the-track-element">track</a></code> element.</p>
7053:
7054: <p class="note">The WebVTT format does not report errors in this
7055: fashion.</p>
7056:
7057: </li>
7058:
7059: </ol><p>Once that <a href="webappapis.html#concept-task" title="concept-task">task</a> is <a href="webappapis.html#queue-a-task" title="queue a task">queued</a>, move on to the step below
7060: labeled <i>monitoring</i>.</p>
1.47 mike 7061:
7062: <p>If, while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> is
7063: active, either:</p>
7064:
7065: <ul><li>the <a href="#track-url">track URL</a> changes so that it is no longer
7066: equal to <var title="">URL</var>, while the <a href="#text-track-mode">text track
7067: mode</a> is set to <a href="#text-track-hidden" title="text track
7068: hidden">hidden</a>, <a href="#text-track-showing" title="text track
7069: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
7070: default">showing by default</a>; or</li>
7071:
7072: <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
7073: track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track
7074: showing by default">showing by default</a>, while the
7075: <a href="#track-url">track URL</a> is not equal to <var title="">URL</var></li>
7076:
7077: </ul><p>...then the user agent must run the following steps:</p>
7078:
7079: <ol><li><p>Abort the <a href="fetching-resources.html#fetch" title="fetch">fetching
7080: algorithm</a>.</p></li>
7081:
7082: <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
7083: event</a> named <code title="event-abort">abort</code> at
7084: the <code><a href="#the-track-element">track</a></code> element.</p></li>
7085:
7086: <li><p>Let <var title="">URL</var> be the new <a href="#track-url">track
7087: URL</a>.</p></li>
7088:
7089: <li><p>Jump back to the top of the step labeled
7090: <i>download</i>.</p></li>
7091:
7092: </ol><p>Until one of the above circumstances occurs, the user agent
7093: must remain on this step.</p>
7094:
7095: </li>
7096:
7097: <li><p><i>Monitoring</i>: Wait until the <a href="#track-url">track URL</a> is
7098: no longer equal to <var title="">URL</var>, at the same time as the
7099: <a href="#text-track-mode">text track mode</a> is set to <a href="#text-track-hidden" title="text track
7100: hidden">hidden</a>, <a href="#text-track-showing" title="text track
7101: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
7102: default">showing by default</a>.</p></li>
7103:
7104: <li><p>Wait until the <a href="#text-track-readiness-state">text track readiness state</a> is
7105: no longer set to <a href="#text-track-loading" title="text track
7106: loading">loading</a>.</p></li>
7107:
7108: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
7109: section</a> consists of the following step. (The step in the
7110: <a href="webappapis.html#synchronous-section">synchronous section</a> is marked with ⌛.)</p></li>
7111:
7112: <li><p>⌛ Set the <a href="#text-track-readiness-state">text track readiness state</a> to
7113: <a href="#text-track-loading" title="text track loading">loading</a>.</p></li>
7114:
7115:
7116: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
7117: remaining steps asynchronously.</p></li>
7118:
7119: <li><p>Jump to the step labeled <i>download</i>.</p></li>
7120:
1.121 mike 7121: </ol></div><h6 id="text-track-api"><span class="secno">4.8.10.12.4 </span>Text track API</h6><pre class="idl">interface <dfn id="texttracklist">TextTrackList</dfn> {
7122: readonly attribute unsigned long <a href="#dom-texttracklist-length" title="dom-TextTrackList-length">length</a>;
7123: getter <a href="#texttrack">TextTrack</a> (unsigned long index);
7124:
7125: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttracklist-onaddtrack" title="handler-TextTrackList-onaddtrack">onaddtrack</a>;
7126: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> . <code title="">length</code></dt>
1.47 mike 7127: <dd>
7128: <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>
7129: </dd>
7130:
7131: <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>
7132: <dd>
7133: <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>
7134: </dd>
7135:
7136: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
7137: <dd>
7138: <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>
7139: </dd>
7140:
7141: </dl><div class="impl">
7142:
1.121 mike 7143: <p>A <code><a href="#texttracklist">TextTrackList</a></code> object represents a dynamically
7144: updating list of <a href="#text-track" title="text track">text tracks</a> in a
7145: given order.</p>
7146:
7147: <p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn> attribute
7148: of <a href="#media-element" title="media element">media elements</a> must return a
7149: <code><a href="#texttracklist">TextTrackList</a></code> object representing the
7150: <code><a href="#texttrack">TextTrack</a></code> objects of the <a href="#text-track" title="text track">text
7151: tracks</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
7152: tracks</a>, in the same order as in the <a href="#list-of-text-tracks">list of text
7153: tracks</a>. The same object must be returned each time the
7154: attribute is accessed. <a href="references.html#refsWEBIDL">[WEBIDL]</a></p>
7155:
7156: <p>The <dfn id="dom-texttracklist-length" title="dom-TextTrackList-length"><code>length</code></dfn> attribute
7157: of a <code><a href="#texttracklist">TextTrackList</a></code> object must return the number of
7158: <a href="#text-track" title="text track">text tracks</a> in the list represented
7159: by the <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
7160:
7161: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of a
7162: <code><a href="#texttracklist">TextTrackList</a></code> object at any instant are the numbers
7163: from zero to the number of <a href="#text-track" title="text track">text
7164: tracks</a> in the list represented by the
7165: <code><a href="#texttracklist">TextTrackList</a></code> object minus one, if any. If there are no
7166: <a href="#text-track" title="text track">text tracks</a> in the list, there are
7167: no <a href="infrastructure.html#supported-property-indices">supported property indices</a>.</p>
7168:
7169: <p>To <a href="infrastructure.html#determine-the-value-of-an-indexed-property">determine the value of an indexed property</a> of a
7170: <code><a href="#texttracklist">TextTrackList</a></code> object for a given index <var title="">index</var>, the user agent must return the <var title="">index</var>th <a href="#text-track">text track</a> in the list
7171: represented by the <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
1.47 mike 7172:
1.86 mike 7173: </div><hr><pre class="idl">interface <dfn id="texttrack">TextTrack</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.47 mike 7174: readonly attribute DOMString <a href="#dom-texttrack-kind" title="dom-TextTrack-kind">kind</a>;
7175: readonly attribute DOMString <a href="#dom-texttrack-label" title="dom-TextTrack-label">label</a>;
7176: readonly attribute DOMString <a href="#dom-texttrack-language" title="dom-TextTrack-language">language</a>;
7177:
1.117 mike 7178: const unsigned short <a href="#dom-texttrack-disabled" title="dom-TextTrack-DISABLED">DISABLED</a> = 0;
1.47 mike 7179: const unsigned short <a href="#dom-texttrack-hidden" title="dom-TextTrack-HIDDEN">HIDDEN</a> = 1;
7180: const unsigned short <a href="#dom-texttrack-showing" title="dom-TextTrack-SHOWING">SHOWING</a> = 2;
7181: attribute unsigned short <a href="#dom-texttrack-mode" title="dom-TextTrack-mode">mode</a>;
7182:
1.68 mike 7183: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a>? <a href="#dom-texttrack-cues" title="dom-TextTrack-cues">cues</a>;
7184: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a>? <a href="#dom-texttrack-activecues" title="dom-TextTrack-activeCues">activeCues</a>;
1.47 mike 7185:
1.132 ! mike 7186: void <a href="#dom-texttrack-addcue" title="dom-TextTrack-addCue">addCue</a>(<a href="#texttrackcue">TextTrackCue</a> cue);
! 7187: void <a href="#dom-texttrack-removecue" title="dom-TextTrack-removeCue">removeCue</a>(<a href="#texttrackcue">TextTrackCue</a> cue);
! 7188:
1.118 mike 7189: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
1.110 mike 7190: };</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 7191: <dd>
7192: <p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
7193: </dd>
7194:
7195: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-label"><a href="#dom-texttrack-label">label</a></code></dt>
7196: <dd>
7197: <p>Returns the <a href="#text-track-label">text track label</a>.</p>
7198: </dd>
7199:
7200: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-language"><a href="#dom-texttrack-language">language</a></code></dt>
7201: <dd>
7202: <p>Returns the <a href="#text-track-language">text track language</a> string.</p>
7203: </dd>
7204:
1.128 mike 7205: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> [ = <var title="">value</var> ]</dt>
1.47 mike 7206: <dd>
7207: <p>Returns the <a href="#text-track-mode">text track mode</a>, represented by a
7208: number from the following list:</p>
1.117 mike 7209: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-DISABLED"><a href="#dom-texttrack-disabled">DISABLED</a></code> (0)</dt>
1.47 mike 7210: <dd>
7211: <p>The <a href="#text-track-disabled">text track disabled</a> mode.</p>
7212: </dd>
7213: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-HIDDEN"><a href="#dom-texttrack-hidden">HIDDEN</a></code> (1)</dt>
7214: <dd>
7215: <p>The <a href="#text-track-hidden">text track hidden</a> mode.</p>
7216: </dd>
7217: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-SHOWING"><a href="#dom-texttrack-showing">SHOWING</a></code> (2)</dt>
7218: <dd>
7219: <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>
7220: </dd>
7221: </dl><p>Can be set, to change the mode.</p>
7222: </dd>
7223:
7224: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-cues"><a href="#dom-texttrack-cues">cues</a></code></dt>
7225: <dd>
7226: <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>
7227: </dd>
7228:
7229: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-activeCues"><a href="#dom-texttrack-activecues">activeCues</a></code></dt>
7230: <dd>
7231: <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>
7232: </dd>
7233:
1.132 ! mike 7234: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-addCue"><a href="#dom-texttrack-addcue">addCue</a></code>( <var title="">cue</var> )</dt>
! 7235: <dd>
! 7236: <p>Adds the given cue to <var title="">textTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
! 7237: <p>Throws an exception if the argument is associated with another <a href="#text-track">text track</a> or already in the list of cues.</p>
! 7238: </dd>
! 7239:
! 7240: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-removeCue"><a href="#dom-texttrack-removecue">removeCue</a></code>( <var title="">cue</var> )</dt>
! 7241: <dd>
! 7242: <p>Removes the given cue from <var title="">textTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
! 7243: <p>Throws an exception if the argument is associated with another <a href="#text-track">text track</a> or not in the list of cues.</p>
! 7244: </dd>
! 7245:
! 7246: <dt><var title="">textTrack</var> = <var title="">media</var> . <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack</a></code>( <var title="">kind</var> [, <var title="">label</var> [, <var title="">language</var> ] ] )</dt>
! 7247: <dd>
! 7248: <p>Creates and returns a new <code><a href="#texttrack">TextTrack</a></code> object, which is also added to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
! 7249: </dd>
! 7250:
1.47 mike 7251: </dl><div class="impl">
7252:
7253: <p>The <dfn id="dom-texttrack-kind" title="dom-TextTrack-kind"><code>kind</code></dfn>
7254: attribute must return the <a href="#text-track-kind">text track kind</a> of the
7255: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7256: represents.</p>
7257:
7258: <p>The <dfn id="dom-texttrack-label" title="dom-TextTrack-label"><code>label</code></dfn>
7259: attribute must return the <a href="#text-track-label">text track label</a> of the
7260: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7261: represents.</p>
7262:
7263: <p>The <dfn id="dom-texttrack-language" title="dom-TextTrack-language"><code>language</code></dfn>
7264: attribute must return the <a href="#text-track-language">text track language</a> of the
7265: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7266: represents.</p>
7267:
1.130 mike 7268: <p>The <dfn id="dom-texttrack-mode" title="dom-TextTrack-mode"><code>mode</code></dfn>
1.47 mike 7269: attribute, on getting, must return the numeric value corresponding
7270: to the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text track</a>
7271: that the <code><a href="#texttrack">TextTrack</a></code> object represents, as defined by
7272: the following list:</p>
7273:
1.117 mike 7274: <dl><dt><dfn id="dom-texttrack-disabled" title="dom-TextTrack-DISABLED"><code>DISABLED</code></dfn> (numeric value 0)</dt>
1.47 mike 7275: <dd>The <a href="#text-track-disabled">text track disabled</a> mode.</dd>
7276: <dt><dfn id="dom-texttrack-hidden" title="dom-TextTrack-HIDDEN"><code>HIDDEN</code></dfn> (numeric value 1)</dt>
7277: <dd>The <a href="#text-track-hidden">text track hidden</a> mode.</dd>
7278: <dt><dfn id="dom-texttrack-showing" title="dom-TextTrack-SHOWING"><code>SHOWING</code></dfn> (numeric value 2)</dt>
7279: <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>
7280: </dl><p>On setting, if the new value is not either 0, 1, or 2, the user
1.119 mike 7281: agent must throw an <code><a href="infrastructure.html#invalidaccesserror">InvalidAccessError</a></code>
1.47 mike 7282: exception. Otherwise, if the new value isn't equal to what the
7283: attribute would currently return, the new value must be processed as
7284: follows:</p>
7285:
7286: <dl class="switch"><dt>If the new value is 0</dt>
7287:
7288: <dd>
7289:
7290: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7291: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7292: the <a href="#text-track-disabled">text track disabled</a> mode.</p>
7293:
7294: </dd>
7295:
7296: <dt>If the new value is 1</dt>
7297:
7298: <dd>
7299:
7300: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7301: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7302: the <a href="#text-track-hidden">text track hidden</a> mode.</p>
7303:
7304: </dd>
7305:
7306: <dt>If the new value is 2</dt>
7307:
7308: <dd>
7309:
7310: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7311: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
7312: the <a href="#text-track-showing">text track showing</a> mode.</p>
7313:
7314: <p class="note">If the mode had been <a href="#text-track-showing-by-default" title="text track
7315: showing by default">showing by default</a>, this will change it
7316: to <a href="#text-track-showing" title="text track showing">showing</a>, even though
7317: the value of <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> would
7318: appear not to change.</p>
7319:
7320: </dd>
7321:
7322: </dl><p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7323: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
7324: not the <a href="#text-track-disabled">text track disabled</a> mode, then the <dfn id="dom-texttrack-cues" title="dom-TextTrack-cues"><code>cues</code></dfn> attribute must
1.104 mike 7325: return a <a href="infrastructure.html#live">live</a> <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that
7326: represents the subset of the <a href="#text-track-list-of-cues">text track list of cues</a> of
7327: the <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
7328: represents whose <a href="#text-track-cue-start-time" title="text track cue start time">start
7329: times</a> occur at or after the <a href="#earliest-possible-position-when-the-script-started">earliest possible position
7330: when the script started</a>, in <a href="#text-track-cue-order">text track cue
7331: order</a>. Otherwise, it must return null. When an object is
7332: returned, the same object must be returned each time.</p>
1.47 mike 7333:
7334: <p>The <dfn id="earliest-possible-position-when-the-script-started">earliest possible position when the script started</dfn>
7335: is whatever the <a href="#earliest-possible-position">earliest possible position</a> was the last
7336: time the <a href="webappapis.html#event-loop">event loop</a> reached step 1.</p>
7337:
7338: <p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
7339: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
7340: 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>
7341: attribute must return a <a href="infrastructure.html#live">live</a>
7342: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that represents the subset of
7343: the <a href="#text-track-list-of-cues">text track list of cues</a> of the <a href="#text-track">text
7344: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents
7345: whose <a href="#active-flag-was-set-when-the-script-started">active flag was set when the script started</a>, in
7346: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
7347: null. When an object is returned, the same object must be returned
7348: each time.</p>
7349:
7350: <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
7351: the script started</dfn> if its <a href="#text-track-cue-active-flag">text track cue active
7352: flag</a> was set the last time the <a href="webappapis.html#event-loop">event loop</a>
7353: reached step 1.</p>
7354:
1.132 ! mike 7355: <hr><p>The <dfn id="dom-texttrack-addcue" title="dom-TextTrack-addCue"><code>addCue(<var title="">cue</var>)</code></dfn> method of <code><a href="#texttrack">TextTrack</a></code>
! 7356: objects, when invoked, must run the following steps:</p>
1.47 mike 7357:
1.132 ! mike 7358: <ol><li><p>If the given <var title="">cue</var> is already associated
! 7359: with a <a href="#text-track">text track</a> other than the method's
! 7360: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>, then throw
! 7361: an <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception and abort these
! 7362: steps.</p></li>
! 7363:
! 7364: <li><p>Associate <var title="">cue</var> with the method's
! 7365: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>, if it is
! 7366: not currently associated with a <a href="#text-track">text track</a>.</p></li>
! 7367:
! 7368: <li><p>If the given <var title="">cue</var> is already listed in
! 7369: the method's <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text
! 7370: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw an
! 7371: <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code> exception.</p></li>
! 7372:
! 7373: <li><p>Add <var title="">cue</var> to the method's
! 7374: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>'s
! 7375: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
! 7376:
! 7377: </ol><p>The <dfn id="dom-texttrack-removecue" title="dom-TextTrack-removeCue"><code>removeCue(<var title="">cue</var>)</code></dfn> method of
! 7378: <code><a href="#texttrack">TextTrack</a></code> objects, when invoked, must run the
! 7379: following steps:</p>
1.47 mike 7380:
1.132 ! mike 7381: <ol><li><p>If the given <var title="">cue</var> is not associated with
! 7382: the method's <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text
! 7383: track</a>, then throw an <code><a href="infrastructure.html#invalidstateerror">InvalidStateError</a></code>
! 7384: exception.</p></li>
1.47 mike 7385:
1.132 ! mike 7386: <li><p>If the given <var title="">cue</var> is not currently listed
! 7387: in the method's <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text
! 7388: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw a
! 7389: <code><a href="infrastructure.html#notfounderror">NotFoundError</a></code> exception.</p></li>
1.47 mike 7390:
1.132 ! mike 7391: <li><p>Remove <var title="">cue</var> from the method's
! 7392: <code><a href="#texttrack">TextTrack</a></code> object's <a href="#text-track">text track</a>'s
! 7393: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
1.47 mike 7394:
1.132 ! mike 7395: </ol><hr><p>The <dfn id="dom-media-addtexttrack" title="dom-media-addTextTrack"><code>addTextTrack(<var title="">kind</var>, <var title="">label</var>, <var title="">language</var>)</code></dfn> method of <a href="#media-element" title="media
1.47 mike 7396: element">media elements</a>, when invoked, must run the following
7397: steps:</p>
7398:
7399: <ol><li>
7400:
7401: <p>If <var title="">kind</var> is not one of the following
1.119 mike 7402: strings, then throw a <code><a href="infrastructure.html#syntaxerror">SyntaxError</a></code> exception and abort
1.47 mike 7403: these steps:</p>
7404:
7405: <ul class="brief"><li><code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code>
7406: </li><li><code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code>
7407: </li><li><code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code>
7408: </li><li><code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code>
7409: </li><li><code title="dom-TextTrack-kind-metadata"><a href="#dom-texttrack-kind-metadata">metadata</a></code>
7410: </li></ul></li>
7411:
7412: <li>
7413:
7414: <p>If the <var title="">label</var> argument was omitted, let <var title="">label</var> be the empty string.</p>
7415:
7416: </li>
7417:
7418: <li>
7419:
7420: <p>If the <var title="">language</var> argument was omitted, let
7421: <var title="">language</var> be the empty string.</p>
7422:
7423: </li>
7424:
7425: <li>
7426:
1.132 ! mike 7427: <p>Create a new <code><a href="#texttrack">TextTrack</a></code> object.</p>
1.102 mike 7428:
7429: </li>
7430:
7431: <li>
7432:
7433: <p>Create a new <a href="#text-track">text track</a> corresponding to the new
7434: object, and set its <a href="#text-track-kind">text track kind</a> to <var title="">kind</var>, its <a href="#text-track-label">text track label</a> to <var title="">label</var>, its <a href="#text-track-language">text track language</a> to <var title="">language</var>, its <a href="#text-track-readiness-state">text track readiness
7435: state</a> to the <a href="#text-track-loaded">text track loaded</a> state, its
7436: <a href="#text-track-mode">text track mode</a> to the <a href="#text-track-hidden">text track hidden</a>
7437: mode, and its <a href="#text-track-list-of-cues">text track list of cues</a> to an empty
7438: list.
1.47 mike 7439: </p>
7440:
7441: </li>
7442:
7443: <li>
7444:
7445: <p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
7446: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
7447:
1.102 mike 7448: </li>
7449:
7450: <li>
7451:
1.122 mike 7452: <p><a href="webappapis.html#queue-a-task">Queue a task</a> to fire an event with the name <code title="event-addtrack">addtrack</code>, that does not bubble and
7453: is not cancelable, and that uses the <code><a href="#trackevent">TrackEvent</a></code>
7454: interface, with the <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code> attribute initialized to
1.132 ! mike 7455: the new <a href="#text-track">text track</a>'s <code><a href="#texttrack">TextTrack</a></code> object,
! 7456: at the <a href="#media-element">media element</a>'s <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> attribute's
1.122 mike 7457: <code><a href="#texttracklist">TextTrackList</a></code> object.</p>
7458:
7459: </li>
7460:
7461: <li>
7462:
1.132 ! mike 7463: <p>Return the new <code><a href="#texttrack">TextTrack</a></code> object.</p>
1.102 mike 7464:
7465: </li>
7466:
1.47 mike 7467: </ol></div><div class="example">
7468:
7469: <p>In this example, an <code><a href="#the-audio-element">audio</a></code> element is used to play a
7470: specific sound-effect from a sound file containing many sound
7471: effects. A cue is used to pause the audio, so that it ends exactly
7472: at the end of the clip, even if the browser is busy running some
7473: script. If the page had relied on script to pause the audio, then
7474: the start of the next clip might be heard if the browser was not
7475: able to run the script at the exact time specified.</p>
7476:
7477: <pre>var sfx = new Audio('sfx.wav');
7478: var sounds = a.addTextTrack('metadata');
7479:
7480: // add sounds we care about
7481: sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
7482: sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));
7483:
7484: function playSound(id) {
7485: sfx.currentTime = sounds.getCueById(id).startTime;
7486: sfx.play();
7487: }
7488:
7489: sfx.oncanplaythrough = function () {
7490: playSound('dog bark');
7491: }
7492: window.onbeforeunload = function () {
7493: playSound('kitten mew');
7494: return 'Are you sure you want to leave this awesome page?';
7495: }</pre>
7496:
7497: </div><hr><pre class="idl">interface <dfn id="texttrackcuelist">TextTrackCueList</dfn> {
7498: readonly attribute unsigned long <a href="#dom-texttrackcuelist-length" title="dom-TextTrackCueList-length">length</a>;
1.101 mike 7499: getter <a href="#texttrackcue">TextTrackCue</a> (unsigned long index);
7500: <a href="#texttrackcue">TextTrackCue</a>? <a href="#dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById">getCueById</a>(DOMString id);
1.47 mike 7501: };</pre><dl class="domintro"><dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-length"><a href="#dom-texttrackcuelist-length">length</a></code></dt>
7502: <dd>
7503: <p>Returns the number of <a href="#text-track-cue" title="text track cue">cues</a> in the list.</p>
7504: </dd>
7505:
7506: <dt><var title="">cuelist</var>[<var title="">index</var>]</dt>
7507: <dd>
7508: <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>
7509: </dd>
7510:
7511: <dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-getCueById"><a href="#dom-texttrackcuelist-getcuebyid">getCueById</a></code>( <var title="">id</var> )</dt>
7512: <dd>
7513: <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>
7514: <p>Returns null if none of the cues have the given identifier or if the argument is the empty string.</p>
7515: </dd>
7516:
7517: </dl><div class="impl">
7518:
7519: <p>A <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object represents a dynamically
7520: updating list of <a href="#text-track-cue" title="text track cue">text track
7521: cues</a> in a given order.</p>
7522:
7523: <p>The <dfn id="dom-texttrackcuelist-length" title="dom-TextTrackCueList-length"><code>length</code></dfn>
7524: attribute must return the number of <a href="#text-track-cue" title="text track
7525: cue">cues</a> in the list represented by the
7526: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7527:
1.76 mike 7528: <p>The <a href="infrastructure.html#supported-property-indices">supported property indices</a> of a
1.47 mike 7529: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
7530: from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
7531: in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
7532: minus one, if any. If there are no <a href="#text-track-cue" title="text track
1.76 mike 7533: cue">cues</a> in the list, there are no <a href="infrastructure.html#supported-property-indices">supported property
7534: indices</a>.</p>
1.47 mike 7535:
1.76 mike 7536: <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 7537: given index <var title="">index</var>, the user agent must return
7538: the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
7539: list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7540:
7541: <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
7542: other than the empty string, must return the first <a href="#text-track-cue">text track
7543: cue</a> in the list represented by the
7544: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object whose <a href="#text-track-cue-identifier">text track cue
7545: identifier</a> is <var title="">id</var>, if any, or null
7546: otherwise. If the argument is the empty string, then the method must
7547: return null.</p>
7548:
7549: </div><hr><pre class="idl">
1.132 ! mike 7550: [<span title="dom-TextTrackCue">Constructor</span>(DOMString id, double startTime, double endTime, DOMString text, optional DOMString settings, optional boolean pauseOnExit)]
1.86 mike 7551: interface <dfn id="texttrackcue">TextTrackCue</dfn> : <a href="infrastructure.html#eventtarget">EventTarget</a> {
1.68 mike 7552: readonly attribute <a href="#texttrack">TextTrack</a>? <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a>;
1.47 mike 7553: readonly attribute DOMString <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a>;
7554:
7555: readonly attribute double <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a>;
7556: readonly attribute double <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a>;
7557: readonly attribute boolean <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a>;
7558:
7559:
7560: DOMString <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>();
7561: <a href="infrastructure.html#documentfragment">DocumentFragment</a> <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>();
7562:
1.118 mike 7563: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter">onenter</a>;
7564: [TreatNonCallableAsNull] attribute <a href="webappapis.html#function">Function</a>? <a href="#handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit">onexit</a>;
1.132 ! mike 7565: };</pre><dl class="domintro"><dt><var title="">cue</var> = new <code title="dom-TextTrackCue">TextTrackCue</code>( <var title="">id</var>, <var title="">startTime</var>, <var title="">endTime</var>, <var title="">text</var> [, <var title="">settings</var> [, <var title="">pauseOnExit</var> ] ] )</dt>
! 7566: <dd>
! 7567: <p>Returns a new <code><a href="#texttrackcue">TextTrackCue</a></code> object, for use with the <code title="dom-TextTrack-addCue"><a href="#dom-texttrack-addcue">addCue()</a></code> method.</p>
! 7568: <p>The <var title="">id</var> argument sets the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
! 7569: <p>The <var title="">startTime</var> argument sets the <a href="#text-track-cue-start-time">text track cue start time</a>.</p>
! 7570: <p>The <var title="">endTime</var> argument sets the <a href="#text-track-cue-end-time">text track cue end time</a>.</p>
! 7571: <p>The <var title="">text</var> argument sets the <a href="#text-track-cue-text">text track cue text</a>.</p>
! 7572: <p>The <var title="">settings</var> argument is a string in the format of <span>WebVTT cue settings</span>. If omitted, the empty string is assumed.</p>
! 7573: <p>The <var title="">pauseOnExit</var> argument sets the <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit flag</a>. If omitted, false is assumed.</p>
! 7574: </dd>
! 7575:
! 7576: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a></dt>
1.47 mike 7577: <dd>
7578: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object to which this
7579: <a href="#text-track-cue">text track cue</a> belongs, if any, or null
7580: otherwise.</p>
7581: </dd>
7582:
7583: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a></dt>
7584: <dd>
7585: <p>Returns the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
7586: </dd>
7587:
7588: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a></dt>
7589: <dd>
7590: <p>Returns the <a href="#text-track-cue-start-time">text track cue start time</a>, in seconds.</p>
7591: </dd>
7592:
7593: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a></dt>
7594: <dd>
7595: <p>Returns the <a href="#text-track-cue-end-time">text track cue end time</a>, in seconds.</p>
7596: </dd>
7597:
7598: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a></dt>
7599: <dd>
7600: <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>
7601: </dd>
7602:
7603:
7604: <dt><var title="">source</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>()</dt>
7605: <dd>
7606: <p>Returns the <a href="#text-track-cue-text">text track cue text</a> in raw unparsed form.</p>
7607: </dd>
7608:
7609: <dt><var title="">fragment</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>()</dt>
7610: <dd>
7611: <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>
7612: </dd>
7613:
7614: </dl><div class="impl">
7615:
7616:
7617: <p>The <dfn id="dom-texttrackcue-track" title="dom-TextTrackCue-track"><code>track</code></dfn>
7618: attribute must return the <code><a href="#texttrack">TextTrack</a></code> object of the
7619: <a href="#text-track">text track</a> with which the <a href="#text-track-cue">text track cue</a>
7620: that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is associated,
7621: if any; or null otherwise.</p>
7622:
7623: <p>The <dfn id="dom-texttrackcue-id" title="dom-TextTrackCue-id"><code>id</code></dfn>
7624: attribute must return the <a href="#text-track-cue-identifier">text track cue identifier</a> of
7625: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7626: object represents.</p>
7627:
7628: <p>The <dfn id="dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime"><code>startTime</code></dfn>
7629: attribute must return the <a href="#text-track-cue-start-time">text track cue start time</a> of
7630: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7631: object represents, in seconds.</p>
7632:
7633: <p>The <dfn id="dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime"><code>endTime</code></dfn>
7634: attribute must return the <a href="#text-track-cue-end-time">text track cue end time</a> of
7635: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7636: object represents, in seconds.</p>
7637:
7638: <p>The <dfn id="dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit"><code>pauseOnExit</code></dfn>
7639: attribute must return true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue
7640: pause-on-exit flag</a> of the <a href="#text-track-cue">text track cue</a> that
7641: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
7642: otherwise.</p>
7643:
7644: <p>The <dfn id="dom-texttrackcue-direction" title="dom-TextTrackCue-direction"><code>direction</code></dfn>
1.123 mike 7645: attribute must return the string from the second cell of the row in
7646: the table below whose first cell is the <a href="#text-track-cue-writing-direction">text track cue
7647: writing direction</a> of the <a href="#text-track-cue">text track cue</a> that the
7648: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents:</p>
7649:
7650: <table><thead><tr><th> <a href="#text-track-cue-writing-direction">Text track cue writing direction</a>
7651: </th><th> <code title="dom-TextTrackCue-direction"><a href="#dom-texttrackcue-direction">direction</a></code> value
7652: </th></tr></thead><tbody><tr><td> <a href="#text-track-cue-horizontal-writing-direction" title="text track cue horizontal writing direction">Horizontal</a>
7653: </td><td> "<code title="">horizontal</code>"
7654: </td></tr><tr><td> <a href="#text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical growing left writing direction">Vertical growing left</a>
7655: </td><td> "<code title="">vertical</code>"
7656: </td></tr><tr><td> <a href="#text-track-cue-vertical-growing-right-writing-direction" title="text track cue vertical growing right writing direction">Vertical growing right</a>
7657: </td><td> "<code title="">vertical-lr</code>"
7658: </td></tr></tbody></table><p>The <dfn id="dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource"><code>getCueAsSource()</code></dfn>
1.47 mike 7659: method must return the raw <a href="#text-track-cue-text">text track cue text</a>.</p>
7660:
7661: <p>The <dfn id="dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML"><code>getCueAsHTML()</code></dfn>
7662: method must convert the <a href="#text-track-cue-text">text track cue text</a> to a
7663: <code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> for the <a href="#media-element">media element</a>'s
7664: <code><a href="infrastructure.html#document">Document</a></code>, using the appropriate rules for doing
7665: so.
7666: </p>
7667:
1.91 mike 7668: </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
7669: given title. Chapters can be nested, in the same way that sections
7670: 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>
7671: being used for describing chapters has three key features: the
7672: <a href="#text-track-cue-start-time">text track cue start time</a>, giving the start time of the
7673: chapter, the <a href="#text-track-cue-end-time">text track cue end time</a>, giving the end
7674: time of the chapter, and the <a href="#text-track-cue-text">text track cue text</a> giving
7675: the chapter title.</p><div class="impl">
7676:
7677: <p>The <dfn id="rules-for-constructing-the-chapter-tree-from-a-text-track">rules for constructing the chapter tree from a text
7678: track</dfn> are as follows. They produce a potentially nested list
7679: of chapters, each of which have a start time, end time, title, and a
7680: list of nested chapters. This algorithm discards cues that do not
7681: correctly nest within each other, or that are out of order.</p>
7682:
7683: <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
7684: <a href="#text-track">text track</a> being processed.</p></li>
7685:
7686: <li><p>Let <var title="">output</var> be an empty list of chapters,
7687: where a chapter is a record consisting of a start time, an end
7688: time, a title, and a (potentially empty) list of nested chapters.
7689: For the purpose of this algorithm, each chapter also has a parent
7690: chapter.</p></li>
7691:
7692: <li><p>Let <var title="">current chapter</var> be a stand-in
7693: chapter whose start time is negative infinity, whose end time is
7694: positive infinity, and whose list of nested chapters is <var title="">output</var>. (This is just used to make the algorithm
7695: easier to describe.)</p></li>
7696:
7697:
7698: <li><p><i>Loop</i>: If <var title="">list</var> is empty, jump to
7699: the step labeled <i>end</i>.</p></li>
7700:
7701:
7702: <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>
7703:
7704: <li><p>If <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track cue
7705: start time</a> is less than the start time of <var title="">current chapter</var>, then return to the step labeled
7706: <i>loop</i>.</p>
7707:
7708: </li><li><p>While <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track cue
7709: start time</a> is greater than or equal to <var title="">current
7710: chapter</var>'s end time, let <var title="">current chapter</var>
7711: be <var title="">current chapter</var>'s parent chapter.</p></li>
7712:
7713: <li><p>If <var title="">current cue</var>'s <a href="#text-track-cue-end-time">text track cue
7714: end time</a> is greater than the end time of <var title="">current chapter</var>, then return to the step labeled
7715: <i>loop</i>.</p>
7716:
7717: </li><li><p>Create a new chapter <var title="">new chapter</var>, whose
7718: start time is <var title="">current cue</var>'s <a href="#text-track-cue-start-time">text track
7719: cue start time</a>, whose end time is <var title="">current
7720: cue</var>'s <a href="#text-track-cue-end-time">text track cue end time</a>, whose title is
7721: <var title="">current cue</var>'s <a href="#text-track-cue-text">text track cue text</a>
7722: interpreted according to its rules for interpretation, and whose
7723: list of nested chapters is empty.</p></li>
7724:
7725: <li><p>Append <var title="">new chapter</var> to <var title="">current chapter</var>'s list of nested chapters, and let
7726: <var title="">current chapter</var> be <var title="">new
7727: chapter</var>'s parent.</p></li>
7728:
7729: <li><p>Let <var title="">current chapter</var> be <var title="">new
7730: chapter</var>.</p></li>
7731:
7732: <li><p>Return to the step labeled <i>loop</i>.</p></li>
7733:
7734:
7735: <li><p><i>End</i>: Return <var title="">output</var>.</p></li>
7736:
7737: </ol></div><div class="impl">
1.47 mike 7738:
1.91 mike 7739: <h6 id="cue-events"><span class="secno">4.8.10.12.6 </span>Event definitions</h6>
1.47 mike 7740:
1.121 mike 7741: <p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that (and their
7742: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
7743: event types</a>) must be
1.47 mike 7744: supported, as IDL attributes, by all objects implementing the
1.121 mike 7745: <code><a href="#texttracklist">TextTrackList</a></code> interface:</p>
7746:
7747: <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>
7748: </th></tr></thead><tbody><tr><td><dfn id="handler-texttracklist-onaddtrack" title="handler-TextTrackList-onaddtrack"><code>onaddtrack</code></dfn> </td><td> <code title="event-addtrack">addtrack</code>
7749: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that (and their
7750: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
7751: event types</a>) must be supported, as IDL attributes, by all
7752: objects implementing the <code><a href="#texttrack">TextTrack</a></code> interface:</p>
1.47 mike 7753:
7754: <table><thead><tr><th><a href="webappapis.html#event-handlers" title="event handlers">Event handler</a> </th><th><a href="webappapis.html#event-handler-event-type">Event handler event type</a>
1.130 mike 7755: </th></tr></thead><tbody><tr><td><dfn id="handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange"><code>oncuechange</code></dfn> </td><td> <code title="event-cuechange">cuechange</code>
1.121 mike 7756: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that (and their
7757: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
7758: event types</a>) must be supported, as IDL attributes, by all
7759: objects implementing the <code><a href="#texttrackcue">TextTrackCue</a></code> interface:</p>
1.47 mike 7760:
7761: <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>
7762: </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>
7763: </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>
7764: </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>
7765: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. If present, it
7766: indicates that the author has not provided a scripted controller and
7767: would like the user agent to provide its own set of controls.</p><div class="impl">
7768:
7769: <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
7770: <a href="#media-element">media element</a>, then the user agent should <dfn id="expose-a-user-interface-to-the-user">expose a
7771: user interface to the user</dfn>. This user interface should include
7772: features to begin playback, pause playback, seek to an arbitrary
7773: position in the content (if the content supports arbitrary seeking),
7774: change the volume, change the display of closed captions or embedded
7775: sign-language tracks, select different audio tracks or turn on audio
7776: descriptions, and show the media content in manners more suitable to
7777: the user (e.g. full-screen video or in an independent resizable
7778: window). Other controls may also be made available.</p>
7779:
7780: <p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7781: controller</a>, then the user agent should expose audio tracks
7782: from all the <a href="#slaved-media-elements">slaved media elements</a> (although avoiding
7783: duplicates if the same <a href="#media-resource">media resource</a> is being used
7784: several times). If a <a href="#media-resource">media resource</a>'s audio track
7785: exposed in this way has no known name, and it is the only audio
7786: track for a particular <a href="#media-element">media element</a>, the user agent
7787: should use the element's <code title="attr-title"><a href="elements.html#the-title-attribute">title</a></code>
7788: attribute, if any, as the name (or as part of the name) of that
7789: track.</p>
7790:
7791: <p>Even when the attribute is absent, however, user agents may
7792: provide controls to affect playback of the media resource
7793: (e.g. play, pause, seeking, and volume controls), but such features
7794: should not interfere with the page's normal rendering. For example,
7795: such features could be exposed in the <a href="#media-element">media element</a>'s
7796: context menu.</p>
7797:
7798: <p>Where possible (specifically, for starting, stopping, pausing,
7799: and unpausing playback, for seeking, for changing the rate of
7800: playback, for fast-forwarding or rewinding,
7801: for listing, enabling, and disabling text tracks,
7802: and for muting or changing the volume of the audio), user interface
7803: features exposed by the user agent must be implemented in terms of
7804: the DOM API described above, so that, e.g., all the same events
7805: fire.</p>
7806:
7807: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7808: controller</a>, the user agent's user interface for pausing and
7809: unpausing playback, for seeking, for changing the rate of playback,
7810: for fast-forwarding or rewinding, and for muting or changing the
7811: volume of audio of the entire group must be implemented in terms of
7812: the <code><a href="#mediacontroller">MediaController</a></code> API exposed on that <a href="#current-media-controller">current
7813: media controller</a>.</p>
7814:
7815: <p>The "play" function in the user agent's interface must set the
7816: <code title="">playbackRate</code> attribute to the value of the
7817: <code title="">defaultPlaybackRate</code> attribute before invoking
7818: the <code title="">play()</code> method.
7819: When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7820: controller</a>, the attributes and method with those names on
7821: that <code><a href="#mediacontroller">MediaController</a></code> object must be used. Otherwise,
7822: the attributes and method with those names on the <a href="#media-element">media
7823: element</a> itself must be used.
7824: </p>
7825:
7826: <p>Features such as fast-forward or rewind must be implemented by
7827: only changing the <code title="">playbackRate</code> attribute (and
7828: not the <code title="">defaultPlaybackRate</code> attribute).
7829: Again, when a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7830: controller</a>, the attributes with those names on that
7831: <code><a href="#mediacontroller">MediaController</a></code> object must be used; otherwise, the
7832: attributes with those names on the <a href="#media-element">media element</a> itself
7833: must be used.
7834: </p>
7835:
7836: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7837: controller</a>, and all the <a href="#slaved-media-elements">slaved media elements</a> of
7838: that <code><a href="#mediacontroller">MediaController</a></code> are paused, the user agent should
7839: unpause all the <a href="#slaved-media-elements">slaved media elements</a> when the user
7840: invokes a user agent interface control for beginning playback.</p>
7841:
7842: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
1.80 mike 7843: controller</a>, seeking must be implemented in terms of the <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> attribute
7844: on that <code><a href="#mediacontroller">MediaController</a></code> object. Otherwise, the user
7845: agent must directly <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the
7846: requested position in the <a href="#media-element">media element</a>'s <a href="#media-timeline">media
1.47 mike 7847: timeline</a>.</p>
7848:
7849: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7850: controller</a>, user agents may additionally provide the user
7851: with controls that directly manipulate an individual <a href="#media-element">media
7852: element</a> without affecting the <code><a href="#mediacontroller">MediaController</a></code>,
7853: but such features are considered relatively advanced and unlikely to
7854: be useful to most users.
7855:
7856: </p><p>For the purposes of listing chapters in the <a href="#media-resource">media
1.91 mike 7857: resource</a>, only <a href="#text-track" title="text track">text tracks</a> in
7858: the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>
7859: <a href="#text-track-showing" title="text track showing">showing</a> or <a href="#text-track-showing-by-default" title="text
7860: track showing by default">showing by default</a> and whose
7861: <a href="#text-track-kind">text track kind</a> is <code title="dom-timedtrack-kind-chapters">chapters</code> should be used.
7862: Such tracks must be interpreted according to the <a href="#rules-for-constructing-the-chapter-tree-from-a-text-track">rules for
7863: constructing the chapter tree from a text track</a>.</p>
1.47 mike 7864:
7865: <p>The <dfn id="dom-media-controls" title="dom-media-controls"><code>controls</code></dfn>
7866: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
7867: same name.</p>
7868:
7869: <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>
7870:
7871: <dd>
7872:
7873: <p>Returns the current playback volume, as a number in the range
7874: 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.</p>
7875:
7876: <p>Can be set, to change the volume.</p>
7877:
1.119 mike 7878: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the new value is not
1.47 mike 7879: in the range 0.0 .. 1.0.</p>
7880:
7881: </dd>
7882:
7883: <dt><var title="">media</var> . <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
7884:
7885: <dd>
7886:
7887: <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
7888: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute is being
7889: honored.</p>
7890:
7891: <p>Can be set, to change whether the audio is muted or not.</p>
7892:
7893: </dd>
7894:
7895: </dl><div class="impl">
7896:
7897: <p>The <dfn id="dom-media-volume" title="dom-media-volume"><code>volume</code></dfn>
7898: attribute must return the playback volume of any audio portions of
7899: the <a href="#media-element">media element</a>, in the range 0.0 (silent) to 1.0
1.98 mike 7900: (loudest). Initially, the volume should be 1.0, but user agents may
1.47 mike 7901: remember the last set value across sessions, on a per-site basis or
7902: otherwise, so the volume may start at other values. On setting, if
1.98 mike 7903: the new value is in the range 0.0 to 1.0 inclusive, the playback
7904: volume of any audio portions of the <a href="#media-element">media element</a> must
7905: be set to the new value. If the new value is outside the range 0.0
1.119 mike 7906: to 1.0 inclusive, then, on setting, an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code>
1.98 mike 7907: exception must be raised instead.</p>
1.47 mike 7908:
7909: <p>The <dfn id="dom-media-muted" title="dom-media-muted"><code>muted</code></dfn>
1.98 mike 7910: attribute must return true if the audio output is muted and false
7911: otherwise. Initially, the audio output should not be muted (false),
7912: but user agents may remember the last set value across sessions, on
7913: a per-site basis or otherwise, so the muted state may start as muted
7914: (true). On setting, if the new value is true then the audio output
7915: should be muted and if the new value is false it should be
7916: unmuted.</p>
7917:
7918: <p>Whenever either of the values that would be returned by the <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> and <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> attributes change, the user
7919: 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
7920: event</a> named <code title="event-media-volumechange"><a href="#event-media-volumechange">volumechange</a></code> at the
7921: <a href="#media-element">media element</a>.</p>
1.47 mike 7922:
7923: <p>An element's <dfn id="effective-media-volume">effective media volume</dfn> is determined as
7924: follows:</p>
7925:
1.98 mike 7926: <ol><li><p>If the user has indicated that the user agent is to override
7927: the volume of the element, then the element's <a href="#effective-media-volume">effective media
7928: volume</a> is the volume desired by the user. Abort these
7929: steps.</p></li>
7930:
7931: <li><p>If the element's audio output is muted, the element's
7932: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
7933: steps.</p></li>
1.47 mike 7934:
7935: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>
7936: and that <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-mute-override">media
7937: controller mute override</a> is true, the element's
7938: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
7939: steps.</p></li>
7940:
1.98 mike 7941: <li><p>Let <var title="">volume</var> be the playback volume of the
7942: audio portions of the <a href="#media-element">media element</a>, in range 0.0
7943: (silent) to 1.0 (loudest).</p></li>
1.47 mike 7944:
7945: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>,
7946: multiply <var title="">volume</var> by that
7947: <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-volume-multiplier">media controller volume
7948: multiplier</a>.</p></li>
7949:
7950: <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
7951: 1.0, with 0.0 being silent, and 1.0 being the loudest setting,
7952: values in between increasing in loudness. The range need not be
7953: linear. The loudest setting may be lower than the system's loudest
7954: possible setting; for example the user could have set a maximum
7955: volume.</p></li>
7956:
7957: </ol></div><p>The <dfn id="attr-media-muted" title="attr-media-muted"><code>muted</code></dfn>
1.97 mike 7958: attribute on <a href="#media-element" title="media element">media elements</a> is a
7959: <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that controls the default state of
1.98 mike 7960: the audio output of the <a href="#media-resource">media resource</a>, potentially
1.97 mike 7961: overriding user preferences.</p><div class="impl">
1.47 mike 7962:
7963: <p>When a <a href="#media-element">media element</a> is created, if it has a <code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code> attribute specified, the user
1.98 mike 7964: agent must mute the <a href="#media-element">media element</a>'s audio output,
7965: overriding any user preference.</p>
1.47 mike 7966:
7967: <p>The <dfn id="dom-media-defaultmuted" title="dom-media-defaultMuted"><code>defaultMuted</code></dfn> IDL
7968: 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>
7969:
7970: </div><p class="note">This attribute has no dynamic effect (it only
7971: controls the default state of the element).</p><div class="example">
7972:
7973: <p>This video (an advertisment) autoplays, but to avoid annoying
7974: users, it does so without sound, and allows the user to turn the
7975: sound on.</p>
7976:
7977: <pre><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></pre>
7978:
7979: </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
7980: represent a list of ranges (periods) of time.</p><pre class="idl">interface <dfn id="timeranges">TimeRanges</dfn> {
7981: readonly attribute unsigned long <a href="#dom-timeranges-length" title="dom-TimeRanges-length">length</a>;
1.101 mike 7982: double <a href="#dom-timeranges-start" title="dom-TimeRanges-start">start</a>(unsigned long index);
7983: double <a href="#dom-timeranges-end" title="dom-TimeRanges-end">end</a>(unsigned long index);
1.47 mike 7984: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-TimeRanges-length"><a href="#dom-timeranges-length">length</a></code></dt>
7985:
7986: <dd>
7987:
7988: <p>Returns the number of ranges in the object.</p>
7989:
7990: </dd>
7991:
7992: <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>
7993:
7994: <dd>
7995:
7996: <p>Returns the time for the start of the range with the given index.</p>
7997:
1.119 mike 7998: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the index is out of range.</p>
1.47 mike 7999:
8000: </dd>
8001:
8002: <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>
8003:
8004: <dd>
8005:
8006: <p>Returns the time for the end of the range with the given index.</p>
8007:
1.119 mike 8008: <p>Throws an <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> if the index is out of range.</p>
1.47 mike 8009:
8010: </dd>
8011:
8012: </dl><div class="impl">
8013:
8014: <p>The <dfn id="dom-timeranges-length" title="dom-TimeRanges-length"><code>length</code></dfn>
8015: IDL attribute must return the number of ranges represented by the object.</p>
8016:
8017: <p>The <dfn id="dom-timeranges-start" title="dom-TimeRanges-start"><code>start(<var title="">index</var>)</code></dfn> method must return the position
8018: of the start of the <var title="">index</var>th range represented by
8019: the object, in seconds measured from the start of the timeline that
8020: the object covers.</p>
8021:
8022: <p>The <dfn id="dom-timeranges-end" title="dom-TimeRanges-end"><code>end(<var title="">index</var>)</code></dfn> method must return the position
8023: of the end of the <var title="">index</var>th range represented by
8024: the object, in seconds measured from the start of the timeline that
8025: the object covers.</p>
8026:
1.119 mike 8027: <p>These methods must throw <code><a href="infrastructure.html#indexsizeerror">IndexSizeError</a></code> exceptions
1.47 mike 8028: if called with an <var title="">index</var> argument greater than or
8029: equal to the number of ranges represented by the object.</p>
8030:
8031: <p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said to be a
8032: <dfn id="normalized-timeranges-object">normalized <code>TimeRanges</code> object</dfn>, the ranges it
8033: represents must obey the following criteria:</p>
8034:
8035: <ul><li>The start of a range must be greater than the end of all
8036: earlier ranges.</li>
8037:
8038: <li>The start of a range must be less than the end of that same
8039: range.</li>
8040:
8041: </ul><p>In other words, the ranges in such an object are ordered, don't
8042: overlap, aren't empty, and don't touch (adjacent ranges are folded
8043: into one bigger range).</p>
8044:
1.62 mike 8045: <p>Ranges in a <code><a href="#timeranges">TimeRanges</a></code> object must be inclusive.</p>
8046:
8047: <p class="example">Thus, the end of a range would be equal to the
8048: start of a following adjacent (touching but not overlapping) range.
8049: Similarly, a range covering a whole timeline anchored at zero would
8050: have a start equal to zero and an end equal to the duration of the
8051: timeline.</p>
8052:
1.47 mike 8053: <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
8054: <a href="#media-timeline">media timeline</a>.</p>
8055:
1.121 mike 8056: </div><h5 id="event-definitions"><span class="secno">4.8.10.15 </span>Event definitions</h5><pre class="idl">[Constructor(DOMString type, optional <a href="#trackeventinit">TrackEventInit</a> eventInitDict)]
8057: interface <dfn id="trackevent">TrackEvent</dfn> : <a href="infrastructure.html#event">Event</a> {
8058: readonly attribute object? <a href="#dom-trackevent-track" title="dom-TrackEvent-track">track</a>;
8059: };
8060:
8061: dictionary <dfn id="trackeventinit">TrackEventInit</dfn> : <a href="infrastructure.html#eventinit">EventInit</a> {
8062: object? Track;
8063: };</pre><dl class="domintro"><dt><var title="">event</var> . <code title="dom-TrackEvent-track"><a href="#dom-trackevent-track">track</a></code></dt>
8064:
8065: <dd>
8066:
8067: <p>Returns the track object (<code><a href="#texttrack">TextTrack</a></code>,
8068: <code><a href="#audiotrack">AudioTrack</a></code>, or <code><a href="#videotrack">VideoTrack</a></code>) to which the
8069: event relates.</p>
8070:
8071: </dd>
8072:
8073: </dl><div class="impl">
8074:
8075: <p>The <dfn id="dom-trackevent-track" title="dom-TrackEvent-track"><code>track</code></dfn>
8076: attribute must return the value it was initialized to. When the
8077: object is created, this attribute must be initialized to null. It
8078: represents the context information for the event.</p>
8079:
8080: </div><h5 id="mediaevents"><span class="secno">4.8.10.16 </span>Event summary</h5><p><i>This section is non-normative.</i></p><p>The following events fire on <a href="#media-element" title="media element">media
1.47 mike 8081: elements</a> as part of the processing model described above:</p><table><thead><tr><th>Event name
8082: </th><th>Interface
1.64 mike 8083: </th><th>Fired when...
1.47 mike 8084: </th><th>Preconditions
8085:
8086: </th></tr></thead><tbody><tr><td><dfn id="event-media-loadstart" title="event-media-loadstart"><code>loadstart</code></dfn>
8087: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8088: </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>.
8089: </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>
8090: </td></tr><tr><td><dfn id="event-media-progress" title="event-media-progress"><code>progress</code></dfn>
8091: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8092: </td><td>The user agent is fetching <a href="#media-data">media data</a>.
8093: </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>
8094: </td></tr><tr><td><dfn id="event-media-suspend" title="event-media-suspend"><code>suspend</code></dfn>
8095: </td><td><code><a href="infrastructure.html#event">Event</a></code>
1.112 mike 8096: </td><td>The user agent is intentionally not currently fetching <a href="#media-data">media data</a>.
1.47 mike 8097: </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>
8098: </td></tr><tr><td><dfn id="event-media-abort" title="event-media-abort"><code>abort</code></dfn>
8099: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8100: </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.
8101: </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>.
8102: <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.
8103: </td></tr><tr><td><dfn id="event-media-error" title="event-media-error"><code>error</code></dfn>
8104: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8105: </td><td>An error occurs while fetching the <a href="#media-data">media data</a>.
8106: </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.
8107: <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.
8108: </td></tr><tr><td><dfn id="event-media-emptied" title="event-media-emptied"><code>emptied</code></dfn>
8109: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8110: </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).
8111: </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.
8112: </td></tr><tr><td><dfn id="event-media-stalled" title="event-media-stalled"><code>stalled</code></dfn>
8113: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8114: </td><td>The user agent is trying to fetch <a href="#media-data">media data</a>, but data is unexpectedly not forthcoming.
8115: </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>.
8116:
8117: </td></tr></tbody><tbody><tr><td><dfn id="event-media-loadedmetadata" title="event-media-loadedmetadata"><code>loadedmetadata</code></dfn>
8118: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8119: </td><td>The user agent has just determined the duration and dimensions of the <a href="#media-resource">media resource</a>
8120: and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>.
8121: </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.
8122: </td></tr><tr><td><dfn id="event-media-loadeddata" title="event-media-loadeddata"><code>loadeddata</code></dfn>
8123: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8124: </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.
8125: </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.
8126: </td></tr><tr><td><dfn id="event-media-canplay" title="event-media-canplay"><code>canplay</code></dfn>
8127: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8128: </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.
8129: </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.
8130: </td></tr><tr><td><dfn id="event-media-canplaythrough" title="event-media-canplaythrough"><code>canplaythrough</code></dfn>
8131: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8132: </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.
8133: </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>.
8134: </td></tr><tr><td><dfn id="event-media-playing" title="event-media-playing"><code>playing</code></dfn>
8135: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8136: </td><td>Playback is ready to start after having been paused or delayed due to lack of <a href="#media-data">media data</a>.
8137: </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
8138: 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
8139: the element is <a href="#paused-for-user-interaction">paused for user interaction</a>.
8140: </td></tr><tr><td><dfn id="event-media-waiting" title="event-media-waiting"><code>waiting</code></dfn>
8141: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8142: </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.
8143: </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.
8144: the element is newly <a href="#blocked-on-its-media-controller">blocked on its media controller</a>, or
8145: <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>.
8146: </td></tr></tbody><tbody><tr><td><dfn id="event-media-seeking" title="event-media-seeking"><code>seeking</code></dfn>
8147: </td><td><code><a href="infrastructure.html#event">Event</a></code>
1.73 mike 8148: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to true.
1.47 mike 8149: </td><td>
8150: </td></tr><tr><td><dfn id="event-media-seeked" title="event-media-seeked"><code>seeked</code></dfn>
8151: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8152: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to false.
8153: </td><td>
8154: </td></tr><tr><td><dfn id="event-media-ended" title="event-media-ended"><code>ended</code></dfn>
8155: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8156: </td><td>Playback has stopped because the end of the <a href="#media-resource">media resource</a> was reached.
8157: </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.
8158:
8159: </td></tr></tbody><tbody><tr><td><dfn id="event-media-durationchange" title="event-media-durationchange"><code>durationchange</code></dfn>
8160: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8161: </td><td>The <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute has just been updated.
8162: </td><td>
8163: </td></tr><tr><td><dfn id="event-media-timeupdate" title="event-media-timeupdate"><code>timeupdate</code></dfn>
8164: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8165: </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.
8166: </td><td>
8167: </td></tr><tr><td><dfn id="event-media-play" title="event-media-play"><code>play</code></dfn>
8168: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8169: </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.
8170: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false.
8171: </td></tr><tr><td><dfn id="event-media-pause" title="event-media-pause"><code>pause</code></dfn>
8172: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8173: </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.
8174: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly true.
8175: </td></tr><tr><td><dfn id="event-media-ratechange" title="event-media-ratechange"><code>ratechange</code></dfn>
8176: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8177: </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.
8178: </td><td>
8179: </td></tr><tr><td><dfn id="event-media-volumechange" title="event-media-volumechange"><code>volumechange</code></dfn>
8180: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8181: </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.
8182: </td><td>
8183: </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
8184: </th><th>Interface
1.64 mike 8185: </th><th>Fired when...
1.47 mike 8186:
8187: </th></tr></thead><tbody><tr><td><dfn id="event-mediacontroller-emptied" title="event-MediaController-emptied"><code>emptied</code></dfn>
8188: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8189: </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>.
8190: </td></tr><tr><td><dfn id="event-mediacontroller-loadedmetadata" title="event-MediaController-loadedmetadata"><code>loadedmetadata</code></dfn>
8191: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8192: </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.
8193: </td></tr><tr><td><dfn id="event-mediacontroller-loadeddata" title="event-MediaController-loadeddata"><code>loadeddata</code></dfn>
8194: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8195: </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.
8196: </td></tr><tr><td><dfn id="event-mediacontroller-canplay" title="event-MediaController-canplay"><code>canplay</code></dfn>
8197: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8198: </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.
8199: </td></tr><tr><td><dfn id="event-mediacontroller-canplaythrough" title="event-MediaController-canplaythrough"><code>canplaythrough</code></dfn>
8200: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8201: </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.
8202: </td></tr><tr><td><dfn id="event-mediacontroller-playing" title="event-MediaController-playing"><code>playing</code></dfn>
8203: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8204: </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 8205: </td></tr><tr><td><dfn id="event-mediacontroller-ended" title="event-MediaController-ended"><code>ended</code></dfn>
8206: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8207: </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 8208: </td></tr><tr><td><dfn id="event-mediacontroller-waiting" title="event-MediaController-waiting"><code>waiting</code></dfn>
8209: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8210: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is now a <a href="#blocked-media-controller">blocked media controller</a>.
8211: </td></tr><tr><td><dfn id="event-mediacontcoller-ended" title="event-MediaContcoller-ended"><code>ended</code></dfn>
8212: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8213: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> have newly <a href="#ended-playback">ended playback</a>.
8214:
8215: </td></tr></tbody><tbody><tr><td><dfn id="event-mediacontroller-durationchange" title="event-MediaController-durationchange"><code>durationchange</code></dfn>
8216: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8217: </td><td>The <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code> attribute has just been updated.
8218: </td></tr><tr><td><dfn id="event-mediacontroller-timeupdate" title="event-MediaController-timeupdate"><code>timeupdate</code></dfn>
8219: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8220: </td><td>The <a href="#media-controller-position">media controller position</a> changed.
8221: </td></tr><tr><td><dfn id="event-mediacontroller-play" title="event-MediaController-play"><code>play</code></dfn>
8222: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8223: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly false.
8224: </td></tr><tr><td><dfn id="event-mediacontroller-pause" title="event-MediaController-pause"><code>pause</code></dfn>
8225: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8226: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly true.
8227: </td></tr><tr><td><dfn id="event-mediacontroller-ratechange" title="event-MediaController-ratechange"><code>ratechange</code></dfn>
8228: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8229: </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.
8230: </td></tr><tr><td><dfn id="event-mediacontroller-volumechange" title="event-MediaController-volumechange"><code>volumechange</code></dfn>
8231: </td><td><code><a href="infrastructure.html#event">Event</a></code>
8232: </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.
8233: </td></tr></tbody></table><div class="impl">
8234:
1.121 mike 8235: <h5 id="security-and-privacy-considerations"><span class="secno">4.8.10.17 </span>Security and privacy considerations</h5>
1.47 mike 8236:
8237: <p>The main security and privacy implications of the
8238: <code><a href="#the-video-element">video</a></code> and <code><a href="#the-audio-element">audio</a></code> elements come from the
8239: ability to embed media cross-origin. There are two directions that
8240: threats can flow: from hostile content to a victim page, and from a
8241: hostile page to victim content.</p>
8242:
8243: <hr><p>If a victim page embeds hostile content, the threat is that the
8244: content might contain scripted code that attempts to interact with
8245: the <code><a href="infrastructure.html#document">Document</a></code> that embeds the content. To avoid this,
8246: user agents must ensure that there is no access from the content to
8247: the embedding page. In the case of media content that uses DOM
8248: concepts, the embedded content must be treated as if it was in its
8249: own unrelated <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>.</p>
8250:
8251: <p class="example">For instance, if an SVG animation was embedded in
8252: a <code><a href="#the-video-element">video</a></code> element, the user agent would not give it
8253: access to the DOM of the outer page. From the perspective of scripts
8254: in the SVG resource, the SVG file would appear to be in a lone
8255: top-level browsing context with no parent.</p>
8256:
8257: <hr><p>If a hostile page embeds victim content, the threat is that the
8258: embedding page could obtain information from the content that it
1.58 mike 8259: would not otherwise have access to. The API does expose some
8260: information: the existence of the media, its type, its duration, its
8261: size, and the performance characteristics of its host. Such
8262: information is already potentially problematic, but in practice the
8263: same information can more or less be obtained using the
8264: <code><a href="embedded-content-1.html#the-img-element">img</a></code> element, and so it has been deemed acceptable.</p>
8265:
8266: <p>However, significantly more sensitive information could be
8267: obtained if the user agent further exposes metadata within the
1.61 mike 8268: content such as subtitles or chapter titles. Such information is
8269: therefore only exposed if the video resource passes a CORS
8270: <a href="infrastructure.html#resource-sharing-check">resource sharing check</a>. The <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> attribute allows
1.101 mike 8271: authors to control how this check is performed. <a href="references.html#refsCORS">[CORS]</a></p>
1.61 mike 8272:
8273: <p class="example">Without this restriction, an attacker could trick
8274: a user running within a corporate network into visiting a site that
8275: attempts to load a video from a previously leaked location on the
8276: corporation's intranet. If such a video included confidential plans
8277: for a new product, then being able to read the subtitles would
8278: present a serious confidentiality breach.</p>
1.47 mike 8279:
1.121 mike 8280: </div><h5 id="best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.18 </span>Best practices for authors using media elements</h5><p><i>This section is non-normative.</i></p><p>Playing audio and video resources on small devices such as
1.47 mike 8281: set-top boxes or mobile phones is often constrained by limited
8282: hardware resources in the device. For example, a device might only
8283: support three simultaneous videos. For this reason, it is a good
8284: practice to release resources held by <a href="#media-element" title="media
8285: element">media elements</a> when they are done playing, either by
8286: being very careful about removing all references to the element and
8287: allowing it to be garbage collected, or, even better, by removing
8288: the element's <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and
8289: any <code><a href="#the-source-element">source</a></code> element descendants, and invoking the
8290: 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,
8291: software, or format limitations can cause video frames to be dropped
8292: and audio to be choppy or muted.</p><div class="impl">
8293:
1.121 mike 8294: <h5 id="best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.19 </span>Best practices for implementors of media elements</h5>
1.47 mike 8295:
8296: <p><i>This section is non-normative.</i></p>
8297:
8298: <p>How accurately various aspects of the <a href="#media-element">media element</a>
8299: API are implemented is considered a quality-of-implementation issue.</p>
8300:
8301: <p>For example, when implementing the <code title="attr-media-buffered">buffered</code> attribute, how precise
8302: an implementation reports the ranges that have been buffered depends
8303: on how carefully the user agent inspects the data. Since the API
8304: reports ranges as times, but the data is obtained in byte streams, a
8305: user agent receiving a variable-bit-rate stream might only be able
8306: to determine precise times by actually decoding all of the data.
8307: User agents aren't required to do this, however; they can instead
8308: return estimates (e.g. based on the average bit rate seen so far)
8309: which get revised as more information becomes available.</p>
8310:
8311: <p>As a general rule, user agents are urged to be conservative
8312: rather than optimistic. For example, it would be bad to report that
8313: everything had been buffered when it had not.</p>
8314:
8315: <p>Another quality-of-implementation issue would be playing a video
8316: backwards when the codec is designed only for forward playback (e.g.
8317: there aren't many key frames, and they are far apart, and the
8318: intervening frames only have deltas from the previous frame). User
8319: agents could do a poor job, e.g. only showing key frames; however,
8320: better implementations would do more work and thus do a better job,
8321: e.g. actually decoding parts of the video forwards, storing the
8322: complete frames, and then playing the frames backwards.</p>
8323:
8324: <p>Similarly, while implementations are allowed to drop buffered
8325: data at any time (there is no requirement that a user agent keep all
8326: the media data obtained for the lifetime of the media element), it
8327: is again a quality of implementation issue: user agents with
8328: sufficient resources to keep all the data around are encouraged to
8329: do so, as this allows for a better user experience. For example, if
8330: the user is watching a live stream, a user agent could allow the
8331: user only to view the live video; however, a better user agent would
8332: buffer everything and allow the user to seek through the earlier
8333: material, pause it, play it forwards and backwards, etc.</p>
8334:
8335: <p>When multiple tracks are synchronised with a
8336: <code><a href="#mediacontroller">MediaController</a></code>, it is possible for scripts to add and
8337: remove media elements from the <code><a href="#mediacontroller">MediaController</a></code>'s list
8338: of <a href="#slaved-media-elements">slaved media elements</a>, even while these tracks are
8339: playing. How smoothly the media plays back in such situations is
8340: another quality-of-implementation issue.</p>
8341:
8342: <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
8343: document</a> and not reinserted before the next time the
8344: <a href="webappapis.html#event-loop">event loop</a> spins, implementations that are resource
8345: constrained are encouraged to take that opportunity to release all
8346: hardware resources (like video planes, networking resources, and
8347: data buffers) used by the <a href="#media-element">media element</a>. (User agents
8348: still have to keep track of the playback position and so forth,
8349: though, in case playback is later restarted.)</p>
8350:
1.1 mike 8351: </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