Annotation of html5/spec/the-iframe-element.html, revision 1.56
1.1 mike 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
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; }
22: dt dfn { font-style: italic; }
23: pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
24: pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
25: pre em { font-weight: bolder; font-style: normal; }
26: @media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
27: var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
28: table { border-collapse: collapse; border-style: hidden hidden none hidden; }
29: table thead, table tbody { border-bottom: solid; }
30: table tbody th:first-child { border-left: solid; }
31: table tbody th { text-align: left; }
32: table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
33: blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
34:
35: .bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
36: .matrix, .matrix td { border: none; text-align: right; }
37: .matrix { margin-left: 2em; }
38: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
39: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
40: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
41:
42: .toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
43: img.extra { float: right; }
44: pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
45: pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
46: pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
47: pre.css:first-line { color: #AAAA50; }
48: dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
49: hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
50: dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
51: dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
52: dl.domintro dd p { margin: 0.5em 0; }
53: dl.switch { padding-left: 2em; }
54: dl.switch > dt { text-indent: -1.5em; }
55: dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
56: dl.triple { padding: 0 0 0 1em; }
57: dl.triple dt, dl.triple dd { margin: 0; display: inline }
58: dl.triple dt:after { content: ':'; }
59: dl.triple dd:after { content: '\A'; white-space: pre; }
60: .diff-old { text-decoration: line-through; color: silver; background: transparent; }
61: .diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
62: a .diff-new { border-bottom: 1px blue solid; }
63:
64: h2 { page-break-before: always; }
65: h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
66: h1 + h2, hr + h2.no-toc { page-break-before: auto; }
67:
1.26 mike 68: p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
69: li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
1.1 mike 70:
71: div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
72: div.head p { margin: 0; }
73: div.head h1 { margin: 0; }
74: div.head .logo { float: right; margin: 0 1em; }
75: div.head .logo img { border: none } /* remove border from top image */
76: div.head dl { margin: 1em 0; }
77: div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
78:
79: body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
80: body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
81: body > .toc > li > * { margin-bottom: 0.5em; }
82: body > .toc > li > * > li > * { margin-bottom: 0.25em; }
83: .toc, .toc li { list-style: none; }
84:
85: .brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
86: .brief li { margin: 0; padding: 0; }
87: .brief li p { margin: 0; padding: 0; }
88:
89: .category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
90: .category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
91: .category-list li { display: inline; }
92: .category-list li:not(:last-child)::after { content: ', '; }
93: .category-list li > span, .category-list li > a { text-transform: lowercase; }
94: .category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
95:
96: .XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
97: .XXX > :first-child { margin-top: 0; }
98: p .XXX { line-height: 3em; }
99: .annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
100: .annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
101: .annotation :link, .annotation :visited { color: inherit; }
102: .annotation :link:hover, .annotation :visited:hover { background: transparent; }
103: .annotation span { border: none ! important; }
104: .note { color: green; background: transparent; font-family: sans-serif; }
105: .warning { color: red; background: transparent; }
106: .note, .warning { font-weight: bolder; font-style: italic; }
107: p.note, div.note { padding: 0.5em 2em; }
108: span.note { padding: 0 2em; }
109: .note p:first-child, .warning p:first-child { margin-top: 0; }
110: .note p:last-child, .warning p:last-child { margin-bottom: 0; }
111: .warning:before { font-style: normal; }
112: p.note:before { content: 'Note: '; }
113: p.warning:before { content: '\26A0 Warning! '; }
114:
115: .bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
116: .bookkeeping { font-size: 0.8em; margin: 2em 0; }
117: .bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
1.12 mike 118: .bookkeeping dt { margin: 0.5em 2em 0; }
119: .bookkeeping dd { margin: 0 3em 0.5em; }
1.1 mike 120:
121: h4 { position: relative; z-index: 3; }
122: h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
123: .element {
124: background: #EEEEFF;
125: color: black;
126: margin: 0 0 1em 0.15em;
127: padding: 0 1em 0.25em 0.75em;
128: border-left: solid #9999FF 0.25em;
129: position: relative;
130: z-index: 1;
131: }
132: .element:before {
133: position: absolute;
134: z-index: 2;
135: top: 0;
136: left: -1.15em;
137: height: 2em;
138: width: 0.9em;
139: background: #EEEEFF;
140: content: ' ';
141: border-style: none none solid solid;
142: border-color: #9999FF;
143: border-width: 0.25em;
144: }
145:
146: .example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
147: td > .example:only-child { margin: 0 0 0 0.1em; }
148:
149: ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
150: ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
151: ul.domTree li li { list-style: none; }
152: 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; }
153: 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; }
154: ul.domTree span { font-style: italic; font-family: serif; }
155: ul.domTree .t1 code { color: purple; font-weight: bold; }
156: ul.domTree .t2 { font-style: normal; font-family: monospace; }
157: ul.domTree .t2 .name { color: black; font-weight: bold; }
158: ul.domTree .t2 .value { color: blue; font-weight: normal; }
159: ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
160: ul.domTree .t7 code, .domTree .t8 code { color: green; }
161: ul.domTree .t10 code { color: teal; }
162:
163: body.dfnEnabled dfn { cursor: pointer; }
164: .dfnPanel {
165: display: inline;
166: position: absolute;
167: z-index: 10;
168: height: auto;
169: width: auto;
170: padding: 0.5em 0.75em;
171: font: small sans-serif, Droid Sans Fallback;
172: background: #DDDDDD;
173: color: black;
174: border: outset 0.2em;
175: }
176: .dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
177: .dfnPanel :link, .dfnPanel :visited { color: black; }
178: .dfnPanel p { font-weight: bolder; }
179: .dfnPanel * + p { margin-top: 0.25em; }
180: .dfnPanel li { list-style-position: inside; }
181:
182: #configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
183: #configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
184: #configUI p label { display: block; }
185: #configUI #updateUI, #configUI .loginUI { text-align: center; }
186: #configUI input[type=button] { display: block; margin: auto; }
1.11 mike 187:
1.30 mike 188: fieldset { margin: 1em; padding: 0.5em 1em; }
189: fieldset > legend + * { margin-top: 0; }
1.21 mike 190: fieldset > :last-child { margin-bottom: 0; }
1.30 mike 191: fieldset p { margin: 0.5em 0; }
192:
1.55 mike 193: .stability {
194: position: fixed;
195: bottom: 0;
196: left: 0; right: 0;
197: margin: 0 auto 0 auto;
198: width: 50%;
199: background: maroon; color: yellow;
200: -webkit-border-radius: 1em 1em 0 0;
201: -moz-border-radius: 1em 1em 0 0;
202: border-radius: 1em 1em 0 0;
203: -moz-box-shadow: 0 0 1em #500;
204: -webkit-box-shadow: 0 0 1em #500;
205: box-shadow: 0 0 1em red;
206: padding: 0.5em 1em;
207: text-align: center;
208: }
209: .stability strong {
210: display: block;
211: }
212: .stability input {
213: appearance: none; margin: 0; border: 0; padding: 0.25em 0.5em; background: transparent; color: black;
214: position: absolute; top: -0.5em; right: 0; font: 1.25em sans-serif; text-align: center;
215: }
216: .stability input:hover {
217: color: white;
218: text-shadow: 0 0 2px black;
219: }
220: .stability input:active {
221: padding: 0.3em 0.45em 0.2em 0.55em;
222: }
223: .stability :link, .stability :visited,
224: .stability :link:hover, .stability :visited:hover {
225: background: transparent;
226: color: white;
227: }
228:
229: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-LC" rel="stylesheet" type="text/css"><style type="text/css">
1.1 mike 230:
231: .applies thead th > * { display: block; }
232: .applies thead code { display: block; }
233: .applies tbody th { whitespace: nowrap; }
234: .applies td { text-align: center; }
235: .applies .yes { background: yellow; }
236:
1.14 mike 237: .matrix, .matrix td { border: hidden; text-align: right; }
1.1 mike 238: .matrix { margin-left: 2em; }
239:
240: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
241: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
242: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
243:
1.17 mike 244: td.eg { border-width: thin; text-align: center; }
245:
1.1 mike 246: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
247: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
248: #table-example-1 caption { padding-bottom: 0.5em; }
249: #table-example-1 thead, #table-example-1 tbody { border: none; }
250: #table-example-1 th, #table-example-1 td { border: solid thin; }
251: #table-example-1 th { font-weight: normal; }
252: #table-example-1 td { border-style: none solid; vertical-align: top; }
253: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
254: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
255: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
256: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
257: #table-example-1 tbody td:first-child::after { content: leader(". "); }
258: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
259: #table-example-1 tbody td:first-child + td { width: 10em; }
260: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
261: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
262:
263: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
264: .apple-table-examples * { font-family: "Times", serif; }
265: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
266: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
267: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
268: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
269: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
270: .apple-table-examples td { text-align: right; vertical-align: top; }
271: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
272: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
273: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
274: .apple-table-examples sup { line-height: 0; }
275:
276: .details-example img { vertical-align: top; }
277:
1.40 mike 278: #base64-table {
279: white-space: nowrap;
280: font-size: 0.6em;
281: column-width: 6em;
282: column-count: 5;
283: column-gap: 1em;
284: -moz-column-width: 6em;
285: -moz-column-count: 5;
286: -moz-column-gap: 1em;
287: -webkit-column-width: 6em;
288: -webkit-column-count: 5;
289: -webkit-column-gap: 1em;
290: }
291: #base64-table thead { display: none; }
292: #base64-table * { border: none; }
293: #base64-table tbody td:first-child:after { content: ':'; }
294: #base64-table tbody td:last-child { text-align: right; }
295:
1.1 mike 296: #named-character-references-table {
1.19 mike 297: white-space: nowrap;
1.1 mike 298: font-size: 0.6em;
1.19 mike 299: column-width: 30em;
1.1 mike 300: column-gap: 1em;
1.19 mike 301: -moz-column-width: 30em;
1.1 mike 302: -moz-column-gap: 1em;
1.19 mike 303: -webkit-column-width: 30em;
1.1 mike 304: -webkit-column-gap: 1em;
305: }
1.19 mike 306: #named-character-references-table > table > tbody > tr > td:first-child + td,
1.1 mike 307: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
308: #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 309: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
1.1 mike 310:
1.2 mike 311: .glyph.control { color: red; }
312:
1.4 mike 313: @font-face {
314: font-family: 'Essays1743';
315: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
316: }
317: @font-face {
318: font-family: 'Essays1743';
319: font-weight: bold;
320: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
321: }
322: @font-face {
323: font-family: 'Essays1743';
324: font-style: italic;
325: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
326: }
327: @font-face {
328: font-family: 'Essays1743';
329: font-style: italic;
330: font-weight: bold;
331: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
332: }
333:
1.1 mike 334: </style><style type="text/css">
335: .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.45 mike 336: </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">
337: function getCookie(name) {
338: var params = location.search.substr(1).split("&");
339: for (var index = 0; index < params.length; index++) {
340: if (params[index] == name)
341: return "1";
342: var data = params[index].split("=");
343: if (data[0] == name)
344: return unescape(data[1]);
345: }
346: var cookies = document.cookie.split("; ");
347: for (var index = 0; index < cookies.length; index++) {
348: var data = cookies[index].split("=");
349: if (data[0] == name)
350: return unescape(data[1]);
351: }
352: return null;
353: }
354: </script>
1.1 mike 355: <script src="link-fixup.js"></script>
1.36 mike 356: <link href="style.css" rel="stylesheet"><link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
1.1 mike 357: <link href="spec.html#contents" title="Table of contents" rel="index">
1.47 mike 358: <link href="the-canvas-element.html" title="4.8.11 The canvas element" rel="next">
1.54 mike 359: </head><body><div class="head" id="head">
1.1 mike 360: <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 361:
1.1 mike 362: <h1>HTML5</h1>
363: </div><div>
1.36 mike 364: <a href="embedded-content-1.html" class="prev">4.8 Embedded content</a> –
1.1 mike 365: <a href="spec.html#contents">Table of contents</a> –
1.47 mike 366: <a href="the-canvas-element.html" class="next">4.8.11 The canvas element</a>
367: <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>
368: <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#the-ready-states"><span class="secno">4.8.10.7 </span>The 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>
369: <ol><li><a href="the-iframe-element.html#tracklist-objects"><span class="secno">4.8.10.10.1 </span><code>TrackList</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>
370: <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>
371: <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#cue-events"><span class="secno">4.8.10.12.5 </span>Event definitions</a></li></ol></li><li><a href="the-iframe-element.html#user-interface"><span class="secno">4.8.10.13 </span>User interface</a></li><li><a href="the-iframe-element.html#time-ranges"><span class="secno">4.8.10.14 </span>Time ranges</a></li><li><a href="the-iframe-element.html#mediaevents"><span class="secno">4.8.10.15 </span>Event summary</a></li><li><a href="the-iframe-element.html#security-and-privacy-considerations"><span class="secno">4.8.10.16 </span>Security and privacy considerations</a></li><li><a href="the-iframe-element.html#best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.17 </span>Best practices for authors using media elements</a></li><li><a href="the-iframe-element.html#best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.18 </span>Best practices for implementors of media elements</a></li></ol></li></ol></li></ol></li></ol></div>
1.1 mike 372:
1.25 mike 373: <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 374: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
375: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
376: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
377: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.16 mike 378: <dt>Contexts in which this element can be used:</dt>
1.1 mike 379: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
380: <dt>Content model:</dt>
1.18 mike 381: <dd>Text that conforms to <a href="#iframe-content-model">the requirements given in the prose</a>.</dd>
1.1 mike 382: <dt>Content attributes:</dt>
383: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
384: <dd><code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code></dd>
385: <dd><code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code></dd>
386: <dd><code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code></dd>
387: <dd><code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code></dd>
388: <dd><code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code></dd>
389: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
390: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
391: <dt>DOM interface:</dt>
392: <dd>
393: <pre class="idl">interface <dfn id="htmliframeelement">HTMLIFrameElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
394: attribute DOMString <a href="#dom-iframe-src" title="dom-iframe-src">src</a>;
395: attribute DOMString <a href="#dom-iframe-srcdoc" title="dom-iframe-srcdoc">srcdoc</a>;
396: attribute DOMString <a href="#dom-iframe-name" title="dom-iframe-name">name</a>;
397: [PutForwards=<a href="common-dom-interfaces.html#dom-domsettabletokenlist-value" title="dom-DOMSettableTokenList-value">value</a>] readonly attribute <a href="common-dom-interfaces.html#domsettabletokenlist">DOMSettableTokenList</a> <a href="#dom-iframe-sandbox" title="dom-iframe-sandbox">sandbox</a>;
398: attribute boolean <a href="#dom-iframe-seamless" title="dom-iframe-seamless">seamless</a>;
399: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
400: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
401: readonly attribute Document <a href="#dom-iframe-contentdocument" title="dom-iframe-contentDocument">contentDocument</a>;
402: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-iframe-contentwindow" title="dom-iframe-contentWindow">contentWindow</a>;
403: };</pre>
404: </dd>
405: </dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
406: <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
407: gives the address of a page that the <a href="browsers.html#nested-browsing-context">nested browsing
408: context</a> is to contain. The attribute, if present, must be a
409: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
410: spaces</a>.</p><p>The <dfn id="attr-iframe-srcdoc" title="attr-iframe-srcdoc"><code>srcdoc</code></dfn>
411: attribute gives the content of the page that the <a href="browsers.html#nested-browsing-context">nested
1.32 mike 412: browsing context</a> is to contain. The value of the attribute is
413: 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="dom.html#html-documents">HTML documents</a>,
1.1 mike 414: the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
415: syntax</a> that consists of the following syntactic components,
416: in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
417: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
418:
419: <li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
420:
421: </li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
422: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
423:
1.47 mike 424: <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 425:
426: <li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
427: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
428:
429: </ol><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="dom.html#xml-documents">XML documents</a>,
430: the attribute, if present, must have a value that matches the
431: production labeled <code><a href="infrastructure.html#document">document</a></code> in the XML
432: 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
433: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute are both
434: specified together, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code>
435: attribute takes priority. This allows authors to provide a fallback
436: <a href="urls.html#url">URL</a> for legacy user agents that do not support the
437: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute.</p><div class="impl">
438:
439: <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
440: an element into a document">inserted into a document</a>, the
441: user agent must create a <a href="browsers.html#nested-browsing-context">nested browsing context</a>, and
442: then <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> for the
443: first time.</p>
444:
445: <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 446: browsing context</a> has its <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute set, changed, or
447: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.1 mike 448: attributes</a>.</p>
449:
450: <p>Similarly, whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a
451: <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 452: <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute set, changed, or
453: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.46 mike 454: attributes</a>.</p>
1.1 mike 455: <p>When the user agent is to <dfn id="process-the-iframe-attributes">process the <code>iframe</code>
456: attributes</dfn>, it must run the first appropriate steps from the
457: following list:</p>
458:
459: <dl class="switch"><dt>If the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute
460: is specified</dt>
461:
1.46 mike 462: <dd><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 463: <a href="browsers.html#browsing-context">browsing context</a> to a resource whose
464: <a href="fetching-resources.html#content-type">Content-Type</a> is <code><a href="iana.html#text-html">text/html</a></code>, whose
465: <a href="urls.html#url">URL</a> is <code><a href="urls.html#about:srcdoc">about:srcdoc</a></code>, and whose data
466: consists of the value of the attribute. The resulting
467: <code><a href="infrastructure.html#document">Document</a></code> must be considered <a href="#an-iframe-srcdoc-document">an
468: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
469: document</a>.</p></dd>
1.1 mike 470:
471: <dt>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code>
472: attribute is specified but the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not</dt>
473:
474: <dd>
475:
476: <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,
477: jump to the <i title="">empty</i> step below.</p></li>
478:
479: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of
480: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute, relative
481: to the <code><a href="#the-iframe-element">iframe</a></code> element.</p></li>
482:
483: <li><p>If that is not successful, then jump to the <i title="">empty</i> step below.</p></li>
484:
485: <li><p>If the resulting <a href="urls.html#absolute-url">absolute URL</a> is an
486: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for the string
487: "<code><a href="fetching-resources.html#about:blank">about:blank</a></code>", and the user agent is processing this
488: <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first time, then jump to
489: the <i title="">empty</i> step below. (In cases other than the
490: first time, <code><a href="fetching-resources.html#about:blank">about:blank</a></code> is loaded
491: normally.)</p></li>
492:
1.46 mike 493: <li><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 494: <a href="browsers.html#browsing-context">browsing context</a> to the resulting <a href="urls.html#absolute-url">absolute
1.1 mike 495: URL</a>.</p></li>
496:
497: </ol><p><i>Empty</i>: When the steps above require the user agent to
498: jump to the <i title="">empty</i> step, if the user agent is
499: processing this <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first
500: time, then the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
501: <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>
502: element. (After jumping to this step, the above steps are not
503: resumed.)</p>
504:
505: </dd>
506:
507: <dt>Otherwise</dt>
508:
509: <dd>
510:
511: <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>
512: named <code title="event-load">load</code> at the
513: <code><a href="#the-iframe-element">iframe</a></code> element.</p>
514:
515: </dd>
516:
517: </dl><p>Any <a href="history.html#navigate" title="navigate">navigation</a> required of the user
518: agent in the <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a>
519: algorithm must be completed with the <code><a href="#the-iframe-element">iframe</a></code> element's
520: document's <a href="browsers.html#browsing-context">browsing context</a> as the <a href="history.html#source-browsing-context">source
521: browsing context</a>.</p>
522:
1.8 mike 523: <p>Furthermore, if the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="history.html#session-history">session
524: history</a> contained only one <code><a href="infrastructure.html#document">Document</a></code> when the
525: <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> algorithm
526: was invoked, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
527: <code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
528: was created, then any <a href="history.html#navigate" title="navigate">navigation</a>
529: required of the user agent in that algorithm must be completed with
1.46 mike 530: <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
1.1 mike 531: </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
532: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is either
533: also not set or set but its value cannot be <a href="urls.html#resolve-a-url" title="resolve a
534: url">resolved</a>, the browsing context will remain at the
535: 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>
536: away from this page, the <code><a href="#the-iframe-element">iframe</a></code>'s corresponding
537: <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 538: 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">
539:
540: <div class="note">
541:
542: <p><a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">Removing</a>
543: an <code><a href="#the-iframe-element">iframe</a></code> from a <code><a href="infrastructure.html#document">Document</a></code> does not cause
544: its <a href="browsers.html#browsing-context">browsing context</a> to be discarded. Indeed, an
545: <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> can survive its
546: original parent <code><a href="infrastructure.html#document">Document</a></code> if its <code><a href="#the-iframe-element">iframe</a></code> is
547: moved to another <code><a href="infrastructure.html#document">Document</a></code>.</p>
548:
1.10 mike 549: <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
550: <code><a href="infrastructure.html#document">Document</a></code> and is then subsequently garbage collected,
551: this will likely mean (in the absence of other references) that the
552: <a href="browsers.html#child-browsing-context">child browsing context</a>'s <code><a href="browsers.html#windowproxy">WindowProxy</a></code>
553: object will become eligble for garbage collection, which will then
554: lead to that <a href="browsers.html#browsing-context">browsing context</a> being <a href="browsers.html#a-browsing-context-is-discarded" title="a
555: browsing context is discarded">discarded</a>, which will then
556: 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 557: document">discarded</a> also. This happens without notice to any
558: scripts running in that <code><a href="infrastructure.html#document">Document</a></code>; for example, no
559: <code title="event-unload">unload</code> events are fired (the
1.10 mike 560: "<a href="history.html#unload-a-document">unload a document</a>" steps are not run).</p>
1.9 mike 561:
562: </div>
563:
564: </div><div class="example">
1.1 mike 565:
566: <p>Here a blog uses the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute in conjunction
567: 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
568: below to provide users of user agents that support this feature
569: with an extra layer of protection from script injection in the blog
570: post comments:</p>
571:
572: <pre><article>
573: <h1>I got my own magazine!</h1>
574: <p>After much effort, I've finally found a publisher, and so now I
575: have my own magazine! Isn't that awesome?! The first issue will come
576: out in September, and we have articles about getting food, and about
577: getting in boxes, it's going to be great!</p>
578: <footer>
579: <p>Written by <a href="/users/cap">cap</a>.
580: <time pubdate>2009-08-21T23:32Z</time></p>
581: </footer>
582: <article>
583: <footer> At <time pubdate>2009-08-21T23:35Z</time>, <a href="/users/ch">ch</a> writes: </footer>
1.33 mike 584: <iframe seamless sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
1.1 mike 585: </article>
586: <article>
587: <footer> At <time pubdate>2009-08-21T23:44Z</time>, <a href="/users/cap">cap</a> writes: </footer>
1.33 mike 588: <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 589: </article>
590: <article>
591: <footer> At <time pubdate>2009-08-21T23:58Z</time>, <a href="/users/ch">ch</a> writes: </footer>
1.33 mike 592: <iframe seamless sandbox srcdoc="<p>hey that's earl's table.
1.1 mike 593: <p>you should get earl&amp;amp;me on the next cover."></iframe>
594: </article></pre>
595:
596: <p>Notice the way that quotes have to be escaped (otherwise the
597: <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute would
598: end prematurely), and the way raw ampersands (e.g. in URLs or in
599: prose) mentioned in the sandboxed content have to be
600: <em>doubly</em> escaped — once so that the ampersand is
601: preserved when originally parsing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and once more
602: to prevent the ampersand from being misinterpreted when parsing the
603: sandboxed content.</p>
604:
605: </div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
606: remember to use U+0022 QUOTATION MARK characters (") to wrap the
607: attribute contents and then to escape all U+0022 QUOTATION MARK (")
608: 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
609: embedding of content.</p><p class="note">Due to restrictions of <span>the XML syntax</span>,
1.24 mike 610: in XML the U+003C LESS-THAN SIGN character (<) needs to be
611: escaped as well. In order to prevent <a href="http://www.w3.org/TR/REC-xml/#AVNormalize">attribute-value
1.39 mike 612: normalization</a>, some of XML's whitespace characters —
1.52 mike 613: specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
1.39 mike 614: (LF), and U+000D CARRIAGE RETURN (CR) — also need to be
615: 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 616: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
617: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
618: browsing context</a>. <span class="impl">When the browsing
619: context is created, if the attribute is present, the <a href="browsers.html#browsing-context-name">browsing
620: context name</a> must be set to the value of this attribute;
621: otherwise, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set to the
622: empty string.</span></p><div class="impl">
623:
624: <p>Whenever the <code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code> attribute
625: 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
626: value. If the attribute is removed, the <a href="browsers.html#browsing-context-name">browsing context
627: name</a> must be set to the empty string.</p>
628:
629: <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
630: 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
631: a simple event</a> named <code title="event-load">load</code> at
632: the <code><a href="#the-iframe-element">iframe</a></code> element. When content whose <a href="urls.html#url">URL</a>
633: has the <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code>
634: element's <code><a href="infrastructure.html#document">Document</a></code> fails to load (e.g. due to a DNS
635: error, network error, or if the server returned a 4xx or 5xx status
636: code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or
637: equivalent</a>), then the user agent must <a href="webappapis.html#queue-a-task">queue a
638: 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
639: does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
640: script errors, or any errors for cross-origin resources.)</p>
641:
642: <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
643: task source</a>.</p>
644:
645: <p class="note">A <code title="event-load">load</code> event is also
646: fired at the <code><a href="#the-iframe-element">iframe</a></code> element when it is created if no
647: other data is loaded in it.</p>
648:
649: <p>When there is an <a href="dom.html#active-parser">active parser</a> in the
650: <code><a href="#the-iframe-element">iframe</a></code>, and when anything in the <code><a href="#the-iframe-element">iframe</a></code> is
651: <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
652: the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a>'s
653: <a href="browsers.html#active-document">active document</a>, the <code><a href="#the-iframe-element">iframe</a></code> must
654: <a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
655:
656: <p class="note">If, during the handling of the <code title="event-load">load</code> event, the <a href="browsers.html#browsing-context">browsing
657: 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
658: load event</a>.</p>
659:
660: </div><hr><p>The <dfn id="attr-iframe-sandbox" title="attr-iframe-sandbox"><code>sandbox</code></dfn>
661: attribute, when specified, enables a set of extra restrictions on
662: any content hosted by the <code><a href="#the-iframe-element">iframe</a></code>. Its value must be an
1.20 mike 663: <a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique space-separated tokens</a> that are
664: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a>. The allowed values are <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>,
1.1 mike 665: <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>,
666: <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code>,
667: and <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>. When
668: the attribute is set, the content is treated as being from a unique
669: <a href="origin-0.html#origin">origin</a>, forms and scripts are disabled, links are
670: prevented from targeting other <a href="browsers.html#browsing-context" title="browsing
671: context">browsing contexts</a>, and plugins are disabled. The
672: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
673: keyword allows the content to be treated as being from the same
674: 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>
675: keyword allows the content to <a href="history.html#navigate">navigate</a> its
676: <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>
677: keywords re-enable forms and scripts respectively (though scripts
678: are still prevented from creating popups).</p><p class="warning">Setting both the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code> and
679: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
680: keywords together when the embedded page has the <a href="origin-0.html#same-origin">same
681: origin</a> as the page containing the <code><a href="#the-iframe-element">iframe</a></code> allows
682: 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
683: an attacker can convince the user to just visit the hostile content
684: directly, rather than in the <code><a href="#the-iframe-element">iframe</a></code>. To limit the
685: damage that can be caused by hostile HTML content, it should be
686: served using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME type.</p><div class="impl">
687:
1.46 mike 688:
1.1 mike 689: <p>While the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
690: attribute is specified, the <code><a href="#the-iframe-element">iframe</a></code> element's
691: <a href="browsers.html#nested-browsing-context">nested browsing context</a> must have the flags given in
692: the following list set. In addition, any browsing contexts <a href="browsers.html#nested-browsing-context" title="nested browsing context">nested</a> within an
693: <code><a href="#the-iframe-element">iframe</a></code>, either directly or indirectly, must have all
694: the flags set on them as were set on the <code><a href="#the-iframe-element">iframe</a></code>'s
695: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> when the
696: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
697:
698: <dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
699:
700: <dd>
701:
702: <p>This flag <a href="history.html#sandboxLinks">prevents content from
703: navigating browsing contexts other than the sandboxed browsing
704: context itself</a> (or browsing contexts further nested inside
705: it), and the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> (which is
706: protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
707: context flag</a> defined next).</p>
708:
709: <p>This flag also <a href="browsers.html#sandboxWindowOpen">prevents content
710: from creating new auxiliary browsing contexts</a>, e.g. using the
711: <code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute or the
712: <code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> method.</p>
713:
714: </dd>
715:
716:
717: <dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
718: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
719: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
720: 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>
721: keyword set</dt>
722:
723: <dd>
724:
725: <p>This flag <a href="history.html#sandboxLinks">prevents content from
726: navigating their <span>top-level browsing context</span></a>.</p>
727:
728: <p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
729: is set, content can navigate its <a href="browsers.html#top-level-browsing-context">top-level browsing
730: context</a>, but other <a href="browsers.html#browsing-context" title="browsing context">browsing
731: contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
732: navigation browsing context flag</a> defined above.</p>
733:
734: </dd>
735:
736:
737: <dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
738:
739: <dd>
740:
741: <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>,
742: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
743: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
744: browsing context</a>.</p>
745:
746: </dd>
747:
748:
749: <dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
750:
751: <dd>
752:
753: <p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attribute on
754: descendant <code><a href="#the-iframe-element">iframe</a></code> elements.</p>
755:
756: <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>
757: keyword from using a CSS-selector-based method of probing the DOM
758: of other pages on the same site (in particular, pages that contain
759: user-sensitive information).</p>
760:
1.46 mike 761:
1.1 mike 762:
763: </dd>
764:
765:
766: <dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn>, unless
767: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
768: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
769: 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>
770: keyword set</dt>
771:
772: <dd>
773:
774: <p>This flag <a href="origin-0.html#sandboxOrigin">forces content into a unique
775: origin</a>, thus preventing it from accessing other content from
776: the same <a href="origin-0.html#origin">origin</a>.</p>
777:
778: <p>This flag also <a href="dom.html#sandboxCookies">prevents script from
779: reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
1.38 mike 780: attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code>.
1.1 mike 781:
782: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
783:
784: </p>
785:
786: <div class="note">
787:
788: <p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
789: attribute is intended for two cases.</p>
790:
791: <p>First, it can be used to allow content from the same site to
792: be sandboxed to disable scripting, while still allowing access to
793: the DOM of the sandboxed content.</p>
794:
795: <p>Second, it can be used to embed content from a third-party
796: site, sandboxed to prevent that site from opening popup windows,
797: etc, without preventing the embedded page from communicating back
798: to its originating site, using the database APIs to store data,
799: etc.</p>
800:
801: </div>
802:
803: </dd>
804:
805:
806: <dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn>, unless
807: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
808: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
809: 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>
810: keyword set</dt>
811:
812: <dd>
813:
814: <p>This flag <a href="association-of-controls-and-forms.html#sandboxSubmitBlocked">blocks form
815: submission</a>.</p>
816:
817: </dd>
818:
819:
820: <dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn>, unless
821: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
822: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
823: 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>
824: keyword set</dt>
825:
826: <dd>
827:
828: <p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
829: execution</a>.</p>
830:
831: </dd>
832:
833:
834: <dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
835: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
836: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
837: found to have the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
838: keyword (defined above) set</dt>
839:
840: <dd>
841:
842: <p>This flag blocks features that trigger automatically, such as
1.47 mike 843: <a href="#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
1.1 mike 844: video</a> or <a href="association-of-controls-and-forms.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
845: focusing a form control</a>. It is relaxed by the same flag as
846: scripts, because when scripts are enabled these features are
847: trivially possible anyway, and it would be unfortunate to force
848: authors to use script to do them when sandboxed rather than
849: allowing them to use the declarative features.</p>
850:
851: </dd>
852:
853: </dl><p>These flags must not be set unless the conditions listed above
854: define them as being set.</p>
855:
856: <p class="warning">These flags only take effect when the
857: <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 858: <a href="history.html#navigate" title="navigate">navigated</a>. Removing them, or removing
1.1 mike 859: the entire <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
860: attribute, has no effect on an already-loaded page.</p>
861:
862: </div><div class="example">
863:
864: <p>In this example, some completely-unknown, potentially hostile,
865: user-provided HTML content is embedded in a page. Because it is
866: sandboxed, it is treated by the user agent as being from a unique
867: origin, despite the content being served from the same site. Thus
868: it is affected by all the normal cross-site restrictions. In
869: addition, the embedded page has scripting disabled, plugins
870: disabled, forms disabled, and it cannot navigate any frames or
871: windows other than itself (or any frames or windows it itself
872: embeds).</p>
873:
874: <pre><p>We're not scared of you! Here is your content, unedited:</p>
875: <iframe sandbox src="getusercontent.cgi?id=12193"></iframe></pre>
876:
877: <p>Note that cookies are still sent to the server in the <code title="">getusercontent.cgi</code> request, though they are not
878: visible in the <code title="dom-document-cookie"><a href="dom.html#dom-document-cookie">document.cookie</a></code> IDL
879: attribute.</p>
880:
881: <p class="warning">It is important that the server serve the
882: user-provided HTML using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME
883: type so that if the attacker convinces the user to visit that page
884: directly, the page doesn't run in the context of the site's origin,
885: which would make the user vulnerable to any attack found in the
886: page.</p>
887:
888: </div><div class="example">
889:
890: <p>In this example, a gadget from another site is embedded. The
891: gadget has scripting and forms enabled, and the origin sandbox
892: restrictions are lifted, allowing the gadget to communicate with
893: its originating server. The sandbox is still useful, however, as it
894: disables plugins and popups, thus reducing the risk of the user
895: being exposed to malware and other annoyances.</p>
896:
897: <pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
898: src="http://maps.example.com/embedded.html"></iframe></pre>
899:
900: </div><div class="example">
901:
902: <p>Suppose a file A contained the following fragment:</p>
903:
904: <pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
905:
906: <p>Suppose that file B contained an iframe also:</p>
907:
908: <pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
909:
910: <p>Further, suppose that file C contained a link:</p>
911:
912: <pre><a href=D>Link</a></pre>
913:
914: <p>For this example, suppose all the files were served as
915: <code><a href="iana.html#text-html">text/html</a></code>.</p>
916:
917: <p>Page C in this scenario has all the sandboxing flags
918: set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
919: scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
920: keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
921: disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
922: have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
923: set.</p>
924:
925: <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
926: B. This would change nothing immediately. If the user clicked the
927: link in C, loading page D into the <code><a href="#the-iframe-element">iframe</a></code> in B, page D
928: 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>
929: and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
930: set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
931: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
932: loaded.</p>
933:
934: <p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
935: ill-advised, because it can make it quite hard to reason about what
936: will be allowed and what will not.</p>
937:
938: </div><p class="note">Potentially hostile files can be served from the
939: same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code> element
940: by labeling them as <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> instead of
941: <code><a href="iana.html#text-html">text/html</a></code>. This ensures that scripts in the files are
942: unable to attack the site (as if they were actually served from
943: another server), even if the user is tricked into visiting those
944: 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>
945: 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>
946: keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
947: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
948: "sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
949: reload itself, effectively breaking out of the sandbox
1.46 mike 950: altogether.</p><hr><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
1.1 mike 951: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
952: indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
953: context</a> is to be rendered in a manner that makes it appear to
954: be part of the containing document (seamlessly included in the
955: parent document). <span class="impl">Specifically, when the
956: attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
957: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
958: the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
959: <code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
960: <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
961: <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
962: document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
963: document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
964: address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
1.33 mike 965: <code><a href="#the-iframe-element">iframe</a></code> element's document, or the <a href="browsers.html#browsing-context">browsing
966: context</a>'s <a href="browsers.html#active-document">active document</a> is <a href="#an-iframe-srcdoc-document">an
967: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
968: document</a>, the following requirements apply:</span></p><div class="impl">
1.1 mike 969:
1.13 mike 970: <ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
971: flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
972: will <a href="history.html#seamlessLinks">cause links to open in the parent
973: browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
974: override</a> is used (<code title="">target="_self"</code>).</p></li>
1.1 mike 975:
976: <li><p>In a CSS-supporting user agent: the user agent must add all
977: the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
978: the cascade of the <a href="browsers.html#active-document">active document</a> of the
979: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
980: at the appropriate cascade levels, before any style sheets
981: specified by the document itself.</p></li>
982:
983: <li><p>In a CSS-supporting user agent: the user agent must, for the
984: purpose of CSS property inheritance only, treat the root element of
985: the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
986: element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
987: the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
988: root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
989: inherit the computed values of those properties on the
990: <code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
991: values.)</p></li>
992:
993: <li><p>In visual media, in a CSS-supporting user agent: the user agent
994: should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
995: width that the element would have if it was a non-replaced
996: block-level element with 'width: auto'.</p></li>
997:
998: <li><p>In visual media, in a CSS-supporting user agent: the user
999: agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
1000: the height of the bounding box around the content rendered in the
1001: <code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
1002: bullet point), as it would be if the scrolling position was such
1003: that the top of the viewport for the content rendered in the
1004: <code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
1005: canvas.</p></li>
1006:
1007: <li>
1008:
1009: <p>In visual media, in a CSS-supporting user agent: the user agent
1010: must force the height of the initial containing block of the
1011: <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
1012: context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
1013:
1014: <p class="note">This is intended to get around the otherwise
1015: circular dependency of percentage dimensions that depend on the
1016: height of the containing block, thus affecting the height of the
1017: document's bounding box, thus affecting the height of the
1018: viewport, thus affecting the size of the initial containing
1019: block.</p>
1020:
1021: </li>
1022:
1023: <li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
1024: browsing context</a> without announcing that it is a separate
1025: document.</p></li>
1026:
1027: <li>
1028:
1029: <p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
1030: document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
1031: context</a> was part of the document that the
1.35 mike 1032: <code><a href="#the-iframe-element">iframe</a></code> is in, if any.</p>
1.1 mike 1033:
1034: <p class="example">For example if the user agent supports listing
1035: all the links in a document, links in "seamlessly" nested
1036: documents would be included in that list without being
1037: significantly distinguished from links in the document itself.</p>
1038:
1039: </li>
1040:
1041: </ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
1042: conditions listed above are not met, then the user agent should
1043: render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
1044: clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
1045: and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
1046: false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
1047:
1048: <p class="warning">It is important that user agents recheck the
1049: above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
1050: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
1051: changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
1052: 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>
1053:
1054: </div><p class="note">The attribute can be set or removed dynamically,
1055: with the rendering updating in tandem.</p><div class="example">
1056:
1057: <p>In this example, the site's navigation is embedded using a
1058: client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
1059: <code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
1060: opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
1061: legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
1062: element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
1063: attribute with the value <code title="">_parent</code>. Similarly,
1064: in new user agents the styles of the parent page will be
1065: automatically applied to the contents of the frame, but to support
1066: legacy user agents authors might wish to include the styles
1067: explicitly.</p>
1068:
1069: <pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
1070:
1071: </div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1072: attributes</a> for cases where the embedded content has specific
1073: 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
1074: content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
1075: context</a>, regardless of whether the specified initial contents
1076: are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
1077: nothing. (In legacy user agents that do not support
1078: <code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
1.18 mike 1079: that could act as fallback content.)</p><p id="iframe-content-model">When used in <a href="dom.html#html-documents">HTML
1080: documents</a>, the allowed content model of <code><a href="#the-iframe-element">iframe</a></code>
1081: elements is text, except that invoking the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment
1082: parsing algorithm</a> with the <code><a href="#the-iframe-element">iframe</a></code> element as the
1.48 mike 1083: <var title="concept-frag-parse-context"><a href="the-end.html#concept-frag-parse-context">context</a></var> element and
1084: the text contents as the <var title="">input</var> must result in a
1085: list of nodes that are all <a href="content-models.html#phrasing-content">phrasing content</a>, with no
1086: <a href="parsing.html#parse-error" title="parse error">parse errors</a> having occurred, with
1087: no <code><a href="scripting-1.html#the-script-element">script</a></code> elements being anywhere in the list or as
1.18 mike 1088: descendants of elements in the list, and with all the elements in
1089: the list (including their descendants) being themselves
1090: conforming.</p><p>The <code><a href="#the-iframe-element">iframe</a></code> element must be empty in <a href="dom.html#xml-documents">XML
1.1 mike 1091: documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
1092: <code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
1093:
1094: <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
1095: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1096: name.</p>
1097:
1098: <p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
1099: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1100: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
1101: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1102:
1103: <p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
1104: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1105: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
1106: context</a>.</p>
1107:
1108: </div><div class="example">
1109:
1110: <p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
1111: include advertising from an advertising broker:</p>
1112:
1113: <pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
1114: width="468" height="60"></iframe></pre>
1115:
1.46 mike 1116: </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 1117: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1118: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1119: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1120: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.16 mike 1121: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1122: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1123: <dt>Content model:</dt>
1124: <dd>Empty.</dd>
1125: <dt>Content attributes:</dt>
1126: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1127: <dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
1128: <dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
1129: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1130: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1131: <dd>Any other attribute that has no namespace (see prose).</dd>
1132: <dt>DOM interface:</dt>
1133: <dd>
1134: <pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1135: attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
1136: attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
1137: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1138: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1139: };</pre>
1140: <div class="impl">
1141: <p>Depending on the type of content instantiated by the
1142: <code><a href="#the-embed-element">embed</a></code> element, the node may also support other
1143: interfaces.</p>
1144: </div>
1145: </dd>
1146: </dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
1147: integration point for an external (typically non-HTML) application
1148: or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
1149: gives the address of the resource being embedded. The attribute, if
1150: present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
1151: surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
1152: attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
1153: plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
1154: 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
1155: <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
1156: same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
1157: 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">
1158:
1159: <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
1160: are removed such that neither attribute is present on the element
1.47 mike 1161: anymore, and when the element has a <a href="#media-element">media element</a>
1.1 mike 1162: ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
1163: element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
1164: content</a>, any plugins instantiated for the element must be
1165: removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
1166:
1167: <p id="sandboxPluginEmbed">If either:
1168:
1169: </p><ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1170: set on the <a href="browsers.html#browsing-context">browsing context</a> for which the
1171: <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> is the
1172: <a href="browsers.html#active-document">active document</a> when that <code><a href="infrastructure.html#document">Document</a></code> was
1173: created, or</li>
1174:
1175: <li>the <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1176: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1177: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1178: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1179:
1180: </ul><p>...then the user agent must render the <code><a href="#the-embed-element">embed</a></code> element
1181: in a manner that conveys that the <a href="infrastructure.html#plugin">plugin</a> was
1182: disabled. The user agent may offer the user the option to override
1183: the sandbox and instantiate the <a href="infrastructure.html#plugin">plugin</a> anyway; if the
1184: user invokes such an option, the user agent must act as if the
1185: conditions above did not apply for the purposes of this element.</p>
1186:
1187: <p class="warning">Plugins are disabled in sandboxed browsing
1188: contexts because they might not honor the restrictions imposed by
1189: the sandbox (e.g. they might allow scripting even when scripting in
1190: the sandbox is disabled). User agents should convey the danger of
1191: overriding the sandbox to the user if an option to do so is
1192: provided.</p>
1193:
1194: <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
1195: following conditions are all met simultaneously:</p>
1196:
1197: <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>
1198: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
1199: <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>
1200: <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>
1201: <li>The element is not in a <code><a href="infrastructure.html#document">Document</a></code> whose <a href="browsers.html#browsing-context">browsing context</a> had the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> set when the <code><a href="infrastructure.html#document">Document</a></code> was created (unless this has been overridden as described above).</li>
1202: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> was not parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> (unless this has been overridden as described above).</li>
1.47 mike 1203: <li>The element is not a descendant of a <a href="#media-element">media element</a>.</li>
1.1 mike 1204: <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>
1205: </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
1206: a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1207: <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
1208: removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1209: <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
1210: removed, the appropriate set of steps from the following is then
1211: applied:</p>
1212:
1213: <dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1214: attribute set</dt>
1215:
1216: <dd>
1217:
1218: <p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
1219: the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1220: attribute, relative to the element. If that is successful, the
1221: user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
1222: URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
1.46 mike 1223: origin</a> if it has one. The <a href="webappapis.html#concept-task" title="concept-task">task</a> that is
1.1 mike 1224: <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking
1225: task source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
1226: 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
1227: <a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
1.46 mike 1228: previously instantiated plugin for the element.</p>
1.1 mike 1229: <p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
1230: the element's document.</p>
1.46 mike 1231:
1232:
1.1 mike 1233: </dd>
1234:
1235: <dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1236: attribute set</dt>
1237:
1238: <dd><p>The user agent should find and instantiate an appropriate
1239: <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>
1240:
1241: </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
1242: <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
1243: <a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
1244: be unloaded.</p>
1245:
1246: <p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
1247: CSS 'display' property. The selected plugin is instantiated even if
1248: the element is hidden with a 'display:none' CSS style.</p>
1249:
1250: <p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
1251: being embedded is defined as follows:</p>
1252:
1253: <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
1254: value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
1255: of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
1256: <a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
1257:
1258: <li>
1259:
1.46 mike 1260:
1.1 mike 1261: <p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
1262: component of the <a href="urls.html#url">URL</a> of the specified resource (after
1263: any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1264: supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
1265: type</a> is the type that that plugin can handle.</p>
1266:
1267: <p class="example">For example, a plugin might say that it can
1268: handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
1269: components that end with the four character string "<code title="">.swf</code>".</p>
1270:
1.46 mike 1271:
1272:
1.1 mike 1273:
1274: </li>
1275:
1276: <li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
1277: that is the <a href="#concept-embed-type" title="concept-embed-type">content's
1278: type</a>.</p></li>
1279:
1280: <li><p>Otherwise, the content has no type and there can be no
1281: appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
1282:
1.46 mike 1283:
1.1 mike 1284:
1285: </ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
1286: content</a>. If the user agent can't find a suitable plugin, then
1287: the user agent must use a default plugin. (This default could be as
1288: simple as saying "Unsupported Format".)</p>
1289:
1290: <p>Whether the resource is fetched successfully or not (e.g. whether
1291: 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
1292: ignored when determining the resource's type and when handing the
1293: resource to the plugin.</p>
1294:
1295: <p class="note">This allows servers to return data for plugins even
1296: with error responses (e.g. HTTP 500 Internal Server Error codes can
1297: still contain plugin data).</p>
1298:
1.46 mike 1299: </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 1300: so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
1301: characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
1302: LATIN CAPITAL LETTER Z). These attributes are then passed as
1303: parameters to the <a href="infrastructure.html#plugin">plugin</a>.</p><p class="note">All attributes in <a href="dom.html#html-documents">HTML documents</a> get
1304: lowercased automatically, so the restriction on uppercase letters
1305: doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
1306: that have side-effects beyond just sending parameters to the
1307: <a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
1308:
1309: <p>The user agent should pass the names and values of all the
1310: attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
1311: to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
1312:
1313: <p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
1314: <code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
1315: <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
1316: expose that interface while the element is instantiated.</p>
1317:
1318: </div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1319: attributes</a>.</p><div class="impl">
1320:
1321: <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
1322: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1323: name.</p>
1324:
1325: </div><div class="example">
1326:
1327: <p>Here's a way to embed a resource that requires a proprietary
1328: plug-in, like Flash:</p>
1329:
1330: <pre><embed src="catgame.swf"></pre>
1331:
1332: <p>If the user does not have the plug-in (for example if the
1333: plug-in vendor doesn't support the user's platform), then the user
1334: will be unable to use the resource.</p>
1335:
1336: <p>To pass the plugin a parameter "quality" with the value "high",
1337: an attribute can be specified:</p>
1338:
1339: <pre><embed src="catgame.swf" quality="high"></pre>
1340:
1341: <p>This would be equivalent to the following, when using an
1342: <code><a href="#the-object-element">object</a></code> element instead:</p>
1343:
1344: <pre><object data="catgame.swf">
1345: <param name="quality" value="high">
1346: </object></pre>
1347:
1.15 mike 1348: </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 1349: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1350: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1351: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1.46 mike 1352: <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 1353: <dd><a href="forms.html#category-listed" title="category-listed">Listed</a>, <a href="forms.html#category-submit" title="category-submit">submittable</a>, <a href="forms.html#form-associated-element">form-associated element</a>.</dd>
1.16 mike 1354: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1355: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1356: <dt>Content model:</dt>
1357: <dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
1358: <dt>Content attributes:</dt>
1359: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1360: <dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
1361: <dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
1362: <dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
1363: <dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
1364: <dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
1365: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1366: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1367: <dt>DOM interface:</dt>
1368: <dd>
1369: <pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1370: attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
1371: attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
1372: attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
1373: attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
1374: 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>;
1375: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1376: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1377: readonly attribute Document <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
1378: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
1379:
1380: readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
1381: 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>;
1382: readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
1383: boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
1384: void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(in DOMString error);
1385: };</pre>
1386: <div class="impl">
1387: <p>Depending on the type of content instantiated by the
1388: <code><a href="#the-object-element">object</a></code> element, the node also supports other
1389: interfaces.</p>
1390: </div>
1391: </dd>
1392: </dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
1393: resource, which, depending on the type of the resource, will either
1394: be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1395: or as an external resource to be processed by a
1396: <a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
1397: attribute, if present, specifies the address of the resource. If
1398: present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1399: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-object-type" title="attr-object-type"><code>type</code></dfn>
1400: attribute, if present, specifies the type of the resource. If
1401: 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-name" title="attr-object-name"><code>name</code></dfn>
1402: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
1403: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
1404: browsing context</a>, if applicable.</p><div class="impl">
1405:
1406: <p>When the element is created, when it is popped off the
1407: <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
1408: or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
1409: <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
1410: document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
1411: document">removed from a document</a>; and whenever the element's
1412: <code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
1413: active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
1414: changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
1415: whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
1416: 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,
1417: whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
1418: 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
1419: its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
1420: changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
1421: to run the following steps to (re)determine what the
1422: <code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
1423: 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 1424: manipulation task source</a>.</p>
1.1 mike 1425: <ol><li>
1426:
1427: <p>If the user has indicated a preference that this
1428: <code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
1429: shown instead of the element's usual behavior, then jump to the
1430: last step in the overall set of steps (fallback).</p>
1431:
1432: <p class="note">For example, a user could ask for the element's
1433: <a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
1434: uses a format that the user finds more accessible.</p>
1435:
1436: </li>
1437:
1438: <li>
1439:
1.47 mike 1440: <p>If the element has an ancestor <a href="#media-element">media element</a>, or
1.1 mike 1441: has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
1442: showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
1443: not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
1444: with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
1445: <code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
1446: element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
1447: <a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
1448: the last step in the overall set of steps (fallback).</p>
1449:
1450: </li>
1451:
1452: <li>
1453:
1.46 mike 1454:
1.1 mike 1455: <p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
1456: attribute is present, and has a value that isn't the empty string,
1457: then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
1458: according to the value of the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute, and <a href="#sandboxPluginObject">plugins aren't being sandboxed</a>,
1459: then that <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be
1460: used</a>, and the value of the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute, if any, should be
1461: passed to the <a href="infrastructure.html#plugin">plugin</a>. If no suitable
1462: <a href="infrastructure.html#plugin">plugin</a> can be found, or if the <a href="infrastructure.html#plugin">plugin</a>
1463: reports an error, jump to the last step in the overall set of
1464: steps (fallback).</p>
1465:
1.46 mike 1466:
1.1 mike 1467: </li>
1468:
1.46 mike 1469:
1.1 mike 1470: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1471: is present and its value is not the empty string, then:</p>
1472:
1473: <ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1474: attribute is present and its value is not a type that the user
1475: agent supports, and is not a type that the user agent can find a
1476: <a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
1477: step in the overall set of steps (fallback) without fetching the
1478: content to examine its real type.</p></li>
1479:
1480: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
1481: <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
1482: element.</p></li>
1483:
1484: <li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1485: <code title="event-error">error</code> at the element, then jump
1486: to the last step in the overall set of steps (fallback).</p></li>
1487:
1488: <li>
1489:
1490: <p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
1491: from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
1.46 mike 1492: it has one.</p>
1.1 mike 1493:
1.46 mike 1494: <p>Fetching the resource
1.1 mike 1495: must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
1496: 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
1497: source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
1498:
1.41 mike 1499: <p>For the purposes of the <a href="offline.html#application-cache">application cache</a>
1500: networking model, this <a href="fetching-resources.html#fetch">fetch</a> operation is not for a
1501: <a href="browsers.html#child-browsing-context">child browsing context</a> (though it might end up
1502: being used for one after all, as defined below).</p>
1503:
1.1 mike 1504: </li>
1505:
1506: <li><p>If the resource is not yet available (e.g. because the
1507: resource was not available in the cache, so that loading the
1508: resource required making a request over the network), then jump
1509: to the last step in the overall set of steps (fallback). The
1510: <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue
1511: a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task source</a>
1512: once the resource is available must restart this algorithm from
1513: this step. Resources can load incrementally; user agents may opt
1514: to consider a resource "available" whenever enough data has been
1515: obtained to begin processing the resource.</p></li>
1516:
1517: <li><p>If the load failed (e.g. there was an HTTP 404 error,
1518: there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1519: <code title="event-error">error</code> at the element, then jump
1520: to the last step in the overall set of steps (fallback).</p></li>
1521:
1522: <li id="object-type-detection">
1523:
1524: <p>Determine the <var title="">resource type</var>, as follows:</p>
1525:
1526:
1527: <ol><li>
1528:
1529: <p>Let the <var title="">resource type</var> be unknown.</p>
1530:
1531: </li>
1532:
1533: <li>
1534:
1.46 mike 1535:
1.1 mike 1536:
1537: <p>If the user agent is configured to strictly obey
1538: Content-Type headers for this resource, and the resource has
1539: <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1540: metadata</a>, then let the <var title="">resource
1541: type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1542: metadata</a>, and jump to the step below labeled
1543: <i>handler</i>.</p>
1544:
1545: </li>
1546:
1547: <li>
1548:
1549: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1550: attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
1551: attribute's value is not a type that the user agent supports,
1552: but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
1553: then let the <var title="">resource type</var> be the type
1554: specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1555: attribute, and jump to the step below labeled
1556: <i>handler</i>.</p>
1557:
1558: </li>
1559:
1560: <li>
1561:
1562: <p>Run the approprate set of steps from the following
1563: list:</p>
1564:
1565: <dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
1566: Content-Type metadata</a></dt>
1567:
1568: <dd>
1569:
1570: <ol><li>
1571:
1572: <p>Let <var title="">binary</var> be false.</p>
1573:
1574: </li>
1575:
1576: <li>
1577:
1578: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1579: resource's Content-Type metadata</a> is
1580: "<code>text/plain</code>", and the result of applying the
1581: <a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
1.49 mike 1582: for distinguishing if a resource is text or binary</a>
1.1 mike 1583: to the resource is that the resource is not
1584: <code>text/plain</code>, then set <var title="">binary</var> to true.</p>
1585:
1586: </li>
1587:
1588: <li>
1589:
1590: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1591: resource's Content-Type metadata</a> is
1592: "<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
1593:
1594: </li>
1595:
1596: <li>
1597:
1598: <p>If <var title="">binary</var> is false, then let the
1599: <var title="">resource type</var> be the type specified in
1600: <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1601: metadata</a>, and jump to the step below labeled
1602: <i>handler</i>.</p>
1603:
1604: </li>
1605:
1606: <li>
1607:
1608: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1609: the <code><a href="#the-object-element">object</a></code> element, and its value is not
1610: <code>application/octet-stream</code>, then run the
1611: following steps:</p>
1612:
1613: <ol><li>
1614:
1615: <p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
1616: 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>,
1617: 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>
1618:
1619: </li>
1620:
1621: <li>
1622:
1623: <p>Jump to the step below labeled <i>handler</i>.</p>
1624:
1625: </li>
1626:
1627: </ol></li>
1628:
1629: </ol></dd>
1630:
1631: <dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1632: metadata</a></dt>
1633:
1634: <dd>
1635:
1636: <ol><li>
1637:
1638: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1639: 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
1640: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1641:
1642: <p>Otherwise, let <var title="">tentative type</var> be the
1643: <a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
1644: resource</a>.</p>
1645:
1646: </li>
1647:
1648: <li>
1649:
1650: <p>If <var title="">tentative type</var> is <em>not</em>
1651: <code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
1652: type</var> and jump to the step below labeled
1653: <i>handler</i>.</p>
1654:
1655: </li>
1656:
1657: </ol></dd>
1658:
1659: </dl></li>
1660:
1661: <li>
1662:
1.46 mike 1663:
1.1 mike 1664: <p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
1665: of the <a href="urls.html#url">URL</a> of the specified resource (after any
1666: redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1667: supports, then let <var title="">resource type</var> be the
1668: type that that plugin can handle.</p>
1669:
1670: <p class="example">For example, a plugin might say that it can
1671: handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
1672: the four character string "<code title="">.swf</code>".</p>
1673:
1.46 mike 1674:
1675:
1.1 mike 1676:
1677: </li>
1678:
1679: </ol><p class="note">It is possible for this step to finish with <var title="">resource type</var> still being unknown, or for one of
1680: the substeps above to jump straight to the next step. In both
1681: cases, the next step will trigger fallback.</p>
1682:
1683: </li>
1684:
1685: <li><p><i>Handler</i>: Handle the content as given by the first
1686: of the following cases that matches:</p>
1687:
1688: <dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
1689: the user agent supports, but it <em>is</em> a type that a
1690: <a href="infrastructure.html#plugin">plugin</a> supports</dt>
1691:
1692: <dd>
1693:
1694: <p>If <a href="#sandboxPluginObject">plugins are being
1695: sandboxed</a>, jump to the last step in the overall set of
1696: steps (fallback).</p>
1697:
1698: <p>Otherwise, the user agent should <a href="#object-plugin">use the plugin that supports <var title="">resource type</var></a> and pass the content of the
1699: resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
1700: <a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
1701: step in the overall set of steps (fallback).</p>
1702:
1703: </dd>
1704:
1705:
1706: <dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
1707: type</a>, or
1.46 mike 1708:
1.1 mike 1709: if the <var title="">resource type</var> does not start with
1710: "<code>image/</code>"</dt>
1711:
1712: <dd>
1713:
1714: <p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
1715: newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
1716: not already have one.</p>
1717:
1718: <p>If the <a href="urls.html#url">URL</a> of the given resource is not
1719: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, the element's <a href="browsers.html#nested-browsing-context">nested browsing
1.46 mike 1720: context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that
1.34 mike 1721: resource, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
1.1 mike 1722: <code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
1.34 mike 1723: context</a> as the <a href="history.html#source-browsing-context">source browsing context</a>.
1724: (The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of
1725: the <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
1.1 mike 1726: browsing context gets further navigated to other
1727: locations.)</p>
1728:
1729: <p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
1730: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, the user agent must
1731: <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a>
1732: named <code title="event-load">load</code> at the
1733: <code><a href="#the-object-element">object</a></code> element.</p>
1734:
1735: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
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:
1771: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
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>
1814: attribute is present, <a href="#sandboxPluginObject">plugins aren't
1815: being sandboxed</a>, and the user agent can find a
1816: <a href="infrastructure.html#plugin">plugin</a> suitable according to the value of the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute, then that
1817: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
1818: no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
1819: <a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the next step
1820: (fallback).</p></li>
1821:
1822: <li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
1823: <a href="rendering.html#represents">represents</a> the element's children, ignoring any
1824: leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
1825: <a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
1826: <a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
1827:
1828: </ol><p id="object-plugin">When the algorithm above instantiates a
1829: <a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
1830: <a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
1831: on the element, in the order they were added to the element, with
1832: the attributes added by the parser being ordered in source order,
1833: followed by a parameter named "PARAM" whose value is null,
1834: followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
1835: <code><a href="#the-param-element">param</a></code> elements that are children of the
1836: <code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
1837: <a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
1838: <code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
1839: should expose that interface. The <code><a href="#the-object-element">object</a></code> element
1840: <a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
1841: <a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
1842: context</a>.</p>
1843:
1844: <p id="sandboxPluginObject">If either:</p>
1845:
1846: <ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1847: set on the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s
1848: <a href="browsers.html#browsing-context">browsing context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was
1849: created, or</li>
1850:
1851: <li>the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1852: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1853: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1854: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1855:
1856: </ul><p>...then the steps above must always act as if they had failed to
1857: find a <a href="infrastructure.html#plugin">plugin</a>, even if one would otherwise have been
1858: used.</p>
1859:
1860: <p class="note">The above algorithm is independent of CSS properties
1861: (including 'display', 'overflow', and 'visibility'). For example, it
1862: runs even if the element is hidden with a 'display:none' CSS style,
1863: and does not run <em>again</em> if the element's visibility
1864: changes.</p>
1865:
1866: <p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
1867: elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
1868: referenced resources can't be shown (e.g. because it returned a 404
1869: error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
1870: nested inside each other, targeting multiple user agents with
1871: different capabilities, with the user agent picking the first one it
1872: supports.</p>
1873:
1874: <p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1875: is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
1876: <a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
1877: name">name</a> must be changed to the new value. If the attribute
1878: is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
1879: context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1880: to the empty string.</p>
1881:
1882: </div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
1883: if present while the <code><a href="#the-object-element">object</a></code> element represents an
1884: image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
1885: map</a>. <span class="impl">The attribute must be ignored if the
1886: <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
1887: explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
1888: <a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
1889:
1890: <p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
1891: elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
1892: validation</a>.</p>
1893:
1894: </div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1895: attributes</a>.</p><div class="impl">
1896:
1897: <p>The IDL attributes <dfn id="dom-object-data" title="dom-object-data"><code>data</code></dfn>, <dfn id="dom-object-type" title="dom-object-type"><code>type</code></dfn>, <dfn id="dom-object-name" title="dom-object-name"><code>name</code></dfn>, and <dfn id="dom-object-usemap" title="dom-object-useMap"><code>useMap</code></dfn> each must
1898: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1899: name.</p>
1900:
1901: <p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
1902: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1903: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
1904: <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
1905: must return null.</p>
1906:
1907: <p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
1908: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1909: <code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1910: if it has one; otherwise, it must return null.</p>
1911:
1912: <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>
1913: 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>
1914: methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
1915: <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
1916: element's forms API.</p>
1917:
1918: </div><div class="example">
1919:
1920: <p>In the following example, a Java applet is embedded in a page
1921: using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
1922: better to avoid using applets like these and instead use native
1923: JavaScript and HTML to provide the functionality, since that way
1924: the application will work on all Web browsers without requiring a
1925: third-party plugin. Many devices, especially embedded devices, do
1926: not support third-party technologies like Java.)</p>
1927:
1928: <pre><figure>
1929: <object type="application/x-java-applet">
1930: <param name="code" value="MyJavaClass">
1931: <p>You do not have Java available, or it is disabled.</p>
1932: </object>
1933: <figcaption>My Java Clock</figcaption>
1934: </figure></pre>
1935:
1936: </div><div class="example">
1937:
1938: <p>In this example, an HTML page is embedded in another using the
1939: <code><a href="#the-object-element">object</a></code> element.</p>
1940:
1941: <pre><figure>
1942: <object data="clock.html"></object>
1943: <figcaption>My HTML Clock</figcaption>
1944: </figure></pre>
1945:
1946: </div><div class="example">
1947:
1948: <p>The following example shows how a plugin can be used in HTML (in
1949: this case the Flash plugin, to show a video file). Fallback is
1950: provided for users who do not have Flash enabled, in this case
1.47 mike 1951: using the <code><a href="#the-video-element">video</a></code> element to show the video for those
1952: using user agents that support <code><a href="#the-video-element">video</a></code>, and finally
1.1 mike 1953: providing a link to the video for those who have neither Flash nor
1.47 mike 1954: a <code><a href="#the-video-element">video</a></code>-capable browser.</p>
1.1 mike 1955:
1956: <pre><p>Look at my video:
1957: <object type="application/x-shockwave-flash">
1958: <param name=movie value="http://video.example.com/library/watch.swf">
1959: <param name=allowfullscreen value=true>
1960: <param name=flashvars value="http://video.example.com/vids/315981">
1961: <video controls src="http://video.example.com/vids/315981">
1962: <a href="http://video.example.com/vids/315981">View video</a>.
1963: </video>
1964: </object>
1965: </p></pre>
1966:
1.15 mike 1967: </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 1968: <dd>None.</dd>
1.16 mike 1969: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1970: <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>
1971: <dt>Content model:</dt>
1972: <dd>Empty.</dd>
1973: <dt>Content attributes:</dt>
1974: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1975: <dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
1976: <dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
1977: <dt>DOM interface:</dt>
1978: <dd>
1979: <pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1980: attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
1981: attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
1982: };</pre>
1983: </dd>
1984: </dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
1985: 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>
1986: attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
1987: attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
1988:
1989: <p>If both attributes are present, and if the parent element of the
1990: <code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
1991: element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
1992: name/value pair.</p>
1993:
1.23 mike 1994: <p>If either the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> defined by a
1995: <code><a href="#the-param-element">param</a></code> element that is the child of an
1996: <code><a href="#the-object-element">object</a></code> element that <a href="rendering.html#represents">represents</a> an
1997: instantiated <a href="infrastructure.html#plugin">plugin</a> changes, and if that
1998: <a href="infrastructure.html#plugin">plugin</a> is communicating with the user agent using an
1999: API that features the ability to update the <a href="infrastructure.html#plugin">plugin</a> when
2000: the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> so changes, then
2001: the user agent must appropriately exercise that ability to notify
2002: the <a href="infrastructure.html#plugin">plugin</a> of the change.</p>
2003:
1.1 mike 2004: <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
2005: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2006: name.</p>
2007:
2008: </div><div class="example">
2009:
2010: <p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
2011: can be used to pass a parameter to a plugin, in this case the O3D
2012: plugin.</p>
2013:
2014: <pre><!DOCTYPE HTML>
2015: <html lang="en">
1.6 mike 2016: <head>
2017: <title>O3D Utah Teapot</title>
2018: </head>
2019: <body>
2020: <p>
2021: <object type="application/vnd.o3d.auto">
2022: <strong><param name="o3d_features" value="FloatingPointTextures"></strong>
2023: <img src="o3d-teapot.png"
2024: title="3D Utah Teapot illustration rendered using O3D."
2025: alt="When O3D renders the Utah Teapot, it appears as a squat
2026: teapot with a shiny metallic finish on which the
2027: surroundings are reflected, with a faint shadow caused by
2028: the lighting.">
2029: <p>To see the teapot actually rendered by O3D on your
2030: computer, please download and install the <a
2031: href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
2032: </object>
2033: <script src="o3d-teapot.js"></script>
2034: </p>
2035: </body>
1.1 mike 2036: </html></pre>
2037:
1.47 mike 2038: </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>
2039: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2040: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2041: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2042: <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>
2043: <dt>Contexts in which this element can be used:</dt>
2044: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2045: <dt>Content model:</dt>
2046: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2047: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2048: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2049: <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
2050: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2051: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2052: <dt>Content attributes:</dt>
2053: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2054: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
2055: <dd><code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code></dd>
2056: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2057: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2058: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2059: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2060: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2061: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2062: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
2063: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
2064: <dt>DOM interface:</dt>
2065: <dd>
2066: <pre class="idl">interface <dfn id="htmlvideoelement">HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {
2067: attribute unsigned long <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
2068: attribute unsigned long <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
2069: readonly attribute unsigned long <a href="#dom-video-videowidth" title="dom-video-videoWidth">videoWidth</a>;
2070: readonly attribute unsigned long <a href="#dom-video-videoheight" title="dom-video-videoHeight">videoHeight</a>;
2071: attribute DOMString <a href="#dom-video-poster" title="dom-video-poster">poster</a>;
2072: };</pre>
2073: </dd>
2074: </dl><p>A <code><a href="#the-video-element">video</a></code> element is used for playing videos or
2075: movies, and audio files with captions.</p><p>Content may be provided inside the <code><a href="#the-video-element">video</a></code>
2076: element<span class="impl">. User agents should not show this content
2077: to the user</span>; it is intended for older Web browsers which do
2078: not support <code><a href="#the-video-element">video</a></code>, so that legacy video plugins can be
2079: tried, or to show text to the users of these older browsers informing
2080: them of how to access the video contents.</p><p class="note">In particular, this content is not intended to
2081: address accessibility concerns. To make video content accessible to
2082: the blind, deaf, and those with other physical or cognitive
2083: disabilities, authors are expected to provide alternative media
2084: streams and/or to embed accessibility aids (such as caption or
2085: subtitle tracks, audio description tracks, or sign-language
2086: overlays) into their media streams.</p><p>The <code><a href="#the-video-element">video</a></code> element is a <a href="#media-element">media element</a>
2087: whose <a href="#media-data">media data</a> is ostensibly video data, possibly
2088: 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>,
2089: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2090: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2091: <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
2092: elements</a>.</p><p>The <dfn id="attr-video-poster" title="attr-video-poster"><code>poster</code></dfn>
2093: attribute gives the address of an image file that the user agent can
2094: show while no video data is available. The attribute, if present,
2095: must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2096: spaces</a>.</p><div class="impl">
2097:
2098: <p>If the specified resource is to be used, then, when the element
2099: is created or when the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
2100: attribute is set, changed, or removed, the user agent must run the
2101: following steps to determine the element's <dfn id="poster-frame">poster
2102: frame</dfn>:</p>
2103: <ol><li><p>If there is an existing instance of this algorithm running
2104: for this <code><a href="#the-video-element">video</a></code> element, abort that instance of this
2105: algorithm without changing the <a href="#poster-frame">poster frame</a>.</p></li>
2106:
2107: <li><p>If the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
1.51 mike 2108: attribute's value is the empty string or if the attribute is
2109: absent, then there is no <a href="#poster-frame">poster frame</a>; abort these
2110: steps.</p></li>
1.47 mike 2111:
2112: <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
2113: to the element. If this fails, then there is no <a href="#poster-frame">poster
2114: frame</a>; abort these steps.</p></li>
2115:
2116: <li><p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
2117: from the element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>.
2118: This must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's
2119: document.</p></li>
2120:
2121:
2122:
2123: <li><p>If an image is thus obtained, the <a href="#poster-frame">poster frame</a>
2124: is that image. Otherwise, there is no <a href="#poster-frame">poster
2125: frame</a>.</p></li>
2126:
2127: </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
2128: frame</a></i>, is intended to be a representative frame of the video
2129: (typically one of the first non-blank frames) that gives the user an
2130: idea of what the video is like.</p><div class="impl">
2131:
2132: <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
2133: <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
2134: 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
2135: subsequent value but the <a href="#media-resource">media resource</a> does not have a
2136: video channel), the <code><a href="#the-video-element">video</a></code> element
2137: <a href="rendering.html#represents">represents</a> either the <a href="#poster-frame">poster frame</a>, or
2138: nothing.</p>
2139:
2140: <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
2141: playback position">current playback position</a> is the first
2142: frame of video, the element <a href="rendering.html#represents">represents</a> either the frame
2143: of video corresponding to the <a href="#current-playback-position" title="current playback
2144: position">current playback position</a> or the <a href="#poster-frame">poster
2145: frame</a>, at the discretion of the user agent.</p>
2146:
2147: <p>Notwithstanding the above, the <a href="#poster-frame">poster frame</a> should
2148: be preferred over nothing, but the <a href="#poster-frame">poster frame</a> should
2149: not be shown again after a frame of video has been shown.</p>
2150:
2151: <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
2152: the <a href="#media-resource">media resource</a> has a video channel, the element
2153: <a href="rendering.html#represents">represents</a> the frame of video corresponding to the
2154: <a href="#current-playback-position" title="current playback position">current playback
2155: position</a>, or, if that is not yet available (e.g. because the
2156: video is seeking or buffering), the last frame of the video to have
2157: been rendered.</p>
2158:
2159: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2160: resource</a> has a video channel is <a href="#potentially-playing">potentially
2161: playing</a>, it <a href="rendering.html#represents">represents</a> the frame of video at the
2162: continuously increasing <a href="#current-playback-position" title="current playback
2163: position">"current" position</a>. When the <a href="#current-playback-position">current playback
2164: position</a> changes such that the last frame rendered is no
2165: longer the frame corresponding to the <a href="#current-playback-position">current playback
2166: position</a> in the video, the new frame must be rendered.
2167:
2168: Similarly, any audio associated with the <a href="#media-resource">media resource</a>
2169: must, if played, be played synchronized with the <a href="#current-playback-position">current
2170: playback position</a>, at the element's <a href="#effective-media-volume">effective media
2171: volume</a>.</p>
2172:
2173: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2174: resource</a> has a video channel is neither <a href="#potentially-playing">potentially
2175: playing</a> nor <a href="#dom-media-paused" title="dom-media-paused">paused</a>
2176: (e.g. when seeking or stalled), the element <a href="rendering.html#represents">represents</a>
2177: the last frame of the video to have been rendered.</p>
2178:
2179: <p class="note">Which frame in a video stream corresponds to a
2180: particular playback position is defined by the video stream's
2181: format.</p>
2182:
2183: <p>The <code><a href="#the-video-element">video</a></code> element also <a href="rendering.html#represents">represents</a> any
2184: <a href="#text-track-cue" title="text track cue">text track cues</a> whose
2185: <a href="#text-track-cue-active-flag">text track cue active flag</a> is set and whose
2186: <a href="#text-track">text track</a> is in the <a href="#text-track-showing" title="text track
2187: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track showing by
2188: default">showing by default</a> modes.</p>
2189:
2190: <p>In addition to the above, the user agent may provide messages to
2191: the user (such as "buffering", "no video loaded", "error", or more
2192: detailed information) by overlaying text or icons on the video or
2193: other areas of the element's playback area, or in another
2194: appropriate manner.</p>
2195:
2196: <p>User agents that cannot render the video may instead make the
2197: element <a href="rendering.html#represents" title="represents">represent</a> a link to an
2198: external video playback utility or to the video data itself.</p>
2199:
2200: <hr></div><dl class="domintro"><dt><var title="">video</var> . <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code></dt>
2201: <dt><var title="">video</var> . <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code></dt>
2202:
2203: <dd>
2204:
2205: <p>These attributes return the intrinsic dimensions of the video,
2206: or zero if the dimensions are not known.</p>
2207:
2208: </dd>
2209:
2210: </dl><div class="impl">
2211:
2212: <p>The <dfn id="concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2213: width</dfn> and <dfn id="concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</dfn> of the
2214: <a href="#media-resource">media resource</a> are the dimensions of the resource in
2215: CSS pixels after taking into account the resource's dimensions,
2216: aspect ratio, clean aperture, resolution, and so forth, as defined
2217: for the format used by the resource. If an anamorphic format does
2218: not define how to apply the aspect ratio to the video data's
2219: dimensions to obtain the "correct" dimensions, then the user agent
2220: must apply the ratio by increasing one dimension and leaving the
2221: other unchanged.</p>
2222:
2223: <p>The <dfn id="dom-video-videowidth" title="dom-video-videoWidth"><code>videoWidth</code></dfn> IDL
2224: attribute must return the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> of the
2225: video in CSS pixels. The <dfn id="dom-video-videoheight" title="dom-video-videoHeight"><code>videoHeight</code></dfn> IDL
2226: attribute must return the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> of
2227: 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
2228: attributes must return 0.</p>
2229:
2230: </div><p>The <code><a href="#the-video-element">video</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
2231: attributes</a>.</p><div class="impl">
2232:
2233: <p>In the absence of style rules to the contrary, video content
2234: should be rendered inside the element's playback area such that the
2235: video content is shown centered in the playback area at the largest
2236: possible size that fits completely within it, with the video
2237: content's aspect ratio being preserved. Thus, if the aspect ratio of
2238: the playback area does not match the aspect ratio of the video, the
2239: video will be shown letterboxed or pillarboxed. Areas of the
2240: element's playback area that do not contain the video represent
2241: nothing.</p>
2242:
2243: <p class="note">In user agents that implement CSS, the above
2244: requirement can be implemented by using the <a href="rendering.html#video-object-fit">style rule suggested in the rendering
2245: section</a>.</p>
2246:
2247: <p>The intrinsic width of a <code><a href="#the-video-element">video</a></code> element's playback
2248: area is the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2249: width</a> of the video resource, if that is available; otherwise
2250: it is the intrinsic width of the <a href="#poster-frame">poster frame</a>, if that
2251: is available; otherwise it is 300 CSS pixels.</p>
2252:
2253: <p>The intrinsic height of a <code><a href="#the-video-element">video</a></code> element's playback
2254: area is the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic
2255: height</a> of the video resource, if that is available; otherwise
2256: it is the intrinsic height of the <a href="#poster-frame">poster frame</a>, if that
2257: is available; otherwise it is 150 CSS pixels.</p>
2258:
2259: <hr><p>User agents should provide controls to enable or disable the
2260: display of closed captions, audio description tracks, and other
2261: additional data associated with the video stream, though such
2262: features should, again, not interfere with the page's normal
2263: rendering.</p>
2264:
2265: <p>User agents may allow users to view the video content in manners
2266: more suitable to the user (e.g. full-screen or in an independent
2267: resizable window). As for the other user interface features,
2268: controls to enable this should not interfere with the page's normal
2269: rendering unless the user agent is <a href="#expose-a-user-interface-to-the-user" title="expose a user
2270: interface to the user">exposing a user interface</a>. In such an
2271: independent context, however, user agents may make full user
2272: interfaces visible, with, e.g., play, pause, seeking, and volume
2273: controls, even if the <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute is absent.</p>
2274:
2275: <p>User agents may allow video playback to affect system features
2276: that could interfere with the user's experience; for example, user
2277: agents could disable screensavers while video playback is in
2278: progress.</p>
2279:
2280: <hr><p>The <dfn id="dom-video-poster" title="dom-video-poster"><code>poster</code></dfn> IDL
2281: 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>
2282:
2283: </div><div class="example">
2284:
2285: <p>This example shows how to detect when a video has failed to play
2286: correctly:</p>
2287:
2288: <pre><script>
2289: function failed(e) {
2290: // video playback failed - show a message saying why
2291: switch (e.target.error.code) {
2292: case e.target.error.MEDIA_ERR_ABORTED:
2293: alert('You aborted the video playback.');
2294: break;
2295: case e.target.error.MEDIA_ERR_NETWORK:
2296: alert('A network error caused the video download to fail part-way.');
2297: break;
2298: case e.target.error.MEDIA_ERR_DECODE:
2299: alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
2300: break;
2301: case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
2302: alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
2303: break;
2304: default:
2305: alert('An unknown error occurred.');
2306: break;
2307: }
2308: }
2309: </script>
2310: <p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
2311: <p><a href="tgif.vid">Download the video file</a>.</p></pre>
2312:
2313: </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>
2314: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2315: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2316: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2317: <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>
2318: <dt>Contexts in which this element can be used:</dt>
2319: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2320: <dt>Content model:</dt>
2321: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2322: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2323: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2324: <dd>If the element does not have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute: one or more <code><a href="#the-source-element">source</a></code> elements, then
2325: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2326: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2327: <dt>Content attributes:</dt>
2328: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2329: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
2330: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2331: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2332: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2333: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2334: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2335: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2336: <dt>DOM interface:</dt>
2337: <dd>
2338: <pre class="idl">[NamedConstructor=<a href="#dom-audio" title="dom-Audio">Audio</a>(),
2339: NamedConstructor=<a href="#dom-audio-s" title="dom-Audio-s">Audio</a>(in DOMString src)]
2340: interface <dfn id="htmlaudioelement">HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {};</pre>
2341: </dd>
2342: </dl><p>An <code><a href="#the-audio-element">audio</a></code> element <a href="rendering.html#represents">represents</a> a sound or
2343: audio stream.</p><p>Content may be provided inside the <code><a href="#the-audio-element">audio</a></code>
2344: element<span class="impl">. User agents should not show this content
2345: to the user</span>; it is intended for older Web browsers which do
2346: not support <code><a href="#the-audio-element">audio</a></code>, so that legacy audio plugins can be
2347: tried, or to show text to the users of these older browsers informing
2348: them of how to access the audio contents.</p><p class="note">In particular, this content is not intended to
2349: address accessibility concerns. To make audio content accessible to
2350: the deaf or to those with other physical or cognitive disabilities,
2351: authors are expected to provide alternative media streams and/or to
2352: embed accessibility aids (such as transcriptions) into their media
2353: streams.</p><p>The <code><a href="#the-audio-element">audio</a></code> element is a <a href="#media-element">media element</a>
2354: 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>,
2355: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2356: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2357: <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
2358: elements</a>.</p><div class="impl">
2359:
2360: <p>When an <code><a href="#the-audio-element">audio</a></code> element is <a href="#potentially-playing">potentially
2361: playing</a>, it must have its audio data played synchronized with
2362: the <a href="#current-playback-position">current playback position</a>, at the element's
2363: <a href="#effective-media-volume">effective media volume</a>.</p>
2364:
2365: <p>When an <code><a href="#the-audio-element">audio</a></code> element is not <a href="#potentially-playing">potentially
2366: playing</a>, audio must not play for the element.</p>
2367:
2368: </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>
2369:
2370: <dd>
2371:
2372: <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
2373: passed in the argument, if applicable.</p>
2374:
2375: </dd>
2376:
2377: </dl><div class="impl">
2378:
2379: <p>Two constructors are provided for creating
2380: <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> objects (in addition to the factory
2381: 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,
2382: these must return a new <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new
2383: <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
2384: 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
2385: its <code title="attr-media-src"><a href="#attr-media-src">src</a></code> content attribute set to
2386: the provided value, and the user agent must invoke the object's
2387: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2388: algorithm</a> before returning. The element's document must be
2389: the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
2390: context</a> of the <code><a href="browsers.html#window">Window</a></code> object on which the
2391: interface object of the invoked constructor is found.</p>
2392:
2393: </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>
2394: <dd>None.</dd>
2395: <dt>Contexts in which this element can be used:</dt>
2396: <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>
2397: or <code><a href="#the-track-element">track</a></code> elements.</dd>
2398: <dt>Content model:</dt>
2399: <dd>Empty.</dd>
2400: <dt>Content attributes:</dt>
2401: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2402: <dd><code title="attr-source-src"><a href="#attr-source-src">src</a></code></dd>
2403: <dd><code title="attr-source-type"><a href="#attr-source-type">type</a></code></dd>
2404: <dd><code title="attr-source-media"><a href="#attr-source-media">media</a></code></dd>
2405: <dt>DOM interface:</dt>
2406: <dd>
2407: <pre class="idl">interface <dfn id="htmlsourceelement">HTMLSourceElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2408: attribute DOMString <a href="#dom-source-src" title="dom-source-src">src</a>;
2409: attribute DOMString <a href="#dom-source-type" title="dom-source-type">type</a>;
2410: attribute DOMString <a href="#dom-source-media" title="dom-source-media">media</a>;
2411: };</pre>
2412: </dd>
2413: </dl><p>The <code><a href="#the-source-element">source</a></code> element allows authors to specify
2414: multiple alternative <a href="#media-resource" title="media resource">media
2415: resources</a> for <a href="#media-element" title="media element">media
2416: 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
2417: gives the address of the <a href="#media-resource">media resource</a>. The value must
2418: be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2419: spaces</a>. This attribute must be present.</p><p class="note">Dynamically modifying a <code><a href="#the-source-element">source</a></code> element
2420: and its attribute when the element is already inserted in a
2421: <code><a href="#the-video-element">video</a></code> or <code><a href="#the-audio-element">audio</a></code> element will have no
2422: effect. To change what is playing, either just use the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute on the <a href="#media-element">media
2423: element</a> directly, or call the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code> method on the <a href="#media-element">media
2424: element</a> after manipulating the <code><a href="#the-source-element">source</a></code>
2425: elements.</p><p>The <dfn id="attr-source-type" title="attr-source-type"><code>type</code></dfn>
2426: attribute gives the type of the <a href="#media-resource">media resource</a>, to help
2427: the user agent determine if it can play this <a href="#media-resource">media
2428: resource</a> before fetching it. If specified, its value must be
2429: a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>. The <code title="">codecs</code>
2430: parameter, which certain MIME types define, might be necessary to
2431: specify exactly how the resource is encoded. <a href="references.html#refsRFC4281">[RFC4281]</a></p><div class="example">
2432:
2433: <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>
2434:
2435: <dl><dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2436: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></pre></dd>
2437:
2438: <dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2439: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></pre></dd>
2440:
2441: <dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
2442: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></pre></dd>
2443:
2444: <dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2445: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></pre></dd>
2446:
2447:
2448: <dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2449: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></pre></dd>
2450:
2451: <dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2452: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></pre></dd>
2453:
2454: <dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
2455: <dd><pre><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></pre></dd>
2456:
2457:
2458: <dt>Theora video and Vorbis audio in Ogg container</dt>
2459: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></pre></dd>
2460:
2461: <dt>Theora video and Speex audio in Ogg container</dt>
2462: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></pre></dd>
2463:
2464: <dt>Vorbis audio alone in Ogg container</dt>
2465: <dd><pre><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></pre></dd>
2466:
2467: <dt>Speex audio alone in Ogg container</dt>
2468: <dd><pre><source src='audio.spx' type='audio/ogg; codecs=speex'></pre></dd>
2469:
2470: <dt>FLAC audio alone in Ogg container</dt>
2471: <dd><pre><source src='audio.oga' type='audio/ogg; codecs=flac'></pre></dd>
2472:
2473: <dt>Dirac video and Vorbis audio in Ogg container</dt>
2474: <dd><pre><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></pre></dd>
2475:
2476:
2477:
2478:
2479:
2480:
2481: </dl></div><p>The <dfn id="attr-source-media" title="attr-source-media"><code>media</code></dfn>
2482: attribute gives the intended media type of the <a href="#media-resource">media
2483: resource</a>, to help the user agent determine if this
2484: <a href="#media-resource">media resource</a> is useful to the user before fetching
2485: 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
2486: "<code title="">all</code>", meaning that by default the <a href="#media-resource">media
2487: resource</a> is suitable for all media.</p><div class="impl">
2488:
2489: <p>If a <code><a href="#the-source-element">source</a></code> element is inserted as a child of a
2490: <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
2491: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, the user
2492: 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
2493: algorithm</a>.</p>
2494:
2495: <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
2496: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2497: name.</p>
2498:
2499: </div><div class="example">
2500:
2501: <p>If the author isn't sure if the user agents will all be able to
2502: render the media resources provided, the author can listen to the
2503: <code title="event-error">error</code> event on the last
2504: <code><a href="#the-source-element">source</a></code> element and trigger fallback behavior:</p>
2505:
2506: <pre><script>
2507: function fallback(video) {
2508: // replace <video> with its contents
2509: while (video.hasChildNodes()) {
2510: if (video.firstChild instanceof HTMLSourceElement)
2511: video.removeChild(video.firstChild);
2512: else
2513: video.parentNode.insertBefore(video.firstChild, video);
2514: }
2515: video.parentNode.removeChild(video);
2516: }
2517: </script>
2518: <video controls autoplay>
2519: <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
2520: <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
2521: onerror="fallback(parentNode)">
2522: ...
2523: </video></pre>
2524:
2525: </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>
2526: <dd>None.</dd>
2527: <dt>Contexts in which this element can be used:</dt>
2528: <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>
2529: <dt>Content model:</dt>
2530: <dd>Empty.</dd>
2531: <dt>Content attributes:</dt>
2532: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2533: <dd><code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code></dd>
2534: <dd><code title="attr-track-src"><a href="#attr-track-src">src</a></code></dd>
2535: <dd><code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code></dd>
2536: <dd><code title="attr-track-label"><a href="#attr-track-label">label</a></code></dd>
2537: <dd><code title="attr-track-default"><a href="#attr-track-default">default</a></code></dd>
2538: <dt>DOM interface:</dt>
2539: <dd>
2540: <pre class="idl">interface <dfn id="htmltrackelement">HTMLTrackElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2541: attribute DOMString <a href="#dom-track-kind" title="dom-track-kind">kind</a>;
2542: attribute DOMString <a href="#dom-track-src" title="dom-track-src">src</a>;
2543: attribute DOMString <a href="#dom-track-srclang" title="dom-track-srclang">srclang</a>;
2544: attribute DOMString <a href="#dom-track-label" title="dom-track-label">label</a>;
2545: attribute boolean <a href="#dom-track-default" title="dom-track-default">default</a>;
2546:
2547: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-track-track" title="dom-track-track">track</a>;
2548: };</pre>
2549: </dd>
2550: </dl><p>The <code><a href="#the-track-element">track</a></code> element allows authors to specify explicit
2551: 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>
2552: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following
2553: table lists the keywords defined for this attribute. The keyword
2554: given in the first cell of each row maps to the state given in the
2555: second cell.</p><table><thead><tr><th>Keyword
2556: </th><th>State
2557: </th><th>Brief description
2558: </th></tr></thead><tbody><tr><td><dfn id="attr-track-kind-keyword-subtitles" title="attr-track-kind-keyword-subtitles"><code>subtitles</code></dfn>
2559: </td><td><dfn id="attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</dfn>
2560: </td><td>
2561: Transcription or translation of the dialogue, suitable for when the sound is available but not understood (e.g. because the user does not understand the language of the <a href="#media-resource">media resource</a>'s soundtrack).
2562: Displayed over the video.
2563: </td></tr><tr><td><dfn id="attr-track-kind-keyword-captions" title="attr-track-kind-keyword-captions"><code>captions</code></dfn>
2564: </td><td><dfn id="attr-track-kind-captions" title="attr-track-kind-captions">Captions</dfn>
2565: </td><td>
2566: Transcription or translation of the dialogue, sound effects, relevant musical cues, and other relevant audio information, suitable for when the soundtrack is unavailable (e.g. because it is muted or because the user is deaf).
2567: Displayed over the video; labeled as appropriate for the hard-of-hearing.
2568: </td></tr><tr><td><dfn id="attr-track-kind-keyword-descriptions" title="attr-track-kind-keyword-descriptions"><code>descriptions</code></dfn>
2569: </td><td><dfn id="attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</dfn>
2570: </td><td>
2571: Textual descriptions of the video component of the <a href="#media-resource">media resource</a>, intended for audio synthesis when the visual component is unavailable (e.g. because the user is interacting with the application without a screen while driving, or because the user is blind).
2572: Synthesized as separate audio track.
2573: </td></tr><tr><td><dfn id="attr-track-kind-keyword-chapters" title="attr-track-kind-keyword-chapters"><code>chapters</code></dfn>
2574: </td><td><dfn id="attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</dfn>
2575: </td><td>
2576: Chapter titles, intended to be used for navigating the <a href="#media-resource">media resource</a>.
2577: Displayed as an interactive list in the user agent's interface.
2578: </td></tr><tr><td><dfn id="attr-track-kind-keyword-metadata" title="attr-track-kind-keyword-metadata"><code>metadata</code></dfn>
2579: </td><td><dfn id="attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</dfn>
2580: </td><td>
2581: Tracks intended for use from script.
2582: Not displayed by the user agent.
2583: </td></tr></tbody></table><p>The attribute may be omitted. The <i>missing value default</i> is
2584: 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
2585: gives the address of the text track data. The value must be a
2586: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2587: spaces</a>. This attribute must be present.</p><div class="impl">
2588:
2589: <p>If the element has a <code title="attr-track-src"><a href="#attr-track-src">src</a></code>
2590: attribute whose value is not the empty string and whose value, when
2591: the attribute was set, could be successfully <a href="urls.html#resolve-a-url" title="resolve a
2592: url">resolved</a> relative to the element, then the element's
2593: <dfn id="track-url">track URL</dfn> is the resulting <a href="urls.html#absolute-url">absolute
2594: URL</a>. Otherwise, the element's <a href="#track-url">track URL</a> is the
2595: empty string.</p>
2596:
2597: </div><p>The <dfn id="attr-track-srclang" title="attr-track-srclang"><code>srclang</code></dfn>
2598: attribute gives the language of the text track data. The value must
2599: be a valid BCP 47 language tag. This attribute must be present if
2600: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute is
2601: in the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a>
2602: state. <a href="references.html#refsBCP47">[BCP47]</a></p><div class="impl">
2603:
2604: <p>If the element has a <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attribute whose value is
2605: not the empty string, then the element's <dfn id="track-language">track language</dfn>
2606: is the value of the attribute. Otherwise, the element has no
2607: <a href="#track-language">track language</a>.</p>
2608:
2609: </div><p>The <dfn id="attr-track-label" title="attr-track-label"><code>label</code></dfn>
2610: attribute gives a user-readable title for the track. This title is
2611: 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
2612: in their user interface.</p><p>The value of the <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2613: attribute, if the attribute is present, must not be the empty
2614: string. Furthermore, there must not be two <code><a href="#the-track-element">track</a></code>
2615: 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
2616: state, whose <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code>
2617: attributes are both missing or have values that represent the same
2618: language, and whose <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2619: attributes are again both missing or both have the same value.</p><div class="impl">
2620:
2621: <p>If the element has a <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2622: attribute whose value is not the empty string, then the element's
2623: <dfn id="track-label">track label</dfn> is the value of the attribute. Otherwise, the
2624: element's <a href="#track-label">track label</a> is a user-agent defined string
2625: (e.g. the string "untitled" in the user's locale, or a value
2626: automatically generated from the other attributes).</p>
2627:
2628: </div><p>The <dfn id="attr-track-default" title="attr-track-default"><code>default</code></dfn>
2629: attribute, if specified, indicates that the track is to be enabled
2630: if the user's preferences do not indicate that another track would
2631: be more appropriate. There must not be more than one
2632: <code><a href="#the-track-element">track</a></code> element with the same parent node with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute specified.</p><dl class="domintro"><dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
2633:
2634: <dd>
2635:
2636: <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>
2637:
2638: </dd>
2639:
2640: </dl><div class="impl">
2641:
2642: <p>The <dfn id="dom-track-track" title="dom-track-track"><code>track</code></dfn> IDL
2643: attribute must, on getting, return the <code><a href="#the-track-element">track</a></code> element's
2644: <a href="#text-track">text track</a>'s corresponding <code><a href="#texttrack">TextTrack</a></code>
2645: object.</p>
2646:
2647: <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
2648: must <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the
2649: same name. The <dfn id="dom-track-kind" title="dom-track-kind"><code>kind</code></dfn>
2650: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
2651: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
2652:
2653: </div><div class="example">
2654:
2655: <p>This video has subtitles in several languages:</p>
2656:
2657: <pre><video src="brave.webm">
2658: <track kind=subtitles src=brave.en.vtt srclang=en label="English">
2659: <track kind=captions src=brave.en.vtt srclang=en label="English for the Hard of Hearing">
2660: <track kind=subtitles src=brave.fr.vtt srclang=fr label="Français">
2661: <track kind=subtitles src=brave.de.vtt srclang=de label="Deutsch">
2662: </video></pre>
2663:
2664: </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>
2665: (<code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>, in this specification)
2666: implement the following interface:</p><pre class="idl">interface <dfn id="htmlmediaelement">HTMLMediaElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2667:
2668: // error state
2669: readonly attribute <a href="#mediaerror">MediaError</a> <a href="#dom-media-error" title="dom-media-error">error</a>;
2670:
2671: // network state
2672: attribute DOMString <a href="#dom-media-src" title="dom-media-src">src</a>;
2673: readonly attribute DOMString <a href="#dom-media-currentsrc" title="dom-media-currentSrc">currentSrc</a>;
2674: const unsigned short <a href="#dom-media-network_empty" title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</a> = 0;
2675: const unsigned short <a href="#dom-media-network_idle" title="dom-media-NETWORK_IDLE">NETWORK_IDLE</a> = 1;
2676: const unsigned short <a href="#dom-media-network_loading" title="dom-media-NETWORK_LOADING">NETWORK_LOADING</a> = 2;
2677: const unsigned short <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a> = 3;
2678: readonly attribute unsigned short <a href="#dom-media-networkstate" title="dom-media-networkState">networkState</a>;
2679: attribute DOMString <a href="#dom-media-preload" title="dom-media-preload">preload</a>;
2680: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-buffered" title="dom-media-buffered">buffered</a>;
2681: void <a href="#dom-media-load" title="dom-media-load">load</a>();
2682: DOMString <a href="#dom-navigator-canplaytype" title="dom-navigator-canPlayType">canPlayType</a>(in DOMString type);
2683:
2684: // ready state
2685: const unsigned short <a href="#dom-media-have_nothing" title="dom-media-HAVE_NOTHING">HAVE_NOTHING</a> = 0;
2686: const unsigned short <a href="#dom-media-have_metadata" title="dom-media-HAVE_METADATA">HAVE_METADATA</a> = 1;
2687: const unsigned short <a href="#dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</a> = 2;
2688: const unsigned short <a href="#dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</a> = 3;
2689: const unsigned short <a href="#dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</a> = 4;
2690: readonly attribute unsigned short <a href="#dom-media-readystate" title="dom-media-readyState">readyState</a>;
2691: readonly attribute boolean <a href="#dom-media-seeking" title="dom-media-seeking">seeking</a>;
2692:
2693: // playback state
2694: attribute double <a href="#dom-media-currenttime" title="dom-media-currentTime">currentTime</a>;
2695: readonly attribute double <a href="#dom-media-initialtime" title="dom-media-initialTime">initialTime</a>;
2696: readonly attribute double <a href="#dom-media-duration" title="dom-media-duration">duration</a>;
2697: readonly attribute <span>Date</span> <a href="#dom-media-startoffsettime" title="dom-media-startOffsetTime">startOffsetTime</a>;
2698: readonly attribute boolean <a href="#dom-media-paused" title="dom-media-paused">paused</a>;
2699: attribute double <a href="#dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate">defaultPlaybackRate</a>;
2700: attribute double <a href="#dom-media-playbackrate" title="dom-media-playbackRate">playbackRate</a>;
2701: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-played" title="dom-media-played">played</a>;
2702: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-seekable" title="dom-media-seekable">seekable</a>;
2703: readonly attribute boolean <a href="#dom-media-ended" title="dom-media-ended">ended</a>;
2704: attribute boolean <a href="#dom-media-autoplay" title="dom-media-autoplay">autoplay</a>;
2705: attribute boolean <a href="#dom-media-loop" title="dom-media-loop">loop</a>;
2706: void <a href="#dom-media-play" title="dom-media-play">play</a>();
2707: void <a href="#dom-media-pause" title="dom-media-pause">pause</a>();
2708:
2709: // media controller
2710: attribute <span>DOMString</span> <a href="#dom-media-mediagroup" title="dom-media-mediaGroup">mediaGroup</a>;
2711: attribute <a href="#mediacontroller">MediaController</a> <a href="#dom-media-controller" title="dom-media-controller">controller</a>;
2712:
2713: // controls
2714: attribute boolean <a href="#dom-media-controls" title="dom-media-controls">controls</a>;
2715: attribute double <a href="#dom-media-volume" title="dom-media-volume">volume</a>;
2716: attribute boolean <a href="#dom-media-muted" title="dom-media-muted">muted</a>;
2717: attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
2718:
2719: // tracks
2720: readonly attribute <a href="#multipletracklist">MultipleTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
2721: readonly attribute <a href="#exclusivetracklist">ExclusiveTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
2722: readonly attribute <a href="#texttrack">TextTrack</a>[] <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
2723: <a href="#mutabletexttrack">MutableTextTrack</a> <a href="#dom-media-addtexttrack" title="dom-media-addTextTrack">addTextTrack</a>(in DOMString kind, in optional DOMString label, in optional DOMString language);
2724: };</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-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
2725: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2726: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2727: <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
2728: this section.</p><p><a href="#media-element" title="media element">Media elements</a> are used to
2729: present audio data, or video and audio data, to the user. This is
2730: referred to as <dfn id="media-data">media data</dfn> in this section, since this
2731: section applies equally to <a href="#media-element" title="media element">media
1.56 ! mike 2732: elements</a> for audio or for video.
! 2733: The term <dfn id="media-resource">media resource</dfn> is used to refer to the complete
! 2734: set of media data, e.g. the complete video file, or complete audio
! 2735: file.
! 2736: </p><p>A <a href="#media-resource">media resource</a> can have multiple audio and video
1.47 mike 2737: tracks. For the purposes of a <a href="#media-element">media element</a>, the video
2738: data of the <a href="#media-resource">media resource</a> is only that of the
2739: 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
2740: audio data of the <a href="#media-resource">media resource</a> is the result of
2741: mixing all the currently enabled tracks (if any) given by the
2742: element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>
2743: 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>
2744: elements can be used for both audio and video. The main difference
2745: between the two is simply that the <code><a href="#the-audio-element">audio</a></code> element has no
2746: playback area for visual content (such as video or captions),
2747: whereas the <code><a href="#the-video-element">video</a></code> element does.</p><div class="impl">
2748:
2749: <p>Except where otherwise specified, the <a href="webappapis.html#task-source">task source</a>
2750: for all the tasks <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> in this
2751: section and its subsections is the <dfn id="media-element-event-task-source">media element event task
2752: source</dfn>.</p>
2753:
2754: </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>
2755:
2756: <dd>
2757:
2758: <p>Returns a <code><a href="#mediaerror">MediaError</a></code> object representing the
2759: current error state of the element.</p>
2760:
2761: <p>Returns null if there is no error.</p>
2762:
2763: </dd>
2764:
2765: </dl><div class="impl">
2766:
2767: <p>All <a href="#media-element" title="media element">media elements</a> have an
2768: associated error status, which records the last error the element
2769: encountered since its <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2770: algorithm</a> was last invoked. The <dfn id="dom-media-error" title="dom-media-error"><code>error</code></dfn> attribute, on
2771: getting, must return the <code><a href="#mediaerror">MediaError</a></code> object created for
2772: this last error, or null if there has not been an error.</p>
2773:
2774: </div><pre class="idl">interface <dfn id="mediaerror">MediaError</dfn> {
2775: const unsigned short <a href="#dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</a> = 1;
2776: const unsigned short <a href="#dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</a> = 2;
2777: const unsigned short <a href="#dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</a> = 3;
2778: 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;
2779: readonly attribute unsigned short <a href="#dom-mediaerror-code" title="dom-MediaError-code">code</a>;
2780: };</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>
2781:
2782: <dd>
2783:
2784: <p>Returns the current error's error code, from the list below.</p>
2785:
2786: </dd>
2787:
2788: </dl><div class="impl">
2789:
2790: <p>The <dfn id="dom-mediaerror-code" title="dom-MediaError-code"><code>code</code></dfn>
2791: attribute of a <code><a href="#mediaerror">MediaError</a></code> object must return the code
2792: for the error, which must be one of the following:</p>
2793:
2794: </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>
2795:
2796: <dd>The fetching process for the <a href="#media-resource">media resource</a> was
2797: aborted by the user agent at the user's request.</dd>
2798:
2799: <dt><dfn id="dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK"><code>MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
2800:
2801: <dd>A network error of some description caused the user agent to
2802: stop fetching the <a href="#media-resource">media resource</a>, after the resource
2803: was established to be usable.</dd>
2804:
2805: <dt><dfn id="dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE"><code>MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
2806:
2807: <dd>An error of some description occurred while decoding the
2808: <a href="#media-resource">media resource</a>, after the resource was established to
2809: be usable.</dd>
2810:
2811: <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>
2812:
2813: <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>
2814:
2815: </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
2816: attribute on <a href="#media-element" title="media element">media elements</a> gives
2817: the address of the media resource (video, audio) to show. The
2818: attribute, if present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
2819: URL potentially surrounded by spaces</a>.</p><div class="impl">
2820:
2821: <p>If a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute of a
2822: <a href="#media-element">media element</a> is set or changed, the user agent must
2823: invoke the <a href="#media-element">media element</a>'s <a href="#media-element-load-algorithm">media element load
2824: 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
2825: if there are <code><a href="#the-source-element">source</a></code> elements present.)</p>
2826:
2827: <p>The <dfn id="dom-media-src" title="dom-media-src"><code>src</code></dfn> IDL
2828: attribute on <a href="#media-element" title="media element">media elements</a> must
2829: <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the same name.</p>
2830:
2831: </div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code></dt>
2832:
2833: <dd>
2834:
2835: <p>Returns the address of the current <a href="#media-resource">media resource</a>.</p>
2836:
2837: <p>Returns the empty string when there is no <a href="#media-resource">media resource</a>.</p>
2838:
2839: </dd>
2840:
2841: </dl><div class="impl">
2842:
2843: <p>The <dfn id="dom-media-currentsrc" title="dom-media-currentSrc"><code>currentSrc</code></dfn> IDL
2844: attribute is initially the empty string. Its value is changed by the
2845: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2846: algorithm</a> defined below.</p>
2847:
2848: </div><p class="note">There are two ways to specify a <a href="#media-resource">media
2849: resource</a>, the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
2850: attribute, or <code><a href="#the-source-element">source</a></code> elements. The attribute overrides
1.53 mike 2851: 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 2852: <em>type</em>, specifically a <a href="infrastructure.html#mime-type">MIME type</a>, in some cases
2853: with a <code title="">codecs</code> parameter. (Whether the <code title="">codecs</code> parameter is allowed or not depends on the
2854: MIME type.) <a href="references.html#refsRFC4281">[RFC4281]</a></p><p>Types are usually somewhat incomplete descriptions; for example
2855: "<code title="">video/mpeg</code>" doesn't say anything except what
2856: the container type is, and even a type like "<code title="">video/mp4; codecs="avc1.42E01E,
2857: mp4a.40.2"</code>" doesn't include information like the actual
2858: bitrate (only the maximum bitrate). Thus, given a type, a user agent
2859: can often only know whether it <em>might</em> be able to play
2860: media of that type (with varying levels of confidence), or whether
2861: 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
2862: one that describes a resource that the user agent definitely does
2863: not support, for example because it doesn't recognize the container
2864: type, or it doesn't support the listed codecs.</p><p>The <a href="infrastructure.html#mime-type">MIME type</a>
2865: "<code>application/octet-stream</code>" with no parameters is never
2866: <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user agent knows it cannot render</a>. User
2867: agents must treat that type as equivalent to the lack of any
2868: explicit <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a>
2869: when it is used to label a potential <a href="#media-resource">media
2870: resource</a>.</p><p class="note">
2871: "<code>application/octet-stream</code>"
2872: is special-cased here; if any parameter appears with it, it
2873: should
2874:
2875: be treated just like any other <a href="infrastructure.html#mime-type">MIME type</a>.
2876:
2877: This is a deviation from the rule that unknown <a href="infrastructure.html#mime-type">MIME type</a> parameters
2878: should be ignored.
2879:
2880:
2881: </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>
2882:
2883: <dd>
2884:
2885: <p>Returns the empty string (a negative response), "maybe", or
2886: "probably" based on how confident the user agent is that it can
2887: play media resources of the given type.</p>
2888:
2889: </dd>
2890:
2891: </dl><div class="impl">
2892:
2893: <p>The <dfn id="dom-navigator-canplaytype" title="dom-navigator-canPlayType"><code>canPlayType(<var title="">type</var>)</code></dfn> method must return the empty
2894: string if <var title="">type</var> is <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user
2895: agent knows it cannot render</a> or is the type
2896: "<code>application/octet-stream</code>"; it must return "<code title="">probably</code>" if the user agent is confident that the
2897: type represents a <a href="#media-resource">media resource</a> that it can render if
2898: used in with this <code><a href="#the-audio-element">audio</a></code> or <code><a href="#the-video-element">video</a></code> element;
2899: and it must return "<code title="">maybe</code>" otherwise.
2900: Implementors are encouraged to return "<code title="">maybe</code>"
2901: unless the type can be confidently established as being supported or
2902: 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
2903: present.</p>
2904:
2905: </div><div class="example">
2906:
2907: <p>This script tests to see if the user agent supports a
2908: (fictional) new format to dynamically decide whether to use a
2909: <code><a href="#the-video-element">video</a></code> element or a plugin:</p>
2910:
2911: <pre><section id="video">
2912: <p><a href="playing-cats.nfv">Download video</a></p>
2913: </section>
2914: <script>
2915: var videoSection = document.getElementById('video');
2916: var videoElement = document.createElement('video');
2917: var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
2918: if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) {
2919: // not confident of browser support
2920: // but we have a plugin
2921: // so use plugin instead
2922: videoElement = document.createElement("embed");
2923: } else if (support == "") {
2924: // no support from browser and no plugin
2925: // do nothing
2926: videoElement = null;
2927: }
2928: if (videoElement) {
2929: while (videoSection.hasChildNodes())
2930: videoSection.removeChild(videoSection.firstChild);
2931: videoElement.setAttribute("src", "playing-cats.nfv");
2932: videoSection.appendChild(videoElement);
2933: }
2934: </script></pre>
2935:
2936: </div><p class="note">The <code title="attr-source-type"><a href="#attr-source-type">type</a></code>
2937: attribute of the <code><a href="#the-source-element">source</a></code> element allows the user agent
2938: to avoid downloading resources that use formats it cannot
2939: 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>
2940:
2941: <dd>
2942:
2943: <p>Returns the current state of network activity for the element,
2944: from the codes in the list below.</p>
2945:
2946: </dd>
2947:
2948: </dl><div class="impl">
2949:
2950: <p>As <a href="#media-element" title="media element">media elements</a> interact
2951: with the network, their current network activity is represented by
2952: the <dfn id="dom-media-networkstate" title="dom-media-networkState"><code>networkState</code></dfn>
2953: attribute. On getting, it must return the current network state of
2954: the element, which must be one of the following values:</p>
2955:
2956: </div><dl><dt><dfn id="dom-media-network_empty" title="dom-media-NETWORK_EMPTY"><code>NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
2957:
2958: <dd>The element has not yet been initialized. All attributes are in
2959: their initial states.</dd>
2960:
2961: <dt><dfn id="dom-media-network_idle" title="dom-media-NETWORK_IDLE"><code>NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
2962:
2963: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2964: algorithm</a> is active and</span> has selected a <a href="#media-resource" title="media resource">resource</a>, but it is not actually
2965: using the network at this time.</dd>
2966:
2967: <dt><dfn id="dom-media-network_loading" title="dom-media-NETWORK_LOADING"><code>NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
2968:
2969: <dd>The user agent is actively trying to download data.</dd>
2970:
2971: <dt><dfn id="dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE"><code>NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
2972:
2973: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2974: algorithm</a> is active, but it</span> has not yet found a <a href="#media-resource" title="media resource">resource</a> to use.</dd>
2975:
2976: </dl><div class="impl">
2977:
2978: <p>The <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2979: algorithm</a> defined below describes exactly when the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute changes
2980: value and what events fire to indicate changes in this state.</p>
2981:
2982: </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>
2983:
2984: <dd>
2985:
2986: <p>Causes the element to reset and start selecting and loading a
2987: new <a href="#media-resource">media resource</a> from scratch.</p>
2988:
2989: </dd>
2990:
2991: </dl><div class="impl">
2992:
2993: <p>All <a href="#media-element" title="media element">media elements</a> have an
2994: <dfn id="autoplaying-flag">autoplaying flag</dfn>, which must begin in the true state, and
2995: a <dfn id="delaying-the-load-event-flag">delaying-the-load-event flag</dfn>, which must begin in the
2996: false state. While the <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> is
2997: true, the element must <a href="the-end.html#delay-the-load-event">delay the load event</a> of its
2998: document.</p>
2999:
3000: <p>When the <dfn id="dom-media-load" title="dom-media-load"><code>load()</code></dfn>
3001: method on a <a href="#media-element">media element</a> is invoked, the user agent
3002: must run the <a href="#media-element-load-algorithm">media element load algorithm</a>.</p>
3003:
3004: <p>The <dfn id="media-element-load-algorithm">media element load algorithm</dfn> consists of the
3005: following steps.</p>
3006:
3007: <ol><li><p>Abort any already-running instance of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3008: algorithm</a> for this element.</p></li>
3009:
3010: <li>
3011:
3012: <p>If there are any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> from
3013: the <a href="#media-element">media element</a>'s <a href="#media-element-event-task-source">media element event task
3014: source</a> in one of the <a href="webappapis.html#task-queue" title="task queue">task
3015: queues</a>, then remove those tasks.</p>
3016:
3017: <p class="note">Basically, pending events and callbacks for the
3018: media element are discarded when the media element starts loading
3019: a new resource.</p>
3020:
3021: </li>
3022:
3023: <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
3024: 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
3025: element</a>.</p></li>
3026:
3027: <li>
3028:
3029: <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
3030: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, then
3031: run these substeps:</p>
3032:
3033: <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
3034: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the <a href="#media-element">media
3035: element</a>.</p></li>
3036:
3037: <li><p>If a fetching process is in progress for the <a href="#media-element">media
3038: element</a>, the user agent should stop it.</p></li>
3039:
3040: <li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3041: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>.</p></li>
3042:
3043: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3044: text tracks</a>.</p></li>
3045:
3046: <li><p>If <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is
3047: not set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then set it
3048: to that state.
3049:
3050: </p></li>
3051:
3052: <li><p>If the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
3053: attribute is false, then set it to true.</p></li>
3054:
3055: <li><p>If <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true,
3056: set it to false.</p></li>
3057:
3058: <li>
3059:
3060: <p>Set the <a href="#current-playback-position">current playback position</a> to 0.</p>
3061:
3062: <p>If this changed the <a href="#current-playback-position">current playback position</a>,
3063: then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3064: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
3065: <a href="#media-element">media element</a>.</p>
3066:
3067: </li>
3068:
3069: <li><p>Set the <a href="#initial-playback-position">initial playback position</a> to
3070: 0.</p></li>
3071:
3072: <li><p>Set the <a href="#timeline-offset">timeline offset</a> to Not-a-Number
3073: (NaN).</p></li>
3074:
3075: <li>
3076:
3077: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3078: attribute to Not-a-Number (NaN).</p>
3079:
3080: <p class="note">The user agent <a href="#durationChange">will
3081: not</a> fire a <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event
3082: for this particular change of the duration.</p>
3083:
3084: </li>
3085:
3086: </ol></li>
3087:
3088: <li><p>Set the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute to the
3089: value of the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
3090: attribute.</p></li>
3091:
3092: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code> attribute
3093: to null and the <a href="#autoplaying-flag">autoplaying flag</a> to true.</p></li>
3094:
3095: <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
3096: algorithm</a>.</p></li>
3097:
3098: <li>
3099:
3100: <p class="note">Playback of any previously playing <a href="#media-resource">media
3101: resource</a> for this element stops.</p>
3102:
3103: </li>
3104:
3105: </ol><p>The <dfn id="concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3106: algorithm</dfn> for a <a href="#media-element">media element</a> is as follows. This
3107: algorithm is always invoked synchronously, but one of the first
3108: steps in the algorithm is to return and continue running the
3109: remaining steps asynchronously, meaning that it runs in the
3110: background with scripts and other <a href="webappapis.html#concept-task" title="concept-task">tasks</a> running in parallel. In addition,
3111: this algorithm interacts closely with the <a href="webappapis.html#event-loop">event loop</a>
3112: mechanism; in particular, it has <a href="webappapis.html#synchronous-section" title="synchronous
3113: section">synchronous sections</a> (which are triggered as part of
3114: the <a href="webappapis.html#event-loop">event loop</a> algorithm). Steps in such sections are
3115: marked with ⌛.</p>
3116:
3117: <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>
3118:
3119: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
3120: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that invoked this
3121: algorithm to continue. The <a href="webappapis.html#synchronous-section">synchronous section</a>
3122: consists of all the remaining steps of this algorithm until the
3123: algorithm says the <a href="webappapis.html#synchronous-section">synchronous section</a> has
3124: ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous
3125: sections</a> are marked with ⌛.)</p></li>
3126:
3127: <li>
3128:
3129: <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>
3130:
3131: <p>⌛ Otherwise, if the <a href="#media-element">media element</a> does not
3132: have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute but has a
3133: <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>
3134: element child in <a href="infrastructure.html#tree-order">tree order</a>.</p>
3135:
3136: <p>⌛ Otherwise the <a href="#media-element">media element</a> has neither a
3137: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute nor a
3138: <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
3139: these steps; the <a href="webappapis.html#synchronous-section">synchronous section</a> ends.</p>
3140:
3141: </li>
3142:
3143: <li><p>⌛ Set the <a href="#media-element">media element</a>'s
3144: <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
3145: its <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3146: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3147:
3148: <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
3149: event</a> named <code title="event-media-loadstart"><a href="#event-media-loadstart">loadstart</a></code> at the <a href="#media-element">media
3150: element</a>.</p></li>
3151:
3152: <li>
3153:
3154: <p>If <var title="">mode</var> is <i title="">attribute</i>, then
3155: run these substeps:</p>
3156:
3157: <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
3158: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3159: down to the <i title="">failed</i> step below.</p></li>
3160:
3161: <li><p>⌛ Let <var title="">absolute URL</var> be the
3162: <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>
3163: specified by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
3164: attribute's value relative to the <a href="#media-element">media element</a> when
3165: the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was last
3166: changed.</p>
3167: </li><li><p>⌛ If <var title="">absolute URL</var> was obtained
3168: 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>
3169:
3170: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3171: remaining steps asynchronously.</p></li>
3172:
3173: <li><p>If <var title="">absolute URL</var> was obtained
3174: successfully, run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3175: algorithm</a> with <var title="">absolute URL</var>. If that
3176: algorithm returns without aborting <em>this</em> one, then the
3177: load failed.</p></li>
3178:
3179: <li>
3180:
3181: <p><i>Failed</i>: Reaching this step indicates that the media
3182: resource failed to load or that the given <a href="urls.html#url">URL</a> could
3183: not be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a>. In one
3184: atomic operation, run the following steps:</p>
3185:
3186: <ol><li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3187: 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
3188: <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>
3189:
3190: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3191: text tracks</a>.</p></li>
3192:
3193: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3194: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3195: value.</p></li>
3196:
3197: </ol></li>
3198:
3199: <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
3200: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3201: at the <a href="#media-element">media element</a>.</p></li>
3202:
3203: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a>
3204: to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying
3205: the load event</a>.</p></li>
3206:
3207: <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
3208: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute is changed, the
3209: element won't attempt to load another resource.</p></li>
3210:
3211:
3212: </ol><p>Otherwise, the <code><a href="#the-source-element">source</a></code> elements will be used; run
3213: these substeps:</p>
3214:
3215: <ol><li>
3216:
3217: <p>⌛ Let <var title="">pointer</var> be a position
3218: defined by two adjacent nodes in the <a href="#media-element">media
3219: element</a>'s child list, treating the start of the list
3220: (before the first child in the list, if any) and end of the list
3221: (after the last child in the list, if any) as nodes in their own
3222: right. One node is the node before <var title="">pointer</var>,
3223: 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
3224: any, or the end of the list, if it is the last node.</p>
3225:
3226: <p>As nodes are inserted and removed into the <a href="#media-element">media
3227: element</a>, <var title="">pointer</var> must be updated as
3228: follows:</p>
3229:
3230: <dl><dt>If a new node is inserted between the two nodes that
3231: define <var title="">pointer</var></dt>
3232:
3233: <dd>Let <var title="">pointer</var> be the point between the
3234: node before <var title="">pointer</var> and the new node. In
3235: other words, insertions at <var title="">pointer</var> go after
3236: <var title="">pointer</var>.</dd>
3237:
3238: <dt>If the node before <var title="">pointer</var> is removed</dt>
3239:
3240: <dd>Let <var title="">pointer</var> be the point between the
3241: node after <var title="">pointer</var> and the node before the
3242: node after <var title="">pointer</var>. In other words, <var title="">pointer</var> doesn't move relative to the remaining
3243: nodes.</dd>
3244:
3245: <dt>If the node after <var title="">pointer</var> is removed</dt>
3246:
3247: <dd>Let <var title="">pointer</var> be the point between the
3248: node before <var title="">pointer</var> and the node after the
3249: node before <var title="">pointer</var>. Just as with the
3250: previous case, <var title="">pointer</var> doesn't move
3251: relative to the remaining nodes.</dd>
3252:
3253: </dl><p>Other changes don't affect <var title="">pointer</var>.</p>
3254:
3255: </li>
3256:
3257: <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
3258: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3259: down to the <i title="">failed</i> step below.</p></li>
3260:
3261: <li><p>⌛ Let <var title="">absolute URL</var> be the
3262: <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>
3263: 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
3264: the <var title="">candidate</var> when the <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute was last
3265: changed.</p>
3266: </li><li><p>⌛ If <var title="">absolute URL</var> was not
3267: obtained successfully, then end the <a href="webappapis.html#synchronous-section">synchronous
3268: section</a>, and jump down to the <i title="">failed</i> step
3269: below.</p></li>
3270:
3271: <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
3272: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3273: described by the <code title="">codecs</code> parameter, for
3274: types that define that parameter), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3275: the user agent knows it cannot render</a>, then end the
3276: <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
3277:
3278: <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
3279: not <a href="common-microsyntaxes.html#matches-the-environment" title="matches the environment">match the
3280: environment</a>, then end the <a href="webappapis.html#synchronous-section">synchronous
3281: section</a>, and jump down to the <i title="">failed</i> step
3282: below.</p></li>
3283:
3284: <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>
3285:
3286: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3287: remaining steps asynchronously.</p></li>
3288:
3289: <li><p>Run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource
3290: fetch algorithm</a> with <var title="">absolute URL</var>. If
3291: that algorithm returns without aborting <em>this</em> one, then
3292: the load failed.</p></li>
3293:
3294: <li><p><i title="">Failed</i>: <a href="webappapis.html#queue-a-task">Queue a task</a> to
3295: <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
3296: obtain <var title="">candidate</var>'s corresponding <a href="#media-resource">media
3297: resource</a> in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3298: algorithm</a>.</p></li>
3299:
3300: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3301: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3302: steps of this algorithm until the algorithm says the
3303: <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
3304: marked with ⌛.)</p></li>
3305:
3306: <li><p>⌛ <a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's
3307: media-resource-specific text tracks</a>.</p></li>
3308:
3309: <li><p>⌛ <i title="">Find next candidate</i>: Let <var title="">candidate</var> be null.</p></li>
3310:
3311: <li><p>⌛ <i title="">Search loop</i>: If the node after
3312: <var title="">pointer</var> is the end of the list, then jump to
3313: the <i title="">waiting</i> step below.</p></li>
3314:
3315: <li><p>⌛ If the node after <var title="">pointer</var> is
3316: a <code><a href="#the-source-element">source</a></code> element, let <var title="">candidate</var>
3317: be that element.</p></li>
3318:
3319: <li><p>⌛ Advance <var title="">pointer</var> so that the
3320: node before <var title="">pointer</var> is now the node that was
3321: after <var title="">pointer</var>, and the node after <var title="">pointer</var> is the node after the node that used to be
3322: after <var title="">pointer</var>, if any.</p></li>
3323:
3324: <li><p>⌛ If <var title="">candidate</var> is null, jump
3325: back to the <i title="">search loop</i> step. Otherwise, jump
3326: back to the <i title="">process candidate</i> step.</p></li>
3327:
3328: <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
3329: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3330: value.</p></li>
3331:
3332: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3333: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3334: event">delaying the load event</a>.</p></li>
3335:
3336: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3337: remaining steps asynchronously.</p></li>
3338:
3339: <li><p>Wait until the node after <var title="">pointer</var> is a
3340: node other than the end of the list. (This step might wait
3341: forever.)</p></li>
3342:
3343: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3344: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3345: steps of this algorithm until the algorithm says the
3346: <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
3347: marked with ⌛.)</p></li>
3348:
3349: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3350: flag</a> back to true (this <a href="the-end.html#delay-the-load-event" title="delay the load
3351: event">delays the load event</a> again, in case it hasn't been
3352: fired yet).</p>
3353:
3354: </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>
3355:
3356: <li><p>⌛ Jump back to the <i title="">find next
3357: candidate</i> step above.</p></li>
3358:
3359: </ol></li>
3360:
3361: </ol><p>The <dfn id="concept-media-load-resource" title="concept-media-load-resource">resource fetch
3362: algorithm</dfn> for a <a href="#media-element">media element</a> and a given
3363: <a href="urls.html#absolute-url">absolute URL</a> is as follows:</p>
3364:
3365: <ol><li><p>Let the <var title="">current media resource</var> be the
3366: resource given by the <a href="urls.html#absolute-url">absolute URL</a> passed to this
3367: algorithm. This is now the element's <a href="#media-resource">media
3368: resource</a>.</p></li>
3369:
3370: <li>
3371:
3372: <p>Begin to <a href="fetching-resources.html#fetch">fetch</a> the <var title="">current media
3373: resource</var>, from the <a href="#media-element">media element</a>'s
3374: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, with the <i>force
3375: same-origin flag</i> set.</p>
3376: <p>Every 350ms (±200ms) or for every byte received, whichever
3377: is <em>least</em> frequent, <a href="webappapis.html#queue-a-task">queue a task</a> to
3378: <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the element.</p>
3379:
3380: <p>The <dfn id="stall-timeout">stall timeout</dfn> is a user-agent defined length of
3381: time, which should be about three seconds. When a <a href="#media-element">media
3382: element</a> that is actively attempting to obtain <a href="#media-data">media
3383: data</a> has failed to receive any data for a duration equal to
3384: the <a href="#stall-timeout">stall timeout</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a
3385: 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>
3386:
3387: <p>User agents may allow users to selectively block or slow
3388: <a href="#media-data">media data</a> downloads. When a <a href="#media-element">media
3389: element</a>'s download has been blocked altogether, the user
3390: agent must act as if it was stalled (as opposed to acting as if
3391: the connection was closed). The rate of the download may also be
3392: throttled automatically by the user agent, e.g. to balance the
3393: download with other connections sharing the same bandwidth.</p>
3394:
3395: <p>User agents may decide to not download more content at any
3396: time, e.g. after buffering five minutes of a one hour media
3397: resource, while waiting for the user to decide whether to play the
3398: resource or not, or while waiting for user input in an interactive
3399: resource. When a <a href="#media-element">media element</a>'s download has been
3400: suspended, the user agent must set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> and <a href="webappapis.html#queue-a-task">queue
3401: a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-suspend"><a href="#event-media-suspend">suspend</a></code> at the element. If and
3402: when downloading of the resource resumes, the user agent must set
3403: the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3404: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p>
3405:
3406: <p class="note">The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute provides a
3407: hint regarding how much buffering the author thinks is advisable,
3408: even in the absence of the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute.</p>
3409:
3410: <p>When a user agent decides to completely stall a download,
3411: e.g. if it is waiting until the user starts playback before
3412: downloading any further content, the element's
3413: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> must be set to
3414: false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the
3415: load event</a>.</p>
3416:
3417: <p>The user agent may use whatever means necessary to fetch the
3418: resource (within the constraints put forward by this and other
3419: specifications); for example, reconnecting to the server in the
3420: face of network errors, using HTTP range retrieval requests, or
3421: switching to a streaming protocol. The user agent must consider a
3422: resource erroneous only if it has given up trying to fetch it.</p>
3423:
3424: <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
3425: being fetched must, when appropriate, include the relevant
3426: substeps from the following list:</p>
3427:
3428: <dl class="switch"><dt>If the <a href="#media-data">media data</a> cannot be fetched at all, due
3429: to network errors, causing the user agent to give up trying to
3430: fetch the resource</dt>
3431:
3432: <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
3433: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3434: described by the <code title="">codecs</code> parameter, if the
3435: parameter is defined for that type), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3436: the user agent knows it cannot render</a> (even if the actual
3437: <a href="#media-data">media data</a> is in a supported format)</dt>
3438:
3439: <dt>If the <a href="#media-data">media data</a> can be fetched but is found by
3440: inspection to be in an unsupported format, or can otherwise not
3441: be rendered at all</dt>
3442:
3443: <dd>
3444:
3445: <p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in
3446: other protocols), and other fatal network errors that occur
3447: before the user agent has established whether the <var title="">current media resource</var> is usable, as well as
3448: the file using an unsupported container format, or using
3449: unsupported codecs for all the data, must cause the user agent
3450: to execute the following steps:</p>
3451:
3452: <ol><li><p>The user agent should cancel the fetching
3453: process.</p></li>
3454:
3455: <li><p>Abort this subalgorithm, returning to the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3456: algorithm</a>.</p>
3457:
3458: </li></ol></dd>
3459:
3460:
3461:
3462:
3463:
3464: <dt id="getting-media-metadata">Once enough of the <a href="#media-data">media
3465: data</a> has been fetched to determine the duration of the
3466: <a href="#media-resource">media resource</a>, its dimensions, and other
3467: metadata,
3468: and once <a href="#the-text-tracks-are-ready">the text tracks are ready</a>
3469: </dt>
3470:
3471: <dd>
3472:
3473: <p>This indicates that the resource is usable. The user agent
3474: must follow these substeps:</p>
3475:
3476: <ol><li>
3477:
3478: <p><a href="#defineTimeline">Establish the media timeline</a> for the purposes
3479: of the <a href="#current-playback-position">current playback position</a>, the
3480: <a href="#earliest-possible-position">earliest possible position</a>, and the <a href="#initial-playback-position">initial
3481: playback position</a>, based on the <a href="#media-data">media
3482: data</a>.</p>
3483:
3484: </li>
3485:
3486: <li>
3487:
3488: <p>Update the <a href="#timeline-offset">timeline offset</a> to the date and
3489: time that corresponds to the zero time in the <a href="#media-timeline">media
3490: timeline</a> established in the previous step, if any. If
3491: no explicit time and date is given by the <a href="#media-resource">media
3492: resource</a>, the <a href="#timeline-offset">timeline offset</a> must be set
3493: to Not-a-Number (NaN).</p>
3494:
3495: </li>
3496:
3497: <li><p>Set the <a href="#current-playback-position">current playback position</a> to the
3498: <a href="#earliest-possible-position">earliest possible position</a>.</p></li>
3499:
3500: <li>
3501:
3502: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3503: attribute with the time of the last frame of the resource, if
3504: known, on the <a href="#media-timeline">media timeline</a> established above.
3505: If it is not known (e.g. a stream that is in principle
3506: infinite), update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute to the
3507: value positive Infinity.</p>
3508:
3509: <p class="note">The user agent <a href="#durationChange">will</a> <a href="webappapis.html#queue-a-task">queue a task</a> to
3510: <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
3511: element at this point.</p>
3512:
3513: </li>
3514:
3515: <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>
3516: attributes.</p></li>
3517:
3518: <li>
3519:
3520: <p>Set the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to
3521: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>.</p>
3522:
3523: <p class="note">A <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> DOM
3524: event <a href="#fire-loadedmetadata">will be fired</a> as part
3525: of setting the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to a
3526: new value.</p>
3527:
3528:
3529:
3530: </li>
3531:
3532: <li><p>Let <var title="">jumped</var> be false.</p></li>
3533:
3534: <li>
3535:
3536: <p>If either the <a href="#media-resource">media resource</a> or the address of
3537: the <var title="">current media resource</var> indicate a
3538: particular start time, then set the <a href="#initial-playback-position">initial playback
3539: position</a> to that time, <a href="#dom-media-seek" title="dom-media-seek">seek</a> to that time, and let <var title="">jumped</var> be true. Ignore any resulting exceptions
3540: (if the position is out of range, it is effectively
3541: ignored).</p>
3542:
3543: <p class="example">For example, with media formats that
3544: support the <cite>Media Fragments URI</cite> fragment
3545: identifier syntax, the fragment identifier can be used to
3546: indicate a start position. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
3547:
3548: </li>
3549:
3550: <li><p>If either the <a href="#media-resource">media resource</a> or the address
3551: of the <var title="">current media resource</var> indicate a
3552: particular set of audio or video tracks to enable, then the
3553: 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
3554: the first selected video track must be selected in the
3555: element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code>
3556: object.</p></li>
3557:
3558: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
3559: media controller</a>, then: if <var title="">jumped</var> is
3560: true and the <a href="#initial-playback-position">initial playback position</a>, relative
3561: to the <a href="#current-media-controller">current media controller</a>'s timeline, is
3562: greater than the <a href="#current-media-controller">current media controller</a>'s
3563: <a href="#media-controller-position">media controller position</a>, then <a href="#seek-the-media-controller">seek the
3564: media controller</a> to the <a href="#media-element">media element</a>'s
3565: <a href="#initial-playback-position">initial playback position</a>, relative to the
3566: <a href="#current-media-controller">current media controller</a>'s timeline; otherwise,
3567: <a href="#dom-media-seek" title="dom-media-seek">seek</a> the <a href="#media-element">media
3568: element</a> to the <a href="#media-controller-position">media controller position</a>,
3569: relative to the <a href="#media-element">media element</a>'s timeline,
3570: discarding any resulting exceptions.</p></li>
3571: <li>
3572:
3573: <p>Once the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
3574: reaches <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
3575: <a href="#fire-loadeddata">after the <code title="event-media-loadeddata">loadeddata</code> event has been
3576: fired</a>, set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3577: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3578: event">delaying the load event</a>.</p>
3579:
3580: <p class="note">A user agent that is attempting to reduce
3581: network usage while still fetching the metadata for each
3582: <a href="#media-resource">media resource</a> would also stop buffering at this
3583: point, causing the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute
3584: to switch to the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> value.</p>
3585:
3586: </li>
3587:
3588: </ol><p class="note">The user agent is <em>required</em> to
3589: determine the duration of the <a href="#media-resource">media resource</a> and
3590: go through this step before playing.</p>
3591: </dd>
3592:
3593:
3594: <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
3595: has been decoded)</dt>
3596:
3597: <dd>
3598:
3599: <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>
3600: named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the
3601: <a href="#media-element">media element</a>.</p>
3602:
3603: </dd>
3604:
3605:
3606: <dt>If the connection is interrupted, causing the user agent to
3607: give up trying to fetch the resource</dt>
3608:
3609: <dd>
3610:
3611: <p>Fatal network errors that occur after the user agent has
3612: established whether the <var title="">current media
3613: resource</var> is usable must cause the user agent to execute
3614: the following steps:</p>
3615:
3616: <ol><li><p>The user agent should cancel the fetching
3617: process.</p></li>
3618:
3619: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3620: 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
3621: <code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code>.</p></li>
3622:
3623: <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
3624: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3625: at the <a href="#media-element">media element</a>.</p></li>
3626:
3627: <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
3628: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3629: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3630: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3631: value and <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3632: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3633: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3634: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3635: value.</p></li>
3636:
3637: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3638: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3639: event">delaying the load event</a>.</p></li>
3640:
3641: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3642: algorithm</a>.</p></li>
3643:
3644: </ol></dd>
3645:
3646:
3647: <dt id="fatal-decode-error">If the <a href="#media-data">media data</a> is
3648: corrupted</dt>
3649:
3650: <dd>
3651:
3652: <p>Fatal errors in decoding the <a href="#media-data">media data</a> that
3653: occur after the user agent has established whether the <var title="">current media resource</var> is usable must cause the
3654: user agent to execute the following steps:</p>
3655:
3656: <ol><li><p>The user agent should cancel the fetching
3657: process.</p></li>
3658:
3659: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3660: 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
3661: <code title="dom-MediaError-MEDIA_ERR_DECODE"><a href="#dom-mediaerror-media_err_decode">MEDIA_ERR_DECODE</a></code>.</p></li>
3662:
3663: <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
3664: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3665: at the <a href="#media-element">media element</a>.</p></li>
3666:
3667: <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
3668: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3669: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3670: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3671: value and <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3672: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3673: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3674: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3675: value.</p></li>
3676:
3677: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3678: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3679: event">delaying the load event</a>.</p></li>
3680:
3681: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3682: algorithm</a>.</p></li>
3683:
3684: </ol></dd>
3685:
3686:
3687: <dt>If the <a href="#media-data">media data</a> fetching process is aborted by
3688: the user</dt>
3689:
3690: <dd>
3691:
3692: <p>The fetching process is aborted by the user, e.g. because the
3693: user navigated the browsing context to another page, the user
3694: agent must execute the following steps. These steps are not
3695: followed if the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code>
3696: method itself is invoked while these steps are running, as the
3697: steps above handle that particular kind of abort.</p>
3698:
3699: <ol><li><p>The user agent should cancel the fetching
3700: process.</p></li>
3701:
3702: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3703: 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
3704: <code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.</p></li>
3705:
3706: <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
3707: event</a> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code>
3708: at the <a href="#media-element">media element</a>.</p></li>
3709:
3710: <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
3711: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3712: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3713: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3714: value and <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3715: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3716: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3717: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3718: value.</p></li>
3719:
3720: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3721: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3722: event">delaying the load event</a>.</p></li>
3723:
3724: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3725: algorithm</a>.</p></li>
3726:
3727: </ol></dd>
3728:
3729:
3730: <dt id="non-fatal-media-error">If the <a href="#media-data">media data</a> can
3731: be fetched but has non-fatal errors or uses, in part, codecs that
3732: are unsupported, preventing the user agent from rendering the
3733: content completely correctly but not preventing playback
3734: altogether</dt>
3735:
3736: <dd>
3737:
3738: <p>The server returning data that is partially usable but cannot
3739: be optimally rendered must cause the user agent to render just
3740: the bits it can handle, and ignore the rest.</p>
3741:
3742:
3743:
3744: </dd>
3745:
3746:
3747: <dt id="found-a-media-resource-specific-timed-track">If the <a href="#media-resource">media resource</a> is found to declare a <a href="#media-resource-specific-text-track">media-resource-specific text track</a> that the user agent supports</dt>
3748:
3749: <dd>
3750:
3751: <p>If the <a href="#media-resource">media resource</a>'s <a href="origin-0.html#origin">origin</a> is
3752: the <a href="origin-0.html#same-origin">same origin</a> as the <a href="#media-element">media element</a>'s
3753: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, <a href="webappapis.html#queue-a-task">queue a
3754: task</a> to run the <a href="#steps-to-expose-a-media-resource-specific-text-track">steps to expose a
3755: media-resource-specific text track</a> with the relevant
3756: data.</p> <!-- CORS -->
3757:
3758: <p class="note">Cross-origin files do not expose their subtitles
3759: in the DOM, for security reasons. However, user agents may still
3760: provide the user with access to such data in their user
3761: interface.</p>
3762:
3763: </dd>
3764:
3765: </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>
3766: (i.e. once the download has completed), if the fetching process
3767: completes without errors, including decoding the media data, and
3768: if all of the data is available to the user agent without network
3769: access, then, the user agent must move on to the next step. This
3770: might never happen, e.g. when streaming an infinite resource such
3771: as Web radio, or if the resource is longer than the user agent's
3772: ability to cache data.</p>
3773:
3774: <p>While the user agent might still need network access to obtain
3775: parts of the <a href="#media-resource">media resource</a>, the user agent must
3776: remain on this step.</p>
3777:
3778: <p class="example">For example, if the user agent has discarded
3779: the first half of a video, the user agent will remain at this step
3780: even once the <a href="#ended-playback" title="ended playback">playback has
3781: ended</a>, because there is always the chance the user will
3782: 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
3783: will end up dispatching a <code title="event-media-stalled"><a href="#event-media-stalled">stalled</a></code> event, as described
3784: earlier.</p>
3785:
3786: </li>
3787:
3788: <li><p>If the user agent ever reaches this step (which can only
3789: happen if the entire resource gets loaded and kept available):
3790: abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3791: algorithm</a>.</p></li>
3792:
3793: </ol></div><hr><p>The <dfn id="attr-media-preload" title="attr-media-preload"><code>preload</code></dfn>
3794: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following table
3795: lists the keywords and states for the attribute — the keywords
3796: in the left column map to the states in the cell in the second
3797: column on the same row as the keyword.</p><table><thead><tr><th> Keyword
3798: </th><th> State
3799: </th><th> Brief description
3800: </th></tr></thead><tbody><tr><td><dfn id="attr-media-preload-none" title="attr-media-preload-none"><code>none</code></dfn>
3801: </td><td><dfn id="attr-media-preload-none-state" title="attr-media-preload-none-state">None</dfn>
3802: </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.
3803: </td></tr><tr><td><dfn id="attr-media-preload-metadata" title="attr-media-preload-metadata"><code>metadata</code></dfn>
3804: </td><td><dfn id="attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</dfn>
3805: </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.
3806: </td></tr><tr><td><dfn id="attr-media-preload-auto" title="attr-media-preload-auto"><code>auto</code></dfn>
3807: </td><td><dfn id="attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</dfn>
3808: </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.
3809: </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
3810: attribute's <i>missing value default</i> is user-agent defined,
3811: though the <a href="#attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</a> state is
3812: suggested as a compromise between reducing server load and providing
3813: an optimal user experience.</p><div class="impl">
3814:
3815: <p>The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute is
3816: intended to provide a hint to the user agent about what the author
3817: thinks will lead to the best user experience. The attribute may be
3818: ignored altogether, for example based on explicit user preferences
3819: or based on the available connectivity.</p>
3820:
3821: <p>The <dfn id="dom-media-preload" title="dom-media-preload"><code>preload</code></dfn> IDL
3822: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
3823: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
3824:
3825: </div><p class="note">The <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute can override
3826: the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute (since
3827: if the media plays, it naturally has to buffer first, regardless of
3828: the hint given by the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute). Including
3829: 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>
3830:
3831: <dd>
3832:
3833: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
3834: ranges of the <a href="#media-resource">media resource</a> that the user agent has
3835: buffered.</p>
3836:
3837: </dd>
3838:
3839: </dl><div class="impl">
3840:
3841: <p>The <dfn id="dom-media-buffered" title="dom-media-buffered"><code>buffered</code></dfn>
3842: attribute must return a new static <a href="#normalized-timeranges-object">normalized
3843: <code>TimeRanges</code> object</a> that represents the ranges of
3844: the <a href="#media-resource">media resource</a>, if any, that the user agent has
3845: buffered, at the time the attribute is evaluated. Users agents must
3846: accurately determine the ranges available, even for media streams
3847: where this can only be determined by tedious inspection.</p>
3848:
3849: <p class="note">Typically this will be a single range anchored at
3850: the zero point, but if, e.g. the user agent uses HTTP range requests
3851: in response to seeking, then there could be multiple ranges.</p>
3852:
3853: <p>User agents may discard previously buffered data.</p>
3854:
3855: <p class="note">Thus, a time position included within a range of the
3856: objects return by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code> attribute at one time can
3857: end up being not included in the range(s) of objects returned by the
3858: same attribute at later times.</p>
3859:
3860: </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>
3861:
3862: <dd>
3863:
3864: <p>Returns the length of the <a href="#media-resource">media resource</a>, in
3865: seconds, assuming that the start of the <a href="#media-resource">media
3866: resource</a> is at time zero.</p>
3867:
3868: <p>Returns NaN if the duration isn't available.</p><p>
3869:
3870: </p><p>Returns Infinity for unbounded streams.</p>
3871:
3872: </dd>
3873:
3874: <dt><var title="">media</var> . <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
3875:
3876: <dd>
3877:
3878: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds.</p>
3879:
3880: <p>Can be set, to seek to the given time.</p><p>
3881:
3882: </p><p>Will throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception if there
3883: is no selected <a href="#media-resource">media resource</a>
3884: or if there is a <a href="#current-media-controller">current media controller</a>.
3885: Will throw an
3886: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception if the given time is not
3887: within the ranges to which the user agent can seek.</p>
3888:
3889: </dd>
3890:
3891: <dt><var title="">media</var> . <code title="dom-media-initialTime"><a href="#dom-media-initialtime">initialTime</a></code></dt>
3892:
3893: <dd>
3894:
3895: <p>Returns the <a href="#initial-playback-position">initial playback position</a>, that is, time
3896: to which the <a href="#media-resource">media resource</a> was automatically seeked
3897: when it was loaded. Returns zero if the <a href="#initial-playback-position">initial playback
3898: position</a> is still unknown.</p>
3899:
3900: </dd>
3901:
3902: </dl><div class="impl">
3903:
3904: <p>A <a href="#media-resource">media resource</a> has a <dfn id="media-timeline">media timeline</dfn>
3905: that maps times (in seconds) to positions in the <a href="#media-resource">media
3906: resource</a>. The origin of a timeline is its earliest defined
3907: position. The duration of a timeline is its last defined
3908: position.</p>
3909:
3910: <p><dfn id="defineTimeline" title="establish the media
3911: timeline">Establishing the media timeline</dfn>: If the <a href="#media-resource">media
3912: resource</a> somehow specifies an explicit timeline whose origin
3913: is not negative, then the <a href="#media-timeline">media timeline</a> should be that
3914: timeline. (Whether the <a href="#media-resource">media resource</a> can specify a
3915: timeline or not depends on the <a href="#media-resource" title="media resource">media
3916: resource's</a> format.) If the <a href="#media-resource">media resource</a>
3917: specifies an explicit start time <em>and date</em>, then that time
3918: and date should be considered the zero point in the <a href="#media-timeline">media
3919: timeline</a>; the <a href="#timeline-offset">timeline offset</a> will be the time
3920: and date, exposed using the <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
3921: attribute.</p>
3922:
3923: <p>If the <a href="#media-resource">media resource</a> has a discontinuous timeline,
3924: the user agent must extend the timeline used at the start of the
3925: resource across the entire resource, so that the <a href="#media-timeline">media
3926: timeline</a> of the <a href="#media-resource">media resource</a> increases
3927: linearly starting from the <a href="#earliest-possible-position">earliest possible position</a>
3928: (as defined below), even if the underlying <a href="#media-data">media data</a>
3929: has out-of-order or even overlapping time codes.</p>
3930:
3931: <p class="example">For example, if two clips have been concatenated
3932: into one video file, but the video format exposes the original times
3933: for the two clips, the video data might expose a timeline that goes,
3934: say, 00:15..00:29 and then 00:05..00:38. However, the user agent
3935: would not expose those times; it would instead expose the times as
3936: 00:15..00:29 and 00:29..01:02, as a single video.</p>
3937:
3938: <p>In the absence of an explicit timeline, the zero time on the
3939: <a href="#media-timeline">media timeline</a> should correspond to the first frame of
3940: the <a href="#media-resource">media resource</a>. For static audio and video files
3941: this is generally trivial. For streaming resources, if the user
3942: agent will be able to seek to an earlier point than the first frame
3943: originally provided by the server, then the zero time should
3944: correspond to the earliest seekable time of the <a href="#media-resource">media
3945: resource</a>; otherwise, it should correspond to the first frame
3946: received from the server (the point in the <a href="#media-resource">media
3947: resource</a> at which the user agent began receiving the
3948: stream).</p>
3949:
3950: <p class="example">Another example would be a stream that carries a
3951: video with several concatenated fragments, broadcast by a server
3952: that does not allow user agents to request specific times but
3953: instead just streams the video data in a predetermined order. If a
3954: user agent connects to this stream and receives fragments defined as
3955: covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
3956: UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
3957: expose this with a <a href="#media-timeline">media timeline</a> starting at 0s and
3958: extending to 3,600s (one hour). Assuming the streaming server
3959: 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
3960: return 3,600. The <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code> attribute
3961: would return a <code>Date</code> object with a time corresponding to
3962: 2010-03-20 23:15:00 UTC. However, if a different user agent
3963: connected five minutes later, <em>it</em> would (presumably) receive
3964: fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
3965: 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
3966: and would expose this with a <a href="#media-timeline">media timeline</a> starting at
3967: 0s and extending to 3,300s (fifty five minutes). In this case, the
3968: <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
3969: attribute would return a <code>Date</code> object with a time
3970: corresponding to 2010-03-20 23:20:00 UTC.</p>
3971:
3972: <p>In any case, the user agent must ensure that the <a href="#earliest-possible-position">earliest
3973: possible position</a> (as defined below) using the established
3974: <a href="#media-timeline">media timeline</a>, is greater than or equal to zero.</p>
3975:
3976: <p>The <a href="#media-timeline">media timeline</a> also has an associated clock.
3977: Which clock is used is user-agent defined, and may be <a href="#media-resource">media
3978: resource</a>-dependent, but it should approximate the user's wall
3979: clock.</p>
3980:
3981: <p class="note">All the <a href="#media-element" title="media element">media
3982: elements</a> that share <a href="#current-media-controller">current media controller</a> use
3983: the same clock for their <a href="#media-timeline">media timeline</a>.</p>
3984:
3985: <p><a href="#media-element" title="media element">Media elements</a> have a
3986: <dfn id="current-playback-position">current playback position</dfn>, which must initially (i.e. in
3987: the absence of <a href="#media-data">media data</a>) be zero seconds. The
3988: <a href="#current-playback-position">current playback position</a> is a time on the <a href="#media-timeline">media
3989: timeline</a>.</p>
3990:
3991: <p>The <dfn id="dom-media-currenttime" title="dom-media-currentTime"><code>currentTime</code></dfn>
3992: attribute must, on getting, return the <a href="#current-playback-position">current playback
3993: position</a>, expressed in seconds. On setting,
3994: if the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
3995: controller</a>, then it must throw an
3996: <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception; otherwise,
3997: the user agent
3998: must <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the new value
3999: (which might raise an exception).</p>
4000:
4001: <p><a href="#media-element" title="media element">Media elements</a> have an
4002: <dfn id="initial-playback-position">initial playback position</dfn>, which must initially (i.e. in
4003: the absence of <a href="#media-data">media data</a>) be zero seconds. The
4004: <a href="#initial-playback-position">initial playback position</a> is updated when a <a href="#media-resource">media
4005: resource</a> is loaded. The <a href="#initial-playback-position">initial playback
4006: position</a> is a time on the <a href="#media-timeline">media timeline</a>.</p>
4007:
1.50 mike 4008: <p>The <dfn id="dom-media-initialtime" title="dom-media-initialTime"><code>initialTime</code></dfn>
1.47 mike 4009: attribute must, on getting, return the <a href="#initial-playback-position">initial playback
4010: position</a>, expressed in seconds.</p>
4011:
4012: <p>If the <a href="#media-resource">media resource</a> is a streaming resource, then
4013: the user agent might be unable to obtain certain parts of the
4014: resource after it has expired from its buffer. Similarly, some <a href="#media-resource" title="media resource">media resources</a> might have a
4015: <a href="#media-timeline">media timeline</a> that doesn't start at zero. The
4016: <dfn id="earliest-possible-position">earliest possible position</dfn> is the earliest position in
4017: the stream or resource that the user agent can ever obtain
4018: again. It is also a time on the <a href="#media-timeline">media timeline</a>.</p>
4019:
4020: <p class="note">The <a href="#earliest-possible-position">earliest possible position</a> is not
4021: explicitly exposed in the API; it corresponds to the start time of
4022: the first range in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute's
4023: <code><a href="#timeranges">TimeRanges</a></code> object, if any, or the <a href="#current-playback-position">current
4024: playback position</a> otherwise.</p>
4025:
4026: <p>When the <a href="#earliest-possible-position">earliest possible position</a> changes, then:
4027: if the <a href="#current-playback-position">current playback position</a> is before the
4028: <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
4029: 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
4030: element in the past 15 to 250ms and is not still running event
4031: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4032: 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>
4033:
4034: <p class="note">Because of the above requirement and the requirement
4035: in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
4036: algorithm</a> that kicks in <a href="#getting-media-metadata">when the metadata of the clip becomes
4037: known</a>, the <a href="#current-playback-position">current playback position</a> can never be
4038: less than the <a href="#earliest-possible-position">earliest possible position</a>.</p>
4039:
4040: <p>The <dfn id="dom-media-duration" title="dom-media-duration"><code>duration</code></dfn>
4041: attribute must return the time of the end of the <a href="#media-resource">media
4042: resource</a>, in seconds, on the <a href="#media-timeline">media timeline</a>. If
4043: no <a href="#media-data">media data</a> is available, then the attributes must
4044: return the Not-a-Number (NaN) value. If the <a href="#media-resource">media
4045: resource</a> is known to be unbounded (e.g. a streaming radio),
4046: then the attribute must return the positive Infinity value.</p>
4047:
4048: <p>The user agent must determine the duration of the <a href="#media-resource">media
4049: resource</a> before playing any part of the <a href="#media-data">media
4050: data</a> and before setting <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> to a value equal to
4051: or greater than <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, even if doing
4052: so requires fetching multiple parts of the resource.</p>
4053:
4054: <p id="durationChange">When the length of the <a href="#media-resource">media
4055: resource</a> changes to a known value (e.g. from being unknown to
4056: known, or from a previously established length to a new length) the
4057: 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
4058: event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
4059: <a href="#media-element">media element</a>. (The event is not fired when the
4060: duration is reset as part of loading a new media resource.)</p>
4061:
4062: <p class="example">If an "infinite" stream ends for some reason,
4063: then the duration would change from positive Infinity to the time of
4064: 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
4065: be fired. Similarly, if the user agent initially estimated the
4066: <a href="#media-resource">media resource</a>'s duration instead of determining it
4067: precisely, and later revises the estimate based on new information,
4068: then the duration would change and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
4069: be fired.</p>
4070:
4071: <p>Some video files also have an explicit date and time
4072: corresponding to the zero time in the <a href="#media-timeline">media timeline</a>,
4073: known as the <dfn id="timeline-offset">timeline offset</dfn>. Initially, the
4074: <a href="#timeline-offset">timeline offset</a> must be set to Not-a-Number (NaN).</p>
4075:
4076: <p>The <dfn id="dom-media-startoffsettime" title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
4077: attribute must return a new <code>Date</code> object representing
4078: the current <a href="#timeline-offset">timeline offset</a>.</p>
4079:
4080: </div><hr><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn>
4081: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that, if specified,
4082: indicates that the <a href="#media-element">media element</a> is to seek back to the
4083: 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
4084: effect while the element has a <a href="#current-media-controller">current media
4085: controller</a>.</p><div class="impl">
4086:
4087: <p>The <dfn id="dom-media-loop" title="dom-media-loop"><code>loop</code></dfn> IDL
4088: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4089: same name.</p>
4090:
4091: </div><h5 id="the-ready-states"><span class="secno">4.8.10.7 </span>The 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>
4092:
4093: <dd>
4094:
4095: <p>Returns a value that expresses the current state of the element
4096: with respect to rendering the <a href="#current-playback-position">current playback
4097: position</a>, from the codes in the list below.</p>
4098:
4099: </dd>
4100:
4101: </dl><div class="impl">
4102:
4103: <p><a href="#media-element" title="media element">Media elements</a> have a
4104: <i>ready state</i>, which describes to what degree they are ready
4105: to be rendered at the <a href="#current-playback-position">current playback position</a>. The
4106: possible values are as follows; the ready state of a media element
4107: at any particular time is the greatest value describing the state of
4108: the element:</p>
4109:
4110: </div><dl><dt><dfn id="dom-media-have_nothing" title="dom-media-HAVE_NOTHING"><code>HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
4111:
4112: <dd>No information regarding the <a href="#media-resource">media resource</a> is
4113: available. No data for the <a href="#current-playback-position">current playback position</a>
4114: is available. <a href="#media-element" title="media element">Media elements</a>
4115: whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code>
4116: attribute are set to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> are always in
4117: the <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>
4118: state.</dd>
4119:
4120: <dt><dfn id="dom-media-have_metadata" title="dom-media-HAVE_METADATA"><code>HAVE_METADATA</code></dfn> (numeric value 1)</dt>
4121:
4122: <dd>Enough of the resource has been obtained that the duration of
4123: the resource is available. In the case of a <code><a href="#the-video-element">video</a></code>
4124: element, the dimensions of the video are also available. The API
4125: will no longer raise an exception when seeking. No <a href="#media-data">media
4126: data</a> is available for the immediate <a href="#current-playback-position">current playback
4127: position</a>.
4128: The <a href="#text-track" title="text track">text tracks</a>
4129: are <a href="#the-text-tracks-are-ready" title="the text tracks are ready">ready</a>.
4130: </dd>
4131:
4132: <dt><dfn id="dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA"><code>HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
4133:
4134: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4135: is available, but either not enough data is available that the user
4136: agent could successfully advance the <a href="#current-playback-position">current playback
4137: position</a> in the <a href="#direction-of-playback">direction of playback</a> at all
4138: without immediately reverting to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4139: there is no more data to obtain in the <a href="#direction-of-playback">direction of
4140: playback</a>. For example, in video this corresponds to the user
4141: agent having data from the current frame, but not the next frame;
4142: and to when <a href="#ended-playback" title="ended playback">playback has
4143: ended</a>.</dd>
4144:
4145: <dt><dfn id="dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA"><code>HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
4146:
4147: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4148: is available, as well as enough data for the user agent to advance
4149: the <a href="#current-playback-position">current playback position</a> in the <a href="#direction-of-playback">direction
4150: of playback</a> at least a little without immediately reverting
4151: to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
4152: state. For example, in video this corresponds to the user agent
4153: having data for at least the current frame and the next frame. The
4154: user agent cannot be in this state if <a href="#ended-playback" title="ended
4155: playback">playback has ended</a>, as the <a href="#current-playback-position">current playback
4156: position</a> can never advance in this case.</dd>
4157:
4158: <dt><dfn id="dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA"><code>HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
4159:
4160: <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
4161: are met, and, in addition, the user agent estimates that data is
4162: being fetched at a rate where the <a href="#current-playback-position">current playback
4163: position</a>, if it were to advance at the <a href="#effective-playback-rate">effective
4164: playback rate</a>, would not overtake the available data before
4165: playback reaches the end of the <a href="#media-resource">media resource</a>.</dd>
4166:
4167: </dl><div class="impl">
4168:
4169: <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
4170: user agent must follow the steps given below:</p>
4171:
4172: <ol><li>
4173:
4174: <p>Apply the first applicable set of substeps from the following
4175: list:</p>
4176:
4177:
4178: <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
4179: ready state is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code></dt>
4180:
4181: <dd id="fire-loadedmetadata">
4182:
4183: <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>
4184: named <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> at the
4185: element.</p>
4186:
4187: <p class="note">Before this task is run, as part of the event
4188: loop mechanism, the rendering will have been updated to resize
4189: the <code><a href="#the-video-element">video</a></code> element if appropriate.</p>
4190:
4191: </dd>
4192:
4193:
4194:
4195: <dt id="handling-first-frame-available">If the previous ready state
4196: was <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and
4197: 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
4198: greater</dt>
4199:
4200: <dd>
4201:
4202: <p id="fire-loadeddata">If this is the first time this occurs for
4203: 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,
4204: 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
4205: simple event</a> named <code title="event-media-loadeddata"><a href="#event-media-loadeddata">loadeddata</a></code> at the element.</p>
4206:
4207: <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
4208: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>,
4209: then the relevant steps below must then be run also.</p>
4210:
4211: </dd>
4212:
4213:
4214: <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,
4215: 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
4216: less</dt>
4217:
4218: <dd>
4219:
4220: <p id="fire-waiting-when-waiting">If the <a href="#media-element">media
4221: element</a> was <a href="#potentially-playing">potentially playing</a> before its
4222: <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
4223: 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
4224: the element has not <a href="#ended-playback">ended playback</a>, and playback
4225: has not <a href="#stopped-due-to-errors">stopped due to errors</a>, and playback has not
4226: <a href="#paused-for-user-interaction">paused for user interaction</a>, the user agent must
4227: <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>
4228: named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at
4229: 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
4230: simple event</a> named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the element.</p>
4231:
4232: </dd>
4233:
4234:
4235: <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
4236: 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>
4237:
4238: <dd>
4239:
4240: <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
4241: simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>.</p>
4242:
4243: <p>If the element's <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4244: attribute is false, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
4245: 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>
4246:
4247: </dd>
4248:
4249:
4250: <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>
4251:
4252: <dd>
4253:
4254: <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
4255: 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
4256: a simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>, and, if the element's
4257: <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false,
4258: <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>
4259: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4260:
4261: <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
4262: <a href="#media-element">media element</a> has an <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute specified,
4263: and the <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s
4264: <a href="browsers.html#browsing-context">browsing context</a> did not have the <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed
4265: automatic features browsing context flag</a> set when the
4266: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent may also
4267: set the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute to
4268: false, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4269: event</a> named <code title="event-media-play"><a href="#event-media-play">play</a></code>, and
4270: <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>
4271: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4272:
4273: <p class="note">User agents do not need to support autoplay,
4274: and it is suggested that user agents honor user preferences on the
4275: matter. Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
4276: using script to force the video to play, so as to allow the user
4277: to override the behavior if so desired.</p>
4278:
4279: <p>In any case, the user agent must finally <a href="webappapis.html#queue-a-task">queue a
4280: 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>
4281:
4282: </dd>
4283:
4284: </dl></li>
4285:
4286: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4287: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4288: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4289: controller</a>.</p></li>
4290:
4291: </ol></div><p class="note">It is possible for the ready state of a media
4292: element to jump between these states discontinuously. For example,
4293: 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
4294: passing through the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> and
4295: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>
4296: states.</p><div class="impl">
4297:
4298: <p>The <dfn id="dom-media-readystate" title="dom-media-readyState"><code>readyState</code></dfn> IDL
4299: attribute must, on getting, return the value described above that
4300: describes the current ready state of the <a href="#media-element">media
4301: element</a>.</p>
4302:
4303: </div><p>The <dfn id="attr-media-autoplay" title="attr-media-autoplay"><code>autoplay</code></dfn>
4304: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When present, the
4305: user agent <span class="impl">(as described in the algorithm
4306: described herein)</span> will automatically begin playback of the
4307: <a href="#media-resource">media resource</a> as soon as it can do so without
4308: 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
4309: using script to trigger automatic playback, as this allows the user
4310: to override the automatic playback when it is not desired, e.g. when
4311: using a screen reader. Authors are also encouraged to consider not
4312: using the automatic playback behavior at all, and instead to let the
4313: user agent wait for the user to start playback explicitly.</p><div class="impl">
4314:
4315: <p>The <dfn id="dom-media-autoplay" title="dom-media-autoplay"><code>autoplay</code></dfn>
4316: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4317: same name.</p>
4318:
4319: </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>
4320:
4321: <dd>
4322:
4323: <p>Returns true if playback is paused; false otherwise.</p>
4324:
4325: </dd>
4326:
4327: <dt><var title="">media</var> . <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code></dt>
4328:
4329: <dd>
4330:
4331: <p>Returns true if playback has reached the end of the <a href="#media-resource">media resource</a>.</p>
4332:
4333: </dd>
4334:
4335: <dt><var title="">media</var> . <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
4336:
4337: <dd>
4338:
4339: <p>Returns the default rate of playback, for when the user is not
4340: fast-forwarding or reversing through the <a href="#media-resource">media
4341: resource</a>.</p>
4342:
4343: <p>Can be set, to change the default rate of playback.</p>
4344:
4345: <p>The default rate has no direct effect on playback, but if the
4346: user switches to a fast-forward mode, when they return to the
4347: normal playback mode, it is expected that the rate of playback
4348: will be returned to the default rate of playback.</p>
4349:
4350: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4351: the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
4352: attribute is ignored and the <a href="#current-media-controller">current media
4353: controller</a>'s <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code>
4354: is used instead.</p>
4355:
4356: </dd>
4357:
4358: <dt><var title="">media</var> . <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
4359:
4360: <dd>
4361:
4362: <p>Returns the current rate playback, where 1.0 is normal speed.</p>
4363:
4364: <p>Can be set, to change the rate of playback.</p>
4365:
4366: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4367: the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>
4368: attribute is ignored and the <a href="#current-media-controller">current media
4369: controller</a>'s <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> is
4370: used instead.</p>
4371:
4372: </dd>
4373:
4374: <dt><var title="">media</var> . <code title="dom-media-played"><a href="#dom-media-played">played</a></code></dt>
4375:
4376: <dd>
4377:
4378: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4379: ranges of the <a href="#media-resource">media resource</a> that the user agent has
4380: played.</p>
4381:
4382: </dd>
4383:
4384: <dt><var title="">media</var> . <code title="dom-media-play"><a href="#dom-media-play">play</a></code>()</dt>
4385:
4386: <dd>
4387:
4388: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4389: to false, loading the <a href="#media-resource">media resource</a> and beginning
4390: playback if necessary. If the playback had ended, will restart it
4391: from the start.</p>
4392:
4393: </dd>
4394:
4395: <dt><var title="">media</var> . <code title="dom-media-pause"><a href="#dom-media-pause">pause</a></code>()</dt>
4396:
4397: <dd>
4398:
4399: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4400: to true, loading the <a href="#media-resource">media resource</a> if necessary.</p>
4401:
4402: </dd>
4403:
4404: </dl><div class="impl">
4405:
4406: <p>The <dfn id="dom-media-paused" title="dom-media-paused"><code>paused</code></dfn>
4407: attribute represents whether the <a href="#media-element">media element</a> is
4408: paused or not. The attribute must initially be true.</p>
4409:
4410: <p>A <a href="#media-element">media element</a> is a <dfn id="blocked-media-element">blocked media
4411: element</dfn> if its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is in the
4412: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> state or
4413: the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
4414: state, or if the element has <a href="#paused-for-user-interaction">paused for user
4415: interaction</a>.</p>
4416:
4417: <p>A <a href="#media-element">media element</a> is said to be <dfn id="potentially-playing">potentially
4418: playing</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4419: attribute is false, the element has not <a href="#ended-playback">ended playback</a>,
4420: playback has not <a href="#stopped-due-to-errors">stopped due to errors</a>,
4421: the element either has no <a href="#current-media-controller">current media controller</a> or
4422: has a <a href="#current-media-controller">current media controller</a> but is not <a href="#blocked-on-its-media-controller">blocked
4423: on its media controller</a>,
4424: and the element is not a <a href="#blocked-media-element">blocked media element</a>.</p>
4425:
4426: <p>A <a href="#media-element">media element</a> is said to have <dfn id="ended-playback">ended
4427: playback</dfn> when:</p>
4428:
4429: <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,
4430: and
4431:
4432: </li><li>
4433:
4434: <p>Either:
4435:
4436: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the end of the
4437: <a href="#media-resource">media resource</a>, and
4438:
4439: </li><li>The <a href="#direction-of-playback">direction of playback</a> is forwards, and
4440:
4441: </li><li>
4442: Either
4443: 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,
4444: or the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4445: controller</a>.
4446:
4447: </li></ul><p>Or:
4448:
4449: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the
4450: <a href="#earliest-possible-position">earliest possible position</a>, and
4451:
4452: </li><li>The <a href="#direction-of-playback">direction of playback</a> is backwards.
4453:
4454: </li></ul></li>
4455:
4456: </ul><p>The <dfn id="dom-media-ended" title="dom-media-ended"><code>ended</code></dfn>
4457: attribute must return true if the <a href="#media-element">media element</a> has
4458: <a href="#ended-playback">ended playback</a> and the <a href="#direction-of-playback">direction of
4459: playback</a> is forwards, and false otherwise.</p>
4460:
4461: <p>A <a href="#media-element">media element</a> is said to have <dfn id="stopped-due-to-errors">stopped due to
4462: 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
4463: the user agent <a href="#non-fatal-media-error">encounters a
4464: non-fatal error</a> during the processing of the <a href="#media-data">media
4465: data</a>, and due to that error, is not able to play the content
4466: at the <a href="#current-playback-position">current playback position</a>.</p>
4467:
4468: <p>A <a href="#media-element">media element</a> is said to have <dfn id="paused-for-user-interaction">paused for user
4469: 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
4470: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4471: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> and
4472: the user agent has reached a point in the <a href="#media-resource">media
4473: resource</a> where the user has to make a selection for the
4474: resource to continue.
4475: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4476: controller</a> when this happens, then the user agent must
4477: <a href="#report-the-controller-state">report the controller state</a> for the <a href="#media-element">media
4478: element</a>'s <a href="#current-media-controller">current media controller</a>. If If the
4479: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4480: controller</a> when the user makes a selection, allowing playback
4481: to resume, the user agent must similarly <a href="#report-the-controller-state">report the controller
4482: state</a> for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current
4483: media controller</a>.
4484: </p>
4485:
4486: <p>It is possible for a <a href="#media-element">media element</a> to have both
4487: <a href="#ended-playback">ended playback</a> and <a href="#paused-for-user-interaction">paused for user
4488: interaction</a> at the same time.</p>
4489:
4490: <p>When a <a href="#media-element">media element</a> that is <a href="#potentially-playing">potentially
4491: playing</a> stops playing because it has <a href="#paused-for-user-interaction">paused for user
4492: interaction</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
4493: <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>
4494:
4495: <p class="note">A <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code>
4496: DOM event <a href="#fire-waiting-when-waiting">can be fired</a> as a
4497: result of an element that is <a href="#potentially-playing">potentially playing</a>
4498: stopping playback due to its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute changing to
4499: a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.</p>
4500:
4501: <p>When the <a href="#current-playback-position">current playback position</a> reaches the end
4502: of the <a href="#media-resource">media resource</a> when the <a href="#direction-of-playback">direction of
4503: playback</a> is forwards, then the user agent must follow these
4504: steps:</p>
4505:
4506: <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
4507: and does not have a <a href="#current-media-controller">current media controller</a>,
4508: then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4509: possible position</a> of the <a href="#media-resource">media resource</a> and
4510: abort these steps.</p></li>
4511: <li><p>Stop playback.</p><p class="note">The <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> attribute becomes
4512: true.</p></li>
4513:
4514: <li><p>The user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
4515: a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
4516:
4517: <li><p>The user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
4518: a simple event</a> named <code title="event-media-ended"><a href="#event-media-ended">ended</a></code>
4519: at the element.</p></li>
4520:
4521: </ol><p>When the <a href="#current-playback-position">current playback position</a> reaches the
4522: <a href="#earliest-possible-position">earliest possible position</a> of the <a href="#media-resource">media
4523: resource</a> when the <a href="#direction-of-playback">direction of playback</a> is
4524: backwards, then the user agent must follow these steps:</p>
4525:
4526: <ol><li><p>Stop playback.</p></li>
4527:
4528: <li><p>The user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire
4529: a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
4530:
4531: </ol><hr><p>The <dfn id="dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
4532: attribute gives the desired speed at which the <a href="#media-resource">media
4533: resource</a> is to play, as a multiple of its intrinsic
4534: speed. The attribute is mutable: on getting it must return the last
4535: value it was set to, or 1.0 if it hasn't yet been set; on setting
4536: the attribute must be set to the new value.</p>
4537:
4538: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> is
4539: used by the user agent when it <a href="#expose-a-user-interface-to-the-user" title="expose a user interface
4540: to the user">exposes a user interface to the user</a>.</p>
4541:
4542: <p>The <dfn id="dom-media-playbackrate" title="dom-media-playbackRate"><code>playbackRate</code></dfn>
4543: attribute gives the <a href="#effective-playback-rate">effective playback rate</a>
4544: (assuming there is no <a href="#current-media-controller">current media controller</a> overriding it),
4545: which is the speed at which the <a href="#media-resource">media resource</a> plays,
4546: as a multiple of its intrinsic speed. If it is not equal to the
4547: <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>,
4548: then the implication is that the user is using a feature such as
4549: fast forward or slow motion playback. The attribute is mutable: on
4550: getting it must return the last value it was set to, or 1.0 if it
4551: hasn't yet been set; on setting the attribute must be set to the new
4552: value, and the playback will change speed
4553: (if the element is <a href="#potentially-playing">potentially playing</a> and there is no
4554: <a href="#current-media-controller">current media controller</a>).</p>
4555:
4556: <p id="rateUpdate">When the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or
4557: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4558: change value (either by being set by script or by being changed
4559: directly by the user agent, e.g. in response to user control) the
4560: 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
4561: event</a> named <code title="event-media-ratechange"><a href="#event-media-ratechange">ratechange</a></code> at the <a href="#media-element">media
4562: element</a>.</p>
4563:
4564: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> and
4565: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4566: have no effect when the <a href="#media-element">media element</a> has a
4567: <a href="#current-media-controller">current media controller</a>; the namesake attributes on
4568: the <code><a href="#mediacontroller">MediaController</a></code> object are used instead in that
4569: situation.</p>
4570:
4571: <hr><p>The <dfn id="dom-media-played" title="dom-media-played"><code>played</code></dfn>
4572: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4573: <code>TimeRanges</code> object</a> that represents the ranges of
4574: the <a href="#media-resource">media resource</a>, if any, that the user agent has so
4575: far rendered, at the time the attribute is evaluated.</p>
4576:
4577: <hr><p>When the <dfn id="dom-media-play" title="dom-media-play"><code>play()</code></dfn>
4578: method on a <a href="#media-element">media element</a> is invoked, the user agent
4579: must run the following steps.</p>
4580:
4581: <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
4582: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4583: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4584: algorithm</a>.</p></li>
4585:
4586: <li>
4587:
4588: <p>If the <a href="#ended-playback" title="ended playback">playback has ended</a>
4589: and the <a href="#direction-of-playback">direction of playback</a> is forwards,
4590: and the <a href="#media-element">media element</a> does not have a <a href="#current-media-controller">current
4591: media controller</a>,
4592: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4593: possible position</a> of the <a href="#media-resource">media resource</a>.</p>
4594:
4595: <p class="note">This <a href="#seekUpdate">will cause</a> the user
4596: 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
4597: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the <a href="#media-element">media
4598: element</a>.</p>
4599: </li>
4600:
4601: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
4602: media controller</a>, then <a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">bring the media element up
4603: to speed with its new media controller</a>.</p>
4604:
4605: </li><li>
4606:
4607: <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
4608: the following substeps:</p>
4609:
4610: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to false.</p></li>
4611:
4612: <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>
4613: named <code title="event-media-play"><a href="#event-media-play">play</a></code> at the element.</p></li>
4614:
4615: <li>
4616:
4617: <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
4618: value <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>,
4619: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, or
4620: <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
4621: <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>
4622: named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the
4623: element.</p>
4624:
4625: <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
4626: value <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4627: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>:
4628: <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>
4629: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> at the
4630: element.</p>
4631:
4632: </li>
4633:
4634: </ol></li>
4635:
4636: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4637: flag</a> to false.</p></li>
4638:
4639: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4640: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4641: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4642: controller</a>.</p></li>
4643:
4644: </ol><hr><p>When the <dfn id="dom-media-pause" title="dom-media-pause"><code>pause()</code></dfn>
4645: method is invoked, and when the user agent is required to pause the
4646: <a href="#media-element">media element</a>, the user agent must run the following
4647: steps:</p>
4648:
4649: <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
4650: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4651: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4652: algorithm</a>.</p></li>
4653:
4654: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4655: flag</a> to false.</p></li>
4656:
4657: <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
4658: following steps:</p>
4659:
4660: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to true.</p></li>
4661:
4662: <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
4663: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4664: element.</p></li>
4665:
4666: <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
4667: event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code>
4668: at the element.</p></li>
4669:
4670: </ol></li>
4671:
4672: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4673: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4674: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4675: controller</a>.</p></li>
4676:
4677: </ol><hr><p>The
4678: <dfn id="effective-playback-rate">effective playback rate</dfn> is not necessarily the element's
4679: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>. When a
4680: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4681: controller</a>, its <a href="#effective-playback-rate">effective playback rate</a> is the
4682: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
4683: rate</a>. Otherwise, the
4684: <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>.
4685: Thus, the <a href="#current-media-controller">current media controller</a> overrides the
4686: <a href="#media-element">media element</a>.
4687: </p>
4688:
4689: <p>If the <a href="#effective-playback-rate">effective playback rate</a> is positive or zero,
4690: then the <dfn id="direction-of-playback">direction of playback</dfn> is forwards. Otherwise, it
4691: is backwards.</p>
4692:
4693: <p id="media-playback">When a <a href="#media-element">media element</a> is
4694: <a href="#potentially-playing">potentially playing</a> and its <code><a href="infrastructure.html#document">Document</a></code> is a
4695: <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
4696: playback position</a> must increase monotonically at
4697: <a href="#effective-playback-rate">effective playback rate</a> units of media time per unit time
4698: of the <a href="#media-timeline">media timeline</a>'s clock.</p>
4699:
4700: <p class="note">The <a href="#effective-playback-rate">effective playback rate</a> can be 0.0,
4701: in which case the <a href="#current-playback-position">current playback position</a> doesn't
4702: 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
4703: <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> event doesn't
4704: fire).</p>
4705:
4706: <p class="note">This specification doesn't define how the user agent
4707: achieves the appropriate playback rate — depending on the
4708: protocol and media available, it is plausible that the user agent
4709: could negotiate with the server to have the server provide the media
4710: data at the appropriate rate, so that (except for the period between
4711: when the rate is changed and when the server updates the stream's
4712: playback rate) the client doesn't actually have to drop or
4713: interpolate any frames.</p>
4714:
4715: <p>When the <a href="#direction-of-playback">direction of playback</a> is backwards, any
4716: corresponding audio must be muted. When the <a href="#effective-playback-rate">effective playback
4717: rate</a> is so low or so high that the user agent cannot play
4718: audio usefully, the corresponding audio must also be muted. If the
4719: <a href="#effective-playback-rate">effective playback rate</a> is not 1.0, the user agent may
4720: apply pitch adjustments to the audio as necessary to render it
4721: faithfully.</p>
4722:
4723: <p><a href="#media-element" title="media element">Media elements</a> that are
4724: <a href="#potentially-playing">potentially playing</a> while not <a href="infrastructure.html#in-a-document">in a
4725: <code>Document</code></a> must not play any video, but should
4726: play any audio component. Media elements must not stop playing just
4727: because all references to them have been removed; only once a media
4728: element is in a state where no further audio could ever be played by
4729: that element may the element be garbage collected.</p>
4730:
4731: <p class="note">It is possible for an element to which no explicit
4732: references exist to play audio, even if such an element is not still
4733: actively playing: for instance, it could have a <a href="#current-media-controller">current media
4734: controller</a> that still has references and can still be
4735: unpaused, or it could be unpaused but stalled waiting for content to
4736: buffer.</p>
4737:
4738: <hr><p>When the <a href="#current-playback-position">current playback position</a> of a <a href="#media-element">media
4739: element</a> changes (e.g. due to playback or seeking), the user
4740: agent must run the following steps. If the <a href="#current-playback-position">current playback
4741: position</a> changes while the steps are running, then the user
4742: agent must wait for the steps to complete, and then must immediately
4743: rerun the steps.
4744: (These steps are thus run as often as possible or needed — if
4745: 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
4746: agent rushes ahead to "catch up".)
4747: </p>
4748:
4749: <ol><li><p>Let <var title="">current cues</var> be an ordered list of
4750: <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
4751: all the <a href="#text-track-cue" title="text track cue">cues</a> of all the <a href="#text-track-hidden" title="text track hidden">hidden</a>, <a href="#text-track-showing" title="text track
4752: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
4753: default">showing by default</a> <a href="#text-track" title="text track">text
4754: 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
4755: or equal to the <a href="#current-playback-position">current playback position</a> and whose
4756: <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are greater
4757: than the <a href="#current-playback-position">current playback position</a>, in <a href="#text-track-cue-order">text
4758: track cue order</a>.</p></li>
4759:
4760: <li><p>Let <var title="">other cues</var> be an ordered list of
4761: <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
4762: all the <a href="#text-track-cue" title="text track cue">cues</a> of <a href="#text-track-hidden" title="text track hidden">hidden</a>, <a href="#text-track-showing" title="text track
4763: showing">showing</a>, and <a href="#text-track-showing-by-default" title="text track showing by
4764: default">showing by default</a> <a href="#text-track" title="text track">text
4765: tracks</a> of the <a href="#media-element">media element</a> that are not
4766: present in <var title="">current cues</var>, also in <a href="#text-track-cue-order">text
4767: track cue order</a>.</p></li>
4768:
4769: <li><p>If the time was reached through the usual monotonic increase
4770: of the <a href="#current-playback-position">current playback position</a> during normal
4771: 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
4772: element in the past 15 to 250ms and is not still running event
4773: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4774: 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.
4775: (In the other cases, such as explicit seeks, relevant events get
4776: fired as part of the overall process of changing the <a href="#current-playback-position">current
4777: playback position</a>.)</p>
4778:
4779: <p class="note">The event thus is not to be fired faster than about
4780: 66Hz or slower than 4Hz (assuming the event handlers don't take
4781: longer than 250ms to run). User agents are encouraged to vary the
4782: frequency of the event based on the system load and the average
4783: cost of processing the event each time, so that the UI updates are
4784: not any more frequent than the user agent can comfortably handle
4785: while decoding the video.</p></li>
4786:
4787: <li><p>If all of the <a href="#text-track-cue" title="text track cue">cues</a> in
4788: <var title="">current cues</var> have their <a href="#text-track-cue-active-flag">text track cue
4789: active flag</a> set, and none of the <a href="#text-track-cue" title="text track
4790: cue">cues</a> in <var title="">other cues</var> have their
4791: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, then abort these
4792: steps.</p></li>
4793:
4794: <li><p>If the time was reached through the usual monotonic increase
4795: of the <a href="#current-playback-position">current playback position</a> during normal
4796: playback, and there are <a href="#text-track-cue" title="text track cue">cues</a> in
4797: <var title="">other cues</var> that have both their <a href="#text-track-cue-active-flag">text
4798: track cue active flag</a> set and their <a href="#text-track-cue-pause-on-exit-flag">text track cue
4799: pause-on-exit flag</a> set, then immediately <a href="#dom-media-pause" title="dom-media-pause">pause</a> the <a href="#media-element">media
4800: element</a>. (In the other cases, such as explicit
4801: seeks, playback is not paused by going past the end time of a <a href="#text-track-cue" title="text track cue">cue</a>, even if that <a href="#text-track-cue" title="text
4802: track cue">cue</a> has its <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
4803: flag</a> set.)</p></li>
4804:
4805: <li><p>Let <var title="">affected tracks</var> be a list of <a href="#text-track" title="text track">text tracks</a>, initially empty.</p></li>
4806:
4807: <li><p>For each <a href="#text-track-cue" title="text track cue">text track
4808: cue</a> in <var title="">other cues</var> that has its
4809: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
4810: <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
4811: <code title="event-exit">exit</code> at the
4812: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
4813: track cue">cue</a>'s <a href="#text-track">text track</a> to <var title="">affected tracks</var>, if it's not already in the
4814: list.</p></li>
4815:
4816: <li><p>For each <a href="#text-track-cue" title="text track cue">text track
4817: cue</a> in <var title="">current cues</var> that does not have
4818: its <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
4819: <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
4820: <code title="event-enter">enter</code> at the
4821: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
4822: track cue">cue</a>'s <a href="#text-track">text track</a> to <var title="">affected tracks</var>, if it's not already in the
4823: list.</p></li>
4824:
4825: <li><p>For each <a href="#text-track">text track</a> in <var title="">affected
4826: tracks</var>, in the order they were added to the list (which will
4827: match the relative order of the <a href="#text-track" title="text track">text
4828: tracks</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
4829: text tracks</a>), <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
4830: simple event</a> named <code title="event-cuechange">cuechange</code> at the
4831: <code><a href="#texttrack">TextTrack</a></code> object, and, if the <a href="#text-track">text
4832: track</a> has a corresponding <code><a href="#the-track-element">track</a></code> element, to
4833: then <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-cuechange">cuechange</code> at the <code><a href="#the-track-element">track</a></code>
4834: element as well.</p></li>
4835:
4836: <li><p>Set the <a href="#text-track-cue-active-flag">text track cue active flag</a> of all the
4837: <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
4838: active flag</a> of all the <a href="#text-track-cue" title="text track
4839: cue">cues</a> in the <var title="">other cues</var>.</p></li>
4840:
4841: <li><p>Run the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
4842: rendering</a> of each of the <a href="#text-track" title="text track">text
4843: 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
4844: track showing by default">showing by default</a>.
4845: </p></li>
4846:
4847: </ol><p>For the purposes of the algorithm above, a <a href="#text-track-cue">text track
4848: cue</a> is considered to be part of a <a href="#text-track">text track</a>
4849: only if it is listed in the <a href="#text-track-list-of-cues">text track list of cues</a>,
4850: not merely if it is associated with the <a href="#text-track">text
4851: track</a>.</p>
4852:
4853: <p class="note">If the <a href="#media-element">media element</a>'s
4854: <code><a href="infrastructure.html#document">Document</a></code> stops being a <a href="browsers.html#fully-active">fully active</a>
4855: document, then the playback will <a href="#media-playback">stop</a>
4856: until the document is active again.</p>
4857:
4858: <p>When a <a href="#media-element">media element</a> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an
4859: element from a document">removed from a
4860: <code>Document</code></a>, the user agent must run
4861: the following steps:</p>
4862:
4863: <ol><li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
4864: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that removed the
4865: <a href="#media-element">media element</a> from the <code><a href="infrastructure.html#document">Document</a></code> to
4866: continue. The <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the
4867: remaining steps of this algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous
4868: section</a> are marked with ⌛.)</p></li>
4869:
4870: <li><p>⌛ If the <a href="#media-element">media element</a> is <a href="infrastructure.html#in-a-document">in a
4871: <code>Document</code></a>, abort these steps.</p></li>
4872:
4873: <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
4874: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, abort these
4875: steps.</p></li>
4876:
4877: <li><p>⌛ <a href="#dom-media-pause" title="dom-media-pause">Pause</a> the
4878: <a href="#media-element">media element</a>.</p>
4879:
4880: </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>
4881:
4882: <dd>
4883:
4884: <p>Returns true if the user agent is currently seeking.</p>
4885:
4886: </dd>
4887:
4888: <dt><var title="">media</var> . <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code></dt>
4889:
4890: <dd>
4891:
4892: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4893: ranges of the <a href="#media-resource">media resource</a> to which it is possible
4894: for the user agent to seek.</p>
4895:
4896: </dd>
4897:
4898: </dl><div class="impl">
4899:
4900: <p>The <dfn id="dom-media-seeking" title="dom-media-seeking"><code>seeking</code></dfn>
4901: attribute must initially have the value false.</p>
4902:
4903: <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
4904: playback position</var> in the <a href="#media-resource">media resource</a>, it means
4905: that the user agent must run the following steps. This algorithm
4906: interacts closely with the <a href="webappapis.html#event-loop">event loop</a> mechanism; in
4907: particular, it has a <a href="webappapis.html#synchronous-section">synchronous
4908: section</a> (which is triggered as part of the <a href="webappapis.html#event-loop">event
4909: loop</a> algorithm). Steps in that section are marked with
4910: ⌛.</p>
4911:
4912: <ol><li><p>If the <a href="#media-element">media element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then raise an
4913: <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception (if the seek was in
4914: response to a DOM method call or setting of an IDL attribute), and
4915: abort these steps.</p></li>
4916:
4917: <li><p>If the element's <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute is true,
4918: then another instance of this algorithm is already running. Abort
4919: that other instance of the algorithm without waiting for the step
4920: that it is running to complete.</p></li>
4921:
4922: <li><p>Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL
4923: attribute to true.</p></li>
4924:
4925: <li><p>If the seek was in response to a DOM method call or setting
4926: of an IDL attribute, then continue the script. The remainder of
4927: these steps must be run asynchronously. With the exception of the
4928: steps marked with ⌛, they could be aborted at any time by
4929: another instance of this algorithm being invoked.</p></li>
4930:
4931: <li><p>If the <var title="">new playback position</var> is later
4932: than the end of the <a href="#media-resource">media resource</a>, then let it be the
4933: end of the <a href="#media-resource">media resource</a> instead.</p></li>
4934:
4935: <li><p>If the <var title="">new playback position</var> is less
4936: than the <a href="#earliest-possible-position">earliest possible position</a>, let it be that
4937: position instead.</p></li>
4938:
4939: <li><p>If the (possibly now changed) <var title="">new playback
4940: 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
4941: 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
4942: nearest to the <var title="">new playback position</var>. If two
4943: positions both satisfy that constraint (i.e. the <var title="">new
4944: playback position</var> is exactly in the middle between two ranges
4945: in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute)
4946: then use the position that is closest to the <a href="#current-playback-position">current playback
4947: 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
4948: <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
4949: false and abort these steps.</p></li>
4950:
4951: <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
4952: event</a> named <code title="event-media-seeking"><a href="#event-media-seeking">seeking</a></code>
4953: at the element.</p></li>
4954:
4955: <li>
4956:
4957: <p>Set the <a href="#current-playback-position">current playback position</a> to the given
4958: <var title="">new playback position</var>.</p>
4959:
4960: <p class="note">If the <a href="#media-element">media element</a> was
4961: <a href="#potentially-playing">potentially playing</a> immediately before it started
4962: seeking, but seeking caused its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to change
4963: 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
4964: <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
4965: element.</p>
4966:
4967:
4968: </li>
4969:
4970: <li><p>Wait until the user agent has established whether or not the
4971: <a href="#media-data">media data</a> for the <var title="">new playback
4972: position</var> is available, and, if it is, until it has decoded
4973: enough data to play back that position.</p>
4974: </li>
4975:
4976: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
4977: section</a> consists of all the remaining steps of this
4978: algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous section</a> are
4979: marked with ⌛.)</p></li>
4980:
4981: <li><p>⌛ Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
4982: false.</p></li>
4983:
4984: <li id="seekUpdate"><p><a href="webappapis.html#queue-a-task">Queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a
4985: simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4986: element.</p></li>
4987:
4988: <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
4989: event</a> named <code title="event-media-seeked"><a href="#event-media-seeked">seeked</a></code>
4990: at the element.</p></li>
4991:
4992: </ol><p>The <dfn id="dom-media-seekable" title="dom-media-seekable"><code>seekable</code></dfn>
4993: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4994: <code>TimeRanges</code> object</a> that represents the ranges of
4995: the <a href="#media-resource">media resource</a>, if any, that the user agent is able
4996: to seek to, at the time the attribute is evaluated.</p>
4997:
4998: <p class="note">If the user agent can seek to anywhere in the
4999: <a href="#media-resource">media resource</a>, e.g. because it is a simple movie file
5000: and the user agent and the server support HTTP Range requests, then
5001: the attribute would return an object with one range, whose start is
5002: the time of the first frame (the <a href="#earliest-possible-position">earliest possible
5003: position</a>, typically zero), and whose end is the same as the
5004: time of the first frame plus the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute's value (which
5005: would equal the time of the last frame, and might be positive
5006: Infinity).</p>
5007:
5008: <p class="note">The range might be continuously changing, e.g. if
5009: the user agent is buffering a sliding window on an infinite
5010: stream. This is the behavior seen with DVRs viewing live TV, for
5011: instance.</p>
5012:
5013: <p><a href="#media-resource" title="media resource">Media resources</a> might be
5014: internally scripted or interactive. Thus, a <a href="#media-element">media
5015: element</a> could play in a non-linear fashion. If this happens,
5016: 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
5017: <a href="#current-playback-position">current playback position</a> changes in a discontinuous
5018: fashion (so that the relevant events fire).
5019: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
5020: controller</a>, then the user agent must <a href="#seek-the-media-controller">seek the media
5021: controller</a> appropriately instead.
5022: </p>
5023:
5024: </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
5025: and video tracks. For example, in addition to the primary video and
5026: audio tracks, a <a href="#media-resource">media resource</a> could have
5027: foreign-language dubbed dialogues, director's commentaries, audio
5028: 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>
5029:
5030: <dd>
5031:
5032: <p>Returns a <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
5033: the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
5034:
5035: </dd>
5036:
5037: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code></dt>
5038:
5039: <dd>
5040:
5041: <p>Returns an <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object representing
5042: the video tracks available in the <a href="#media-resource">media resource</a>.</p>
5043:
5044: </dd>
5045:
5046: </dl><div class="impl">
5047:
5048: <p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
5049: attribute of a <a href="#media-element">media element</a> must return a
5050: <a href="infrastructure.html#live">live</a> <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
5051: the audio tracks available in the <a href="#media-element">media element</a>'s
5052: <a href="#media-resource">media resource</a>. The same object must be returned each
5053: time.</p>
5054:
5055: <p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
5056: attribute of a <a href="#media-element">media element</a> must return a
5057: <a href="infrastructure.html#live">live</a> <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object
5058: representing the video tracks available in the <a href="#media-element">media
5059: element</a>'s <a href="#media-resource">media resource</a>. The same object must
5060: be returned each time.</p>
5061:
5062: <p class="note">There are only ever two <code><a href="#tracklist">TrackList</a></code>
5063: objects (one <code><a href="#multipletracklist">MultipleTrackList</a></code> object and one
5064: <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object) per <a href="#media-element">media
5065: element</a>, even if another <a href="#media-resource">media resource</a> is
5066: loaded into the element: the objects are reused.</p>
5067:
5068: </div><h6 id="tracklist-objects"><span class="secno">4.8.10.10.1 </span><code><a href="#tracklist">TrackList</a></code> objects</h6><p>The <code><a href="#multipletracklist">MultipleTrackList</a></code> and
5069: <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> interfaces, used by the attributes
5070: defined in the previous section, are substantially similar. Their
5071: common features are defined in the <code><a href="#tracklist">TrackList</a></code> interface,
5072: from which they both inherit.</p><pre class="idl">interface <dfn id="tracklist">TrackList</dfn> {
5073: readonly attribute unsigned long <a href="#dom-tracklist-length" title="dom-TrackList-length">length</a>;
5074: DOMString <a href="#dom-tracklist-getid" title="dom-TrackList-getID">getID</a>(in unsigned long index);
5075: DOMString <a href="#dom-tracklist-getkind" title="dom-TrackList-getKind">getKind</a>(in unsigned long index);
5076: DOMString <a href="#dom-tracklist-getlabel" title="dom-TrackList-getLabel">getLabel</a>(in unsigned long index);
5077: DOMString <a href="#dom-tracklist-getlanguage" title="dom-TrackList-getLanguage">getLanguage</a>(in unsigned long index);
5078:
5079: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
5080: };
5081:
5082: interface <dfn id="multipletracklist">MultipleTrackList</dfn> : <a href="#tracklist">TrackList</a> {
5083: boolean <a href="#dom-tracklist-isenabled" title="dom-TrackList-isEnabled">isEnabled</a>(in unsigned long index);
5084: void <a href="#dom-tracklist-enable" title="dom-TrackList-enable">enable</a>(in unsigned long index);
5085: void <a href="#dom-tracklist-disable" title="dom-TrackList-disable">disable</a>(in unsigned long index);
5086: };
5087:
5088: interface <dfn id="exclusivetracklist">ExclusiveTrackList</dfn> : <a href="#tracklist">TrackList</a> {
5089: readonly attribute unsigned long <a href="#dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex">selectedIndex</a>;
5090: void <a href="#dom-tracklist-select" title="dom-TrackList-select">select</a>(in unsigned long index);
5091: };</pre><dl class="domintro"><dt><var title="">tracks</var> . <code title="dom-TrackList-length"><a href="#dom-tracklist-length">length</a></code></dt>
5092:
5093: <dd>
5094:
5095: <p>Returns the number of tracks in the list.</p>
5096:
5097: </dd>
5098:
5099: <dt><var title="">id</var> = <var title="">tracks</var> . <code title="dom-TrackList-getID"><a href="#dom-tracklist-getid">getID</a></code>( <var title="">index</var> )</dt>
5100:
5101: <dd>
5102:
5103: <p>Returns the ID of the given track. This is the ID that can be
5104: used with a fragment identifier if the format supports the
5105: <cite>Media Fragments URI</cite> syntax. <a href="#hrefMEDIAFRAG">[MEDIAFRAG]</a></p>
5106:
5107: </dd>
5108:
5109: <dt><var title="">kind</var> = <var title="">tracks</var> . <code title="dom-TrackList-getKind"><a href="#dom-tracklist-getkind">getKind</a></code>( <var title="">index</var> )</dt>
5110:
5111: <dd>
5112:
5113: <p>Returns the category the given track falls into. The <a href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p>
5114:
5115: </dd>
5116:
5117: <dt><var title="">label</var> = <var title="">tracks</var> . <code title="dom-TrackList-getLabel"><a href="#dom-tracklist-getlabel">getLabel</a></code>( <var title="">index</var> )</dt>
5118:
5119: <dd>
5120:
5121: <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
5122:
5123: </dd>
5124:
5125: <dt><var title="">language</var> = <var title="">tracks</var> . <code title="dom-TrackList-getLanguage"><a href="#dom-tracklist-getlanguage">getLanguage</a></code>( <var title="">index</var> )</dt>
5126:
5127: <dd>
5128:
5129: <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
5130:
5131: </dd>
5132:
5133: <dt><var title="">enabled</var> = <var title="">audioTracks</var> . <code title="dom-TrackList-isEnabled"><a href="#dom-tracklist-isenabled">isEnabled</a></code>( <var title="">index</var> )</dt>
5134:
5135: <dd>
5136:
5137: <p>Returns true if the given track is active, and false otherwise.</p>
5138:
5139: </dd>
5140:
5141: <dt><var title="">audioTracks</var> . <code title="dom-TrackList-enable"><a href="#dom-tracklist-enable">enable</a></code>( <var title="">index</var> )</dt>
5142:
5143: <dd>
5144:
5145: <p>Enables the given track.</p>
5146:
5147: </dd>
5148:
5149: <dt><var title="">audioTracks</var> . <code title="dom-TrackList-disable"><a href="#dom-tracklist-disable">disable</a></code>( <var title="">index</var> )</dt>
5150:
5151: <dd>
5152:
5153: <p>Disables the given track.</p>
5154:
5155: </dd>
5156:
5157: <dt><var title="">videoTracks</var> . <code title="dom-TrackList-selectedIndex"><a href="#dom-tracklist-selectedindex">isEnabled</a></code></dt>
5158:
5159: <dd>
5160:
5161: <p>Returns the index of the currently selected track, if any, or −1 otherwise.</p>
5162:
5163: </dd>
5164:
5165: <dt><var title="">videoTracks</var> . <code title="dom-TrackList-select"><a href="#dom-tracklist-select">select</a></code>( <var title="">index</var> )</dt>
5166:
5167: <dd>
5168:
5169: <p>Selects the given track.</p>
5170:
5171: </dd>
5172:
5173: </dl><div class="impl">
5174:
5175: <p>The <dfn id="dom-tracklist-length" title="dom-TrackList-length"><code>length</code></dfn>
5176: attribute must return the number of tracks represented by the
5177: <code><a href="#tracklist">TrackList</a></code> object at the time of getting.</p>
5178:
5179: <p>Tracks in a <code><a href="#tracklist">TrackList</a></code> object must be consistently
5180: ordered. If the <a href="#media-resource">media resource</a> is in a format that
5181: defines an order, then that order must be used; otherwise, the order
5182: must be the relative order in which the tracks are declared in the
5183: <a href="#media-resource">media resource</a>. Each track in a <code><a href="#tracklist">TrackList</a></code>
5184: thus has an index; the first has the index 0, and each subsequent
5185: track is numbered one higher than the previous one.</p>
5186:
5187: <p>The <dfn id="dom-tracklist-getid" title="dom-TrackList-getID"><code>getID(<var title="">index</var>)</code></dfn> method must return the identifier
5188: of the track with index <var title="">index</var>, if there is one.
5189: If there is no such track, then the method must instead throw an
5190: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If the <a href="#media-resource">media
5191: resource</a> is in a format that supports the <cite>Media
5192: Fragments URI</cite> fragment identifier syntax, the returned
5193: identifier must be the same identifier that would enable the track
5194: if used as the name of a track in the track dimension of such a
5195: fragment identifier. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
5196:
5197: <p>The <dfn id="dom-tracklist-getkind" title="dom-TrackList-getKind"><code>getKind(<var title="">index</var>)</code></dfn> method must return the category
5198: of the track with index <var title="">index</var>, if there is one.
5199: If there is no such track, then the method must instead throw an
5200: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5201:
5202: <p>The category of a track is the string given in the first column
5203: of the table below that is the most appropriate for the track based
5204: on the definitions in the table's second and third columns, as
5205: determined by the metadata included in the track in the <a href="#media-resource">media
5206: resource</a>. For Ogg files, the Role header of the track gives
5207: the relevant metadata. The cell in the third column of a row says
5208: what the category given in the cell in the first column of that row
5209: applies to; a category is only appropriate for an audio track if it
5210: applies to audio tracks, and a category is only appropriate for
5211: video tracks if it applies to video tracks.</p>
5212:
5213: </div><table id="dom-TrackList-getKind-categories"><caption>Return values for <code title="dom-TrackList-getKind"><a href="#dom-tracklist-getkind">getKind()</a></code></caption>
5214: <thead><tr><th>Category
5215: </th><th>Definition
5216: </th><th>Applies to...</th>
5217: <th>Examples
5218: </th></tr></thead><tbody><tr><td>"<dfn id="dom-tracklist-getkind-alternate" title="dom-TrackList-getKind-alternate"><code>alternative</code></dfn>"
5219: </td><td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
5220: </td><td>Audio and video.
5221: </td><td>Ogg: "audio/alterate" or "video/alternate".
5222:
5223: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-description" title="dom-TrackList-getKind-description"><code>description</code></dfn>"
5224: </td><td>An audio description of a video track.
5225: </td><td>Audio only.
5226: </td><td>Ogg: "audio/audiodesc".
5227:
5228: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-main" title="dom-TrackList-getKind-main"><code>main</code></dfn>"
5229: </td><td>The primary audio or video track.
5230: </td><td>Audio and video.
5231: </td><td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
5232:
5233: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-sign" title="dom-TrackList-getKind-sign"><code>sign</code></dfn>"
5234: </td><td>A sign-language interpretation of an audio track.
5235: </td><td>Video only.
5236: </td><td>Ogg: "video/sign".
5237:
5238: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-translation" title="dom-TrackList-getKind-translation"><code>translation</code></dfn>"
5239: </td><td>A translated version of the main track.
5240: </td><td>Audio only.
5241: </td><td>Ogg: "audio/dub".
5242:
5243: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-none" title="dom-TrackList-getKind-none"><code></code></dfn>" (empty string)
5244: </td><td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
5245: </td><td>Audio and video.
5246: </td><td>Any other track type or track role.
5247:
5248: </td></tr></tbody></table><div class="impl">
5249:
5250: <p>The <dfn id="dom-tracklist-getlabel" title="dom-TrackList-getLabel"><code>getLabel(<var title="">index</var>)</code></dfn> method must return the label of
5251: the track with index <var title="">index</var>, if there is one and
5252: it has a label. If there is no such track, then the method must
5253: instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is
5254: a track with index <var title="">index</var>, but it has no label,
5255: then the method must return the empty string.</p>
5256:
5257: <p>The <dfn id="dom-tracklist-getlanguage" title="dom-TrackList-getLanguage"><code>getLanguage(<var title="">index</var>)</code></dfn> method must return the BCP 47
5258: language tag of the language of the track with index <var title="">index</var>, if there is one and it has a language. If
5259: there is no such track, then the method must instead throw an
5260: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is a track with
5261: index <var title="">index</var>, but it has no language, or the user
5262: agent is not able to express that language as a BCP 47 language tag
5263: (for example because the language information in the <a href="#media-resource">media
5264: resource</a>'s format is a free-form string without a defined
5265: interpretation), then the method must return the empty string.</p>
5266:
5267: <hr><p>A <code><a href="#multipletracklist">MultipleTrackList</a></code> object represents a track list
5268: where multiple tracks can be enabled simultaneously. Each track is
5269: either enabled or disabled.</p>
5270:
5271: <p>The <dfn id="dom-tracklist-isenabled" title="dom-TrackList-isEnabled"><code>isEnabled(<var title="">index</var>)</code></dfn> method must return true if there
5272: is a track with index <var title="">index</var>, and it is currently
5273: enabled, false if there is a track with index <var title="">index</var>, but it is currently disabled, and must throw
5274: an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception if there is no track with
5275: index <var title="">index</var>.</p>
5276:
5277: <p>The <dfn id="dom-tracklist-enable" title="dom-TrackList-enable"><code>enable(<var title="">index</var>)</code></dfn> method must enable the track with
5278: index <var title="">index</var>, if there is one. If there is not,
5279: it must instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5280:
5281: <p>The <dfn id="dom-tracklist-disable" title="dom-TrackList-disable"><code>disable(<var title="">index</var>)</code></dfn> method must disable the track with
5282: index <var title="">index</var>, if there is one. If there is not,
5283: it must instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5284:
5285: <p>Whenever a track is enabled or disabled, the user agent must
5286: <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
5287: <code title="event-media-change">change</code> at the
5288: <code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
5289:
5290: <hr><p>An <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object represents a track list
5291: where exactly one track is selected at a time.</p>
5292:
5293: <p>The <dfn id="dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex"><code>selectedIndex</code></dfn>
5294: attribute must return the index of the currently selected track. If
5295: the <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object does not represent any
5296: tracks, it must instead return −1.</p>
5297:
5298: <p>The <dfn id="dom-tracklist-select" title="dom-TrackList-select"><code>select(<var title="">index</var>)</code></dfn> must select the track with index
5299: <var title="">index</var>, if there is one, unselecting whichever
5300: track was previously selected. If there is no track with index <var title="">index</var>, it must instead throw an
5301: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5302:
5303: <p>Whenever the selected track is changed, the user agent must
5304: <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
5305: <code title="event-media-change">change</code> at the
5306: <code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
5307:
5308: <hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
5309: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
5310: event types</a>) that must be supported, as IDL attributes, by
5311: all objects implementing the <code><a href="#tracklist">TrackList</a></code>
5312: interface:</p>
5313:
5314: <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>
5315: </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>
5316: </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
5317: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5318:
5319:
5320:
5321: </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
5322: <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attributes
5323: allow scripts to select which track should play, but it is also
5324: possible to select specific tracks declaratively, by specifying
5325: particular tracks in the fragment identifier of the <a href="urls.html#url">URL</a>
5326: of the <a href="#media-resource">media resource</a>. The format of the fragment
5327: identifier depends on the <a href="infrastructure.html#mime-type">MIME type</a> of the <a href="#media-resource">media
5328: resource</a>. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3986">[RFC3986]</a></p><div class="example">
5329:
5330: <p>In this example, a video that uses a format that supports the
5331: <cite>Media Fragments URI</cite> fragment identifier syntax is
5332: embedded in such a way that the alternative angles labeled
5333: "Alternative" are enabled instead of the default video track. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
5334:
5335: <pre><video src="myvideo#track=Alternative"></video></pre>
5336:
5337:
5338: </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
5339: <code><a href="#mediacontroller">MediaController</a></code>. A <code><a href="#mediacontroller">MediaController</a></code> is an
5340: object that coordinates the playback of multiple <a href="#media-element" title="media
5341: element">media elements</a>, for instance so that a sign-language
5342: interpreter track can be overlaid on a video track, with the two
5343: being kept in sync.</p><p>By default, a <a href="#media-element">media element</a> has no
5344: <code><a href="#mediacontroller">MediaController</a></code>. An implicit
5345: <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.
5346: An explicit <code><a href="#mediacontroller">MediaController</a></code> can be assigned directly
5347: using the <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> IDL
5348: attribute.</p><p><a href="#media-element" title="media element">Media elements</a> with a
5349: <code><a href="#mediacontroller">MediaController</a></code> are said to be <i>slaved</i> to their
5350: controller. The <code><a href="#mediacontroller">MediaController</a></code> modifies the playback
5351: rate and the playback volume of each of the <a href="#media-element" title="media
5352: element">media elements</a> slaved to it, and ensures that when
5353: any of its slaved <a href="#media-element" title="media element">media elements</a>
5354: 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
5355: <code><a href="#mediacontroller">MediaController</a></code>, its playback rate is fixed to that of
5356: the other tracks in the same <code><a href="#mediacontroller">MediaController</a></code>, and any
5357: 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>]
5358: interface <dfn id="mediacontroller">MediaController</dfn> {
5359: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-buffered" title="dom-MediaController-buffered">buffered</a>;
5360: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-seekable" title="dom-MediaController-seekable">seekable</a>;
5361: readonly attribute double <a href="#dom-mediacontroller-duration" title="dom-MediaController-duration">duration</a>;
5362: attribute double <a href="#dom-mediacontroller-currenttime" title="dom-MediaController-currentTime">currentTime</a>;
5363:
5364: readonly attribute boolean <a href="#dom-mediacontroller-paused" title="dom-MediaController-paused">paused</a>;
5365: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-played" title="dom-MediaController-played">played</a>;
5366: void <a href="#dom-mediacontroller-play" title="dom-MediaController-play">play</a>();
5367: void <a href="#dom-mediacontroller-pause" title="dom-MediaController-pause">pause</a>();
5368:
5369: attribute double <a href="#dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate">defaultPlaybackRate</a>;
5370: attribute double <a href="#dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate">playbackRate</a>;
5371:
5372: attribute double <a href="#dom-mediacontroller-volume" title="dom-MediaController-volume">volume</a>;
5373: attribute boolean <a href="#dom-mediacontroller-muted" title="dom-MediaController-muted">muted</a>;
5374:
5375: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onemptied" title="handler-MediaController-onemptied">onemptied</a>;
5376: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata">onloadedmetadata</a>;
5377: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata">onloadeddata</a>;
5378: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay">oncanplay</a>;
5379: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough">oncanplaythrough</a>;
5380: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onplaying" title="handler-MediaController-onplaying">onplaying</a>;
5381: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting">onwaiting</a>;
5382:
5383: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange">ondurationchange</a>;
5384: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate">ontimeupdate</a>;
5385: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onplay" title="handler-MediaController-onplay">onplay</a>;
5386: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onpause" title="handler-MediaController-onpause">onpause</a>;
5387: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onratechange" title="handler-MediaController-onratechange">onratechange</a>;
5388: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange">onvolumechange</a>;
5389: };</pre><dl class="domintro"><dt><var title="">controller</var> = new <code title="dom-MediaController"><a href="#dom-mediacontroller">MediaController</a></code>()</dt>
5390:
5391: <dd>
5392:
5393: <p>Returns a new <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5394:
5395: </dd>
5396:
5397: <dt><var title="">media</var> . <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> [ = <var title="">controller</var> ]</dt>
5398:
5399: <dd>
5400:
5401: <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>
5402:
5403: <p>Can be set, to set an explicit <code><a href="#mediacontroller">MediaController</a></code>.
5404: Doing so removes the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if
5405: any.</p>
5406:
5407: </dd>
5408:
5409: <dt><var title="">controller</var> . <code title="dom-MediaController-buffered"><a href="#dom-mediacontroller-buffered">buffered</a></code></dt>
5410:
5411: <dd>
5412:
5413: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5414: intersection of the time ranges for which the user agent has all
5415: relevant media data for all the slaved <a href="#media-element" title="media
5416: element">media elements</a>.</p>
5417:
5418: </dd>
5419:
5420: <dt><var title="">controller</var> . <code title="dom-MediaController-seekable"><a href="#dom-mediacontroller-seekable">seekable</a></code></dt>
5421:
5422: <dd>
5423:
5424: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5425: intersection of the time ranges into which the user agent can seek
5426: for all the slaved <a href="#media-element" title="media element">media
5427: elements</a>.</p>
5428:
5429: </dd>
5430:
5431: <dt><var title="">controller</var> . <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code></dt>
5432:
5433: <dd>
5434:
5435: <p>Returns the difference between the earliest playable moment and
5436: the latest playable moment (not considering whether the data in
5437: question is actually buffered or directly seekable, but not
5438: including time in the future for infinite streams). Will return
5439: zero if there is no media.</p>
5440:
5441: </dd>
5442:
5443: <dt><var title="">controller</var> . <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
5444:
5445: <dd>
5446:
5447: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds,
5448: as a position between zero time and the current <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code>.</p>
5449:
5450: <p>Can be set, to seek to the given time.</p><p>
5451:
5452: </p></dd>
5453:
5454: <dt><var title="">controller</var> . <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code></dt>
5455:
5456: <dd>
5457:
5458: <p>Returns true if playback is paused; false otherwise. When this
5459: attribute is true, any <a href="#media-element">media element</a> slaved to this
5460: controller will be stopped.</p>
5461:
5462: </dd>
5463:
5464: <dt><var title="">controller</var> . <code title="dom-MediaController-played"><a href="#dom-mediacontroller-played">played</a></code></dt>
5465:
5466: <dd>
5467:
5468: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5469: union of the time ranges in all the slaved <a href="#media-element" title="media
5470: element">media elements</a> that have been played.</p>
5471:
5472: </dd>
5473:
5474: <dt><var title="">controller</var> . <code title="dom-MediaController-play"><a href="#dom-mediacontroller-play">play</a></code>()</dt>
5475:
5476: <dd>
5477:
5478: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5479: attribute to false.</p>
5480:
5481: </dd>
5482:
5483: <dt><var title="">controller</var> . <code title="dom-MediaController-pause"><a href="#dom-mediacontroller-pause">pause</a></code>()</dt>
5484:
5485: <dd>
5486:
5487: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5488: attribute to true.</p>
5489:
5490: </dd>
5491:
5492: <dt><var title="">controller</var> . <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
5493:
5494: <dd>
5495:
5496: <p>Returns the default rate of playback.</p>
5497:
5498: <p>Can be set, to change the default rate of playback.</p>
5499:
5500: <p>This default rate has no direct effect on playback, but if the
5501: user switches to a fast-forward mode, when they return to the
5502: normal playback mode, it is expected that rate of playback (<code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code>) will
5503: be returned to this default rate.</p>
5504:
5505: </dd>
5506:
5507: <dt><var title="">controller</var> . <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
5508:
5509: <dd>
5510:
5511: <p>Returns the current rate of playback.</p>
5512:
5513: <p>Can be set, to change the rate of playback.</p>
5514:
5515: </dd>
5516:
5517: <dt><var title="">controller</var> . <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
5518:
5519: <dd>
5520:
5521: <p>Returns the current playback volume multiplier, as a number in
5522: the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the
5523: loudest.</p>
5524:
5525: <p>Can be set, to change the volume multiplier.</p>
5526:
5527: <p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
5528: in the range 0.0 .. 1.0.</p>
5529:
5530: </dd>
5531:
5532: <dt><var title="">controller</var> . <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
5533:
5534: <dd>
5535:
5536: <p>Returns true if all audio is muted (regardless of other
5537: attributes either on the controller or on any <a href="#media-element" title="media
5538: element">media elements</a> slaved to this controller), and
5539: false otherwise.</p>
5540:
5541: <p>Can be set, to change whether the audio is muted or not.</p>
5542:
5543: </dd>
5544:
5545: </dl><div class="impl">
5546:
5547: <p>A <a href="#media-element">media element</a> can have a <dfn id="current-media-controller">current media
5548: controller</dfn>, which is a <code><a href="#mediacontroller">MediaController</a></code> object.
5549: 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
5550: not have a <a href="#current-media-controller">current media controller</a>. (If it is created
5551: <em>with</em> such an attribute, then that attribute initializes the
5552: <a href="#current-media-controller">current media controller</a>, as defined below.)</p>
5553:
5554: <p>The <dfn id="slaved-media-elements">slaved media elements</dfn> of a
5555: <code><a href="#mediacontroller">MediaController</a></code> are the <a href="#media-element" title="media
5556: element">media elements</a> whose <a href="#current-media-controller">current media
5557: controller</a> is that <code><a href="#mediacontroller">MediaController</a></code>. All the
5558: <a href="#slaved-media-elements">slaved media elements</a> of a <code><a href="#mediacontroller">MediaController</a></code>
5559: must use the same clock for their definition of their <a href="#media-timeline">media
5560: timeline</a>'s unit time.</p>
5561:
5562: <hr><p>The <dfn id="dom-media-controller" title="dom-media-controller"><code>controller</code></dfn> attribute
5563: on a <a href="#media-element">media element</a>, on getting, must return the
5564: element's <a href="#current-media-controller">current media controller</a>, if any, or null
5565: 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,
5566: and then set the <a href="#current-media-controller">current media controller</a> to the given
5567: value. If the given value is null, the element no longer has a
5568: <a href="#current-media-controller">current media controller</a>; if it is not null, then the
5569: 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
5570: new media controller</a>.</p>
5571:
5572: <hr><p>The <dfn id="dom-mediacontroller" title="dom-MediaController"><code>MediaController()</code></dfn>
5573: constructor, when invoked, must return a newly created
5574: <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5575:
5576: <hr><p>The <dfn id="dom-mediacontroller-seekable" title="dom-MediaController-seekable"><code>seekable</code></dfn>
5577: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5578: <code>TimeRanges</code> object</a> that represents the
5579: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5580: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5581: user agent is able to seek to, at the time the attribute is
5582: evaluated.</p>
5583:
5584: <p>The <dfn id="dom-mediacontroller-buffered" title="dom-MediaController-buffered"><code>buffered</code></dfn>
5585: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5586: <code>TimeRanges</code> object</a> that represents the
5587: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5588: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5589: user agent has buffered, at the time the attribute is evaluated.
5590: Users agents must accurately determine the ranges available, even
5591: for media streams where this can only be determined by tedious
5592: inspection.</p>
5593:
5594: <p>The <dfn id="dom-mediacontroller-duration" title="dom-MediaController-duration"><code>duration</code></dfn>
5595: attribute must return the <a href="#media-controller-duration">media controller
5596: duration</a>.</p>
5597:
5598: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5599: <a href="#media-controller-duration">media controller duration</a> changes, whichever happens
5600: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5601: <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>
5602: at the <code><a href="#mediacontroller">MediaController</a></code>. If the
5603: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-duration">media controller
5604: duration</a> decreases such that the <a href="#media-controller-position">media controller
5605: position</a> is greater than the <a href="#media-controller-duration">media controller
5606: duration</a>, the user agent must immediately <a href="#seek-the-media-controller">seek the
5607: media controller</a> to <a href="#media-controller-duration">media controller
5608: duration</a>.</p>
5609:
5610: <p>The <dfn id="dom-mediacontroller-currenttime" title="dom-MediaController-currentTime"><code>currentTime</code></dfn>
5611: attribute must return the <a href="#media-controller-position">media controller position</a> on
5612: getting, and on setting must <a href="#seek-the-media-controller">seek the media controller</a>
5613: to the new value.</p>
5614:
5615: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5616: <a href="#media-controller-position">media controller position</a> changes, whichever happens
5617: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5618: <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
5619: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5620:
5621: <hr><p>When a <code><a href="#mediacontroller">MediaController</a></code> is created it is a
5622: <dfn id="playing-media-controller">playing media controller</dfn>. It can be changed into a
5623: <dfn id="paused-media-controller">paused media controller</dfn> and back either via the user
5624: agent's user interface (when the element is <a href="#expose-a-user-interface-to-the-user" title="expose a
5625: user interface to the user">exposing a user interface to the
5626: user</a>) or by script using the APIs defined in this section
5627: (see below).</p>
5628:
5629: <p>The <dfn id="dom-mediacontroller-paused" title="dom-MediaController-paused"><code>paused</code></dfn>
5630: attribute must return true if the <code><a href="#mediacontroller">MediaController</a></code>
5631: object is a <a href="#paused-media-controller">paused media controller</a>, and false
5632: otherwise.</p>
5633:
5634: <p>The <dfn id="dom-mediacontroller-played" title="dom-MediaController-played"><code>played</code></dfn>
5635: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5636: <code>TimeRanges</code> object</a> that represents the union of
5637: the ranges of the <a href="#media-resource" title="media resource">media
5638: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5639: user agent has so far rendered, at the time the attribute is
5640: evaluated.</p>
5641:
5642: <p>When the <dfn id="dom-mediacontroller-pause" title="dom-MediaController-pause"><code>pause()</code></dfn> method
5643: is invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#playing-media-controller">playing
5644: media controller</a> then the user agent must change the
5645: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#paused-media-controller">paused media
5646: 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
5647: event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
5648: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
5649: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5650:
5651: <p>When the <dfn id="dom-mediacontroller-play" title="dom-MediaController-play"><code>play()</code></dfn> method is
5652: invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#paused-media-controller">paused media
5653: controller</a>, the user agent must change the
5654: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#playing-media-controller">playing media
5655: 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
5656: event</a> named <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code> at the
5657: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
5658: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5659:
5660: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-default-playback-rate">media controller
5661: default playback rate</dfn> and a <dfn id="media-controller-playback-rate">media controller playback
5662: rate</dfn>, which must both be set to 1.0 when the
5663: <code><a href="#mediacontroller">MediaController</a></code> object is created.</p>
5664:
5665: <p>The <dfn id="dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
5666: attribute, on getting, must return the
5667: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
5668: playback rate</a>, and on setting, must set the
5669: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
5670: playback rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a
5671: 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
5672: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5673:
5674: <p>The <dfn id="dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate"><code>playbackRate</code></dfn>
5675: attribute, on getting, must return the
5676: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
5677: rate</a>, and on setting, must set the
5678: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
5679: rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a task</a> to
5680: <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
5681: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5682:
5683: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-volume-multiplier">media controller volume
5684: multiplier</dfn>, which must be set to 1.0 when the
5685: <code><a href="#mediacontroller">MediaController</a></code> object is created, and a <dfn id="media-controller-mute-override">media
5686: controller mute override</dfn>, much must initially be false.</p>
5687:
5688: <p>The <dfn id="dom-mediacontroller-volume" title="dom-MediaController-volume"><code>volume</code></dfn>
5689: attribute, on getting, must return the
5690: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-volume-multiplier">media controller volume
5691: multiplier</a>, and on setting, if the new value is in the range
5692: 0.0 to 1.0 inclusive, must set the <code><a href="#mediacontroller">MediaController</a></code>'s
5693: <a href="#media-controller-volume-multiplier">media controller volume multiplier</a> to the new value and
5694: <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
5695: <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
5696: at the <code><a href="#mediacontroller">MediaController</a></code>. If the new value is outside the
5697: range 0.0 to 1.0 inclusive, then, on setting, an
5698: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
5699:
5700: <p>The <dfn id="dom-mediacontroller-muted" title="dom-MediaController-muted"><code>muted</code></dfn>
5701: attribute, on getting, must return the
5702: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
5703: override</a>, and on setting, must set the
5704: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
5705: override</a> to the new value and <a href="webappapis.html#queue-a-task">queue a task</a> to
5706: <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
5707: the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5708:
5709: <hr><p>The <a href="#media-resource" title="media resource">media resources</a> of all
5710: the <a href="#slaved-media-elements">slaved media elements</a> of a
5711: <code><a href="#mediacontroller">MediaController</a></code> have a defined temporal relationship
5712: which provides relative offsets between the zero time of each such
5713: <a href="#media-resource">media resource</a>: for <a href="#media-resource" title="media resource">media
5714: resources</a> with a <a href="#timeline-offset">timeline offset</a>, their relative
5715: offsets are the difference between their <a href="#timeline-offset">timeline
5716: offset</a>; the zero times of all the <a href="#media-resource" title="media
5717: resource">media resources</a> without a <a href="#timeline-offset">timeline
5718: offset</a> are not offset from each other (i.e. the origins of
5719: their timelines are cotemporal); and finally, the zero time of the
5720: <a href="#media-resource">media resource</a> with the earliest <a href="#timeline-offset">timeline
5721: offset</a> (if any) is not offset from the zero times of the
5722: <a href="#media-resource" title="media resource">media resources</a> without a
5723: <a href="#timeline-offset">timeline offset</a> (i.e. the origins of <a href="#media-resource" title="media
5724: resource">media resources</a> without a <a href="#timeline-offset">timeline
5725: offset</a> are further cotemporal with the earliest defined point
5726: on the timeline of the <a href="#media-resource">media resource</a> with the earliest
5727: <a href="#timeline-offset">timeline offset</a>).</p>
5728:
5729: <p>The <dfn id="media-resource-end-position">media resource end position</dfn> of a <a href="#media-resource">media
5730: resource</a> in a <a href="#media-element">media element</a> is defined as
5731: follows: if the <a href="#media-resource">media resource</a> has a finite and known
5732: duration, the <a href="#media-resource-end-position">media resource end position</a> is the
5733: duration of the <a href="#media-resource">media resource</a>'s timeline (the last
5734: defined position on that timeline); otherwise, the <a href="#media-resource">media
5735: resource</a>'s duration is infinite or unknown, and the
5736: <a href="#media-resource-end-position">media resource end position</a> is the time of the last
5737: frame of <a href="#media-data">media data</a> currently available for that
5738: <a href="#media-resource">media resource</a>.</p>
5739:
5740: <p>Each <code><a href="#mediacontroller">MediaController</a></code> also has its own defined
5741: timeline. On this timeline, all the <a href="#media-resource" title="media
5742: resource">media resources</a> of all the <a href="#slaved-media-elements">slaved media
5743: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code> are temporally
5744: aligned according to their defined offsets. The <dfn id="media-controller-duration">media
5745: controller duration</dfn> of that <code><a href="#mediacontroller">MediaController</a></code> is
5746: the time from the earliest <a href="#earliest-possible-position">earliest possible position</a>,
5747: relative to this <code><a href="#mediacontroller">MediaController</a></code> timeline, of any of
5748: the <a href="#media-resource" title="media resource">media resources</a> of the
5749: <a href="#slaved-media-elements">slaved media elements</a> of the
5750: <code><a href="#mediacontroller">MediaController</a></code>, to the time of the latest <a href="#media-resource-end-position">media
5751: resource end position</a> of the <a href="#media-resource" title="media
5752: resource">media resources</a> of the <a href="#slaved-media-elements">slaved media
5753: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code>, again relative
5754: to this <code><a href="#mediacontroller">MediaController</a></code> timeline.</p>
5755:
5756: <p>Each <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-position">media controller
5757: position</dfn>. This is the time on the
5758: <code><a href="#mediacontroller">MediaController</a></code>'s timeline at which the user agent is
5759: trying to play the <a href="#slaved-media-elements">slaved media elements</a>. When a
5760: <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#media-controller-position">media controller
5761: position</a> is initially zero.</p>
5762:
5763: <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
5764: to speed with its new media controller">bring a media element up to
5765: 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>
5766: to the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-position">media controller
5767: position</a> relative to the <a href="#media-element">media element</a>'s
5768: timeline, discarding any resulting exceptions.</p>
5769:
5770: <p>When the user agent is to <dfn id="seek-the-media-controller">seek the media controller</dfn> to
5771: a particular <var title="">new playback position</var>, it must
5772: follow these steps:</p>
5773:
5774: <ol><li><p>If the <var title="">new playback position</var> is less
5775: than zero, then set it to zero.</p></li>
5776:
5777: <li><p>If the <var title="">new playback position</var> is greater
5778: than the <a href="#media-controller-duration">media controller duration</a>, then set it to the
5779: <a href="#media-controller-duration">media controller duration</a>.</p></li>
5780:
5781: <li><p>Set the <a href="#media-controller-position">media controller position</a> to the <var title="">new playback position</var>.</p></li>
5782:
5783: <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
5784: <var title="">new playback position</var> relative to the
5785: <a href="#media-element">media element</a> timeline, discarding any resulting
5786: exceptions.</p></li>
5787: </ol><p>A <code><a href="#mediacontroller">MediaController</a></code> is a <dfn id="blocked-media-controller">blocked media
5788: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
5789: <a href="#paused-media-controller">paused media controller</a>, or if any of its <a href="#slaved-media-elements">slaved
5790: media elements</a> are <a href="#blocked-media-element" title="blocked media
5791: element">blocked media elements</a>, or if any of its
5792: <a href="#slaved-media-elements">slaved media elements</a> whose <a href="#autoplaying-flag">autoplaying
5793: flag</a> is true still have a <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute that is true, or if
5794: 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>
5795:
5796: <p>A <a href="#media-element">media element</a> is <dfn id="blocked-on-its-media-controller">blocked on its media
5797: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
5798: <a href="#blocked-media-controller">blocked media controller</a>, or if its <a href="#media-controller-position">media
5799: controller position</a> is either before the <a href="#media-resource">media
5800: resource</a>'s <a href="#earliest-possible-position">earliest possible position</a> relative
5801: to the <code><a href="#mediacontroller">MediaController</a></code>'s timeline or after the end of
5802: the <a href="#media-resource">media resource</a> relative to the
5803: <code><a href="#mediacontroller">MediaController</a></code>'s timeline.</p>
5804:
5805: <p id="controller-playback">When a <code><a href="#mediacontroller">MediaController</a></code> is
5806: not a <a href="#blocked-media-controller">blocked media controller</a> and it has at least one
5807: <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a>
5808: whose <code><a href="infrastructure.html#document">Document</a></code> is a <a href="browsers.html#fully-active">fully active</a>
5809: <code><a href="infrastructure.html#document">Document</a></code>, the <code><a href="#mediacontroller">MediaController</a></code>'s
5810: <a href="#media-controller-position">media controller position</a> must increase monotonically
5811: at <a href="#media-controller-playback-rate">media controller playback rate</a> units of time on the
5812: <code><a href="#mediacontroller">MediaController</a></code>'s timeline per unit time of the clock
5813: used by its <a href="#slaved-media-elements">slaved media elements</a>.</p>
5814:
5815: <p>When the zero point on the timeline of a
5816: <code><a href="#mediacontroller">MediaController</a></code> moves relative to the timelines of the
5817: <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
5818: <a href="#media-controller-position">media controller position</a> must be decremented by <var title="">ΔT</var>.</p>
5819:
5820: <p class="note">In some situations, e.g. when playing back a live
5821: stream without buffering anything, the <a href="#media-controller-position">media controller
5822: position</a> would increase motonically as described above at the
5823: same rate as the <var title="">ΔT</var> described in the
5824: previous paragraph decreases it, with the end result that for all
5825: intents and purposes, the <a href="#media-controller-position">media controller position</a>
5826: would appear to remain constant (probably with the value 0).</p>
5827:
5828: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="most-recently-reported-readiness-state">most recently reported
5829: readiness state</dfn>, which is a number from 0 to 4 derived from
5830: the numbers used for the <a href="#media-element">media element</a> <code title="attr-media-readyState">readyState</code> attribute, and a
5831: <dfn id="most-recently-reported-playback-state">most recently reported playback state</dfn>, which is either
5832: <i>playing</i>, <i>waiting</i>, or <i>ended</i>.</p>
5833:
5834: <p>When a <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#most-recently-reported-readiness-state">most
5835: recently reported readiness state</a> must be set to 0, and its
5836: <a href="#most-recently-reported-playback-state">most recently reported playback state</a> must be set to
5837: <i>waiting</i>.</p>
5838:
5839: <p>When a user agent is required to <dfn id="report-the-controller-state">report the controller
5840: state</dfn> for a <code><a href="#mediacontroller">MediaController</a></code>, the user agent must
5841: run the following steps:</p>
5842:
5843: <ol><li>
5844:
5845: <p>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved media
5846: elements</a>, let <var title="">new readiness state</var> be
5847: 0.</p>
5848:
5849: <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
5850: all of its <a href="#slaved-media-elements">slaved media elements</a>.</p>
5851:
5852: </li>
5853:
5854: <li>
5855:
5856: <p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
5857: reported readiness state</a> is not equal to <var title="">new
5858: 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
5859: a simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
5860: whose name is the event name corresponding to the value of <var title="">new readiness state</var> given in the table below:</p>
5861:
5862:
5863: <table><thead><tr><th>Value of <var title="">new readiness state</var>
5864: </th><th>Event name
5865:
5866: </th></tr></thead><tbody><tr><td> 0
5867: </td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
5868:
5869: </td></tr><tr><td> 1
5870: </td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
5871:
5872: </td></tr><tr><td> 2
5873: </td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
5874:
5875: </td></tr><tr><td> 3
5876: </td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
5877:
5878: </td></tr><tr><td> 4
5879: </td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
5880:
5881: </td></tr></tbody></table></li>
5882:
5883: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
5884: reported readiness state</a> be <var title="">new readiness
5885: state</var>.</p></li>
5886:
5887: <li>
5888:
5889: <p>Initialize <var title="">new playback state</var> by setting it
5890: to the state given for the first matching condition from the
5891: following list:</p>
5892:
5893: <dl class="switch"><dt>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved
5894: media elements</a></dt>
5895:
5896: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
5897:
5898: <dt>If all of the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#slaved-media-elements">slaved
5899: media elements</a> have <a href="#ended-playback">ended playback</a> and the
5900: <a href="#media-controller-playback-rate">media controller playback rate</a> is positive or
5901: zero</dt>
5902:
5903: <dd>Let <var title="">new playback state</var> be <i>ended</i>.</dd>
5904:
5905: <dt>If the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#blocked-media-controller">blocked media
5906: controller</a></dt>
5907:
5908: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
5909:
5910: <dt>Otherwise</dt>
5911:
5912: <dd>Let <var title="">new playback state</var> be <i>playing</i>.</dd>
5913:
5914: </dl></li>
5915:
5916: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
5917: reported playback state</a> is not equal to <var title="">new
5918: 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
5919: simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
5920: 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">ended</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>
5921: otherwise.</p></li>
5922:
5923: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
5924: reported playback state</a> be <var title="">new playback
5925: state</var>.</p></li>
5926:
5927: </ol><hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
5928: supported, as IDL attributes, by all objects implementing the
5929: <code><a href="#mediacontroller">MediaController</a></code> interface:</p>
5930:
5931: <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>
5932: </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>
5933: </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>
5934: </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>
5935: </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>
5936: </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>
5937: </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>
5938: </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>
5939: </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>
5940: </td></tr><tr><td><dfn id="handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate"><code>ontimeupdate</code></dfn> </td><td> <code title="event-MediaController-durationchange"><a href="#event-mediacontroller-durationchange">durationchange</a></code>
5941: </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>
5942: </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>
5943: </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>
5944: </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>
5945: </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
5946: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5947:
5948: </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
5949: attribute on <a href="#media-element" title="media element">media elements</a> can
5950: be used to link multiple <a href="#media-element" title="media element">media
5951: elements</a> together by implicitly creating a
5952: <code><a href="#mediacontroller">MediaController</a></code>.</p><div class="impl">
5953:
5954: <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
5955: 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,
5956: changed, or removed, the user agent must run the following
5957: steps:</p>
5958:
5959: <ol><li><p>Let <var title="">m</var> be the <a href="#media-element">media element</a>
5960: in question.</p></li>
5961:
5962: <li><p>Let <var title="">m</var> have no <a href="#current-media-controller">current
5963: media controller</a>, if it currently has one.</p></li>
5964:
5965: <li><p>If <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is being
5966: removed, then abort these steps.</p></li>
5967:
5968: <li>
5969:
5970: <p>If there is another <a href="#media-element">media element</a> whose
5971: <code><a href="infrastructure.html#document">Document</a></code> is the same as <var title="">m</var>'s
5972: <code><a href="infrastructure.html#document">Document</a></code> (even if one or both of these elements are
5973: not actually <a href="infrastructure.html#in-a-document" title="in a Document"><em>in</em> the
5974: <code>Document</code></a>), and which also has a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and
5975: whose <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>
5976: 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
5977: let <var title="">controller</var> be that <a href="#media-element">media
5978: element</a>'s <a href="#current-media-controller">current media controller</a>.</p>
5979:
5980: <p>Otherwise, let <var title="">controller</var> be a newly created
5981: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5982:
5983: </li>
5984:
5985: <li><p>Let <var title="">m</var>'s <a href="#current-media-controller">current media
5986: controller</a> be <var title="">controller</var>.</p></li>
5987:
5988: <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
5989: controller</a>.</p></li>
5990:
5991: </ol><p>The <dfn id="dom-media-mediagroup" title="dom-media-mediaGroup"><code>mediaGroup</code></dfn> IDL
5992: attribute on <a href="#media-element" title="media element">media elements</a> must
5993: <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content
5994: attribute.</p>
5995:
5996: </div><div class="example">
5997:
5998: <p>Multiple <a href="#media-element" title="media element">media elements</a>
5999: referencing the same <a href="#media-resource">media resource</a> will share a
6000: single network request. This can be used to efficiently play two
6001: (video) tracks from the same <a href="#media-resource">media resource</a> in two
6002: different places on the screen. Used with the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, these
6003: elements can also be kept synchronised.</p>
6004:
6005: <p>In this example, a sign-languge interpreter track from a movie
6006: file is overlaid on the primary video track of that same video file
6007: using two <code><a href="#the-video-element">video</a></code> elements, some CSS, and an implicit
6008: <code><a href="#mediacontroller">MediaController</a></code>:</p>
6009:
6010: <pre><article>
6011: <style scoped>
6012: div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
6013: video { position; absolute; bottom: 0; right: 0; }
6014: video:first-child { width: 100%; height: 100%; }
6015: video:last-child { width: 30%; }
6016: </style>
6017: <div>
6018: <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
6019: <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
6020: </div>
6021: </article></pre>
6022:
6023: </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
6024: 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
6025: to <code><a href="#the-track-element">track</a></code> element children of the <a href="#media-element">media
6026: element</a>, in <a href="infrastructure.html#tree-order">tree order</a>.</li>
6027:
6028: <li>Any <a href="#text-track" title="text track">text tracks</a> added using
6029: the <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack()</a></code> method, in
6030: the order they were added, oldest first.</li>
6031:
6032: <li>Any <a href="#media-resource-specific-text-track" title="media-resource-specific text
6033: track">media-resource-specific text tracks</a> (<a href="#text-track" title="text track">text tracks</a> corresponding to data in
6034: the <a href="#media-resource">media resource</a>), in the order defined by the
6035: <a href="#media-resource">media resource</a>'s format specification.</li>
6036:
6037: </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>
6038:
6039: </dt><dd>
6040:
6041: <p>This decides how the track is handled by the user agent. The
6042: kind is represented by a string. The possible strings are:</p>
6043:
6044: <ul class="brief"><li><dfn id="dom-texttrack-kind-subtitles" title="dom-TextTrack-kind-subtitles"><code>subtitles</code></dfn>
6045: </li><li><dfn id="dom-texttrack-kind-captions" title="dom-TextTrack-kind-captions"><code>captions</code></dfn>
6046: </li><li><dfn id="dom-texttrack-kind-descriptions" title="dom-TextTrack-kind-descriptions"><code>descriptions</code></dfn>
6047: </li><li><dfn id="dom-texttrack-kind-chapters" title="dom-TextTrack-kind-chapters"><code>chapters</code></dfn>
6048: </li><li><dfn id="dom-texttrack-kind-metadata" title="dom-TextTrack-kind-metadata"><code>metadata</code></dfn>
6049: </li></ul><p>The <a href="#text-track-kind" title="text track kind">kind of track</a> can
6050: change dynamically, in the case of a <a href="#text-track">text track</a>
6051: corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6052:
6053: </dd>
6054:
6055: <dt><dfn id="text-track-label" title="text track label">A label</dfn>
6056:
6057: </dt><dd>
6058:
6059: <p>This is a human-readable string intended to identify the track
6060: for the user. In certain cases, the label might be generated
6061: automatically.</p>
6062:
6063: <p>The <a href="#text-track-label" title="text track label">label of a track</a> can
6064: change dynamically, in the case of a <a href="#text-track">text track</a>
6065: corresponding to a <code><a href="#the-track-element">track</a></code> element or in the case of an
6066: automatically-generated label whose value depends on variable
6067: factors such as the user's preferred user interface language.</p>
6068:
6069: </dd>
6070:
6071: <dt><dfn id="text-track-language" title="text track language">A language</dfn>
6072:
6073: </dt><dd>
6074:
6075: <p>This is a string (a BCP 47 language tag) representing the
6076: language of the text track's cues. <a href="references.html#refsBCP47">[BCP47]</a></p>
6077:
6078: <p>The <a href="#text-track-language" title="text track language">language of a text
6079: track</a> can change dynamically, in the case of a <a href="#text-track">text
6080: track</a> corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6081:
6082: </dd>
6083:
6084: <dt><dfn id="text-track-readiness-state" title="text track readiness state">A readiness state</dfn>
6085:
6086: </dt><dd>
6087:
6088: <p>One of the following:</p>
6089:
6090: <dl><dt><dfn id="text-track-not-loaded" title="text track not loaded">Not loaded</dfn>
6091:
6092: </dt><dd>
6093:
6094: <p>Indicates that the text track is known to exist (e.g. it has
6095: been declared with a <code><a href="#the-track-element">track</a></code> element), but its cues
6096: have not been obtained.</p>
6097:
6098: </dd>
6099:
6100: <dt><dfn id="text-track-loading" title="text track loading">Loading</dfn>
6101:
6102: </dt><dd>
6103:
6104: <p>Indicates that the text track is loading and there have been
6105: no fatal errors encountered so far. Further cues might still be
6106: added to the track.</p>
6107:
6108: </dd>
6109:
6110: <dt><dfn id="text-track-loaded" title="text track loaded">Loaded</dfn>
6111:
6112: </dt><dd>
6113:
6114: <p>Indicates that the text track has been loaded with no fatal
6115: errors. No new cues will be added to the track except if the
6116: <a href="#text-track">text track</a> corresponds to a
6117: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object.</p>
6118:
6119: </dd>
6120:
6121: <dt><dfn id="text-track-failed-to-load" title="text track failed to load">Failed to load</dfn>
6122:
6123: </dt><dd>
6124:
6125: <p>Indicates that the text track was enabled, but when the user
6126: agent attempted to obtain it, this failed in some way
6127: (e.g. <a href="urls.html#url">URL</a> could not be <a href="urls.html#resolve-a-url" title="resolve a
6128: url">resolved</a>, network error, unknown text track
6129: format). Some or all of the cues are likely missing and will not
6130: be obtained.</p>
6131:
6132: </dd>
6133:
6134: </dl><p>The <a href="#text-track-readiness-state" title="text track readiness state">readiness
6135: state</a> of a <a href="#text-track">text track</a> changes dynamically as
6136: the track is obtained.</p>
6137:
6138: </dd>
6139:
6140: <dt><dfn id="text-track-mode" title="text track mode">A mode</dfn>
6141:
6142: </dt><dd>
6143:
6144: <p>One of the following:</p>
6145:
6146: <dl><dt><dfn id="text-track-disabled" title="text track disabled">Disabled</dfn>
6147:
6148: </dt><dd>
6149:
6150: <p>Indicates that the text track is not active. Other than for
6151: the purposes of exposing the track in the DOM, the user agent is
6152: ignoring the text track. No cues are active, no events are
6153: fired, and the user agent will not attempt to obtain the track's
6154: cues.</p>
6155:
6156: </dd>
6157:
6158: <dt><dfn id="text-track-hidden" title="text track hidden">Hidden</dfn>
6159:
6160: </dt><dd>
6161:
6162: <p>Indicates that the text track is active, but that the user
6163: agent is not actively displaying the cues. If no attempt has yet
6164: been made to obtain the track's cues, the user agent will
6165: perform such an attempt momentarily. The user agent is
6166: maintaining a list of which cues are active, and events are
6167: being fired accordingly.</p>
6168:
6169: </dd>
6170:
6171: <dt><dfn id="text-track-showing" title="text track showing">Showing</dfn>
6172: <dt><dfn id="text-track-showing-by-default" title="text track showing by default">Showing by default</dfn>
6173:
6174: </dt></dt><dd>
6175:
6176: <p>Indicates that the text track is active. If no attempt has
6177: yet been made to obtain the track's cues, the user agent will
6178: perform such an attempt momentarily. The user agent is
6179: maintaining a list of which cues are active, and events are
6180: being fired accordingly. In addition, for text tracks whose
6181: <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
6182: are being displayed over the video as appropriate; for text
6183: tracks whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-descriptions">descriptions</code>,
6184: the user agent is making the cues available to the user in a
6185: non-visual fashion; and for text tracks whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-chapters">chapters</code>, the user
6186: agent is making available to the user a mechanism by which the
6187: user can navigate to any point in the <a href="#media-resource">media
6188: resource</a> by selecting a cue.</p>
6189:
6190: <p>The <a href="#text-track-showing-by-default" title="text track showing by default">showing by
6191: default</a> state is used in conjunction with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute on
6192: <code><a href="#the-track-element">track</a></code> elements to indicate that the text track was
6193: enabled due to that attribute. This allows the user agent to
6194: override the state if a later track is discovered that is more
6195: appropriate per the user's preferences.</p>
6196:
6197: </dd>
6198:
6199: </dl></dd>
6200:
6201: <dt><dfn id="text-track-list-of-cues" title="text track list of cues">A list of zero or more cues</dfn>
6202:
6203: </dt><dd>
6204:
6205: <p>A list of <a href="#text-track-cue" title="text track cue">text track
6206: cues</a>, along with <dfn id="rules-for-updating-the-text-track-rendering">rules for updating the text track
6207: rendering</dfn>.
6208: </p>
6209:
6210: <p>The <a href="#text-track-list-of-cues" title="text track list of cues">list of cues of a
6211: text track</a> can change dynamically, either because the
6212: <a href="#text-track">text track</a> has <a href="#text-track-not-loaded" title="text track not
6213: loaded">not yet been loaded</a> or is still <a href="#text-track-loading" title="text
6214: track loading">loading</a>, or because the <a href="#text-track">text
6215: track</a> corresponds to a <code><a href="#mutabletexttrack">MutableTextTrack</a></code>
6216: object, whose API allows individual cues can be added or removed
6217: dynamically.</p>
6218:
6219: </dd>
6220:
6221: </dl><p>Each <a href="#text-track">text track</a> has a corresponding
6222: <code><a href="#texttrack">TextTrack</a></code> object.</p><p>The <a href="#text-track" title="text track">text tracks</a> of a
6223: <a href="#media-element">media element</a> are <dfn id="the-text-tracks-are-ready" title="the text tracks are
6224: ready">ready</dfn> if all the <a href="#text-track" title="text track">text
6225: tracks</a> whose <a href="#text-track-mode" title="text track mode">mode</a> was
6226: not in the <a href="#text-track-disabled" title="text track disabled">disabled</a> state
6227: when the element's <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
6228: algorithm</a> last started now have a <a href="#text-track-readiness-state">text track readiness
6229: state</a> of <a href="#text-track-loaded" title="text track loaded">loaded</a> or
6230: <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
6231: in a <a href="#text-track">text track</a>, corresponding for instance for
6232: subtitles and captions to the text that appears at a particular time
6233: 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>
6234: </dt><dd>
6235: <p>An arbitrary string.</p>
6236: </dd>
6237:
6238: <dt><dfn id="text-track-cue-start-time" title="text track cue start time">A start time</dfn>
6239: </dt><dd>
6240: <p>A time, in seconds and fractions of a second, at which the cue
6241: becomes relevant.</p>
6242: </dd>
6243:
6244: <dt><dfn id="text-track-cue-end-time" title="text track cue end time">An end time</dfn>
6245: </dt><dd>
6246: <p>A time, in seconds and fractions of a second, at which the cue
6247: stops being relevant.</p>
6248: </dd>
6249:
6250: <dt><dfn id="text-track-cue-pause-on-exit-flag" title="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
6251: </dt><dd>
6252: <p>A boolean indicating whether playback of the <a href="#media-resource">media
6253: resource</a> is to pause when the cue stops being relevant.</p>
6254: </dd>
6255:
6256: <dt><dfn id="text-track-cue-writing-direction" title="text track cue writing direction">A writing direction</dfn>
6257: </dt><dd>
6258: <p>A writing direction, either <dfn id="text-track-cue-horizontal-writing-direction" title="text track cue
6259: horizontal writing direction">horizontal</dfn> (a line extends
6260: horizontally and is positioned vertically, with consecutive lines
6261: displayed below each other), <dfn id="text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical
6262: growing left writing direction">vertical growing left</dfn> (a
6263: line extends vertically and is positioned horizontally, with
6264: 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
6265: growing right writing direction">vertical growing right</dfn> (a
6266: line extends vertically and is positioned horizontally, with
6267: consecutive lines displayed to the right of each other).</p>
6268:
6269:
6270: </dd>
6271:
6272:
6273: <dt><dfn id="text-track-cue-size" title="text track cue size">A size</dfn>
6274: </dt><dd>
6275: <p>A number giving the size of the box within which the text of
6276: each line of the cue is to be aligned, to be interpreted as a
6277: percentage of the video, as defined by the <a href="#text-track-cue-writing-direction" title="text
6278: track cue writing direction">writing direction</a>.</p>
6279: </dd>
6280:
6281:
6282: <dt><dfn id="text-track-cue-text" title="text track cue text">The text of the cue</dfn>
6283: </dt><dd>
6284: <p>The raw text of the cue, and rules for its interpretation,
6285: allowing the text to be rendered and converted to a DOM fragment.</p>
6286: </dd>
6287:
6288: </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
6289: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and can be associated with a
6290: particular <a href="#text-track">text track</a>. Once a <a href="#text-track-cue">text track
6291: cue</a> is associated with a particular <a href="#text-track">text track</a>,
6292: the association is permanent.</p><p>In addition, each <a href="#text-track-cue">text track cue</a> has two pieces of
6293: dynamic information:</p><dl><dt>The <dfn id="text-track-cue-active-flag" title="text track cue active flag">active flag</dfn>
6294: </dt><dd>
6295:
6296: <p>This flag must be initially unset. The flag is used to ensure
6297: events are fired appropriately when the cue becomes active or
6298: inactive, and to make sure the right cues are rendered.</p>
6299:
6300: <p>The user agent must synchronously unset this flag whenever the
6301: <a href="#text-track-cue">text track cue</a> is removed from its <a href="#text-track">text
6302: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>; whenever the
6303: <a href="#text-track">text track</a> itself is removed from its <a href="#media-element">media
6304: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> or has its
6305: <a href="#text-track-mode">text track mode</a> changed to <a href="#text-track-disabled" title="text track
6306: disabled">disabled</a>; and whenever the <a href="#media-element">media
6307: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is changed back to
6308: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>. When the
6309: 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
6310: track showing by default">showing by default</a> prior to the
6311: relevant incident, the user agent must, after having unset the
6312: flag for all the affected cues, apply the <a href="#rules-for-updating-the-text-track-rendering">rules for updating
6313: the text track rendering</a> of those <a href="#text-track" title="text
6314: track">text tracks</a>.
6315: </p></dd>
6316:
6317: <dt>The <dfn id="text-track-cue-display-state" title="text track cue display state">display state</dfn>
6318: </dt><dd>
6319:
6320: <p>This is used as part of the rendering model, to keep cues in a
6321: consistent position. It must initially be empty. Whenever the
6322: <a href="#text-track-cue-active-flag">text track cue active flag</a> is unset, the user agent
6323: must empty the <a href="#text-track-cue-display-state">text track cue display state</a>.</p>
6324:
6325: </dd>
6326:
6327: </dl><p>The <a href="#text-track-cue" title="text track cue">text track cues</a> of a
6328: <a href="#media-element">media element</a>'s <a href="#text-track" title="text track">text
6329: tracks</a> are ordered relative to each other in the <dfn id="text-track-cue-order">text
6330: track cue order</dfn>, which is determined as follows: first group
6331: the <a href="#text-track-cue" title="text track cue">cues</a> by their <a href="#text-track">text
6332: track</a>, with the groups being sorted in the same order as
6333: their <a href="#text-track" title="text track">text tracks</a> appear in the
6334: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>;
6335: then, within each group, <a href="#text-track-cue" title="text track cue">cues</a>
6336: must be sorted by their <a href="#text-track-cue-start-time" title="text track cue start
6337: 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
6338: track cue start time">start time</a> must be sorted by their
6339: <a href="#text-track-cue-end-time" title="text track cue end time">end time</a>, earliest
6340: first; and finally, any <a href="#text-track-cue" title="text track cue">cues</a>
6341: with identical <a href="#text-track-cue-end-time" title="text track cue end time">end
6342: times</a> must be sorted in the order they were created (so
6343: e.g. for cues from a <span>WebVTT</span> file, that would be the
6344: 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
6345: track</a> that corresponds to data found in the <a href="#media-resource">media
6346: resource</a>.</p><div class="impl">
6347:
6348: <p>Rules for processing and rendering such data are defined by the
6349: relevant specifications, e.g. the specification of the video format
6350: if the <a href="#media-resource">media resource</a> is a video.</p>
6351:
6352: <p>When a <a href="#media-resource">media resource</a> contains data that the user
6353: agent recognises and supports as being equivalent to a <a href="#text-track">text
6354: track</a>, the user agent <a href="#found-a-media-resource-specific-timed-track">runs</a> the
6355: <dfn id="steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text track</dfn>
6356: with the relevant data, as follows:</p>
6357:
6358: <ol><li><p>Associate the relevant data with a new <a href="#text-track">text
6359: track</a> and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6360: object. The <a href="#text-track">text track</a> is a
6361: <a href="#media-resource-specific-text-track">media-resource-specific text track</a>.</p></li>
6362:
6363: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-kind" title="text track
6364: kind">kind</a>, <a href="#text-track-label" title="text track label">label</a>,
6365: and <a href="#text-track-language" title="text track language">language</a> based on the
6366: semantics of the relevant data, as defined by the relevant
6367: specification.</p></li>
6368:
6369: <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
6370: parsed so far, folllowing the <span>guidelines for exposing
6371: cues</span>, and begin updating it dynamically as
6372: necessary.</p></li>
6373:
6374: <li>
6375:
6376: <p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-readiness-state" title="text track
6377: readiness state">readiness state</a> to the value that most
6378: correctly describes the current state, and begin updating it
6379: dynamically as necessary.</p>
6380:
6381: <p class="example">For example, if the relevant data in the
6382: <a href="#media-resource">media resource</a> has been fully parsed and completely
6383: describes the cues, then the <a href="#text-track">text track</a> would be
6384: <a href="#text-track-loaded" title="text track loaded">loaded</a>. On the other hand,
6385: if the data for the cues is interleaved with the <a href="#media-data">media
6386: data</a>, and the <a href="#media-resource">media resource</a> as a whole is
6387: still being downloaded, then the <a href="#text-track-loading" title="text track
6388: loading">loading</a> state might be more accurate.</p>
6389:
6390: </li>
6391:
6392: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-mode" title="text
6393: track mode">mode</a> to the mode consistent with the user's
6394: preferences and the requirements of the relevant specification for
6395: the data.</p></li>
6396:
6397: <li><p>Leave the <a href="#text-track-list-of-cues">text track list of cues</a> empty, and
6398: associate with it the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
6399: rendering</a> appropriate for the format in question.</p>
6400:
6401: </li><li><p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6402: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p></li>
6403:
6404: </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
6405: element's media-resource-specific text tracks</dfn>, the user
6406: agent must remove from the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list
6407: of text tracks</a> all the <a href="#media-resource-specific-text-track" title="media-resource-specific
6408: text track">media-resource-specific text tracks</a>.</p>
6409:
6410: </div><div class="impl">
6411:
6412: <h6 id="sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</h6>
6413:
6414: <p>When a <code><a href="#the-track-element">track</a></code> element is created, it must be
6415: associated with a new <a href="#text-track">text track</a> (with its value set
6416: as defined below) and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6417: object.</p>
6418:
6419: <p>The <a href="#text-track-kind">text track kind</a> is determined from the state of
6420: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute
6421: according to the following table; for a state given in a cell of the
6422: first column, the <a href="#text-track-kind" title="text track kind">kind</a> is the
6423: string given in the second column:</p>
6424:
6425: <table><thead><tr><th>State
6426: </th><th>String
6427: </th></tr></thead><tbody><tr><td><a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</a>
6428: </td><td><code title="dom-timedtrack-kind-subtitles">subtitles</code>
6429: </td></tr><tr><td><a href="#attr-track-kind-captions" title="attr-track-kind-captions">Captions</a>
6430: </td><td><code title="dom-timedtrack-kind-captions">captions</code>
6431: </td></tr><tr><td><a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</a>
6432: </td><td><code title="dom-timedtrack-kind-descriptions">descriptions</code>
6433: </td></tr><tr><td><a href="#attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</a>
6434: </td><td><code title="dom-timedtrack-kind-chapters">chapters</code>
6435: </td></tr><tr><td><a href="#attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</a>
6436: </td><td><code title="dom-timedtrack-kind-metadata">metadata</code>
6437: </td></tr></tbody></table><p>The <a href="#text-track-label">text track label</a> is the element's <a href="#track-label">track
6438: label</a>.</p>
6439:
6440: <p>The <a href="#text-track-language">text track language</a> is the element's
6441: <a href="#track-language">track language</a>, if any, or the empty string
6442: otherwise.</p>
6443:
6444: <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,
6445: changed, or removed, the <a href="#text-track">text track</a> must update
6446: accordingly, as per the definitions above.</p>
6447:
6448: <p class="note">Changes to the <a href="#track-url">track URL</a> are handled in
6449: the algorithm below.</p>
6450:
6451: <p>The <a href="#text-track-list-of-cues">text track list of cues</a> is initially empty. It
6452: is dynamically modified when the referenced file is parsed.
6453: Associated with the list are the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text
6454: track rendering</a> appropriate for the format in question; for
6455: <span>WebVTT</span>, this is the <a href="rendering.html#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the
6456: display of WebVTT text tracks</a>.</p>
6457:
6458: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6459: the new parent is a <a href="#media-element">media element</a>, then the user agent
6460: must add the <code><a href="#the-track-element">track</a></code> element's corresponding <a href="#text-track">text
6461: track</a> to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
6462: tracks</a>.</p>
6463:
6464: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6465: the old parent was a <a href="#media-element">media element</a>, then the user agent
6466: must remove the <code><a href="#the-track-element">track</a></code> element's corresponding
6467: <a href="#text-track">text track</a> from the <a href="#media-element">media element</a>'s
6468: <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6469:
6470: <p>When a <a href="#text-track">text track</a> corresponding to a
6471: <code><a href="#the-track-element">track</a></code> element is added to a <a href="#media-element">media
6472: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, the user agent
6473: must set the <a href="#text-track-mode">text track mode</a> appropriately, as
6474: determined by the following conditions:</p>
6475:
6476: <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
6477: has indicated an interest in having a track with this <a href="#text-track-kind">text
6478: track kind</a>, <a href="#text-track-language">text track language</a>, and
6479: <a href="#text-track-label">text track label</a> enabled, and there is no other
6480: <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6481: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6482: 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
6483: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6484: showing">showing</a></dt>
6485:
6486: <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
6487: the user has indicated an interest in having text descriptions with
6488: this <a href="#text-track-language">text track language</a> and <a href="#text-track-label">text track
6489: label</a> enabled, and there is no other <a href="#text-track">text
6490: track</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
6491: 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
6492: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6493: showing">showing</a></dt>
6494:
6495: <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
6496: <a href="#text-track-language">text track language</a> is one that the user agent has
6497: reason to believe is appropriate for the user, and there is no
6498: other <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6499: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6500: kind</a> of <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> whose
6501: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6502: showing">showing</a></dt>
6503:
6504: <dd>
6505: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6506: track showing">showing</a>.</p>
6507:
6508: <p>If there is a <a href="#text-track">text track</a> in the <a href="#media-element">media
6509: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6510: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing-by-default" title="text track showing
6511: by default">showing by default</a>, the user agent must
6512: furthermore change <em>that</em> <a href="#text-track">text track</a>'s
6513: <a href="#text-track-mode">text track mode</a> to <a href="#text-track-hidden" title="text track
6514: hidden">hidden</a>.</p>
6515: </dd>
6516:
6517: <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
6518: there is no other <a href="#text-track">text track</a> in the <a href="#media-element">media
6519: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6520: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6521: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track
6522: showing by default">showing by default</a></dt>
6523:
6524: <dd>
6525: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing-by-default" title="text
6526: track showing by default">showing by default</a>.</p>
6527: </dd>
6528:
6529: <dt>Otherwise</dt>
6530:
6531: <dd>
6532: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-disabled" title="text
6533: track disabled">disabled</a>.</p>
6534: </dd>
6535:
6536: </dl><p>When a <a href="#text-track">text track</a> corresponding to a
6537: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6538: mode</a> set to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6539: <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>,
6540: and when a <a href="#text-track">text track</a> corresponding to a
6541: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6542: mode</a> set to <a href="#text-track-disabled" title="text track
6543: disabled">disabled</a> and subsequently changes its <a href="#text-track-mode">text
6544: track mode</a> to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6545: <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
6546: the first time, the user agent must immediately and synchronously
6547: run the following algorithm. This algorithm interacts closely with
6548: the <a href="webappapis.html#event-loop">event loop</a> mechanism; in particular, it has a
6549: <a href="webappapis.html#synchronous-section">synchronous section</a> (which is triggered as part of the
6550: <a href="webappapis.html#event-loop">event loop</a> algorithm). The step in that section is
6551: marked with ⌛.</p>
6552:
6553: <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>
6554:
6555: <li><p>Let <var title="">URL</var> be the <a href="#track-url">track URL</a> of
6556: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6557:
6558: <li><p>Asynchronously run the remaining steps, while continuing
6559: with whatever task was responsible for creating the <a href="#text-track">text
6560: track</a> or changing the <a href="#text-track-mode">text track
6561: mode</a>.</p></li>
6562:
6563: <li>
6564:
6565: <p><i>Download</i>: If <var title="">URL</var> is not the empty
6566: string, and its <a href="origin-0.html#origin">origin</a> is the same as the <a href="#media-element">media
6567: element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, then
6568: <a href="fetching-resources.html#fetch">fetch</a> <var title="">URL</var>, from the <a href="#media-element">media
6569: element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, with
6570: the <i>force same-origin flag</i> set.</p>
6571: <p>The <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue
6572: a task">queued</a> by the <a href="fetching-resources.html#fetch" title="fetch">fetching
6573: algorithm</a> on the <a href="webappapis.html#networking-task-source">networking task source</a> to
6574: process the data as it is being fetched must examine the
6575: resource's <a href="fetching-resources.html#content-type" title="Content-Type">Content Type
6576: 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
6577: available, or if the type is not recognised as a text track
6578: format, then the resource's format must be assumed to be
6579: unsupported (this causes the load to fail, as described below). If
6580: a type is obtained, and represents a supported text track format,
6581: then the resource's data must be passed to the appropriate parser
6582: as it is received, with the <a href="#text-track-list-of-cues">text
6583: track list of cues</a> being used for that parser's output.</p>
6584:
6585: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> fails for
6586: any reason (network error, the server returns an error code, a
6587: cross-origin check fails, etc), or if <var title="">URL</var> is
6588: the empty string or has the wrong <a href="origin-0.html#origin">origin</a> as
6589: determined by the condition at the start of this step, or if the
6590: fetched resource is not in a supported format, then <a href="webappapis.html#queue-a-task">queue a
6591: task</a> to first change the <a href="#text-track-readiness-state">text track readiness
6592: state</a> to <a href="#text-track-failed-to-load" title="text track failed to load">failed to
6593: load</a> and then <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the <code><a href="#the-track-element">track</a></code>
6594: 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
6595: task">queued</a>, move on to the step below labeled
6596: <i>monitoring</i>.</p>
6597:
6598: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> does not
6599: fail, then, when it completes, <a href="webappapis.html#queue-a-task">queue a task</a> to first
6600: change the <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-loaded" title="text track loaded">loaded</a> and then <a href="webappapis.html#fire-a-simple-event">fire a
6601: simple event</a> named <code title="event-load">load</code> at
6602: the <code><a href="#the-track-element">track</a></code> element; and then, once that <a href="webappapis.html#concept-task" title="concept-task">task</a> is <a href="webappapis.html#queue-a-task" title="queue a
6603: task">queued</a>, move on to the step below labeled
6604: <i>monitoring</i>.</p>
6605:
6606: <p>If, while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> is
6607: active, either:</p>
6608:
6609: <ul><li>the <a href="#track-url">track URL</a> changes so that it is no longer
6610: equal to <var title="">URL</var>, while the <a href="#text-track-mode">text track
6611: mode</a> is set to <a href="#text-track-hidden" title="text track
6612: hidden">hidden</a>, <a href="#text-track-showing" title="text track
6613: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
6614: default">showing by default</a>; or</li>
6615:
6616: <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
6617: track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track
6618: showing by default">showing by default</a>, while the
6619: <a href="#track-url">track URL</a> is not equal to <var title="">URL</var></li>
6620:
6621: </ul><p>...then the user agent must run the following steps:</p>
6622:
6623: <ol><li><p>Abort the <a href="fetching-resources.html#fetch" title="fetch">fetching
6624: algorithm</a>.</p></li>
6625:
6626: <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
6627: event</a> named <code title="event-abort">abort</code> at
6628: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6629:
6630: <li><p>Let <var title="">URL</var> be the new <a href="#track-url">track
6631: URL</a>.</p></li>
6632:
6633: <li><p>Jump back to the top of the step labeled
6634: <i>download</i>.</p></li>
6635:
6636: </ol><p>Until one of the above circumstances occurs, the user agent
6637: must remain on this step.</p>
6638:
6639: </li>
6640:
6641: <li><p><i>Monitoring</i>: Wait until the <a href="#track-url">track URL</a> is
6642: no longer equal to <var title="">URL</var>, at the same time as the
6643: <a href="#text-track-mode">text track mode</a> is set to <a href="#text-track-hidden" title="text track
6644: hidden">hidden</a>, <a href="#text-track-showing" title="text track
6645: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
6646: default">showing by default</a>.</p></li>
6647:
6648: <li><p>Wait until the <a href="#text-track-readiness-state">text track readiness state</a> is
6649: no longer set to <a href="#text-track-loading" title="text track
6650: loading">loading</a>.</p></li>
6651:
6652: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
6653: section</a> consists of the following step. (The step in the
6654: <a href="webappapis.html#synchronous-section">synchronous section</a> is marked with ⌛.)</p></li>
6655:
6656: <li><p>⌛ Set the <a href="#text-track-readiness-state">text track readiness state</a> to
6657: <a href="#text-track-loading" title="text track loading">loading</a>.</p></li>
6658:
6659:
6660: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
6661: remaining steps asynchronously.</p></li>
6662:
6663: <li><p>Jump to the step labeled <i>download</i>.</p></li>
6664:
6665: </ol></div><h6 id="text-track-api"><span class="secno">4.8.10.12.4 </span>Text track API</h6><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-textTracks"><a href="#dom-media-texttracks">textTracks</a></code> . <code title="">length</code></dt>
6666: <dd>
6667: <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>
6668: </dd>
6669:
6670: <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>
6671: <dd>
6672: <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>
6673: </dd>
6674:
6675: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
6676: <dd>
6677: <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>
6678: </dd>
6679:
6680: </dl><div class="impl">
6681:
6682: <p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn>
6683: attribute of <a href="#media-element" title="media element">media elements</a> must
6684: return an <span title="array host objects">array host object</span>
6685: for objects of type <code><a href="#texttrack">TextTrack</a></code> that is <i>fixed
6686: length</i> and <i>read only</i>. The same object must be returned
6687: each time the attribute is accessed. <a href="references.html#refsWEBIDL">[WEBIDL]</a></p>
6688:
6689: <p>The array must contain the <code><a href="#texttrack">TextTrack</a></code> objects of the
6690: <a href="#text-track" title="text track">text tracks</a> in the <a href="#media-element">media
6691: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, in the same
6692: order as in the <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6693:
6694: </div><hr><pre class="idl">interface <dfn id="texttrack">TextTrack</dfn> {
6695: readonly attribute DOMString <a href="#dom-texttrack-kind" title="dom-TextTrack-kind">kind</a>;
6696: readonly attribute DOMString <a href="#dom-texttrack-label" title="dom-TextTrack-label">label</a>;
6697: readonly attribute DOMString <a href="#dom-texttrack-language" title="dom-TextTrack-language">language</a>;
6698:
6699: const unsigned short <a href="#dom-texttrack-none" title="dom-TextTrack-NONE">NONE</a> = 0;
6700: const unsigned short <a href="#dom-texttrack-loading" title="dom-TextTrack-LOADING">LOADING</a> = 1;
6701: const unsigned short <a href="#dom-texttrack-loaded" title="dom-TextTrack-LOADED">LOADED</a> = 2;
6702: const unsigned short <a href="#dom-texttrack-error" title="dom-TextTrack-ERROR">ERROR</a> = 3;
6703: readonly attribute unsigned short <a href="#dom-texttrack-readystate" title="dom-TextTrack-readyState">readyState</a>;
6704: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-onload" title="handler-TextTrack-onload">onload</a>;
6705: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-onerror" title="handler-TextTrack-onerror">onerror</a>;
6706:
6707: const unsigned short <a href="#dom-texttrack-off" title="dom-TextTrack-OFF">OFF</a> = 0;
6708: const unsigned short <a href="#dom-texttrack-hidden" title="dom-TextTrack-HIDDEN">HIDDEN</a> = 1;
6709: const unsigned short <a href="#dom-texttrack-showing" title="dom-TextTrack-SHOWING">SHOWING</a> = 2;
6710: attribute unsigned short <a href="#dom-texttrack-mode" title="dom-TextTrack-mode">mode</a>;
6711:
6712: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a> <a href="#dom-texttrack-cues" title="dom-TextTrack-cues">cues</a>;
6713: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a> <a href="#dom-texttrack-activecues" title="dom-TextTrack-activeCues">activeCues</a>;
6714:
6715: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
6716: };
6717: <a href="#texttrack">TextTrack</a> implements <a href="infrastructure.html#eventtarget">EventTarget</a>;</pre><dl class="domintro"><dt><var title="">textTrack</var> . <code title="dom-TextTrack-kind"><a href="#dom-texttrack-kind">kind</a></code></dt>
6718: <dd>
6719: <p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
6720: </dd>
6721:
6722: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-label"><a href="#dom-texttrack-label">label</a></code></dt>
6723: <dd>
6724: <p>Returns the <a href="#text-track-label">text track label</a>.</p>
6725: </dd>
6726:
6727: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-language"><a href="#dom-texttrack-language">language</a></code></dt>
6728: <dd>
6729: <p>Returns the <a href="#text-track-language">text track language</a> string.</p>
6730: </dd>
6731:
6732: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-readyState"><a href="#dom-texttrack-readystate">readyState</a></code></dt>
6733: <dd>
6734: <p>Returns the <a href="#text-track-readiness-state">text track readiness state</a>,
6735: represented by a number from the following list:</p>
6736: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-NONE"><a href="#dom-texttrack-none">NONE</a></code> (0)</dt>
6737: <dd>
6738: <p>The <a href="#text-track-not-loaded">text track not loaded</a> state.</p>
6739: </dd>
6740: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADING"><a href="#dom-texttrack-loading">LOADING</a></code> (1)</dt>
6741: <dd>
6742: <p>The <a href="#text-track-loading">text track loading</a> state.</p>
6743: </dd>
6744: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADED"><a href="#dom-texttrack-loaded">LOADED</a></code> (2)</dt>
6745: <dd>
6746: <p>The <a href="#text-track-loaded">text track loaded</a> state.</p>
6747: </dd>
6748: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-ERROR"><a href="#dom-texttrack-error">ERROR</a></code> (3)</dt>
6749: <dd>
6750: <p>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</p>
6751: </dd>
6752: </dl></dd>
6753:
6754: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code></dt>
6755: <dd>
6756: <p>Returns the <a href="#text-track-mode">text track mode</a>, represented by a
6757: number from the following list:</p>
6758: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-OFF"><a href="#dom-texttrack-off">OFF</a></code> (0)</dt>
6759: <dd>
6760: <p>The <a href="#text-track-disabled">text track disabled</a> mode.</p>
6761: </dd>
6762: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-HIDDEN"><a href="#dom-texttrack-hidden">HIDDEN</a></code> (1)</dt>
6763: <dd>
6764: <p>The <a href="#text-track-hidden">text track hidden</a> mode.</p>
6765: </dd>
6766: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-SHOWING"><a href="#dom-texttrack-showing">SHOWING</a></code> (2)</dt>
6767: <dd>
6768: <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>
6769: </dd>
6770: </dl><p>Can be set, to change the mode.</p>
6771: </dd>
6772:
6773: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-cues"><a href="#dom-texttrack-cues">cues</a></code></dt>
6774: <dd>
6775: <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>
6776: </dd>
6777:
6778: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-activeCues"><a href="#dom-texttrack-activecues">activeCues</a></code></dt>
6779: <dd>
6780: <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>
6781: </dd>
6782:
6783: </dl><div class="impl">
6784:
6785: <p>The <dfn id="dom-texttrack-kind" title="dom-TextTrack-kind"><code>kind</code></dfn>
6786: attribute must return the <a href="#text-track-kind">text track kind</a> of the
6787: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
6788: represents.</p>
6789:
6790: <p>The <dfn id="dom-texttrack-label" title="dom-TextTrack-label"><code>label</code></dfn>
6791: attribute must return the <a href="#text-track-label">text track label</a> of the
6792: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
6793: represents.</p>
6794:
6795: <p>The <dfn id="dom-texttrack-language" title="dom-TextTrack-language"><code>language</code></dfn>
6796: attribute must return the <a href="#text-track-language">text track language</a> of the
6797: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
6798: represents.</p>
6799:
6800: <p>The <dfn id="dom-texttrack-readystate" title="dom-TextTrack-readyState"><code>readyState</code></dfn>
6801: attribute must return the numeric value corresponding to the
6802: <a href="#text-track-readiness-state">text track readiness state</a> of the <a href="#text-track">text
6803: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents, as
6804: defined by the following list:</p>
6805:
6806: <dl><dt><dfn id="dom-texttrack-none" title="dom-TextTrack-NONE"><code>NONE</code></dfn> (numeric value 0)</dt>
6807: <dd>The <a href="#text-track-not-loaded">text track not loaded</a> state.</dd>
6808: <dt><dfn id="dom-texttrack-loading" title="dom-TextTrack-LOADING"><code>LOADING</code></dfn> (numeric value 1)</dt>
6809: <dd>The <a href="#text-track-loading">text track loading</a> state.</dd>
6810: <dt><dfn id="dom-texttrack-loaded" title="dom-TextTrack-LOADED"><code>LOADED</code></dfn> (numeric value 2)</dt>
6811: <dd>The <a href="#text-track-loaded">text track loaded</a> state.</dd>
6812: <dt><dfn id="dom-texttrack-error" title="dom-TextTrack-ERROR"><code>ERROR</code></dfn> (numeric value 3)</dt>
6813: <dd>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</dd>
6814: </dl><p>The <dfn id="dom-texttrack-mode" title="dom-TextTrack-mode"><code>mode</code></dfn>
6815: attribute, on getting, must return the numeric value corresponding
6816: to the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text track</a>
6817: that the <code><a href="#texttrack">TextTrack</a></code> object represents, as defined by
6818: the following list:</p>
6819:
6820: <dl><dt><dfn id="dom-texttrack-off" title="dom-TextTrack-OFF"><code>OFF</code></dfn> (numeric value 0)</dt>
6821: <dd>The <a href="#text-track-disabled">text track disabled</a> mode.</dd>
6822: <dt><dfn id="dom-texttrack-hidden" title="dom-TextTrack-HIDDEN"><code>HIDDEN</code></dfn> (numeric value 1)</dt>
6823: <dd>The <a href="#text-track-hidden">text track hidden</a> mode.</dd>
6824: <dt><dfn id="dom-texttrack-showing" title="dom-TextTrack-SHOWING"><code>SHOWING</code></dfn> (numeric value 2)</dt>
6825: <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>
6826: </dl><p>On setting, if the new value is not either 0, 1, or 2, the user
6827: agent must throw an <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code>
6828: exception. Otherwise, if the new value isn't equal to what the
6829: attribute would currently return, the new value must be processed as
6830: follows:</p>
6831:
6832: <dl class="switch"><dt>If the new value is 0</dt>
6833:
6834: <dd>
6835:
6836: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6837: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
6838: the <a href="#text-track-disabled">text track disabled</a> mode.</p>
6839:
6840: </dd>
6841:
6842: <dt>If the new value is 1</dt>
6843:
6844: <dd>
6845:
6846: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6847: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
6848: the <a href="#text-track-hidden">text track hidden</a> mode.</p>
6849:
6850: </dd>
6851:
6852: <dt>If the new value is 2</dt>
6853:
6854: <dd>
6855:
6856: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6857: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
6858: the <a href="#text-track-showing">text track showing</a> mode.</p>
6859:
6860: <p class="note">If the mode had been <a href="#text-track-showing-by-default" title="text track
6861: showing by default">showing by default</a>, this will change it
6862: to <a href="#text-track-showing" title="text track showing">showing</a>, even though
6863: the value of <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> would
6864: appear not to change.</p>
6865:
6866: </dd>
6867:
6868: </dl><p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6869: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
6870: 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
6871: return a <a href="infrastructure.html#live">live</a> <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
6872: that represents the subset of the <a href="#text-track-list-of-cues">text track list of
6873: cues</a> of the <a href="#text-track">text track</a> that the
6874: <code><a href="#texttrack">TextTrack</a></code> object represents whose <a href="#text-track-cue-start-time" title="text
6875: track cue start time">start times</a> occur before the
6876: <a href="#earliest-possible-position-when-the-script-started">earliest possible position when the script started</a>, in
6877: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
6878: null. When an object is returned, the same object must be returned
6879: each time.</p>
6880:
6881: <p>The <dfn id="earliest-possible-position-when-the-script-started">earliest possible position when the script started</dfn>
6882: is whatever the <a href="#earliest-possible-position">earliest possible position</a> was the last
6883: time the <a href="webappapis.html#event-loop">event loop</a> reached step 1.</p>
6884:
6885: <p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6886: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
6887: 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>
6888: attribute must return a <a href="infrastructure.html#live">live</a>
6889: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that represents the subset of
6890: the <a href="#text-track-list-of-cues">text track list of cues</a> of the <a href="#text-track">text
6891: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents
6892: whose <a href="#active-flag-was-set-when-the-script-started">active flag was set when the script started</a>, in
6893: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
6894: null. When an object is returned, the same object must be returned
6895: each time.</p>
6896:
6897: <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
6898: the script started</dfn> if its <a href="#text-track-cue-active-flag">text track cue active
6899: flag</a> was set the last time the <a href="webappapis.html#event-loop">event loop</a>
6900: reached step 1.</p>
6901:
6902: </div><hr><pre class="idl">interface <dfn id="mutabletexttrack">MutableTextTrack</dfn> : <a href="#texttrack">TextTrack</a> {
6903: void <a href="#dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue">addCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
6904: void <a href="#dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue">removeCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
6905: };</pre><dl class="domintro"><dt><var title="">mutableTextTrack</var> = <var title="">media</var> . <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack</a></code>( <var title="">kind</var> [, <var title="">label</var> [, <var title="">language</var> ] ] )</dt>
6906:
6907: <dd>
6908: <p>Creates and returns a new <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object, which is also added to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6909: </dd>
6910:
6911: <dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-addCue"><a href="#dom-mutabletexttrack-addcue">addCue</a></code>( <var title="">cue</var> )</dt>
6912: <dd>
6913: <p>Adds the given cue to <var title="">mutableTextTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
6914: <p>Raises an exception if the argument is null, associated with another <a href="#text-track">text track</a>, or already in the list of cues.</p>
6915: </dd>
6916:
6917: <dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-removeCue"><a href="#dom-mutabletexttrack-removecue">removeCue</a></code>( <var title="">cue</var> )</dt>
6918: <dd>
6919: <p>Removes the given cue from <var title="">mutableTextTrack</var>'s <a href="#text-track-list-of-cues">text track list of cues</a>.</p>
6920: <p>Raises an exception if the argument is null, associated with another <a href="#text-track">text track</a>, or not in the list of cues.</p>
6921: </dd>
6922:
6923: </dl><div class="impl">
6924:
6925: <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
6926: element">media elements</a>, when invoked, must run the following
6927: steps:</p>
6928:
6929: <ol><li>
6930:
6931: <p>If <var title="">kind</var> is not one of the following
6932: strings, then throw a <code><a href="common-dom-interfaces.html#syntax_err">SYNTAX_ERR</a></code> exception and abort
6933: these steps:</p>
6934:
6935: <ul class="brief"><li><code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code>
6936: </li><li><code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code>
6937: </li><li><code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code>
6938: </li><li><code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code>
6939: </li><li><code title="dom-TextTrack-kind-metadata"><a href="#dom-texttrack-kind-metadata">metadata</a></code>
6940: </li></ul></li>
6941:
6942: <li>
6943:
6944: <p>If the <var title="">label</var> argument was omitted, let <var title="">label</var> be the empty string.</p>
6945:
6946: </li>
6947:
6948: <li>
6949:
6950: <p>If the <var title="">language</var> argument was omitted, let
6951: <var title="">language</var> be the empty string.</p>
6952:
6953: </li>
6954:
6955: <li>
6956:
6957: <p>Create a new <a href="#text-track">text track</a>, and set its <a href="#text-track-kind">text
6958: track kind</a> to <var title="">kind</var>, its <a href="#text-track-label">text
6959: track label</a> to <var title="">label</var>, its <a href="#text-track-language">text
6960: track language</a> to <var title="">language</var>, its
6961: <a href="#text-track-readiness-state">text track readiness state</a> to the <a href="#text-track-loaded">text track
6962: loaded</a> state, its <a href="#text-track-mode">text track mode</a> to the
6963: <a href="#text-track-hidden">text track hidden</a> mode, and its <a href="#text-track-list-of-cues">text track
6964: list of cues</a> to an empty list.
6965: </p>
6966:
6967: </li>
6968:
6969: <li>
6970:
6971: <p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6972: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6973:
6974: </li></ol><p>The <dfn id="dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue"><code>addCue(<var title="">cue</var>)</code></dfn> method of
6975: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
6976: following steps:</p>
6977:
6978: <ol><li><p>If <var title="">cue</var> is null, then throw an
6979: <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
6980: steps.</p></li>
6981:
6982: <li><p>If the given <var title="">cue</var> is already associated
6983: with a <a href="#text-track">text track</a> other than the method's
6984: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
6985: then throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception and abort
6986: these steps.</p></li>
6987:
6988: <li><p>Associate <var title="">cue</var> with the method's
6989: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
6990: if it is not currently associated with a <a href="#text-track">text
6991: track</a>.</p></li>
6992:
6993: <li><p>If the given <var title="">cue</var> is already listed in
6994: the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
6995: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw an
6996: <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception.</p></li>
6997:
6998: <li><p>Add <var title="">cue</var> to the method's
6999: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
7000: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7001:
7002: </ol><p>The <dfn id="dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue"><code>removeCue(<var title="">cue</var>)</code></dfn> method of
7003: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
7004: following steps:</p>
7005:
7006: <ol><li><p>If <var title="">cue</var> is null, then throw an
7007: <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
7008: steps.</p></li>
7009:
7010: <li><p>If the given <var title="">cue</var> is not associated with
7011: the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7012: track</a>, then throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code>
7013: exception.</p></li>
7014:
7015: <li><p>If the given <var title="">cue</var> is not currently listed
7016: in the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7017: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw a
7018: <code><a href="common-dom-interfaces.html#not_found_err">NOT_FOUND_ERR</a></code> exception.</p></li>
7019:
7020: <li><p>Remove <var title="">cue</var> from the method's
7021: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
7022: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7023:
7024: </ol></div><div class="example">
7025:
7026: <p>In this example, an <code><a href="#the-audio-element">audio</a></code> element is used to play a
7027: specific sound-effect from a sound file containing many sound
7028: effects. A cue is used to pause the audio, so that it ends exactly
7029: at the end of the clip, even if the browser is busy running some
7030: script. If the page had relied on script to pause the audio, then
7031: the start of the next clip might be heard if the browser was not
7032: able to run the script at the exact time specified.</p>
7033:
7034: <pre>var sfx = new Audio('sfx.wav');
7035: var sounds = a.addTextTrack('metadata');
7036:
7037: // add sounds we care about
7038: sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
7039: sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));
7040:
7041: function playSound(id) {
7042: sfx.currentTime = sounds.getCueById(id).startTime;
7043: sfx.play();
7044: }
7045:
7046: sfx.oncanplaythrough = function () {
7047: playSound('dog bark');
7048: }
7049: window.onbeforeunload = function () {
7050: playSound('kitten mew');
7051: return 'Are you sure you want to leave this awesome page?';
7052: }</pre>
7053:
7054: </div><hr><pre class="idl">interface <dfn id="texttrackcuelist">TextTrackCueList</dfn> {
7055: readonly attribute unsigned long <a href="#dom-texttrackcuelist-length" title="dom-TextTrackCueList-length">length</a>;
7056: getter <a href="#texttrackcue">TextTrackCue</a> (in unsigned long index);
7057: <a href="#texttrackcue">TextTrackCue</a> <a href="#dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById">getCueById</a>(in DOMString id);
7058: };</pre><dl class="domintro"><dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-length"><a href="#dom-texttrackcuelist-length">length</a></code></dt>
7059: <dd>
7060: <p>Returns the number of <a href="#text-track-cue" title="text track cue">cues</a> in the list.</p>
7061: </dd>
7062:
7063: <dt><var title="">cuelist</var>[<var title="">index</var>]</dt>
7064: <dd>
7065: <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>
7066: </dd>
7067:
7068: <dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-getCueById"><a href="#dom-texttrackcuelist-getcuebyid">getCueById</a></code>( <var title="">id</var> )</dt>
7069: <dd>
7070: <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>
7071: <p>Returns null if none of the cues have the given identifier or if the argument is the empty string.</p>
7072: </dd>
7073:
7074: </dl><div class="impl">
7075:
7076: <p>A <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object represents a dynamically
7077: updating list of <a href="#text-track-cue" title="text track cue">text track
7078: cues</a> in a given order.</p>
7079:
7080: <p>The <dfn id="dom-texttrackcuelist-length" title="dom-TextTrackCueList-length"><code>length</code></dfn>
7081: attribute must return the number of <a href="#text-track-cue" title="text track
7082: cue">cues</a> in the list represented by the
7083: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7084:
7085: <p>The <span>supported property indicies</span> of a
7086: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
7087: from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
7088: in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
7089: minus one, if any. If there are no <a href="#text-track-cue" title="text track
7090: cue">cues</a> in the list, there are no <span>supported property
7091: indicies</span>.</p>
7092:
7093: <p>To <span>determine the value of an indexed property</span> for a
7094: given index <var title="">index</var>, the user agent must return
7095: the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
7096: list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7097:
7098: <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
7099: other than the empty string, must return the first <a href="#text-track-cue">text track
7100: cue</a> in the list represented by the
7101: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object whose <a href="#text-track-cue-identifier">text track cue
7102: identifier</a> is <var title="">id</var>, if any, or null
7103: otherwise. If the argument is the empty string, then the method must
7104: return null.</p>
7105:
7106: </div><hr><pre class="idl">
7107: interface <dfn id="texttrackcue">TextTrackCue</dfn> {
7108: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a>;
7109: readonly attribute DOMString <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a>;
7110:
7111: readonly attribute double <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a>;
7112: readonly attribute double <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a>;
7113: readonly attribute boolean <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a>;
7114:
7115:
7116: DOMString <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>();
7117: <a href="infrastructure.html#documentfragment">DocumentFragment</a> <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>();
7118:
7119: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter">onenter</a>;
7120: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit">onexit</a>;
7121: };
7122: <a href="#texttrackcue">TextTrackCue</a> implements <a href="infrastructure.html#eventtarget">EventTarget</a>;</pre><dl class="domintro"><dt><var title="">cue</var> . <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a></dt>
7123: <dd>
7124: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object to which this
7125: <a href="#text-track-cue">text track cue</a> belongs, if any, or null
7126: otherwise.</p>
7127: </dd>
7128:
7129: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a></dt>
7130: <dd>
7131: <p>Returns the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
7132: </dd>
7133:
7134: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a></dt>
7135: <dd>
7136: <p>Returns the <a href="#text-track-cue-start-time">text track cue start time</a>, in seconds.</p>
7137: </dd>
7138:
7139: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a></dt>
7140: <dd>
7141: <p>Returns the <a href="#text-track-cue-end-time">text track cue end time</a>, in seconds.</p>
7142: </dd>
7143:
7144: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a></dt>
7145: <dd>
7146: <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>
7147: </dd>
7148:
7149:
7150: <dt><var title="">source</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>()</dt>
7151: <dd>
7152: <p>Returns the <a href="#text-track-cue-text">text track cue text</a> in raw unparsed form.</p>
7153: </dd>
7154:
7155: <dt><var title="">fragment</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>()</dt>
7156: <dd>
7157: <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>
7158: </dd>
7159:
7160: </dl><div class="impl">
7161:
7162:
7163: <p>The <dfn id="dom-texttrackcue-track" title="dom-TextTrackCue-track"><code>track</code></dfn>
7164: attribute must return the <code><a href="#texttrack">TextTrack</a></code> object of the
7165: <a href="#text-track">text track</a> with which the <a href="#text-track-cue">text track cue</a>
7166: that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is associated,
7167: if any; or null otherwise.</p>
7168:
7169: <p>The <dfn id="dom-texttrackcue-id" title="dom-TextTrackCue-id"><code>id</code></dfn>
7170: attribute must return the <a href="#text-track-cue-identifier">text track cue identifier</a> of
7171: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7172: object represents.</p>
7173:
7174: <p>The <dfn id="dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime"><code>startTime</code></dfn>
7175: attribute must return the <a href="#text-track-cue-start-time">text track cue start time</a> of
7176: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7177: object represents, in seconds.</p>
7178:
7179: <p>The <dfn id="dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime"><code>endTime</code></dfn>
7180: attribute must return the <a href="#text-track-cue-end-time">text track cue end time</a> of
7181: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7182: object represents, in seconds.</p>
7183:
7184: <p>The <dfn id="dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit"><code>pauseOnExit</code></dfn>
7185: attribute must return true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue
7186: pause-on-exit flag</a> of the <a href="#text-track-cue">text track cue</a> that
7187: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
7188: otherwise.</p>
7189:
7190: <p>The <dfn id="dom-texttrackcue-direction" title="dom-TextTrackCue-direction"><code>direction</code></dfn>
7191: attribute must return the <a href="#text-track-cue-writing-direction">text track cue writing
7192: direction</a> of the <a href="#text-track-cue">text track cue</a> that the
7193: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents.</p>
7194:
7195:
7196: <p>The <dfn id="dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource"><code>getCueAsSource()</code></dfn>
7197: method must return the raw <a href="#text-track-cue-text">text track cue text</a>.</p>
7198:
7199: <p>The <dfn id="dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML"><code>getCueAsHTML()</code></dfn>
7200: method must convert the <a href="#text-track-cue-text">text track cue text</a> to a
7201: <code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> for the <a href="#media-element">media element</a>'s
7202: <code><a href="infrastructure.html#document">Document</a></code>, using the appropriate rules for doing
7203: so.
7204: </p>
7205:
7206: </div><div class="impl">
7207:
7208: <h6 id="cue-events"><span class="secno">4.8.10.12.5 </span>Event definitions</h6>
7209:
7210: <p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
7211: supported, as IDL attributes, by all objects implementing the
7212: <code><a href="#texttrack">TextTrack</a></code> interface:</p>
7213:
7214: <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>
7215: </th></tr></thead><tbody><tr><td><dfn id="handler-texttrack-onload" title="handler-TextTrack-onload"><code>onload</code></dfn> </td><td> <code title="event-load">load</code>
7216: </td></tr><tr><td><dfn id="handler-texttrack-onerror" title="handler-TextTrack-onerror"><code>onerror</code></dfn> </td><td> <code title="event-error">error</code>
7217: </td></tr><tr><td><dfn id="handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange"><code>oncuechange</code></dfn> </td><td> <code title="event-cuechange">cuechange</code>
7218: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
7219: supported, as IDL attributes, by all objects implementing the
7220: <code><a href="#texttrackcue">TextTrackCue</a></code> interface:</p>
7221:
7222: <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>
7223: </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>
7224: </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>
7225: </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>
7226: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. If present, it
7227: indicates that the author has not provided a scripted controller and
7228: would like the user agent to provide its own set of controls.</p><div class="impl">
7229:
7230: <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
7231: <a href="#media-element">media element</a>, then the user agent should <dfn id="expose-a-user-interface-to-the-user">expose a
7232: user interface to the user</dfn>. This user interface should include
7233: features to begin playback, pause playback, seek to an arbitrary
7234: position in the content (if the content supports arbitrary seeking),
7235: change the volume, change the display of closed captions or embedded
7236: sign-language tracks, select different audio tracks or turn on audio
7237: descriptions, and show the media content in manners more suitable to
7238: the user (e.g. full-screen video or in an independent resizable
7239: window). Other controls may also be made available.</p>
7240:
7241: <p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7242: controller</a>, then the user agent should expose audio tracks
7243: from all the <a href="#slaved-media-elements">slaved media elements</a> (although avoiding
7244: duplicates if the same <a href="#media-resource">media resource</a> is being used
7245: several times). If a <a href="#media-resource">media resource</a>'s audio track
7246: exposed in this way has no known name, and it is the only audio
7247: track for a particular <a href="#media-element">media element</a>, the user agent
7248: should use the element's <code title="attr-title"><a href="elements.html#the-title-attribute">title</a></code>
7249: attribute, if any, as the name (or as part of the name) of that
7250: track.</p>
7251:
7252: <p>Even when the attribute is absent, however, user agents may
7253: provide controls to affect playback of the media resource
7254: (e.g. play, pause, seeking, and volume controls), but such features
7255: should not interfere with the page's normal rendering. For example,
7256: such features could be exposed in the <a href="#media-element">media element</a>'s
7257: context menu.</p>
7258:
7259: <p>Where possible (specifically, for starting, stopping, pausing,
7260: and unpausing playback, for seeking, for changing the rate of
7261: playback, for fast-forwarding or rewinding,
7262: for listing, enabling, and disabling text tracks,
7263: and for muting or changing the volume of the audio), user interface
7264: features exposed by the user agent must be implemented in terms of
7265: the DOM API described above, so that, e.g., all the same events
7266: fire.</p>
7267:
7268: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7269: controller</a>, the user agent's user interface for pausing and
7270: unpausing playback, for seeking, for changing the rate of playback,
7271: for fast-forwarding or rewinding, and for muting or changing the
7272: volume of audio of the entire group must be implemented in terms of
7273: the <code><a href="#mediacontroller">MediaController</a></code> API exposed on that <a href="#current-media-controller">current
7274: media controller</a>.</p>
7275:
7276: <p>The "play" function in the user agent's interface must set the
7277: <code title="">playbackRate</code> attribute to the value of the
7278: <code title="">defaultPlaybackRate</code> attribute before invoking
7279: the <code title="">play()</code> method.
7280: When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7281: controller</a>, the attributes and method with those names on
7282: that <code><a href="#mediacontroller">MediaController</a></code> object must be used. Otherwise,
7283: the attributes and method with those names on the <a href="#media-element">media
7284: element</a> itself must be used.
7285: </p>
7286:
7287: <p>Features such as fast-forward or rewind must be implemented by
7288: only changing the <code title="">playbackRate</code> attribute (and
7289: not the <code title="">defaultPlaybackRate</code> attribute).
7290: Again, when a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7291: controller</a>, the attributes with those names on that
7292: <code><a href="#mediacontroller">MediaController</a></code> object must be used; otherwise, the
7293: attributes with those names on the <a href="#media-element">media element</a> itself
7294: must be used.
7295: </p>
7296:
7297: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7298: controller</a>, and all the <a href="#slaved-media-elements">slaved media elements</a> of
7299: that <code><a href="#mediacontroller">MediaController</a></code> are paused, the user agent should
7300: unpause all the <a href="#slaved-media-elements">slaved media elements</a> when the user
7301: invokes a user agent interface control for beginning playback.</p>
7302:
7303: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7304: controller</a>, seeking must be implemented in terms of the <code title="dom-MediaController-seek">seek()</code> method on that
7305: <code><a href="#mediacontroller">MediaController</a></code> object. Otherwise, the user agent must
7306: directly <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the requested
7307: position in the <a href="#media-element">media element</a>'s <a href="#media-timeline">media
7308: timeline</a>.</p>
7309:
7310: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7311: controller</a>, user agents may additionally provide the user
7312: with controls that directly manipulate an individual <a href="#media-element">media
7313: element</a> without affecting the <code><a href="#mediacontroller">MediaController</a></code>,
7314: but such features are considered relatively advanced and unlikely to
7315: be useful to most users.
7316:
7317: </p><p>For the purposes of listing chapters in the <a href="#media-resource">media
7318: resource</a>, only <a href="#text-track" title="text track">text tracks</a>
7319: in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
7320: tracks</a> <a href="#text-track-showing" title="text track showing">showing</a> or
7321: <a href="#text-track-showing-by-default" title="text track showing by default">showing by
7322: default</a> and whose <a href="#text-track-kind">text track kind</a> is <code title="dom-timedtrack-kind-chapters">chapters</code> should be used.
7323: Each <a href="#text-track-cue" title="text track cue">cue</a> in such a <a href="#text-track">text
7324: track</a> represents a chapter starting at the cue's <a href="#text-track-cue-start-time" title="text track cue start time">start time</a>. The name of
7325: the chapter is the <a href="#text-track-cue-text">text track cue text</a>, interpreted
7326: literally.</p>
7327:
7328: <p>The <dfn id="dom-media-controls" title="dom-media-controls"><code>controls</code></dfn>
7329: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
7330: same name.</p>
7331:
7332: <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>
7333:
7334: <dd>
7335:
7336: <p>Returns the current playback volume, as a number in the range
7337: 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.</p>
7338:
7339: <p>Can be set, to change the volume.</p>
7340:
7341: <p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
7342: in the range 0.0 .. 1.0.</p>
7343:
7344: </dd>
7345:
7346: <dt><var title="">media</var> . <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
7347:
7348: <dd>
7349:
7350: <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
7351: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute is being
7352: honored.</p>
7353:
7354: <p>Can be set, to change whether the audio is muted or not.</p>
7355:
7356: </dd>
7357:
7358: </dl><div class="impl">
7359:
7360: <p>The <dfn id="dom-media-volume" title="dom-media-volume"><code>volume</code></dfn>
7361: attribute must return the playback volume of any audio portions of
7362: the <a href="#media-element">media element</a>, in the range 0.0 (silent) to 1.0
7363: (loudest). Initially, the volume must be 1.0, but user agents may
7364: remember the last set value across sessions, on a per-site basis or
7365: otherwise, so the volume may start at other values. On setting, if
7366: the new value is in the range 0.0 to 1.0 inclusive, the attribute
7367: must be set to the new value. If the new value is outside the range
7368: 0.0 to 1.0 inclusive, then, on setting, an
7369: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
7370:
7371: <p>The <dfn id="dom-media-muted" title="dom-media-muted"><code>muted</code></dfn>
7372: attribute must return true if the audio channels are muted and false
7373: otherwise. Initially, the audio channels should not be muted
7374: (false), but user agents may remember the last set value across
7375: sessions, on a per-site basis or otherwise, so the muted state may
7376: start as muted (true). On setting, the attribute must be set to the
7377: new value.</p>
7378:
7379: <p>Whenever either the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> or
7380: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attributes are changed,
7381: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
7382: event</a> named <code title="event-media-volumechange"><a href="#event-media-volumechange">volumechange</a></code> at the <a href="#media-element">media
7383: element</a>.</p>
7384:
7385: <p>An element's <dfn id="effective-media-volume">effective media volume</dfn> is determined as
7386: follows:</p>
7387:
7388: <ol><li><p>If the element's <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code>
7389: attribute is true, the element's <a href="#effective-media-volume">effective media
7390: volume</a> is zero. Abort these steps.</p></li>
7391:
7392: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>
7393: and that <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-mute-override">media
7394: controller mute override</a> is true, the element's
7395: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
7396: steps.</p></li>
7397:
7398: <li><p>Let <var title="">volume</var> be the value of the element's
7399: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute.</p></li>
7400:
7401: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>,
7402: multiply <var title="">volume</var> by that
7403: <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-volume-multiplier">media controller volume
7404: multiplier</a>.</p></li>
7405:
7406: <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
7407: 1.0, with 0.0 being silent, and 1.0 being the loudest setting,
7408: values in between increasing in loudness. The range need not be
7409: linear. The loudest setting may be lower than the system's loudest
7410: possible setting; for example the user could have set a maximum
7411: volume.</p></li>
7412:
7413: </ol></div><p>The <dfn id="attr-media-muted" title="attr-media-muted"><code>muted</code></dfn>
7414: attribute on the <code><a href="#the-video-element">video</a></code> element controls the default
7415: state of the audio channel of the <a href="#media-resource">media resource</a>,
7416: potentially overriding user preferences.</p><div class="impl">
7417:
7418: <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
7419: agent must set the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> IDL
7420: attribute to true, overriding any user preference.</p>
7421:
7422: <p>The <dfn id="dom-media-defaultmuted" title="dom-media-defaultMuted"><code>defaultMuted</code></dfn> IDL
7423: 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>
7424:
7425: </div><p class="note">This attribute has no dynamic effect (it only
7426: controls the default state of the element).</p><div class="example">
7427:
7428: <p>This video (an advertisment) autoplays, but to avoid annoying
7429: users, it does so without sound, and allows the user to turn the
7430: sound on.</p>
7431:
7432: <pre><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></pre>
7433:
7434: </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
7435: represent a list of ranges (periods) of time.</p><pre class="idl">interface <dfn id="timeranges">TimeRanges</dfn> {
7436: readonly attribute unsigned long <a href="#dom-timeranges-length" title="dom-TimeRanges-length">length</a>;
7437: double <a href="#dom-timeranges-start" title="dom-TimeRanges-start">start</a>(in unsigned long index);
7438: double <a href="#dom-timeranges-end" title="dom-TimeRanges-end">end</a>(in unsigned long index);
7439: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-TimeRanges-length"><a href="#dom-timeranges-length">length</a></code></dt>
7440:
7441: <dd>
7442:
7443: <p>Returns the number of ranges in the object.</p>
7444:
7445: </dd>
7446:
7447: <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>
7448:
7449: <dd>
7450:
7451: <p>Returns the time for the start of the range with the given index.</p>
7452:
7453: <p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the index is out of range.</p>
7454:
7455: </dd>
7456:
7457: <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>
7458:
7459: <dd>
7460:
7461: <p>Returns the time for the end of the range with the given index.</p>
7462:
7463: <p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the index is out of range.</p>
7464:
7465: </dd>
7466:
7467: </dl><div class="impl">
7468:
7469: <p>The <dfn id="dom-timeranges-length" title="dom-TimeRanges-length"><code>length</code></dfn>
7470: IDL attribute must return the number of ranges represented by the object.</p>
7471:
7472: <p>The <dfn id="dom-timeranges-start" title="dom-TimeRanges-start"><code>start(<var title="">index</var>)</code></dfn> method must return the position
7473: of the start of the <var title="">index</var>th range represented by
7474: the object, in seconds measured from the start of the timeline that
7475: the object covers.</p>
7476:
7477: <p>The <dfn id="dom-timeranges-end" title="dom-TimeRanges-end"><code>end(<var title="">index</var>)</code></dfn> method must return the position
7478: of the end of the <var title="">index</var>th range represented by
7479: the object, in seconds measured from the start of the timeline that
7480: the object covers.</p>
7481:
7482: <p>These methods must raise <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exceptions
7483: if called with an <var title="">index</var> argument greater than or
7484: equal to the number of ranges represented by the object.</p>
7485:
7486: <p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said to be a
7487: <dfn id="normalized-timeranges-object">normalized <code>TimeRanges</code> object</dfn>, the ranges it
7488: represents must obey the following criteria:</p>
7489:
7490: <ul><li>The start of a range must be greater than the end of all
7491: earlier ranges.</li>
7492:
7493: <li>The start of a range must be less than the end of that same
7494: range.</li>
7495:
7496: </ul><p>In other words, the ranges in such an object are ordered, don't
7497: overlap, aren't empty, and don't touch (adjacent ranges are folded
7498: into one bigger range).</p>
7499:
7500: <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
7501: <a href="#media-timeline">media timeline</a>.</p>
7502:
7503: </div><h5 id="mediaevents"><span class="secno">4.8.10.15 </span>Event summary</h5><p><i>This section is non-normative.</i></p><p>The following events fire on <a href="#media-element" title="media element">media
7504: elements</a> as part of the processing model described above:</p><table><thead><tr><th>Event name
7505: </th><th>Interface
7506: </th><th>Dispatched when...
7507: </th><th>Preconditions
7508:
7509: </th></tr></thead><tbody><tr><td><dfn id="event-media-loadstart" title="event-media-loadstart"><code>loadstart</code></dfn>
7510: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7511: </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>.
7512: </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>
7513: </td></tr><tr><td><dfn id="event-media-progress" title="event-media-progress"><code>progress</code></dfn>
7514: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7515: </td><td>The user agent is fetching <a href="#media-data">media data</a>.
7516: </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>
7517: </td></tr><tr><td><dfn id="event-media-suspend" title="event-media-suspend"><code>suspend</code></dfn>
7518: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7519: </td><td>The user agent is intentionally not currently fetching <a href="#media-data">media data</a>, but does not have the entire <a href="#media-resource">media resource</a> downloaded.
7520: </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>
7521: </td></tr><tr><td><dfn id="event-media-abort" title="event-media-abort"><code>abort</code></dfn>
7522: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7523: </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.
7524: </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>.
7525: <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.
7526: </td></tr><tr><td><dfn id="event-media-error" title="event-media-error"><code>error</code></dfn>
7527: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7528: </td><td>An error occurs while fetching the <a href="#media-data">media data</a>.
7529: </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.
7530: <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.
7531: </td></tr><tr><td><dfn id="event-media-emptied" title="event-media-emptied"><code>emptied</code></dfn>
7532: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7533: </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).
7534: </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.
7535: </td></tr><tr><td><dfn id="event-media-stalled" title="event-media-stalled"><code>stalled</code></dfn>
7536: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7537: </td><td>The user agent is trying to fetch <a href="#media-data">media data</a>, but data is unexpectedly not forthcoming.
7538: </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>.
7539:
7540: </td></tr></tbody><tbody><tr><td><dfn id="event-media-loadedmetadata" title="event-media-loadedmetadata"><code>loadedmetadata</code></dfn>
7541: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7542: </td><td>The user agent has just determined the duration and dimensions of the <a href="#media-resource">media resource</a>
7543: and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>.
7544: </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.
7545: </td></tr><tr><td><dfn id="event-media-loadeddata" title="event-media-loadeddata"><code>loadeddata</code></dfn>
7546: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7547: </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.
7548: </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.
7549: </td></tr><tr><td><dfn id="event-media-canplay" title="event-media-canplay"><code>canplay</code></dfn>
7550: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7551: </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.
7552: </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.
7553: </td></tr><tr><td><dfn id="event-media-canplaythrough" title="event-media-canplaythrough"><code>canplaythrough</code></dfn>
7554: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7555: </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.
7556: </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>.
7557: </td></tr><tr><td><dfn id="event-media-playing" title="event-media-playing"><code>playing</code></dfn>
7558: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7559: </td><td>Playback is ready to start after having been paused or delayed due to lack of <a href="#media-data">media data</a>.
7560: </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
7561: 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
7562: the element is <a href="#paused-for-user-interaction">paused for user interaction</a>.
7563: </td></tr><tr><td><dfn id="event-media-waiting" title="event-media-waiting"><code>waiting</code></dfn>
7564: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7565: </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.
7566: </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.
7567: the element is newly <a href="#blocked-on-its-media-controller">blocked on its media controller</a>, or
7568: <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>.
7569: </td></tr></tbody><tbody><tr><td><dfn id="event-media-seeking" title="event-media-seeking"><code>seeking</code></dfn>
7570: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7571: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to true and the seek operation is taking long enough that the user agent has time to fire the event.
7572: </td><td>
7573: </td></tr><tr><td><dfn id="event-media-seeked" title="event-media-seeked"><code>seeked</code></dfn>
7574: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7575: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to false.
7576: </td><td>
7577: </td></tr><tr><td><dfn id="event-media-ended" title="event-media-ended"><code>ended</code></dfn>
7578: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7579: </td><td>Playback has stopped because the end of the <a href="#media-resource">media resource</a> was reached.
7580: </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.
7581:
7582: </td></tr></tbody><tbody><tr><td><dfn id="event-media-durationchange" title="event-media-durationchange"><code>durationchange</code></dfn>
7583: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7584: </td><td>The <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute has just been updated.
7585: </td><td>
7586: </td></tr><tr><td><dfn id="event-media-timeupdate" title="event-media-timeupdate"><code>timeupdate</code></dfn>
7587: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7588: </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.
7589: </td><td>
7590: </td></tr><tr><td><dfn id="event-media-play" title="event-media-play"><code>play</code></dfn>
7591: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7592: </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.
7593: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false.
7594: </td></tr><tr><td><dfn id="event-media-pause" title="event-media-pause"><code>pause</code></dfn>
7595: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7596: </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.
7597: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly true.
7598: </td></tr><tr><td><dfn id="event-media-ratechange" title="event-media-ratechange"><code>ratechange</code></dfn>
7599: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7600: </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.
7601: </td><td>
7602: </td></tr><tr><td><dfn id="event-media-volumechange" title="event-media-volumechange"><code>volumechange</code></dfn>
7603: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7604: </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.
7605: </td><td>
7606: </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
7607: </th><th>Interface
7608: </th><th>Dispatched when...
7609:
7610: </th></tr></thead><tbody><tr><td><dfn id="event-mediacontroller-emptied" title="event-MediaController-emptied"><code>emptied</code></dfn>
7611: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7612: </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>.
7613: </td></tr><tr><td><dfn id="event-mediacontroller-loadedmetadata" title="event-MediaController-loadedmetadata"><code>loadedmetadata</code></dfn>
7614: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7615: </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.
7616: </td></tr><tr><td><dfn id="event-mediacontroller-loadeddata" title="event-MediaController-loadeddata"><code>loadeddata</code></dfn>
7617: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7618: </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.
7619: </td></tr><tr><td><dfn id="event-mediacontroller-canplay" title="event-MediaController-canplay"><code>canplay</code></dfn>
7620: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7621: </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.
7622: </td></tr><tr><td><dfn id="event-mediacontroller-canplaythrough" title="event-MediaController-canplaythrough"><code>canplaythrough</code></dfn>
7623: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7624: </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.
7625: </td></tr><tr><td><dfn id="event-mediacontroller-playing" title="event-MediaController-playing"><code>playing</code></dfn>
7626: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7627: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is no longer a <a href="#blocked-media-controller">blocked media controller</a>.
7628: </td></tr><tr><td><dfn id="event-mediacontroller-waiting" title="event-MediaController-waiting"><code>waiting</code></dfn>
7629: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7630: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is now a <a href="#blocked-media-controller">blocked media controller</a>.
7631: </td></tr><tr><td><dfn id="event-mediacontcoller-ended" title="event-MediaContcoller-ended"><code>ended</code></dfn>
7632: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7633: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> have newly <a href="#ended-playback">ended playback</a>.
7634:
7635: </td></tr></tbody><tbody><tr><td><dfn id="event-mediacontroller-durationchange" title="event-MediaController-durationchange"><code>durationchange</code></dfn>
7636: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7637: </td><td>The <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code> attribute has just been updated.
7638: </td></tr><tr><td><dfn id="event-mediacontroller-timeupdate" title="event-MediaController-timeupdate"><code>timeupdate</code></dfn>
7639: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7640: </td><td>The <a href="#media-controller-position">media controller position</a> changed.
7641: </td></tr><tr><td><dfn id="event-mediacontroller-play" title="event-MediaController-play"><code>play</code></dfn>
7642: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7643: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly false.
7644: </td></tr><tr><td><dfn id="event-mediacontroller-pause" title="event-MediaController-pause"><code>pause</code></dfn>
7645: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7646: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly true.
7647: </td></tr><tr><td><dfn id="event-mediacontroller-ratechange" title="event-MediaController-ratechange"><code>ratechange</code></dfn>
7648: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7649: </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.
7650: </td></tr><tr><td><dfn id="event-mediacontroller-volumechange" title="event-MediaController-volumechange"><code>volumechange</code></dfn>
7651: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7652: </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.
7653: </td></tr></tbody></table><div class="impl">
7654:
7655: <h5 id="security-and-privacy-considerations"><span class="secno">4.8.10.16 </span>Security and privacy considerations</h5>
7656:
7657: <p>The main security and privacy implications of the
7658: <code><a href="#the-video-element">video</a></code> and <code><a href="#the-audio-element">audio</a></code> elements come from the
7659: ability to embed media cross-origin. There are two directions that
7660: threats can flow: from hostile content to a victim page, and from a
7661: hostile page to victim content.</p>
7662:
7663: <hr><p>If a victim page embeds hostile content, the threat is that the
7664: content might contain scripted code that attempts to interact with
7665: the <code><a href="infrastructure.html#document">Document</a></code> that embeds the content. To avoid this,
7666: user agents must ensure that there is no access from the content to
7667: the embedding page. In the case of media content that uses DOM
7668: concepts, the embedded content must be treated as if it was in its
7669: own unrelated <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>.</p>
7670:
7671: <p class="example">For instance, if an SVG animation was embedded in
7672: a <code><a href="#the-video-element">video</a></code> element, the user agent would not give it
7673: access to the DOM of the outer page. From the perspective of scripts
7674: in the SVG resource, the SVG file would appear to be in a lone
7675: top-level browsing context with no parent.</p>
7676:
7677: <hr><p>If a hostile page embeds victim content, the threat is that the
7678: embedding page could obtain information from the content that it
7679: would not otherwise have access to. The API does expose some
7680: information: the existence of the media, its type, its duration, its
7681: size, and the performance characteristics of its host. Such
7682: information is already potentially problematic, but in practice the
7683: same information can more or less be obtained using the
7684: <code><a href="embedded-content-1.html#the-img-element">img</a></code> element, and so it has been deemed acceptable.</p>
7685:
7686: <p>However, significantly more sensitive information could be
7687: obtained if the user agent further exposes metadata within the
7688: content such as subtitles or chapter titles. This version of the API
7689: does not expose such information. Future extensions to this API will
7690: likely reuse a mechanism such as CORS to check that the embedded
7691: content's site has opted in to exposing such information. <a href="references.html#refsCORS">[CORS]</a></p>
7692:
7693: <p class="example">An attacker could trick a user running within a
7694: corporate network into visiting a site that attempts to load a video
7695: from a previously leaked location on the corporation's intranet. If
7696: such a video included confidential plans for a new product, then
7697: being able to read the subtitles would present a confidentiality
7698: breach.</p>
7699:
7700: </div><h5 id="best-practices-for-authors-using-media-elements"><span class="secno">4.8.10.17 </span>Best practices for authors using media elements</h5><p><i>This section is non-normative.</i></p><p>Playing audio and video resources on small devices such as
7701: set-top boxes or mobile phones is often constrained by limited
7702: hardware resources in the device. For example, a device might only
7703: support three simultaneous videos. For this reason, it is a good
7704: practice to release resources held by <a href="#media-element" title="media
7705: element">media elements</a> when they are done playing, either by
7706: being very careful about removing all references to the element and
7707: allowing it to be garbage collected, or, even better, by removing
7708: the element's <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and
7709: any <code><a href="#the-source-element">source</a></code> element descendants, and invoking the
7710: 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,
7711: software, or format limitations can cause video frames to be dropped
7712: and audio to be choppy or muted.</p><div class="impl">
7713:
7714: <h5 id="best-practices-for-implementors-of-media-elements"><span class="secno">4.8.10.18 </span>Best practices for implementors of media elements</h5>
7715:
7716: <p><i>This section is non-normative.</i></p>
7717:
7718: <p>How accurately various aspects of the <a href="#media-element">media element</a>
7719: API are implemented is considered a quality-of-implementation issue.</p>
7720:
7721: <p>For example, when implementing the <code title="attr-media-buffered">buffered</code> attribute, how precise
7722: an implementation reports the ranges that have been buffered depends
7723: on how carefully the user agent inspects the data. Since the API
7724: reports ranges as times, but the data is obtained in byte streams, a
7725: user agent receiving a variable-bit-rate stream might only be able
7726: to determine precise times by actually decoding all of the data.
7727: User agents aren't required to do this, however; they can instead
7728: return estimates (e.g. based on the average bit rate seen so far)
7729: which get revised as more information becomes available.</p>
7730:
7731: <p>As a general rule, user agents are urged to be conservative
7732: rather than optimistic. For example, it would be bad to report that
7733: everything had been buffered when it had not.</p>
7734:
7735: <p>Another quality-of-implementation issue would be playing a video
7736: backwards when the codec is designed only for forward playback (e.g.
7737: there aren't many key frames, and they are far apart, and the
7738: intervening frames only have deltas from the previous frame). User
7739: agents could do a poor job, e.g. only showing key frames; however,
7740: better implementations would do more work and thus do a better job,
7741: e.g. actually decoding parts of the video forwards, storing the
7742: complete frames, and then playing the frames backwards.</p>
7743:
7744: <p>Similarly, while implementations are allowed to drop buffered
7745: data at any time (there is no requirement that a user agent keep all
7746: the media data obtained for the lifetime of the media element), it
7747: is again a quality of implementation issue: user agents with
7748: sufficient resources to keep all the data around are encouraged to
7749: do so, as this allows for a better user experience. For example, if
7750: the user is watching a live stream, a user agent could allow the
7751: user only to view the live video; however, a better user agent would
7752: buffer everything and allow the user to seek through the earlier
7753: material, pause it, play it forwards and backwards, etc.</p>
7754:
7755: <p>When multiple tracks are synchronised with a
7756: <code><a href="#mediacontroller">MediaController</a></code>, it is possible for scripts to add and
7757: remove media elements from the <code><a href="#mediacontroller">MediaController</a></code>'s list
7758: of <a href="#slaved-media-elements">slaved media elements</a>, even while these tracks are
7759: playing. How smoothly the media plays back in such situations is
7760: another quality-of-implementation issue.</p>
7761:
7762: <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
7763: document</a> and not reinserted before the next time the
7764: <a href="webappapis.html#event-loop">event loop</a> spins, implementations that are resource
7765: constrained are encouraged to take that opportunity to release all
7766: hardware resources (like video planes, networking resources, and
7767: data buffers) used by the <a href="#media-element">media element</a>. (User agents
7768: still have to keep track of the playback position and so forth,
7769: though, in case playback is later restarted.)</p>
7770:
1.1 mike 7771: </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