Annotation of html5/spec/the-iframe-element.html, revision 1.64
1.1 mike 1: <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN">
1.61 mike 2: <!DOCTYPE html>
1.46 mike 3: <html lang="en-US-x-Hixie" class="split chapter"><head><title>4.8.2 The iframe element — HTML5 </title><style type="text/css">
1.1 mike 4: pre { margin-left: 2em; white-space: pre-wrap; }
5: h2 { margin: 3em 0 1em 0; }
6: h3 { margin: 2.5em 0 1em 0; }
7: h4 { margin: 2.5em 0 0.75em 0; }
8: h5, h6 { margin: 2.5em 0 1em; }
9: h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
10: h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
11: p { margin: 1em 0; }
12: hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
13: dl, dd { margin-top: 0; margin-bottom: 0; }
14: dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
15: dt + dt { margin-top: 0; }
16: dd dt { margin-top: 0.25em; margin-bottom: 0; }
17: dd p { margin-top: 0; }
18: dd dl + p { margin-top: 1em; }
19: dd table + p { margin-top: 1em; }
20: p + * > li, dd li { margin: 1em 0; }
21: dt, dfn { font-weight: bold; font-style: normal; }
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.62 mike 193: </style><link href="http://www.w3.org/StyleSheets/TR/W3C-ED" rel="stylesheet" type="text/css"><style type="text/css">
1.1 mike 194:
195: .applies thead th > * { display: block; }
196: .applies thead code { display: block; }
197: .applies tbody th { whitespace: nowrap; }
198: .applies td { text-align: center; }
199: .applies .yes { background: yellow; }
200:
1.14 mike 201: .matrix, .matrix td { border: hidden; text-align: right; }
1.1 mike 202: .matrix { margin-left: 2em; }
203:
204: .dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
205: .dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
206: .dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
207:
1.17 mike 208: td.eg { border-width: thin; text-align: center; }
209:
1.1 mike 210: #table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
211: #table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
212: #table-example-1 caption { padding-bottom: 0.5em; }
213: #table-example-1 thead, #table-example-1 tbody { border: none; }
214: #table-example-1 th, #table-example-1 td { border: solid thin; }
215: #table-example-1 th { font-weight: normal; }
216: #table-example-1 td { border-style: none solid; vertical-align: top; }
217: #table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
218: #table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
219: #table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
220: #table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
221: #table-example-1 tbody td:first-child::after { content: leader(". "); }
222: #table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
223: #table-example-1 tbody td:first-child + td { width: 10em; }
224: #table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
225: #table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
226:
227: .apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
228: .apple-table-examples * { font-family: "Times", serif; }
229: .apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
230: .apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
231: .apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
232: .apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
233: .apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
234: .apple-table-examples td { text-align: right; vertical-align: top; }
235: .apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
236: .apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
237: .apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
238: .apple-table-examples sup { line-height: 0; }
239:
240: .details-example img { vertical-align: top; }
241:
1.40 mike 242: #base64-table {
243: white-space: nowrap;
244: font-size: 0.6em;
245: column-width: 6em;
246: column-count: 5;
247: column-gap: 1em;
248: -moz-column-width: 6em;
249: -moz-column-count: 5;
250: -moz-column-gap: 1em;
251: -webkit-column-width: 6em;
252: -webkit-column-count: 5;
253: -webkit-column-gap: 1em;
254: }
255: #base64-table thead { display: none; }
256: #base64-table * { border: none; }
257: #base64-table tbody td:first-child:after { content: ':'; }
258: #base64-table tbody td:last-child { text-align: right; }
259:
1.1 mike 260: #named-character-references-table {
1.19 mike 261: white-space: nowrap;
1.1 mike 262: font-size: 0.6em;
1.19 mike 263: column-width: 30em;
1.1 mike 264: column-gap: 1em;
1.19 mike 265: -moz-column-width: 30em;
1.1 mike 266: -moz-column-gap: 1em;
1.19 mike 267: -webkit-column-width: 30em;
1.1 mike 268: -webkit-column-gap: 1em;
269: }
1.19 mike 270: #named-character-references-table > table > tbody > tr > td:first-child + td,
1.1 mike 271: #named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
272: #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 273: #named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
1.1 mike 274:
1.2 mike 275: .glyph.control { color: red; }
276:
1.4 mike 277: @font-face {
278: font-family: 'Essays1743';
279: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
280: }
281: @font-face {
282: font-family: 'Essays1743';
283: font-weight: bold;
284: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
285: }
286: @font-face {
287: font-family: 'Essays1743';
288: font-style: italic;
289: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
290: }
291: @font-face {
292: font-family: 'Essays1743';
293: font-style: italic;
294: font-weight: bold;
295: src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
296: }
297:
1.1 mike 298: </style><style type="text/css">
299: .domintro:before { display: table; margin: -1em -0.5em -0.5em auto; width: auto; content: 'This box is non-normative. Implementation requirements are given below this box.'; color: black; font-style: italic; border: solid 2px; background: white; padding: 0 0.25em; }
1.61 mike 300: </style><link href="data:text/css," id="complete" rel="stylesheet" title="Complete specification"><link href="data:text/css,.impl%20%7B%20display:%20none;%20%7D%0Ahtml%20%7B%20border:%20solid%20yellow;%20%7D%20.domintro:before%20%7B%20display:%20none;%20%7D" id="author" rel="alternate stylesheet" title="Author documentation only"><link href="data:text/css,.impl%20%7B%20background:%20%23FFEEEE;%20%7D%20.domintro:before%20%7B%20background:%20%23FFEEEE;%20%7D" id="highlight" rel="alternate stylesheet" title="Highlight implementation requirements"><script type="text/javascript">
1.45 mike 301: function getCookie(name) {
302: var params = location.search.substr(1).split("&");
303: for (var index = 0; index < params.length; index++) {
304: if (params[index] == name)
305: return "1";
306: var data = params[index].split("=");
307: if (data[0] == name)
308: return unescape(data[1]);
309: }
310: var cookies = document.cookie.split("; ");
311: for (var index = 0; index < cookies.length; index++) {
312: var data = cookies[index].split("=");
313: if (data[0] == name)
314: return unescape(data[1]);
315: }
316: return null;
317: }
318: </script>
1.1 mike 319: <script src="link-fixup.js"></script>
1.36 mike 320: <link href="style.css" rel="stylesheet"><link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
1.1 mike 321: <link href="spec.html#contents" title="Table of contents" rel="index">
1.47 mike 322: <link href="the-canvas-element.html" title="4.8.11 The canvas element" rel="next">
1.54 mike 323: </head><body><div class="head" id="head">
1.1 mike 324: <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 325:
1.1 mike 326: <h1>HTML5</h1>
327: </div><div>
1.36 mike 328: <a href="embedded-content-1.html" class="prev">4.8 Embedded content</a> –
1.1 mike 329: <a href="spec.html#contents">Table of contents</a> –
1.47 mike 330: <a href="the-canvas-element.html" class="next">4.8.11 The canvas element</a>
331: <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>
332: <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>
333: <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>
334: <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>
335: <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 336:
1.25 mike 337: <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 338: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
339: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
340: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
341: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.16 mike 342: <dt>Contexts in which this element can be used:</dt>
1.1 mike 343: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
344: <dt>Content model:</dt>
1.18 mike 345: <dd>Text that conforms to <a href="#iframe-content-model">the requirements given in the prose</a>.</dd>
1.1 mike 346: <dt>Content attributes:</dt>
347: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
348: <dd><code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code></dd>
349: <dd><code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code></dd>
350: <dd><code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code></dd>
351: <dd><code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code></dd>
352: <dd><code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code></dd>
353: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
354: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
355: <dt>DOM interface:</dt>
356: <dd>
357: <pre class="idl">interface <dfn id="htmliframeelement">HTMLIFrameElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
358: attribute DOMString <a href="#dom-iframe-src" title="dom-iframe-src">src</a>;
359: attribute DOMString <a href="#dom-iframe-srcdoc" title="dom-iframe-srcdoc">srcdoc</a>;
360: attribute DOMString <a href="#dom-iframe-name" title="dom-iframe-name">name</a>;
361: [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>;
362: attribute boolean <a href="#dom-iframe-seamless" title="dom-iframe-seamless">seamless</a>;
363: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
364: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
365: readonly attribute Document <a href="#dom-iframe-contentdocument" title="dom-iframe-contentDocument">contentDocument</a>;
366: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-iframe-contentwindow" title="dom-iframe-contentWindow">contentWindow</a>;
367: };</pre>
368: </dd>
369: </dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
370: <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
371: gives the address of a page that the <a href="browsers.html#nested-browsing-context">nested browsing
372: context</a> is to contain. The attribute, if present, must be a
373: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
374: spaces</a>.</p><p>The <dfn id="attr-iframe-srcdoc" title="attr-iframe-srcdoc"><code>srcdoc</code></dfn>
375: attribute gives the content of the page that the <a href="browsers.html#nested-browsing-context">nested
1.32 mike 376: browsing context</a> is to contain. The value of the attribute is
377: 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 378: the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
379: syntax</a> that consists of the following syntactic components,
380: in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
381: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
382:
383: <li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
384:
385: </li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
386: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
387:
1.47 mike 388: <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 389:
390: <li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
391: <a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
392:
393: </ol><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="dom.html#xml-documents">XML documents</a>,
394: the attribute, if present, must have a value that matches the
395: production labeled <code><a href="infrastructure.html#document">document</a></code> in the XML
396: 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
397: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute are both
398: specified together, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code>
399: attribute takes priority. This allows authors to provide a fallback
400: <a href="urls.html#url">URL</a> for legacy user agents that do not support the
401: <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute.</p><div class="impl">
402:
403: <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
404: an element into a document">inserted into a document</a>, the
405: user agent must create a <a href="browsers.html#nested-browsing-context">nested browsing context</a>, and
406: then <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> for the
407: first time.</p>
408:
409: <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 410: browsing context</a> has its <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute set, changed, or
411: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.1 mike 412: attributes</a>.</p>
413:
414: <p>Similarly, whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a
415: <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 416: <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute set, changed, or
417: removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
1.46 mike 418: attributes</a>.</p>
1.1 mike 419: <p>When the user agent is to <dfn id="process-the-iframe-attributes">process the <code>iframe</code>
420: attributes</dfn>, it must run the first appropriate steps from the
421: following list:</p>
422:
423: <dl class="switch"><dt>If the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute
424: is specified</dt>
425:
1.46 mike 426: <dd><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 427: <a href="browsers.html#browsing-context">browsing context</a> to a resource whose
428: <a href="fetching-resources.html#content-type">Content-Type</a> is <code><a href="iana.html#text-html">text/html</a></code>, whose
429: <a href="urls.html#url">URL</a> is <code><a href="urls.html#about:srcdoc">about:srcdoc</a></code>, and whose data
430: consists of the value of the attribute. The resulting
431: <code><a href="infrastructure.html#document">Document</a></code> must be considered <a href="#an-iframe-srcdoc-document">an
432: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
433: document</a>.</p></dd>
1.1 mike 434:
435: <dt>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code>
436: attribute is specified but the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not</dt>
437:
438: <dd>
439:
440: <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,
441: jump to the <i title="">empty</i> step below.</p></li>
442:
443: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of
444: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute, relative
445: to the <code><a href="#the-iframe-element">iframe</a></code> element.</p></li>
446:
447: <li><p>If that is not successful, then jump to the <i title="">empty</i> step below.</p></li>
448:
449: <li><p>If the resulting <a href="urls.html#absolute-url">absolute URL</a> is an
450: <a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for the string
451: "<code><a href="fetching-resources.html#about:blank">about:blank</a></code>", and the user agent is processing this
452: <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first time, then jump to
453: the <i title="">empty</i> step below. (In cases other than the
454: first time, <code><a href="fetching-resources.html#about:blank">about:blank</a></code> is loaded
455: normally.)</p></li>
456:
1.46 mike 457: <li><p><a href="history.html#navigate">Navigate</a> the element's
1.34 mike 458: <a href="browsers.html#browsing-context">browsing context</a> to the resulting <a href="urls.html#absolute-url">absolute
1.1 mike 459: URL</a>.</p></li>
460:
461: </ol><p><i>Empty</i>: When the steps above require the user agent to
462: jump to the <i title="">empty</i> step, if the user agent is
463: processing this <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first
464: time, then the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
465: <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>
466: element. (After jumping to this step, the above steps are not
467: resumed.)</p>
468:
469: </dd>
470:
471: <dt>Otherwise</dt>
472:
473: <dd>
474:
475: <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>
476: named <code title="event-load">load</code> at the
477: <code><a href="#the-iframe-element">iframe</a></code> element.</p>
478:
479: </dd>
480:
481: </dl><p>Any <a href="history.html#navigate" title="navigate">navigation</a> required of the user
482: agent in the <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a>
483: algorithm must be completed with the <code><a href="#the-iframe-element">iframe</a></code> element's
484: document's <a href="browsers.html#browsing-context">browsing context</a> as the <a href="history.html#source-browsing-context">source
485: browsing context</a>.</p>
486:
1.8 mike 487: <p>Furthermore, if the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="history.html#session-history">session
488: history</a> contained only one <code><a href="infrastructure.html#document">Document</a></code> when the
489: <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> algorithm
490: was invoked, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
491: <code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
492: was created, then any <a href="history.html#navigate" title="navigate">navigation</a>
493: required of the user agent in that algorithm must be completed with
1.46 mike 494: <a href="history.html#replacement-enabled">replacement enabled</a>.</p>
1.1 mike 495: </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
496: the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is either
497: also not set or set but its value cannot be <a href="urls.html#resolve-a-url" title="resolve a
498: url">resolved</a>, the browsing context will remain at the
499: 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>
500: away from this page, the <code><a href="#the-iframe-element">iframe</a></code>'s corresponding
501: <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 502: 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">
503:
504: <div class="note">
505:
506: <p><a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">Removing</a>
507: an <code><a href="#the-iframe-element">iframe</a></code> from a <code><a href="infrastructure.html#document">Document</a></code> does not cause
508: its <a href="browsers.html#browsing-context">browsing context</a> to be discarded. Indeed, an
509: <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> can survive its
510: original parent <code><a href="infrastructure.html#document">Document</a></code> if its <code><a href="#the-iframe-element">iframe</a></code> is
511: moved to another <code><a href="infrastructure.html#document">Document</a></code>.</p>
512:
1.10 mike 513: <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
514: <code><a href="infrastructure.html#document">Document</a></code> and is then subsequently garbage collected,
515: this will likely mean (in the absence of other references) that the
516: <a href="browsers.html#child-browsing-context">child browsing context</a>'s <code><a href="browsers.html#windowproxy">WindowProxy</a></code>
517: object will become eligble for garbage collection, which will then
518: lead to that <a href="browsers.html#browsing-context">browsing context</a> being <a href="browsers.html#a-browsing-context-is-discarded" title="a
519: browsing context is discarded">discarded</a>, which will then
520: 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 521: document">discarded</a> also. This happens without notice to any
522: scripts running in that <code><a href="infrastructure.html#document">Document</a></code>; for example, no
523: <code title="event-unload">unload</code> events are fired (the
1.10 mike 524: "<a href="history.html#unload-a-document">unload a document</a>" steps are not run).</p>
1.9 mike 525:
526: </div>
527:
528: </div><div class="example">
1.1 mike 529:
530: <p>Here a blog uses the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute in conjunction
531: 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
532: below to provide users of user agents that support this feature
533: with an extra layer of protection from script injection in the blog
534: post comments:</p>
535:
536: <pre><article>
537: <h1>I got my own magazine!</h1>
538: <p>After much effort, I've finally found a publisher, and so now I
539: have my own magazine! Isn't that awesome?! The first issue will come
540: out in September, and we have articles about getting food, and about
541: getting in boxes, it's going to be great!</p>
542: <footer>
543: <p>Written by <a href="/users/cap">cap</a>.
544: <time pubdate>2009-08-21T23:32Z</time></p>
545: </footer>
546: <article>
547: <footer> At <time pubdate>2009-08-21T23:35Z</time>, <a href="/users/ch">ch</a> writes: </footer>
1.33 mike 548: <iframe seamless sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
1.1 mike 549: </article>
550: <article>
551: <footer> At <time pubdate>2009-08-21T23:44Z</time>, <a href="/users/cap">cap</a> writes: </footer>
1.33 mike 552: <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 553: </article>
554: <article>
555: <footer> At <time pubdate>2009-08-21T23:58Z</time>, <a href="/users/ch">ch</a> writes: </footer>
1.33 mike 556: <iframe seamless sandbox srcdoc="<p>hey that's earl's table.
1.1 mike 557: <p>you should get earl&amp;amp;me on the next cover."></iframe>
558: </article></pre>
559:
560: <p>Notice the way that quotes have to be escaped (otherwise the
561: <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute would
562: end prematurely), and the way raw ampersands (e.g. in URLs or in
563: prose) mentioned in the sandboxed content have to be
564: <em>doubly</em> escaped — once so that the ampersand is
565: preserved when originally parsing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and once more
566: to prevent the ampersand from being misinterpreted when parsing the
567: sandboxed content.</p>
568:
569: </div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
570: remember to use U+0022 QUOTATION MARK characters (") to wrap the
571: attribute contents and then to escape all U+0022 QUOTATION MARK (")
572: 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
573: embedding of content.</p><p class="note">Due to restrictions of <span>the XML syntax</span>,
1.24 mike 574: in XML the U+003C LESS-THAN SIGN character (<) needs to be
575: escaped as well. In order to prevent <a href="http://www.w3.org/TR/REC-xml/#AVNormalize">attribute-value
1.39 mike 576: normalization</a>, some of XML's whitespace characters —
1.52 mike 577: specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
1.39 mike 578: (LF), and U+000D CARRIAGE RETURN (CR) — also need to be
579: 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 580: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
581: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
582: browsing context</a>. <span class="impl">When the browsing
583: context is created, if the attribute is present, the <a href="browsers.html#browsing-context-name">browsing
584: context name</a> must be set to the value of this attribute;
585: otherwise, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set to the
586: empty string.</span></p><div class="impl">
587:
588: <p>Whenever the <code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code> attribute
589: 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
590: value. If the attribute is removed, the <a href="browsers.html#browsing-context-name">browsing context
591: name</a> must be set to the empty string.</p>
592:
593: <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
594: 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
595: a simple event</a> named <code title="event-load">load</code> at
596: the <code><a href="#the-iframe-element">iframe</a></code> element. When content whose <a href="urls.html#url">URL</a>
597: has the <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code>
598: element's <code><a href="infrastructure.html#document">Document</a></code> fails to load (e.g. due to a DNS
599: error, network error, or if the server returned a 4xx or 5xx status
600: code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or
601: equivalent</a>), then the user agent must <a href="webappapis.html#queue-a-task">queue a
602: 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
603: does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
604: script errors, or any errors for cross-origin resources.)</p>
605:
606: <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
607: task source</a>.</p>
608:
609: <p class="note">A <code title="event-load">load</code> event is also
610: fired at the <code><a href="#the-iframe-element">iframe</a></code> element when it is created if no
611: other data is loaded in it.</p>
612:
613: <p>When there is an <a href="dom.html#active-parser">active parser</a> in the
614: <code><a href="#the-iframe-element">iframe</a></code>, and when anything in the <code><a href="#the-iframe-element">iframe</a></code> is
615: <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
616: the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a>'s
617: <a href="browsers.html#active-document">active document</a>, the <code><a href="#the-iframe-element">iframe</a></code> must
618: <a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
619:
620: <p class="note">If, during the handling of the <code title="event-load">load</code> event, the <a href="browsers.html#browsing-context">browsing
621: 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
622: load event</a>.</p>
623:
624: </div><hr><p>The <dfn id="attr-iframe-sandbox" title="attr-iframe-sandbox"><code>sandbox</code></dfn>
625: attribute, when specified, enables a set of extra restrictions on
626: any content hosted by the <code><a href="#the-iframe-element">iframe</a></code>. Its value must be an
1.20 mike 627: <a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique space-separated tokens</a> that are
628: <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 629: <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>,
630: <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code>,
631: and <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>. When
632: the attribute is set, the content is treated as being from a unique
633: <a href="origin-0.html#origin">origin</a>, forms and scripts are disabled, links are
634: prevented from targeting other <a href="browsers.html#browsing-context" title="browsing
635: context">browsing contexts</a>, and plugins are disabled. The
636: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
637: keyword allows the content to be treated as being from the same
638: 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>
639: keyword allows the content to <a href="history.html#navigate">navigate</a> its
640: <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>
641: keywords re-enable forms and scripts respectively (though scripts
642: 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
643: <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
644: keywords together when the embedded page has the <a href="origin-0.html#same-origin">same
645: origin</a> as the page containing the <code><a href="#the-iframe-element">iframe</a></code> allows
646: 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
647: an attacker can convince the user to just visit the hostile content
648: directly, rather than in the <code><a href="#the-iframe-element">iframe</a></code>. To limit the
649: damage that can be caused by hostile HTML content, it should be
650: served using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME type.</p><div class="impl">
651:
1.46 mike 652:
1.1 mike 653: <p>While the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
654: attribute is specified, the <code><a href="#the-iframe-element">iframe</a></code> element's
655: <a href="browsers.html#nested-browsing-context">nested browsing context</a> must have the flags given in
656: the following list set. In addition, any browsing contexts <a href="browsers.html#nested-browsing-context" title="nested browsing context">nested</a> within an
657: <code><a href="#the-iframe-element">iframe</a></code>, either directly or indirectly, must have all
658: the flags set on them as were set on the <code><a href="#the-iframe-element">iframe</a></code>'s
659: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> when the
660: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
661:
662: <dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
663:
664: <dd>
665:
666: <p>This flag <a href="history.html#sandboxLinks">prevents content from
667: navigating browsing contexts other than the sandboxed browsing
668: context itself</a> (or browsing contexts further nested inside
669: it), and the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> (which is
670: protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
671: context flag</a> defined next).</p>
672:
673: <p>This flag also <a href="browsers.html#sandboxWindowOpen">prevents content
674: from creating new auxiliary browsing contexts</a>, e.g. using the
675: <code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute or the
676: <code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> method.</p>
677:
678: </dd>
679:
680:
681: <dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
682: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
683: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
684: 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>
685: keyword set</dt>
686:
687: <dd>
688:
689: <p>This flag <a href="history.html#sandboxLinks">prevents content from
690: navigating their <span>top-level browsing context</span></a>.</p>
691:
692: <p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
693: is set, content can navigate its <a href="browsers.html#top-level-browsing-context">top-level browsing
694: context</a>, but other <a href="browsers.html#browsing-context" title="browsing context">browsing
695: contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
696: navigation browsing context flag</a> defined above.</p>
697:
698: </dd>
699:
700:
701: <dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
702:
703: <dd>
704:
705: <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>,
706: <a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
707: element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
708: browsing context</a>.</p>
709:
710: </dd>
711:
712:
713: <dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
714:
715: <dd>
716:
717: <p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attribute on
718: descendant <code><a href="#the-iframe-element">iframe</a></code> elements.</p>
719:
720: <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>
721: keyword from using a CSS-selector-based method of probing the DOM
722: of other pages on the same site (in particular, pages that contain
723: user-sensitive information).</p>
724:
1.46 mike 725:
1.1 mike 726:
727: </dd>
728:
729:
730: <dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn>, unless
731: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
732: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
733: 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>
734: keyword set</dt>
735:
736: <dd>
737:
738: <p>This flag <a href="origin-0.html#sandboxOrigin">forces content into a unique
739: origin</a>, thus preventing it from accessing other content from
740: the same <a href="origin-0.html#origin">origin</a>.</p>
741:
742: <p>This flag also <a href="dom.html#sandboxCookies">prevents script from
743: reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
1.38 mike 744: attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code>.
1.1 mike 745:
746: <a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
747:
748: </p>
749:
750: <div class="note">
751:
752: <p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
753: attribute is intended for two cases.</p>
754:
755: <p>First, it can be used to allow content from the same site to
756: be sandboxed to disable scripting, while still allowing access to
757: the DOM of the sandboxed content.</p>
758:
759: <p>Second, it can be used to embed content from a third-party
760: site, sandboxed to prevent that site from opening popup windows,
761: etc, without preventing the embedded page from communicating back
762: to its originating site, using the database APIs to store data,
763: etc.</p>
764:
765: </div>
766:
767: </dd>
768:
769:
770: <dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn>, unless
771: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
772: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
773: 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>
774: keyword set</dt>
775:
776: <dd>
777:
778: <p>This flag <a href="association-of-controls-and-forms.html#sandboxSubmitBlocked">blocks form
779: submission</a>.</p>
780:
781: </dd>
782:
783:
784: <dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn>, unless
785: the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
786: value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
787: 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>
788: keyword set</dt>
789:
790: <dd>
791:
792: <p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
793: execution</a>.</p>
794:
795: </dd>
796:
797:
798: <dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
799: flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
800: <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
801: found to have the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
802: keyword (defined above) set</dt>
803:
804: <dd>
805:
806: <p>This flag blocks features that trigger automatically, such as
1.47 mike 807: <a href="#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
1.1 mike 808: video</a> or <a href="association-of-controls-and-forms.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
809: focusing a form control</a>. It is relaxed by the same flag as
810: scripts, because when scripts are enabled these features are
811: trivially possible anyway, and it would be unfortunate to force
812: authors to use script to do them when sandboxed rather than
813: allowing them to use the declarative features.</p>
814:
815: </dd>
816:
817: </dl><p>These flags must not be set unless the conditions listed above
818: define them as being set.</p>
819:
820: <p class="warning">These flags only take effect when the
821: <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 822: <a href="history.html#navigate" title="navigate">navigated</a>. Removing them, or removing
1.1 mike 823: the entire <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
824: attribute, has no effect on an already-loaded page.</p>
825:
826: </div><div class="example">
827:
828: <p>In this example, some completely-unknown, potentially hostile,
829: user-provided HTML content is embedded in a page. Because it is
830: sandboxed, it is treated by the user agent as being from a unique
831: origin, despite the content being served from the same site. Thus
832: it is affected by all the normal cross-site restrictions. In
833: addition, the embedded page has scripting disabled, plugins
834: disabled, forms disabled, and it cannot navigate any frames or
835: windows other than itself (or any frames or windows it itself
836: embeds).</p>
837:
838: <pre><p>We're not scared of you! Here is your content, unedited:</p>
839: <iframe sandbox src="getusercontent.cgi?id=12193"></iframe></pre>
840:
841: <p>Note that cookies are still sent to the server in the <code title="">getusercontent.cgi</code> request, though they are not
842: visible in the <code title="dom-document-cookie"><a href="dom.html#dom-document-cookie">document.cookie</a></code> IDL
843: attribute.</p>
844:
845: <p class="warning">It is important that the server serve the
846: user-provided HTML using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME
847: type so that if the attacker convinces the user to visit that page
848: directly, the page doesn't run in the context of the site's origin,
849: which would make the user vulnerable to any attack found in the
850: page.</p>
851:
852: </div><div class="example">
853:
854: <p>In this example, a gadget from another site is embedded. The
855: gadget has scripting and forms enabled, and the origin sandbox
856: restrictions are lifted, allowing the gadget to communicate with
857: its originating server. The sandbox is still useful, however, as it
858: disables plugins and popups, thus reducing the risk of the user
859: being exposed to malware and other annoyances.</p>
860:
861: <pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
862: src="http://maps.example.com/embedded.html"></iframe></pre>
863:
864: </div><div class="example">
865:
866: <p>Suppose a file A contained the following fragment:</p>
867:
868: <pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
869:
870: <p>Suppose that file B contained an iframe also:</p>
871:
872: <pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
873:
874: <p>Further, suppose that file C contained a link:</p>
875:
876: <pre><a href=D>Link</a></pre>
877:
878: <p>For this example, suppose all the files were served as
879: <code><a href="iana.html#text-html">text/html</a></code>.</p>
880:
881: <p>Page C in this scenario has all the sandboxing flags
882: set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
883: scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
884: keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
885: disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
886: have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
887: set.</p>
888:
889: <p>Suppose now that a script in A removes all the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attributes in A and
890: B. This would change nothing immediately. If the user clicked the
891: link in C, loading page D into the <code><a href="#the-iframe-element">iframe</a></code> in B, page D
892: would now act as if the <code><a href="#the-iframe-element">iframe</a></code> in B had the <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
893: and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
894: set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
895: context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
896: loaded.</p>
897:
898: <p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
899: ill-advised, because it can make it quite hard to reason about what
900: will be allowed and what will not.</p>
901:
902: </div><p class="note">Potentially hostile files can be served from the
903: same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code> element
904: by labeling them as <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> instead of
905: <code><a href="iana.html#text-html">text/html</a></code>. This ensures that scripts in the files are
906: unable to attack the site (as if they were actually served from
907: another server), even if the user is tricked into visiting those
908: 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>
909: 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>
910: keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
911: <code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
912: "sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
913: reload itself, effectively breaking out of the sandbox
1.46 mike 914: altogether.</p><hr><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
1.1 mike 915: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
916: indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
917: context</a> is to be rendered in a manner that makes it appear to
918: be part of the containing document (seamlessly included in the
919: parent document). <span class="impl">Specifically, when the
920: attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
921: <code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
922: the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
923: <code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
924: <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
925: <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
926: document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
927: document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
928: address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
1.33 mike 929: <code><a href="#the-iframe-element">iframe</a></code> element's document, or the <a href="browsers.html#browsing-context">browsing
930: context</a>'s <a href="browsers.html#active-document">active document</a> is <a href="#an-iframe-srcdoc-document">an
931: <code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
932: document</a>, the following requirements apply:</span></p><div class="impl">
1.1 mike 933:
1.13 mike 934: <ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
935: flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
936: will <a href="history.html#seamlessLinks">cause links to open in the parent
937: browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
938: override</a> is used (<code title="">target="_self"</code>).</p></li>
1.1 mike 939:
940: <li><p>In a CSS-supporting user agent: the user agent must add all
941: the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
942: the cascade of the <a href="browsers.html#active-document">active document</a> of the
943: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
944: at the appropriate cascade levels, before any style sheets
945: specified by the document itself.</p></li>
946:
947: <li><p>In a CSS-supporting user agent: the user agent must, for the
948: purpose of CSS property inheritance only, treat the root element of
949: the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
950: element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
951: the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
952: root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
953: inherit the computed values of those properties on the
954: <code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
955: values.)</p></li>
956:
957: <li><p>In visual media, in a CSS-supporting user agent: the user agent
958: should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
959: width that the element would have if it was a non-replaced
960: block-level element with 'width: auto'.</p></li>
961:
962: <li><p>In visual media, in a CSS-supporting user agent: the user
963: agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
964: the height of the bounding box around the content rendered in the
965: <code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
966: bullet point), as it would be if the scrolling position was such
967: that the top of the viewport for the content rendered in the
968: <code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
969: canvas.</p></li>
970:
971: <li>
972:
973: <p>In visual media, in a CSS-supporting user agent: the user agent
974: must force the height of the initial containing block of the
975: <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
976: context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
977:
978: <p class="note">This is intended to get around the otherwise
979: circular dependency of percentage dimensions that depend on the
980: height of the containing block, thus affecting the height of the
981: document's bounding box, thus affecting the height of the
982: viewport, thus affecting the size of the initial containing
983: block.</p>
984:
985: </li>
986:
987: <li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
988: browsing context</a> without announcing that it is a separate
989: document.</p></li>
990:
991: <li>
992:
993: <p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
994: document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
995: context</a> was part of the document that the
1.35 mike 996: <code><a href="#the-iframe-element">iframe</a></code> is in, if any.</p>
1.1 mike 997:
998: <p class="example">For example if the user agent supports listing
999: all the links in a document, links in "seamlessly" nested
1000: documents would be included in that list without being
1001: significantly distinguished from links in the document itself.</p>
1002:
1003: </li>
1004:
1005: </ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
1006: conditions listed above are not met, then the user agent should
1007: render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
1008: clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
1009: and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
1010: false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
1011:
1012: <p class="warning">It is important that user agents recheck the
1013: above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
1014: <a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
1015: changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
1016: 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>
1017:
1018: </div><p class="note">The attribute can be set or removed dynamically,
1019: with the rendering updating in tandem.</p><div class="example">
1020:
1021: <p>In this example, the site's navigation is embedded using a
1022: client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
1023: <code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
1024: opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
1025: legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
1026: element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
1027: attribute with the value <code title="">_parent</code>. Similarly,
1028: in new user agents the styles of the parent page will be
1029: automatically applied to the contents of the frame, but to support
1030: legacy user agents authors might wish to include the styles
1031: explicitly.</p>
1032:
1033: <pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
1034:
1035: </div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1036: attributes</a> for cases where the embedded content has specific
1037: 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
1038: content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
1039: context</a>, regardless of whether the specified initial contents
1040: are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
1041: nothing. (In legacy user agents that do not support
1042: <code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
1.18 mike 1043: that could act as fallback content.)</p><p id="iframe-content-model">When used in <a href="dom.html#html-documents">HTML
1044: documents</a>, the allowed content model of <code><a href="#the-iframe-element">iframe</a></code>
1045: elements is text, except that invoking the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment
1046: parsing algorithm</a> with the <code><a href="#the-iframe-element">iframe</a></code> element as the
1.48 mike 1047: <var title="concept-frag-parse-context"><a href="the-end.html#concept-frag-parse-context">context</a></var> element and
1048: the text contents as the <var title="">input</var> must result in a
1049: list of nodes that are all <a href="content-models.html#phrasing-content">phrasing content</a>, with no
1050: <a href="parsing.html#parse-error" title="parse error">parse errors</a> having occurred, with
1051: no <code><a href="scripting-1.html#the-script-element">script</a></code> elements being anywhere in the list or as
1.18 mike 1052: descendants of elements in the list, and with all the elements in
1053: the list (including their descendants) being themselves
1054: 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 1055: documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
1056: <code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
1057:
1058: <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
1059: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1060: name.</p>
1061:
1062: <p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
1063: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1064: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
1065: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1066:
1067: <p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
1068: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1069: <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
1070: context</a>.</p>
1071:
1072: </div><div class="example">
1073:
1074: <p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
1075: include advertising from an advertising broker:</p>
1076:
1077: <pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
1078: width="468" height="60"></iframe></pre>
1079:
1.46 mike 1080: </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 1081: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1082: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1083: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1084: <dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
1.16 mike 1085: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1086: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1087: <dt>Content model:</dt>
1088: <dd>Empty.</dd>
1089: <dt>Content attributes:</dt>
1090: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1091: <dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
1092: <dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
1093: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1094: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1095: <dd>Any other attribute that has no namespace (see prose).</dd>
1096: <dt>DOM interface:</dt>
1097: <dd>
1098: <pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1099: attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
1100: attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
1101: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1102: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1103: };</pre>
1104: <div class="impl">
1105: <p>Depending on the type of content instantiated by the
1106: <code><a href="#the-embed-element">embed</a></code> element, the node may also support other
1107: interfaces.</p>
1108: </div>
1109: </dd>
1110: </dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
1111: integration point for an external (typically non-HTML) application
1112: or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
1113: gives the address of the resource being embedded. The attribute, if
1114: present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
1115: surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
1116: attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
1117: plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
1118: MIME type</a>. If both the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute and the <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute are present, then the
1119: <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
1120: same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
1121: metadata</a> of the resource given by the <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute.</p><div class="impl">
1122:
1123: <p>When the element is created with neither a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code> attribute nor a <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute, and when attributes
1124: are removed such that neither attribute is present on the element
1.47 mike 1125: anymore, and when the element has a <a href="#media-element">media element</a>
1.1 mike 1126: ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
1127: element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
1128: content</a>, any plugins instantiated for the element must be
1129: removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
1130:
1131: <p id="sandboxPluginEmbed">If either:
1132:
1133: </p><ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1134: set on the <a href="browsers.html#browsing-context">browsing context</a> for which the
1135: <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> is the
1136: <a href="browsers.html#active-document">active document</a> when that <code><a href="infrastructure.html#document">Document</a></code> was
1137: created, or</li>
1138:
1139: <li>the <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1140: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1141: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1142: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1143:
1144: </ul><p>...then the user agent must render the <code><a href="#the-embed-element">embed</a></code> element
1145: in a manner that conveys that the <a href="infrastructure.html#plugin">plugin</a> was
1146: disabled. The user agent may offer the user the option to override
1147: the sandbox and instantiate the <a href="infrastructure.html#plugin">plugin</a> anyway; if the
1148: user invokes such an option, the user agent must act as if the
1149: conditions above did not apply for the purposes of this element.</p>
1150:
1151: <p class="warning">Plugins are disabled in sandboxed browsing
1152: contexts because they might not honor the restrictions imposed by
1153: the sandbox (e.g. they might allow scripting even when scripting in
1154: the sandbox is disabled). User agents should convey the danger of
1155: overriding the sandbox to the user if an option to do so is
1156: provided.</p>
1157:
1158: <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
1159: following conditions are all met simultaneously:</p>
1160:
1161: <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>
1162: <li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
1163: <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>
1164: <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>
1165: <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>
1166: <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 1167: <li>The element is not a descendant of a <a href="#media-element">media element</a>.</li>
1.1 mike 1168: <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>
1169: </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
1170: a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1171: <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
1172: removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
1173: <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
1174: removed, the appropriate set of steps from the following is then
1175: applied:</p>
1176:
1177: <dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1178: attribute set</dt>
1179:
1180: <dd>
1181:
1182: <p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
1183: the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1184: attribute, relative to the element. If that is successful, the
1185: user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
1186: URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
1.46 mike 1187: origin</a> if it has one. The <a href="webappapis.html#concept-task" title="concept-task">task</a> that is
1.1 mike 1188: <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking
1189: task source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
1190: 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
1191: <a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
1.46 mike 1192: previously instantiated plugin for the element.</p>
1.1 mike 1193: <p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
1194: the element's document.</p>
1.46 mike 1195:
1196:
1.1 mike 1197: </dd>
1198:
1199: <dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
1200: attribute set</dt>
1201:
1202: <dd><p>The user agent should find and instantiate an appropriate
1203: <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>
1204:
1205: </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
1206: <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
1207: <a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
1208: be unloaded.</p>
1209:
1210: <p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
1211: CSS 'display' property. The selected plugin is instantiated even if
1212: the element is hidden with a 'display:none' CSS style.</p>
1213:
1214: <p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
1215: being embedded is defined as follows:</p>
1216:
1217: <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
1218: value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
1219: of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
1220: <a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
1221:
1222: <li>
1223:
1.46 mike 1224:
1.1 mike 1225: <p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
1226: component of the <a href="urls.html#url">URL</a> of the specified resource (after
1227: any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1228: supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
1229: type</a> is the type that that plugin can handle.</p>
1230:
1231: <p class="example">For example, a plugin might say that it can
1232: handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
1233: components that end with the four character string "<code title="">.swf</code>".</p>
1234:
1.46 mike 1235:
1236:
1.1 mike 1237:
1238: </li>
1239:
1240: <li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
1241: that is the <a href="#concept-embed-type" title="concept-embed-type">content's
1242: type</a>.</p></li>
1243:
1244: <li><p>Otherwise, the content has no type and there can be no
1245: appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
1246:
1.46 mike 1247:
1.1 mike 1248:
1249: </ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
1250: content</a>. If the user agent can't find a suitable plugin, then
1251: the user agent must use a default plugin. (This default could be as
1252: simple as saying "Unsupported Format".)</p>
1253:
1254: <p>Whether the resource is fetched successfully or not (e.g. whether
1255: 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
1256: ignored when determining the resource's type and when handing the
1257: resource to the plugin.</p>
1258:
1259: <p class="note">This allows servers to return data for plugins even
1260: with error responses (e.g. HTTP 500 Internal Server Error codes can
1261: still contain plugin data).</p>
1262:
1.46 mike 1263: </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 1264: so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
1265: characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
1266: LATIN CAPITAL LETTER Z). These attributes are then passed as
1267: 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
1268: lowercased automatically, so the restriction on uppercase letters
1269: doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
1270: that have side-effects beyond just sending parameters to the
1271: <a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
1272:
1273: <p>The user agent should pass the names and values of all the
1274: attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
1275: to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
1276:
1277: <p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
1278: <code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
1279: <code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
1280: expose that interface while the element is instantiated.</p>
1281:
1282: </div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1283: attributes</a>.</p><div class="impl">
1284:
1285: <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
1286: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1287: name.</p>
1288:
1289: </div><div class="example">
1290:
1291: <p>Here's a way to embed a resource that requires a proprietary
1292: plug-in, like Flash:</p>
1293:
1294: <pre><embed src="catgame.swf"></pre>
1295:
1296: <p>If the user does not have the plug-in (for example if the
1297: plug-in vendor doesn't support the user's platform), then the user
1298: will be unable to use the resource.</p>
1299:
1300: <p>To pass the plugin a parameter "quality" with the value "high",
1301: an attribute can be specified:</p>
1302:
1303: <pre><embed src="catgame.swf" quality="high"></pre>
1304:
1305: <p>This would be equivalent to the following, when using an
1306: <code><a href="#the-object-element">object</a></code> element instead:</p>
1307:
1308: <pre><object data="catgame.swf">
1309: <param name="quality" value="high">
1310: </object></pre>
1311:
1.15 mike 1312: </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 1313: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
1314: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
1315: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
1.46 mike 1316: <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 1317: <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 1318: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1319: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
1320: <dt>Content model:</dt>
1321: <dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
1322: <dt>Content attributes:</dt>
1323: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1324: <dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
1325: <dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
1326: <dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
1327: <dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
1328: <dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
1329: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
1330: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
1331: <dt>DOM interface:</dt>
1332: <dd>
1333: <pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1334: attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
1335: attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
1336: attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
1337: attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
1338: 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>;
1339: attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
1340: attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
1341: readonly attribute Document <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
1342: readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
1343:
1344: readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
1345: 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>;
1346: readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
1347: boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
1348: void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(in DOMString error);
1349: };</pre>
1350: <div class="impl">
1351: <p>Depending on the type of content instantiated by the
1352: <code><a href="#the-object-element">object</a></code> element, the node also supports other
1353: interfaces.</p>
1354: </div>
1355: </dd>
1356: </dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
1357: resource, which, depending on the type of the resource, will either
1358: be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1359: or as an external resource to be processed by a
1360: <a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
1361: attribute, if present, specifies the address of the resource. If
1362: present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1363: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-object-type" title="attr-object-type"><code>type</code></dfn>
1364: attribute, if present, specifies the type of the resource. If
1365: present, the attribute must be a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>.</p><p>At least one of either the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute or the <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute must be present.</p><p>The <dfn id="attr-object-name" title="attr-object-name"><code>name</code></dfn>
1366: attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
1367: name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
1368: browsing context</a>, if applicable.</p><div class="impl">
1369:
1370: <p>When the element is created, when it is popped off the
1371: <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
1372: or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
1373: <a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
1374: document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
1375: document">removed from a document</a>; and whenever the element's
1376: <code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
1377: active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
1378: changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
1379: whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
1380: 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,
1381: whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
1382: 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
1383: its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
1384: changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
1385: to run the following steps to (re)determine what the
1386: <code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
1387: 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 1388: manipulation task source</a>.</p>
1.1 mike 1389: <ol><li>
1390:
1391: <p>If the user has indicated a preference that this
1392: <code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
1393: shown instead of the element's usual behavior, then jump to the
1394: last step in the overall set of steps (fallback).</p>
1395:
1396: <p class="note">For example, a user could ask for the element's
1397: <a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
1398: uses a format that the user finds more accessible.</p>
1399:
1400: </li>
1401:
1402: <li>
1403:
1.47 mike 1404: <p>If the element has an ancestor <a href="#media-element">media element</a>, or
1.1 mike 1405: has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
1406: showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
1407: not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
1408: with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
1409: <code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
1410: element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
1411: <a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
1412: the last step in the overall set of steps (fallback).</p>
1413:
1414: </li>
1415:
1416: <li>
1417:
1.46 mike 1418:
1.1 mike 1419: <p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
1420: attribute is present, and has a value that isn't the empty string,
1421: then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
1422: 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>,
1423: then that <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be
1424: 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
1425: passed to the <a href="infrastructure.html#plugin">plugin</a>. If no suitable
1426: <a href="infrastructure.html#plugin">plugin</a> can be found, or if the <a href="infrastructure.html#plugin">plugin</a>
1427: reports an error, jump to the last step in the overall set of
1428: steps (fallback).</p>
1429:
1.46 mike 1430:
1.1 mike 1431: </li>
1432:
1.46 mike 1433:
1.1 mike 1434: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1435: is present and its value is not the empty string, then:</p>
1436:
1437: <ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1438: attribute is present and its value is not a type that the user
1439: agent supports, and is not a type that the user agent can find a
1440: <a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
1441: step in the overall set of steps (fallback) without fetching the
1442: content to examine its real type.</p></li>
1443:
1444: <li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
1445: <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
1446: element.</p></li>
1447:
1448: <li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1449: <code title="event-error">error</code> at the element, then jump
1450: to the last step in the overall set of steps (fallback).</p></li>
1451:
1452: <li>
1453:
1454: <p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
1455: from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
1.46 mike 1456: it has one.</p>
1.1 mike 1457:
1.46 mike 1458: <p>Fetching the resource
1.1 mike 1459: must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
1460: 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
1461: source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
1462:
1.41 mike 1463: <p>For the purposes of the <a href="offline.html#application-cache">application cache</a>
1464: networking model, this <a href="fetching-resources.html#fetch">fetch</a> operation is not for a
1465: <a href="browsers.html#child-browsing-context">child browsing context</a> (though it might end up
1466: being used for one after all, as defined below).</p>
1467:
1.1 mike 1468: </li>
1469:
1470: <li><p>If the resource is not yet available (e.g. because the
1471: resource was not available in the cache, so that loading the
1472: resource required making a request over the network), then jump
1473: to the last step in the overall set of steps (fallback). The
1474: <a href="webappapis.html#concept-task" title="concept-task">task</a> that is <a href="webappapis.html#queue-a-task" title="queue
1475: a task">queued</a> by the <a href="webappapis.html#networking-task-source">networking task source</a>
1476: once the resource is available must restart this algorithm from
1477: this step. Resources can load incrementally; user agents may opt
1478: to consider a resource "available" whenever enough data has been
1479: obtained to begin processing the resource.</p></li>
1480:
1481: <li><p>If the load failed (e.g. there was an HTTP 404 error,
1482: there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
1483: <code title="event-error">error</code> at the element, then jump
1484: to the last step in the overall set of steps (fallback).</p></li>
1485:
1486: <li id="object-type-detection">
1487:
1488: <p>Determine the <var title="">resource type</var>, as follows:</p>
1489:
1490:
1491: <ol><li>
1492:
1493: <p>Let the <var title="">resource type</var> be unknown.</p>
1494:
1495: </li>
1496:
1497: <li>
1498:
1.46 mike 1499:
1.1 mike 1500:
1501: <p>If the user agent is configured to strictly obey
1502: Content-Type headers for this resource, and the resource has
1503: <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1504: metadata</a>, then let the <var title="">resource
1505: type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1506: metadata</a>, and jump to the step below labeled
1507: <i>handler</i>.</p>
1508:
1509: </li>
1510:
1511: <li>
1512:
1513: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1514: attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
1515: attribute's value is not a type that the user agent supports,
1516: but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
1517: then let the <var title="">resource type</var> be the type
1518: specified in that <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1519: attribute, and jump to the step below labeled
1520: <i>handler</i>.</p>
1521:
1522: </li>
1523:
1524: <li>
1525:
1526: <p>Run the approprate set of steps from the following
1527: list:</p>
1528:
1529: <dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
1530: Content-Type metadata</a></dt>
1531:
1532: <dd>
1533:
1534: <ol><li>
1535:
1536: <p>Let <var title="">binary</var> be false.</p>
1537:
1538: </li>
1539:
1540: <li>
1541:
1542: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1543: resource's Content-Type metadata</a> is
1544: "<code>text/plain</code>", and the result of applying the
1545: <a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
1.49 mike 1546: for distinguishing if a resource is text or binary</a>
1.1 mike 1547: to the resource is that the resource is not
1548: <code>text/plain</code>, then set <var title="">binary</var> to true.</p>
1549:
1550: </li>
1551:
1552: <li>
1553:
1554: <p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
1555: resource's Content-Type metadata</a> is
1556: "<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
1557:
1558: </li>
1559:
1560: <li>
1561:
1562: <p>If <var title="">binary</var> is false, then let the
1563: <var title="">resource type</var> be the type specified in
1564: <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
1565: metadata</a>, and jump to the step below labeled
1566: <i>handler</i>.</p>
1567:
1568: </li>
1569:
1570: <li>
1571:
1572: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1573: the <code><a href="#the-object-element">object</a></code> element, and its value is not
1574: <code>application/octet-stream</code>, then run the
1575: following steps:</p>
1576:
1577: <ol><li>
1578:
1579: <p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
1580: 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>,
1581: 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>
1582:
1583: </li>
1584:
1585: <li>
1586:
1587: <p>Jump to the step below labeled <i>handler</i>.</p>
1588:
1589: </li>
1590:
1591: </ol></li>
1592:
1593: </ol></dd>
1594:
1595: <dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
1596: metadata</a></dt>
1597:
1598: <dd>
1599:
1600: <ol><li>
1601:
1602: <p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
1603: 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
1604: <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
1605:
1606: <p>Otherwise, let <var title="">tentative type</var> be the
1607: <a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
1608: resource</a>.</p>
1609:
1610: </li>
1611:
1612: <li>
1613:
1614: <p>If <var title="">tentative type</var> is <em>not</em>
1615: <code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
1616: type</var> and jump to the step below labeled
1617: <i>handler</i>.</p>
1618:
1619: </li>
1620:
1621: </ol></dd>
1622:
1623: </dl></li>
1624:
1625: <li>
1626:
1.46 mike 1627:
1.1 mike 1628: <p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
1629: of the <a href="urls.html#url">URL</a> of the specified resource (after any
1630: redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
1631: supports, then let <var title="">resource type</var> be the
1632: type that that plugin can handle.</p>
1633:
1634: <p class="example">For example, a plugin might say that it can
1635: handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
1636: the four character string "<code title="">.swf</code>".</p>
1637:
1.46 mike 1638:
1639:
1.1 mike 1640:
1641: </li>
1642:
1643: </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
1644: the substeps above to jump straight to the next step. In both
1645: cases, the next step will trigger fallback.</p>
1646:
1647: </li>
1648:
1649: <li><p><i>Handler</i>: Handle the content as given by the first
1650: of the following cases that matches:</p>
1651:
1652: <dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
1653: the user agent supports, but it <em>is</em> a type that a
1654: <a href="infrastructure.html#plugin">plugin</a> supports</dt>
1655:
1656: <dd>
1657:
1658: <p>If <a href="#sandboxPluginObject">plugins are being
1659: sandboxed</a>, jump to the last step in the overall set of
1660: steps (fallback).</p>
1661:
1662: <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
1663: resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
1664: <a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
1665: step in the overall set of steps (fallback).</p>
1666:
1667: </dd>
1668:
1669:
1670: <dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
1671: type</a>, or
1.46 mike 1672:
1.1 mike 1673: if the <var title="">resource type</var> does not start with
1674: "<code>image/</code>"</dt>
1675:
1676: <dd>
1677:
1678: <p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
1679: newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
1680: not already have one.</p>
1681:
1682: <p>If the <a href="urls.html#url">URL</a> of the given resource is not
1683: <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 1684: context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that
1.34 mike 1685: resource, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
1.1 mike 1686: <code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
1.34 mike 1687: context</a> as the <a href="history.html#source-browsing-context">source browsing context</a>.
1688: (The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of
1689: the <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
1.1 mike 1690: browsing context gets further navigated to other
1691: locations.)</p>
1692:
1693: <p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
1694: <code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, the user agent must
1695: <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>
1696: named <code title="event-load">load</code> at the
1697: <code><a href="#the-object-element">object</a></code> element.</p>
1698:
1699: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1700: <a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
1701:
1702: <p>If the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1703: is present, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1704: to the value of this attribute; otherwise, the <a href="browsers.html#browsing-context-name">browsing
1705: context name</a> must be set to the empty string.</p>
1706:
1.41 mike 1707: <p class="note">In certain situations, e.g. if the resource
1708: was <a href="fetching-resources.html#fetch" title="fetch">fetched</a> from an
1709: <a href="offline.html#application-cache">application cache</a> but it is an HTML file with a
1710: <code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> attribute
1711: that points to a different <a href="offline.html#concept-appcache-manifest" title="concept-appcache-manifest">application cache
1712: manifest</a>, the <a href="history.html#navigate" title="navigate">navigation</a>
1713: of the <a href="browsers.html#browsing-context">browsing context</a> will be restarted so as
1714: to load the resource afresh from the network or a different
1715: <a href="offline.html#application-cache">application cache</a>. Even if the resource is then
1716: found to have a different type, it is still used as part of a
1717: <a href="browsers.html#nested-browsing-context">nested browsing context</a>: only the
1718: <a href="history.html#navigate">navigate</a> algorithm is restarted, not this
1719: <code><a href="#the-object-element">object</a></code> algorithm.</p>
1.1 mike 1720:
1.46 mike 1721:
1.1 mike 1722:
1723: </dd>
1724:
1725:
1726: <dt>If the <var title="">resource type</var> starts with
1727: "<code>image/</code>", and support for images has not been
1728: disabled</dt>
1729:
1730: <dd>
1731:
1732: <p>Apply the <a href="fetching-resources.html#content-type-sniffing:-image" title="content-type sniffing: image">image
1733: sniffing</a> rules to determine the type of the image.</p>
1734:
1735: <p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
1736: specified image. The image is not a <a href="browsers.html#nested-browsing-context">nested browsing
1737: context</a>.</p>
1738:
1739: <p>If the image cannot be rendered, e.g. because it is
1740: malformed or in an unsupported format, jump to the last step
1741: in the overall set of steps (fallback).</p>
1742:
1743: </dd>
1744:
1745:
1746: <dt>Otherwise</dt>
1747:
1748: <dd>
1749:
1750: <p>The given <var title="">resource type</var> is not
1751: supported. Jump to the last step in the overall set of steps
1752: (fallback).</p>
1753:
1754: <p class="note">If the previous step ended with the <var title="">resource type</var> being unknown, this is the case
1755: that is triggered.</p>
1756:
1757: </dd>
1758:
1759: </dl></li>
1760:
1761: <li><p>The element's contents are not part of what the
1762: <code><a href="#the-object-element">object</a></code> element represents.</p>
1763:
1764: </li><li>
1765:
1766: <p>Once the resource is completely loaded, <a href="webappapis.html#queue-a-task">queue a
1767: 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>
1768:
1.46 mike 1769: <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 1770: source</a>.</p>
1771:
1772: </li>
1773:
1774: </ol></li>
1775:
1776: <li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
1777: is absent but the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
1778: attribute is present, <a href="#sandboxPluginObject">plugins aren't
1779: being sandboxed</a>, and the user agent can find a
1780: <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
1781: <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
1782: no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
1783: <a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the next step
1784: (fallback).</p></li>
1785:
1786: <li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
1787: <a href="rendering.html#represents">represents</a> the element's children, ignoring any
1788: leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
1789: <a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
1790: <a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
1791:
1792: </ol><p id="object-plugin">When the algorithm above instantiates a
1793: <a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
1794: <a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
1795: on the element, in the order they were added to the element, with
1796: the attributes added by the parser being ordered in source order,
1797: followed by a parameter named "PARAM" whose value is null,
1798: followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
1799: <code><a href="#the-param-element">param</a></code> elements that are children of the
1800: <code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
1801: <a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
1802: <code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
1803: should expose that interface. The <code><a href="#the-object-element">object</a></code> element
1804: <a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
1805: <a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
1806: context</a>.</p>
1807:
1808: <p id="sandboxPluginObject">If either:</p>
1809:
1810: <ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
1811: set on the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s
1812: <a href="browsers.html#browsing-context">browsing context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was
1813: created, or</li>
1814:
1815: <li>the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
1816: parsed from a resource whose <a href="fetching-resources.html#content-type-sniffing-0" title="Content-Type
1817: sniffing">sniffed type</a> as determined during <a href="history.html#navigate" title="navigate">navigation</a> is
1818: <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code></li>
1819:
1820: </ul><p>...then the steps above must always act as if they had failed to
1821: find a <a href="infrastructure.html#plugin">plugin</a>, even if one would otherwise have been
1822: used.</p>
1823:
1824: <p class="note">The above algorithm is independent of CSS properties
1825: (including 'display', 'overflow', and 'visibility'). For example, it
1826: runs even if the element is hidden with a 'display:none' CSS style,
1827: and does not run <em>again</em> if the element's visibility
1828: changes.</p>
1829:
1830: <p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
1831: elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
1832: referenced resources can't be shown (e.g. because it returned a 404
1833: error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
1834: nested inside each other, targeting multiple user agents with
1835: different capabilities, with the user agent picking the first one it
1836: supports.</p>
1837:
1838: <p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
1839: is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
1840: <a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
1841: name">name</a> must be changed to the new value. If the attribute
1842: is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
1843: context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
1844: to the empty string.</p>
1845:
1846: </div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
1847: if present while the <code><a href="#the-object-element">object</a></code> element represents an
1848: image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
1849: map</a>. <span class="impl">The attribute must be ignored if the
1850: <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
1851: explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
1852: <a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
1853:
1854: <p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
1855: elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
1856: validation</a>.</p>
1857:
1858: </div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
1859: attributes</a>.</p><div class="impl">
1860:
1861: <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
1862: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1863: name.</p>
1864:
1865: <p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
1866: IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
1867: <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
1868: <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
1869: must return null.</p>
1870:
1871: <p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
1872: IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
1873: <code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
1874: if it has one; otherwise, it must return null.</p>
1875:
1876: <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>
1877: 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>
1878: methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
1879: <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
1880: element's forms API.</p>
1881:
1882: </div><div class="example">
1883:
1884: <p>In the following example, a Java applet is embedded in a page
1885: using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
1886: better to avoid using applets like these and instead use native
1887: JavaScript and HTML to provide the functionality, since that way
1888: the application will work on all Web browsers without requiring a
1889: third-party plugin. Many devices, especially embedded devices, do
1890: not support third-party technologies like Java.)</p>
1891:
1892: <pre><figure>
1893: <object type="application/x-java-applet">
1894: <param name="code" value="MyJavaClass">
1895: <p>You do not have Java available, or it is disabled.</p>
1896: </object>
1897: <figcaption>My Java Clock</figcaption>
1898: </figure></pre>
1899:
1900: </div><div class="example">
1901:
1902: <p>In this example, an HTML page is embedded in another using the
1903: <code><a href="#the-object-element">object</a></code> element.</p>
1904:
1905: <pre><figure>
1906: <object data="clock.html"></object>
1907: <figcaption>My HTML Clock</figcaption>
1908: </figure></pre>
1909:
1910: </div><div class="example">
1911:
1912: <p>The following example shows how a plugin can be used in HTML (in
1913: this case the Flash plugin, to show a video file). Fallback is
1914: provided for users who do not have Flash enabled, in this case
1.47 mike 1915: using the <code><a href="#the-video-element">video</a></code> element to show the video for those
1916: using user agents that support <code><a href="#the-video-element">video</a></code>, and finally
1.1 mike 1917: providing a link to the video for those who have neither Flash nor
1.47 mike 1918: a <code><a href="#the-video-element">video</a></code>-capable browser.</p>
1.1 mike 1919:
1920: <pre><p>Look at my video:
1921: <object type="application/x-shockwave-flash">
1922: <param name=movie value="http://video.example.com/library/watch.swf">
1923: <param name=allowfullscreen value=true>
1924: <param name=flashvars value="http://video.example.com/vids/315981">
1925: <video controls src="http://video.example.com/vids/315981">
1926: <a href="http://video.example.com/vids/315981">View video</a>.
1927: </video>
1928: </object>
1929: </p></pre>
1930:
1.15 mike 1931: </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 1932: <dd>None.</dd>
1.16 mike 1933: <dt>Contexts in which this element can be used:</dt>
1.1 mike 1934: <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>
1935: <dt>Content model:</dt>
1936: <dd>Empty.</dd>
1937: <dt>Content attributes:</dt>
1938: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
1939: <dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
1940: <dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
1941: <dt>DOM interface:</dt>
1942: <dd>
1943: <pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
1944: attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
1945: attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
1946: };</pre>
1947: </dd>
1948: </dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
1949: 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>
1950: attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
1951: attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
1952:
1953: <p>If both attributes are present, and if the parent element of the
1954: <code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
1955: element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
1956: name/value pair.</p>
1957:
1.23 mike 1958: <p>If either the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> defined by a
1959: <code><a href="#the-param-element">param</a></code> element that is the child of an
1960: <code><a href="#the-object-element">object</a></code> element that <a href="rendering.html#represents">represents</a> an
1961: instantiated <a href="infrastructure.html#plugin">plugin</a> changes, and if that
1962: <a href="infrastructure.html#plugin">plugin</a> is communicating with the user agent using an
1963: API that features the ability to update the <a href="infrastructure.html#plugin">plugin</a> when
1964: the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> so changes, then
1965: the user agent must appropriately exercise that ability to notify
1966: the <a href="infrastructure.html#plugin">plugin</a> of the change.</p>
1967:
1.1 mike 1968: <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
1969: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
1970: name.</p>
1971:
1972: </div><div class="example">
1973:
1974: <p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
1975: can be used to pass a parameter to a plugin, in this case the O3D
1976: plugin.</p>
1977:
1978: <pre><!DOCTYPE HTML>
1979: <html lang="en">
1.6 mike 1980: <head>
1981: <title>O3D Utah Teapot</title>
1982: </head>
1983: <body>
1984: <p>
1985: <object type="application/vnd.o3d.auto">
1986: <strong><param name="o3d_features" value="FloatingPointTextures"></strong>
1987: <img src="o3d-teapot.png"
1988: title="3D Utah Teapot illustration rendered using O3D."
1989: alt="When O3D renders the Utah Teapot, it appears as a squat
1990: teapot with a shiny metallic finish on which the
1991: surroundings are reflected, with a faint shadow caused by
1992: the lighting.">
1993: <p>To see the teapot actually rendered by O3D on your
1994: computer, please download and install the <a
1995: href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
1996: </object>
1997: <script src="o3d-teapot.js"></script>
1998: </p>
1999: </body>
1.1 mike 2000: </html></pre>
2001:
1.47 mike 2002: </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>
2003: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2004: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2005: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2006: <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>
2007: <dt>Contexts in which this element can be used:</dt>
2008: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2009: <dt>Content model:</dt>
2010: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2011: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2012: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2013: <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
2014: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2015: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2016: <dt>Content attributes:</dt>
2017: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2018: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2019: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2020: <dd><code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code></dd>
2021: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2022: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2023: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2024: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2025: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2026: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2027: <dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
2028: <dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
2029: <dt>DOM interface:</dt>
2030: <dd>
2031: <pre class="idl">interface <dfn id="htmlvideoelement">HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {
2032: attribute unsigned long <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
2033: attribute unsigned long <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
2034: readonly attribute unsigned long <a href="#dom-video-videowidth" title="dom-video-videoWidth">videoWidth</a>;
2035: readonly attribute unsigned long <a href="#dom-video-videoheight" title="dom-video-videoHeight">videoHeight</a>;
2036: attribute DOMString <a href="#dom-video-poster" title="dom-video-poster">poster</a>;
2037: };</pre>
2038: </dd>
2039: </dl><p>A <code><a href="#the-video-element">video</a></code> element is used for playing videos or
2040: movies, and audio files with captions.</p><p>Content may be provided inside the <code><a href="#the-video-element">video</a></code>
2041: element<span class="impl">. User agents should not show this content
2042: to the user</span>; it is intended for older Web browsers which do
2043: not support <code><a href="#the-video-element">video</a></code>, so that legacy video plugins can be
2044: tried, or to show text to the users of these older browsers informing
2045: them of how to access the video contents.</p><p class="note">In particular, this content is not intended to
2046: address accessibility concerns. To make video content accessible to
2047: the blind, deaf, and those with other physical or cognitive
2048: disabilities, authors are expected to provide alternative media
2049: streams and/or to embed accessibility aids (such as caption or
2050: subtitle tracks, audio description tracks, or sign-language
2051: 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>
2052: whose <a href="#media-data">media data</a> is ostensibly video data, possibly
2053: 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>,
2054: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2055: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2056: <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
2057: elements</a>.</p><p>The <dfn id="attr-video-poster" title="attr-video-poster"><code>poster</code></dfn>
2058: attribute gives the address of an image file that the user agent can
2059: show while no video data is available. The attribute, if present,
2060: must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2061: spaces</a>.</p><div class="impl">
2062:
2063: <p>If the specified resource is to be used, then, when the element
2064: is created or when the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
2065: attribute is set, changed, or removed, the user agent must run the
2066: following steps to determine the element's <dfn id="poster-frame">poster
2067: frame</dfn>:</p>
2068: <ol><li><p>If there is an existing instance of this algorithm running
2069: for this <code><a href="#the-video-element">video</a></code> element, abort that instance of this
2070: algorithm without changing the <a href="#poster-frame">poster frame</a>.</p></li>
2071:
2072: <li><p>If the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
1.51 mike 2073: attribute's value is the empty string or if the attribute is
2074: absent, then there is no <a href="#poster-frame">poster frame</a>; abort these
2075: steps.</p></li>
1.47 mike 2076:
2077: <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
2078: to the element. If this fails, then there is no <a href="#poster-frame">poster
2079: frame</a>; abort these steps.</p></li>
2080:
2081: <li><p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
2082: from the element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>.
2083: This must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's
2084: document.</p></li>
2085:
2086:
2087:
2088: <li><p>If an image is thus obtained, the <a href="#poster-frame">poster frame</a>
2089: is that image. Otherwise, there is no <a href="#poster-frame">poster
2090: frame</a>.</p></li>
2091:
2092: </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
2093: frame</a></i>, is intended to be a representative frame of the video
2094: (typically one of the first non-blank frames) that gives the user an
2095: idea of what the video is like.</p><div class="impl">
2096:
2097: <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
2098: <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
2099: 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
2100: subsequent value but the <a href="#media-resource">media resource</a> does not have a
2101: video channel), the <code><a href="#the-video-element">video</a></code> element
2102: <a href="rendering.html#represents">represents</a> either the <a href="#poster-frame">poster frame</a>, or
2103: nothing.</p>
2104:
2105: <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
2106: playback position">current playback position</a> is the first
2107: frame of video, the element <a href="rendering.html#represents">represents</a> either the frame
2108: of video corresponding to the <a href="#current-playback-position" title="current playback
2109: position">current playback position</a> or the <a href="#poster-frame">poster
2110: frame</a>, at the discretion of the user agent.</p>
2111:
2112: <p>Notwithstanding the above, the <a href="#poster-frame">poster frame</a> should
2113: be preferred over nothing, but the <a href="#poster-frame">poster frame</a> should
2114: not be shown again after a frame of video has been shown.</p>
2115:
2116: <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
2117: the <a href="#media-resource">media resource</a> has a video channel, the element
2118: <a href="rendering.html#represents">represents</a> the frame of video corresponding to the
2119: <a href="#current-playback-position" title="current playback position">current playback
2120: position</a>, or, if that is not yet available (e.g. because the
2121: video is seeking or buffering), the last frame of the video to have
2122: been rendered.</p>
2123:
2124: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2125: resource</a> has a video channel is <a href="#potentially-playing">potentially
2126: playing</a>, it <a href="rendering.html#represents">represents</a> the frame of video at the
2127: continuously increasing <a href="#current-playback-position" title="current playback
2128: position">"current" position</a>. When the <a href="#current-playback-position">current playback
2129: position</a> changes such that the last frame rendered is no
2130: longer the frame corresponding to the <a href="#current-playback-position">current playback
2131: position</a> in the video, the new frame must be rendered.
2132:
2133: Similarly, any audio associated with the <a href="#media-resource">media resource</a>
2134: must, if played, be played synchronized with the <a href="#current-playback-position">current
2135: playback position</a>, at the element's <a href="#effective-media-volume">effective media
2136: volume</a>.</p>
2137:
2138: <p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
2139: resource</a> has a video channel is neither <a href="#potentially-playing">potentially
2140: playing</a> nor <a href="#dom-media-paused" title="dom-media-paused">paused</a>
2141: (e.g. when seeking or stalled), the element <a href="rendering.html#represents">represents</a>
2142: the last frame of the video to have been rendered.</p>
2143:
2144: <p class="note">Which frame in a video stream corresponds to a
2145: particular playback position is defined by the video stream's
2146: format.</p>
2147:
2148: <p>The <code><a href="#the-video-element">video</a></code> element also <a href="rendering.html#represents">represents</a> any
2149: <a href="#text-track-cue" title="text track cue">text track cues</a> whose
2150: <a href="#text-track-cue-active-flag">text track cue active flag</a> is set and whose
2151: <a href="#text-track">text track</a> is in the <a href="#text-track-showing" title="text track
2152: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track showing by
2153: default">showing by default</a> modes.</p>
2154:
2155: <p>In addition to the above, the user agent may provide messages to
2156: the user (such as "buffering", "no video loaded", "error", or more
2157: detailed information) by overlaying text or icons on the video or
2158: other areas of the element's playback area, or in another
2159: appropriate manner.</p>
2160:
2161: <p>User agents that cannot render the video may instead make the
2162: element <a href="rendering.html#represents" title="represents">represent</a> a link to an
2163: external video playback utility or to the video data itself.</p>
2164:
2165: <hr></div><dl class="domintro"><dt><var title="">video</var> . <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code></dt>
2166: <dt><var title="">video</var> . <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code></dt>
2167:
2168: <dd>
2169:
2170: <p>These attributes return the intrinsic dimensions of the video,
2171: or zero if the dimensions are not known.</p>
2172:
2173: </dd>
2174:
2175: </dl><div class="impl">
2176:
2177: <p>The <dfn id="concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2178: width</dfn> and <dfn id="concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</dfn> of the
2179: <a href="#media-resource">media resource</a> are the dimensions of the resource in
2180: CSS pixels after taking into account the resource's dimensions,
2181: aspect ratio, clean aperture, resolution, and so forth, as defined
2182: for the format used by the resource. If an anamorphic format does
2183: not define how to apply the aspect ratio to the video data's
2184: dimensions to obtain the "correct" dimensions, then the user agent
2185: must apply the ratio by increasing one dimension and leaving the
2186: other unchanged.</p>
2187:
2188: <p>The <dfn id="dom-video-videowidth" title="dom-video-videoWidth"><code>videoWidth</code></dfn> IDL
2189: attribute must return the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> of the
2190: video in CSS pixels. The <dfn id="dom-video-videoheight" title="dom-video-videoHeight"><code>videoHeight</code></dfn> IDL
2191: attribute must return the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> of
2192: 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
2193: attributes must return 0.</p>
2194:
2195: </div><p>The <code><a href="#the-video-element">video</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
2196: attributes</a>.</p><div class="impl">
2197:
2198: <p>In the absence of style rules to the contrary, video content
2199: should be rendered inside the element's playback area such that the
2200: video content is shown centered in the playback area at the largest
2201: possible size that fits completely within it, with the video
2202: content's aspect ratio being preserved. Thus, if the aspect ratio of
2203: the playback area does not match the aspect ratio of the video, the
2204: video will be shown letterboxed or pillarboxed. Areas of the
2205: element's playback area that do not contain the video represent
2206: nothing.</p>
2207:
2208: <p class="note">In user agents that implement CSS, the above
2209: requirement can be implemented by using the <a href="rendering.html#video-object-fit">style rule suggested in the rendering
2210: section</a>.</p>
2211:
2212: <p>The intrinsic width of a <code><a href="#the-video-element">video</a></code> element's playback
2213: area is the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
2214: width</a> of the video resource, if that is available; otherwise
2215: it is the intrinsic width of the <a href="#poster-frame">poster frame</a>, if that
2216: is available; otherwise it is 300 CSS pixels.</p>
2217:
2218: <p>The intrinsic height of a <code><a href="#the-video-element">video</a></code> element's playback
2219: area is the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic
2220: height</a> of the video resource, if that is available; otherwise
2221: it is the intrinsic height of the <a href="#poster-frame">poster frame</a>, if that
2222: is available; otherwise it is 150 CSS pixels.</p>
2223:
2224: <hr><p>User agents should provide controls to enable or disable the
2225: display of closed captions, audio description tracks, and other
2226: additional data associated with the video stream, though such
2227: features should, again, not interfere with the page's normal
2228: rendering.</p>
2229:
2230: <p>User agents may allow users to view the video content in manners
2231: more suitable to the user (e.g. full-screen or in an independent
2232: resizable window). As for the other user interface features,
2233: controls to enable this should not interfere with the page's normal
2234: rendering unless the user agent is <a href="#expose-a-user-interface-to-the-user" title="expose a user
2235: interface to the user">exposing a user interface</a>. In such an
2236: independent context, however, user agents may make full user
2237: interfaces visible, with, e.g., play, pause, seeking, and volume
2238: controls, even if the <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute is absent.</p>
2239:
2240: <p>User agents may allow video playback to affect system features
2241: that could interfere with the user's experience; for example, user
2242: agents could disable screensavers while video playback is in
2243: progress.</p>
2244:
2245: <hr><p>The <dfn id="dom-video-poster" title="dom-video-poster"><code>poster</code></dfn> IDL
2246: 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>
2247:
2248: </div><div class="example">
2249:
2250: <p>This example shows how to detect when a video has failed to play
2251: correctly:</p>
2252:
2253: <pre><script>
2254: function failed(e) {
2255: // video playback failed - show a message saying why
2256: switch (e.target.error.code) {
2257: case e.target.error.MEDIA_ERR_ABORTED:
2258: alert('You aborted the video playback.');
2259: break;
2260: case e.target.error.MEDIA_ERR_NETWORK:
2261: alert('A network error caused the video download to fail part-way.');
2262: break;
2263: case e.target.error.MEDIA_ERR_DECODE:
2264: alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
2265: break;
2266: case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
2267: alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
2268: break;
2269: default:
2270: alert('An unknown error occurred.');
2271: break;
2272: }
2273: }
2274: </script>
2275: <p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
2276: <p><a href="tgif.vid">Download the video file</a>.</p></pre>
2277:
2278: </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>
2279: <dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
2280: <dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
2281: <dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
2282: <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>
2283: <dt>Contexts in which this element can be used:</dt>
2284: <dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
2285: <dt>Content model:</dt>
2286: <dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
2287: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2288: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2289: <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
2290: zero or more <code><a href="#the-track-element">track</a></code> elements, then
2291: <a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
2292: <dt>Content attributes:</dt>
2293: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2294: <dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
1.61 mike 2295: <dd><code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code></dd>
1.47 mike 2296: <dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
2297: <dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
2298: <dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
2299: <dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
2300: <dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
2301: <dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
2302: <dt>DOM interface:</dt>
2303: <dd>
2304: <pre class="idl">[NamedConstructor=<a href="#dom-audio" title="dom-Audio">Audio</a>(),
2305: NamedConstructor=<a href="#dom-audio-s" title="dom-Audio-s">Audio</a>(in DOMString src)]
2306: interface <dfn id="htmlaudioelement">HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {};</pre>
2307: </dd>
2308: </dl><p>An <code><a href="#the-audio-element">audio</a></code> element <a href="rendering.html#represents">represents</a> a sound or
2309: audio stream.</p><p>Content may be provided inside the <code><a href="#the-audio-element">audio</a></code>
2310: element<span class="impl">. User agents should not show this content
2311: to the user</span>; it is intended for older Web browsers which do
2312: not support <code><a href="#the-audio-element">audio</a></code>, so that legacy audio plugins can be
2313: tried, or to show text to the users of these older browsers informing
2314: them of how to access the audio contents.</p><p class="note">In particular, this content is not intended to
2315: address accessibility concerns. To make audio content accessible to
2316: the deaf or to those with other physical or cognitive disabilities,
2317: authors are expected to provide alternative media streams and/or to
2318: embed accessibility aids (such as transcriptions) into their media
2319: streams.</p><p>The <code><a href="#the-audio-element">audio</a></code> element is a <a href="#media-element">media element</a>
2320: 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>,
2321: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2322: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2323: <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
2324: elements</a>.</p><div class="impl">
2325:
2326: <p>When an <code><a href="#the-audio-element">audio</a></code> element is <a href="#potentially-playing">potentially
2327: playing</a>, it must have its audio data played synchronized with
2328: the <a href="#current-playback-position">current playback position</a>, at the element's
2329: <a href="#effective-media-volume">effective media volume</a>.</p>
2330:
2331: <p>When an <code><a href="#the-audio-element">audio</a></code> element is not <a href="#potentially-playing">potentially
2332: playing</a>, audio must not play for the element.</p>
2333:
2334: </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>
2335:
2336: <dd>
2337:
2338: <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
2339: passed in the argument, if applicable.</p>
2340:
2341: </dd>
2342:
2343: </dl><div class="impl">
2344:
2345: <p>Two constructors are provided for creating
2346: <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> objects (in addition to the factory
2347: 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,
2348: these must return a new <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new
2349: <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
2350: 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
2351: its <code title="attr-media-src"><a href="#attr-media-src">src</a></code> content attribute set to
2352: the provided value, and the user agent must invoke the object's
2353: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2354: algorithm</a> before returning. The element's document must be
2355: the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
2356: context</a> of the <code><a href="browsers.html#window">Window</a></code> object on which the
2357: interface object of the invoked constructor is found.</p>
2358:
2359: </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>
2360: <dd>None.</dd>
2361: <dt>Contexts in which this element can be used:</dt>
2362: <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>
2363: or <code><a href="#the-track-element">track</a></code> elements.</dd>
2364: <dt>Content model:</dt>
2365: <dd>Empty.</dd>
2366: <dt>Content attributes:</dt>
2367: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2368: <dd><code title="attr-source-src"><a href="#attr-source-src">src</a></code></dd>
2369: <dd><code title="attr-source-type"><a href="#attr-source-type">type</a></code></dd>
2370: <dd><code title="attr-source-media"><a href="#attr-source-media">media</a></code></dd>
2371: <dt>DOM interface:</dt>
2372: <dd>
2373: <pre class="idl">interface <dfn id="htmlsourceelement">HTMLSourceElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2374: attribute DOMString <a href="#dom-source-src" title="dom-source-src">src</a>;
2375: attribute DOMString <a href="#dom-source-type" title="dom-source-type">type</a>;
2376: attribute DOMString <a href="#dom-source-media" title="dom-source-media">media</a>;
2377: };</pre>
2378: </dd>
2379: </dl><p>The <code><a href="#the-source-element">source</a></code> element allows authors to specify
2380: multiple alternative <a href="#media-resource" title="media resource">media
2381: resources</a> for <a href="#media-element" title="media element">media
2382: 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
2383: gives the address of the <a href="#media-resource">media resource</a>. The value must
2384: be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2385: spaces</a>. This attribute must be present.</p><p class="note">Dynamically modifying a <code><a href="#the-source-element">source</a></code> element
2386: and its attribute when the element is already inserted in a
2387: <code><a href="#the-video-element">video</a></code> or <code><a href="#the-audio-element">audio</a></code> element will have no
1.62 mike 2388: effect. To change what is playing, just use the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute on the <a href="#media-element">media
2389: element</a> directly, possibly making use of the <code title="dom-navigator-canPlayType"><a href="#dom-navigator-canplaytype">canPlayType()</a></code> method to
2390: pick from amongst available resources. Generally, manipulating
2391: <code><a href="#the-source-element">source</a></code> elements manually after the document has been
2392: parsed is an unncessarily complicated approach.</p><p>The <dfn id="attr-source-type" title="attr-source-type"><code>type</code></dfn>
1.47 mike 2393: attribute gives the type of the <a href="#media-resource">media resource</a>, to help
2394: the user agent determine if it can play this <a href="#media-resource">media
2395: resource</a> before fetching it. If specified, its value must be
2396: a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>. The <code title="">codecs</code>
2397: parameter, which certain MIME types define, might be necessary to
2398: specify exactly how the resource is encoded. <a href="references.html#refsRFC4281">[RFC4281]</a></p><div class="example">
2399:
2400: <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>
2401:
2402: <dl><dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2403: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></pre></dd>
2404:
2405: <dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2406: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></pre></dd>
2407:
2408: <dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
2409: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></pre></dd>
2410:
2411: <dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
2412: <dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></pre></dd>
2413:
2414:
2415: <dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2416: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></pre></dd>
2417:
2418: <dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
2419: <dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></pre></dd>
2420:
2421: <dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
2422: <dd><pre><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></pre></dd>
2423:
2424:
2425: <dt>Theora video and Vorbis audio in Ogg container</dt>
2426: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></pre></dd>
2427:
2428: <dt>Theora video and Speex audio in Ogg container</dt>
2429: <dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></pre></dd>
2430:
2431: <dt>Vorbis audio alone in Ogg container</dt>
2432: <dd><pre><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></pre></dd>
2433:
2434: <dt>Speex audio alone in Ogg container</dt>
2435: <dd><pre><source src='audio.spx' type='audio/ogg; codecs=speex'></pre></dd>
2436:
2437: <dt>FLAC audio alone in Ogg container</dt>
2438: <dd><pre><source src='audio.oga' type='audio/ogg; codecs=flac'></pre></dd>
2439:
2440: <dt>Dirac video and Vorbis audio in Ogg container</dt>
2441: <dd><pre><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></pre></dd>
2442:
2443:
2444:
2445:
2446:
2447:
2448: </dl></div><p>The <dfn id="attr-source-media" title="attr-source-media"><code>media</code></dfn>
2449: attribute gives the intended media type of the <a href="#media-resource">media
2450: resource</a>, to help the user agent determine if this
2451: <a href="#media-resource">media resource</a> is useful to the user before fetching
2452: 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
2453: "<code title="">all</code>", meaning that by default the <a href="#media-resource">media
2454: resource</a> is suitable for all media.</p><div class="impl">
2455:
2456: <p>If a <code><a href="#the-source-element">source</a></code> element is inserted as a child of a
2457: <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
2458: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, the user
2459: 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
2460: algorithm</a>.</p>
2461:
2462: <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
2463: <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
2464: name.</p>
2465:
2466: </div><div class="example">
2467:
2468: <p>If the author isn't sure if the user agents will all be able to
2469: render the media resources provided, the author can listen to the
2470: <code title="event-error">error</code> event on the last
2471: <code><a href="#the-source-element">source</a></code> element and trigger fallback behavior:</p>
2472:
2473: <pre><script>
2474: function fallback(video) {
2475: // replace <video> with its contents
2476: while (video.hasChildNodes()) {
2477: if (video.firstChild instanceof HTMLSourceElement)
2478: video.removeChild(video.firstChild);
2479: else
2480: video.parentNode.insertBefore(video.firstChild, video);
2481: }
2482: video.parentNode.removeChild(video);
2483: }
2484: </script>
2485: <video controls autoplay>
2486: <source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
2487: <source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
2488: onerror="fallback(parentNode)">
2489: ...
2490: </video></pre>
2491:
2492: </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>
2493: <dd>None.</dd>
2494: <dt>Contexts in which this element can be used:</dt>
2495: <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>
2496: <dt>Content model:</dt>
2497: <dd>Empty.</dd>
2498: <dt>Content attributes:</dt>
2499: <dd><a href="elements.html#global-attributes">Global attributes</a></dd>
2500: <dd><code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code></dd>
2501: <dd><code title="attr-track-src"><a href="#attr-track-src">src</a></code></dd>
2502: <dd><code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code></dd>
2503: <dd><code title="attr-track-label"><a href="#attr-track-label">label</a></code></dd>
2504: <dd><code title="attr-track-default"><a href="#attr-track-default">default</a></code></dd>
2505: <dt>DOM interface:</dt>
2506: <dd>
2507: <pre class="idl">interface <dfn id="htmltrackelement">HTMLTrackElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2508: attribute DOMString <a href="#dom-track-kind" title="dom-track-kind">kind</a>;
2509: attribute DOMString <a href="#dom-track-src" title="dom-track-src">src</a>;
2510: attribute DOMString <a href="#dom-track-srclang" title="dom-track-srclang">srclang</a>;
2511: attribute DOMString <a href="#dom-track-label" title="dom-track-label">label</a>;
2512: attribute boolean <a href="#dom-track-default" title="dom-track-default">default</a>;
2513:
2514: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-track-track" title="dom-track-track">track</a>;
2515: };</pre>
2516: </dd>
2517: </dl><p>The <code><a href="#the-track-element">track</a></code> element allows authors to specify explicit
2518: 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>
2519: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following
2520: table lists the keywords defined for this attribute. The keyword
2521: given in the first cell of each row maps to the state given in the
2522: second cell.</p><table><thead><tr><th>Keyword
2523: </th><th>State
2524: </th><th>Brief description
2525: </th></tr></thead><tbody><tr><td><dfn id="attr-track-kind-keyword-subtitles" title="attr-track-kind-keyword-subtitles"><code>subtitles</code></dfn>
2526: </td><td><dfn id="attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</dfn>
2527: </td><td>
2528: 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).
2529: Displayed over the video.
2530: </td></tr><tr><td><dfn id="attr-track-kind-keyword-captions" title="attr-track-kind-keyword-captions"><code>captions</code></dfn>
2531: </td><td><dfn id="attr-track-kind-captions" title="attr-track-kind-captions">Captions</dfn>
2532: </td><td>
2533: 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).
2534: Displayed over the video; labeled as appropriate for the hard-of-hearing.
2535: </td></tr><tr><td><dfn id="attr-track-kind-keyword-descriptions" title="attr-track-kind-keyword-descriptions"><code>descriptions</code></dfn>
2536: </td><td><dfn id="attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</dfn>
2537: </td><td>
2538: 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).
2539: Synthesized as separate audio track.
2540: </td></tr><tr><td><dfn id="attr-track-kind-keyword-chapters" title="attr-track-kind-keyword-chapters"><code>chapters</code></dfn>
2541: </td><td><dfn id="attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</dfn>
2542: </td><td>
2543: Chapter titles, intended to be used for navigating the <a href="#media-resource">media resource</a>.
2544: Displayed as an interactive list in the user agent's interface.
2545: </td></tr><tr><td><dfn id="attr-track-kind-keyword-metadata" title="attr-track-kind-keyword-metadata"><code>metadata</code></dfn>
2546: </td><td><dfn id="attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</dfn>
2547: </td><td>
2548: Tracks intended for use from script.
2549: Not displayed by the user agent.
2550: </td></tr></tbody></table><p>The attribute may be omitted. The <i>missing value default</i> is
2551: 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
2552: gives the address of the text track data. The value must be a
2553: <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
2554: spaces</a>. This attribute must be present.</p><div class="impl">
2555:
2556: <p>If the element has a <code title="attr-track-src"><a href="#attr-track-src">src</a></code>
2557: attribute whose value is not the empty string and whose value, when
2558: the attribute was set, could be successfully <a href="urls.html#resolve-a-url" title="resolve a
2559: url">resolved</a> relative to the element, then the element's
2560: <dfn id="track-url">track URL</dfn> is the resulting <a href="urls.html#absolute-url">absolute
2561: URL</a>. Otherwise, the element's <a href="#track-url">track URL</a> is the
2562: empty string.</p>
2563:
2564: </div><p>The <dfn id="attr-track-srclang" title="attr-track-srclang"><code>srclang</code></dfn>
2565: attribute gives the language of the text track data. The value must
2566: be a valid BCP 47 language tag. This attribute must be present if
2567: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute is
2568: in the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a>
2569: state. <a href="references.html#refsBCP47">[BCP47]</a></p><div class="impl">
2570:
2571: <p>If the element has a <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attribute whose value is
2572: not the empty string, then the element's <dfn id="track-language">track language</dfn>
2573: is the value of the attribute. Otherwise, the element has no
2574: <a href="#track-language">track language</a>.</p>
2575:
2576: </div><p>The <dfn id="attr-track-label" title="attr-track-label"><code>label</code></dfn>
2577: attribute gives a user-readable title for the track. This title is
2578: 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
2579: in their user interface.</p><p>The value of the <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2580: attribute, if the attribute is present, must not be the empty
2581: string. Furthermore, there must not be two <code><a href="#the-track-element">track</a></code>
2582: 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
2583: state, whose <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code>
2584: attributes are both missing or have values that represent the same
2585: language, and whose <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2586: attributes are again both missing or both have the same value.</p><div class="impl">
2587:
2588: <p>If the element has a <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
2589: attribute whose value is not the empty string, then the element's
2590: <dfn id="track-label">track label</dfn> is the value of the attribute. Otherwise, the
2591: element's <a href="#track-label">track label</a> is a user-agent defined string
2592: (e.g. the string "untitled" in the user's locale, or a value
2593: automatically generated from the other attributes).</p>
2594:
2595: </div><p>The <dfn id="attr-track-default" title="attr-track-default"><code>default</code></dfn>
2596: attribute, if specified, indicates that the track is to be enabled
2597: if the user's preferences do not indicate that another track would
2598: be more appropriate. There must not be more than one
2599: <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>
2600:
2601: <dd>
2602:
2603: <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>
2604:
2605: </dd>
2606:
2607: </dl><div class="impl">
2608:
2609: <p>The <dfn id="dom-track-track" title="dom-track-track"><code>track</code></dfn> IDL
2610: attribute must, on getting, return the <code><a href="#the-track-element">track</a></code> element's
2611: <a href="#text-track">text track</a>'s corresponding <code><a href="#texttrack">TextTrack</a></code>
2612: object.</p>
2613:
2614: <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
2615: must <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the
2616: same name. The <dfn id="dom-track-kind" title="dom-track-kind"><code>kind</code></dfn>
2617: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
2618: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
2619:
2620: </div><div class="example">
2621:
2622: <p>This video has subtitles in several languages:</p>
2623:
2624: <pre><video src="brave.webm">
2625: <track kind=subtitles src=brave.en.vtt srclang=en label="English">
2626: <track kind=captions src=brave.en.vtt srclang=en label="English for the Hard of Hearing">
2627: <track kind=subtitles src=brave.fr.vtt srclang=fr label="Français">
2628: <track kind=subtitles src=brave.de.vtt srclang=de label="Deutsch">
2629: </video></pre>
2630:
2631: </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>
2632: (<code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>, in this specification)
2633: implement the following interface:</p><pre class="idl">interface <dfn id="htmlmediaelement">HTMLMediaElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
2634:
2635: // error state
2636: readonly attribute <a href="#mediaerror">MediaError</a> <a href="#dom-media-error" title="dom-media-error">error</a>;
2637:
2638: // network state
2639: attribute DOMString <a href="#dom-media-src" title="dom-media-src">src</a>;
2640: readonly attribute DOMString <a href="#dom-media-currentsrc" title="dom-media-currentSrc">currentSrc</a>;
1.61 mike 2641: attribute DOMString <a href="#dom-media-crossorigin" title="dom-media-crossOrigin">crossOrigin</a>;
1.47 mike 2642: const unsigned short <a href="#dom-media-network_empty" title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</a> = 0;
2643: const unsigned short <a href="#dom-media-network_idle" title="dom-media-NETWORK_IDLE">NETWORK_IDLE</a> = 1;
2644: const unsigned short <a href="#dom-media-network_loading" title="dom-media-NETWORK_LOADING">NETWORK_LOADING</a> = 2;
2645: const unsigned short <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a> = 3;
2646: readonly attribute unsigned short <a href="#dom-media-networkstate" title="dom-media-networkState">networkState</a>;
2647: attribute DOMString <a href="#dom-media-preload" title="dom-media-preload">preload</a>;
2648: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-buffered" title="dom-media-buffered">buffered</a>;
2649: void <a href="#dom-media-load" title="dom-media-load">load</a>();
2650: DOMString <a href="#dom-navigator-canplaytype" title="dom-navigator-canPlayType">canPlayType</a>(in DOMString type);
2651:
2652: // ready state
2653: const unsigned short <a href="#dom-media-have_nothing" title="dom-media-HAVE_NOTHING">HAVE_NOTHING</a> = 0;
2654: const unsigned short <a href="#dom-media-have_metadata" title="dom-media-HAVE_METADATA">HAVE_METADATA</a> = 1;
2655: const unsigned short <a href="#dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</a> = 2;
2656: const unsigned short <a href="#dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</a> = 3;
2657: const unsigned short <a href="#dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</a> = 4;
2658: readonly attribute unsigned short <a href="#dom-media-readystate" title="dom-media-readyState">readyState</a>;
2659: readonly attribute boolean <a href="#dom-media-seeking" title="dom-media-seeking">seeking</a>;
2660:
2661: // playback state
2662: attribute double <a href="#dom-media-currenttime" title="dom-media-currentTime">currentTime</a>;
2663: readonly attribute double <a href="#dom-media-initialtime" title="dom-media-initialTime">initialTime</a>;
2664: readonly attribute double <a href="#dom-media-duration" title="dom-media-duration">duration</a>;
2665: readonly attribute <span>Date</span> <a href="#dom-media-startoffsettime" title="dom-media-startOffsetTime">startOffsetTime</a>;
2666: readonly attribute boolean <a href="#dom-media-paused" title="dom-media-paused">paused</a>;
2667: attribute double <a href="#dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate">defaultPlaybackRate</a>;
2668: attribute double <a href="#dom-media-playbackrate" title="dom-media-playbackRate">playbackRate</a>;
2669: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-played" title="dom-media-played">played</a>;
2670: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-seekable" title="dom-media-seekable">seekable</a>;
2671: readonly attribute boolean <a href="#dom-media-ended" title="dom-media-ended">ended</a>;
2672: attribute boolean <a href="#dom-media-autoplay" title="dom-media-autoplay">autoplay</a>;
2673: attribute boolean <a href="#dom-media-loop" title="dom-media-loop">loop</a>;
2674: void <a href="#dom-media-play" title="dom-media-play">play</a>();
2675: void <a href="#dom-media-pause" title="dom-media-pause">pause</a>();
2676:
2677: // media controller
2678: attribute <span>DOMString</span> <a href="#dom-media-mediagroup" title="dom-media-mediaGroup">mediaGroup</a>;
2679: attribute <a href="#mediacontroller">MediaController</a> <a href="#dom-media-controller" title="dom-media-controller">controller</a>;
2680:
2681: // controls
2682: attribute boolean <a href="#dom-media-controls" title="dom-media-controls">controls</a>;
2683: attribute double <a href="#dom-media-volume" title="dom-media-volume">volume</a>;
2684: attribute boolean <a href="#dom-media-muted" title="dom-media-muted">muted</a>;
2685: attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
2686:
2687: // tracks
2688: readonly attribute <a href="#multipletracklist">MultipleTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
2689: readonly attribute <a href="#exclusivetracklist">ExclusiveTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
2690: readonly attribute <a href="#texttrack">TextTrack</a>[] <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
2691: <a href="#mutabletexttrack">MutableTextTrack</a> <a href="#dom-media-addtexttrack" title="dom-media-addTextTrack">addTextTrack</a>(in DOMString kind, in optional DOMString label, in optional DOMString language);
1.61 mike 2692: };</pre><p>The <dfn id="media-element-attributes">media element attributes</dfn>, <code title="attr-media-src"><a href="#attr-media-src">src</a></code>, <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code>, <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
1.47 mike 2693: <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
2694: <code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
2695: <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
2696: this section.</p><p><a href="#media-element" title="media element">Media elements</a> are used to
2697: present audio data, or video and audio data, to the user. This is
2698: referred to as <dfn id="media-data">media data</dfn> in this section, since this
2699: section applies equally to <a href="#media-element" title="media element">media
1.56 mike 2700: elements</a> for audio or for video.
2701: The term <dfn id="media-resource">media resource</dfn> is used to refer to the complete
2702: set of media data, e.g. the complete video file, or complete audio
2703: file.
2704: </p><p>A <a href="#media-resource">media resource</a> can have multiple audio and video
1.47 mike 2705: tracks. For the purposes of a <a href="#media-element">media element</a>, the video
2706: data of the <a href="#media-resource">media resource</a> is only that of the
2707: 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
2708: audio data of the <a href="#media-resource">media resource</a> is the result of
2709: mixing all the currently enabled tracks (if any) given by the
2710: element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>
2711: 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>
2712: elements can be used for both audio and video. The main difference
2713: between the two is simply that the <code><a href="#the-audio-element">audio</a></code> element has no
2714: playback area for visual content (such as video or captions),
2715: whereas the <code><a href="#the-video-element">video</a></code> element does.</p><div class="impl">
2716:
2717: <p>Except where otherwise specified, the <a href="webappapis.html#task-source">task source</a>
2718: for all the tasks <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> in this
2719: section and its subsections is the <dfn id="media-element-event-task-source">media element event task
2720: source</dfn>.</p>
2721:
2722: </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>
2723:
2724: <dd>
2725:
2726: <p>Returns a <code><a href="#mediaerror">MediaError</a></code> object representing the
2727: current error state of the element.</p>
2728:
2729: <p>Returns null if there is no error.</p>
2730:
2731: </dd>
2732:
2733: </dl><div class="impl">
2734:
2735: <p>All <a href="#media-element" title="media element">media elements</a> have an
2736: associated error status, which records the last error the element
2737: encountered since its <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2738: algorithm</a> was last invoked. The <dfn id="dom-media-error" title="dom-media-error"><code>error</code></dfn> attribute, on
2739: getting, must return the <code><a href="#mediaerror">MediaError</a></code> object created for
2740: this last error, or null if there has not been an error.</p>
2741:
2742: </div><pre class="idl">interface <dfn id="mediaerror">MediaError</dfn> {
2743: const unsigned short <a href="#dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</a> = 1;
2744: const unsigned short <a href="#dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</a> = 2;
2745: const unsigned short <a href="#dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</a> = 3;
2746: 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;
2747: readonly attribute unsigned short <a href="#dom-mediaerror-code" title="dom-MediaError-code">code</a>;
2748: };</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>
2749:
2750: <dd>
2751:
2752: <p>Returns the current error's error code, from the list below.</p>
2753:
2754: </dd>
2755:
2756: </dl><div class="impl">
2757:
2758: <p>The <dfn id="dom-mediaerror-code" title="dom-MediaError-code"><code>code</code></dfn>
2759: attribute of a <code><a href="#mediaerror">MediaError</a></code> object must return the code
2760: for the error, which must be one of the following:</p>
2761:
2762: </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>
2763:
2764: <dd>The fetching process for the <a href="#media-resource">media resource</a> was
2765: aborted by the user agent at the user's request.</dd>
2766:
2767: <dt><dfn id="dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK"><code>MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
2768:
2769: <dd>A network error of some description caused the user agent to
2770: stop fetching the <a href="#media-resource">media resource</a>, after the resource
2771: was established to be usable.</dd>
2772:
2773: <dt><dfn id="dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE"><code>MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
2774:
2775: <dd>An error of some description occurred while decoding the
2776: <a href="#media-resource">media resource</a>, after the resource was established to
2777: be usable.</dd>
2778:
2779: <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>
2780:
2781: <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>
2782:
2783: </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
2784: attribute on <a href="#media-element" title="media element">media elements</a> gives
2785: the address of the media resource (video, audio) to show. The
2786: attribute, if present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
1.61 mike 2787: URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-media-crossorigin" title="attr-media-crossorigin"><code>crossorigin</code></dfn>
2788: content attribute on <a href="#media-element" title="media element">media
2789: elements</a> is a <a href="fetching-resources.html#cors-settings-attribute">CORS settings attribute</a>.</p><div class="impl">
1.47 mike 2790:
2791: <p>If a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute of a
2792: <a href="#media-element">media element</a> is set or changed, the user agent must
2793: invoke the <a href="#media-element">media element</a>'s <a href="#media-element-load-algorithm">media element load
2794: 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
2795: if there are <code><a href="#the-source-element">source</a></code> elements present.)</p>
2796:
2797: <p>The <dfn id="dom-media-src" title="dom-media-src"><code>src</code></dfn> IDL
2798: attribute on <a href="#media-element" title="media element">media elements</a> must
2799: <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the same name.</p>
2800:
1.61 mike 2801: <p>The <dfn id="dom-media-crossorigin" title="dom-media-crossOrigin"><code>crossOrigin</code></dfn> IDL
2802: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
2803: attribute.</p>
2804:
1.47 mike 2805: </div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code></dt>
2806:
2807: <dd>
2808:
2809: <p>Returns the address of the current <a href="#media-resource">media resource</a>.</p>
2810:
2811: <p>Returns the empty string when there is no <a href="#media-resource">media resource</a>.</p>
2812:
2813: </dd>
2814:
2815: </dl><div class="impl">
2816:
2817: <p>The <dfn id="dom-media-currentsrc" title="dom-media-currentSrc"><code>currentSrc</code></dfn> IDL
2818: attribute is initially the empty string. Its value is changed by the
2819: <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2820: algorithm</a> defined below.</p>
2821:
2822: </div><p class="note">There are two ways to specify a <a href="#media-resource">media
2823: resource</a>, the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
2824: attribute, or <code><a href="#the-source-element">source</a></code> elements. The attribute overrides
1.53 mike 2825: 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 2826: <em>type</em>, specifically a <a href="infrastructure.html#mime-type">MIME type</a>, in some cases
2827: with a <code title="">codecs</code> parameter. (Whether the <code title="">codecs</code> parameter is allowed or not depends on the
2828: MIME type.) <a href="references.html#refsRFC4281">[RFC4281]</a></p><p>Types are usually somewhat incomplete descriptions; for example
2829: "<code title="">video/mpeg</code>" doesn't say anything except what
2830: the container type is, and even a type like "<code title="">video/mp4; codecs="avc1.42E01E,
2831: mp4a.40.2"</code>" doesn't include information like the actual
2832: bitrate (only the maximum bitrate). Thus, given a type, a user agent
2833: can often only know whether it <em>might</em> be able to play
2834: media of that type (with varying levels of confidence), or whether
2835: 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
2836: one that describes a resource that the user agent definitely does
2837: not support, for example because it doesn't recognize the container
2838: type, or it doesn't support the listed codecs.</p><p>The <a href="infrastructure.html#mime-type">MIME type</a>
2839: "<code>application/octet-stream</code>" with no parameters is never
2840: <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user agent knows it cannot render</a>. User
2841: agents must treat that type as equivalent to the lack of any
2842: explicit <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a>
2843: when it is used to label a potential <a href="#media-resource">media
2844: resource</a>.</p><p class="note">
2845: "<code>application/octet-stream</code>"
2846: is special-cased here; if any parameter appears with it, it
2847: should
2848:
2849: be treated just like any other <a href="infrastructure.html#mime-type">MIME type</a>.
2850:
2851: This is a deviation from the rule that unknown <a href="infrastructure.html#mime-type">MIME type</a> parameters
2852: should be ignored.
2853:
2854:
2855: </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>
2856:
2857: <dd>
2858:
2859: <p>Returns the empty string (a negative response), "maybe", or
2860: "probably" based on how confident the user agent is that it can
2861: play media resources of the given type.</p>
2862:
2863: </dd>
2864:
2865: </dl><div class="impl">
2866:
2867: <p>The <dfn id="dom-navigator-canplaytype" title="dom-navigator-canPlayType"><code>canPlayType(<var title="">type</var>)</code></dfn> method must return the empty
2868: string if <var title="">type</var> is <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user
2869: agent knows it cannot render</a> or is the type
2870: "<code>application/octet-stream</code>"; it must return "<code title="">probably</code>" if the user agent is confident that the
2871: type represents a <a href="#media-resource">media resource</a> that it can render if
2872: used in with this <code><a href="#the-audio-element">audio</a></code> or <code><a href="#the-video-element">video</a></code> element;
2873: and it must return "<code title="">maybe</code>" otherwise.
2874: Implementors are encouraged to return "<code title="">maybe</code>"
2875: unless the type can be confidently established as being supported or
2876: 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
2877: present.</p>
2878:
2879: </div><div class="example">
2880:
2881: <p>This script tests to see if the user agent supports a
2882: (fictional) new format to dynamically decide whether to use a
2883: <code><a href="#the-video-element">video</a></code> element or a plugin:</p>
2884:
2885: <pre><section id="video">
2886: <p><a href="playing-cats.nfv">Download video</a></p>
2887: </section>
2888: <script>
2889: var videoSection = document.getElementById('video');
2890: var videoElement = document.createElement('video');
2891: var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
2892: if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) {
2893: // not confident of browser support
2894: // but we have a plugin
2895: // so use plugin instead
2896: videoElement = document.createElement("embed");
2897: } else if (support == "") {
2898: // no support from browser and no plugin
2899: // do nothing
2900: videoElement = null;
2901: }
2902: if (videoElement) {
2903: while (videoSection.hasChildNodes())
2904: videoSection.removeChild(videoSection.firstChild);
2905: videoElement.setAttribute("src", "playing-cats.nfv");
2906: videoSection.appendChild(videoElement);
2907: }
2908: </script></pre>
2909:
2910: </div><p class="note">The <code title="attr-source-type"><a href="#attr-source-type">type</a></code>
2911: attribute of the <code><a href="#the-source-element">source</a></code> element allows the user agent
2912: to avoid downloading resources that use formats it cannot
2913: 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>
2914:
2915: <dd>
2916:
2917: <p>Returns the current state of network activity for the element,
2918: from the codes in the list below.</p>
2919:
2920: </dd>
2921:
2922: </dl><div class="impl">
2923:
2924: <p>As <a href="#media-element" title="media element">media elements</a> interact
2925: with the network, their current network activity is represented by
2926: the <dfn id="dom-media-networkstate" title="dom-media-networkState"><code>networkState</code></dfn>
2927: attribute. On getting, it must return the current network state of
2928: the element, which must be one of the following values:</p>
2929:
2930: </div><dl><dt><dfn id="dom-media-network_empty" title="dom-media-NETWORK_EMPTY"><code>NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
2931:
2932: <dd>The element has not yet been initialized. All attributes are in
2933: their initial states.</dd>
2934:
2935: <dt><dfn id="dom-media-network_idle" title="dom-media-NETWORK_IDLE"><code>NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
2936:
2937: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2938: algorithm</a> is active and</span> has selected a <a href="#media-resource" title="media resource">resource</a>, but it is not actually
2939: using the network at this time.</dd>
2940:
2941: <dt><dfn id="dom-media-network_loading" title="dom-media-NETWORK_LOADING"><code>NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
2942:
2943: <dd>The user agent is actively trying to download data.</dd>
2944:
2945: <dt><dfn id="dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE"><code>NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
2946:
2947: <dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2948: algorithm</a> is active, but it</span> has not yet found a <a href="#media-resource" title="media resource">resource</a> to use.</dd>
2949:
2950: </dl><div class="impl">
2951:
2952: <p>The <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2953: algorithm</a> defined below describes exactly when the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute changes
2954: value and what events fire to indicate changes in this state.</p>
2955:
2956: </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>
2957:
2958: <dd>
2959:
2960: <p>Causes the element to reset and start selecting and loading a
2961: new <a href="#media-resource">media resource</a> from scratch.</p>
2962:
2963: </dd>
2964:
2965: </dl><div class="impl">
2966:
2967: <p>All <a href="#media-element" title="media element">media elements</a> have an
2968: <dfn id="autoplaying-flag">autoplaying flag</dfn>, which must begin in the true state, and
2969: a <dfn id="delaying-the-load-event-flag">delaying-the-load-event flag</dfn>, which must begin in the
2970: false state. While the <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> is
2971: true, the element must <a href="the-end.html#delay-the-load-event">delay the load event</a> of its
2972: document.</p>
2973:
2974: <p>When the <dfn id="dom-media-load" title="dom-media-load"><code>load()</code></dfn>
2975: method on a <a href="#media-element">media element</a> is invoked, the user agent
2976: must run the <a href="#media-element-load-algorithm">media element load algorithm</a>.</p>
2977:
2978: <p>The <dfn id="media-element-load-algorithm">media element load algorithm</dfn> consists of the
2979: following steps.</p>
2980:
2981: <ol><li><p>Abort any already-running instance of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
2982: algorithm</a> for this element.</p></li>
2983:
2984: <li>
2985:
2986: <p>If there are any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> from
2987: the <a href="#media-element">media element</a>'s <a href="#media-element-event-task-source">media element event task
2988: source</a> in one of the <a href="webappapis.html#task-queue" title="task queue">task
2989: queues</a>, then remove those tasks.</p>
2990:
2991: <p class="note">Basically, pending events and callbacks for the
2992: media element are discarded when the media element starts loading
2993: a new resource.</p>
2994:
2995: </li>
2996:
2997: <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
2998: 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
2999: element</a>.</p></li>
3000:
3001: <li>
3002:
3003: <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
3004: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, then
3005: run these substeps:</p>
3006:
3007: <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
3008: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the <a href="#media-element">media
3009: element</a>.</p></li>
3010:
3011: <li><p>If a fetching process is in progress for the <a href="#media-element">media
3012: element</a>, the user agent should stop it.</p></li>
3013:
3014: <li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3015: <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>.</p></li>
3016:
3017: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3018: text tracks</a>.</p></li>
3019:
3020: <li><p>If <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is
3021: not set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then set it
3022: to that state.
3023:
3024: </p></li>
3025:
3026: <li><p>If the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
3027: attribute is false, then set it to true.</p></li>
3028:
3029: <li><p>If <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true,
3030: set it to false.</p></li>
3031:
3032: <li>
3033:
3034: <p>Set the <a href="#current-playback-position">current playback position</a> to 0.</p>
3035:
3036: <p>If this changed the <a href="#current-playback-position">current playback position</a>,
3037: then <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
3038: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
3039: <a href="#media-element">media element</a>.</p>
3040:
3041: </li>
3042:
3043: <li><p>Set the <a href="#initial-playback-position">initial playback position</a> to
3044: 0.</p></li>
3045:
3046: <li><p>Set the <a href="#timeline-offset">timeline offset</a> to Not-a-Number
3047: (NaN).</p></li>
3048:
3049: <li>
3050:
3051: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3052: attribute to Not-a-Number (NaN).</p>
3053:
3054: <p class="note">The user agent <a href="#durationChange">will
3055: not</a> fire a <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event
3056: for this particular change of the duration.</p>
3057:
3058: </li>
3059:
3060: </ol></li>
3061:
3062: <li><p>Set the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute to the
3063: value of the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
3064: attribute.</p></li>
3065:
3066: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code> attribute
3067: to null and the <a href="#autoplaying-flag">autoplaying flag</a> to true.</p></li>
3068:
3069: <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
3070: algorithm</a>.</p></li>
3071:
3072: <li>
3073:
3074: <p class="note">Playback of any previously playing <a href="#media-resource">media
3075: resource</a> for this element stops.</p>
3076:
3077: </li>
3078:
3079: </ol><p>The <dfn id="concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3080: algorithm</dfn> for a <a href="#media-element">media element</a> is as follows. This
3081: algorithm is always invoked synchronously, but one of the first
3082: steps in the algorithm is to return and continue running the
3083: remaining steps asynchronously, meaning that it runs in the
3084: background with scripts and other <a href="webappapis.html#concept-task" title="concept-task">tasks</a> running in parallel. In addition,
3085: this algorithm interacts closely with the <a href="webappapis.html#event-loop">event loop</a>
3086: mechanism; in particular, it has <a href="webappapis.html#synchronous-section" title="synchronous
3087: section">synchronous sections</a> (which are triggered as part of
3088: the <a href="webappapis.html#event-loop">event loop</a> algorithm). Steps in such sections are
3089: marked with ⌛.</p>
3090:
3091: <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>
3092:
3093: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
3094: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that invoked this
3095: algorithm to continue. The <a href="webappapis.html#synchronous-section">synchronous section</a>
3096: consists of all the remaining steps of this algorithm until the
3097: algorithm says the <a href="webappapis.html#synchronous-section">synchronous section</a> has
3098: ended. (Steps in <a href="webappapis.html#synchronous-section" title="synchronous section">synchronous
3099: sections</a> are marked with ⌛.)</p></li>
3100:
3101: <li>
3102:
3103: <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>
3104:
3105: <p>⌛ Otherwise, if the <a href="#media-element">media element</a> does not
3106: have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute but has a
3107: <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>
3108: element child in <a href="infrastructure.html#tree-order">tree order</a>.</p>
3109:
3110: <p>⌛ Otherwise the <a href="#media-element">media element</a> has neither a
3111: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute nor a
3112: <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
3113: these steps; the <a href="webappapis.html#synchronous-section">synchronous section</a> ends.</p>
3114:
3115: </li>
3116:
3117: <li><p>⌛ Set the <a href="#media-element">media element</a>'s
3118: <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
3119: its <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3120: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
3121:
3122: <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
3123: event</a> named <code title="event-media-loadstart"><a href="#event-media-loadstart">loadstart</a></code> at the <a href="#media-element">media
3124: element</a>.</p></li>
3125:
3126: <li>
3127:
3128: <p>If <var title="">mode</var> is <i title="">attribute</i>, then
3129: run these substeps:</p>
3130:
3131: <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
3132: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3133: down to the <i title="">failed</i> step below.</p></li>
3134:
3135: <li><p>⌛ Let <var title="">absolute URL</var> be the
3136: <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>
3137: specified by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
3138: attribute's value relative to the <a href="#media-element">media element</a> when
3139: the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was last
3140: changed.</p>
3141: </li><li><p>⌛ If <var title="">absolute URL</var> was obtained
3142: 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>
3143:
3144: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3145: remaining steps asynchronously.</p></li>
3146:
3147: <li><p>If <var title="">absolute URL</var> was obtained
3148: successfully, run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3149: algorithm</a> with <var title="">absolute URL</var>. If that
3150: algorithm returns without aborting <em>this</em> one, then the
3151: load failed.</p></li>
3152:
3153: <li>
3154:
3155: <p><i>Failed</i>: Reaching this step indicates that the media
3156: resource failed to load or that the given <a href="urls.html#url">URL</a> could
3157: not be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a>. In one
3158: atomic operation, run the following steps:</p>
3159:
3160: <ol><li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3161: 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
3162: <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>
3163:
3164: <li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
3165: text tracks</a>.</p></li>
3166:
3167: <li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3168: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3169: value.</p></li>
3170:
3171: </ol></li>
3172:
3173: <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
3174: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3175: at the <a href="#media-element">media element</a>.</p></li>
3176:
3177: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a>
3178: to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying
3179: the load event</a>.</p></li>
3180:
3181: <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
3182: <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute is changed, the
3183: element won't attempt to load another resource.</p></li>
3184:
3185:
3186: </ol><p>Otherwise, the <code><a href="#the-source-element">source</a></code> elements will be used; run
3187: these substeps:</p>
3188:
3189: <ol><li>
3190:
3191: <p>⌛ Let <var title="">pointer</var> be a position
3192: defined by two adjacent nodes in the <a href="#media-element">media
3193: element</a>'s child list, treating the start of the list
3194: (before the first child in the list, if any) and end of the list
3195: (after the last child in the list, if any) as nodes in their own
3196: right. One node is the node before <var title="">pointer</var>,
3197: 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
3198: any, or the end of the list, if it is the last node.</p>
3199:
3200: <p>As nodes are inserted and removed into the <a href="#media-element">media
3201: element</a>, <var title="">pointer</var> must be updated as
3202: follows:</p>
3203:
3204: <dl><dt>If a new node is inserted between the two nodes that
3205: define <var title="">pointer</var></dt>
3206:
3207: <dd>Let <var title="">pointer</var> be the point between the
3208: node before <var title="">pointer</var> and the new node. In
3209: other words, insertions at <var title="">pointer</var> go after
3210: <var title="">pointer</var>.</dd>
3211:
3212: <dt>If the node before <var title="">pointer</var> is removed</dt>
3213:
3214: <dd>Let <var title="">pointer</var> be the point between the
3215: node after <var title="">pointer</var> and the node before the
3216: node after <var title="">pointer</var>. In other words, <var title="">pointer</var> doesn't move relative to the remaining
3217: nodes.</dd>
3218:
3219: <dt>If the node after <var title="">pointer</var> is removed</dt>
3220:
3221: <dd>Let <var title="">pointer</var> be the point between the
3222: node before <var title="">pointer</var> and the node after the
3223: node before <var title="">pointer</var>. Just as with the
3224: previous case, <var title="">pointer</var> doesn't move
3225: relative to the remaining nodes.</dd>
3226:
3227: </dl><p>Other changes don't affect <var title="">pointer</var>.</p>
3228:
3229: </li>
3230:
3231: <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
3232: string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
3233: down to the <i title="">failed</i> step below.</p></li>
3234:
3235: <li><p>⌛ Let <var title="">absolute URL</var> be the
3236: <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>
3237: 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
3238: the <var title="">candidate</var> when the <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute was last
3239: changed.</p>
3240: </li><li><p>⌛ If <var title="">absolute URL</var> was not
3241: obtained successfully, then end the <a href="webappapis.html#synchronous-section">synchronous
3242: section</a>, and jump down to the <i title="">failed</i> step
3243: below.</p></li>
3244:
3245: <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
3246: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3247: described by the <code title="">codecs</code> parameter, for
3248: types that define that parameter), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3249: the user agent knows it cannot render</a>, then end the
3250: <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
3251:
3252: <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
3253: not <a href="common-microsyntaxes.html#matches-the-environment" title="matches the environment">match the
3254: environment</a>, then end the <a href="webappapis.html#synchronous-section">synchronous
3255: section</a>, and jump down to the <i title="">failed</i> step
3256: below.</p></li>
3257:
3258: <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>
3259:
3260: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3261: remaining steps asynchronously.</p></li>
3262:
3263: <li><p>Run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource
3264: fetch algorithm</a> with <var title="">absolute URL</var>. If
3265: that algorithm returns without aborting <em>this</em> one, then
3266: the load failed.</p></li>
3267:
3268: <li><p><i title="">Failed</i>: <a href="webappapis.html#queue-a-task">Queue a task</a> to
3269: <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
3270: obtain <var title="">candidate</var>'s corresponding <a href="#media-resource">media
3271: resource</a> in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
3272: algorithm</a>.</p></li>
3273:
3274: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3275: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3276: steps of this algorithm until the algorithm says the
3277: <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
3278: marked with ⌛.)</p></li>
3279:
3280: <li><p>⌛ <a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's
3281: media-resource-specific text tracks</a>.</p></li>
3282:
3283: <li><p>⌛ <i title="">Find next candidate</i>: Let <var title="">candidate</var> be null.</p></li>
3284:
3285: <li><p>⌛ <i title="">Search loop</i>: If the node after
3286: <var title="">pointer</var> is the end of the list, then jump to
3287: the <i title="">waiting</i> step below.</p></li>
3288:
3289: <li><p>⌛ If the node after <var title="">pointer</var> is
3290: a <code><a href="#the-source-element">source</a></code> element, let <var title="">candidate</var>
3291: be that element.</p></li>
3292:
3293: <li><p>⌛ Advance <var title="">pointer</var> so that the
3294: node before <var title="">pointer</var> is now the node that was
3295: after <var title="">pointer</var>, and the node after <var title="">pointer</var> is the node after the node that used to be
3296: after <var title="">pointer</var>, if any.</p></li>
3297:
3298: <li><p>⌛ If <var title="">candidate</var> is null, jump
3299: back to the <i title="">search loop</i> step. Otherwise, jump
3300: back to the <i title="">process candidate</i> step.</p></li>
3301:
3302: <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
3303: the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
3304: value.</p></li>
3305:
3306: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3307: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3308: event">delaying the load event</a>.</p></li>
3309:
3310: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
3311: remaining steps asynchronously.</p></li>
3312:
3313: <li><p>Wait until the node after <var title="">pointer</var> is a
3314: node other than the end of the list. (This step might wait
3315: forever.)</p></li>
3316:
3317: <li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
3318: <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
3319: steps of this algorithm until the algorithm says the
3320: <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
3321: marked with ⌛.)</p></li>
3322:
3323: <li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3324: flag</a> back to true (this <a href="the-end.html#delay-the-load-event" title="delay the load
3325: event">delays the load event</a> again, in case it hasn't been
3326: fired yet).</p>
3327:
3328: </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>
3329:
3330: <li><p>⌛ Jump back to the <i title="">find next
3331: candidate</i> step above.</p></li>
3332:
3333: </ol></li>
3334:
3335: </ol><p>The <dfn id="concept-media-load-resource" title="concept-media-load-resource">resource fetch
3336: algorithm</dfn> for a <a href="#media-element">media element</a> and a given
3337: <a href="urls.html#absolute-url">absolute URL</a> is as follows:</p>
3338:
3339: <ol><li><p>Let the <var title="">current media resource</var> be the
3340: resource given by the <a href="urls.html#absolute-url">absolute URL</a> passed to this
3341: algorithm. This is now the element's <a href="#media-resource">media
3342: resource</a>.</p></li>
3343:
3344: <li>
3345:
1.61 mike 3346: <p>Perform a <a href="fetching-resources.html#potentially-cors-enabled-fetch">potentially CORS-enabled fetch</a> of the
3347: <var title="">current media resource</var>'s <a href="urls.html#absolute-url">absolute
3348: URL</a>, with the <i>mode</i> being the state of the
3349: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
3350: attribute, the <i><a href="origin-0.html#origin">origin</a></i> being the <a href="origin-0.html#origin">origin</a> of the
3351: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
3352: <i>default origin behaviour</i> set to <i>taint</i>.</p>
3353:
3354: <p>The resource obtained in this fashion, if any, contains the
3355: <a href="#media-data">media data</a>. It can be <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>
3356: or <a href="fetching-resources.html#cors-cross-origin">CORS-cross-origin</a>; this affects whether subtitles
3357: referenced in the <a href="#media-data">media data</a> are exposed in the API
3358: and, for <code><a href="#the-video-element">video</a></code> elements, whether a
3359: <code><a href="the-canvas-element.html#the-canvas-element">canvas</a></code> gets tainted when the video is drawn on
3360: it.</p>
3361:
1.47 mike 3362: <p>Every 350ms (±200ms) or for every byte received, whichever
3363: is <em>least</em> frequent, <a href="webappapis.html#queue-a-task">queue a task</a> to
3364: <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>
3365:
3366: <p>The <dfn id="stall-timeout">stall timeout</dfn> is a user-agent defined length of
3367: time, which should be about three seconds. When a <a href="#media-element">media
3368: element</a> that is actively attempting to obtain <a href="#media-data">media
3369: data</a> has failed to receive any data for a duration equal to
3370: the <a href="#stall-timeout">stall timeout</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a
3371: 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>
3372:
3373: <p>User agents may allow users to selectively block or slow
3374: <a href="#media-data">media data</a> downloads. When a <a href="#media-element">media
3375: element</a>'s download has been blocked altogether, the user
3376: agent must act as if it was stalled (as opposed to acting as if
3377: the connection was closed). The rate of the download may also be
3378: throttled automatically by the user agent, e.g. to balance the
3379: download with other connections sharing the same bandwidth.</p>
3380:
3381: <p>User agents may decide to not download more content at any
3382: time, e.g. after buffering five minutes of a one hour media
3383: resource, while waiting for the user to decide whether to play the
3384: resource or not, or while waiting for user input in an interactive
3385: resource. When a <a href="#media-element">media element</a>'s download has been
3386: 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
3387: 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
3388: when downloading of the resource resumes, the user agent must set
3389: the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
3390: <code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p>
3391:
3392: <p class="note">The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute provides a
3393: hint regarding how much buffering the author thinks is advisable,
3394: even in the absence of the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute.</p>
3395:
3396: <p>When a user agent decides to completely stall a download,
3397: e.g. if it is waiting until the user starts playback before
3398: downloading any further content, the element's
3399: <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> must be set to
3400: false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the
3401: load event</a>.</p>
3402:
3403: <p>The user agent may use whatever means necessary to fetch the
3404: resource (within the constraints put forward by this and other
3405: specifications); for example, reconnecting to the server in the
3406: face of network errors, using HTTP range retrieval requests, or
3407: switching to a streaming protocol. The user agent must consider a
3408: resource erroneous only if it has given up trying to fetch it.</p>
3409:
3410: <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
3411: being fetched must, when appropriate, include the relevant
3412: substeps from the following list:</p>
3413:
3414: <dl class="switch"><dt>If the <a href="#media-data">media data</a> cannot be fetched at all, due
3415: to network errors, causing the user agent to give up trying to
3416: fetch the resource</dt>
3417:
3418: <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
3419: parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
3420: described by the <code title="">codecs</code> parameter, if the
3421: parameter is defined for that type), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
3422: the user agent knows it cannot render</a> (even if the actual
3423: <a href="#media-data">media data</a> is in a supported format)</dt>
3424:
3425: <dt>If the <a href="#media-data">media data</a> can be fetched but is found by
3426: inspection to be in an unsupported format, or can otherwise not
3427: be rendered at all</dt>
3428:
3429: <dd>
3430:
3431: <p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in
3432: other protocols), and other fatal network errors that occur
3433: before the user agent has established whether the <var title="">current media resource</var> is usable, as well as
3434: the file using an unsupported container format, or using
3435: unsupported codecs for all the data, must cause the user agent
3436: to execute the following steps:</p>
3437:
3438: <ol><li><p>The user agent should cancel the fetching
3439: process.</p></li>
3440:
3441: <li><p>Abort this subalgorithm, returning to the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3442: algorithm</a>.</p>
3443:
3444: </li></ol></dd>
3445:
3446:
3447:
3448:
3449:
3450: <dt id="getting-media-metadata">Once enough of the <a href="#media-data">media
3451: data</a> has been fetched to determine the duration of the
3452: <a href="#media-resource">media resource</a>, its dimensions, and other
3453: metadata,
3454: and once <a href="#the-text-tracks-are-ready">the text tracks are ready</a>
3455: </dt>
3456:
3457: <dd>
3458:
3459: <p>This indicates that the resource is usable. The user agent
3460: must follow these substeps:</p>
3461:
3462: <ol><li>
3463:
3464: <p><a href="#defineTimeline">Establish the media timeline</a> for the purposes
3465: of the <a href="#current-playback-position">current playback position</a>, the
3466: <a href="#earliest-possible-position">earliest possible position</a>, and the <a href="#initial-playback-position">initial
3467: playback position</a>, based on the <a href="#media-data">media
3468: data</a>.</p>
3469:
3470: </li>
3471:
3472: <li>
3473:
3474: <p>Update the <a href="#timeline-offset">timeline offset</a> to the date and
3475: time that corresponds to the zero time in the <a href="#media-timeline">media
3476: timeline</a> established in the previous step, if any. If
3477: no explicit time and date is given by the <a href="#media-resource">media
3478: resource</a>, the <a href="#timeline-offset">timeline offset</a> must be set
3479: to Not-a-Number (NaN).</p>
3480:
3481: </li>
3482:
3483: <li><p>Set the <a href="#current-playback-position">current playback position</a> to the
3484: <a href="#earliest-possible-position">earliest possible position</a>.</p></li>
3485:
3486: <li>
3487:
3488: <p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
3489: attribute with the time of the last frame of the resource, if
3490: known, on the <a href="#media-timeline">media timeline</a> established above.
3491: If it is not known (e.g. a stream that is in principle
3492: infinite), update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute to the
3493: value positive Infinity.</p>
3494:
3495: <p class="note">The user agent <a href="#durationChange">will</a> <a href="webappapis.html#queue-a-task">queue a task</a> to
3496: <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
3497: element at this point.</p>
3498:
3499: </li>
3500:
3501: <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>
3502: attributes.</p></li>
3503:
3504: <li>
3505:
3506: <p>Set the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to
3507: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>.</p>
3508:
3509: <p class="note">A <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> DOM
3510: event <a href="#fire-loadedmetadata">will be fired</a> as part
3511: of setting the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to a
3512: new value.</p>
3513:
3514:
3515:
3516: </li>
3517:
3518: <li><p>Let <var title="">jumped</var> be false.</p></li>
3519:
3520: <li>
3521:
3522: <p>If either the <a href="#media-resource">media resource</a> or the address of
3523: the <var title="">current media resource</var> indicate a
3524: particular start time, then set the <a href="#initial-playback-position">initial playback
3525: 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
3526: (if the position is out of range, it is effectively
3527: ignored).</p>
3528:
3529: <p class="example">For example, with media formats that
3530: support the <cite>Media Fragments URI</cite> fragment
3531: identifier syntax, the fragment identifier can be used to
3532: indicate a start position. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
3533:
3534: </li>
3535:
3536: <li><p>If either the <a href="#media-resource">media resource</a> or the address
3537: of the <var title="">current media resource</var> indicate a
3538: particular set of audio or video tracks to enable, then the
3539: 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
3540: the first selected video track must be selected in the
3541: element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code>
3542: object.</p></li>
3543:
3544: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
3545: media controller</a>, then: if <var title="">jumped</var> is
3546: true and the <a href="#initial-playback-position">initial playback position</a>, relative
3547: to the <a href="#current-media-controller">current media controller</a>'s timeline, is
3548: greater than the <a href="#current-media-controller">current media controller</a>'s
3549: <a href="#media-controller-position">media controller position</a>, then <a href="#seek-the-media-controller">seek the
3550: media controller</a> to the <a href="#media-element">media element</a>'s
3551: <a href="#initial-playback-position">initial playback position</a>, relative to the
3552: <a href="#current-media-controller">current media controller</a>'s timeline; otherwise,
3553: <a href="#dom-media-seek" title="dom-media-seek">seek</a> the <a href="#media-element">media
3554: element</a> to the <a href="#media-controller-position">media controller position</a>,
3555: relative to the <a href="#media-element">media element</a>'s timeline,
3556: discarding any resulting exceptions.</p></li>
3557: <li>
3558:
3559: <p>Once the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
3560: reaches <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
3561: <a href="#fire-loadeddata">after the <code title="event-media-loadeddata">loadeddata</code> event has been
3562: fired</a>, set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3563: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3564: event">delaying the load event</a>.</p>
3565:
3566: <p class="note">A user agent that is attempting to reduce
3567: network usage while still fetching the metadata for each
3568: <a href="#media-resource">media resource</a> would also stop buffering at this
3569: point, causing the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute
3570: to switch to the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> value.</p>
3571:
3572: </li>
3573:
3574: </ol><p class="note">The user agent is <em>required</em> to
3575: determine the duration of the <a href="#media-resource">media resource</a> and
3576: go through this step before playing.</p>
3577: </dd>
3578:
3579:
3580: <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
3581: has been decoded)</dt>
3582:
3583: <dd>
3584:
3585: <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>
3586: named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the
3587: <a href="#media-element">media element</a>.</p>
3588:
3589: </dd>
3590:
3591:
3592: <dt>If the connection is interrupted, causing the user agent to
3593: give up trying to fetch the resource</dt>
3594:
3595: <dd>
3596:
3597: <p>Fatal network errors that occur after the user agent has
3598: established whether the <var title="">current media
3599: resource</var> is usable must cause the user agent to execute
3600: the following steps:</p>
3601:
3602: <ol><li><p>The user agent should cancel the fetching
3603: process.</p></li>
3604:
3605: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3606: 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
3607: <code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code>.</p></li>
3608:
3609: <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
3610: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3611: at the <a href="#media-element">media element</a>.</p></li>
3612:
3613: <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
3614: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3615: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3616: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3617: 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
3618: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3619: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3620: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3621: value.</p></li>
3622:
3623: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3624: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3625: event">delaying the load event</a>.</p></li>
3626:
3627: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3628: algorithm</a>.</p></li>
3629:
3630: </ol></dd>
3631:
3632:
3633: <dt id="fatal-decode-error">If the <a href="#media-data">media data</a> is
3634: corrupted</dt>
3635:
3636: <dd>
3637:
3638: <p>Fatal errors in decoding the <a href="#media-data">media data</a> that
3639: occur after the user agent has established whether the <var title="">current media resource</var> is usable must cause the
3640: user agent to execute the following steps:</p>
3641:
3642: <ol><li><p>The user agent should cancel the fetching
3643: process.</p></li>
3644:
3645: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3646: 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
3647: <code title="dom-MediaError-MEDIA_ERR_DECODE"><a href="#dom-mediaerror-media_err_decode">MEDIA_ERR_DECODE</a></code>.</p></li>
3648:
3649: <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
3650: event</a> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
3651: at the <a href="#media-element">media element</a>.</p></li>
3652:
3653: <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
3654: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3655: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3656: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3657: 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
3658: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3659: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3660: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3661: value.</p></li>
3662:
3663: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3664: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3665: event">delaying the load event</a>.</p></li>
3666:
3667: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3668: algorithm</a>.</p></li>
3669:
3670: </ol></dd>
3671:
3672:
3673: <dt>If the <a href="#media-data">media data</a> fetching process is aborted by
3674: the user</dt>
3675:
3676: <dd>
3677:
3678: <p>The fetching process is aborted by the user, e.g. because the
3679: user navigated the browsing context to another page, the user
3680: agent must execute the following steps. These steps are not
3681: followed if the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code>
3682: method itself is invoked while these steps are running, as the
3683: steps above handle that particular kind of abort.</p>
3684:
3685: <ol><li><p>The user agent should cancel the fetching
3686: process.</p></li>
3687:
3688: <li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
3689: 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
3690: <code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.</p></li>
3691:
3692: <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
3693: event</a> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code>
3694: at the <a href="#media-element">media element</a>.</p></li>
3695:
3696: <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
3697: value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
3698: element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3699: the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
3700: 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
3701: event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
3702: at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
3703: the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
3704: value.</p></li>
3705:
3706: <li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
3707: flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
3708: event">delaying the load event</a>.</p></li>
3709:
3710: <li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3711: algorithm</a>.</p></li>
3712:
3713: </ol></dd>
3714:
3715:
3716: <dt id="non-fatal-media-error">If the <a href="#media-data">media data</a> can
3717: be fetched but has non-fatal errors or uses, in part, codecs that
3718: are unsupported, preventing the user agent from rendering the
3719: content completely correctly but not preventing playback
3720: altogether</dt>
3721:
3722: <dd>
3723:
3724: <p>The server returning data that is partially usable but cannot
3725: be optimally rendered must cause the user agent to render just
3726: the bits it can handle, and ignore the rest.</p>
3727:
3728:
3729:
3730: </dd>
3731:
3732:
3733: <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>
3734:
3735: <dd>
3736:
1.61 mike 3737: <p>If the <a href="#media-data">media data</a> is
3738: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a>, <a href="webappapis.html#queue-a-task">queue a task</a> to run
3739: the <a href="#steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text
3740: track</a> with the relevant data.</p>
3741:
3742: <p class="note">Cross-origin videos do not expose their
3743: subtitles, since that would allow attacks such as hostile sites
3744: reading subtitles from confidential videos on a user's
3745: intranet.</p>
1.47 mike 3746:
3747: </dd>
3748:
3749: </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>
3750: (i.e. once the download has completed), if the fetching process
3751: completes without errors, including decoding the media data, and
3752: if all of the data is available to the user agent without network
3753: access, then, the user agent must move on to the next step. This
3754: might never happen, e.g. when streaming an infinite resource such
3755: as Web radio, or if the resource is longer than the user agent's
3756: ability to cache data.</p>
3757:
3758: <p>While the user agent might still need network access to obtain
3759: parts of the <a href="#media-resource">media resource</a>, the user agent must
3760: remain on this step.</p>
3761:
3762: <p class="example">For example, if the user agent has discarded
3763: the first half of a video, the user agent will remain at this step
3764: even once the <a href="#ended-playback" title="ended playback">playback has
3765: ended</a>, because there is always the chance the user will
3766: seek back to the start. In fact, in this situation, once <a href="#ended-playback" title="ended playback">playback has ended</a>, the user agent
1.64 ! mike 3767: will end up firing a <code title="event-media-stalled"><a href="#event-media-stalled">stalled</a></code> event, as described
1.47 mike 3768: earlier.</p>
3769:
3770: </li>
3771:
3772: <li><p>If the user agent ever reaches this step (which can only
3773: happen if the entire resource gets loaded and kept available):
3774: abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
3775: algorithm</a>.</p></li>
3776:
3777: </ol></div><hr><p>The <dfn id="attr-media-preload" title="attr-media-preload"><code>preload</code></dfn>
3778: attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following table
3779: lists the keywords and states for the attribute — the keywords
3780: in the left column map to the states in the cell in the second
3781: column on the same row as the keyword.</p><table><thead><tr><th> Keyword
3782: </th><th> State
3783: </th><th> Brief description
3784: </th></tr></thead><tbody><tr><td><dfn id="attr-media-preload-none" title="attr-media-preload-none"><code>none</code></dfn>
3785: </td><td><dfn id="attr-media-preload-none-state" title="attr-media-preload-none-state">None</dfn>
3786: </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.
3787: </td></tr><tr><td><dfn id="attr-media-preload-metadata" title="attr-media-preload-metadata"><code>metadata</code></dfn>
3788: </td><td><dfn id="attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</dfn>
1.62 mike 3789: </td><td>Hints to the user agent that the author does not expect the user to need the media resource, but that fetching the resource metadata (dimensions, first frame, track list, duration, etc) is reasonable. If the user agent precisely fetches no more than the metadata, then the <a href="#media-element">media element</a> will end up with its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute set to <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>; typically though, some frames will be obtained as well and it will probably be <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.
1.47 mike 3790: </td></tr><tr><td><dfn id="attr-media-preload-auto" title="attr-media-preload-auto"><code>auto</code></dfn>
3791: </td><td><dfn id="attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</dfn>
3792: </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.
3793: </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
3794: attribute's <i>missing value default</i> is user-agent defined,
3795: though the <a href="#attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</a> state is
3796: suggested as a compromise between reducing server load and providing
3797: an optimal user experience.</p><div class="impl">
3798:
3799: <p>The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute is
3800: intended to provide a hint to the user agent about what the author
3801: thinks will lead to the best user experience. The attribute may be
3802: ignored altogether, for example based on explicit user preferences
3803: or based on the available connectivity.</p>
3804:
3805: <p>The <dfn id="dom-media-preload" title="dom-media-preload"><code>preload</code></dfn> IDL
3806: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
3807: same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
3808:
3809: </div><p class="note">The <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute can override
3810: the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute (since
3811: if the media plays, it naturally has to buffer first, regardless of
3812: the hint given by the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute). Including
3813: 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>
3814:
3815: <dd>
3816:
3817: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
3818: ranges of the <a href="#media-resource">media resource</a> that the user agent has
3819: buffered.</p>
3820:
3821: </dd>
3822:
3823: </dl><div class="impl">
3824:
3825: <p>The <dfn id="dom-media-buffered" title="dom-media-buffered"><code>buffered</code></dfn>
3826: attribute must return a new static <a href="#normalized-timeranges-object">normalized
3827: <code>TimeRanges</code> object</a> that represents the ranges of
3828: the <a href="#media-resource">media resource</a>, if any, that the user agent has
3829: buffered, at the time the attribute is evaluated. Users agents must
3830: accurately determine the ranges available, even for media streams
3831: where this can only be determined by tedious inspection.</p>
3832:
3833: <p class="note">Typically this will be a single range anchored at
3834: the zero point, but if, e.g. the user agent uses HTTP range requests
3835: in response to seeking, then there could be multiple ranges.</p>
3836:
3837: <p>User agents may discard previously buffered data.</p>
3838:
3839: <p class="note">Thus, a time position included within a range of the
3840: objects return by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code> attribute at one time can
3841: end up being not included in the range(s) of objects returned by the
3842: same attribute at later times.</p>
3843:
3844: </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>
3845:
3846: <dd>
3847:
3848: <p>Returns the length of the <a href="#media-resource">media resource</a>, in
3849: seconds, assuming that the start of the <a href="#media-resource">media
3850: resource</a> is at time zero.</p>
3851:
3852: <p>Returns NaN if the duration isn't available.</p><p>
3853:
3854: </p><p>Returns Infinity for unbounded streams.</p>
3855:
3856: </dd>
3857:
3858: <dt><var title="">media</var> . <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
3859:
3860: <dd>
3861:
3862: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds.</p>
3863:
3864: <p>Can be set, to seek to the given time.</p><p>
3865:
3866: </p><p>Will throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception if there
3867: is no selected <a href="#media-resource">media resource</a>
3868: or if there is a <a href="#current-media-controller">current media controller</a>.
3869: Will throw an
3870: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception if the given time is not
3871: within the ranges to which the user agent can seek.</p>
3872:
3873: </dd>
3874:
3875: <dt><var title="">media</var> . <code title="dom-media-initialTime"><a href="#dom-media-initialtime">initialTime</a></code></dt>
3876:
3877: <dd>
3878:
3879: <p>Returns the <a href="#initial-playback-position">initial playback position</a>, that is, time
3880: to which the <a href="#media-resource">media resource</a> was automatically seeked
3881: when it was loaded. Returns zero if the <a href="#initial-playback-position">initial playback
3882: position</a> is still unknown.</p>
3883:
3884: </dd>
3885:
3886: </dl><div class="impl">
3887:
3888: <p>A <a href="#media-resource">media resource</a> has a <dfn id="media-timeline">media timeline</dfn>
3889: that maps times (in seconds) to positions in the <a href="#media-resource">media
3890: resource</a>. The origin of a timeline is its earliest defined
3891: position. The duration of a timeline is its last defined
3892: position.</p>
3893:
3894: <p><dfn id="defineTimeline" title="establish the media
3895: timeline">Establishing the media timeline</dfn>: If the <a href="#media-resource">media
3896: resource</a> somehow specifies an explicit timeline whose origin
3897: is not negative, then the <a href="#media-timeline">media timeline</a> should be that
3898: timeline. (Whether the <a href="#media-resource">media resource</a> can specify a
3899: timeline or not depends on the <a href="#media-resource" title="media resource">media
3900: resource's</a> format.) If the <a href="#media-resource">media resource</a>
3901: specifies an explicit start time <em>and date</em>, then that time
3902: and date should be considered the zero point in the <a href="#media-timeline">media
3903: timeline</a>; the <a href="#timeline-offset">timeline offset</a> will be the time
3904: and date, exposed using the <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
3905: attribute.</p>
3906:
3907: <p>If the <a href="#media-resource">media resource</a> has a discontinuous timeline,
3908: the user agent must extend the timeline used at the start of the
3909: resource across the entire resource, so that the <a href="#media-timeline">media
3910: timeline</a> of the <a href="#media-resource">media resource</a> increases
3911: linearly starting from the <a href="#earliest-possible-position">earliest possible position</a>
3912: (as defined below), even if the underlying <a href="#media-data">media data</a>
3913: has out-of-order or even overlapping time codes.</p>
3914:
3915: <p class="example">For example, if two clips have been concatenated
3916: into one video file, but the video format exposes the original times
3917: for the two clips, the video data might expose a timeline that goes,
3918: say, 00:15..00:29 and then 00:05..00:38. However, the user agent
3919: would not expose those times; it would instead expose the times as
3920: 00:15..00:29 and 00:29..01:02, as a single video.</p>
3921:
3922: <p>In the absence of an explicit timeline, the zero time on the
3923: <a href="#media-timeline">media timeline</a> should correspond to the first frame of
3924: the <a href="#media-resource">media resource</a>. For static audio and video files
3925: this is generally trivial. For streaming resources, if the user
3926: agent will be able to seek to an earlier point than the first frame
3927: originally provided by the server, then the zero time should
3928: correspond to the earliest seekable time of the <a href="#media-resource">media
3929: resource</a>; otherwise, it should correspond to the first frame
3930: received from the server (the point in the <a href="#media-resource">media
3931: resource</a> at which the user agent began receiving the
3932: stream).</p>
3933:
3934: <p class="example">Another example would be a stream that carries a
3935: video with several concatenated fragments, broadcast by a server
3936: that does not allow user agents to request specific times but
3937: instead just streams the video data in a predetermined order. If a
3938: user agent connects to this stream and receives fragments defined as
3939: covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
3940: UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
3941: expose this with a <a href="#media-timeline">media timeline</a> starting at 0s and
3942: extending to 3,600s (one hour). Assuming the streaming server
3943: 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
3944: return 3,600. The <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code> attribute
3945: would return a <code>Date</code> object with a time corresponding to
3946: 2010-03-20 23:15:00 UTC. However, if a different user agent
3947: connected five minutes later, <em>it</em> would (presumably) receive
3948: fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
3949: 00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
3950: and would expose this with a <a href="#media-timeline">media timeline</a> starting at
3951: 0s and extending to 3,300s (fifty five minutes). In this case, the
3952: <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
3953: attribute would return a <code>Date</code> object with a time
3954: corresponding to 2010-03-20 23:20:00 UTC.</p>
3955:
3956: <p>In any case, the user agent must ensure that the <a href="#earliest-possible-position">earliest
3957: possible position</a> (as defined below) using the established
3958: <a href="#media-timeline">media timeline</a>, is greater than or equal to zero.</p>
3959:
3960: <p>The <a href="#media-timeline">media timeline</a> also has an associated clock.
3961: Which clock is used is user-agent defined, and may be <a href="#media-resource">media
3962: resource</a>-dependent, but it should approximate the user's wall
3963: clock.</p>
3964:
3965: <p class="note">All the <a href="#media-element" title="media element">media
3966: elements</a> that share <a href="#current-media-controller">current media controller</a> use
3967: the same clock for their <a href="#media-timeline">media timeline</a>.</p>
3968:
3969: <p><a href="#media-element" title="media element">Media elements</a> have a
3970: <dfn id="current-playback-position">current playback position</dfn>, which must initially (i.e. in
3971: the absence of <a href="#media-data">media data</a>) be zero seconds. The
3972: <a href="#current-playback-position">current playback position</a> is a time on the <a href="#media-timeline">media
3973: timeline</a>.</p>
3974:
3975: <p>The <dfn id="dom-media-currenttime" title="dom-media-currentTime"><code>currentTime</code></dfn>
3976: attribute must, on getting, return the <a href="#current-playback-position">current playback
3977: position</a>, expressed in seconds. On setting,
3978: if the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
3979: controller</a>, then it must throw an
3980: <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception; otherwise,
3981: the user agent
3982: must <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the new value
3983: (which might raise an exception).</p>
3984:
3985: <p><a href="#media-element" title="media element">Media elements</a> have an
3986: <dfn id="initial-playback-position">initial 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="#initial-playback-position">initial playback position</a> is updated when a <a href="#media-resource">media
3989: resource</a> is loaded. The <a href="#initial-playback-position">initial playback
3990: position</a> is a time on the <a href="#media-timeline">media timeline</a>.</p>
3991:
1.50 mike 3992: <p>The <dfn id="dom-media-initialtime" title="dom-media-initialTime"><code>initialTime</code></dfn>
1.47 mike 3993: attribute must, on getting, return the <a href="#initial-playback-position">initial playback
3994: position</a>, expressed in seconds.</p>
3995:
3996: <p>If the <a href="#media-resource">media resource</a> is a streaming resource, then
3997: the user agent might be unable to obtain certain parts of the
3998: resource after it has expired from its buffer. Similarly, some <a href="#media-resource" title="media resource">media resources</a> might have a
3999: <a href="#media-timeline">media timeline</a> that doesn't start at zero. The
4000: <dfn id="earliest-possible-position">earliest possible position</dfn> is the earliest position in
4001: the stream or resource that the user agent can ever obtain
4002: again. It is also a time on the <a href="#media-timeline">media timeline</a>.</p>
4003:
4004: <p class="note">The <a href="#earliest-possible-position">earliest possible position</a> is not
4005: explicitly exposed in the API; it corresponds to the start time of
4006: the first range in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute's
4007: <code><a href="#timeranges">TimeRanges</a></code> object, if any, or the <a href="#current-playback-position">current
4008: playback position</a> otherwise.</p>
4009:
4010: <p>When the <a href="#earliest-possible-position">earliest possible position</a> changes, then:
4011: if the <a href="#current-playback-position">current playback position</a> is before the
4012: <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
4013: 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
4014: element in the past 15 to 250ms and is not still running event
4015: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4016: 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>
4017:
4018: <p class="note">Because of the above requirement and the requirement
4019: in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
4020: algorithm</a> that kicks in <a href="#getting-media-metadata">when the metadata of the clip becomes
4021: known</a>, the <a href="#current-playback-position">current playback position</a> can never be
4022: less than the <a href="#earliest-possible-position">earliest possible position</a>.</p>
4023:
4024: <p>The <dfn id="dom-media-duration" title="dom-media-duration"><code>duration</code></dfn>
4025: attribute must return the time of the end of the <a href="#media-resource">media
4026: resource</a>, in seconds, on the <a href="#media-timeline">media timeline</a>. If
4027: no <a href="#media-data">media data</a> is available, then the attributes must
4028: return the Not-a-Number (NaN) value. If the <a href="#media-resource">media
1.62 mike 4029: resource</a> is not known to be bounded (e.g. streaming radio, or
4030: a live event with no announced end time), then the attribute must
4031: return the positive Infinity value.</p>
1.47 mike 4032:
4033: <p>The user agent must determine the duration of the <a href="#media-resource">media
4034: resource</a> before playing any part of the <a href="#media-data">media
4035: data</a> and before setting <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> to a value equal to
4036: or greater than <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, even if doing
4037: so requires fetching multiple parts of the resource.</p>
4038:
4039: <p id="durationChange">When the length of the <a href="#media-resource">media
4040: resource</a> changes to a known value (e.g. from being unknown to
4041: known, or from a previously established length to a new length) the
4042: 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
4043: event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
4044: <a href="#media-element">media element</a>. (The event is not fired when the
1.63 mike 4045: duration is reset as part of loading a new media resource.) If the
4046: duration is changed such that the <a href="#current-playback-position">current playback
4047: position</a> ends up being greater than the time of the end of
4048: the <a href="#media-resource">media resource</a>, then the user agent must also <a href="#dom-media-seek" title="dom-media-seek">seek</a> the to the time of the end of the
4049: <a href="#media-resource">media resource</a>.</p>
1.47 mike 4050:
4051: <p class="example">If an "infinite" stream ends for some reason,
4052: then the duration would change from positive Infinity to the time of
4053: 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
4054: be fired. Similarly, if the user agent initially estimated the
4055: <a href="#media-resource">media resource</a>'s duration instead of determining it
4056: precisely, and later revises the estimate based on new information,
4057: then the duration would change and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
4058: be fired.</p>
4059:
4060: <p>Some video files also have an explicit date and time
4061: corresponding to the zero time in the <a href="#media-timeline">media timeline</a>,
4062: known as the <dfn id="timeline-offset">timeline offset</dfn>. Initially, the
4063: <a href="#timeline-offset">timeline offset</a> must be set to Not-a-Number (NaN).</p>
4064:
4065: <p>The <dfn id="dom-media-startoffsettime" title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
4066: attribute must return a new <code>Date</code> object representing
4067: the current <a href="#timeline-offset">timeline offset</a>.</p>
4068:
4069: </div><hr><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn>
4070: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that, if specified,
4071: indicates that the <a href="#media-element">media element</a> is to seek back to the
4072: 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
4073: effect while the element has a <a href="#current-media-controller">current media
4074: controller</a>.</p><div class="impl">
4075:
4076: <p>The <dfn id="dom-media-loop" title="dom-media-loop"><code>loop</code></dfn> IDL
4077: attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4078: same name.</p>
4079:
4080: </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>
4081:
4082: <dd>
4083:
4084: <p>Returns a value that expresses the current state of the element
4085: with respect to rendering the <a href="#current-playback-position">current playback
4086: position</a>, from the codes in the list below.</p>
4087:
4088: </dd>
4089:
4090: </dl><div class="impl">
4091:
4092: <p><a href="#media-element" title="media element">Media elements</a> have a
4093: <i>ready state</i>, which describes to what degree they are ready
4094: to be rendered at the <a href="#current-playback-position">current playback position</a>. The
4095: possible values are as follows; the ready state of a media element
4096: at any particular time is the greatest value describing the state of
4097: the element:</p>
4098:
4099: </div><dl><dt><dfn id="dom-media-have_nothing" title="dom-media-HAVE_NOTHING"><code>HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
4100:
4101: <dd>No information regarding the <a href="#media-resource">media resource</a> is
4102: available. No data for the <a href="#current-playback-position">current playback position</a>
4103: is available. <a href="#media-element" title="media element">Media elements</a>
4104: whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code>
4105: attribute are set to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> are always in
4106: the <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>
4107: state.</dd>
4108:
4109: <dt><dfn id="dom-media-have_metadata" title="dom-media-HAVE_METADATA"><code>HAVE_METADATA</code></dfn> (numeric value 1)</dt>
4110:
4111: <dd>Enough of the resource has been obtained that the duration of
4112: the resource is available. In the case of a <code><a href="#the-video-element">video</a></code>
4113: element, the dimensions of the video are also available. The API
4114: will no longer raise an exception when seeking. No <a href="#media-data">media
4115: data</a> is available for the immediate <a href="#current-playback-position">current playback
4116: position</a>.
4117: The <a href="#text-track" title="text track">text tracks</a>
4118: are <a href="#the-text-tracks-are-ready" title="the text tracks are ready">ready</a>.
4119: </dd>
4120:
4121: <dt><dfn id="dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA"><code>HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
4122:
4123: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4124: is available, but either not enough data is available that the user
4125: agent could successfully advance the <a href="#current-playback-position">current playback
4126: position</a> in the <a href="#direction-of-playback">direction of playback</a> at all
4127: without immediately reverting to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4128: there is no more data to obtain in the <a href="#direction-of-playback">direction of
4129: playback</a>. For example, in video this corresponds to the user
1.62 mike 4130: agent having data from the current frame, but not the next frame,
4131: when the <a href="#current-playback-position">current playback position</a> is at the end of
4132: the current frame; and to when <a href="#ended-playback" title="ended
4133: playback">playback has ended</a>.</dd>
1.47 mike 4134:
4135: <dt><dfn id="dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA"><code>HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
4136:
4137: <dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
4138: is available, as well as enough data for the user agent to advance
4139: the <a href="#current-playback-position">current playback position</a> in the <a href="#direction-of-playback">direction
4140: of playback</a> at least a little without immediately reverting
4141: to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
4142: state. For example, in video this corresponds to the user agent
1.62 mike 4143: having data for at least the current frame and the next frame when
4144: the <a href="#current-playback-position">current playback position</a> is at the instant in
4145: time between the two frames, or to the user agent having the video
4146: data for the current frame and audio data to keep playing at least
4147: a little when the <a href="#current-playback-position">current playback position</a> is in the
4148: middle of a frame. The user agent cannot be in this state if <a href="#ended-playback" title="ended playback">playback has ended</a>, as the
4149: <a href="#current-playback-position">current playback position</a> can never advance in this
4150: case.</dd>
1.47 mike 4151:
4152: <dt><dfn id="dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA"><code>HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
4153:
4154: <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
4155: are met, and, in addition, the user agent estimates that data is
4156: being fetched at a rate where the <a href="#current-playback-position">current playback
4157: position</a>, if it were to advance at the <a href="#effective-playback-rate">effective
4158: playback rate</a>, would not overtake the available data before
4159: playback reaches the end of the <a href="#media-resource">media resource</a>.</dd>
4160:
1.62 mike 4161: </dl><p class="note">In practice, the difference between <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> is
4162: negligible. Really the only time the difference is relevant is when
4163: painting a <code><a href="#the-video-element">video</a></code> element onto a <code><a href="the-canvas-element.html#the-canvas-element">canvas</a></code>,
4164: where it distinguishes the case where something will be drawn (<code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> or
4165: greater) from the case where nothing is drawn (<code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> or less).
4166: Similarly, the difference between <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> (only
4167: the current frame) and <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> (at least
4168: this frame and the next) can be negligible (in the extreme, only one
4169: frame). The only time that distinction really matters is when a page
4170: provides an interface for "frame-by-frame" navigation.</p><div class="impl">
1.47 mike 4171:
4172: <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
4173: user agent must follow the steps given below:</p>
4174:
4175: <ol><li>
4176:
4177: <p>Apply the first applicable set of substeps from the following
4178: list:</p>
4179:
4180:
4181: <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
4182: ready state is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code></dt>
4183:
4184: <dd id="fire-loadedmetadata">
4185:
4186: <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>
4187: named <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> at the
4188: element.</p>
4189:
4190: <p class="note">Before this task is run, as part of the event
4191: loop mechanism, the rendering will have been updated to resize
4192: the <code><a href="#the-video-element">video</a></code> element if appropriate.</p>
4193:
4194: </dd>
4195:
4196:
4197:
4198: <dt id="handling-first-frame-available">If the previous ready state
4199: was <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> and
4200: 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
4201: greater</dt>
4202:
4203: <dd>
4204:
4205: <p id="fire-loadeddata">If this is the first time this occurs for
4206: 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,
4207: 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
4208: simple event</a> named <code title="event-media-loadeddata"><a href="#event-media-loadeddata">loadeddata</a></code> at the element.</p>
4209:
4210: <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
4211: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>,
4212: then the relevant steps below must then be run also.</p>
4213:
4214: </dd>
4215:
4216:
4217: <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,
4218: 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
4219: less</dt>
4220:
4221: <dd>
4222:
4223: <p id="fire-waiting-when-waiting">If the <a href="#media-element">media
4224: element</a> was <a href="#potentially-playing">potentially playing</a> before its
4225: <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
4226: 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
4227: the element has not <a href="#ended-playback">ended playback</a>, and playback
4228: has not <a href="#stopped-due-to-errors">stopped due to errors</a>, and playback has not
4229: <a href="#paused-for-user-interaction">paused for user interaction</a>, the user agent must
4230: <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>
4231: named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at
4232: 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
4233: simple event</a> named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the element.</p>
4234:
4235: </dd>
4236:
4237:
4238: <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
4239: 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>
4240:
4241: <dd>
4242:
4243: <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
4244: simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>.</p>
4245:
4246: <p>If the element's <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4247: attribute is false, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
4248: 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>
4249:
4250: </dd>
4251:
4252:
4253: <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>
4254:
4255: <dd>
4256:
4257: <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
4258: 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
4259: a simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>, and, if the element's
4260: <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false,
4261: <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>
4262: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4263:
4264: <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
4265: <a href="#media-element">media element</a> has an <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute specified,
4266: and the <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s
4267: <a href="browsers.html#browsing-context">browsing context</a> did not have the <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed
4268: automatic features browsing context flag</a> set when the
4269: <code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent may also
4270: set the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute to
4271: false, <a href="webappapis.html#queue-a-task">queue a task</a> to <a href="webappapis.html#fire-a-simple-event">fire a simple
4272: event</a> named <code title="event-media-play"><a href="#event-media-play">play</a></code>, and
4273: <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>
4274: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
4275:
4276: <p class="note">User agents do not need to support autoplay,
4277: and it is suggested that user agents honor user preferences on the
4278: matter. Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
4279: using script to force the video to play, so as to allow the user
4280: to override the behavior if so desired.</p>
4281:
4282: <p>In any case, the user agent must finally <a href="webappapis.html#queue-a-task">queue a
4283: 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>
4284:
4285: </dd>
4286:
4287: </dl></li>
4288:
4289: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4290: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4291: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4292: controller</a>.</p></li>
4293:
4294: </ol></div><p class="note">It is possible for the ready state of a media
4295: element to jump between these states discontinuously. For example,
4296: 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
4297: passing through the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> and
4298: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>
4299: states.</p><div class="impl">
4300:
4301: <p>The <dfn id="dom-media-readystate" title="dom-media-readyState"><code>readyState</code></dfn> IDL
4302: attribute must, on getting, return the value described above that
4303: describes the current ready state of the <a href="#media-element">media
4304: element</a>.</p>
4305:
4306: </div><p>The <dfn id="attr-media-autoplay" title="attr-media-autoplay"><code>autoplay</code></dfn>
4307: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When present, the
4308: user agent <span class="impl">(as described in the algorithm
4309: described herein)</span> will automatically begin playback of the
4310: <a href="#media-resource">media resource</a> as soon as it can do so without
4311: 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
4312: using script to trigger automatic playback, as this allows the user
4313: to override the automatic playback when it is not desired, e.g. when
4314: using a screen reader. Authors are also encouraged to consider not
4315: using the automatic playback behavior at all, and instead to let the
4316: user agent wait for the user to start playback explicitly.</p><div class="impl">
4317:
4318: <p>The <dfn id="dom-media-autoplay" title="dom-media-autoplay"><code>autoplay</code></dfn>
4319: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
4320: same name.</p>
4321:
4322: </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>
4323:
4324: <dd>
4325:
4326: <p>Returns true if playback is paused; false otherwise.</p>
4327:
4328: </dd>
4329:
4330: <dt><var title="">media</var> . <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code></dt>
4331:
4332: <dd>
4333:
4334: <p>Returns true if playback has reached the end of the <a href="#media-resource">media resource</a>.</p>
4335:
4336: </dd>
4337:
4338: <dt><var title="">media</var> . <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
4339:
4340: <dd>
4341:
4342: <p>Returns the default rate of playback, for when the user is not
4343: fast-forwarding or reversing through the <a href="#media-resource">media
4344: resource</a>.</p>
4345:
4346: <p>Can be set, to change the default rate of playback.</p>
4347:
4348: <p>The default rate has no direct effect on playback, but if the
4349: user switches to a fast-forward mode, when they return to the
4350: normal playback mode, it is expected that the rate of playback
4351: will be returned to the default rate of playback.</p>
4352:
4353: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4354: the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
4355: attribute is ignored and the <a href="#current-media-controller">current media
4356: controller</a>'s <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code>
4357: is used instead.</p>
4358:
4359: </dd>
4360:
4361: <dt><var title="">media</var> . <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
4362:
4363: <dd>
4364:
4365: <p>Returns the current rate playback, where 1.0 is normal speed.</p>
4366:
4367: <p>Can be set, to change the rate of playback.</p>
4368:
4369: <p>When the element has a <a href="#current-media-controller">current media controller</a>,
4370: the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>
4371: attribute is ignored and the <a href="#current-media-controller">current media
4372: controller</a>'s <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> is
4373: used instead.</p>
4374:
4375: </dd>
4376:
4377: <dt><var title="">media</var> . <code title="dom-media-played"><a href="#dom-media-played">played</a></code></dt>
4378:
4379: <dd>
4380:
4381: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4382: ranges of the <a href="#media-resource">media resource</a> that the user agent has
4383: played.</p>
4384:
4385: </dd>
4386:
4387: <dt><var title="">media</var> . <code title="dom-media-play"><a href="#dom-media-play">play</a></code>()</dt>
4388:
4389: <dd>
4390:
4391: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4392: to false, loading the <a href="#media-resource">media resource</a> and beginning
4393: playback if necessary. If the playback had ended, will restart it
4394: from the start.</p>
4395:
4396: </dd>
4397:
4398: <dt><var title="">media</var> . <code title="dom-media-pause"><a href="#dom-media-pause">pause</a></code>()</dt>
4399:
4400: <dd>
4401:
4402: <p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
4403: to true, loading the <a href="#media-resource">media resource</a> if necessary.</p>
4404:
4405: </dd>
4406:
4407: </dl><div class="impl">
4408:
4409: <p>The <dfn id="dom-media-paused" title="dom-media-paused"><code>paused</code></dfn>
4410: attribute represents whether the <a href="#media-element">media element</a> is
4411: paused or not. The attribute must initially be true.</p>
4412:
4413: <p>A <a href="#media-element">media element</a> is a <dfn id="blocked-media-element">blocked media
4414: element</dfn> if its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is in the
1.62 mike 4415: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> state, the
4416: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
4417: the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> state,
4418: or if the element has <a href="#paused-for-user-interaction">paused for user interaction</a>.</p>
1.47 mike 4419:
4420: <p>A <a href="#media-element">media element</a> is said to be <dfn id="potentially-playing">potentially
4421: playing</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
4422: attribute is false, the element has not <a href="#ended-playback">ended playback</a>,
4423: playback has not <a href="#stopped-due-to-errors">stopped due to errors</a>,
4424: the element either has no <a href="#current-media-controller">current media controller</a> or
4425: has a <a href="#current-media-controller">current media controller</a> but is not <a href="#blocked-on-its-media-controller">blocked
4426: on its media controller</a>,
4427: and the element is not a <a href="#blocked-media-element">blocked media element</a>.</p>
4428:
4429: <p>A <a href="#media-element">media element</a> is said to have <dfn id="ended-playback">ended
4430: playback</dfn> when:</p>
4431:
4432: <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,
4433: and
4434:
4435: </li><li>
4436:
4437: <p>Either:
4438:
4439: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the end of the
4440: <a href="#media-resource">media resource</a>, and
4441:
4442: </li><li>The <a href="#direction-of-playback">direction of playback</a> is forwards, and
4443:
4444: </li><li>
4445: Either
4446: 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,
4447: or the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4448: controller</a>.
4449:
4450: </li></ul><p>Or:
4451:
4452: </p><ul><li>The <a href="#current-playback-position">current playback position</a> is the
4453: <a href="#earliest-possible-position">earliest possible position</a>, and
4454:
4455: </li><li>The <a href="#direction-of-playback">direction of playback</a> is backwards.
4456:
4457: </li></ul></li>
4458:
4459: </ul><p>The <dfn id="dom-media-ended" title="dom-media-ended"><code>ended</code></dfn>
4460: attribute must return true if the <a href="#media-element">media element</a> has
4461: <a href="#ended-playback">ended playback</a> and the <a href="#direction-of-playback">direction of
4462: playback</a> is forwards, and false otherwise.</p>
4463:
4464: <p>A <a href="#media-element">media element</a> is said to have <dfn id="stopped-due-to-errors">stopped due to
4465: 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
4466: the user agent <a href="#non-fatal-media-error">encounters a
4467: non-fatal error</a> during the processing of the <a href="#media-data">media
4468: data</a>, and due to that error, is not able to play the content
4469: at the <a href="#current-playback-position">current playback position</a>.</p>
4470:
4471: <p>A <a href="#media-element">media element</a> is said to have <dfn id="paused-for-user-interaction">paused for user
4472: 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
4473: <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4474: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> and
4475: the user agent has reached a point in the <a href="#media-resource">media
4476: resource</a> where the user has to make a selection for the
4477: resource to continue.
4478: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4479: controller</a> when this happens, then the user agent must
4480: <a href="#report-the-controller-state">report the controller state</a> for the <a href="#media-element">media
4481: element</a>'s <a href="#current-media-controller">current media controller</a>. If If the
4482: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4483: controller</a> when the user makes a selection, allowing playback
4484: to resume, the user agent must similarly <a href="#report-the-controller-state">report the controller
4485: state</a> for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current
4486: media controller</a>.
4487: </p>
4488:
4489: <p>It is possible for a <a href="#media-element">media element</a> to have both
4490: <a href="#ended-playback">ended playback</a> and <a href="#paused-for-user-interaction">paused for user
4491: interaction</a> at the same time.</p>
4492:
4493: <p>When a <a href="#media-element">media element</a> that is <a href="#potentially-playing">potentially
4494: playing</a> stops playing because it has <a href="#paused-for-user-interaction">paused for user
4495: interaction</a>, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
4496: <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>
4497:
4498: <p class="note">A <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code>
4499: DOM event <a href="#fire-waiting-when-waiting">can be fired</a> as a
4500: result of an element that is <a href="#potentially-playing">potentially playing</a>
4501: stopping playback due to its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute changing to
4502: a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.</p>
4503:
4504: <p>When the <a href="#current-playback-position">current playback position</a> reaches the end
4505: of the <a href="#media-resource">media resource</a> when the <a href="#direction-of-playback">direction of
4506: playback</a> is forwards, then the user agent must follow these
4507: steps:</p>
4508:
4509: <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
4510: and does not have a <a href="#current-media-controller">current media controller</a>,
4511: then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4512: possible position</a> of the <a href="#media-resource">media resource</a> and
4513: abort these steps.</p></li>
4514: <li><p>Stop playback.</p><p class="note">The <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> attribute becomes
4515: true.</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-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
4519:
4520: <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
4521: a simple event</a> named <code title="event-media-ended"><a href="#event-media-ended">ended</a></code>
4522: at the element.</p></li>
4523:
4524: </ol><p>When the <a href="#current-playback-position">current playback position</a> reaches the
4525: <a href="#earliest-possible-position">earliest possible position</a> of the <a href="#media-resource">media
4526: resource</a> when the <a href="#direction-of-playback">direction of playback</a> is
4527: backwards, then the user agent must follow these steps:</p>
4528:
4529: <ol><li><p>Stop playback.</p></li>
4530:
4531: <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
4532: a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
4533:
4534: </ol><hr><p>The <dfn id="dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
4535: attribute gives the desired speed at which the <a href="#media-resource">media
4536: resource</a> is to play, as a multiple of its intrinsic
4537: speed. The attribute is mutable: on getting it must return the last
4538: value it was set to, or 1.0 if it hasn't yet been set; on setting
4539: the attribute must be set to the new value.</p>
4540:
4541: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> is
4542: used by the user agent when it <a href="#expose-a-user-interface-to-the-user" title="expose a user interface
4543: to the user">exposes a user interface to the user</a>.</p>
4544:
4545: <p>The <dfn id="dom-media-playbackrate" title="dom-media-playbackRate"><code>playbackRate</code></dfn>
4546: attribute gives the <a href="#effective-playback-rate">effective playback rate</a>
4547: (assuming there is no <a href="#current-media-controller">current media controller</a> overriding it),
4548: which is the speed at which the <a href="#media-resource">media resource</a> plays,
4549: as a multiple of its intrinsic speed. If it is not equal to the
4550: <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>,
4551: then the implication is that the user is using a feature such as
4552: fast forward or slow motion playback. The attribute is mutable: on
4553: getting it must return the last value it was set to, or 1.0 if it
4554: hasn't yet been set; on setting the attribute must be set to the new
4555: value, and the playback will change speed
4556: (if the element is <a href="#potentially-playing">potentially playing</a> and there is no
4557: <a href="#current-media-controller">current media controller</a>).</p>
4558:
4559: <p id="rateUpdate">When the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or
4560: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4561: change value (either by being set by script or by being changed
4562: directly by the user agent, e.g. in response to user control) the
4563: 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
4564: event</a> named <code title="event-media-ratechange"><a href="#event-media-ratechange">ratechange</a></code> at the <a href="#media-element">media
4565: element</a>.</p>
4566:
4567: <p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> and
4568: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
4569: have no effect when the <a href="#media-element">media element</a> has a
4570: <a href="#current-media-controller">current media controller</a>; the namesake attributes on
4571: the <code><a href="#mediacontroller">MediaController</a></code> object are used instead in that
4572: situation.</p>
4573:
4574: <hr><p>The <dfn id="dom-media-played" title="dom-media-played"><code>played</code></dfn>
4575: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4576: <code>TimeRanges</code> object</a> that represents the ranges of
4577: the <a href="#media-resource">media resource</a>, if any, that the user agent has so
4578: far rendered, at the time the attribute is evaluated.</p>
4579:
4580: <hr><p>When the <dfn id="dom-media-play" title="dom-media-play"><code>play()</code></dfn>
4581: method on a <a href="#media-element">media element</a> is invoked, the user agent
4582: must run the following steps.</p>
4583:
4584: <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
4585: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4586: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4587: algorithm</a>.</p></li>
4588:
4589: <li>
4590:
4591: <p>If the <a href="#ended-playback" title="ended playback">playback has ended</a>
4592: and the <a href="#direction-of-playback">direction of playback</a> is forwards,
4593: and the <a href="#media-element">media element</a> does not have a <a href="#current-media-controller">current
4594: media controller</a>,
4595: <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
4596: possible position</a> of the <a href="#media-resource">media resource</a>.</p>
4597:
4598: <p class="note">This <a href="#seekUpdate">will cause</a> the user
4599: 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
4600: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the <a href="#media-element">media
4601: element</a>.</p>
4602: </li>
4603:
4604: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
4605: media controller</a>, then <a href="#bring-the-media-element-up-to-speed-with-its-new-media-controller">bring the media element up
4606: to speed with its new media controller</a>.</p>
4607:
4608: </li><li>
4609:
4610: <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
4611: the following substeps:</p>
4612:
4613: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to false.</p></li>
4614:
4615: <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>
4616: named <code title="event-media-play"><a href="#event-media-play">play</a></code> at the element.</p></li>
4617:
4618: <li>
4619:
4620: <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
4621: value <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>,
4622: <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, or
4623: <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
4624: <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>
4625: named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the
4626: element.</p>
4627:
4628: <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
4629: value <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
4630: <code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>:
4631: <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>
4632: named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> at the
4633: element.</p>
4634:
4635: </li>
4636:
4637: </ol></li>
4638:
4639: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4640: flag</a> to false.</p></li>
4641:
4642: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4643: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4644: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4645: controller</a>.</p></li>
4646:
4647: </ol><hr><p>When the <dfn id="dom-media-pause" title="dom-media-pause"><code>pause()</code></dfn>
4648: method is invoked, and when the user agent is required to pause the
4649: <a href="#media-element">media element</a>, the user agent must run the following
4650: steps:</p>
4651:
4652: <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
4653: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
4654: <a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
4655: algorithm</a>.</p></li>
4656:
4657: <li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
4658: flag</a> to false.</p></li>
4659:
4660: <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
4661: following steps:</p>
4662:
4663: <ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to true.</p></li>
4664:
4665: <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
4666: event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4667: element.</p></li>
4668:
4669: <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
4670: event</a> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code>
4671: at the element.</p></li>
4672:
4673: </ol></li>
4674:
4675: <li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4676: controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
4677: for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
4678: controller</a>.</p></li>
4679:
4680: </ol><hr><p>The
4681: <dfn id="effective-playback-rate">effective playback rate</dfn> is not necessarily the element's
4682: <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>. When a
4683: <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
4684: controller</a>, its <a href="#effective-playback-rate">effective playback rate</a> is the
4685: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
4686: rate</a>. Otherwise, the
4687: <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>.
4688: Thus, the <a href="#current-media-controller">current media controller</a> overrides the
4689: <a href="#media-element">media element</a>.
4690: </p>
4691:
4692: <p>If the <a href="#effective-playback-rate">effective playback rate</a> is positive or zero,
4693: then the <dfn id="direction-of-playback">direction of playback</dfn> is forwards. Otherwise, it
4694: is backwards.</p>
4695:
4696: <p id="media-playback">When a <a href="#media-element">media element</a> is
4697: <a href="#potentially-playing">potentially playing</a> and its <code><a href="infrastructure.html#document">Document</a></code> is a
4698: <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
4699: playback position</a> must increase monotonically at
4700: <a href="#effective-playback-rate">effective playback rate</a> units of media time per unit time
4701: of the <a href="#media-timeline">media timeline</a>'s clock.</p>
4702:
4703: <p class="note">The <a href="#effective-playback-rate">effective playback rate</a> can be 0.0,
4704: in which case the <a href="#current-playback-position">current playback position</a> doesn't
4705: 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
4706: <code title="event-media-pause"><a href="#event-media-pause">pause</a></code> event doesn't
4707: fire).</p>
4708:
4709: <p class="note">This specification doesn't define how the user agent
4710: achieves the appropriate playback rate — depending on the
4711: protocol and media available, it is plausible that the user agent
4712: could negotiate with the server to have the server provide the media
4713: data at the appropriate rate, so that (except for the period between
4714: when the rate is changed and when the server updates the stream's
4715: playback rate) the client doesn't actually have to drop or
4716: interpolate any frames.</p>
4717:
4718: <p>When the <a href="#direction-of-playback">direction of playback</a> is backwards, any
4719: corresponding audio must be muted. When the <a href="#effective-playback-rate">effective playback
4720: rate</a> is so low or so high that the user agent cannot play
4721: audio usefully, the corresponding audio must also be muted. If the
4722: <a href="#effective-playback-rate">effective playback rate</a> is not 1.0, the user agent may
4723: apply pitch adjustments to the audio as necessary to render it
4724: faithfully.</p>
4725:
4726: <p><a href="#media-element" title="media element">Media elements</a> that are
4727: <a href="#potentially-playing">potentially playing</a> while not <a href="infrastructure.html#in-a-document">in a
4728: <code>Document</code></a> must not play any video, but should
4729: play any audio component. Media elements must not stop playing just
4730: because all references to them have been removed; only once a media
4731: element is in a state where no further audio could ever be played by
4732: that element may the element be garbage collected.</p>
4733:
4734: <p class="note">It is possible for an element to which no explicit
4735: references exist to play audio, even if such an element is not still
4736: actively playing: for instance, it could have a <a href="#current-media-controller">current media
4737: controller</a> that still has references and can still be
4738: unpaused, or it could be unpaused but stalled waiting for content to
4739: buffer.</p>
4740:
4741: <hr><p>When the <a href="#current-playback-position">current playback position</a> of a <a href="#media-element">media
4742: element</a> changes (e.g. due to playback or seeking), the user
4743: agent must run the following steps. If the <a href="#current-playback-position">current playback
4744: position</a> changes while the steps are running, then the user
4745: agent must wait for the steps to complete, and then must immediately
4746: rerun the steps.
4747: (These steps are thus run as often as possible or needed — if
4748: 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
4749: agent rushes ahead to "catch up".)
4750: </p>
4751:
4752: <ol><li><p>Let <var title="">current cues</var> be an ordered list of
4753: <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
4754: 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
4755: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
4756: default">showing by default</a> <a href="#text-track" title="text track">text
4757: 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
4758: or equal to the <a href="#current-playback-position">current playback position</a> and whose
4759: <a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are greater
4760: than the <a href="#current-playback-position">current playback position</a>, in <a href="#text-track-cue-order">text
4761: track cue order</a>.</p></li>
4762:
4763: <li><p>Let <var title="">other cues</var> be an ordered list of
4764: <a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
4765: 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
4766: showing">showing</a>, and <a href="#text-track-showing-by-default" title="text track showing by
4767: default">showing by default</a> <a href="#text-track" title="text track">text
4768: tracks</a> of the <a href="#media-element">media element</a> that are not
4769: present in <var title="">current cues</var>, also in <a href="#text-track-cue-order">text
4770: track cue order</a>.</p></li>
4771:
4772: <li><p>If the time was reached through the usual monotonic increase
4773: of the <a href="#current-playback-position">current playback position</a> during normal
4774: 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
4775: element in the past 15 to 250ms and is not still running event
4776: handlers for such an event, then the user agent must <a href="webappapis.html#queue-a-task">queue a
4777: 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.
4778: (In the other cases, such as explicit seeks, relevant events get
4779: fired as part of the overall process of changing the <a href="#current-playback-position">current
4780: playback position</a>.)</p>
4781:
4782: <p class="note">The event thus is not to be fired faster than about
4783: 66Hz or slower than 4Hz (assuming the event handlers don't take
4784: longer than 250ms to run). User agents are encouraged to vary the
4785: frequency of the event based on the system load and the average
4786: cost of processing the event each time, so that the UI updates are
4787: not any more frequent than the user agent can comfortably handle
4788: while decoding the video.</p></li>
4789:
4790: <li><p>If all of the <a href="#text-track-cue" title="text track cue">cues</a> in
4791: <var title="">current cues</var> have their <a href="#text-track-cue-active-flag">text track cue
4792: active flag</a> set, and none of the <a href="#text-track-cue" title="text track
4793: cue">cues</a> in <var title="">other cues</var> have their
4794: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, then abort these
4795: steps.</p></li>
4796:
4797: <li><p>If the time was reached through the usual monotonic increase
4798: of the <a href="#current-playback-position">current playback position</a> during normal
4799: playback, and there are <a href="#text-track-cue" title="text track cue">cues</a> in
4800: <var title="">other cues</var> that have both their <a href="#text-track-cue-active-flag">text
4801: track cue active flag</a> set and their <a href="#text-track-cue-pause-on-exit-flag">text track cue
4802: 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
4803: element</a>. (In the other cases, such as explicit
4804: 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
4805: track cue">cue</a> has its <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
4806: flag</a> set.)</p></li>
4807:
4808: <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>
4809:
4810: <li><p>For each <a href="#text-track-cue" title="text track cue">text track
4811: cue</a> in <var title="">other cues</var> that has its
4812: <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
4813: <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
4814: <code title="event-exit">exit</code> at the
4815: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
4816: 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
4817: list.</p></li>
4818:
4819: <li><p>For each <a href="#text-track-cue" title="text track cue">text track
4820: cue</a> in <var title="">current cues</var> that does not have
4821: its <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
4822: <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
4823: <code title="event-enter">enter</code> at the
4824: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
4825: 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
4826: list.</p></li>
4827:
4828: <li><p>For each <a href="#text-track">text track</a> in <var title="">affected
4829: tracks</var>, in the order they were added to the list (which will
4830: match the relative order of the <a href="#text-track" title="text track">text
4831: tracks</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
4832: 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
4833: simple event</a> named <code title="event-cuechange">cuechange</code> at the
4834: <code><a href="#texttrack">TextTrack</a></code> object, and, if the <a href="#text-track">text
4835: track</a> has a corresponding <code><a href="#the-track-element">track</a></code> element, to
4836: 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>
4837: element as well.</p></li>
4838:
4839: <li><p>Set the <a href="#text-track-cue-active-flag">text track cue active flag</a> of all the
4840: <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
4841: active flag</a> of all the <a href="#text-track-cue" title="text track
4842: cue">cues</a> in the <var title="">other cues</var>.</p></li>
4843:
4844: <li><p>Run the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
4845: rendering</a> of each of the <a href="#text-track" title="text track">text
4846: 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
4847: track showing by default">showing by default</a>.
4848: </p></li>
4849:
4850: </ol><p>For the purposes of the algorithm above, a <a href="#text-track-cue">text track
4851: cue</a> is considered to be part of a <a href="#text-track">text track</a>
4852: only if it is listed in the <a href="#text-track-list-of-cues">text track list of cues</a>,
4853: not merely if it is associated with the <a href="#text-track">text
4854: track</a>.</p>
4855:
4856: <p class="note">If the <a href="#media-element">media element</a>'s
4857: <code><a href="infrastructure.html#document">Document</a></code> stops being a <a href="browsers.html#fully-active">fully active</a>
4858: document, then the playback will <a href="#media-playback">stop</a>
4859: until the document is active again.</p>
4860:
4861: <p>When a <a href="#media-element">media element</a> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an
4862: element from a document">removed from a
4863: <code>Document</code></a>, the user agent must run
4864: the following steps:</p>
4865:
4866: <ol><li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
4867: the <a href="webappapis.html#concept-task" title="concept-task">task</a> that removed the
4868: <a href="#media-element">media element</a> from the <code><a href="infrastructure.html#document">Document</a></code> to
4869: continue. The <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the
4870: remaining steps of this algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous
4871: section</a> are marked with ⌛.)</p></li>
4872:
4873: <li><p>⌛ If the <a href="#media-element">media element</a> is <a href="infrastructure.html#in-a-document">in a
4874: <code>Document</code></a>, abort these steps.</p></li>
4875:
4876: <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
4877: the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, abort these
4878: steps.</p></li>
4879:
4880: <li><p>⌛ <a href="#dom-media-pause" title="dom-media-pause">Pause</a> the
4881: <a href="#media-element">media element</a>.</p>
4882:
4883: </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>
4884:
4885: <dd>
4886:
4887: <p>Returns true if the user agent is currently seeking.</p>
4888:
4889: </dd>
4890:
4891: <dt><var title="">media</var> . <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code></dt>
4892:
4893: <dd>
4894:
4895: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
4896: ranges of the <a href="#media-resource">media resource</a> to which it is possible
4897: for the user agent to seek.</p>
4898:
4899: </dd>
4900:
4901: </dl><div class="impl">
4902:
4903: <p>The <dfn id="dom-media-seeking" title="dom-media-seeking"><code>seeking</code></dfn>
4904: attribute must initially have the value false.</p>
4905:
4906: <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
4907: playback position</var> in the <a href="#media-resource">media resource</a>, it means
4908: that the user agent must run the following steps. This algorithm
4909: interacts closely with the <a href="webappapis.html#event-loop">event loop</a> mechanism; in
4910: particular, it has a <a href="webappapis.html#synchronous-section">synchronous
4911: section</a> (which is triggered as part of the <a href="webappapis.html#event-loop">event
4912: loop</a> algorithm). Steps in that section are marked with
4913: ⌛.</p>
4914:
4915: <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
4916: <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception (if the seek was in
4917: response to a DOM method call or setting of an IDL attribute), and
4918: abort these steps.</p></li>
4919:
4920: <li><p>If the element's <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute is true,
4921: then another instance of this algorithm is already running. Abort
4922: that other instance of the algorithm without waiting for the step
4923: that it is running to complete.</p></li>
4924:
4925: <li><p>Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL
4926: attribute to true.</p></li>
4927:
4928: <li><p>If the seek was in response to a DOM method call or setting
4929: of an IDL attribute, then continue the script. The remainder of
4930: these steps must be run asynchronously. With the exception of the
4931: steps marked with ⌛, they could be aborted at any time by
4932: another instance of this algorithm being invoked.</p></li>
4933:
4934: <li><p>If the <var title="">new playback position</var> is later
4935: than the end of the <a href="#media-resource">media resource</a>, then let it be the
4936: end of the <a href="#media-resource">media resource</a> instead.</p></li>
4937:
4938: <li><p>If the <var title="">new playback position</var> is less
4939: than the <a href="#earliest-possible-position">earliest possible position</a>, let it be that
4940: position instead.</p></li>
4941:
4942: <li><p>If the (possibly now changed) <var title="">new playback
4943: 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
4944: 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
4945: nearest to the <var title="">new playback position</var>. If two
4946: positions both satisfy that constraint (i.e. the <var title="">new
4947: playback position</var> is exactly in the middle between two ranges
4948: in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute)
4949: then use the position that is closest to the <a href="#current-playback-position">current playback
4950: 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
4951: <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
4952: false and abort these steps.</p></li>
4953:
4954: <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
4955: event</a> named <code title="event-media-seeking"><a href="#event-media-seeking">seeking</a></code>
4956: at the element.</p></li>
4957:
4958: <li>
4959:
4960: <p>Set the <a href="#current-playback-position">current playback position</a> to the given
4961: <var title="">new playback position</var>.</p>
4962:
4963: <p class="note">If the <a href="#media-element">media element</a> was
4964: <a href="#potentially-playing">potentially playing</a> immediately before it started
4965: seeking, but seeking caused its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to change
4966: 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
4967: <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
4968: element.</p>
4969:
4970:
4971: </li>
4972:
4973: <li><p>Wait until the user agent has established whether or not the
4974: <a href="#media-data">media data</a> for the <var title="">new playback
4975: position</var> is available, and, if it is, until it has decoded
4976: enough data to play back that position.</p>
4977: </li>
4978:
4979: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
4980: section</a> consists of all the remaining steps of this
4981: algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous section</a> are
4982: marked with ⌛.)</p></li>
4983:
4984: <li><p>⌛ Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
4985: false.</p></li>
4986:
4987: <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
4988: simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
4989: element.</p></li>
4990:
4991: <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
4992: event</a> named <code title="event-media-seeked"><a href="#event-media-seeked">seeked</a></code>
4993: at the element.</p></li>
4994:
4995: </ol><p>The <dfn id="dom-media-seekable" title="dom-media-seekable"><code>seekable</code></dfn>
4996: attribute must return a new static <a href="#normalized-timeranges-object">normalized
4997: <code>TimeRanges</code> object</a> that represents the ranges of
4998: the <a href="#media-resource">media resource</a>, if any, that the user agent is able
4999: to seek to, at the time the attribute is evaluated.</p>
5000:
5001: <p class="note">If the user agent can seek to anywhere in the
5002: <a href="#media-resource">media resource</a>, e.g. because it is a simple movie file
5003: and the user agent and the server support HTTP Range requests, then
5004: the attribute would return an object with one range, whose start is
5005: the time of the first frame (the <a href="#earliest-possible-position">earliest possible
5006: position</a>, typically zero), and whose end is the same as the
5007: time of the first frame plus the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute's value (which
5008: would equal the time of the last frame, and might be positive
5009: Infinity).</p>
5010:
5011: <p class="note">The range might be continuously changing, e.g. if
5012: the user agent is buffering a sliding window on an infinite
5013: stream. This is the behavior seen with DVRs viewing live TV, for
5014: instance.</p>
5015:
5016: <p><a href="#media-resource" title="media resource">Media resources</a> might be
5017: internally scripted or interactive. Thus, a <a href="#media-element">media
5018: element</a> could play in a non-linear fashion. If this happens,
5019: 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
5020: <a href="#current-playback-position">current playback position</a> changes in a discontinuous
5021: fashion (so that the relevant events fire).
5022: If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
5023: controller</a>, then the user agent must <a href="#seek-the-media-controller">seek the media
5024: controller</a> appropriately instead.
5025: </p>
5026:
5027: </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
5028: and video tracks. For example, in addition to the primary video and
5029: audio tracks, a <a href="#media-resource">media resource</a> could have
5030: foreign-language dubbed dialogues, director's commentaries, audio
5031: 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>
5032:
5033: <dd>
5034:
5035: <p>Returns a <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
5036: the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
5037:
5038: </dd>
5039:
5040: <dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code></dt>
5041:
5042: <dd>
5043:
5044: <p>Returns an <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object representing
5045: the video tracks available in the <a href="#media-resource">media resource</a>.</p>
5046:
5047: </dd>
5048:
5049: </dl><div class="impl">
5050:
5051: <p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
5052: attribute of a <a href="#media-element">media element</a> must return a
5053: <a href="infrastructure.html#live">live</a> <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
5054: the audio tracks available in the <a href="#media-element">media element</a>'s
5055: <a href="#media-resource">media resource</a>. The same object must be returned each
5056: time.</p>
5057:
5058: <p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
5059: attribute of a <a href="#media-element">media element</a> must return a
5060: <a href="infrastructure.html#live">live</a> <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object
5061: representing the video tracks available in the <a href="#media-element">media
5062: element</a>'s <a href="#media-resource">media resource</a>. The same object must
5063: be returned each time.</p>
5064:
5065: <p class="note">There are only ever two <code><a href="#tracklist">TrackList</a></code>
5066: objects (one <code><a href="#multipletracklist">MultipleTrackList</a></code> object and one
5067: <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object) per <a href="#media-element">media
5068: element</a>, even if another <a href="#media-resource">media resource</a> is
5069: loaded into the element: the objects are reused.</p>
5070:
5071: </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
5072: <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> interfaces, used by the attributes
5073: defined in the previous section, are substantially similar. Their
5074: common features are defined in the <code><a href="#tracklist">TrackList</a></code> interface,
5075: from which they both inherit.</p><pre class="idl">interface <dfn id="tracklist">TrackList</dfn> {
5076: readonly attribute unsigned long <a href="#dom-tracklist-length" title="dom-TrackList-length">length</a>;
5077: DOMString <a href="#dom-tracklist-getid" title="dom-TrackList-getID">getID</a>(in unsigned long index);
5078: DOMString <a href="#dom-tracklist-getkind" title="dom-TrackList-getKind">getKind</a>(in unsigned long index);
5079: DOMString <a href="#dom-tracklist-getlabel" title="dom-TrackList-getLabel">getLabel</a>(in unsigned long index);
5080: DOMString <a href="#dom-tracklist-getlanguage" title="dom-TrackList-getLanguage">getLanguage</a>(in unsigned long index);
5081:
5082: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
5083: };
5084:
5085: interface <dfn id="multipletracklist">MultipleTrackList</dfn> : <a href="#tracklist">TrackList</a> {
5086: boolean <a href="#dom-tracklist-isenabled" title="dom-TrackList-isEnabled">isEnabled</a>(in unsigned long index);
5087: void <a href="#dom-tracklist-enable" title="dom-TrackList-enable">enable</a>(in unsigned long index);
5088: void <a href="#dom-tracklist-disable" title="dom-TrackList-disable">disable</a>(in unsigned long index);
5089: };
5090:
5091: interface <dfn id="exclusivetracklist">ExclusiveTrackList</dfn> : <a href="#tracklist">TrackList</a> {
5092: readonly attribute unsigned long <a href="#dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex">selectedIndex</a>;
5093: void <a href="#dom-tracklist-select" title="dom-TrackList-select">select</a>(in unsigned long index);
5094: };</pre><dl class="domintro"><dt><var title="">tracks</var> . <code title="dom-TrackList-length"><a href="#dom-tracklist-length">length</a></code></dt>
5095:
5096: <dd>
5097:
5098: <p>Returns the number of tracks in the list.</p>
5099:
5100: </dd>
5101:
5102: <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>
5103:
5104: <dd>
5105:
5106: <p>Returns the ID of the given track. This is the ID that can be
5107: used with a fragment identifier if the format supports the
1.61 mike 5108: <cite>Media Fragments URI</cite> syntax. <a href="#hrefMEDIAFRAG">[MEDIAFRAG]</a></p>
1.47 mike 5109:
5110: </dd>
5111:
5112: <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>
5113:
5114: <dd>
5115:
5116: <p>Returns the category the given track falls into. The <a href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p>
5117:
5118: </dd>
5119:
5120: <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>
5121:
5122: <dd>
5123:
5124: <p>Returns the label of the given track, if known, or the empty string otherwise.</p>
5125:
5126: </dd>
5127:
5128: <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>
5129:
5130: <dd>
5131:
5132: <p>Returns the language of the given track, if known, or the empty string otherwise.</p>
5133:
5134: </dd>
5135:
5136: <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>
5137:
5138: <dd>
5139:
5140: <p>Returns true if the given track is active, and false otherwise.</p>
5141:
5142: </dd>
5143:
5144: <dt><var title="">audioTracks</var> . <code title="dom-TrackList-enable"><a href="#dom-tracklist-enable">enable</a></code>( <var title="">index</var> )</dt>
5145:
5146: <dd>
5147:
5148: <p>Enables the given track.</p>
5149:
5150: </dd>
5151:
5152: <dt><var title="">audioTracks</var> . <code title="dom-TrackList-disable"><a href="#dom-tracklist-disable">disable</a></code>( <var title="">index</var> )</dt>
5153:
5154: <dd>
5155:
5156: <p>Disables the given track.</p>
5157:
5158: </dd>
5159:
5160: <dt><var title="">videoTracks</var> . <code title="dom-TrackList-selectedIndex"><a href="#dom-tracklist-selectedindex">isEnabled</a></code></dt>
5161:
5162: <dd>
5163:
5164: <p>Returns the index of the currently selected track, if any, or −1 otherwise.</p>
5165:
5166: </dd>
5167:
5168: <dt><var title="">videoTracks</var> . <code title="dom-TrackList-select"><a href="#dom-tracklist-select">select</a></code>( <var title="">index</var> )</dt>
5169:
5170: <dd>
5171:
5172: <p>Selects the given track.</p>
5173:
5174: </dd>
5175:
5176: </dl><div class="impl">
5177:
5178: <p>The <dfn id="dom-tracklist-length" title="dom-TrackList-length"><code>length</code></dfn>
5179: attribute must return the number of tracks represented by the
5180: <code><a href="#tracklist">TrackList</a></code> object at the time of getting.</p>
5181:
5182: <p>Tracks in a <code><a href="#tracklist">TrackList</a></code> object must be consistently
5183: ordered. If the <a href="#media-resource">media resource</a> is in a format that
5184: defines an order, then that order must be used; otherwise, the order
5185: must be the relative order in which the tracks are declared in the
5186: <a href="#media-resource">media resource</a>. Each track in a <code><a href="#tracklist">TrackList</a></code>
5187: thus has an index; the first has the index 0, and each subsequent
5188: track is numbered one higher than the previous one.</p>
5189:
5190: <p>The <dfn id="dom-tracklist-getid" title="dom-TrackList-getID"><code>getID(<var title="">index</var>)</code></dfn> method must return the identifier
5191: of the track with index <var title="">index</var>, if there is one.
5192: If there is no such track, then the method must instead throw an
5193: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If the <a href="#media-resource">media
5194: resource</a> is in a format that supports the <cite>Media
5195: Fragments URI</cite> fragment identifier syntax, the returned
5196: identifier must be the same identifier that would enable the track
5197: if used as the name of a track in the track dimension of such a
5198: fragment identifier. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
5199:
5200: <p>The <dfn id="dom-tracklist-getkind" title="dom-TrackList-getKind"><code>getKind(<var title="">index</var>)</code></dfn> method must return the category
5201: of the track with index <var title="">index</var>, if there is one.
5202: If there is no such track, then the method must instead throw an
5203: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5204:
5205: <p>The category of a track is the string given in the first column
5206: of the table below that is the most appropriate for the track based
5207: on the definitions in the table's second and third columns, as
5208: determined by the metadata included in the track in the <a href="#media-resource">media
5209: resource</a>. For Ogg files, the Role header of the track gives
5210: the relevant metadata. The cell in the third column of a row says
5211: what the category given in the cell in the first column of that row
5212: applies to; a category is only appropriate for an audio track if it
5213: applies to audio tracks, and a category is only appropriate for
5214: video tracks if it applies to video tracks.</p>
5215:
5216: </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>
5217: <thead><tr><th>Category
5218: </th><th>Definition
5219: </th><th>Applies to...</th>
5220: <th>Examples
5221: </th></tr></thead><tbody><tr><td>"<dfn id="dom-tracklist-getkind-alternate" title="dom-TrackList-getKind-alternate"><code>alternative</code></dfn>"
5222: </td><td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
5223: </td><td>Audio and video.
5224: </td><td>Ogg: "audio/alterate" or "video/alternate".
5225:
5226: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-description" title="dom-TrackList-getKind-description"><code>description</code></dfn>"
5227: </td><td>An audio description of a video track.
5228: </td><td>Audio only.
5229: </td><td>Ogg: "audio/audiodesc".
5230:
5231: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-main" title="dom-TrackList-getKind-main"><code>main</code></dfn>"
5232: </td><td>The primary audio or video track.
5233: </td><td>Audio and video.
5234: </td><td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
5235:
5236: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-sign" title="dom-TrackList-getKind-sign"><code>sign</code></dfn>"
5237: </td><td>A sign-language interpretation of an audio track.
5238: </td><td>Video only.
5239: </td><td>Ogg: "video/sign".
5240:
5241: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-translation" title="dom-TrackList-getKind-translation"><code>translation</code></dfn>"
5242: </td><td>A translated version of the main track.
5243: </td><td>Audio only.
5244: </td><td>Ogg: "audio/dub".
5245:
5246: </td></tr><tr><td>"<dfn id="dom-tracklist-getkind-none" title="dom-TrackList-getKind-none"><code></code></dfn>" (empty string)
5247: </td><td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
5248: </td><td>Audio and video.
5249: </td><td>Any other track type or track role.
5250:
5251: </td></tr></tbody></table><div class="impl">
5252:
5253: <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
5254: the track with index <var title="">index</var>, if there is one and
5255: it has a label. If there is no such track, then the method must
5256: instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is
5257: a track with index <var title="">index</var>, but it has no label,
5258: then the method must return the empty string.</p>
5259:
5260: <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
5261: language tag of the language of the track with index <var title="">index</var>, if there is one and it has a language. If
5262: there is no such track, then the method must instead throw an
5263: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is a track with
5264: index <var title="">index</var>, but it has no language, or the user
5265: agent is not able to express that language as a BCP 47 language tag
5266: (for example because the language information in the <a href="#media-resource">media
5267: resource</a>'s format is a free-form string without a defined
5268: interpretation), then the method must return the empty string.</p>
5269:
5270: <hr><p>A <code><a href="#multipletracklist">MultipleTrackList</a></code> object represents a track list
5271: where multiple tracks can be enabled simultaneously. Each track is
5272: either enabled or disabled.</p>
5273:
5274: <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
5275: is a track with index <var title="">index</var>, and it is currently
5276: enabled, false if there is a track with index <var title="">index</var>, but it is currently disabled, and must throw
5277: an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception if there is no track with
5278: index <var title="">index</var>.</p>
5279:
5280: <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
5281: index <var title="">index</var>, if there is one. If there is not,
5282: it must instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5283:
5284: <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
5285: index <var title="">index</var>, if there is one. If there is not,
5286: it must instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5287:
5288: <p>Whenever a track is enabled or disabled, the user agent must
5289: <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
5290: <code title="event-media-change">change</code> at the
5291: <code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
5292:
5293: <hr><p>An <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object represents a track list
5294: where exactly one track is selected at a time.</p>
5295:
5296: <p>The <dfn id="dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex"><code>selectedIndex</code></dfn>
5297: attribute must return the index of the currently selected track. If
5298: the <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object does not represent any
5299: tracks, it must instead return −1.</p>
5300:
5301: <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
5302: <var title="">index</var>, if there is one, unselecting whichever
5303: track was previously selected. If there is no track with index <var title="">index</var>, it must instead throw an
5304: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
5305:
5306: <p>Whenever the selected track is changed, the user agent must
5307: <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
5308: <code title="event-media-change">change</code> at the
5309: <code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
5310:
5311: <hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
5312: corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
5313: event types</a>) that must be supported, as IDL attributes, by
5314: all objects implementing the <code><a href="#tracklist">TrackList</a></code>
5315: interface:</p>
5316:
5317: <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>
5318: </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>
5319: </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
5320: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5321:
5322:
5323:
5324: </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
5325: <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attributes
5326: allow scripts to select which track should play, but it is also
5327: possible to select specific tracks declaratively, by specifying
5328: particular tracks in the fragment identifier of the <a href="urls.html#url">URL</a>
5329: of the <a href="#media-resource">media resource</a>. The format of the fragment
5330: identifier depends on the <a href="infrastructure.html#mime-type">MIME type</a> of the <a href="#media-resource">media
5331: resource</a>. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3986">[RFC3986]</a></p><div class="example">
5332:
5333: <p>In this example, a video that uses a format that supports the
5334: <cite>Media Fragments URI</cite> fragment identifier syntax is
5335: embedded in such a way that the alternative angles labeled
5336: "Alternative" are enabled instead of the default video track. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
5337:
5338: <pre><video src="myvideo#track=Alternative"></video></pre>
5339:
5340:
5341: </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
5342: <code><a href="#mediacontroller">MediaController</a></code>. A <code><a href="#mediacontroller">MediaController</a></code> is an
5343: object that coordinates the playback of multiple <a href="#media-element" title="media
5344: element">media elements</a>, for instance so that a sign-language
5345: interpreter track can be overlaid on a video track, with the two
5346: being kept in sync.</p><p>By default, a <a href="#media-element">media element</a> has no
5347: <code><a href="#mediacontroller">MediaController</a></code>. An implicit
5348: <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.
5349: An explicit <code><a href="#mediacontroller">MediaController</a></code> can be assigned directly
5350: using the <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> IDL
5351: attribute.</p><p><a href="#media-element" title="media element">Media elements</a> with a
5352: <code><a href="#mediacontroller">MediaController</a></code> are said to be <i>slaved</i> to their
5353: controller. The <code><a href="#mediacontroller">MediaController</a></code> modifies the playback
5354: rate and the playback volume of each of the <a href="#media-element" title="media
5355: element">media elements</a> slaved to it, and ensures that when
5356: any of its slaved <a href="#media-element" title="media element">media elements</a>
5357: 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
5358: <code><a href="#mediacontroller">MediaController</a></code>, its playback rate is fixed to that of
5359: the other tracks in the same <code><a href="#mediacontroller">MediaController</a></code>, and any
5360: 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>]
5361: interface <dfn id="mediacontroller">MediaController</dfn> {
5362: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-buffered" title="dom-MediaController-buffered">buffered</a>;
5363: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-seekable" title="dom-MediaController-seekable">seekable</a>;
5364: readonly attribute double <a href="#dom-mediacontroller-duration" title="dom-MediaController-duration">duration</a>;
5365: attribute double <a href="#dom-mediacontroller-currenttime" title="dom-MediaController-currentTime">currentTime</a>;
5366:
5367: readonly attribute boolean <a href="#dom-mediacontroller-paused" title="dom-MediaController-paused">paused</a>;
5368: readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-played" title="dom-MediaController-played">played</a>;
5369: void <a href="#dom-mediacontroller-play" title="dom-MediaController-play">play</a>();
5370: void <a href="#dom-mediacontroller-pause" title="dom-MediaController-pause">pause</a>();
5371:
5372: attribute double <a href="#dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate">defaultPlaybackRate</a>;
5373: attribute double <a href="#dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate">playbackRate</a>;
5374:
5375: attribute double <a href="#dom-mediacontroller-volume" title="dom-MediaController-volume">volume</a>;
5376: attribute boolean <a href="#dom-mediacontroller-muted" title="dom-MediaController-muted">muted</a>;
5377:
5378: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onemptied" title="handler-MediaController-onemptied">onemptied</a>;
5379: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata">onloadedmetadata</a>;
5380: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata">onloadeddata</a>;
5381: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay">oncanplay</a>;
5382: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough">oncanplaythrough</a>;
5383: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onplaying" title="handler-MediaController-onplaying">onplaying</a>;
5384: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting">onwaiting</a>;
5385:
5386: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange">ondurationchange</a>;
5387: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate">ontimeupdate</a>;
5388: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onplay" title="handler-MediaController-onplay">onplay</a>;
5389: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onpause" title="handler-MediaController-onpause">onpause</a>;
5390: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onratechange" title="handler-MediaController-onratechange">onratechange</a>;
5391: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange">onvolumechange</a>;
5392: };</pre><dl class="domintro"><dt><var title="">controller</var> = new <code title="dom-MediaController"><a href="#dom-mediacontroller">MediaController</a></code>()</dt>
5393:
5394: <dd>
5395:
5396: <p>Returns a new <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5397:
5398: </dd>
5399:
5400: <dt><var title="">media</var> . <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> [ = <var title="">controller</var> ]</dt>
5401:
5402: <dd>
5403:
5404: <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>
5405:
5406: <p>Can be set, to set an explicit <code><a href="#mediacontroller">MediaController</a></code>.
5407: Doing so removes the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if
5408: any.</p>
5409:
5410: </dd>
5411:
5412: <dt><var title="">controller</var> . <code title="dom-MediaController-buffered"><a href="#dom-mediacontroller-buffered">buffered</a></code></dt>
5413:
5414: <dd>
5415:
5416: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5417: intersection of the time ranges for which the user agent has all
5418: relevant media data for all the slaved <a href="#media-element" title="media
5419: element">media elements</a>.</p>
5420:
5421: </dd>
5422:
5423: <dt><var title="">controller</var> . <code title="dom-MediaController-seekable"><a href="#dom-mediacontroller-seekable">seekable</a></code></dt>
5424:
5425: <dd>
5426:
5427: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5428: intersection of the time ranges into which the user agent can seek
5429: for all the slaved <a href="#media-element" title="media element">media
5430: elements</a>.</p>
5431:
5432: </dd>
5433:
5434: <dt><var title="">controller</var> . <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code></dt>
5435:
5436: <dd>
5437:
5438: <p>Returns the difference between the earliest playable moment and
5439: the latest playable moment (not considering whether the data in
5440: question is actually buffered or directly seekable, but not
5441: including time in the future for infinite streams). Will return
5442: zero if there is no media.</p>
5443:
5444: </dd>
5445:
5446: <dt><var title="">controller</var> . <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
5447:
5448: <dd>
5449:
5450: <p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds,
5451: as a position between zero time and the current <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code>.</p>
5452:
5453: <p>Can be set, to seek to the given time.</p><p>
5454:
5455: </p></dd>
5456:
5457: <dt><var title="">controller</var> . <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code></dt>
5458:
5459: <dd>
5460:
5461: <p>Returns true if playback is paused; false otherwise. When this
5462: attribute is true, any <a href="#media-element">media element</a> slaved to this
5463: controller will be stopped.</p>
5464:
5465: </dd>
5466:
5467: <dt><var title="">controller</var> . <code title="dom-MediaController-played"><a href="#dom-mediacontroller-played">played</a></code></dt>
5468:
5469: <dd>
5470:
5471: <p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
5472: union of the time ranges in all the slaved <a href="#media-element" title="media
5473: element">media elements</a> that have been played.</p>
5474:
5475: </dd>
5476:
5477: <dt><var title="">controller</var> . <code title="dom-MediaController-play"><a href="#dom-mediacontroller-play">play</a></code>()</dt>
5478:
5479: <dd>
5480:
5481: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5482: attribute to false.</p>
5483:
5484: </dd>
5485:
5486: <dt><var title="">controller</var> . <code title="dom-MediaController-pause"><a href="#dom-mediacontroller-pause">pause</a></code>()</dt>
5487:
5488: <dd>
5489:
5490: <p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
5491: attribute to true.</p>
5492:
5493: </dd>
5494:
5495: <dt><var title="">controller</var> . <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
5496:
5497: <dd>
5498:
5499: <p>Returns the default rate of playback.</p>
5500:
5501: <p>Can be set, to change the default rate of playback.</p>
5502:
5503: <p>This default rate has no direct effect on playback, but if the
5504: user switches to a fast-forward mode, when they return to the
5505: normal playback mode, it is expected that rate of playback (<code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code>) will
5506: be returned to this default rate.</p>
5507:
5508: </dd>
5509:
5510: <dt><var title="">controller</var> . <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
5511:
5512: <dd>
5513:
5514: <p>Returns the current rate of playback.</p>
5515:
5516: <p>Can be set, to change the rate of playback.</p>
5517:
5518: </dd>
5519:
5520: <dt><var title="">controller</var> . <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
5521:
5522: <dd>
5523:
5524: <p>Returns the current playback volume multiplier, as a number in
5525: the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the
5526: loudest.</p>
5527:
5528: <p>Can be set, to change the volume multiplier.</p>
5529:
5530: <p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
5531: in the range 0.0 .. 1.0.</p>
5532:
5533: </dd>
5534:
5535: <dt><var title="">controller</var> . <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
5536:
5537: <dd>
5538:
5539: <p>Returns true if all audio is muted (regardless of other
5540: attributes either on the controller or on any <a href="#media-element" title="media
5541: element">media elements</a> slaved to this controller), and
5542: false otherwise.</p>
5543:
5544: <p>Can be set, to change whether the audio is muted or not.</p>
5545:
5546: </dd>
5547:
5548: </dl><div class="impl">
5549:
5550: <p>A <a href="#media-element">media element</a> can have a <dfn id="current-media-controller">current media
5551: controller</dfn>, which is a <code><a href="#mediacontroller">MediaController</a></code> object.
5552: 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
5553: not have a <a href="#current-media-controller">current media controller</a>. (If it is created
5554: <em>with</em> such an attribute, then that attribute initializes the
5555: <a href="#current-media-controller">current media controller</a>, as defined below.)</p>
5556:
5557: <p>The <dfn id="slaved-media-elements">slaved media elements</dfn> of a
5558: <code><a href="#mediacontroller">MediaController</a></code> are the <a href="#media-element" title="media
5559: element">media elements</a> whose <a href="#current-media-controller">current media
5560: controller</a> is that <code><a href="#mediacontroller">MediaController</a></code>. All the
5561: <a href="#slaved-media-elements">slaved media elements</a> of a <code><a href="#mediacontroller">MediaController</a></code>
5562: must use the same clock for their definition of their <a href="#media-timeline">media
5563: timeline</a>'s unit time.</p>
5564:
5565: <hr><p>The <dfn id="dom-media-controller" title="dom-media-controller"><code>controller</code></dfn> attribute
5566: on a <a href="#media-element">media element</a>, on getting, must return the
5567: element's <a href="#current-media-controller">current media controller</a>, if any, or null
5568: 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,
5569: and then set the <a href="#current-media-controller">current media controller</a> to the given
5570: value. If the given value is null, the element no longer has a
5571: <a href="#current-media-controller">current media controller</a>; if it is not null, then the
5572: 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
5573: new media controller</a>.</p>
5574:
5575: <hr><p>The <dfn id="dom-mediacontroller" title="dom-MediaController"><code>MediaController()</code></dfn>
5576: constructor, when invoked, must return a newly created
5577: <code><a href="#mediacontroller">MediaController</a></code> object.</p>
5578:
5579: <hr><p>The <dfn id="dom-mediacontroller-seekable" title="dom-MediaController-seekable"><code>seekable</code></dfn>
5580: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5581: <code>TimeRanges</code> object</a> that represents the
5582: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5583: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5584: user agent is able to seek to, at the time the attribute is
5585: evaluated.</p>
5586:
5587: <p>The <dfn id="dom-mediacontroller-buffered" title="dom-MediaController-buffered"><code>buffered</code></dfn>
5588: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5589: <code>TimeRanges</code> object</a> that represents the
5590: intersection of the ranges of the <a href="#media-resource" title="media resource">media
5591: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5592: user agent has buffered, at the time the attribute is evaluated.
5593: Users agents must accurately determine the ranges available, even
5594: for media streams where this can only be determined by tedious
5595: inspection.</p>
5596:
5597: <p>The <dfn id="dom-mediacontroller-duration" title="dom-MediaController-duration"><code>duration</code></dfn>
5598: attribute must return the <a href="#media-controller-duration">media controller
5599: duration</a>.</p>
5600:
5601: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5602: <a href="#media-controller-duration">media controller duration</a> changes, whichever happens
5603: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5604: <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>
5605: at the <code><a href="#mediacontroller">MediaController</a></code>. If the
5606: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-duration">media controller
5607: duration</a> decreases such that the <a href="#media-controller-position">media controller
5608: position</a> is greater than the <a href="#media-controller-duration">media controller
5609: duration</a>, the user agent must immediately <a href="#seek-the-media-controller">seek the
5610: media controller</a> to <a href="#media-controller-duration">media controller
5611: duration</a>.</p>
5612:
5613: <p>The <dfn id="dom-mediacontroller-currenttime" title="dom-MediaController-currentTime"><code>currentTime</code></dfn>
5614: attribute must return the <a href="#media-controller-position">media controller position</a> on
5615: getting, and on setting must <a href="#seek-the-media-controller">seek the media controller</a>
5616: to the new value.</p>
5617:
5618: <p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
5619: <a href="#media-controller-position">media controller position</a> changes, whichever happens
5620: least often, the user agent must <a href="webappapis.html#queue-a-task">queue a task</a> to
5621: <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
5622: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5623:
5624: <hr><p>When a <code><a href="#mediacontroller">MediaController</a></code> is created it is a
5625: <dfn id="playing-media-controller">playing media controller</dfn>. It can be changed into a
5626: <dfn id="paused-media-controller">paused media controller</dfn> and back either via the user
5627: agent's user interface (when the element is <a href="#expose-a-user-interface-to-the-user" title="expose a
5628: user interface to the user">exposing a user interface to the
5629: user</a>) or by script using the APIs defined in this section
5630: (see below).</p>
5631:
5632: <p>The <dfn id="dom-mediacontroller-paused" title="dom-MediaController-paused"><code>paused</code></dfn>
5633: attribute must return true if the <code><a href="#mediacontroller">MediaController</a></code>
5634: object is a <a href="#paused-media-controller">paused media controller</a>, and false
5635: otherwise.</p>
5636:
5637: <p>The <dfn id="dom-mediacontroller-played" title="dom-MediaController-played"><code>played</code></dfn>
5638: attribute must return a new static <a href="#normalized-timeranges-object">normalized
5639: <code>TimeRanges</code> object</a> that represents the union of
5640: the ranges of the <a href="#media-resource" title="media resource">media
5641: resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
5642: user agent has so far rendered, at the time the attribute is
5643: evaluated.</p>
5644:
5645: <p>When the <dfn id="dom-mediacontroller-pause" title="dom-MediaController-pause"><code>pause()</code></dfn> method
5646: is invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#playing-media-controller">playing
5647: media controller</a> then the user agent must change the
5648: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#paused-media-controller">paused media
5649: 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
5650: event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
5651: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
5652: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5653:
5654: <p>When the <dfn id="dom-mediacontroller-play" title="dom-MediaController-play"><code>play()</code></dfn> method is
5655: invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#paused-media-controller">paused media
5656: controller</a>, the user agent must change the
5657: <code><a href="#mediacontroller">MediaController</a></code> into a <a href="#playing-media-controller">playing media
5658: 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
5659: event</a> named <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code> at the
5660: <code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
5661: state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5662:
5663: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-default-playback-rate">media controller
5664: default playback rate</dfn> and a <dfn id="media-controller-playback-rate">media controller playback
5665: rate</dfn>, which must both be set to 1.0 when the
5666: <code><a href="#mediacontroller">MediaController</a></code> object is created.</p>
5667:
5668: <p>The <dfn id="dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
5669: attribute, on getting, must return the
5670: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
5671: playback rate</a>, and on setting, must set the
5672: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
5673: playback rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a
5674: 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
5675: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5676:
5677: <p>The <dfn id="dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate"><code>playbackRate</code></dfn>
5678: attribute, on getting, must return the
5679: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
5680: rate</a>, and on setting, must set the
5681: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
5682: rate</a> to the new value, then <a href="webappapis.html#queue-a-task">queue a task</a> to
5683: <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
5684: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5685:
5686: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-volume-multiplier">media controller volume
5687: multiplier</dfn>, which must be set to 1.0 when the
5688: <code><a href="#mediacontroller">MediaController</a></code> object is created, and a <dfn id="media-controller-mute-override">media
5689: controller mute override</dfn>, much must initially be false.</p>
5690:
5691: <p>The <dfn id="dom-mediacontroller-volume" title="dom-MediaController-volume"><code>volume</code></dfn>
5692: attribute, on getting, must return the
5693: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-volume-multiplier">media controller volume
5694: multiplier</a>, and on setting, if the new value is in the range
5695: 0.0 to 1.0 inclusive, must set the <code><a href="#mediacontroller">MediaController</a></code>'s
5696: <a href="#media-controller-volume-multiplier">media controller volume multiplier</a> to the new value and
5697: <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
5698: <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
5699: at the <code><a href="#mediacontroller">MediaController</a></code>. If the new value is outside the
5700: range 0.0 to 1.0 inclusive, then, on setting, an
5701: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
5702:
5703: <p>The <dfn id="dom-mediacontroller-muted" title="dom-MediaController-muted"><code>muted</code></dfn>
5704: attribute, on getting, must return the
5705: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
5706: override</a>, and on setting, must set the
5707: <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
5708: override</a> to the new value and <a href="webappapis.html#queue-a-task">queue a task</a> to
5709: <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
5710: the <code><a href="#mediacontroller">MediaController</a></code>.</p>
5711:
5712: <hr><p>The <a href="#media-resource" title="media resource">media resources</a> of all
5713: the <a href="#slaved-media-elements">slaved media elements</a> of a
5714: <code><a href="#mediacontroller">MediaController</a></code> have a defined temporal relationship
5715: which provides relative offsets between the zero time of each such
5716: <a href="#media-resource">media resource</a>: for <a href="#media-resource" title="media resource">media
5717: resources</a> with a <a href="#timeline-offset">timeline offset</a>, their relative
5718: offsets are the difference between their <a href="#timeline-offset">timeline
5719: offset</a>; the zero times of all the <a href="#media-resource" title="media
5720: resource">media resources</a> without a <a href="#timeline-offset">timeline
5721: offset</a> are not offset from each other (i.e. the origins of
5722: their timelines are cotemporal); and finally, the zero time of the
5723: <a href="#media-resource">media resource</a> with the earliest <a href="#timeline-offset">timeline
5724: offset</a> (if any) is not offset from the zero times of the
5725: <a href="#media-resource" title="media resource">media resources</a> without a
5726: <a href="#timeline-offset">timeline offset</a> (i.e. the origins of <a href="#media-resource" title="media
5727: resource">media resources</a> without a <a href="#timeline-offset">timeline
5728: offset</a> are further cotemporal with the earliest defined point
5729: on the timeline of the <a href="#media-resource">media resource</a> with the earliest
5730: <a href="#timeline-offset">timeline offset</a>).</p>
5731:
5732: <p>The <dfn id="media-resource-end-position">media resource end position</dfn> of a <a href="#media-resource">media
5733: resource</a> in a <a href="#media-element">media element</a> is defined as
5734: follows: if the <a href="#media-resource">media resource</a> has a finite and known
5735: duration, the <a href="#media-resource-end-position">media resource end position</a> is the
5736: duration of the <a href="#media-resource">media resource</a>'s timeline (the last
5737: defined position on that timeline); otherwise, the <a href="#media-resource">media
5738: resource</a>'s duration is infinite or unknown, and the
5739: <a href="#media-resource-end-position">media resource end position</a> is the time of the last
5740: frame of <a href="#media-data">media data</a> currently available for that
5741: <a href="#media-resource">media resource</a>.</p>
5742:
5743: <p>Each <code><a href="#mediacontroller">MediaController</a></code> also has its own defined
5744: timeline. On this timeline, all the <a href="#media-resource" title="media
5745: resource">media resources</a> of all the <a href="#slaved-media-elements">slaved media
5746: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code> are temporally
5747: aligned according to their defined offsets. The <dfn id="media-controller-duration">media
5748: controller duration</dfn> of that <code><a href="#mediacontroller">MediaController</a></code> is
5749: the time from the earliest <a href="#earliest-possible-position">earliest possible position</a>,
5750: relative to this <code><a href="#mediacontroller">MediaController</a></code> timeline, of any of
5751: the <a href="#media-resource" title="media resource">media resources</a> of the
5752: <a href="#slaved-media-elements">slaved media elements</a> of the
5753: <code><a href="#mediacontroller">MediaController</a></code>, to the time of the latest <a href="#media-resource-end-position">media
5754: resource end position</a> of the <a href="#media-resource" title="media
5755: resource">media resources</a> of the <a href="#slaved-media-elements">slaved media
5756: elements</a> of the <code><a href="#mediacontroller">MediaController</a></code>, again relative
5757: to this <code><a href="#mediacontroller">MediaController</a></code> timeline.</p>
5758:
5759: <p>Each <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-position">media controller
5760: position</dfn>. This is the time on the
5761: <code><a href="#mediacontroller">MediaController</a></code>'s timeline at which the user agent is
5762: trying to play the <a href="#slaved-media-elements">slaved media elements</a>. When a
5763: <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#media-controller-position">media controller
5764: position</a> is initially zero.</p>
5765:
5766: <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
5767: to speed with its new media controller">bring a media element up to
5768: 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>
5769: to the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-position">media controller
5770: position</a> relative to the <a href="#media-element">media element</a>'s
5771: timeline, discarding any resulting exceptions.</p>
5772:
5773: <p>When the user agent is to <dfn id="seek-the-media-controller">seek the media controller</dfn> to
5774: a particular <var title="">new playback position</var>, it must
5775: follow these steps:</p>
5776:
5777: <ol><li><p>If the <var title="">new playback position</var> is less
5778: than zero, then set it to zero.</p></li>
5779:
5780: <li><p>If the <var title="">new playback position</var> is greater
5781: than the <a href="#media-controller-duration">media controller duration</a>, then set it to the
5782: <a href="#media-controller-duration">media controller duration</a>.</p></li>
5783:
5784: <li><p>Set the <a href="#media-controller-position">media controller position</a> to the <var title="">new playback position</var>.</p></li>
5785:
5786: <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
5787: <var title="">new playback position</var> relative to the
5788: <a href="#media-element">media element</a> timeline, discarding any resulting
5789: exceptions.</p></li>
5790: </ol><p>A <code><a href="#mediacontroller">MediaController</a></code> is a <dfn id="blocked-media-controller">blocked media
5791: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
5792: <a href="#paused-media-controller">paused media controller</a>, or if any of its <a href="#slaved-media-elements">slaved
5793: media elements</a> are <a href="#blocked-media-element" title="blocked media
5794: element">blocked media elements</a>, or if any of its
5795: <a href="#slaved-media-elements">slaved media elements</a> whose <a href="#autoplaying-flag">autoplaying
5796: 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
5797: 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>
5798:
5799: <p>A <a href="#media-element">media element</a> is <dfn id="blocked-on-its-media-controller">blocked on its media
5800: controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
5801: <a href="#blocked-media-controller">blocked media controller</a>, or if its <a href="#media-controller-position">media
5802: controller position</a> is either before the <a href="#media-resource">media
5803: resource</a>'s <a href="#earliest-possible-position">earliest possible position</a> relative
5804: to the <code><a href="#mediacontroller">MediaController</a></code>'s timeline or after the end of
5805: the <a href="#media-resource">media resource</a> relative to the
5806: <code><a href="#mediacontroller">MediaController</a></code>'s timeline.</p>
5807:
5808: <p id="controller-playback">When a <code><a href="#mediacontroller">MediaController</a></code> is
5809: not a <a href="#blocked-media-controller">blocked media controller</a> and it has at least one
5810: <a href="#slaved-media-elements" title="slaved media elements">slaved media element</a>
5811: whose <code><a href="infrastructure.html#document">Document</a></code> is a <a href="browsers.html#fully-active">fully active</a>
5812: <code><a href="infrastructure.html#document">Document</a></code>, the <code><a href="#mediacontroller">MediaController</a></code>'s
5813: <a href="#media-controller-position">media controller position</a> must increase monotonically
5814: at <a href="#media-controller-playback-rate">media controller playback rate</a> units of time on the
5815: <code><a href="#mediacontroller">MediaController</a></code>'s timeline per unit time of the clock
5816: used by its <a href="#slaved-media-elements">slaved media elements</a>.</p>
5817:
5818: <p>When the zero point on the timeline of a
5819: <code><a href="#mediacontroller">MediaController</a></code> moves relative to the timelines of the
5820: <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
5821: <a href="#media-controller-position">media controller position</a> must be decremented by <var title="">ΔT</var>.</p>
5822:
5823: <p class="note">In some situations, e.g. when playing back a live
5824: stream without buffering anything, the <a href="#media-controller-position">media controller
5825: position</a> would increase motonically as described above at the
5826: same rate as the <var title="">ΔT</var> described in the
5827: previous paragraph decreases it, with the end result that for all
5828: intents and purposes, the <a href="#media-controller-position">media controller position</a>
5829: would appear to remain constant (probably with the value 0).</p>
5830:
5831: <hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="most-recently-reported-readiness-state">most recently reported
5832: readiness state</dfn>, which is a number from 0 to 4 derived from
5833: the numbers used for the <a href="#media-element">media element</a> <code title="attr-media-readyState">readyState</code> attribute, and a
5834: <dfn id="most-recently-reported-playback-state">most recently reported playback state</dfn>, which is either
5835: <i>playing</i>, <i>waiting</i>, or <i>ended</i>.</p>
5836:
5837: <p>When a <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#most-recently-reported-readiness-state">most
5838: recently reported readiness state</a> must be set to 0, and its
5839: <a href="#most-recently-reported-playback-state">most recently reported playback state</a> must be set to
5840: <i>waiting</i>.</p>
5841:
5842: <p>When a user agent is required to <dfn id="report-the-controller-state">report the controller
5843: state</dfn> for a <code><a href="#mediacontroller">MediaController</a></code>, the user agent must
5844: run the following steps:</p>
5845:
5846: <ol><li>
5847:
5848: <p>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved media
5849: elements</a>, let <var title="">new readiness state</var> be
5850: 0.</p>
5851:
5852: <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
5853: all of its <a href="#slaved-media-elements">slaved media elements</a>.</p>
5854:
5855: </li>
5856:
5857: <li>
5858:
5859: <p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
5860: reported readiness state</a> is not equal to <var title="">new
5861: 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
5862: a simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
5863: whose name is the event name corresponding to the value of <var title="">new readiness state</var> given in the table below:</p>
5864:
5865:
5866: <table><thead><tr><th>Value of <var title="">new readiness state</var>
5867: </th><th>Event name
5868:
5869: </th></tr></thead><tbody><tr><td> 0
5870: </td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
5871:
5872: </td></tr><tr><td> 1
5873: </td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
5874:
5875: </td></tr><tr><td> 2
5876: </td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
5877:
5878: </td></tr><tr><td> 3
5879: </td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
5880:
5881: </td></tr><tr><td> 4
5882: </td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
5883:
5884: </td></tr></tbody></table></li>
5885:
5886: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
5887: reported readiness state</a> be <var title="">new readiness
5888: state</var>.</p></li>
5889:
5890: <li>
5891:
5892: <p>Initialize <var title="">new playback state</var> by setting it
5893: to the state given for the first matching condition from the
5894: following list:</p>
5895:
5896: <dl class="switch"><dt>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved
5897: media elements</a></dt>
5898:
5899: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
5900:
5901: <dt>If all of the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#slaved-media-elements">slaved
5902: media elements</a> have <a href="#ended-playback">ended playback</a> and the
5903: <a href="#media-controller-playback-rate">media controller playback rate</a> is positive or
5904: zero</dt>
5905:
5906: <dd>Let <var title="">new playback state</var> be <i>ended</i>.</dd>
5907:
5908: <dt>If the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#blocked-media-controller">blocked media
5909: controller</a></dt>
5910:
5911: <dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
5912:
5913: <dt>Otherwise</dt>
5914:
5915: <dd>Let <var title="">new playback state</var> be <i>playing</i>.</dd>
5916:
5917: </dl></li>
5918:
5919: <li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
5920: reported playback state</a> is not equal to <var title="">new
5921: 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
5922: simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
5923: 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>
5924: otherwise.</p></li>
5925:
5926: <li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
5927: reported playback state</a> be <var title="">new playback
5928: state</var>.</p></li>
5929:
5930: </ol><hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
5931: supported, as IDL attributes, by all objects implementing the
5932: <code><a href="#mediacontroller">MediaController</a></code> interface:</p>
5933:
5934: <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>
5935: </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>
5936: </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>
5937: </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>
5938: </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>
5939: </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>
5940: </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>
5941: </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>
5942: </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>
5943: </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>
5944: </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>
5945: </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>
5946: </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>
5947: </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>
5948: </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
5949: <a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
5950:
5951: </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
5952: attribute on <a href="#media-element" title="media element">media elements</a> can
5953: be used to link multiple <a href="#media-element" title="media element">media
5954: elements</a> together by implicitly creating a
5955: <code><a href="#mediacontroller">MediaController</a></code>.</p><div class="impl">
5956:
5957: <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
5958: 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,
5959: changed, or removed, the user agent must run the following
5960: steps:</p>
5961:
5962: <ol><li><p>Let <var title="">m</var> be the <a href="#media-element">media element</a>
5963: in question.</p></li>
5964:
5965: <li><p>Let <var title="">m</var> have no <a href="#current-media-controller">current
5966: media controller</a>, if it currently has one.</p></li>
5967:
5968: <li><p>If <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is being
5969: removed, then abort these steps.</p></li>
5970:
5971: <li>
5972:
5973: <p>If there is another <a href="#media-element">media element</a> whose
5974: <code><a href="infrastructure.html#document">Document</a></code> is the same as <var title="">m</var>'s
5975: <code><a href="infrastructure.html#document">Document</a></code> (even if one or both of these elements are
5976: not actually <a href="infrastructure.html#in-a-document" title="in a Document"><em>in</em> the
5977: <code>Document</code></a>), and which also has a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and
5978: whose <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>
5979: 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
5980: let <var title="">controller</var> be that <a href="#media-element">media
5981: element</a>'s <a href="#current-media-controller">current media controller</a>.</p>
5982:
5983: <p>Otherwise, let <var title="">controller</var> be a newly created
5984: <code><a href="#mediacontroller">MediaController</a></code>.</p>
5985:
5986: </li>
5987:
5988: <li><p>Let <var title="">m</var>'s <a href="#current-media-controller">current media
5989: controller</a> be <var title="">controller</var>.</p></li>
5990:
5991: <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
5992: controller</a>.</p></li>
5993:
5994: </ol><p>The <dfn id="dom-media-mediagroup" title="dom-media-mediaGroup"><code>mediaGroup</code></dfn> IDL
5995: attribute on <a href="#media-element" title="media element">media elements</a> must
5996: <a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content
5997: attribute.</p>
5998:
5999: </div><div class="example">
6000:
6001: <p>Multiple <a href="#media-element" title="media element">media elements</a>
6002: referencing the same <a href="#media-resource">media resource</a> will share a
6003: single network request. This can be used to efficiently play two
6004: (video) tracks from the same <a href="#media-resource">media resource</a> in two
6005: different places on the screen. Used with the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, these
6006: elements can also be kept synchronised.</p>
6007:
6008: <p>In this example, a sign-languge interpreter track from a movie
6009: file is overlaid on the primary video track of that same video file
6010: using two <code><a href="#the-video-element">video</a></code> elements, some CSS, and an implicit
6011: <code><a href="#mediacontroller">MediaController</a></code>:</p>
6012:
6013: <pre><article>
6014: <style scoped>
6015: div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
6016: video { position; absolute; bottom: 0; right: 0; }
6017: video:first-child { width: 100%; height: 100%; }
6018: video:last-child { width: 30%; }
6019: </style>
6020: <div>
6021: <video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
6022: <video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
6023: </div>
6024: </article></pre>
6025:
6026: </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
6027: 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
6028: to <code><a href="#the-track-element">track</a></code> element children of the <a href="#media-element">media
6029: element</a>, in <a href="infrastructure.html#tree-order">tree order</a>.</li>
6030:
6031: <li>Any <a href="#text-track" title="text track">text tracks</a> added using
6032: the <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack()</a></code> method, in
6033: the order they were added, oldest first.</li>
6034:
6035: <li>Any <a href="#media-resource-specific-text-track" title="media-resource-specific text
6036: track">media-resource-specific text tracks</a> (<a href="#text-track" title="text track">text tracks</a> corresponding to data in
6037: the <a href="#media-resource">media resource</a>), in the order defined by the
6038: <a href="#media-resource">media resource</a>'s format specification.</li>
6039:
6040: </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>
6041:
6042: </dt><dd>
6043:
6044: <p>This decides how the track is handled by the user agent. The
6045: kind is represented by a string. The possible strings are:</p>
6046:
6047: <ul class="brief"><li><dfn id="dom-texttrack-kind-subtitles" title="dom-TextTrack-kind-subtitles"><code>subtitles</code></dfn>
6048: </li><li><dfn id="dom-texttrack-kind-captions" title="dom-TextTrack-kind-captions"><code>captions</code></dfn>
6049: </li><li><dfn id="dom-texttrack-kind-descriptions" title="dom-TextTrack-kind-descriptions"><code>descriptions</code></dfn>
6050: </li><li><dfn id="dom-texttrack-kind-chapters" title="dom-TextTrack-kind-chapters"><code>chapters</code></dfn>
6051: </li><li><dfn id="dom-texttrack-kind-metadata" title="dom-TextTrack-kind-metadata"><code>metadata</code></dfn>
6052: </li></ul><p>The <a href="#text-track-kind" title="text track kind">kind of track</a> can
6053: change dynamically, in the case of a <a href="#text-track">text track</a>
6054: corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6055:
6056: </dd>
6057:
6058: <dt><dfn id="text-track-label" title="text track label">A label</dfn>
6059:
6060: </dt><dd>
6061:
6062: <p>This is a human-readable string intended to identify the track
6063: for the user. In certain cases, the label might be generated
6064: automatically.</p>
6065:
6066: <p>The <a href="#text-track-label" title="text track label">label of a track</a> can
6067: change dynamically, in the case of a <a href="#text-track">text track</a>
6068: corresponding to a <code><a href="#the-track-element">track</a></code> element or in the case of an
6069: automatically-generated label whose value depends on variable
6070: factors such as the user's preferred user interface language.</p>
6071:
6072: </dd>
6073:
6074: <dt><dfn id="text-track-language" title="text track language">A language</dfn>
6075:
6076: </dt><dd>
6077:
6078: <p>This is a string (a BCP 47 language tag) representing the
6079: language of the text track's cues. <a href="references.html#refsBCP47">[BCP47]</a></p>
6080:
6081: <p>The <a href="#text-track-language" title="text track language">language of a text
6082: track</a> can change dynamically, in the case of a <a href="#text-track">text
6083: track</a> corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
6084:
6085: </dd>
6086:
6087: <dt><dfn id="text-track-readiness-state" title="text track readiness state">A readiness state</dfn>
6088:
6089: </dt><dd>
6090:
6091: <p>One of the following:</p>
6092:
6093: <dl><dt><dfn id="text-track-not-loaded" title="text track not loaded">Not loaded</dfn>
6094:
6095: </dt><dd>
6096:
6097: <p>Indicates that the text track is known to exist (e.g. it has
6098: been declared with a <code><a href="#the-track-element">track</a></code> element), but its cues
6099: have not been obtained.</p>
6100:
6101: </dd>
6102:
6103: <dt><dfn id="text-track-loading" title="text track loading">Loading</dfn>
6104:
6105: </dt><dd>
6106:
6107: <p>Indicates that the text track is loading and there have been
6108: no fatal errors encountered so far. Further cues might still be
6109: added to the track.</p>
6110:
6111: </dd>
6112:
6113: <dt><dfn id="text-track-loaded" title="text track loaded">Loaded</dfn>
6114:
6115: </dt><dd>
6116:
6117: <p>Indicates that the text track has been loaded with no fatal
6118: errors. No new cues will be added to the track except if the
6119: <a href="#text-track">text track</a> corresponds to a
6120: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object.</p>
6121:
6122: </dd>
6123:
6124: <dt><dfn id="text-track-failed-to-load" title="text track failed to load">Failed to load</dfn>
6125:
6126: </dt><dd>
6127:
6128: <p>Indicates that the text track was enabled, but when the user
6129: agent attempted to obtain it, this failed in some way
6130: (e.g. <a href="urls.html#url">URL</a> could not be <a href="urls.html#resolve-a-url" title="resolve a
6131: url">resolved</a>, network error, unknown text track
6132: format). Some or all of the cues are likely missing and will not
6133: be obtained.</p>
6134:
6135: </dd>
6136:
6137: </dl><p>The <a href="#text-track-readiness-state" title="text track readiness state">readiness
6138: state</a> of a <a href="#text-track">text track</a> changes dynamically as
6139: the track is obtained.</p>
6140:
6141: </dd>
6142:
6143: <dt><dfn id="text-track-mode" title="text track mode">A mode</dfn>
6144:
6145: </dt><dd>
6146:
6147: <p>One of the following:</p>
6148:
6149: <dl><dt><dfn id="text-track-disabled" title="text track disabled">Disabled</dfn>
6150:
6151: </dt><dd>
6152:
6153: <p>Indicates that the text track is not active. Other than for
6154: the purposes of exposing the track in the DOM, the user agent is
6155: ignoring the text track. No cues are active, no events are
6156: fired, and the user agent will not attempt to obtain the track's
6157: cues.</p>
6158:
6159: </dd>
6160:
6161: <dt><dfn id="text-track-hidden" title="text track hidden">Hidden</dfn>
6162:
6163: </dt><dd>
6164:
6165: <p>Indicates that the text track is active, but that the user
6166: agent is not actively displaying the cues. If no attempt has yet
6167: been made to obtain the track's cues, the user agent will
6168: perform such an attempt momentarily. The user agent is
6169: maintaining a list of which cues are active, and events are
6170: being fired accordingly.</p>
6171:
6172: </dd>
6173:
6174: <dt><dfn id="text-track-showing" title="text track showing">Showing</dfn>
6175: <dt><dfn id="text-track-showing-by-default" title="text track showing by default">Showing by default</dfn>
6176:
6177: </dt></dt><dd>
6178:
6179: <p>Indicates that the text track is active. If no attempt has
6180: yet been made to obtain the track's cues, the user agent will
6181: perform such an attempt momentarily. The user agent is
6182: maintaining a list of which cues are active, and events are
6183: being fired accordingly. In addition, for text tracks whose
6184: <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
6185: are being displayed over the video as appropriate; for text
6186: tracks whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-descriptions">descriptions</code>,
6187: the user agent is making the cues available to the user in a
6188: 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
6189: agent is making available to the user a mechanism by which the
6190: user can navigate to any point in the <a href="#media-resource">media
6191: resource</a> by selecting a cue.</p>
6192:
6193: <p>The <a href="#text-track-showing-by-default" title="text track showing by default">showing by
6194: default</a> state is used in conjunction with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute on
6195: <code><a href="#the-track-element">track</a></code> elements to indicate that the text track was
6196: enabled due to that attribute. This allows the user agent to
6197: override the state if a later track is discovered that is more
6198: appropriate per the user's preferences.</p>
6199:
6200: </dd>
6201:
6202: </dl></dd>
6203:
6204: <dt><dfn id="text-track-list-of-cues" title="text track list of cues">A list of zero or more cues</dfn>
6205:
6206: </dt><dd>
6207:
6208: <p>A list of <a href="#text-track-cue" title="text track cue">text track
6209: cues</a>, along with <dfn id="rules-for-updating-the-text-track-rendering">rules for updating the text track
6210: rendering</dfn>.
6211: </p>
6212:
6213: <p>The <a href="#text-track-list-of-cues" title="text track list of cues">list of cues of a
6214: text track</a> can change dynamically, either because the
6215: <a href="#text-track">text track</a> has <a href="#text-track-not-loaded" title="text track not
6216: loaded">not yet been loaded</a> or is still <a href="#text-track-loading" title="text
6217: track loading">loading</a>, or because the <a href="#text-track">text
6218: track</a> corresponds to a <code><a href="#mutabletexttrack">MutableTextTrack</a></code>
6219: object, whose API allows individual cues can be added or removed
6220: dynamically.</p>
6221:
6222: </dd>
6223:
6224: </dl><p>Each <a href="#text-track">text track</a> has a corresponding
6225: <code><a href="#texttrack">TextTrack</a></code> object.</p><p>The <a href="#text-track" title="text track">text tracks</a> of a
6226: <a href="#media-element">media element</a> are <dfn id="the-text-tracks-are-ready" title="the text tracks are
6227: ready">ready</dfn> if all the <a href="#text-track" title="text track">text
6228: tracks</a> whose <a href="#text-track-mode" title="text track mode">mode</a> was
6229: not in the <a href="#text-track-disabled" title="text track disabled">disabled</a> state
6230: when the element's <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
6231: algorithm</a> last started now have a <a href="#text-track-readiness-state">text track readiness
6232: state</a> of <a href="#text-track-loaded" title="text track loaded">loaded</a> or
6233: <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
6234: in a <a href="#text-track">text track</a>, corresponding for instance for
6235: subtitles and captions to the text that appears at a particular time
6236: 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>
6237: </dt><dd>
6238: <p>An arbitrary string.</p>
6239: </dd>
6240:
6241: <dt><dfn id="text-track-cue-start-time" title="text track cue start time">A start time</dfn>
6242: </dt><dd>
6243: <p>A time, in seconds and fractions of a second, at which the cue
6244: becomes relevant.</p>
6245: </dd>
6246:
6247: <dt><dfn id="text-track-cue-end-time" title="text track cue end time">An end time</dfn>
6248: </dt><dd>
6249: <p>A time, in seconds and fractions of a second, at which the cue
6250: stops being relevant.</p>
6251: </dd>
6252:
6253: <dt><dfn id="text-track-cue-pause-on-exit-flag" title="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
6254: </dt><dd>
6255: <p>A boolean indicating whether playback of the <a href="#media-resource">media
6256: resource</a> is to pause when the cue stops being relevant.</p>
6257: </dd>
6258:
6259: <dt><dfn id="text-track-cue-writing-direction" title="text track cue writing direction">A writing direction</dfn>
6260: </dt><dd>
6261: <p>A writing direction, either <dfn id="text-track-cue-horizontal-writing-direction" title="text track cue
6262: horizontal writing direction">horizontal</dfn> (a line extends
6263: horizontally and is positioned vertically, with consecutive lines
6264: displayed below each other), <dfn id="text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical
6265: growing left writing direction">vertical growing left</dfn> (a
6266: line extends vertically and is positioned horizontally, with
6267: 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
6268: growing right writing direction">vertical growing right</dfn> (a
6269: line extends vertically and is positioned horizontally, with
6270: consecutive lines displayed to the right of each other).</p>
6271:
6272:
6273: </dd>
6274:
6275:
6276: <dt><dfn id="text-track-cue-size" title="text track cue size">A size</dfn>
6277: </dt><dd>
6278: <p>A number giving the size of the box within which the text of
6279: each line of the cue is to be aligned, to be interpreted as a
6280: percentage of the video, as defined by the <a href="#text-track-cue-writing-direction" title="text
6281: track cue writing direction">writing direction</a>.</p>
6282: </dd>
6283:
6284:
6285: <dt><dfn id="text-track-cue-text" title="text track cue text">The text of the cue</dfn>
6286: </dt><dd>
6287: <p>The raw text of the cue, and rules for its interpretation,
6288: allowing the text to be rendered and converted to a DOM fragment.</p>
6289: </dd>
6290:
6291: </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
6292: <code><a href="#texttrackcue">TextTrackCue</a></code> object, and can be associated with a
6293: particular <a href="#text-track">text track</a>. Once a <a href="#text-track-cue">text track
6294: cue</a> is associated with a particular <a href="#text-track">text track</a>,
6295: the association is permanent.</p><p>In addition, each <a href="#text-track-cue">text track cue</a> has two pieces of
6296: dynamic information:</p><dl><dt>The <dfn id="text-track-cue-active-flag" title="text track cue active flag">active flag</dfn>
6297: </dt><dd>
6298:
6299: <p>This flag must be initially unset. The flag is used to ensure
6300: events are fired appropriately when the cue becomes active or
6301: inactive, and to make sure the right cues are rendered.</p>
6302:
6303: <p>The user agent must synchronously unset this flag whenever the
6304: <a href="#text-track-cue">text track cue</a> is removed from its <a href="#text-track">text
6305: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>; whenever the
6306: <a href="#text-track">text track</a> itself is removed from its <a href="#media-element">media
6307: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> or has its
6308: <a href="#text-track-mode">text track mode</a> changed to <a href="#text-track-disabled" title="text track
6309: disabled">disabled</a>; and whenever the <a href="#media-element">media
6310: element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is changed back to
6311: <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>. When the
6312: 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
6313: track showing by default">showing by default</a> prior to the
6314: relevant incident, the user agent must, after having unset the
6315: flag for all the affected cues, apply the <a href="#rules-for-updating-the-text-track-rendering">rules for updating
6316: the text track rendering</a> of those <a href="#text-track" title="text
6317: track">text tracks</a>.
6318: </p></dd>
6319:
6320: <dt>The <dfn id="text-track-cue-display-state" title="text track cue display state">display state</dfn>
6321: </dt><dd>
6322:
6323: <p>This is used as part of the rendering model, to keep cues in a
6324: consistent position. It must initially be empty. Whenever the
6325: <a href="#text-track-cue-active-flag">text track cue active flag</a> is unset, the user agent
6326: must empty the <a href="#text-track-cue-display-state">text track cue display state</a>.</p>
6327:
6328: </dd>
6329:
6330: </dl><p>The <a href="#text-track-cue" title="text track cue">text track cues</a> of a
6331: <a href="#media-element">media element</a>'s <a href="#text-track" title="text track">text
6332: tracks</a> are ordered relative to each other in the <dfn id="text-track-cue-order">text
6333: track cue order</dfn>, which is determined as follows: first group
6334: the <a href="#text-track-cue" title="text track cue">cues</a> by their <a href="#text-track">text
6335: track</a>, with the groups being sorted in the same order as
6336: their <a href="#text-track" title="text track">text tracks</a> appear in the
6337: <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>;
6338: then, within each group, <a href="#text-track-cue" title="text track cue">cues</a>
6339: must be sorted by their <a href="#text-track-cue-start-time" title="text track cue start
6340: 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
6341: track cue start time">start time</a> must be sorted by their
6342: <a href="#text-track-cue-end-time" title="text track cue end time">end time</a>, earliest
6343: first; and finally, any <a href="#text-track-cue" title="text track cue">cues</a>
6344: with identical <a href="#text-track-cue-end-time" title="text track cue end time">end
6345: times</a> must be sorted in the order they were created (so
6346: e.g. for cues from a <span>WebVTT</span> file, that would be the
6347: 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
6348: track</a> that corresponds to data found in the <a href="#media-resource">media
6349: resource</a>.</p><div class="impl">
6350:
6351: <p>Rules for processing and rendering such data are defined by the
6352: relevant specifications, e.g. the specification of the video format
6353: if the <a href="#media-resource">media resource</a> is a video.</p>
6354:
6355: <p>When a <a href="#media-resource">media resource</a> contains data that the user
6356: agent recognises and supports as being equivalent to a <a href="#text-track">text
6357: track</a>, the user agent <a href="#found-a-media-resource-specific-timed-track">runs</a> the
6358: <dfn id="steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text track</dfn>
6359: with the relevant data, as follows:</p>
6360:
6361: <ol><li><p>Associate the relevant data with a new <a href="#text-track">text
6362: track</a> and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6363: object. The <a href="#text-track">text track</a> is a
6364: <a href="#media-resource-specific-text-track">media-resource-specific text track</a>.</p></li>
6365:
6366: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-kind" title="text track
6367: kind">kind</a>, <a href="#text-track-label" title="text track label">label</a>,
6368: and <a href="#text-track-language" title="text track language">language</a> based on the
6369: semantics of the relevant data, as defined by the relevant
6370: specification.</p></li>
6371:
6372: <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
6373: parsed so far, folllowing the <span>guidelines for exposing
6374: cues</span>, and begin updating it dynamically as
6375: necessary.</p></li>
6376:
6377: <li>
6378:
6379: <p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-readiness-state" title="text track
6380: readiness state">readiness state</a> to the value that most
6381: correctly describes the current state, and begin updating it
6382: dynamically as necessary.</p>
6383:
6384: <p class="example">For example, if the relevant data in the
6385: <a href="#media-resource">media resource</a> has been fully parsed and completely
6386: describes the cues, then the <a href="#text-track">text track</a> would be
6387: <a href="#text-track-loaded" title="text track loaded">loaded</a>. On the other hand,
6388: if the data for the cues is interleaved with the <a href="#media-data">media
6389: data</a>, and the <a href="#media-resource">media resource</a> as a whole is
6390: still being downloaded, then the <a href="#text-track-loading" title="text track
6391: loading">loading</a> state might be more accurate.</p>
6392:
6393: </li>
6394:
6395: <li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-mode" title="text
6396: track mode">mode</a> to the mode consistent with the user's
6397: preferences and the requirements of the relevant specification for
6398: the data.</p></li>
6399:
6400: <li><p>Leave the <a href="#text-track-list-of-cues">text track list of cues</a> empty, and
6401: associate with it the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
6402: rendering</a> appropriate for the format in question.</p>
6403:
6404: </li><li><p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6405: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p></li>
6406:
6407: </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
6408: element's media-resource-specific text tracks</dfn>, the user
6409: agent must remove from the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list
6410: of text tracks</a> all the <a href="#media-resource-specific-text-track" title="media-resource-specific
6411: text track">media-resource-specific text tracks</a>.</p>
6412:
6413: </div><div class="impl">
6414:
6415: <h6 id="sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</h6>
6416:
6417: <p>When a <code><a href="#the-track-element">track</a></code> element is created, it must be
6418: associated with a new <a href="#text-track">text track</a> (with its value set
6419: as defined below) and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
6420: object.</p>
6421:
6422: <p>The <a href="#text-track-kind">text track kind</a> is determined from the state of
6423: the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute
6424: according to the following table; for a state given in a cell of the
6425: first column, the <a href="#text-track-kind" title="text track kind">kind</a> is the
6426: string given in the second column:</p>
6427:
6428: <table><thead><tr><th>State
6429: </th><th>String
6430: </th></tr></thead><tbody><tr><td><a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</a>
6431: </td><td><code title="dom-timedtrack-kind-subtitles">subtitles</code>
6432: </td></tr><tr><td><a href="#attr-track-kind-captions" title="attr-track-kind-captions">Captions</a>
6433: </td><td><code title="dom-timedtrack-kind-captions">captions</code>
6434: </td></tr><tr><td><a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</a>
6435: </td><td><code title="dom-timedtrack-kind-descriptions">descriptions</code>
6436: </td></tr><tr><td><a href="#attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</a>
6437: </td><td><code title="dom-timedtrack-kind-chapters">chapters</code>
6438: </td></tr><tr><td><a href="#attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</a>
6439: </td><td><code title="dom-timedtrack-kind-metadata">metadata</code>
6440: </td></tr></tbody></table><p>The <a href="#text-track-label">text track label</a> is the element's <a href="#track-label">track
6441: label</a>.</p>
6442:
6443: <p>The <a href="#text-track-language">text track language</a> is the element's
6444: <a href="#track-language">track language</a>, if any, or the empty string
6445: otherwise.</p>
6446:
6447: <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,
6448: changed, or removed, the <a href="#text-track">text track</a> must update
6449: accordingly, as per the definitions above.</p>
6450:
6451: <p class="note">Changes to the <a href="#track-url">track URL</a> are handled in
6452: the algorithm below.</p>
6453:
6454: <p>The <a href="#text-track-list-of-cues">text track list of cues</a> is initially empty. It
6455: is dynamically modified when the referenced file is parsed.
6456: Associated with the list are the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text
6457: track rendering</a> appropriate for the format in question; for
6458: <span>WebVTT</span>, this is the <a href="rendering.html#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the
6459: display of WebVTT text tracks</a>.</p>
6460:
6461: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6462: the new parent is a <a href="#media-element">media element</a>, then the user agent
6463: must add the <code><a href="#the-track-element">track</a></code> element's corresponding <a href="#text-track">text
6464: track</a> to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
6465: tracks</a>.</p>
6466:
6467: <p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
6468: the old parent was a <a href="#media-element">media element</a>, then the user agent
6469: must remove the <code><a href="#the-track-element">track</a></code> element's corresponding
6470: <a href="#text-track">text track</a> from the <a href="#media-element">media element</a>'s
6471: <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6472:
6473: <p>When a <a href="#text-track">text track</a> corresponding to a
6474: <code><a href="#the-track-element">track</a></code> element is added to a <a href="#media-element">media
6475: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, the user agent
6476: must set the <a href="#text-track-mode">text track mode</a> appropriately, as
6477: determined by the following conditions:</p>
6478:
6479: <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
6480: has indicated an interest in having a track with this <a href="#text-track-kind">text
6481: track kind</a>, <a href="#text-track-language">text track language</a>, and
6482: <a href="#text-track-label">text track label</a> enabled, and there is no other
6483: <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6484: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6485: 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
6486: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6487: showing">showing</a></dt>
6488:
6489: <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
6490: the user has indicated an interest in having text descriptions with
6491: this <a href="#text-track-language">text track language</a> and <a href="#text-track-label">text track
6492: label</a> enabled, and there is no other <a href="#text-track">text
6493: track</a> in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of
6494: 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
6495: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6496: showing">showing</a></dt>
6497:
1.62 mike 6498: <dd>
6499: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6500: track showing">showing</a>.</p>
6501:
6502: <p>If there is a <a href="#text-track">text track</a> in the <a href="#media-element">media
6503: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6504: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing-by-default" title="text track showing
6505: by default">showing by default</a>, the user agent must
6506: furthermore change <em>that</em> <a href="#text-track">text track</a>'s
6507: <a href="#text-track-mode">text track mode</a> to <a href="#text-track-hidden" title="text track
6508: hidden">hidden</a>.</p>
6509: </dd>
6510:
1.47 mike 6511: <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
6512: <a href="#text-track-language">text track language</a> is one that the user agent has
6513: reason to believe is appropriate for the user, and there is no
6514: other <a href="#text-track">text track</a> in the <a href="#media-element">media element</a>'s
6515: <a href="#list-of-text-tracks">list of text tracks</a> with a <a href="#text-track-kind">text track
6516: kind</a> of <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> whose
6517: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6518: showing">showing</a></dt>
6519:
6520: <dd>
6521: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
6522: track showing">showing</a>.</p>
6523: </dd>
6524:
6525: <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
6526: there is no other <a href="#text-track">text track</a> in the <a href="#media-element">media
6527: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> whose
6528: <a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
6529: showing">showing</a> or <a href="#text-track-showing-by-default" title="text track
6530: showing by default">showing by default</a></dt>
6531:
6532: <dd>
6533: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing-by-default" title="text
6534: track showing by default">showing by default</a>.</p>
6535: </dd>
6536:
6537: <dt>Otherwise</dt>
6538:
6539: <dd>
6540: <p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-disabled" title="text
6541: track disabled">disabled</a>.</p>
6542: </dd>
6543:
6544: </dl><p>When a <a href="#text-track">text track</a> corresponding to a
6545: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6546: mode</a> set to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6547: <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>,
6548: and when a <a href="#text-track">text track</a> corresponding to a
6549: <code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
6550: mode</a> set to <a href="#text-track-disabled" title="text track
6551: disabled">disabled</a> and subsequently changes its <a href="#text-track-mode">text
6552: track mode</a> to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
6553: <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
6554: the first time, the user agent must immediately and synchronously
6555: run the following algorithm. This algorithm interacts closely with
6556: the <a href="webappapis.html#event-loop">event loop</a> mechanism; in particular, it has a
6557: <a href="webappapis.html#synchronous-section">synchronous section</a> (which is triggered as part of the
6558: <a href="webappapis.html#event-loop">event loop</a> algorithm). The step in that section is
6559: marked with ⌛.</p>
6560:
6561: <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>
6562:
6563: <li><p>Let <var title="">URL</var> be the <a href="#track-url">track URL</a> of
6564: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6565:
6566: <li><p>Asynchronously run the remaining steps, while continuing
6567: with whatever task was responsible for creating the <a href="#text-track">text
6568: track</a> or changing the <a href="#text-track-mode">text track
6569: mode</a>.</p></li>
6570:
6571: <li>
6572:
1.61 mike 6573: <p><i>Download</i>: At this point, the text track is downloaded.</p>
6574:
6575: <p>If <var title="">URL</var> is not the empty string, perform a
6576: <a href="fetching-resources.html#potentially-cors-enabled-fetch">potentially CORS-enabled fetch</a> of <var title="">URL</var>, with the <i>mode</i> being the state of the
6577: <a href="#media-element">media element</a>'s <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> content
6578: attribute, the <i><a href="origin-0.html#origin">origin</a></i> being the <a href="origin-0.html#origin">origin</a> of the
6579: <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>, and the
6580: <i>default origin behaviour</i> set to <i>fail</i>.</p>
6581:
6582: <p>The resource obtained in this fashion, if any, contains the
6583: text track data. If any data is obtained, it is by definition
6584: <a href="fetching-resources.html#cors-same-origin">CORS-same-origin</a> (cross-origin resources that are not
6585: suitably CORS-enabled do not get this far).</p>
6586:
1.47 mike 6587: <p>The <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue
6588: a task">queued</a> by the <a href="fetching-resources.html#fetch" title="fetch">fetching
6589: algorithm</a> on the <a href="webappapis.html#networking-task-source">networking task source</a> to
6590: process the data as it is being fetched must examine the
6591: resource's <a href="fetching-resources.html#content-type" title="Content-Type">Content Type
6592: 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
6593: available, or if the type is not recognised as a text track
6594: format, then the resource's format must be assumed to be
6595: unsupported (this causes the load to fail, as described below). If
6596: a type is obtained, and represents a supported text track format,
6597: then the resource's data must be passed to the appropriate parser
6598: as it is received, with the <a href="#text-track-list-of-cues">text
6599: track list of cues</a> being used for that parser's output.</p>
6600:
6601: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> fails for
6602: any reason (network error, the server returns an error code, a
1.61 mike 6603: cross-origin check fails, etc), if <var title="">URL</var> is the
6604: empty string, or if the fetched resource is not in a supported
6605: format, then <a href="webappapis.html#queue-a-task">queue a task</a> to first change the
6606: <a href="#text-track-readiness-state">text track readiness state</a> to <a href="#text-track-failed-to-load" title="text track
6607: failed to load">failed to load</a> and then <a href="webappapis.html#fire-a-simple-event">fire a simple
6608: event</a> named <code title="event-error">error</code> at the
6609: <code><a href="#the-track-element">track</a></code> element; and then, once that <a href="webappapis.html#concept-task" title="concept-task">task</a> is <a href="webappapis.html#queue-a-task" title="queue a
1.47 mike 6610: task">queued</a>, move on to the step below labeled
6611: <i>monitoring</i>.</p>
6612:
6613: <p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> does not
6614: fail, then, when it completes, <a href="webappapis.html#queue-a-task">queue a task</a> to first
6615: 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
6616: simple event</a> named <code title="event-load">load</code> at
6617: 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
6618: task">queued</a>, move on to the step below labeled
6619: <i>monitoring</i>.</p>
6620:
6621: <p>If, while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> is
6622: active, either:</p>
6623:
6624: <ul><li>the <a href="#track-url">track URL</a> changes so that it is no longer
6625: equal to <var title="">URL</var>, while the <a href="#text-track-mode">text track
6626: mode</a> is set to <a href="#text-track-hidden" title="text track
6627: hidden">hidden</a>, <a href="#text-track-showing" title="text track
6628: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
6629: default">showing by default</a>; or</li>
6630:
6631: <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
6632: track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track
6633: showing by default">showing by default</a>, while the
6634: <a href="#track-url">track URL</a> is not equal to <var title="">URL</var></li>
6635:
6636: </ul><p>...then the user agent must run the following steps:</p>
6637:
6638: <ol><li><p>Abort the <a href="fetching-resources.html#fetch" title="fetch">fetching
6639: algorithm</a>.</p></li>
6640:
6641: <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
6642: event</a> named <code title="event-abort">abort</code> at
6643: the <code><a href="#the-track-element">track</a></code> element.</p></li>
6644:
6645: <li><p>Let <var title="">URL</var> be the new <a href="#track-url">track
6646: URL</a>.</p></li>
6647:
6648: <li><p>Jump back to the top of the step labeled
6649: <i>download</i>.</p></li>
6650:
6651: </ol><p>Until one of the above circumstances occurs, the user agent
6652: must remain on this step.</p>
6653:
6654: </li>
6655:
6656: <li><p><i>Monitoring</i>: Wait until the <a href="#track-url">track URL</a> is
6657: no longer equal to <var title="">URL</var>, at the same time as the
6658: <a href="#text-track-mode">text track mode</a> is set to <a href="#text-track-hidden" title="text track
6659: hidden">hidden</a>, <a href="#text-track-showing" title="text track
6660: showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
6661: default">showing by default</a>.</p></li>
6662:
6663: <li><p>Wait until the <a href="#text-track-readiness-state">text track readiness state</a> is
6664: no longer set to <a href="#text-track-loading" title="text track
6665: loading">loading</a>.</p></li>
6666:
6667: <li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
6668: section</a> consists of the following step. (The step in the
6669: <a href="webappapis.html#synchronous-section">synchronous section</a> is marked with ⌛.)</p></li>
6670:
6671: <li><p>⌛ Set the <a href="#text-track-readiness-state">text track readiness state</a> to
6672: <a href="#text-track-loading" title="text track loading">loading</a>.</p></li>
6673:
6674:
6675: <li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
6676: remaining steps asynchronously.</p></li>
6677:
6678: <li><p>Jump to the step labeled <i>download</i>.</p></li>
6679:
6680: </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>
6681: <dd>
6682: <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>
6683: </dd>
6684:
6685: <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>
6686: <dd>
6687: <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>
6688: </dd>
6689:
6690: <dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
6691: <dd>
6692: <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>
6693: </dd>
6694:
6695: </dl><div class="impl">
6696:
6697: <p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn>
6698: attribute of <a href="#media-element" title="media element">media elements</a> must
6699: return an <span title="array host objects">array host object</span>
6700: for objects of type <code><a href="#texttrack">TextTrack</a></code> that is <i>fixed
6701: length</i> and <i>read only</i>. The same object must be returned
6702: each time the attribute is accessed. <a href="references.html#refsWEBIDL">[WEBIDL]</a></p>
6703:
6704: <p>The array must contain the <code><a href="#texttrack">TextTrack</a></code> objects of the
6705: <a href="#text-track" title="text track">text tracks</a> in the <a href="#media-element">media
6706: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, in the same
6707: order as in the <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6708:
6709: </div><hr><pre class="idl">interface <dfn id="texttrack">TextTrack</dfn> {
6710: readonly attribute DOMString <a href="#dom-texttrack-kind" title="dom-TextTrack-kind">kind</a>;
6711: readonly attribute DOMString <a href="#dom-texttrack-label" title="dom-TextTrack-label">label</a>;
6712: readonly attribute DOMString <a href="#dom-texttrack-language" title="dom-TextTrack-language">language</a>;
6713:
6714: const unsigned short <a href="#dom-texttrack-none" title="dom-TextTrack-NONE">NONE</a> = 0;
6715: const unsigned short <a href="#dom-texttrack-loading" title="dom-TextTrack-LOADING">LOADING</a> = 1;
6716: const unsigned short <a href="#dom-texttrack-loaded" title="dom-TextTrack-LOADED">LOADED</a> = 2;
6717: const unsigned short <a href="#dom-texttrack-error" title="dom-TextTrack-ERROR">ERROR</a> = 3;
6718: readonly attribute unsigned short <a href="#dom-texttrack-readystate" title="dom-TextTrack-readyState">readyState</a>;
6719: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-onload" title="handler-TextTrack-onload">onload</a>;
6720: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-onerror" title="handler-TextTrack-onerror">onerror</a>;
6721:
6722: const unsigned short <a href="#dom-texttrack-off" title="dom-TextTrack-OFF">OFF</a> = 0;
6723: const unsigned short <a href="#dom-texttrack-hidden" title="dom-TextTrack-HIDDEN">HIDDEN</a> = 1;
6724: const unsigned short <a href="#dom-texttrack-showing" title="dom-TextTrack-SHOWING">SHOWING</a> = 2;
6725: attribute unsigned short <a href="#dom-texttrack-mode" title="dom-TextTrack-mode">mode</a>;
6726:
6727: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a> <a href="#dom-texttrack-cues" title="dom-TextTrack-cues">cues</a>;
6728: readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a> <a href="#dom-texttrack-activecues" title="dom-TextTrack-activeCues">activeCues</a>;
6729:
6730: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
6731: };
6732: <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>
6733: <dd>
6734: <p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
6735: </dd>
6736:
6737: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-label"><a href="#dom-texttrack-label">label</a></code></dt>
6738: <dd>
6739: <p>Returns the <a href="#text-track-label">text track label</a>.</p>
6740: </dd>
6741:
6742: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-language"><a href="#dom-texttrack-language">language</a></code></dt>
6743: <dd>
6744: <p>Returns the <a href="#text-track-language">text track language</a> string.</p>
6745: </dd>
6746:
6747: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-readyState"><a href="#dom-texttrack-readystate">readyState</a></code></dt>
6748: <dd>
6749: <p>Returns the <a href="#text-track-readiness-state">text track readiness state</a>,
6750: represented by a number from the following list:</p>
6751: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-NONE"><a href="#dom-texttrack-none">NONE</a></code> (0)</dt>
6752: <dd>
6753: <p>The <a href="#text-track-not-loaded">text track not loaded</a> state.</p>
6754: </dd>
6755: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADING"><a href="#dom-texttrack-loading">LOADING</a></code> (1)</dt>
6756: <dd>
6757: <p>The <a href="#text-track-loading">text track loading</a> state.</p>
6758: </dd>
6759: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADED"><a href="#dom-texttrack-loaded">LOADED</a></code> (2)</dt>
6760: <dd>
6761: <p>The <a href="#text-track-loaded">text track loaded</a> state.</p>
6762: </dd>
6763: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-ERROR"><a href="#dom-texttrack-error">ERROR</a></code> (3)</dt>
6764: <dd>
6765: <p>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</p>
6766: </dd>
6767: </dl></dd>
6768:
6769: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code></dt>
6770: <dd>
6771: <p>Returns the <a href="#text-track-mode">text track mode</a>, represented by a
6772: number from the following list:</p>
6773: <dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-OFF"><a href="#dom-texttrack-off">OFF</a></code> (0)</dt>
6774: <dd>
6775: <p>The <a href="#text-track-disabled">text track disabled</a> mode.</p>
6776: </dd>
6777: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-HIDDEN"><a href="#dom-texttrack-hidden">HIDDEN</a></code> (1)</dt>
6778: <dd>
6779: <p>The <a href="#text-track-hidden">text track hidden</a> mode.</p>
6780: </dd>
6781: <dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-SHOWING"><a href="#dom-texttrack-showing">SHOWING</a></code> (2)</dt>
6782: <dd>
6783: <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>
6784: </dd>
6785: </dl><p>Can be set, to change the mode.</p>
6786: </dd>
6787:
6788: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-cues"><a href="#dom-texttrack-cues">cues</a></code></dt>
6789: <dd>
6790: <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>
6791: </dd>
6792:
6793: <dt><var title="">textTrack</var> . <code title="dom-TextTrack-activeCues"><a href="#dom-texttrack-activecues">activeCues</a></code></dt>
6794: <dd>
6795: <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>
6796: </dd>
6797:
6798: </dl><div class="impl">
6799:
6800: <p>The <dfn id="dom-texttrack-kind" title="dom-TextTrack-kind"><code>kind</code></dfn>
6801: attribute must return the <a href="#text-track-kind">text track kind</a> of the
6802: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
6803: represents.</p>
6804:
6805: <p>The <dfn id="dom-texttrack-label" title="dom-TextTrack-label"><code>label</code></dfn>
6806: attribute must return the <a href="#text-track-label">text track label</a> of the
6807: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
6808: represents.</p>
6809:
6810: <p>The <dfn id="dom-texttrack-language" title="dom-TextTrack-language"><code>language</code></dfn>
6811: attribute must return the <a href="#text-track-language">text track language</a> of the
6812: <a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
6813: represents.</p>
6814:
6815: <p>The <dfn id="dom-texttrack-readystate" title="dom-TextTrack-readyState"><code>readyState</code></dfn>
6816: attribute must return the numeric value corresponding to the
6817: <a href="#text-track-readiness-state">text track readiness state</a> of the <a href="#text-track">text
6818: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents, as
6819: defined by the following list:</p>
6820:
6821: <dl><dt><dfn id="dom-texttrack-none" title="dom-TextTrack-NONE"><code>NONE</code></dfn> (numeric value 0)</dt>
6822: <dd>The <a href="#text-track-not-loaded">text track not loaded</a> state.</dd>
6823: <dt><dfn id="dom-texttrack-loading" title="dom-TextTrack-LOADING"><code>LOADING</code></dfn> (numeric value 1)</dt>
6824: <dd>The <a href="#text-track-loading">text track loading</a> state.</dd>
6825: <dt><dfn id="dom-texttrack-loaded" title="dom-TextTrack-LOADED"><code>LOADED</code></dfn> (numeric value 2)</dt>
6826: <dd>The <a href="#text-track-loaded">text track loaded</a> state.</dd>
6827: <dt><dfn id="dom-texttrack-error" title="dom-TextTrack-ERROR"><code>ERROR</code></dfn> (numeric value 3)</dt>
6828: <dd>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</dd>
6829: </dl><p>The <dfn id="dom-texttrack-mode" title="dom-TextTrack-mode"><code>mode</code></dfn>
6830: attribute, on getting, must return the numeric value corresponding
6831: to the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text track</a>
6832: that the <code><a href="#texttrack">TextTrack</a></code> object represents, as defined by
6833: the following list:</p>
6834:
6835: <dl><dt><dfn id="dom-texttrack-off" title="dom-TextTrack-OFF"><code>OFF</code></dfn> (numeric value 0)</dt>
6836: <dd>The <a href="#text-track-disabled">text track disabled</a> mode.</dd>
6837: <dt><dfn id="dom-texttrack-hidden" title="dom-TextTrack-HIDDEN"><code>HIDDEN</code></dfn> (numeric value 1)</dt>
6838: <dd>The <a href="#text-track-hidden">text track hidden</a> mode.</dd>
6839: <dt><dfn id="dom-texttrack-showing" title="dom-TextTrack-SHOWING"><code>SHOWING</code></dfn> (numeric value 2)</dt>
6840: <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>
6841: </dl><p>On setting, if the new value is not either 0, 1, or 2, the user
6842: agent must throw an <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code>
6843: exception. Otherwise, if the new value isn't equal to what the
6844: attribute would currently return, the new value must be processed as
6845: follows:</p>
6846:
6847: <dl class="switch"><dt>If the new value is 0</dt>
6848:
6849: <dd>
6850:
6851: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6852: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
6853: the <a href="#text-track-disabled">text track disabled</a> mode.</p>
6854:
6855: </dd>
6856:
6857: <dt>If the new value is 1</dt>
6858:
6859: <dd>
6860:
6861: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6862: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
6863: the <a href="#text-track-hidden">text track hidden</a> mode.</p>
6864:
6865: </dd>
6866:
6867: <dt>If the new value is 2</dt>
6868:
6869: <dd>
6870:
6871: <p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6872: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
6873: the <a href="#text-track-showing">text track showing</a> mode.</p>
6874:
6875: <p class="note">If the mode had been <a href="#text-track-showing-by-default" title="text track
6876: showing by default">showing by default</a>, this will change it
6877: to <a href="#text-track-showing" title="text track showing">showing</a>, even though
6878: the value of <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> would
6879: appear not to change.</p>
6880:
6881: </dd>
6882:
6883: </dl><p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6884: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
6885: 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
6886: return a <a href="infrastructure.html#live">live</a> <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
6887: that represents the subset of the <a href="#text-track-list-of-cues">text track list of
6888: cues</a> of the <a href="#text-track">text track</a> that the
6889: <code><a href="#texttrack">TextTrack</a></code> object represents whose <a href="#text-track-cue-start-time" title="text
6890: track cue start time">start times</a> occur before the
6891: <a href="#earliest-possible-position-when-the-script-started">earliest possible position when the script started</a>, in
6892: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
6893: null. When an object is returned, the same object must be returned
6894: each time.</p>
6895:
6896: <p>The <dfn id="earliest-possible-position-when-the-script-started">earliest possible position when the script started</dfn>
6897: is whatever the <a href="#earliest-possible-position">earliest possible position</a> was the last
6898: time the <a href="webappapis.html#event-loop">event loop</a> reached step 1.</p>
6899:
6900: <p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
6901: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
6902: 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>
6903: attribute must return a <a href="infrastructure.html#live">live</a>
6904: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that represents the subset of
6905: the <a href="#text-track-list-of-cues">text track list of cues</a> of the <a href="#text-track">text
6906: track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents
6907: whose <a href="#active-flag-was-set-when-the-script-started">active flag was set when the script started</a>, in
6908: <a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
6909: null. When an object is returned, the same object must be returned
6910: each time.</p>
6911:
6912: <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
6913: the script started</dfn> if its <a href="#text-track-cue-active-flag">text track cue active
6914: flag</a> was set the last time the <a href="webappapis.html#event-loop">event loop</a>
6915: reached step 1.</p>
6916:
6917: </div><hr><pre class="idl">interface <dfn id="mutabletexttrack">MutableTextTrack</dfn> : <a href="#texttrack">TextTrack</a> {
6918: void <a href="#dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue">addCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
6919: void <a href="#dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue">removeCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
6920: };</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>
6921:
6922: <dd>
6923: <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>
6924: </dd>
6925:
6926: <dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-addCue"><a href="#dom-mutabletexttrack-addcue">addCue</a></code>( <var title="">cue</var> )</dt>
6927: <dd>
6928: <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>
6929: <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>
6930: </dd>
6931:
6932: <dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-removeCue"><a href="#dom-mutabletexttrack-removecue">removeCue</a></code>( <var title="">cue</var> )</dt>
6933: <dd>
6934: <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>
6935: <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>
6936: </dd>
6937:
6938: </dl><div class="impl">
6939:
6940: <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
6941: element">media elements</a>, when invoked, must run the following
6942: steps:</p>
6943:
6944: <ol><li>
6945:
6946: <p>If <var title="">kind</var> is not one of the following
6947: strings, then throw a <code><a href="common-dom-interfaces.html#syntax_err">SYNTAX_ERR</a></code> exception and abort
6948: these steps:</p>
6949:
6950: <ul class="brief"><li><code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code>
6951: </li><li><code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code>
6952: </li><li><code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code>
6953: </li><li><code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code>
6954: </li><li><code title="dom-TextTrack-kind-metadata"><a href="#dom-texttrack-kind-metadata">metadata</a></code>
6955: </li></ul></li>
6956:
6957: <li>
6958:
6959: <p>If the <var title="">label</var> argument was omitted, let <var title="">label</var> be the empty string.</p>
6960:
6961: </li>
6962:
6963: <li>
6964:
6965: <p>If the <var title="">language</var> argument was omitted, let
6966: <var title="">language</var> be the empty string.</p>
6967:
6968: </li>
6969:
6970: <li>
6971:
6972: <p>Create a new <a href="#text-track">text track</a>, and set its <a href="#text-track-kind">text
6973: track kind</a> to <var title="">kind</var>, its <a href="#text-track-label">text
6974: track label</a> to <var title="">label</var>, its <a href="#text-track-language">text
6975: track language</a> to <var title="">language</var>, its
6976: <a href="#text-track-readiness-state">text track readiness state</a> to the <a href="#text-track-loaded">text track
6977: loaded</a> state, its <a href="#text-track-mode">text track mode</a> to the
6978: <a href="#text-track-hidden">text track hidden</a> mode, and its <a href="#text-track-list-of-cues">text track
6979: list of cues</a> to an empty list.
6980: </p>
6981:
6982: </li>
6983:
6984: <li>
6985:
6986: <p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
6987: element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
6988:
6989: </li></ol><p>The <dfn id="dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue"><code>addCue(<var title="">cue</var>)</code></dfn> method of
6990: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
6991: following steps:</p>
6992:
6993: <ol><li><p>If <var title="">cue</var> is null, then throw an
6994: <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
6995: steps.</p></li>
6996:
6997: <li><p>If the given <var title="">cue</var> is already associated
6998: with a <a href="#text-track">text track</a> other than the method's
6999: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
7000: then throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception and abort
7001: these steps.</p></li>
7002:
7003: <li><p>Associate <var title="">cue</var> with the method's
7004: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
7005: if it is not currently associated with a <a href="#text-track">text
7006: track</a>.</p></li>
7007:
7008: <li><p>If the given <var title="">cue</var> is already listed in
7009: the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7010: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw an
7011: <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception.</p></li>
7012:
7013: <li><p>Add <var title="">cue</var> to the method's
7014: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
7015: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7016:
7017: </ol><p>The <dfn id="dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue"><code>removeCue(<var title="">cue</var>)</code></dfn> method of
7018: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
7019: following steps:</p>
7020:
7021: <ol><li><p>If <var title="">cue</var> is null, then throw an
7022: <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
7023: steps.</p></li>
7024:
7025: <li><p>If the given <var title="">cue</var> is not associated with
7026: the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7027: track</a>, then throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code>
7028: exception.</p></li>
7029:
7030: <li><p>If the given <var title="">cue</var> is not currently listed
7031: in the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
7032: track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw a
7033: <code><a href="common-dom-interfaces.html#not_found_err">NOT_FOUND_ERR</a></code> exception.</p></li>
7034:
7035: <li><p>Remove <var title="">cue</var> from the method's
7036: <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
7037: <a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
7038:
7039: </ol></div><div class="example">
7040:
7041: <p>In this example, an <code><a href="#the-audio-element">audio</a></code> element is used to play a
7042: specific sound-effect from a sound file containing many sound
7043: effects. A cue is used to pause the audio, so that it ends exactly
7044: at the end of the clip, even if the browser is busy running some
7045: script. If the page had relied on script to pause the audio, then
7046: the start of the next clip might be heard if the browser was not
7047: able to run the script at the exact time specified.</p>
7048:
7049: <pre>var sfx = new Audio('sfx.wav');
7050: var sounds = a.addTextTrack('metadata');
7051:
7052: // add sounds we care about
7053: sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
7054: sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));
7055:
7056: function playSound(id) {
7057: sfx.currentTime = sounds.getCueById(id).startTime;
7058: sfx.play();
7059: }
7060:
7061: sfx.oncanplaythrough = function () {
7062: playSound('dog bark');
7063: }
7064: window.onbeforeunload = function () {
7065: playSound('kitten mew');
7066: return 'Are you sure you want to leave this awesome page?';
7067: }</pre>
7068:
7069: </div><hr><pre class="idl">interface <dfn id="texttrackcuelist">TextTrackCueList</dfn> {
7070: readonly attribute unsigned long <a href="#dom-texttrackcuelist-length" title="dom-TextTrackCueList-length">length</a>;
7071: getter <a href="#texttrackcue">TextTrackCue</a> (in unsigned long index);
7072: <a href="#texttrackcue">TextTrackCue</a> <a href="#dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById">getCueById</a>(in DOMString id);
7073: };</pre><dl class="domintro"><dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-length"><a href="#dom-texttrackcuelist-length">length</a></code></dt>
7074: <dd>
7075: <p>Returns the number of <a href="#text-track-cue" title="text track cue">cues</a> in the list.</p>
7076: </dd>
7077:
7078: <dt><var title="">cuelist</var>[<var title="">index</var>]</dt>
7079: <dd>
7080: <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>
7081: </dd>
7082:
7083: <dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-getCueById"><a href="#dom-texttrackcuelist-getcuebyid">getCueById</a></code>( <var title="">id</var> )</dt>
7084: <dd>
7085: <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>
7086: <p>Returns null if none of the cues have the given identifier or if the argument is the empty string.</p>
7087: </dd>
7088:
7089: </dl><div class="impl">
7090:
7091: <p>A <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object represents a dynamically
7092: updating list of <a href="#text-track-cue" title="text track cue">text track
7093: cues</a> in a given order.</p>
7094:
7095: <p>The <dfn id="dom-texttrackcuelist-length" title="dom-TextTrackCueList-length"><code>length</code></dfn>
7096: attribute must return the number of <a href="#text-track-cue" title="text track
7097: cue">cues</a> in the list represented by the
7098: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7099:
7100: <p>The <span>supported property indicies</span> of a
7101: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
7102: from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
7103: in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
7104: minus one, if any. If there are no <a href="#text-track-cue" title="text track
7105: cue">cues</a> in the list, there are no <span>supported property
7106: indicies</span>.</p>
7107:
7108: <p>To <span>determine the value of an indexed property</span> for a
7109: given index <var title="">index</var>, the user agent must return
7110: the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
7111: list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
7112:
7113: <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
7114: other than the empty string, must return the first <a href="#text-track-cue">text track
7115: cue</a> in the list represented by the
7116: <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object whose <a href="#text-track-cue-identifier">text track cue
7117: identifier</a> is <var title="">id</var>, if any, or null
7118: otherwise. If the argument is the empty string, then the method must
7119: return null.</p>
7120:
7121: </div><hr><pre class="idl">
7122: interface <dfn id="texttrackcue">TextTrackCue</dfn> {
7123: readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a>;
7124: readonly attribute DOMString <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a>;
7125:
7126: readonly attribute double <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a>;
7127: readonly attribute double <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a>;
7128: readonly attribute boolean <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a>;
7129:
7130:
7131: DOMString <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>();
7132: <a href="infrastructure.html#documentfragment">DocumentFragment</a> <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>();
7133:
7134: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter">onenter</a>;
7135: attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit">onexit</a>;
7136: };
7137: <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>
7138: <dd>
7139: <p>Returns the <code><a href="#texttrack">TextTrack</a></code> object to which this
7140: <a href="#text-track-cue">text track cue</a> belongs, if any, or null
7141: otherwise.</p>
7142: </dd>
7143:
7144: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a></dt>
7145: <dd>
7146: <p>Returns the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
7147: </dd>
7148:
7149: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a></dt>
7150: <dd>
7151: <p>Returns the <a href="#text-track-cue-start-time">text track cue start time</a>, in seconds.</p>
7152: </dd>
7153:
7154: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a></dt>
7155: <dd>
7156: <p>Returns the <a href="#text-track-cue-end-time">text track cue end time</a>, in seconds.</p>
7157: </dd>
7158:
7159: <dt><var title="">cue</var> . <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a></dt>
7160: <dd>
7161: <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>
7162: </dd>
7163:
7164:
7165: <dt><var title="">source</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>()</dt>
7166: <dd>
7167: <p>Returns the <a href="#text-track-cue-text">text track cue text</a> in raw unparsed form.</p>
7168: </dd>
7169:
7170: <dt><var title="">fragment</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>()</dt>
7171: <dd>
7172: <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>
7173: </dd>
7174:
7175: </dl><div class="impl">
7176:
7177:
7178: <p>The <dfn id="dom-texttrackcue-track" title="dom-TextTrackCue-track"><code>track</code></dfn>
7179: attribute must return the <code><a href="#texttrack">TextTrack</a></code> object of the
7180: <a href="#text-track">text track</a> with which the <a href="#text-track-cue">text track cue</a>
7181: that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is associated,
7182: if any; or null otherwise.</p>
7183:
7184: <p>The <dfn id="dom-texttrackcue-id" title="dom-TextTrackCue-id"><code>id</code></dfn>
7185: attribute must return the <a href="#text-track-cue-identifier">text track cue identifier</a> of
7186: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7187: object represents.</p>
7188:
7189: <p>The <dfn id="dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime"><code>startTime</code></dfn>
7190: attribute must return the <a href="#text-track-cue-start-time">text track cue start time</a> of
7191: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7192: object represents, in seconds.</p>
7193:
7194: <p>The <dfn id="dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime"><code>endTime</code></dfn>
7195: attribute must return the <a href="#text-track-cue-end-time">text track cue end time</a> of
7196: the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
7197: object represents, in seconds.</p>
7198:
7199: <p>The <dfn id="dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit"><code>pauseOnExit</code></dfn>
7200: attribute must return true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue
7201: pause-on-exit flag</a> of the <a href="#text-track-cue">text track cue</a> that
7202: the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
7203: otherwise.</p>
7204:
7205: <p>The <dfn id="dom-texttrackcue-direction" title="dom-TextTrackCue-direction"><code>direction</code></dfn>
7206: attribute must return the <a href="#text-track-cue-writing-direction">text track cue writing
7207: direction</a> of the <a href="#text-track-cue">text track cue</a> that the
7208: <code><a href="#texttrackcue">TextTrackCue</a></code> object represents.</p>
7209:
7210:
7211: <p>The <dfn id="dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource"><code>getCueAsSource()</code></dfn>
7212: method must return the raw <a href="#text-track-cue-text">text track cue text</a>.</p>
7213:
7214: <p>The <dfn id="dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML"><code>getCueAsHTML()</code></dfn>
7215: method must convert the <a href="#text-track-cue-text">text track cue text</a> to a
7216: <code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> for the <a href="#media-element">media element</a>'s
7217: <code><a href="infrastructure.html#document">Document</a></code>, using the appropriate rules for doing
7218: so.
7219: </p>
7220:
7221: </div><div class="impl">
7222:
7223: <h6 id="cue-events"><span class="secno">4.8.10.12.5 </span>Event definitions</h6>
7224:
7225: <p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
7226: supported, as IDL attributes, by all objects implementing the
7227: <code><a href="#texttrack">TextTrack</a></code> interface:</p>
7228:
7229: <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>
7230: </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>
7231: </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>
7232: </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>
7233: </td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
7234: supported, as IDL attributes, by all objects implementing the
7235: <code><a href="#texttrackcue">TextTrackCue</a></code> interface:</p>
7236:
7237: <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>
7238: </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>
7239: </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>
7240: </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>
7241: attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. If present, it
7242: indicates that the author has not provided a scripted controller and
7243: would like the user agent to provide its own set of controls.</p><div class="impl">
7244:
7245: <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
7246: <a href="#media-element">media element</a>, then the user agent should <dfn id="expose-a-user-interface-to-the-user">expose a
7247: user interface to the user</dfn>. This user interface should include
7248: features to begin playback, pause playback, seek to an arbitrary
7249: position in the content (if the content supports arbitrary seeking),
7250: change the volume, change the display of closed captions or embedded
7251: sign-language tracks, select different audio tracks or turn on audio
7252: descriptions, and show the media content in manners more suitable to
7253: the user (e.g. full-screen video or in an independent resizable
7254: window). Other controls may also be made available.</p>
7255:
7256: <p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7257: controller</a>, then the user agent should expose audio tracks
7258: from all the <a href="#slaved-media-elements">slaved media elements</a> (although avoiding
7259: duplicates if the same <a href="#media-resource">media resource</a> is being used
7260: several times). If a <a href="#media-resource">media resource</a>'s audio track
7261: exposed in this way has no known name, and it is the only audio
7262: track for a particular <a href="#media-element">media element</a>, the user agent
7263: should use the element's <code title="attr-title"><a href="elements.html#the-title-attribute">title</a></code>
7264: attribute, if any, as the name (or as part of the name) of that
7265: track.</p>
7266:
7267: <p>Even when the attribute is absent, however, user agents may
7268: provide controls to affect playback of the media resource
7269: (e.g. play, pause, seeking, and volume controls), but such features
7270: should not interfere with the page's normal rendering. For example,
7271: such features could be exposed in the <a href="#media-element">media element</a>'s
7272: context menu.</p>
7273:
7274: <p>Where possible (specifically, for starting, stopping, pausing,
7275: and unpausing playback, for seeking, for changing the rate of
7276: playback, for fast-forwarding or rewinding,
7277: for listing, enabling, and disabling text tracks,
7278: and for muting or changing the volume of the audio), user interface
7279: features exposed by the user agent must be implemented in terms of
7280: the DOM API described above, so that, e.g., all the same events
7281: fire.</p>
7282:
7283: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7284: controller</a>, the user agent's user interface for pausing and
7285: unpausing playback, for seeking, for changing the rate of playback,
7286: for fast-forwarding or rewinding, and for muting or changing the
7287: volume of audio of the entire group must be implemented in terms of
7288: the <code><a href="#mediacontroller">MediaController</a></code> API exposed on that <a href="#current-media-controller">current
7289: media controller</a>.</p>
7290:
7291: <p>The "play" function in the user agent's interface must set the
7292: <code title="">playbackRate</code> attribute to the value of the
7293: <code title="">defaultPlaybackRate</code> attribute before invoking
7294: the <code title="">play()</code> method.
7295: When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7296: controller</a>, the attributes and method with those names on
7297: that <code><a href="#mediacontroller">MediaController</a></code> object must be used. Otherwise,
7298: the attributes and method with those names on the <a href="#media-element">media
7299: element</a> itself must be used.
7300: </p>
7301:
7302: <p>Features such as fast-forward or rewind must be implemented by
7303: only changing the <code title="">playbackRate</code> attribute (and
7304: not the <code title="">defaultPlaybackRate</code> attribute).
7305: Again, when a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7306: controller</a>, the attributes with those names on that
7307: <code><a href="#mediacontroller">MediaController</a></code> object must be used; otherwise, the
7308: attributes with those names on the <a href="#media-element">media element</a> itself
7309: must be used.
7310: </p>
7311:
7312: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7313: controller</a>, and all the <a href="#slaved-media-elements">slaved media elements</a> of
7314: that <code><a href="#mediacontroller">MediaController</a></code> are paused, the user agent should
7315: unpause all the <a href="#slaved-media-elements">slaved media elements</a> when the user
7316: invokes a user agent interface control for beginning playback.</p>
7317:
7318: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7319: controller</a>, seeking must be implemented in terms of the <code title="dom-MediaController-seek">seek()</code> method on that
7320: <code><a href="#mediacontroller">MediaController</a></code> object. Otherwise, the user agent must
7321: directly <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the requested
7322: position in the <a href="#media-element">media element</a>'s <a href="#media-timeline">media
7323: timeline</a>.</p>
7324:
7325: <p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
7326: controller</a>, user agents may additionally provide the user
7327: with controls that directly manipulate an individual <a href="#media-element">media
7328: element</a> without affecting the <code><a href="#mediacontroller">MediaController</a></code>,
7329: but such features are considered relatively advanced and unlikely to
7330: be useful to most users.
7331:
7332: </p><p>For the purposes of listing chapters in the <a href="#media-resource">media
7333: resource</a>, only <a href="#text-track" title="text track">text tracks</a>
7334: in the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
7335: tracks</a> <a href="#text-track-showing" title="text track showing">showing</a> or
7336: <a href="#text-track-showing-by-default" title="text track showing by default">showing by
7337: 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.
7338: Each <a href="#text-track-cue" title="text track cue">cue</a> in such a <a href="#text-track">text
7339: 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
7340: the chapter is the <a href="#text-track-cue-text">text track cue text</a>, interpreted
7341: literally.</p>
7342:
7343: <p>The <dfn id="dom-media-controls" title="dom-media-controls"><code>controls</code></dfn>
7344: IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
7345: same name.</p>
7346:
7347: <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>
7348:
7349: <dd>
7350:
7351: <p>Returns the current playback volume, as a number in the range
7352: 0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.</p>
7353:
7354: <p>Can be set, to change the volume.</p>
7355:
7356: <p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
7357: in the range 0.0 .. 1.0.</p>
7358:
7359: </dd>
7360:
7361: <dt><var title="">media</var> . <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
7362:
7363: <dd>
7364:
7365: <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
7366: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute is being
7367: honored.</p>
7368:
7369: <p>Can be set, to change whether the audio is muted or not.</p>
7370:
7371: </dd>
7372:
7373: </dl><div class="impl">
7374:
7375: <p>The <dfn id="dom-media-volume" title="dom-media-volume"><code>volume</code></dfn>
7376: attribute must return the playback volume of any audio portions of
7377: the <a href="#media-element">media element</a>, in the range 0.0 (silent) to 1.0
7378: (loudest). Initially, the volume must be 1.0, but user agents may
7379: remember the last set value across sessions, on a per-site basis or
7380: otherwise, so the volume may start at other values. On setting, if
7381: the new value is in the range 0.0 to 1.0 inclusive, the attribute
7382: must be set to the new value. If the new value is outside the range
7383: 0.0 to 1.0 inclusive, then, on setting, an
7384: <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
7385:
7386: <p>The <dfn id="dom-media-muted" title="dom-media-muted"><code>muted</code></dfn>
7387: attribute must return true if the audio channels are muted and false
7388: otherwise. Initially, the audio channels should not be muted
7389: (false), but user agents may remember the last set value across
7390: sessions, on a per-site basis or otherwise, so the muted state may
7391: start as muted (true). On setting, the attribute must be set to the
7392: new value.</p>
7393:
7394: <p>Whenever either the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> or
7395: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attributes are changed,
7396: 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
7397: event</a> named <code title="event-media-volumechange"><a href="#event-media-volumechange">volumechange</a></code> at the <a href="#media-element">media
7398: element</a>.</p>
7399:
7400: <p>An element's <dfn id="effective-media-volume">effective media volume</dfn> is determined as
7401: follows:</p>
7402:
7403: <ol><li><p>If the element's <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code>
7404: attribute is true, the element's <a href="#effective-media-volume">effective media
7405: volume</a> is zero. Abort these steps.</p></li>
7406:
7407: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>
7408: and that <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-mute-override">media
7409: controller mute override</a> is true, the element's
7410: <a href="#effective-media-volume">effective media volume</a> is zero. Abort these
7411: steps.</p></li>
7412:
7413: <li><p>Let <var title="">volume</var> be the value of the element's
7414: <code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute.</p></li>
7415:
7416: <li><p>If the element has a <a href="#current-media-controller">current media controller</a>,
7417: multiply <var title="">volume</var> by that
7418: <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-volume-multiplier">media controller volume
7419: multiplier</a>.</p></li>
7420:
7421: <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
7422: 1.0, with 0.0 being silent, and 1.0 being the loudest setting,
7423: values in between increasing in loudness. The range need not be
7424: linear. The loudest setting may be lower than the system's loudest
7425: possible setting; for example the user could have set a maximum
7426: volume.</p></li>
7427:
7428: </ol></div><p>The <dfn id="attr-media-muted" title="attr-media-muted"><code>muted</code></dfn>
7429: attribute on the <code><a href="#the-video-element">video</a></code> element controls the default
7430: state of the audio channel of the <a href="#media-resource">media resource</a>,
7431: potentially overriding user preferences.</p><div class="impl">
7432:
7433: <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
7434: agent must set the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> IDL
7435: attribute to true, overriding any user preference.</p>
7436:
7437: <p>The <dfn id="dom-media-defaultmuted" title="dom-media-defaultMuted"><code>defaultMuted</code></dfn> IDL
7438: 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>
7439:
7440: </div><p class="note">This attribute has no dynamic effect (it only
7441: controls the default state of the element).</p><div class="example">
7442:
7443: <p>This video (an advertisment) autoplays, but to avoid annoying
7444: users, it does so without sound, and allows the user to turn the
7445: sound on.</p>
7446:
7447: <pre><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></pre>
7448:
7449: </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
7450: represent a list of ranges (periods) of time.</p><pre class="idl">interface <dfn id="timeranges">TimeRanges</dfn> {
7451: readonly attribute unsigned long <a href="#dom-timeranges-length" title="dom-TimeRanges-length">length</a>;
7452: double <a href="#dom-timeranges-start" title="dom-TimeRanges-start">start</a>(in unsigned long index);
7453: double <a href="#dom-timeranges-end" title="dom-TimeRanges-end">end</a>(in unsigned long index);
7454: };</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-TimeRanges-length"><a href="#dom-timeranges-length">length</a></code></dt>
7455:
7456: <dd>
7457:
7458: <p>Returns the number of ranges in the object.</p>
7459:
7460: </dd>
7461:
7462: <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>
7463:
7464: <dd>
7465:
7466: <p>Returns the time for the start of the range with the given index.</p>
7467:
7468: <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>
7469:
7470: </dd>
7471:
7472: <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>
7473:
7474: <dd>
7475:
7476: <p>Returns the time for the end of the range with the given index.</p>
7477:
7478: <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>
7479:
7480: </dd>
7481:
7482: </dl><div class="impl">
7483:
7484: <p>The <dfn id="dom-timeranges-length" title="dom-TimeRanges-length"><code>length</code></dfn>
7485: IDL attribute must return the number of ranges represented by the object.</p>
7486:
7487: <p>The <dfn id="dom-timeranges-start" title="dom-TimeRanges-start"><code>start(<var title="">index</var>)</code></dfn> method must return the position
7488: of the start of the <var title="">index</var>th range represented by
7489: the object, in seconds measured from the start of the timeline that
7490: the object covers.</p>
7491:
7492: <p>The <dfn id="dom-timeranges-end" title="dom-TimeRanges-end"><code>end(<var title="">index</var>)</code></dfn> method must return the position
7493: of the end of the <var title="">index</var>th range represented by
7494: the object, in seconds measured from the start of the timeline that
7495: the object covers.</p>
7496:
7497: <p>These methods must raise <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exceptions
7498: if called with an <var title="">index</var> argument greater than or
7499: equal to the number of ranges represented by the object.</p>
7500:
7501: <p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said to be a
7502: <dfn id="normalized-timeranges-object">normalized <code>TimeRanges</code> object</dfn>, the ranges it
7503: represents must obey the following criteria:</p>
7504:
7505: <ul><li>The start of a range must be greater than the end of all
7506: earlier ranges.</li>
7507:
7508: <li>The start of a range must be less than the end of that same
7509: range.</li>
7510:
7511: </ul><p>In other words, the ranges in such an object are ordered, don't
7512: overlap, aren't empty, and don't touch (adjacent ranges are folded
7513: into one bigger range).</p>
7514:
1.62 mike 7515: <p>Ranges in a <code><a href="#timeranges">TimeRanges</a></code> object must be inclusive.</p>
7516:
7517: <p class="example">Thus, the end of a range would be equal to the
7518: start of a following adjacent (touching but not overlapping) range.
7519: Similarly, a range covering a whole timeline anchored at zero would
7520: have a start equal to zero and an end equal to the duration of the
7521: timeline.</p>
7522:
1.47 mike 7523: <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
7524: <a href="#media-timeline">media timeline</a>.</p>
7525:
7526: </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
7527: elements</a> as part of the processing model described above:</p><table><thead><tr><th>Event name
7528: </th><th>Interface
1.64 ! mike 7529: </th><th>Fired when...
1.47 mike 7530: </th><th>Preconditions
7531:
7532: </th></tr></thead><tbody><tr><td><dfn id="event-media-loadstart" title="event-media-loadstart"><code>loadstart</code></dfn>
7533: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7534: </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>.
7535: </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>
7536: </td></tr><tr><td><dfn id="event-media-progress" title="event-media-progress"><code>progress</code></dfn>
7537: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7538: </td><td>The user agent is fetching <a href="#media-data">media data</a>.
7539: </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>
7540: </td></tr><tr><td><dfn id="event-media-suspend" title="event-media-suspend"><code>suspend</code></dfn>
7541: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7542: </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.
7543: </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>
7544: </td></tr><tr><td><dfn id="event-media-abort" title="event-media-abort"><code>abort</code></dfn>
7545: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7546: </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.
7547: </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>.
7548: <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.
7549: </td></tr><tr><td><dfn id="event-media-error" title="event-media-error"><code>error</code></dfn>
7550: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7551: </td><td>An error occurs while fetching the <a href="#media-data">media data</a>.
7552: </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.
7553: <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.
7554: </td></tr><tr><td><dfn id="event-media-emptied" title="event-media-emptied"><code>emptied</code></dfn>
7555: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7556: </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).
7557: </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.
7558: </td></tr><tr><td><dfn id="event-media-stalled" title="event-media-stalled"><code>stalled</code></dfn>
7559: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7560: </td><td>The user agent is trying to fetch <a href="#media-data">media data</a>, but data is unexpectedly not forthcoming.
7561: </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>.
7562:
7563: </td></tr></tbody><tbody><tr><td><dfn id="event-media-loadedmetadata" title="event-media-loadedmetadata"><code>loadedmetadata</code></dfn>
7564: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7565: </td><td>The user agent has just determined the duration and dimensions of the <a href="#media-resource">media resource</a>
7566: and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>.
7567: </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.
7568: </td></tr><tr><td><dfn id="event-media-loadeddata" title="event-media-loadeddata"><code>loadeddata</code></dfn>
7569: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7570: </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.
7571: </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.
7572: </td></tr><tr><td><dfn id="event-media-canplay" title="event-media-canplay"><code>canplay</code></dfn>
7573: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7574: </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.
7575: </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.
7576: </td></tr><tr><td><dfn id="event-media-canplaythrough" title="event-media-canplaythrough"><code>canplaythrough</code></dfn>
7577: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7578: </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.
7579: </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>.
7580: </td></tr><tr><td><dfn id="event-media-playing" title="event-media-playing"><code>playing</code></dfn>
7581: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7582: </td><td>Playback is ready to start after having been paused or delayed due to lack of <a href="#media-data">media data</a>.
7583: </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
7584: 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
7585: the element is <a href="#paused-for-user-interaction">paused for user interaction</a>.
7586: </td></tr><tr><td><dfn id="event-media-waiting" title="event-media-waiting"><code>waiting</code></dfn>
7587: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7588: </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.
7589: </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.
7590: the element is newly <a href="#blocked-on-its-media-controller">blocked on its media controller</a>, or
7591: <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>.
7592: </td></tr></tbody><tbody><tr><td><dfn id="event-media-seeking" title="event-media-seeking"><code>seeking</code></dfn>
7593: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7594: </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.
7595: </td><td>
7596: </td></tr><tr><td><dfn id="event-media-seeked" title="event-media-seeked"><code>seeked</code></dfn>
7597: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7598: </td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to false.
7599: </td><td>
7600: </td></tr><tr><td><dfn id="event-media-ended" title="event-media-ended"><code>ended</code></dfn>
7601: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7602: </td><td>Playback has stopped because the end of the <a href="#media-resource">media resource</a> was reached.
7603: </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.
7604:
7605: </td></tr></tbody><tbody><tr><td><dfn id="event-media-durationchange" title="event-media-durationchange"><code>durationchange</code></dfn>
7606: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7607: </td><td>The <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute has just been updated.
7608: </td><td>
7609: </td></tr><tr><td><dfn id="event-media-timeupdate" title="event-media-timeupdate"><code>timeupdate</code></dfn>
7610: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7611: </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.
7612: </td><td>
7613: </td></tr><tr><td><dfn id="event-media-play" title="event-media-play"><code>play</code></dfn>
7614: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7615: </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.
7616: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false.
7617: </td></tr><tr><td><dfn id="event-media-pause" title="event-media-pause"><code>pause</code></dfn>
7618: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7619: </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.
7620: </td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly true.
7621: </td></tr><tr><td><dfn id="event-media-ratechange" title="event-media-ratechange"><code>ratechange</code></dfn>
7622: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7623: </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.
7624: </td><td>
7625: </td></tr><tr><td><dfn id="event-media-volumechange" title="event-media-volumechange"><code>volumechange</code></dfn>
7626: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7627: </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.
7628: </td><td>
7629: </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
7630: </th><th>Interface
1.64 ! mike 7631: </th><th>Fired when...
1.47 mike 7632:
7633: </th></tr></thead><tbody><tr><td><dfn id="event-mediacontroller-emptied" title="event-MediaController-emptied"><code>emptied</code></dfn>
7634: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7635: </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>.
7636: </td></tr><tr><td><dfn id="event-mediacontroller-loadedmetadata" title="event-MediaController-loadedmetadata"><code>loadedmetadata</code></dfn>
7637: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7638: </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.
7639: </td></tr><tr><td><dfn id="event-mediacontroller-loadeddata" title="event-MediaController-loadeddata"><code>loadeddata</code></dfn>
7640: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7641: </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.
7642: </td></tr><tr><td><dfn id="event-mediacontroller-canplay" title="event-MediaController-canplay"><code>canplay</code></dfn>
7643: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7644: </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.
7645: </td></tr><tr><td><dfn id="event-mediacontroller-canplaythrough" title="event-MediaController-canplaythrough"><code>canplaythrough</code></dfn>
7646: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7647: </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.
7648: </td></tr><tr><td><dfn id="event-mediacontroller-playing" title="event-MediaController-playing"><code>playing</code></dfn>
7649: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7650: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is no longer a <a href="#blocked-media-controller">blocked media controller</a>.
7651: </td></tr><tr><td><dfn id="event-mediacontroller-waiting" title="event-MediaController-waiting"><code>waiting</code></dfn>
7652: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7653: </td><td>The <code><a href="#mediacontroller">MediaController</a></code> is now a <a href="#blocked-media-controller">blocked media controller</a>.
7654: </td></tr><tr><td><dfn id="event-mediacontcoller-ended" title="event-MediaContcoller-ended"><code>ended</code></dfn>
7655: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7656: </td><td>All the <a href="#slaved-media-elements">slaved media elements</a> have newly <a href="#ended-playback">ended playback</a>.
7657:
7658: </td></tr></tbody><tbody><tr><td><dfn id="event-mediacontroller-durationchange" title="event-MediaController-durationchange"><code>durationchange</code></dfn>
7659: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7660: </td><td>The <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code> attribute has just been updated.
7661: </td></tr><tr><td><dfn id="event-mediacontroller-timeupdate" title="event-MediaController-timeupdate"><code>timeupdate</code></dfn>
7662: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7663: </td><td>The <a href="#media-controller-position">media controller position</a> changed.
7664: </td></tr><tr><td><dfn id="event-mediacontroller-play" title="event-MediaController-play"><code>play</code></dfn>
7665: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7666: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly false.
7667: </td></tr><tr><td><dfn id="event-mediacontroller-pause" title="event-MediaController-pause"><code>pause</code></dfn>
7668: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7669: </td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly true.
7670: </td></tr><tr><td><dfn id="event-mediacontroller-ratechange" title="event-MediaController-ratechange"><code>ratechange</code></dfn>
7671: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7672: </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.
7673: </td></tr><tr><td><dfn id="event-mediacontroller-volumechange" title="event-MediaController-volumechange"><code>volumechange</code></dfn>
7674: </td><td><code><a href="infrastructure.html#event">Event</a></code>
7675: </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.
7676: </td></tr></tbody></table><div class="impl">
7677:
7678: <h5 id="security-and-privacy-considerations"><span class="secno">4.8.10.16 </span>Security and privacy considerations</h5>
7679:
7680: <p>The main security and privacy implications of the
7681: <code><a href="#the-video-element">video</a></code> and <code><a href="#the-audio-element">audio</a></code> elements come from the
7682: ability to embed media cross-origin. There are two directions that
7683: threats can flow: from hostile content to a victim page, and from a
7684: hostile page to victim content.</p>
7685:
7686: <hr><p>If a victim page embeds hostile content, the threat is that the
7687: content might contain scripted code that attempts to interact with
7688: the <code><a href="infrastructure.html#document">Document</a></code> that embeds the content. To avoid this,
7689: user agents must ensure that there is no access from the content to
7690: the embedding page. In the case of media content that uses DOM
7691: concepts, the embedded content must be treated as if it was in its
7692: own unrelated <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>.</p>
7693:
7694: <p class="example">For instance, if an SVG animation was embedded in
7695: a <code><a href="#the-video-element">video</a></code> element, the user agent would not give it
7696: access to the DOM of the outer page. From the perspective of scripts
7697: in the SVG resource, the SVG file would appear to be in a lone
7698: top-level browsing context with no parent.</p>
7699:
7700: <hr><p>If a hostile page embeds victim content, the threat is that the
7701: embedding page could obtain information from the content that it
1.58 mike 7702: would not otherwise have access to. The API does expose some
7703: information: the existence of the media, its type, its duration, its
7704: size, and the performance characteristics of its host. Such
7705: information is already potentially problematic, but in practice the
7706: same information can more or less be obtained using the
7707: <code><a href="embedded-content-1.html#the-img-element">img</a></code> element, and so it has been deemed acceptable.</p>
7708:
7709: <p>However, significantly more sensitive information could be
7710: obtained if the user agent further exposes metadata within the
1.61 mike 7711: content such as subtitles or chapter titles. Such information is
7712: therefore only exposed if the video resource passes a CORS
7713: <a href="infrastructure.html#resource-sharing-check">resource sharing check</a>. The <code title="attr-media-crossorigin"><a href="#attr-media-crossorigin">crossorigin</a></code> attribute allows
7714: authors to control how this check is performed. <a href="references.html#refsCORS">[CORS]</a></p>
7715:
7716: <p class="example">Without this restriction, an attacker could trick
7717: a user running within a corporate network into visiting a site that
7718: attempts to load a video from a previously leaked location on the
7719: corporation's intranet. If such a video included confidential plans
7720: for a new product, then being able to read the subtitles would
7721: present a serious confidentiality breach.</p>
1.47 mike 7722:
7723: </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
7724: set-top boxes or mobile phones is often constrained by limited
7725: hardware resources in the device. For example, a device might only
7726: support three simultaneous videos. For this reason, it is a good
7727: practice to release resources held by <a href="#media-element" title="media
7728: element">media elements</a> when they are done playing, either by
7729: being very careful about removing all references to the element and
7730: allowing it to be garbage collected, or, even better, by removing
7731: the element's <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and
7732: any <code><a href="#the-source-element">source</a></code> element descendants, and invoking the
7733: 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,
7734: software, or format limitations can cause video frames to be dropped
7735: and audio to be choppy or muted.</p><div class="impl">
7736:
7737: <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>
7738:
7739: <p><i>This section is non-normative.</i></p>
7740:
7741: <p>How accurately various aspects of the <a href="#media-element">media element</a>
7742: API are implemented is considered a quality-of-implementation issue.</p>
7743:
7744: <p>For example, when implementing the <code title="attr-media-buffered">buffered</code> attribute, how precise
7745: an implementation reports the ranges that have been buffered depends
7746: on how carefully the user agent inspects the data. Since the API
7747: reports ranges as times, but the data is obtained in byte streams, a
7748: user agent receiving a variable-bit-rate stream might only be able
7749: to determine precise times by actually decoding all of the data.
7750: User agents aren't required to do this, however; they can instead
7751: return estimates (e.g. based on the average bit rate seen so far)
7752: which get revised as more information becomes available.</p>
7753:
7754: <p>As a general rule, user agents are urged to be conservative
7755: rather than optimistic. For example, it would be bad to report that
7756: everything had been buffered when it had not.</p>
7757:
7758: <p>Another quality-of-implementation issue would be playing a video
7759: backwards when the codec is designed only for forward playback (e.g.
7760: there aren't many key frames, and they are far apart, and the
7761: intervening frames only have deltas from the previous frame). User
7762: agents could do a poor job, e.g. only showing key frames; however,
7763: better implementations would do more work and thus do a better job,
7764: e.g. actually decoding parts of the video forwards, storing the
7765: complete frames, and then playing the frames backwards.</p>
7766:
7767: <p>Similarly, while implementations are allowed to drop buffered
7768: data at any time (there is no requirement that a user agent keep all
7769: the media data obtained for the lifetime of the media element), it
7770: is again a quality of implementation issue: user agents with
7771: sufficient resources to keep all the data around are encouraged to
7772: do so, as this allows for a better user experience. For example, if
7773: the user is watching a live stream, a user agent could allow the
7774: user only to view the live video; however, a better user agent would
7775: buffer everything and allow the user to seek through the earlier
7776: material, pause it, play it forwards and backwards, etc.</p>
7777:
7778: <p>When multiple tracks are synchronised with a
7779: <code><a href="#mediacontroller">MediaController</a></code>, it is possible for scripts to add and
7780: remove media elements from the <code><a href="#mediacontroller">MediaController</a></code>'s list
7781: of <a href="#slaved-media-elements">slaved media elements</a>, even while these tracks are
7782: playing. How smoothly the media plays back in such situations is
7783: another quality-of-implementation issue.</p>
7784:
7785: <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
7786: document</a> and not reinserted before the next time the
7787: <a href="webappapis.html#event-loop">event loop</a> spins, implementations that are resource
7788: constrained are encouraged to take that opportunity to release all
7789: hardware resources (like video planes, networking resources, and
7790: data buffers) used by the <a href="#media-element">media element</a>. (User agents
7791: still have to keep track of the playback position and so forth,
7792: though, in case playback is later restarted.)</p>
7793:
1.1 mike 7794: </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