You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
7791 lines
517 KiB
7791 lines
517 KiB
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
|
|
<html lang="en-US-x-Hixie" ><head><title>4.8.2 The iframe element — HTML5 </title><style type="text/css">
|
|
pre { margin-left: 2em; white-space: pre-wrap; }
|
|
h2 { margin: 3em 0 1em 0; }
|
|
h3 { margin: 2.5em 0 1em 0; }
|
|
h4 { margin: 2.5em 0 0.75em 0; }
|
|
h5, h6 { margin: 2.5em 0 1em; }
|
|
h1 + h2, h1 + h2 + h2 { margin: 0.75em 0 0.75em; }
|
|
h2 + h3, h3 + h4, h4 + h5, h5 + h6 { margin-top: 0.5em; }
|
|
p { margin: 1em 0; }
|
|
hr:not(.top) { display: block; background: none; border: none; padding: 0; margin: 2em 0; height: auto; }
|
|
dl, dd { margin-top: 0; margin-bottom: 0; }
|
|
dt { margin-top: 0.75em; margin-bottom: 0.25em; clear: left; }
|
|
dt + dt { margin-top: 0; }
|
|
dd dt { margin-top: 0.25em; margin-bottom: 0; }
|
|
dd p { margin-top: 0; }
|
|
dd dl + p { margin-top: 1em; }
|
|
dd table + p { margin-top: 1em; }
|
|
p + * > li, dd li { margin: 1em 0; }
|
|
dt, dfn { font-weight: bold; font-style: normal; }
|
|
dt dfn { font-style: italic; }
|
|
pre, code { font-size: inherit; font-family: monospace; font-variant: normal; }
|
|
pre strong { color: black; font: inherit; font-weight: bold; background: yellow; }
|
|
pre em { font-weight: bolder; font-style: normal; }
|
|
@media screen { code { color: orangered; } code :link, code :visited { color: inherit; } }
|
|
var sub { vertical-align: bottom; font-size: smaller; position: relative; top: 0.1em; }
|
|
table { border-collapse: collapse; border-style: hidden hidden none hidden; }
|
|
table thead, table tbody { border-bottom: solid; }
|
|
table tbody th:first-child { border-left: solid; }
|
|
table tbody th { text-align: left; }
|
|
table td, table th { border-left: solid; border-right: solid; border-bottom: solid thin; vertical-align: top; padding: 0.2em; }
|
|
blockquote { margin: 0 0 0 2em; border: 0; padding: 0; font-style: italic; }
|
|
|
|
.bad, .bad *:not(.XXX) { color: gray; border-color: gray; background: transparent; }
|
|
.matrix, .matrix td { border: none; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
.toc dfn, h1 dfn, h2 dfn, h3 dfn, h4 dfn, h5 dfn, h6 dfn { font: inherit; }
|
|
img.extra { float: right; }
|
|
pre.idl { border: solid thin; background: #EEEEEE; color: black; padding: 0.5em 1em; }
|
|
pre.idl :link, pre.idl :visited { color: inherit; background: transparent; }
|
|
pre.css { border: solid thin; background: #FFFFEE; color: black; padding: 0.5em 1em; }
|
|
pre.css:first-line { color: #AAAA50; }
|
|
dl.domintro { color: green; margin: 2em 0 2em 2em; padding: 0.5em 1em; border: none; background: #DDFFDD; }
|
|
hr + dl.domintro, div.impl + dl.domintro { margin-top: 2.5em; margin-bottom: 1.5em; }
|
|
dl.domintro dt, dl.domintro dt * { color: black; text-decoration: none; }
|
|
dl.domintro dd { margin: 0.5em 0 1em 2em; padding: 0; }
|
|
dl.domintro dd p { margin: 0.5em 0; }
|
|
dl.switch { padding-left: 2em; }
|
|
dl.switch > dt { text-indent: -1.5em; }
|
|
dl.switch > dt:before { content: '\21AA'; padding: 0 0.5em 0 0; display: inline-block; width: 1em; text-align: right; line-height: 0.5em; }
|
|
dl.triple { padding: 0 0 0 1em; }
|
|
dl.triple dt, dl.triple dd { margin: 0; display: inline }
|
|
dl.triple dt:after { content: ':'; }
|
|
dl.triple dd:after { content: '\A'; white-space: pre; }
|
|
.diff-old { text-decoration: line-through; color: silver; background: transparent; }
|
|
.diff-chg, .diff-new { text-decoration: underline; color: green; background: transparent; }
|
|
a .diff-new { border-bottom: 1px blue solid; }
|
|
|
|
h2 { page-break-before: always; }
|
|
h1, h2, h3, h4, h5, h6 { page-break-after: avoid; }
|
|
h1 + h2, hr + h2.no-toc { page-break-before: auto; }
|
|
|
|
p > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]),
|
|
li > span:not([title=""]):not([class="XXX"]):not([class="impl"]):not([class="note"]), { border-bottom: solid #9999CC; }
|
|
|
|
div.head { margin: 0 0 1em; padding: 1em 0 0 0; }
|
|
div.head p { margin: 0; }
|
|
div.head h1 { margin: 0; }
|
|
div.head .logo { float: right; margin: 0 1em; }
|
|
div.head .logo img { border: none } /* remove border from top image */
|
|
div.head dl { margin: 1em 0; }
|
|
div.head p.copyright, div.head p.alt { font-size: x-small; font-style: oblique; margin: 0; }
|
|
|
|
body > .toc > li { margin-top: 1em; margin-bottom: 1em; }
|
|
body > .toc.brief > li { margin-top: 0.35em; margin-bottom: 0.35em; }
|
|
body > .toc > li > * { margin-bottom: 0.5em; }
|
|
body > .toc > li > * > li > * { margin-bottom: 0.25em; }
|
|
.toc, .toc li { list-style: none; }
|
|
|
|
.brief { margin-top: 1em; margin-bottom: 1em; line-height: 1.1; }
|
|
.brief li { margin: 0; padding: 0; }
|
|
.brief li p { margin: 0; padding: 0; }
|
|
|
|
.category-list { margin-top: -0.75em; margin-bottom: 1em; line-height: 1.5; }
|
|
.category-list::before { content: '\21D2\A0'; font-size: 1.2em; font-weight: 900; }
|
|
.category-list li { display: inline; }
|
|
.category-list li:not(:last-child)::after { content: ', '; }
|
|
.category-list li > span, .category-list li > a { text-transform: lowercase; }
|
|
.category-list li * { text-transform: none; } /* don't affect <code> nested in <a> */
|
|
|
|
.XXX { color: #E50000; background: white; border: solid red; padding: 0.5em; margin: 1em 0; }
|
|
.XXX > :first-child { margin-top: 0; }
|
|
p .XXX { line-height: 3em; }
|
|
.annotation { border: solid thin black; background: #0C479D; color: white; position: relative; margin: 8px 0 20px 0; }
|
|
.annotation:before { position: absolute; left: 0; top: 0; width: 100%; height: 100%; margin: 6px -6px -6px 6px; background: #333333; z-index: -1; content: ''; }
|
|
.annotation :link, .annotation :visited { color: inherit; }
|
|
.annotation :link:hover, .annotation :visited:hover { background: transparent; }
|
|
.annotation span { border: none ! important; }
|
|
.note { color: green; background: transparent; font-family: sans-serif; }
|
|
.warning { color: red; background: transparent; }
|
|
.note, .warning { font-weight: bolder; font-style: italic; }
|
|
p.note, div.note { padding: 0.5em 2em; }
|
|
span.note { padding: 0 2em; }
|
|
.note p:first-child, .warning p:first-child { margin-top: 0; }
|
|
.note p:last-child, .warning p:last-child { margin-bottom: 0; }
|
|
.warning:before { font-style: normal; }
|
|
p.note:before { content: 'Note: '; }
|
|
p.warning:before { content: '\26A0 Warning! '; }
|
|
|
|
.bookkeeping:before { display: block; content: 'Bookkeeping details'; font-weight: bolder; font-style: italic; }
|
|
.bookkeeping { font-size: 0.8em; margin: 2em 0; }
|
|
.bookkeeping p { margin: 0.5em 2em; display: list-item; list-style: square; }
|
|
.bookkeeping dt { margin: 0.5em 2em 0; }
|
|
.bookkeeping dd { margin: 0 3em 0.5em; }
|
|
|
|
h4 { position: relative; z-index: 3; }
|
|
h4 + .element, h4 + div + .element { margin-top: -2.5em; padding-top: 2em; }
|
|
.element {
|
|
background: #EEEEFF;
|
|
color: black;
|
|
margin: 0 0 1em 0.15em;
|
|
padding: 0 1em 0.25em 0.75em;
|
|
border-left: solid #9999FF 0.25em;
|
|
position: relative;
|
|
z-index: 1;
|
|
}
|
|
.element:before {
|
|
position: absolute;
|
|
z-index: 2;
|
|
top: 0;
|
|
left: -1.15em;
|
|
height: 2em;
|
|
width: 0.9em;
|
|
background: #EEEEFF;
|
|
content: ' ';
|
|
border-style: none none solid solid;
|
|
border-color: #9999FF;
|
|
border-width: 0.25em;
|
|
}
|
|
|
|
.example { display: block; color: #222222; background: #FCFCFC; border-left: double; margin-left: 2em; padding-left: 1em; }
|
|
td > .example:only-child { margin: 0 0 0 0.1em; }
|
|
|
|
ul.domTree, ul.domTree ul { padding: 0 0 0 1em; margin: 0; }
|
|
ul.domTree li { padding: 0; margin: 0; list-style: none; position: relative; }
|
|
ul.domTree li li { list-style: none; }
|
|
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; }
|
|
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; }
|
|
ul.domTree span { font-style: italic; font-family: serif; }
|
|
ul.domTree .t1 code { color: purple; font-weight: bold; }
|
|
ul.domTree .t2 { font-style: normal; font-family: monospace; }
|
|
ul.domTree .t2 .name { color: black; font-weight: bold; }
|
|
ul.domTree .t2 .value { color: blue; font-weight: normal; }
|
|
ul.domTree .t3 code, .domTree .t4 code, .domTree .t5 code { color: gray; }
|
|
ul.domTree .t7 code, .domTree .t8 code { color: green; }
|
|
ul.domTree .t10 code { color: teal; }
|
|
|
|
body.dfnEnabled dfn { cursor: pointer; }
|
|
.dfnPanel {
|
|
display: inline;
|
|
position: absolute;
|
|
z-index: 10;
|
|
height: auto;
|
|
width: auto;
|
|
padding: 0.5em 0.75em;
|
|
font: small sans-serif, Droid Sans Fallback;
|
|
background: #DDDDDD;
|
|
color: black;
|
|
border: outset 0.2em;
|
|
}
|
|
.dfnPanel * { margin: 0; padding: 0; font: inherit; text-indent: 0; }
|
|
.dfnPanel :link, .dfnPanel :visited { color: black; }
|
|
.dfnPanel p { font-weight: bolder; }
|
|
.dfnPanel * + p { margin-top: 0.25em; }
|
|
.dfnPanel li { list-style-position: inside; }
|
|
|
|
#configUI { position: absolute; z-index: 20; top: 10em; right: 1em; width: 11em; font-size: small; }
|
|
#configUI p { margin: 0.5em 0; padding: 0.3em; background: #EEEEEE; color: black; border: inset thin; }
|
|
#configUI p label { display: block; }
|
|
#configUI #updateUI, #configUI .loginUI { text-align: center; }
|
|
#configUI input[type=button] { display: block; margin: auto; }
|
|
|
|
fieldset { margin: 1em; padding: 0.5em 1em; }
|
|
fieldset > legend + * { margin-top: 0; }
|
|
fieldset > :last-child { margin-bottom: 0; }
|
|
fieldset p { margin: 0.5em 0; }
|
|
|
|
.stability {
|
|
position: fixed;
|
|
bottom: 0;
|
|
left: 0; right: 0;
|
|
margin: 0 auto 0 auto !important;
|
|
z-index: 1000;
|
|
width: 50%;
|
|
background: maroon; color: yellow;
|
|
-webkit-border-radius: 1em 1em 0 0;
|
|
-moz-border-radius: 1em 1em 0 0;
|
|
border-radius: 1em 1em 0 0;
|
|
-moz-box-shadow: 0 0 1em #500;
|
|
-webkit-box-shadow: 0 0 1em #500;
|
|
box-shadow: 0 0 1em red;
|
|
padding: 0.5em 1em;
|
|
text-align: center;
|
|
}
|
|
.stability strong {
|
|
display: block;
|
|
}
|
|
.stability input {
|
|
appearance: none; margin: 0; border: 0; padding: 0.25em 0.5em; background: transparent; color: black;
|
|
position: absolute; top: -0.5em; right: 0; font: 1.25em sans-serif; text-align: center;
|
|
}
|
|
.stability input:hover {
|
|
color: white;
|
|
text-shadow: 0 0 2px black;
|
|
}
|
|
.stability input:active {
|
|
padding: 0.3em 0.45em 0.2em 0.55em;
|
|
}
|
|
.stability :link, .stability :visited,
|
|
.stability :link:hover, .stability :visited:hover {
|
|
background: transparent;
|
|
color: white;
|
|
}
|
|
|
|
</style><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"><link href="http://www.w3.org/StyleSheets/TR/W3C-WD" rel="stylesheet" type="text/css"><style type="text/css">
|
|
|
|
.applies thead th > * { display: block; }
|
|
.applies thead code { display: block; }
|
|
.applies tbody th { whitespace: nowrap; }
|
|
.applies td { text-align: center; }
|
|
.applies .yes { background: yellow; }
|
|
|
|
.matrix, .matrix td { border: hidden; text-align: right; }
|
|
.matrix { margin-left: 2em; }
|
|
|
|
.dice-example { border-collapse: collapse; border-style: hidden solid solid hidden; border-width: thin; margin-left: 3em; }
|
|
.dice-example caption { width: 30em; font-size: smaller; font-style: italic; padding: 0.75em 0; text-align: left; }
|
|
.dice-example td, .dice-example th { border: solid thin; width: 1.35em; height: 1.05em; text-align: center; padding: 0; }
|
|
|
|
td.eg { border-width: thin; text-align: center; }
|
|
|
|
#table-example-1 { border: solid thin; border-collapse: collapse; margin-left: 3em; }
|
|
#table-example-1 * { font-family: "Essays1743", serif; line-height: 1.01em; }
|
|
#table-example-1 caption { padding-bottom: 0.5em; }
|
|
#table-example-1 thead, #table-example-1 tbody { border: none; }
|
|
#table-example-1 th, #table-example-1 td { border: solid thin; }
|
|
#table-example-1 th { font-weight: normal; }
|
|
#table-example-1 td { border-style: none solid; vertical-align: top; }
|
|
#table-example-1 th { padding: 0.5em; vertical-align: middle; text-align: center; }
|
|
#table-example-1 tbody tr:first-child td { padding-top: 0.5em; }
|
|
#table-example-1 tbody tr:last-child td { padding-bottom: 1.5em; }
|
|
#table-example-1 tbody td:first-child { padding-left: 2.5em; padding-right: 0; width: 9em; }
|
|
#table-example-1 tbody td:first-child::after { content: leader(". "); }
|
|
#table-example-1 tbody td { padding-left: 2em; padding-right: 2em; }
|
|
#table-example-1 tbody td:first-child + td { width: 10em; }
|
|
#table-example-1 tbody td:first-child + td ~ td { width: 2.5em; }
|
|
#table-example-1 tbody td:first-child + td + td + td ~ td { width: 1.25em; }
|
|
|
|
.apple-table-examples { border: none; border-collapse: separate; border-spacing: 1.5em 0em; width: 40em; margin-left: 3em; }
|
|
.apple-table-examples * { font-family: "Times", serif; }
|
|
.apple-table-examples td, .apple-table-examples th { border: none; white-space: nowrap; padding-top: 0; padding-bottom: 0; }
|
|
.apple-table-examples tbody th:first-child { border-left: none; width: 100%; }
|
|
.apple-table-examples thead th:first-child ~ th { font-size: smaller; font-weight: bolder; border-bottom: solid 2px; text-align: center; }
|
|
.apple-table-examples tbody th::after, .apple-table-examples tfoot th::after { content: leader(". ") }
|
|
.apple-table-examples tbody th, .apple-table-examples tfoot th { font: inherit; text-align: left; }
|
|
.apple-table-examples td { text-align: right; vertical-align: top; }
|
|
.apple-table-examples.e1 tbody tr:last-child td { border-bottom: solid 1px; }
|
|
.apple-table-examples.e1 tbody + tbody tr:last-child td { border-bottom: double 3px; }
|
|
.apple-table-examples.e2 th[scope=row] { padding-left: 1em; }
|
|
.apple-table-examples sup { line-height: 0; }
|
|
|
|
.details-example img { vertical-align: top; }
|
|
|
|
#base64-table {
|
|
white-space: nowrap;
|
|
font-size: 0.6em;
|
|
column-width: 6em;
|
|
column-count: 5;
|
|
column-gap: 1em;
|
|
-moz-column-width: 6em;
|
|
-moz-column-count: 5;
|
|
-moz-column-gap: 1em;
|
|
-webkit-column-width: 6em;
|
|
-webkit-column-count: 5;
|
|
-webkit-column-gap: 1em;
|
|
}
|
|
#base64-table thead { display: none; }
|
|
#base64-table * { border: none; }
|
|
#base64-table tbody td:first-child:after { content: ':'; }
|
|
#base64-table tbody td:last-child { text-align: right; }
|
|
|
|
#named-character-references-table {
|
|
white-space: nowrap;
|
|
font-size: 0.6em;
|
|
column-width: 30em;
|
|
column-gap: 1em;
|
|
-moz-column-width: 30em;
|
|
-moz-column-gap: 1em;
|
|
-webkit-column-width: 30em;
|
|
-webkit-column-gap: 1em;
|
|
}
|
|
#named-character-references-table > table > tbody > tr > td:first-child + td,
|
|
#named-character-references-table > table > tbody > tr > td:last-child { text-align: center; }
|
|
#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; }
|
|
#named-character-references-table > table > tbody > tr#entity-CounterClockwiseContourIntegral > td:first-child { font-size: 0.5em; }
|
|
|
|
.glyph.control { color: red; }
|
|
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-weight: bold;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Bold.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-style: italic;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-Italic.ttf');
|
|
}
|
|
@font-face {
|
|
font-family: 'Essays1743';
|
|
font-style: italic;
|
|
font-weight: bold;
|
|
src: url('http://www.whatwg.org/specs/web-apps/current-work/fonts/Essays1743-BoldItalic.ttf');
|
|
}
|
|
|
|
</style><style type="text/css">
|
|
.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; }
|
|
</style><script type="text/javascript">
|
|
function getCookie(name) {
|
|
var params = location.search.substr(1).split("&");
|
|
for (var index = 0; index < params.length; index++) {
|
|
if (params[index] == name)
|
|
return "1";
|
|
var data = params[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
var cookies = document.cookie.split("; ");
|
|
for (var index = 0; index < cookies.length; index++) {
|
|
var data = cookies[index].split("=");
|
|
if (data[0] == name)
|
|
return unescape(data[1]);
|
|
}
|
|
return null;
|
|
}
|
|
</script>
|
|
<script src="link-fixup.js" type="text/javascript"></script>
|
|
<link href="style.css" rel="stylesheet"><link href="embedded-content-1.html" title="4.8 Embedded content" rel="prev">
|
|
<link href="spec.html#contents" title="Table of contents" rel="index">
|
|
<link href="the-canvas-element.html" title="4.8.11 The canvas element" rel="next">
|
|
</head><body><div class="head" id="head">
|
|
<div id="multipage-common">
|
|
<p class="stability" id="wip"><strong>This is a work in
|
|
progress!</strong> For the latest updates from the HTML WG, possibly
|
|
including important bug fixes, please look at the <a href="http://dev.w3.org/html5/spec/Overview.html">editor's draft</a> instead.
|
|
There may also be a more
|
|
<a href="http://www.w3.org/TR/html5">up-to-date Working Draft</a>
|
|
with changes based on resolution of Last Call issues.
|
|
<input onclick="closeWarning(this.parentNode)" type="button" value="╳⃝"></p>
|
|
<script type="text/javascript">
|
|
function closeWarning(element) {
|
|
element.parentNode.removeChild(element);
|
|
var date = new Date();
|
|
date.setDate(date.getDate()+4);
|
|
document.cookie = 'hide-obsolescence-warning=1; expires=' + date.toGMTString();
|
|
}
|
|
if (getCookie('hide-obsolescence-warning') == '1')
|
|
setTimeout(function () { document.getElementById('wip').parentNode.removeChild(document.getElementById('wip')); }, 2000);
|
|
</script></div>
|
|
|
|
<p><a href="http://www.w3.org/"><img alt="W3C" height="48" src="http://www.w3.org/Icons/w3c_home" width="72"></a></p>
|
|
|
|
<h1>HTML5</h1>
|
|
</div><div>
|
|
<a href="embedded-content-1.html" class="prev">4.8 Embedded content</a> –
|
|
<a href="spec.html#contents">Table of contents</a> –
|
|
<a href="the-canvas-element.html" class="next">4.8.11 The canvas element</a>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
|
|
<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>
|
|
<dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
|
|
<dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
|
|
<dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
|
|
<dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
|
|
<dt>Content model:</dt>
|
|
<dd>Text that conforms to <a href="#iframe-content-model">the requirements given in the prose</a>.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code></dd>
|
|
<dd><code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code></dd>
|
|
<dd><code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code></dd>
|
|
<dd><code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code></dd>
|
|
<dd><code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code></dd>
|
|
<dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
|
|
<dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmliframeelement">HTMLIFrameElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
attribute DOMString <a href="#dom-iframe-src" title="dom-iframe-src">src</a>;
|
|
attribute DOMString <a href="#dom-iframe-srcdoc" title="dom-iframe-srcdoc">srcdoc</a>;
|
|
attribute DOMString <a href="#dom-iframe-name" title="dom-iframe-name">name</a>;
|
|
[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>;
|
|
attribute boolean <a href="#dom-iframe-seamless" title="dom-iframe-seamless">seamless</a>;
|
|
attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
|
|
attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
|
|
readonly attribute Document <a href="#dom-iframe-contentdocument" title="dom-iframe-contentDocument">contentDocument</a>;
|
|
readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-iframe-contentwindow" title="dom-iframe-contentWindow">contentWindow</a>;
|
|
};</pre>
|
|
</dd>
|
|
</dl><p>The <code><a href="#the-iframe-element">iframe</a></code> element <a href="rendering.html#represents">represents</a> a
|
|
<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
|
|
gives the address of a page that the <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a> is to contain. The attribute, if present, must be a
|
|
<a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
|
|
spaces</a>.</p><p>The <dfn id="attr-iframe-srcdoc" title="attr-iframe-srcdoc"><code>srcdoc</code></dfn>
|
|
attribute gives the content of the page that the <a href="browsers.html#nested-browsing-context">nested
|
|
browsing context</a> is to contain. The value of the attribute is
|
|
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>,
|
|
the attribute, if present, must have a value using <a href="syntax.html#syntax">the HTML
|
|
syntax</a> that consists of the following syntactic components,
|
|
in the given order:</p><ol><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
|
|
<a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
|
|
|
|
<li>Optionally, a <a href="syntax.html#syntax-doctype" title="syntax-doctype">DOCTYPE</a>.
|
|
|
|
</li><li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
|
|
<a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
|
|
|
|
<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>
|
|
|
|
<li>Any number of <a href="syntax.html#syntax-comments" title="syntax-comments">comments</a> and
|
|
<a href="common-microsyntaxes.html#space-character" title="space character">space characters</a>.</li>
|
|
|
|
</ol><p>For <code><a href="#the-iframe-element">iframe</a></code> elements in <a href="dom.html#xml-documents">XML documents</a>,
|
|
the attribute, if present, must have a value that matches the
|
|
production labeled <code><a href="infrastructure.html#document">document</a></code> in the XML
|
|
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
|
|
<code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute are both
|
|
specified together, the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code>
|
|
attribute takes priority. This allows authors to provide a fallback
|
|
<a href="urls.html#url">URL</a> for legacy user agents that do not support the
|
|
<code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute.</p><div class="impl">
|
|
|
|
<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
|
|
an element into a document">inserted into a document</a>, the
|
|
user agent must create a <a href="browsers.html#nested-browsing-context">nested browsing context</a>, and
|
|
then <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> for the
|
|
first time.</p>
|
|
|
|
<p>Whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a <a href="browsers.html#nested-browsing-context">nested
|
|
browsing context</a> has its <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute set, changed, or
|
|
removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
|
|
attributes</a>.</p>
|
|
|
|
<p>Similarly, whenever an <code><a href="#the-iframe-element">iframe</a></code> element with a
|
|
<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
|
|
<code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute set, changed, or
|
|
removed, the user agent must <a href="#process-the-iframe-attributes">process the <code>iframe</code>
|
|
attributes</a>.</p>
|
|
<p>When the user agent is to <dfn id="process-the-iframe-attributes">process the <code>iframe</code>
|
|
attributes</dfn>, it must run the first appropriate steps from the
|
|
following list:</p>
|
|
|
|
<dl class="switch"><dt>If the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute
|
|
is specified</dt>
|
|
|
|
<dd><p><a href="history.html#navigate">Navigate</a> the element's
|
|
<a href="browsers.html#browsing-context">browsing context</a> to a resource whose
|
|
<a href="fetching-resources.html#content-type">Content-Type</a> is <code><a href="iana.html#text-html">text/html</a></code>, whose
|
|
<a href="urls.html#url">URL</a> is <code><a href="urls.html#about:srcdoc">about:srcdoc</a></code>, and whose data
|
|
consists of the value of the attribute. The resulting
|
|
<code><a href="infrastructure.html#document">Document</a></code> must be considered <a href="#an-iframe-srcdoc-document">an
|
|
<code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
|
|
document</a>.</p></dd>
|
|
|
|
<dt>If the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code>
|
|
attribute is specified but the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute is not</dt>
|
|
|
|
<dd>
|
|
|
|
<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,
|
|
jump to the <i title="">empty</i> step below.</p></li>
|
|
|
|
<li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the value of
|
|
the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute, relative
|
|
to the <code><a href="#the-iframe-element">iframe</a></code> element.</p></li>
|
|
|
|
<li><p>If that is not successful, then jump to the <i title="">empty</i> step below.</p></li>
|
|
|
|
<li><p>If the resulting <a href="urls.html#absolute-url">absolute URL</a> is an
|
|
<a href="infrastructure.html#ascii-case-insensitive">ASCII case-insensitive</a> match for the string
|
|
"<code><a href="fetching-resources.html#about:blank">about:blank</a></code>", and the user agent is processing this
|
|
<code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first time, then jump to
|
|
the <i title="">empty</i> step below. (In cases other than the
|
|
first time, <code><a href="fetching-resources.html#about:blank">about:blank</a></code> is loaded
|
|
normally.)</p></li>
|
|
|
|
<li><p><a href="history.html#navigate">Navigate</a> the element's
|
|
<a href="browsers.html#browsing-context">browsing context</a> to the resulting <a href="urls.html#absolute-url">absolute
|
|
URL</a>.</p></li>
|
|
|
|
</ol><p><i>Empty</i>: When the steps above require the user agent to
|
|
jump to the <i title="">empty</i> step, if the user agent is
|
|
processing this <code><a href="#the-iframe-element">iframe</a></code>'s attributes for the first
|
|
time, then 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 event</a> named <code title="event-load">load</code> at the <code><a href="#the-iframe-element">iframe</a></code>
|
|
element. (After jumping to this step, the above steps are not
|
|
resumed.)</p>
|
|
|
|
</dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<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>
|
|
named <code title="event-load">load</code> at the
|
|
<code><a href="#the-iframe-element">iframe</a></code> element.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>Any <a href="history.html#navigate" title="navigate">navigation</a> required of the user
|
|
agent in the <a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a>
|
|
algorithm must be completed with the <code><a href="#the-iframe-element">iframe</a></code> element's
|
|
document's <a href="browsers.html#browsing-context">browsing context</a> as the <a href="history.html#source-browsing-context">source
|
|
browsing context</a>.</p>
|
|
|
|
<p>Furthermore, if the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="history.html#session-history">session
|
|
history</a> contained only one <code><a href="infrastructure.html#document">Document</a></code> when the
|
|
<a href="#process-the-iframe-attributes">process the <code>iframe</code> attributes</a> algorithm
|
|
was invoked, and that was the <code><a href="fetching-resources.html#about:blank">about:blank</a></code>
|
|
<code><a href="infrastructure.html#document">Document</a></code> created when the <a href="browsers.html#browsing-context">browsing context</a>
|
|
was created, then any <a href="history.html#navigate" title="navigate">navigation</a>
|
|
required of the user agent in that algorithm must be completed with
|
|
<a href="history.html#replacement-enabled">replacement enabled</a>.</p>
|
|
</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
|
|
the <code title="attr-iframe-src"><a href="#attr-iframe-src">src</a></code> attribute is either
|
|
also not set or set but its value cannot be <a href="urls.html#resolve-a-url" title="resolve a
|
|
url">resolved</a>, the browsing context will remain at the
|
|
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>
|
|
away from this page, the <code><a href="#the-iframe-element">iframe</a></code>'s corresponding
|
|
<code><a href="browsers.html#windowproxy">WindowProxy</a></code> object will proxy new <code><a href="browsers.html#window">Window</a></code>
|
|
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">
|
|
|
|
<div class="note">
|
|
|
|
<p><a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a document">Removing</a>
|
|
an <code><a href="#the-iframe-element">iframe</a></code> from a <code><a href="infrastructure.html#document">Document</a></code> does not cause
|
|
its <a href="browsers.html#browsing-context">browsing context</a> to be discarded. Indeed, an
|
|
<code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> can survive its
|
|
original parent <code><a href="infrastructure.html#document">Document</a></code> if its <code><a href="#the-iframe-element">iframe</a></code> is
|
|
moved to another <code><a href="infrastructure.html#document">Document</a></code>.</p>
|
|
|
|
<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
|
|
<code><a href="infrastructure.html#document">Document</a></code> and is then subsequently garbage collected,
|
|
this will likely mean (in the absence of other references) that the
|
|
<a href="browsers.html#child-browsing-context">child browsing context</a>'s <code><a href="browsers.html#windowproxy">WindowProxy</a></code>
|
|
object will become eligble for garbage collection, which will then
|
|
lead to that <a href="browsers.html#browsing-context">browsing context</a> being <a href="browsers.html#a-browsing-context-is-discarded" title="a
|
|
browsing context is discarded">discarded</a>, which will then
|
|
lead to its <code><a href="infrastructure.html#document">Document</a></code> being <a href="browsers.html#discard-a-document" title="discard a
|
|
document">discarded</a> also. This happens without notice to any
|
|
scripts running in that <code><a href="infrastructure.html#document">Document</a></code>; for example, no
|
|
<code title="event-unload">unload</code> events are fired (the
|
|
"<a href="history.html#unload-a-document">unload a document</a>" steps are not run).</p>
|
|
|
|
</div>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Here a blog uses the <code title="attr-iframe-srcdoc"><a href="#attr-iframe-srcdoc">srcdoc</a></code> attribute in conjunction
|
|
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
|
|
below to provide users of user agents that support this feature
|
|
with an extra layer of protection from script injection in the blog
|
|
post comments:</p>
|
|
|
|
<pre><article>
|
|
<h1>I got my own magazine!</h1>
|
|
<p>After much effort, I've finally found a publisher, and so now I
|
|
have my own magazine! Isn't that awesome?! The first issue will come
|
|
out in September, and we have articles about getting food, and about
|
|
getting in boxes, it's going to be great!</p>
|
|
<footer>
|
|
<p>Written by <a href="/users/cap">cap</a>.
|
|
<time pubdate>2009-08-21T23:32Z</time></p>
|
|
</footer>
|
|
<article>
|
|
<footer> At <time pubdate>2009-08-21T23:35Z</time>, <a href="/users/ch">ch</a> writes: </footer>
|
|
<iframe seamless sandbox srcdoc="<p>did you get a cover picture yet?"></iframe>
|
|
</article>
|
|
<article>
|
|
<footer> At <time pubdate>2009-08-21T23:44Z</time>, <a href="/users/cap">cap</a> writes: </footer>
|
|
<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>
|
|
</article>
|
|
<article>
|
|
<footer> At <time pubdate>2009-08-21T23:58Z</time>, <a href="/users/ch">ch</a> writes: </footer>
|
|
<iframe seamless sandbox srcdoc="<p>hey that's earl's table.
|
|
<p>you should get earl&amp;amp;me on the next cover."></iframe>
|
|
</article></pre>
|
|
|
|
<p>Notice the way that quotes have to be escaped (otherwise the
|
|
<code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute would
|
|
end prematurely), and the way raw ampersands (e.g. in URLs or in
|
|
prose) mentioned in the sandboxed content have to be
|
|
<em>doubly</em> escaped — once so that the ampersand is
|
|
preserved when originally parsing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and once more
|
|
to prevent the ampersand from being misinterpreted when parsing the
|
|
sandboxed content.</p>
|
|
|
|
</div><p class="note">In <a href="syntax.html#syntax">the HTML syntax</a>, authors need only
|
|
remember to use U+0022 QUOTATION MARK characters (") to wrap the
|
|
attribute contents and then to escape all U+0022 QUOTATION MARK (")
|
|
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
|
|
embedding of content.</p><p class="note">Due to restrictions of <span>the XML syntax</span>,
|
|
in XML the U+003C LESS-THAN SIGN character (<) needs to be
|
|
escaped as well. In order to prevent <a href="http://www.w3.org/TR/REC-xml/#AVNormalize">attribute-value
|
|
normalization</a>, some of XML's whitespace characters —
|
|
specifically U+0009 CHARACTER TABULATION (tab), U+000A LINE FEED
|
|
(LF), and U+000D CARRIAGE RETURN (CR) — also need to be
|
|
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>
|
|
attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
|
|
name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
|
|
browsing context</a>. <span class="impl">When the browsing
|
|
context is created, if the attribute is present, the <a href="browsers.html#browsing-context-name">browsing
|
|
context name</a> must be set to the value of this attribute;
|
|
otherwise, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set to the
|
|
empty string.</span></p><div class="impl">
|
|
|
|
<p>Whenever the <code title="attr-iframe-name"><a href="#attr-iframe-name">name</a></code> attribute
|
|
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
|
|
value. If the attribute is removed, the <a href="browsers.html#browsing-context-name">browsing context
|
|
name</a> must be set to the empty string.</p>
|
|
|
|
<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
|
|
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
|
|
a simple event</a> named <code title="event-load">load</code> at
|
|
the <code><a href="#the-iframe-element">iframe</a></code> element. When content whose <a href="urls.html#url">URL</a>
|
|
has the <a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code>
|
|
element's <code><a href="infrastructure.html#document">Document</a></code> fails to load (e.g. due to a DNS
|
|
error, network error, or if the server returned a 4xx or 5xx status
|
|
code <a href="fetching-resources.html#concept-http-equivalent-codes" title="concept-http-equivalent-codes">or
|
|
equivalent</a>), then 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 event</a> named <code title="event-error">error</code> at the element instead. (This event
|
|
does not fire for <a href="parsing.html#parse-error" title="parse error">parse errors</a>,
|
|
script errors, or any errors for cross-origin resources.)</p>
|
|
|
|
<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
|
|
task source</a>.</p>
|
|
|
|
<p class="note">A <code title="event-load">load</code> event is also
|
|
fired at the <code><a href="#the-iframe-element">iframe</a></code> element when it is created if no
|
|
other data is loaded in it.</p>
|
|
|
|
<p>When there is an <a href="dom.html#active-parser">active parser</a> in the
|
|
<code><a href="#the-iframe-element">iframe</a></code>, and when anything in the <code><a href="#the-iframe-element">iframe</a></code> is
|
|
<a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the load event</a> of
|
|
the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#browsing-context">browsing context</a>'s
|
|
<a href="browsers.html#active-document">active document</a>, the <code><a href="#the-iframe-element">iframe</a></code> must
|
|
<a href="the-end.html#delay-the-load-event">delay the load event</a> of its document.</p>
|
|
|
|
<p class="note">If, during the handling of the <code title="event-load">load</code> event, the <a href="browsers.html#browsing-context">browsing
|
|
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
|
|
load event</a>.</p>
|
|
|
|
</div><hr><p>The <dfn id="attr-iframe-sandbox" title="attr-iframe-sandbox"><code>sandbox</code></dfn>
|
|
attribute, when specified, enables a set of extra restrictions on
|
|
any content hosted by the <code><a href="#the-iframe-element">iframe</a></code>. Its value must be an
|
|
<a href="common-microsyntaxes.html#unordered-set-of-unique-space-separated-tokens">unordered set of unique space-separated tokens</a> that are
|
|
<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>,
|
|
<code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>,
|
|
<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>. When
|
|
the attribute is set, the content is treated as being from a unique
|
|
<a href="origin-0.html#origin">origin</a>, forms and scripts are disabled, links are
|
|
prevented from targeting other <a href="browsers.html#browsing-context" title="browsing
|
|
context">browsing contexts</a>, and plugins are disabled. The
|
|
<code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
|
|
keyword allows the content to be treated as being from the same
|
|
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>
|
|
keyword allows the content to <a href="history.html#navigate">navigate</a> its
|
|
<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>
|
|
keywords re-enable forms and scripts respectively (though scripts
|
|
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
|
|
<code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
|
|
keywords together when the embedded page has the <a href="origin-0.html#same-origin">same
|
|
origin</a> as the page containing the <code><a href="#the-iframe-element">iframe</a></code> allows
|
|
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
|
|
an attacker can convince the user to just visit the hostile content
|
|
directly, rather than in the <code><a href="#the-iframe-element">iframe</a></code>. To limit the
|
|
damage that can be caused by hostile HTML content, it should be
|
|
served using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME type.</p><div class="impl">
|
|
|
|
|
|
<p>While the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
|
|
attribute is specified, the <code><a href="#the-iframe-element">iframe</a></code> element's
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a> must have the flags given in
|
|
the following list set. In addition, any browsing contexts <a href="browsers.html#nested-browsing-context" title="nested browsing context">nested</a> within an
|
|
<code><a href="#the-iframe-element">iframe</a></code>, either directly or indirectly, must have all
|
|
the flags set on them as were set on the <code><a href="#the-iframe-element">iframe</a></code>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> when the
|
|
<code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code> was created.</p>
|
|
|
|
<dl><dt>The <dfn id="sandboxed-navigation-browsing-context-flag">sandboxed navigation browsing context flag</dfn></dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag <a href="history.html#sandboxLinks">prevents content from
|
|
navigating browsing contexts other than the sandboxed browsing
|
|
context itself</a> (or browsing contexts further nested inside
|
|
it), and the <a href="browsers.html#top-level-browsing-context">top-level browsing context</a> (which is
|
|
protected by the <a href="#sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing
|
|
context flag</a> defined next).</p>
|
|
|
|
<p>This flag also <a href="browsers.html#sandboxWindowOpen">prevents content
|
|
from creating new auxiliary browsing contexts</a>, e.g. using the
|
|
<code title="attr-hyperlink-target"><a href="links.html#attr-hyperlink-target">target</a></code> attribute or the
|
|
<code title="dom-open"><a href="browsers.html#dom-open">window.open()</a></code> method.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-top-level-navigation-browsing-context-flag">sandboxed top-level navigation browsing context
|
|
flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
|
|
<a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
|
|
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>
|
|
keyword set</dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag <a href="history.html#sandboxLinks">prevents content from
|
|
navigating their <span>top-level browsing context</span></a>.</p>
|
|
|
|
<p>When the <code title="attr-iframe-sandbox-allow-top-navigation"><a href="#attr-iframe-sandbox-allow-top-navigation">allow-top-navigation</a></code>
|
|
is set, content can navigate its <a href="browsers.html#top-level-browsing-context">top-level browsing
|
|
context</a>, but other <a href="browsers.html#browsing-context" title="browsing context">browsing
|
|
contexts</a> are still protected by the <a href="#sandboxed-navigation-browsing-context-flag">sandboxed
|
|
navigation browsing context flag</a> defined above.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</dfn></dt>
|
|
|
|
<dd>
|
|
|
|
<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>,
|
|
<a href="obsolete.html#sandboxPluginApplet">the <code>applet</code>
|
|
element</a>, or through <a href="history.html#sandboxPluginNavigate">navigation</a> of a <a href="browsers.html#nested-browsing-context">nested
|
|
browsing context</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</dfn></dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag prevents content from using the <code title="attr-iframe-seamless"><a href="#attr-iframe-seamless">seamless</a></code> attribute on
|
|
descendant <code><a href="#the-iframe-element">iframe</a></code> elements.</p>
|
|
|
|
<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>
|
|
keyword from using a CSS-selector-based method of probing the DOM
|
|
of other pages on the same site (in particular, pages that contain
|
|
user-sensitive information).</p>
|
|
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-origin-browsing-context-flag">sandboxed origin browsing context flag</dfn>, unless
|
|
the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
|
|
value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
|
|
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>
|
|
keyword set</dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag <a href="origin-0.html#sandboxOrigin">forces content into a unique
|
|
origin</a>, thus preventing it from accessing other content from
|
|
the same <a href="origin-0.html#origin">origin</a>.</p>
|
|
|
|
<p>This flag also <a href="dom.html#sandboxCookies">prevents script from
|
|
reading from or writing to the <code title="dom-document-cookie">document.cookie</code> IDL
|
|
attribute</a>, and blocks access to <code title="dom-localStorage">localStorage</code>.
|
|
|
|
<a href="references.html#refsWEBSTORAGE">[WEBSTORAGE]</a>
|
|
|
|
</p>
|
|
|
|
<div class="note">
|
|
|
|
<p>The <code title="attr-iframe-sandbox-allow-same-origin"><a href="#attr-iframe-sandbox-allow-same-origin">allow-same-origin</a></code>
|
|
attribute is intended for two cases.</p>
|
|
|
|
<p>First, it can be used to allow content from the same site to
|
|
be sandboxed to disable scripting, while still allowing access to
|
|
the DOM of the sandboxed content.</p>
|
|
|
|
<p>Second, it can be used to embed content from a third-party
|
|
site, sandboxed to prevent that site from opening popup windows,
|
|
etc, without preventing the embedded page from communicating back
|
|
to its originating site, using the database APIs to store data,
|
|
etc.</p>
|
|
|
|
</div>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-forms-browsing-context-flag">sandboxed forms browsing context flag</dfn>, unless
|
|
the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
|
|
value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
|
|
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>
|
|
keyword set</dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag <a href="association-of-controls-and-forms.html#sandboxSubmitBlocked">blocks form
|
|
submission</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-scripts-browsing-context-flag">sandboxed scripts browsing context flag</dfn>, unless
|
|
the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's
|
|
value, when <a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on
|
|
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>
|
|
keyword set</dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag <a href="webappapis.html#sandboxScriptBlocked">blocks script
|
|
execution</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>The <dfn id="sandboxed-automatic-features-browsing-context-flag">sandboxed automatic features browsing context
|
|
flag</dfn>, unless the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute's value, when
|
|
<a href="common-microsyntaxes.html#split-a-string-on-spaces" title="split a string on spaces">split on spaces</a>, is
|
|
found to have the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
|
|
keyword (defined above) set</dt>
|
|
|
|
<dd>
|
|
|
|
<p>This flag blocks features that trigger automatically, such as
|
|
<a href="#attr-media-autoplay" title="attr-media-autoplay">automatically playing a
|
|
video</a> or <a href="association-of-controls-and-forms.html#attr-fe-autofocus" title="attr-fe-autofocus">automatically
|
|
focusing a form control</a>. It is relaxed by the same flag as
|
|
scripts, because when scripts are enabled these features are
|
|
trivially possible anyway, and it would be unfortunate to force
|
|
authors to use script to do them when sandboxed rather than
|
|
allowing them to use the declarative features.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>These flags must not be set unless the conditions listed above
|
|
define them as being set.</p>
|
|
|
|
<p class="warning">These flags only take effect when the
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code> is
|
|
<a href="history.html#navigate" title="navigate">navigated</a>. Removing them, or removing
|
|
the entire <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code>
|
|
attribute, has no effect on an already-loaded page.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>In this example, some completely-unknown, potentially hostile,
|
|
user-provided HTML content is embedded in a page. Because it is
|
|
sandboxed, it is treated by the user agent as being from a unique
|
|
origin, despite the content being served from the same site. Thus
|
|
it is affected by all the normal cross-site restrictions. In
|
|
addition, the embedded page has scripting disabled, plugins
|
|
disabled, forms disabled, and it cannot navigate any frames or
|
|
windows other than itself (or any frames or windows it itself
|
|
embeds).</p>
|
|
|
|
<pre><p>We're not scared of you! Here is your content, unedited:</p>
|
|
<iframe sandbox src="getusercontent.cgi?id=12193"></iframe></pre>
|
|
|
|
<p>Note that cookies are still sent to the server in the <code title="">getusercontent.cgi</code> request, though they are not
|
|
visible in the <code title="dom-document-cookie"><a href="dom.html#dom-document-cookie">document.cookie</a></code> IDL
|
|
attribute.</p>
|
|
|
|
<p class="warning">It is important that the server serve the
|
|
user-provided HTML using the <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> MIME
|
|
type so that if the attacker convinces the user to visit that page
|
|
directly, the page doesn't run in the context of the site's origin,
|
|
which would make the user vulnerable to any attack found in the
|
|
page.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>In this example, a gadget from another site is embedded. The
|
|
gadget has scripting and forms enabled, and the origin sandbox
|
|
restrictions are lifted, allowing the gadget to communicate with
|
|
its originating server. The sandbox is still useful, however, as it
|
|
disables plugins and popups, thus reducing the risk of the user
|
|
being exposed to malware and other annoyances.</p>
|
|
|
|
<pre><iframe sandbox="allow-same-origin allow-forms allow-scripts"
|
|
src="http://maps.example.com/embedded.html"></iframe></pre>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Suppose a file A contained the following fragment:</p>
|
|
|
|
<pre><iframe sandbox="allow-same-origin allow-forms" src=B></iframe></pre>
|
|
|
|
<p>Suppose that file B contained an iframe also:</p>
|
|
|
|
<pre><iframe sandbox="allow-scripts" src=C></iframe></pre>
|
|
|
|
<p>Further, suppose that file C contained a link:</p>
|
|
|
|
<pre><a href=D>Link</a></pre>
|
|
|
|
<p>For this example, suppose all the files were served as
|
|
<code><a href="iana.html#text-html">text/html</a></code>.</p>
|
|
|
|
<p>Page C in this scenario has all the sandboxing flags
|
|
set. Scripts are disabled, because the <code><a href="#the-iframe-element">iframe</a></code> in A has
|
|
scripts disabled, and this overrides the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
|
|
keyword set on the <code><a href="#the-iframe-element">iframe</a></code> in B. Forms are also
|
|
disabled, because the inner <code><a href="#the-iframe-element">iframe</a></code> (in B) does not
|
|
have the <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keyword
|
|
set.</p>
|
|
|
|
<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
|
|
B. This would change nothing immediately. If the user clicked the
|
|
link in C, loading page D into the <code><a href="#the-iframe-element">iframe</a></code> in B, page D
|
|
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>
|
|
and <code title="attr-iframe-sandbox-allow-forms"><a href="#attr-iframe-sandbox-allow-forms">allow-forms</a></code> keywords
|
|
set, because that was the state of the <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a> in the <code><a href="#the-iframe-element">iframe</a></code> in A when page B was
|
|
loaded.</p>
|
|
|
|
<p>Generally speaking, dynamically removing or changing the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute is
|
|
ill-advised, because it can make it quite hard to reason about what
|
|
will be allowed and what will not.</p>
|
|
|
|
</div><p class="note">Potentially hostile files can be served from the
|
|
same server as the file containing the <code><a href="#the-iframe-element">iframe</a></code> element
|
|
by labeling them as <code><a href="iana.html#text-html-sandboxed">text/html-sandboxed</a></code> instead of
|
|
<code><a href="iana.html#text-html">text/html</a></code>. This ensures that scripts in the files are
|
|
unable to attack the site (as if they were actually served from
|
|
another server), even if the user is tricked into visiting those
|
|
pages directly, without the protection of the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute.</p><p class="warning">If the <code title="attr-iframe-sandbox-allow-scripts"><a href="#attr-iframe-sandbox-allow-scripts">allow-scripts</a></code>
|
|
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>
|
|
keyword, and the file is from the <a href="origin-0.html#same-origin">same origin</a> as the
|
|
<code><a href="#the-iframe-element">iframe</a></code>'s <code><a href="infrastructure.html#document">Document</a></code>, then a script in the
|
|
"sandboxed" iframe could just reach out, remove the <code title="attr-iframe-sandbox"><a href="#attr-iframe-sandbox">sandbox</a></code> attribute, and then
|
|
reload itself, effectively breaking out of the sandbox
|
|
altogether.</p><hr><p>The <dfn id="attr-iframe-seamless" title="attr-iframe-seamless"><code>seamless</code></dfn>
|
|
attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When specified, it
|
|
indicates that the <code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#browsing-context">browsing
|
|
context</a> is to be rendered in a manner that makes it appear to
|
|
be part of the containing document (seamlessly included in the
|
|
parent document). <span class="impl">Specifically, when the
|
|
attribute is set on an <code><a href="#the-iframe-element">iframe</a></code> element whose owner
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <a href="browsers.html#browsing-context">browsing context</a> did not have
|
|
the <a href="#sandboxed-seamless-iframes-flag">sandboxed seamless iframes flag</a> set when that
|
|
<code><a href="infrastructure.html#document">Document</a></code> was created, and while either the
|
|
<a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active document</a> has the
|
|
<a href="origin-0.html#same-origin">same origin</a> as the <code><a href="#the-iframe-element">iframe</a></code> element's
|
|
document, or the <a href="browsers.html#browsing-context">browsing context</a>'s <a href="browsers.html#active-document">active
|
|
document</a>'s <em><a href="dom.html#the-document-s-address" title="the document's
|
|
address">address</a></em> has the <a href="origin-0.html#same-origin">same origin</a> as the
|
|
<code><a href="#the-iframe-element">iframe</a></code> element's document, or the <a href="browsers.html#browsing-context">browsing
|
|
context</a>'s <a href="browsers.html#active-document">active document</a> is <a href="#an-iframe-srcdoc-document">an
|
|
<code>iframe</code> <code title="attr-iframe-srcdoc">srcdoc</code>
|
|
document</a>, the following requirements apply:</span></p><div class="impl">
|
|
|
|
<ul><li><p>The user agent must set the <dfn id="seamless-browsing-context-flag">seamless browsing context
|
|
flag</dfn> to true for that <a href="browsers.html#browsing-context">browsing context</a>. This
|
|
will <a href="history.html#seamlessLinks">cause links to open in the parent
|
|
browsing context</a> unless an <a href="browsers.html#explicit-self-navigation-override">explicit self-navigation
|
|
override</a> is used (<code title="">target="_self"</code>).</p></li>
|
|
|
|
<li><p>In a CSS-supporting user agent: the user agent must add all
|
|
the style sheets that apply to the <code><a href="#the-iframe-element">iframe</a></code> element to
|
|
the cascade of the <a href="browsers.html#active-document">active document</a> of the
|
|
<code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
|
|
at the appropriate cascade levels, before any style sheets
|
|
specified by the document itself.</p></li>
|
|
|
|
<li><p>In a CSS-supporting user agent: the user agent must, for the
|
|
purpose of CSS property inheritance only, treat the root element of
|
|
the <a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code>
|
|
element's <a href="browsers.html#nested-browsing-context">nested browsing context</a> as being a child of
|
|
the <code><a href="#the-iframe-element">iframe</a></code> element. (Thus inherited properties on the
|
|
root element of the document in the <code><a href="#the-iframe-element">iframe</a></code> will
|
|
inherit the computed values of those properties on the
|
|
<code><a href="#the-iframe-element">iframe</a></code> element instead of taking their initial
|
|
values.)</p></li>
|
|
|
|
<li><p>In visual media, in a CSS-supporting user agent: the user agent
|
|
should set the intrinsic width of the <code><a href="#the-iframe-element">iframe</a></code> to the
|
|
width that the element would have if it was a non-replaced
|
|
block-level element with 'width: auto'.</p></li>
|
|
|
|
<li><p>In visual media, in a CSS-supporting user agent: the user
|
|
agent should set the intrinsic height of the <code><a href="#the-iframe-element">iframe</a></code> to
|
|
the height of the bounding box around the content rendered in the
|
|
<code><a href="#the-iframe-element">iframe</a></code> at its current width (as given in the previous
|
|
bullet point), as it would be if the scrolling position was such
|
|
that the top of the viewport for the content rendered in the
|
|
<code><a href="#the-iframe-element">iframe</a></code> was aligned with the origin of that content's
|
|
canvas.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>In visual media, in a CSS-supporting user agent: the user agent
|
|
must force the height of the initial containing block of the
|
|
<a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a> of the <code><a href="#the-iframe-element">iframe</a></code> to zero.</p>
|
|
|
|
<p class="note">This is intended to get around the otherwise
|
|
circular dependency of percentage dimensions that depend on the
|
|
height of the containing block, thus affecting the height of the
|
|
document's bounding box, thus affecting the height of the
|
|
viewport, thus affecting the size of the initial containing
|
|
block.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>In speech media, the user agent should render the <a href="browsers.html#nested-browsing-context">nested
|
|
browsing context</a> without announcing that it is a separate
|
|
document.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>User agents should, in general, act as if the <a href="browsers.html#active-document">active
|
|
document</a> of the <code><a href="#the-iframe-element">iframe</a></code>'s <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a> was part of the document that the
|
|
<code><a href="#the-iframe-element">iframe</a></code> is in, if any.</p>
|
|
|
|
<p class="example">For example if the user agent supports listing
|
|
all the links in a document, links in "seamlessly" nested
|
|
documents would be included in that list without being
|
|
significantly distinguished from links in the document itself.</p>
|
|
|
|
</li>
|
|
|
|
</ul><p>If the attribute is not specified, or if the <a href="origin-0.html#origin">origin</a>
|
|
conditions listed above are not met, then the user agent should
|
|
render the <a href="browsers.html#nested-browsing-context">nested browsing context</a> in a manner that is
|
|
clearly distinguishable as a separate <a href="browsers.html#browsing-context">browsing context</a>,
|
|
and the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a> must be set to
|
|
false for that <a href="browsers.html#browsing-context">browsing context</a>.</p>
|
|
|
|
<p class="warning">It is important that user agents recheck the
|
|
above conditions whenever the <a href="browsers.html#active-document">active document</a> of the
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a> of the <code><a href="#the-iframe-element">iframe</a></code>
|
|
changes, such that the <a href="#seamless-browsing-context-flag">seamless browsing context flag</a>
|
|
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>
|
|
|
|
</div><p class="note">The attribute can be set or removed dynamically,
|
|
with the rendering updating in tandem.</p><div class="example">
|
|
|
|
<p>In this example, the site's navigation is embedded using a
|
|
client-side include using an <code><a href="#the-iframe-element">iframe</a></code>. Any links in the
|
|
<code><a href="#the-iframe-element">iframe</a></code> will, in new user agents, be automatically
|
|
opened in the <code><a href="#the-iframe-element">iframe</a></code>'s parent browsing context; for
|
|
legacy user agents, the site could also include a <code><a href="semantics.html#the-base-element">base</a></code>
|
|
element with a <code title="attr-base-target"><a href="semantics.html#attr-base-target">target</a></code>
|
|
attribute with the value <code title="">_parent</code>. Similarly,
|
|
in new user agents the styles of the parent page will be
|
|
automatically applied to the contents of the frame, but to support
|
|
legacy user agents authors might wish to include the styles
|
|
explicitly.</p>
|
|
|
|
<pre><nav><iframe seamless src="nav.include.html"></iframe></nav></pre>
|
|
|
|
</div><hr><p>The <code><a href="#the-iframe-element">iframe</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
|
|
attributes</a> for cases where the embedded content has specific
|
|
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
|
|
content</a>, as it will always create a nested <a href="browsers.html#browsing-context">browsing
|
|
context</a>, regardless of whether the specified initial contents
|
|
are successfully used.</p><p>Descendants of <code><a href="#the-iframe-element">iframe</a></code> elements represent
|
|
nothing. (In legacy user agents that do not support
|
|
<code><a href="#the-iframe-element">iframe</a></code> elements, the contents would be parsed as markup
|
|
that could act as fallback content.)</p><p id="iframe-content-model">When used in <a href="dom.html#html-documents">HTML
|
|
documents</a>, the allowed content model of <code><a href="#the-iframe-element">iframe</a></code>
|
|
elements is text, except that invoking the <a href="the-end.html#html-fragment-parsing-algorithm">HTML fragment
|
|
parsing algorithm</a> with the <code><a href="#the-iframe-element">iframe</a></code> element as the
|
|
<var title="concept-frag-parse-context"><a href="the-end.html#concept-frag-parse-context">context</a></var> element and
|
|
the text contents as the <var title="">input</var> must result in a
|
|
list of nodes that are all <a href="content-models.html#phrasing-content">phrasing content</a>, with no
|
|
<a href="parsing.html#parse-error" title="parse error">parse errors</a> having occurred, with
|
|
no <code><a href="scripting-1.html#the-script-element">script</a></code> elements being anywhere in the list or as
|
|
descendants of elements in the list, and with all the elements in
|
|
the list (including their descendants) being themselves
|
|
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
|
|
documents</a>.</p><p class="note">The <a href="parsing.html#html-parser">HTML parser</a> treats markup inside
|
|
<code><a href="#the-iframe-element">iframe</a></code> elements as text.</p><div class="impl">
|
|
|
|
<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
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
|
|
name.</p>
|
|
|
|
<p>The <dfn id="dom-iframe-contentdocument" title="dom-iframe-contentDocument"><code>contentDocument</code></dfn>
|
|
IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
|
|
<a href="browsers.html#active-document">active document</a> of the <code><a href="#the-iframe-element">iframe</a></code> element's
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
|
|
|
|
<p>The <dfn id="dom-iframe-contentwindow" title="dom-iframe-contentWindow"><code>contentWindow</code></dfn>
|
|
IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
|
|
<code><a href="#the-iframe-element">iframe</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a>.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Here is an example of a page using an <code><a href="#the-iframe-element">iframe</a></code> to
|
|
include advertising from an advertising broker:</p>
|
|
|
|
<pre><iframe src="http://ads.example.com/?customerid=923513721&amp;format=banner"
|
|
width="468" height="60"></iframe></pre>
|
|
|
|
</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>
|
|
<dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
|
|
<dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
|
|
<dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
|
|
<dd><a href="content-models.html#interactive-content">Interactive content</a>.</dd>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
|
|
<dt>Content model:</dt>
|
|
<dd>Empty.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-embed-src"><a href="#attr-embed-src">src</a></code></dd>
|
|
<dd><code title="attr-embed-type"><a href="#attr-embed-type">type</a></code></dd>
|
|
<dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
|
|
<dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
|
|
<dd>Any other attribute that has no namespace (see prose).</dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmlembedelement">HTMLEmbedElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
attribute DOMString <a href="#dom-embed-src" title="dom-embed-src">src</a>;
|
|
attribute DOMString <a href="#dom-embed-type" title="dom-embed-type">type</a>;
|
|
attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
|
|
attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
|
|
};</pre>
|
|
<div class="impl">
|
|
<p>Depending on the type of content instantiated by the
|
|
<code><a href="#the-embed-element">embed</a></code> element, the node may also support other
|
|
interfaces.</p>
|
|
</div>
|
|
</dd>
|
|
</dl><p>The <code><a href="#the-embed-element">embed</a></code> element <a href="rendering.html#represents">represents</a> an
|
|
integration point for an external (typically non-HTML) application
|
|
or interactive content.</p><p>The <dfn id="attr-embed-src" title="attr-embed-src"><code>src</code></dfn> attribute
|
|
gives the address of the resource being embedded. The attribute, if
|
|
present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially
|
|
surrounded by spaces</a>.</p><p>The <dfn id="attr-embed-type" title="attr-embed-type"><code>type</code></dfn>
|
|
attribute, if present, gives the <a href="infrastructure.html#mime-type">MIME type</a> by which the
|
|
plugin to instantiate is selected. The value must be a <a href="infrastructure.html#valid-mime-type">valid
|
|
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
|
|
<code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute must specify the
|
|
same type as the <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type
|
|
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">
|
|
|
|
<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
|
|
are removed such that neither attribute is present on the element
|
|
anymore, and when the element has a <a href="#media-element">media element</a>
|
|
ancestor, and when the element has an ancestor <code><a href="#the-object-element">object</a></code>
|
|
element that is <em>not</em> showing its <a href="content-models.html#fallback-content">fallback
|
|
content</a>, any plugins instantiated for the element must be
|
|
removed, and the <code><a href="#the-embed-element">embed</a></code> element represents nothing.</p>
|
|
|
|
<p id="sandboxPluginEmbed">If either:
|
|
|
|
</p><ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
|
|
set on the <a href="browsers.html#browsing-context">browsing context</a> for which the
|
|
<code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> is the
|
|
<a href="browsers.html#active-document">active document</a> when that <code><a href="infrastructure.html#document">Document</a></code> was
|
|
created, or</li>
|
|
|
|
<li>the <code><a href="#the-embed-element">embed</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
|
|
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></li>
|
|
|
|
</ul><p>...then the user agent must render the <code><a href="#the-embed-element">embed</a></code> element
|
|
in a manner that conveys that the <a href="infrastructure.html#plugin">plugin</a> was
|
|
disabled. The user agent may offer the user the option to override
|
|
the sandbox and instantiate the <a href="infrastructure.html#plugin">plugin</a> anyway; if the
|
|
user invokes such an option, the user agent must act as if the
|
|
conditions above did not apply for the purposes of this element.</p>
|
|
|
|
<p class="warning">Plugins are disabled in sandboxed browsing
|
|
contexts because they might not honor the restrictions imposed by
|
|
the sandbox (e.g. they might allow scripting even when scripting in
|
|
the sandbox is disabled). User agents should convey the danger of
|
|
overriding the sandbox to the user if an option to do so is
|
|
provided.</p>
|
|
|
|
<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
|
|
following conditions are all met simultaneously:</p>
|
|
|
|
<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>
|
|
<li>The element's <code><a href="infrastructure.html#document">Document</a></code> is <a href="browsers.html#fully-active">fully active</a>.</li>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<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>
|
|
<li>The element is not a descendant of a <a href="#media-element">media element</a>.</li>
|
|
<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>
|
|
</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
|
|
a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
|
|
<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
|
|
removed, and whenever a <a href="#concept-embed-active" title="concept-embed-active">potentially active</a>
|
|
<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
|
|
removed, the appropriate set of steps from the following is then
|
|
applied:</p>
|
|
|
|
<dl class="switch"><dt>If the element has a <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
|
|
attribute set</dt>
|
|
|
|
<dd>
|
|
|
|
<p>The user agent must <a href="urls.html#resolve-a-url" title="resolve a url">resolve</a>
|
|
the value of the element's <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
|
|
attribute, relative to the element. If that is successful, the
|
|
user agent should <a href="fetching-resources.html#fetch">fetch</a> the resulting <a href="urls.html#absolute-url">absolute
|
|
URL</a>, from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope
|
|
origin</a> if it has one. 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 source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> must find and instantiate an
|
|
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
|
|
<a href="infrastructure.html#plugin">plugin</a> the content of the resource, replacing any
|
|
previously instantiated plugin for the element.</p>
|
|
<p>Fetching the resource must <a href="the-end.html#delay-the-load-event">delay the load event</a> of
|
|
the element's document.</p>
|
|
|
|
|
|
</dd>
|
|
|
|
<dt>If the element has no <code title="attr-embed-src"><a href="#attr-embed-src">src</a></code>
|
|
attribute set</dt>
|
|
|
|
<dd><p>The user agent should find and instantiate an appropriate
|
|
<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>
|
|
|
|
</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
|
|
<a href="#concept-embed-active" title="concept-embed-active">potentially active</a>, any
|
|
<a href="infrastructure.html#plugin">plugin</a> that had been instantiated for that element must
|
|
be unloaded.</p>
|
|
|
|
<p class="note">The <code><a href="#the-embed-element">embed</a></code> element is unaffected by the
|
|
CSS 'display' property. The selected plugin is instantiated even if
|
|
the element is hidden with a 'display:none' CSS style.</p>
|
|
|
|
<p>The <dfn id="concept-embed-type" title="concept-embed-type">type of the content</dfn>
|
|
being embedded is defined as follows:</p>
|
|
|
|
<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
|
|
value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, then the value
|
|
of the <code title="attr-embed-type"><a href="#attr-embed-type">type</a></code> attribute is the
|
|
<a href="#concept-embed-type" title="concept-embed-type">content's type</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
|
|
<p>Otherwise, if the <a href="urls.html#url-path" title="url-path"><path></a>
|
|
component of the <a href="urls.html#url">URL</a> of the specified resource (after
|
|
any redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
|
|
supports, then the <a href="#concept-embed-type" title="concept-embed-type">content's
|
|
type</a> is the type that that plugin can handle.</p>
|
|
|
|
<p class="example">For example, a plugin might say that it can
|
|
handle resources with <a href="urls.html#url-path" title="url-path"><path></a>
|
|
components that end with the four character string "<code title="">.swf</code>".</p>
|
|
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li><p>Otherwise, if the specified resource has <a href="fetching-resources.html#content-type" title="Content-Type">explicit Content-Type metadata</a>, then
|
|
that is the <a href="#concept-embed-type" title="concept-embed-type">content's
|
|
type</a>.</p></li>
|
|
|
|
<li><p>Otherwise, the content has no type and there can be no
|
|
appropriate <a href="infrastructure.html#plugin">plugin</a> for it.</p></li>
|
|
|
|
|
|
|
|
</ol><p>The <code><a href="#the-embed-element">embed</a></code> element has no <a href="content-models.html#fallback-content">fallback
|
|
content</a>. If the user agent can't find a suitable plugin, then
|
|
the user agent must use a default plugin. (This default could be as
|
|
simple as saying "Unsupported Format".)</p>
|
|
|
|
<p>Whether the resource is fetched successfully or not (e.g. whether
|
|
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
|
|
ignored when determining the resource's type and when handing the
|
|
resource to the plugin.</p>
|
|
|
|
<p class="note">This allows servers to return data for plugins even
|
|
with error responses (e.g. HTTP 500 Internal Server Error codes can
|
|
still contain plugin data).</p>
|
|
|
|
</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,
|
|
so long as its name is <a href="infrastructure.html#xml-compatible">XML-compatible</a> and contains no
|
|
characters in the range U+0041 to U+005A (LATIN CAPITAL LETTER A to
|
|
LATIN CAPITAL LETTER Z). These attributes are then passed as
|
|
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
|
|
lowercased automatically, so the restriction on uppercase letters
|
|
doesn't affect such documents.</p><p class="note">The four exceptions are to exclude legacy attributes
|
|
that have side-effects beyond just sending parameters to the
|
|
<a href="infrastructure.html#plugin">plugin</a>.</p><div class="impl">
|
|
|
|
<p>The user agent should pass the names and values of all the
|
|
attributes of the <code><a href="#the-embed-element">embed</a></code> element that have no namespace
|
|
to the <a href="infrastructure.html#plugin">plugin</a> used, when it is instantiated.</p>
|
|
|
|
<p>If the <a href="infrastructure.html#plugin">plugin</a> instantiated for the
|
|
<code><a href="#the-embed-element">embed</a></code> element supports a scriptable interface, the
|
|
<code><a href="#htmlembedelement">HTMLEmbedElement</a></code> object representing the element should
|
|
expose that interface while the element is instantiated.</p>
|
|
|
|
</div><p>The <code><a href="#the-embed-element">embed</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
|
|
attributes</a>.</p><div class="impl">
|
|
|
|
<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
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
|
|
name.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Here's a way to embed a resource that requires a proprietary
|
|
plug-in, like Flash:</p>
|
|
|
|
<pre><embed src="catgame.swf"></pre>
|
|
|
|
<p>If the user does not have the plug-in (for example if the
|
|
plug-in vendor doesn't support the user's platform), then the user
|
|
will be unable to use the resource.</p>
|
|
|
|
<p>To pass the plugin a parameter "quality" with the value "high",
|
|
an attribute can be specified:</p>
|
|
|
|
<pre><embed src="catgame.swf" quality="high"></pre>
|
|
|
|
<p>This would be equivalent to the following, when using an
|
|
<code><a href="#the-object-element">object</a></code> element instead:</p>
|
|
|
|
<pre><object data="catgame.swf">
|
|
<param name="quality" value="high">
|
|
</object></pre>
|
|
|
|
</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>
|
|
<dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
|
|
<dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
|
|
<dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
|
|
<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>
|
|
<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>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
|
|
<dt>Content model:</dt>
|
|
<dd>Zero or more <code><a href="#the-param-element">param</a></code> elements, then, <a href="content-models.html#transparent">transparent</a>.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-object-data"><a href="#attr-object-data">data</a></code></dd>
|
|
<dd><code title="attr-object-type"><a href="#attr-object-type">type</a></code></dd>
|
|
<dd><code title="attr-object-name"><a href="#attr-object-name">name</a></code></dd>
|
|
<dd><code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code></dd>
|
|
<dd><code title="attr-fae-form"><a href="association-of-controls-and-forms.html#attr-fae-form">form</a></code></dd>
|
|
<dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
|
|
<dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmlobjectelement">HTMLObjectElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
attribute DOMString <a href="#dom-object-data" title="dom-object-data">data</a>;
|
|
attribute DOMString <a href="#dom-object-type" title="dom-object-type">type</a>;
|
|
attribute DOMString <a href="#dom-object-name" title="dom-object-name">name</a>;
|
|
attribute DOMString <a href="#dom-object-usemap" title="dom-object-useMap">useMap</a>;
|
|
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>;
|
|
attribute DOMString <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
|
|
attribute DOMString <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
|
|
readonly attribute Document <a href="#dom-object-contentdocument" title="dom-object-contentDocument">contentDocument</a>;
|
|
readonly attribute <a href="browsers.html#windowproxy">WindowProxy</a> <a href="#dom-object-contentwindow" title="dom-object-contentWindow">contentWindow</a>;
|
|
|
|
readonly attribute boolean <a href="association-of-controls-and-forms.html#dom-cva-willvalidate" title="dom-cva-willValidate">willValidate</a>;
|
|
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>;
|
|
readonly attribute DOMString <a href="association-of-controls-and-forms.html#dom-cva-validationmessage" title="dom-cva-validationMessage">validationMessage</a>;
|
|
boolean <a href="association-of-controls-and-forms.html#dom-cva-checkvalidatity" title="dom-cva-checkValidatity">checkValidity</a>();
|
|
void <a href="association-of-controls-and-forms.html#dom-cva-setcustomvalidity" title="dom-cva-setCustomValidity">setCustomValidity</a>(in DOMString error);
|
|
};</pre>
|
|
<div class="impl">
|
|
<p>Depending on the type of content instantiated by the
|
|
<code><a href="#the-object-element">object</a></code> element, the node also supports other
|
|
interfaces.</p>
|
|
</div>
|
|
</dd>
|
|
</dl><p>The <code><a href="#the-object-element">object</a></code> element can represent an external
|
|
resource, which, depending on the type of the resource, will either
|
|
be treated as an image, as a <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
|
|
or as an external resource to be processed by a
|
|
<a href="infrastructure.html#plugin">plugin</a>.</p><p>The <dfn id="attr-object-data" title="attr-object-data"><code>data</code></dfn>
|
|
attribute, if present, specifies the address of the resource. If
|
|
present, the attribute must be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
|
|
URL potentially surrounded by spaces</a>.</p><p>The <dfn id="attr-object-type" title="attr-object-type"><code>type</code></dfn>
|
|
attribute, if present, specifies the type of the resource. If
|
|
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>
|
|
attribute, if present, must be a <a href="browsers.html#valid-browsing-context-name">valid browsing context
|
|
name</a>. The given value is used to name the <a href="browsers.html#nested-browsing-context">nested
|
|
browsing context</a>, if applicable.</p><div class="impl">
|
|
|
|
<p>When the element is created, when it is popped off the
|
|
<a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an <a href="parsing.html#html-parser">HTML parser</a>
|
|
or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, and subsequently whenever the element is
|
|
<a href="infrastructure.html#insert-an-element-into-a-document" title="insert an element into a document">inserted into a
|
|
document</a> or <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an element from a
|
|
document">removed from a document</a>; and whenever the element's
|
|
<code><a href="infrastructure.html#document">Document</a></code> changes whether it is <a href="browsers.html#fully-active">fully
|
|
active</a>; and whenever an ancestor <code><a href="#the-object-element">object</a></code> element
|
|
changes to or from showing its <a href="content-models.html#fallback-content">fallback content</a>; and
|
|
whenever the element's <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code> attribute is set,
|
|
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,
|
|
whenever its <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute is
|
|
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
|
|
its <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute is set,
|
|
changed, or removed: the user agent must <a href="webappapis.html#queue-a-task">queue a task</a>
|
|
to run the following steps to (re)determine what the
|
|
<code><a href="#the-object-element">object</a></code> element represents. The <a href="webappapis.html#task-source">task source</a>
|
|
for this <a href="webappapis.html#concept-task" title="concept-task">task</a> is the <a href="webappapis.html#dom-manipulation-task-source">DOM
|
|
manipulation task source</a>.</p>
|
|
<ol><li>
|
|
|
|
<p>If the user has indicated a preference that this
|
|
<code><a href="#the-object-element">object</a></code> element's <a href="content-models.html#fallback-content">fallback content</a> be
|
|
shown instead of the element's usual behavior, then jump to the
|
|
last step in the overall set of steps (fallback).</p>
|
|
|
|
<p class="note">For example, a user could ask for the element's
|
|
<a href="content-models.html#fallback-content">fallback content</a> to be shown because that content
|
|
uses a format that the user finds more accessible.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the element has an ancestor <a href="#media-element">media element</a>, or
|
|
has an ancestor <code><a href="#the-object-element">object</a></code> element that is <em>not</em>
|
|
showing its <a href="content-models.html#fallback-content">fallback content</a>, or if the element is
|
|
not <a href="infrastructure.html#in-a-document" title="in a document">in a <code>Document</code></a>
|
|
with a <a href="browsers.html#browsing-context">browsing context</a>, or if the element's
|
|
<code><a href="infrastructure.html#document">Document</a></code> is not <a href="browsers.html#fully-active">fully active</a>, or if the
|
|
element is still in the <a href="parsing.html#stack-of-open-elements">stack of open elements</a> of an
|
|
<a href="parsing.html#html-parser">HTML parser</a> or <a href="the-xhtml-syntax.html#xml-parser">XML parser</a>, then jump to
|
|
the last step in the overall set of steps (fallback).</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
|
|
<p>If the <code title="attr-object-classid"><a href="obsolete.html#attr-object-classid">classid</a></code>
|
|
attribute is present, and has a value that isn't the empty string,
|
|
then: if the user agent can find a <a href="infrastructure.html#plugin">plugin</a> suitable
|
|
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>,
|
|
then that <a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be
|
|
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
|
|
passed to the <a href="infrastructure.html#plugin">plugin</a>. If no suitable
|
|
<a href="infrastructure.html#plugin">plugin</a> can be found, or if the <a href="infrastructure.html#plugin">plugin</a>
|
|
reports an error, jump to the last step in the overall set of
|
|
steps (fallback).</p>
|
|
|
|
|
|
</li>
|
|
|
|
|
|
<li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
|
|
is present and its value is not the empty string, then:</p>
|
|
|
|
<ol><li><p>If the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
|
|
attribute is present and its value is not a type that the user
|
|
agent supports, and is not a type that the user agent can find a
|
|
<a href="infrastructure.html#plugin">plugin</a> for, then the user agent may jump to the last
|
|
step in the overall set of steps (fallback) without fetching the
|
|
content to examine its real type.</p></li>
|
|
|
|
<li><p><a href="urls.html#resolve-a-url" title="resolve a url">Resolve</a> the
|
|
<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
|
|
element.</p></li>
|
|
|
|
<li><p>If that failed, <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
|
|
<code title="event-error">error</code> at the element, then jump
|
|
to the last step in the overall set of steps (fallback).</p></li>
|
|
|
|
<li>
|
|
|
|
<p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
|
|
from the element's <a href="browsers.html#browsing-context-scope-origin">browsing context scope origin</a> if
|
|
it has one.</p>
|
|
|
|
<p>Fetching the resource
|
|
must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's document
|
|
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
|
|
source</a> once the resource has been <a href="fetching-resources.html#fetch" title="fetch">fetched</a> (defined next) has been run.</p>
|
|
|
|
<p>For the purposes of the <a href="offline.html#application-cache">application cache</a>
|
|
networking model, this <a href="fetching-resources.html#fetch">fetch</a> operation is not for a
|
|
<a href="browsers.html#child-browsing-context">child browsing context</a> (though it might end up
|
|
being used for one after all, as defined below).</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If the resource is not yet available (e.g. because the
|
|
resource was not available in the cache, so that loading the
|
|
resource required making a request over the network), then jump
|
|
to the last step in the overall set of steps (fallback). 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 source</a>
|
|
once the resource is available must restart this algorithm from
|
|
this step. Resources can load incrementally; user agents may opt
|
|
to consider a resource "available" whenever enough data has been
|
|
obtained to begin processing the resource.</p></li>
|
|
|
|
<li><p>If the load failed (e.g. there was an HTTP 404 error,
|
|
there was a DNS error), <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named
|
|
<code title="event-error">error</code> at the element, then jump
|
|
to the last step in the overall set of steps (fallback).</p></li>
|
|
|
|
<li id="object-type-detection">
|
|
|
|
<p>Determine the <var title="">resource type</var>, as follows:</p>
|
|
|
|
|
|
<ol><li>
|
|
|
|
<p>Let the <var title="">resource type</var> be unknown.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
|
|
|
|
<p>If the user agent is configured to strictly obey
|
|
Content-Type headers for this resource, and the resource has
|
|
<a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
|
|
metadata</a>, then let the <var title="">resource
|
|
type</var> be the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
|
|
metadata</a>, and jump to the step below labeled
|
|
<i>handler</i>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
|
|
attribute present on the <code><a href="#the-object-element">object</a></code> element, and that
|
|
attribute's value is not a type that the user agent supports,
|
|
but it <em>is</em> a type that a <a href="infrastructure.html#plugin">plugin</a> supports,
|
|
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, and jump to the step below labeled
|
|
<i>handler</i>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Run the approprate set of steps from the following
|
|
list:</p>
|
|
|
|
<dl class="switch"><dt>The resource has <a href="fetching-resources.html#content-type" title="Content-Type">associated
|
|
Content-Type metadata</a></dt>
|
|
|
|
<dd>
|
|
|
|
<ol><li>
|
|
|
|
<p>Let <var title="">binary</var> be false.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
|
|
resource's Content-Type metadata</a> is
|
|
"<code>text/plain</code>", and the result of applying the
|
|
<a href="fetching-resources.html#content-type-sniffing:-text-or-binary" title="Content-Type sniffing: text or binary">rules
|
|
for distinguishing if a resource is text or binary</a>
|
|
to the resource is that the resource is not
|
|
<code>text/plain</code>, then set <var title="">binary</var> to true.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the type specified in <a href="fetching-resources.html#content-type" title="Content-Type">the
|
|
resource's Content-Type metadata</a> is
|
|
"<code>application/octet-stream</code>", then set <var title="">binary</var> to true.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">binary</var> is false, then let the
|
|
<var title="">resource type</var> be the type specified in
|
|
<a href="fetching-resources.html#content-type" title="Content-Type">the resource's Content-Type
|
|
metadata</a>, and jump to the step below labeled
|
|
<i>handler</i>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
|
|
the <code><a href="#the-object-element">object</a></code> element, and its value is not
|
|
<code>application/octet-stream</code>, then run the
|
|
following steps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If the attribute's value is a type that a <a href="infrastructure.html#plugin">plugin</a> supports, or
|
|
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>,
|
|
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>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Jump to the step below labeled <i>handler</i>.</p>
|
|
|
|
</li>
|
|
|
|
</ol></li>
|
|
|
|
</ol></dd>
|
|
|
|
<dt>The resource does not have <a href="fetching-resources.html#content-type" title="Content-Type">associated Content-Type
|
|
metadata</a></dt>
|
|
|
|
<dd>
|
|
|
|
<ol><li>
|
|
|
|
<p>If there is a <code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute present on
|
|
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
|
|
<code title="attr-object-type"><a href="#attr-object-type">type</a></code> attribute.</p>
|
|
|
|
<p>Otherwise, let <var title="">tentative type</var> be the
|
|
<a href="fetching-resources.html#content-type-sniffing-0" title="content-type sniffing">sniffed type of the
|
|
resource</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">tentative type</var> is <em>not</em>
|
|
<code>application/octet-stream</code>, then let <var title="">resource type</var> be <var title="">tentative
|
|
type</var> and jump to the step below labeled
|
|
<i>handler</i>.</p>
|
|
|
|
</li>
|
|
|
|
</ol></dd>
|
|
|
|
</dl></li>
|
|
|
|
<li>
|
|
|
|
|
|
<p>If the <a href="urls.html#url-path" title="url-path"><path></a> component
|
|
of the <a href="urls.html#url">URL</a> of the specified resource (after any
|
|
redirects) matches a pattern that a <a href="infrastructure.html#plugin">plugin</a>
|
|
supports, then let <var title="">resource type</var> be the
|
|
type that that plugin can handle.</p>
|
|
|
|
<p class="example">For example, a plugin might say that it can
|
|
handle resources with <a href="urls.html#url-path" title="url-path"><path></a> components that end with
|
|
the four character string "<code title="">.swf</code>".</p>
|
|
|
|
|
|
|
|
|
|
</li>
|
|
|
|
</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
|
|
the substeps above to jump straight to the next step. In both
|
|
cases, the next step will trigger fallback.</p>
|
|
|
|
</li>
|
|
|
|
<li><p><i>Handler</i>: Handle the content as given by the first
|
|
of the following cases that matches:</p>
|
|
|
|
<dl class="switch"><dt>If the <var title="">resource type</var> is not a type that
|
|
the user agent supports, but it <em>is</em> a type that a
|
|
<a href="infrastructure.html#plugin">plugin</a> supports</dt>
|
|
|
|
<dd>
|
|
|
|
<p>If <a href="#sandboxPluginObject">plugins are being
|
|
sandboxed</a>, jump to the last step in the overall set of
|
|
steps (fallback).</p>
|
|
|
|
<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
|
|
resource to that <a href="infrastructure.html#plugin">plugin</a>. If the
|
|
<a href="infrastructure.html#plugin">plugin</a> reports an error, then jump to the last
|
|
step in the overall set of steps (fallback).</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the <var title="">resource type</var> is an <a href="infrastructure.html#xml-mime-type">XML MIME
|
|
type</a>, or
|
|
|
|
if the <var title="">resource type</var> does not start with
|
|
"<code>image/</code>"</dt>
|
|
|
|
<dd>
|
|
|
|
<p>The <code><a href="#the-object-element">object</a></code> element must be associated with a
|
|
newly created <a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it does
|
|
not already have one.</p>
|
|
|
|
<p>If the <a href="urls.html#url">URL</a> of the given resource is not
|
|
<code><a href="fetching-resources.html#about:blank">about:blank</a></code>, the element's <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a> must then be <a href="history.html#navigate" title="navigate">navigated</a> to that
|
|
resource, with <a href="history.html#replacement-enabled">replacement enabled</a>, and with the
|
|
<code><a href="#the-object-element">object</a></code> element's document's <a href="browsers.html#browsing-context">browsing
|
|
context</a> as the <a href="history.html#source-browsing-context">source browsing context</a>.
|
|
(The <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute of
|
|
the <code><a href="#the-object-element">object</a></code> element doesn't get updated if the
|
|
browsing context gets further navigated to other
|
|
locations.)</p>
|
|
|
|
<p>If the <a href="urls.html#url">URL</a> of the given resource <em>is</em>
|
|
<code><a href="fetching-resources.html#about:blank">about:blank</a></code>, then, instead, 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 event</a>
|
|
named <code title="event-load">load</code> at the
|
|
<code><a href="#the-object-element">object</a></code> element.</p>
|
|
|
|
<p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a>.</p>
|
|
|
|
<p>If the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
|
|
is present, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
|
|
to the value of this attribute; otherwise, the <a href="browsers.html#browsing-context-name">browsing
|
|
context name</a> must be set to the empty string.</p>
|
|
|
|
<p class="note">In certain situations, e.g. if the resource
|
|
was <a href="fetching-resources.html#fetch" title="fetch">fetched</a> from an
|
|
<a href="offline.html#application-cache">application cache</a> but it is an HTML file with a
|
|
<code title="attr-html-manifest"><a href="semantics.html#attr-html-manifest">manifest</a></code> attribute
|
|
that points to a different <a href="offline.html#concept-appcache-manifest" title="concept-appcache-manifest">application cache
|
|
manifest</a>, the <a href="history.html#navigate" title="navigate">navigation</a>
|
|
of the <a href="browsers.html#browsing-context">browsing context</a> will be restarted so as
|
|
to load the resource afresh from the network or a different
|
|
<a href="offline.html#application-cache">application cache</a>. Even if the resource is then
|
|
found to have a different type, it is still used as part of a
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a>: only the
|
|
<a href="history.html#navigate">navigate</a> algorithm is restarted, not this
|
|
<code><a href="#the-object-element">object</a></code> algorithm.</p>
|
|
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the <var title="">resource type</var> starts with
|
|
"<code>image/</code>", and support for images has not been
|
|
disabled</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Apply the <a href="fetching-resources.html#content-type-sniffing:-image" title="content-type sniffing: image">image
|
|
sniffing</a> rules to determine the type of the image.</p>
|
|
|
|
<p>The <code><a href="#the-object-element">object</a></code> element <a href="rendering.html#represents">represents</a> the
|
|
specified image. The image is not a <a href="browsers.html#nested-browsing-context">nested browsing
|
|
context</a>.</p>
|
|
|
|
<p>If the image cannot be rendered, e.g. because it is
|
|
malformed or in an unsupported format, jump to the last step
|
|
in the overall set of steps (fallback).</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
|
|
<p>The given <var title="">resource type</var> is not
|
|
supported. Jump to the last step in the overall set of steps
|
|
(fallback).</p>
|
|
|
|
<p class="note">If the previous step ended with the <var title="">resource type</var> being unknown, this is the case
|
|
that is triggered.</p>
|
|
|
|
</dd>
|
|
|
|
</dl></li>
|
|
|
|
<li><p>The element's contents are not part of what the
|
|
<code><a href="#the-object-element">object</a></code> element represents.</p>
|
|
|
|
</li><li>
|
|
|
|
<p>Once the resource is completely loaded, <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 <code title="event-load">load</code> at the element.</p>
|
|
|
|
<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
|
|
source</a>.</p>
|
|
|
|
</li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p>If the <code title="attr-object-data"><a href="#attr-object-data">data</a></code> attribute
|
|
is absent but the <code title="attr-object-type"><a href="#attr-object-type">type</a></code>
|
|
attribute is present, <a href="#sandboxPluginObject">plugins aren't
|
|
being sandboxed</a>, and the user agent can find a
|
|
<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
|
|
<a href="infrastructure.html#plugin">plugin</a> <a href="#object-plugin">should be used</a>. If
|
|
no suitable <a href="infrastructure.html#plugin">plugin</a> can be found, or if the
|
|
<a href="infrastructure.html#plugin">plugin</a> reports an error, jump to the next step
|
|
(fallback).</p></li>
|
|
|
|
<li><p>(Fallback.) The <code><a href="#the-object-element">object</a></code> element
|
|
<a href="rendering.html#represents">represents</a> the element's children, ignoring any
|
|
leading <code><a href="#the-param-element">param</a></code> element children. This is the element's
|
|
<a href="content-models.html#fallback-content">fallback content</a>. If the element has an instantiated
|
|
<a href="infrastructure.html#plugin">plugin</a>, then unload it.</p></li>
|
|
|
|
</ol><p id="object-plugin">When the algorithm above instantiates a
|
|
<a href="infrastructure.html#plugin">plugin</a>, the user agent should pass to the
|
|
<a href="infrastructure.html#plugin">plugin</a> used the names and values of all the attributes
|
|
on the element, in the order they were added to the element, with
|
|
the attributes added by the parser being ordered in source order,
|
|
followed by a parameter named "PARAM" whose value is null,
|
|
followed by all the names and values of <a href="#concept-param-parameter" title="concept-param-parameter">parameters</a> given by
|
|
<code><a href="#the-param-element">param</a></code> elements that are children of the
|
|
<code><a href="#the-object-element">object</a></code> element, in <a href="infrastructure.html#tree-order">tree order</a>. If the
|
|
<a href="infrastructure.html#plugin">plugin</a> supports a scriptable interface, the
|
|
<code><a href="#htmlobjectelement">HTMLObjectElement</a></code> object representing the element
|
|
should expose that interface. The <code><a href="#the-object-element">object</a></code> element
|
|
<a href="rendering.html#represents">represents</a> the <a href="infrastructure.html#plugin">plugin</a>. The
|
|
<a href="infrastructure.html#plugin">plugin</a> is not a nested <a href="browsers.html#browsing-context">browsing
|
|
context</a>.</p>
|
|
|
|
<p id="sandboxPluginObject">If either:</p>
|
|
|
|
<ul><li>the <a href="#sandboxed-plugins-browsing-context-flag">sandboxed plugins browsing context flag</a> was
|
|
set on the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code>'s
|
|
<a href="browsers.html#browsing-context">browsing context</a> when the <code><a href="infrastructure.html#document">Document</a></code> was
|
|
created, or</li>
|
|
|
|
<li>the <code><a href="#the-object-element">object</a></code> element's <code><a href="infrastructure.html#document">Document</a></code> was
|
|
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></li>
|
|
|
|
</ul><p>...then the steps above must always act as if they had failed to
|
|
find a <a href="infrastructure.html#plugin">plugin</a>, even if one would otherwise have been
|
|
used.</p>
|
|
|
|
<p class="note">The above algorithm is independent of CSS properties
|
|
(including 'display', 'overflow', and 'visibility'). For example, it
|
|
runs even if the element is hidden with a 'display:none' CSS style,
|
|
and does not run <em>again</em> if the element's visibility
|
|
changes.</p>
|
|
|
|
<p>Due to the algorithm above, the contents of <code><a href="#the-object-element">object</a></code>
|
|
elements act as <a href="content-models.html#fallback-content">fallback content</a>, used only when
|
|
referenced resources can't be shown (e.g. because it returned a 404
|
|
error). This allows multiple <code><a href="#the-object-element">object</a></code> elements to be
|
|
nested inside each other, targeting multiple user agents with
|
|
different capabilities, with the user agent picking the first one it
|
|
supports.</p>
|
|
|
|
<p>Whenever the <code title="attr-object-name"><a href="#attr-object-name">name</a></code> attribute
|
|
is set, if the <code><a href="#the-object-element">object</a></code> element has a nested
|
|
<a href="browsers.html#browsing-context">browsing context</a>, its <a href="browsers.html#browsing-context-name" title="browsing context
|
|
name">name</a> must be changed to the new value. If the attribute
|
|
is removed, if the <code><a href="#the-object-element">object</a></code> element has a <a href="browsers.html#browsing-context">browsing
|
|
context</a>, the <a href="browsers.html#browsing-context-name">browsing context name</a> must be set
|
|
to the empty string.</p>
|
|
|
|
</div><p>The <code title="attr-hyperlink-usemap"><a href="the-map-element.html#attr-hyperlink-usemap">usemap</a></code> attribute,
|
|
if present while the <code><a href="#the-object-element">object</a></code> element represents an
|
|
image, can indicate that the object has an associated <a href="the-map-element.html#image-map">image
|
|
map</a>. <span class="impl">The attribute must be ignored if the
|
|
<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
|
|
explicitly associate the <code><a href="#the-object-element">object</a></code> element with its
|
|
<a href="association-of-controls-and-forms.html#form-owner">form owner</a>.</p><div class="impl">
|
|
|
|
<p><strong>Constraint validation</strong>: <code><a href="#the-object-element">object</a></code>
|
|
elements are always <a href="association-of-controls-and-forms.html#barred-from-constraint-validation">barred from constraint
|
|
validation</a>.</p>
|
|
|
|
</div><p>The <code><a href="#the-object-element">object</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
|
|
attributes</a>.</p><div class="impl">
|
|
|
|
<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
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
|
|
name.</p>
|
|
|
|
<p>The <dfn id="dom-object-contentdocument" title="dom-object-contentDocument"><code>contentDocument</code></dfn>
|
|
IDL attribute must return the <code><a href="infrastructure.html#document">Document</a></code> object of the
|
|
<a href="browsers.html#active-document">active document</a> of the <code><a href="#the-object-element">object</a></code> element's
|
|
<a href="browsers.html#nested-browsing-context">nested browsing context</a>, if it has one; otherwise, it
|
|
must return null.</p>
|
|
|
|
<p>The <dfn id="dom-object-contentwindow" title="dom-object-contentWindow"><code>contentWindow</code></dfn>
|
|
IDL attribute must return the <code><a href="browsers.html#windowproxy">WindowProxy</a></code> object of the
|
|
<code><a href="#the-object-element">object</a></code> element's <a href="browsers.html#nested-browsing-context">nested browsing context</a>,
|
|
if it has one; otherwise, it must return null.</p>
|
|
|
|
<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>
|
|
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>
|
|
methods, are part of the <a href="association-of-controls-and-forms.html#the-constraint-validation-api">constraint validation API</a>. The
|
|
<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
|
|
element's forms API.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>In the following example, a Java applet is embedded in a page
|
|
using the <code><a href="#the-object-element">object</a></code> element. (Generally speaking, it is
|
|
better to avoid using applets like these and instead use native
|
|
JavaScript and HTML to provide the functionality, since that way
|
|
the application will work on all Web browsers without requiring a
|
|
third-party plugin. Many devices, especially embedded devices, do
|
|
not support third-party technologies like Java.)</p>
|
|
|
|
<pre><figure>
|
|
<object type="application/x-java-applet">
|
|
<param name="code" value="MyJavaClass">
|
|
<p>You do not have Java available, or it is disabled.</p>
|
|
</object>
|
|
<figcaption>My Java Clock</figcaption>
|
|
</figure></pre>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>In this example, an HTML page is embedded in another using the
|
|
<code><a href="#the-object-element">object</a></code> element.</p>
|
|
|
|
<pre><figure>
|
|
<object data="clock.html"></object>
|
|
<figcaption>My HTML Clock</figcaption>
|
|
</figure></pre>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>The following example shows how a plugin can be used in HTML (in
|
|
this case the Flash plugin, to show a video file). Fallback is
|
|
provided for users who do not have Flash enabled, in this case
|
|
using the <code><a href="#the-video-element">video</a></code> element to show the video for those
|
|
using user agents that support <code><a href="#the-video-element">video</a></code>, and finally
|
|
providing a link to the video for those who have neither Flash nor
|
|
a <code><a href="#the-video-element">video</a></code>-capable browser.</p>
|
|
|
|
<pre><p>Look at my video:
|
|
<object type="application/x-shockwave-flash">
|
|
<param name=movie value="http://video.example.com/library/watch.swf">
|
|
<param name=allowfullscreen value=true>
|
|
<param name=flashvars value="http://video.example.com/vids/315981">
|
|
<video controls src="http://video.example.com/vids/315981">
|
|
<a href="http://video.example.com/vids/315981">View video</a>.
|
|
</video>
|
|
</object>
|
|
</p></pre>
|
|
|
|
</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>
|
|
<dd>None.</dd>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<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>
|
|
<dt>Content model:</dt>
|
|
<dd>Empty.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-param-name"><a href="#attr-param-name">name</a></code></dd>
|
|
<dd><code title="attr-param-value"><a href="#attr-param-value">value</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmlparamelement">HTMLParamElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
attribute DOMString <a href="#dom-param-name" title="dom-param-name">name</a>;
|
|
attribute DOMString <a href="#dom-param-value" title="dom-param-value">value</a>;
|
|
};</pre>
|
|
</dd>
|
|
</dl><p>The <code><a href="#the-param-element">param</a></code> element defines parameters for plugins
|
|
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>
|
|
attribute gives the name of the parameter.</p><p>The <dfn id="attr-param-value" title="attr-param-value"><code>value</code></dfn>
|
|
attribute gives the value of the parameter.</p><p>Both attributes must be present. They may have any value.</p><div class="impl">
|
|
|
|
<p>If both attributes are present, and if the parent element of the
|
|
<code><a href="#the-param-element">param</a></code> is an <code><a href="#the-object-element">object</a></code> element, then the
|
|
element defines a <dfn id="concept-param-parameter" title="concept-param-parameter">parameter</dfn> with the given
|
|
name/value pair.</p>
|
|
|
|
<p>If either the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> defined by a
|
|
<code><a href="#the-param-element">param</a></code> element that is the child of an
|
|
<code><a href="#the-object-element">object</a></code> element that <a href="rendering.html#represents">represents</a> an
|
|
instantiated <a href="infrastructure.html#plugin">plugin</a> changes, and if that
|
|
<a href="infrastructure.html#plugin">plugin</a> is communicating with the user agent using an
|
|
API that features the ability to update the <a href="infrastructure.html#plugin">plugin</a> when
|
|
the name or value of a <a href="#concept-param-parameter" title="concept-param-parameter">parameter</a> so changes, then
|
|
the user agent must appropriately exercise that ability to notify
|
|
the <a href="infrastructure.html#plugin">plugin</a> of the change.</p>
|
|
|
|
<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
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
|
|
name.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>The following example shows how the <code><a href="#the-param-element">param</a></code> element
|
|
can be used to pass a parameter to a plugin, in this case the O3D
|
|
plugin.</p>
|
|
|
|
<pre><!DOCTYPE HTML>
|
|
<html lang="en">
|
|
<head>
|
|
<title>O3D Utah Teapot</title>
|
|
</head>
|
|
<body>
|
|
<p>
|
|
<object type="application/vnd.o3d.auto">
|
|
<strong><param name="o3d_features" value="FloatingPointTextures"></strong>
|
|
<img src="o3d-teapot.png"
|
|
title="3D Utah Teapot illustration rendered using O3D."
|
|
alt="When O3D renders the Utah Teapot, it appears as a squat
|
|
teapot with a shiny metallic finish on which the
|
|
surroundings are reflected, with a faint shadow caused by
|
|
the lighting.">
|
|
<p>To see the teapot actually rendered by O3D on your
|
|
computer, please download and install the <a
|
|
href="http://code.google.com/apis/o3d/docs/gettingstarted.html#install">O3D plugin</a>.</p>
|
|
</object>
|
|
<script src="o3d-teapot.js"></script>
|
|
</p>
|
|
</body>
|
|
</html></pre>
|
|
|
|
</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>
|
|
<dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
|
|
<dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
|
|
<dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
|
|
<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>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
|
|
<dt>Content model:</dt>
|
|
<dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
|
|
zero or more <code><a href="#the-track-element">track</a></code> elements, then
|
|
<a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
|
|
<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
|
|
zero or more <code><a href="#the-track-element">track</a></code> elements, then
|
|
<a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
|
|
<dd><code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code></dd>
|
|
<dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
|
|
<dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
|
|
<dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
|
|
<dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
|
|
<dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
|
|
<dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
|
|
<dd><code title="attr-dim-width"><a href="the-map-element.html#attr-dim-width">width</a></code></dd>
|
|
<dd><code title="attr-dim-height"><a href="the-map-element.html#attr-dim-height">height</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmlvideoelement">HTMLVideoElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {
|
|
attribute unsigned long <a href="the-map-element.html#dom-dim-width" title="dom-dim-width">width</a>;
|
|
attribute unsigned long <a href="the-map-element.html#dom-dim-height" title="dom-dim-height">height</a>;
|
|
readonly attribute unsigned long <a href="#dom-video-videowidth" title="dom-video-videoWidth">videoWidth</a>;
|
|
readonly attribute unsigned long <a href="#dom-video-videoheight" title="dom-video-videoHeight">videoHeight</a>;
|
|
attribute DOMString <a href="#dom-video-poster" title="dom-video-poster">poster</a>;
|
|
};</pre>
|
|
</dd>
|
|
</dl><p>A <code><a href="#the-video-element">video</a></code> element is used for playing videos or
|
|
movies, and audio files with captions.</p><p>Content may be provided inside the <code><a href="#the-video-element">video</a></code>
|
|
element<span class="impl">. User agents should not show this content
|
|
to the user</span>; it is intended for older Web browsers which do
|
|
not support <code><a href="#the-video-element">video</a></code>, so that legacy video plugins can be
|
|
tried, or to show text to the users of these older browsers informing
|
|
them of how to access the video contents.</p><p class="note">In particular, this content is not intended to
|
|
address accessibility concerns. To make video content accessible to
|
|
the blind, deaf, and those with other physical or cognitive
|
|
disabilities, authors are expected to provide alternative media
|
|
streams and/or to embed accessibility aids (such as caption or
|
|
subtitle tracks, audio description tracks, or sign-language
|
|
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>
|
|
whose <a href="#media-data">media data</a> is ostensibly video data, possibly
|
|
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>,
|
|
<code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
|
|
<code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
|
|
<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
|
|
elements</a>.</p><p>The <dfn id="attr-video-poster" title="attr-video-poster"><code>poster</code></dfn>
|
|
attribute gives the address of an image file that the user agent can
|
|
show while no video data is available. The attribute, if present,
|
|
must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
|
|
spaces</a>.</p><div class="impl">
|
|
|
|
<p>If the specified resource is to be used, then, when the element
|
|
is created or when the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
|
|
attribute is set, changed, or removed, the user agent must run the
|
|
following steps to determine the element's <dfn id="poster-frame">poster
|
|
frame</dfn>:</p>
|
|
<ol><li><p>If there is an existing instance of this algorithm running
|
|
for this <code><a href="#the-video-element">video</a></code> element, abort that instance of this
|
|
algorithm without changing the <a href="#poster-frame">poster frame</a>.</p></li>
|
|
|
|
<li><p>If the <code title="attr-video-poster"><a href="#attr-video-poster">poster</a></code>
|
|
attribute's value is the empty string or if the attribute is
|
|
absent, then there is no <a href="#poster-frame">poster frame</a>; abort these
|
|
steps.</p></li>
|
|
|
|
<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
|
|
to the element. If this fails, then there is no <a href="#poster-frame">poster
|
|
frame</a>; abort these steps.</p></li>
|
|
|
|
<li><p><a href="fetching-resources.html#fetch">Fetch</a> the resulting <a href="urls.html#absolute-url">absolute URL</a>,
|
|
from the element's <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>.
|
|
This must <a href="the-end.html#delay-the-load-event">delay the load event</a> of the element's
|
|
document.</p></li>
|
|
|
|
|
|
|
|
<li><p>If an image is thus obtained, the <a href="#poster-frame">poster frame</a>
|
|
is that image. Otherwise, there is no <a href="#poster-frame">poster
|
|
frame</a>.</p></li>
|
|
|
|
</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
|
|
frame</a></i>, is intended to be a representative frame of the video
|
|
(typically one of the first non-blank frames) that gives the user an
|
|
idea of what the video is like.</p><div class="impl">
|
|
|
|
<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
|
|
<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
|
|
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
|
|
subsequent value but the <a href="#media-resource">media resource</a> does not have a
|
|
video channel), the <code><a href="#the-video-element">video</a></code> element
|
|
<a href="rendering.html#represents">represents</a> either the <a href="#poster-frame">poster frame</a>, or
|
|
nothing.</p>
|
|
|
|
<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
|
|
playback position">current playback position</a> is the first
|
|
frame of video, the element <a href="rendering.html#represents">represents</a> either the frame
|
|
of video corresponding to the <a href="#current-playback-position" title="current playback
|
|
position">current playback position</a> or the <a href="#poster-frame">poster
|
|
frame</a>, at the discretion of the user agent.</p>
|
|
|
|
<p>Notwithstanding the above, the <a href="#poster-frame">poster frame</a> should
|
|
be preferred over nothing, but the <a href="#poster-frame">poster frame</a> should
|
|
not be shown again after a frame of video has been shown.</p>
|
|
|
|
<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
|
|
the <a href="#media-resource">media resource</a> has a video channel, the element
|
|
<a href="rendering.html#represents">represents</a> the frame of video corresponding to the
|
|
<a href="#current-playback-position" title="current playback position">current playback
|
|
position</a>, or, if that is not yet available (e.g. because the
|
|
video is seeking or buffering), the last frame of the video to have
|
|
been rendered.</p>
|
|
|
|
<p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
|
|
resource</a> has a video channel is <a href="#potentially-playing">potentially
|
|
playing</a>, it <a href="rendering.html#represents">represents</a> the frame of video at the
|
|
continuously increasing <a href="#current-playback-position" title="current playback
|
|
position">"current" position</a>. When the <a href="#current-playback-position">current playback
|
|
position</a> changes such that the last frame rendered is no
|
|
longer the frame corresponding to the <a href="#current-playback-position">current playback
|
|
position</a> in the video, the new frame must be rendered.
|
|
|
|
Similarly, any audio associated with the <a href="#media-resource">media resource</a>
|
|
must, if played, be played synchronized with the <a href="#current-playback-position">current
|
|
playback position</a>, at the element's <a href="#effective-media-volume">effective media
|
|
volume</a>.</p>
|
|
|
|
<p>When a <code><a href="#the-video-element">video</a></code> element whose <a href="#media-resource">media
|
|
resource</a> has a video channel is neither <a href="#potentially-playing">potentially
|
|
playing</a> nor <a href="#dom-media-paused" title="dom-media-paused">paused</a>
|
|
(e.g. when seeking or stalled), the element <a href="rendering.html#represents">represents</a>
|
|
the last frame of the video to have been rendered.</p>
|
|
|
|
<p class="note">Which frame in a video stream corresponds to a
|
|
particular playback position is defined by the video stream's
|
|
format.</p>
|
|
|
|
<p>The <code><a href="#the-video-element">video</a></code> element also <a href="rendering.html#represents">represents</a> any
|
|
<a href="#text-track-cue" title="text track cue">text track cues</a> whose
|
|
<a href="#text-track-cue-active-flag">text track cue active flag</a> is set and whose
|
|
<a href="#text-track">text track</a> is in the <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> modes.</p>
|
|
|
|
<p>In addition to the above, the user agent may provide messages to
|
|
the user (such as "buffering", "no video loaded", "error", or more
|
|
detailed information) by overlaying text or icons on the video or
|
|
other areas of the element's playback area, or in another
|
|
appropriate manner.</p>
|
|
|
|
<p>User agents that cannot render the video may instead make the
|
|
element <a href="rendering.html#represents" title="represents">represent</a> a link to an
|
|
external video playback utility or to the video data itself.</p>
|
|
|
|
<hr></div><dl class="domintro"><dt><var title="">video</var> . <code title="dom-video-videoWidth"><a href="#dom-video-videowidth">videoWidth</a></code></dt>
|
|
<dt><var title="">video</var> . <code title="dom-video-videoHeight"><a href="#dom-video-videoheight">videoHeight</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>These attributes return the intrinsic dimensions of the video,
|
|
or zero if the dimensions are not known.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
|
|
width</dfn> and <dfn id="concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</dfn> of the
|
|
<a href="#media-resource">media resource</a> are the dimensions of the resource in
|
|
CSS pixels after taking into account the resource's dimensions,
|
|
aspect ratio, clean aperture, resolution, and so forth, as defined
|
|
for the format used by the resource. If an anamorphic format does
|
|
not define how to apply the aspect ratio to the video data's
|
|
dimensions to obtain the "correct" dimensions, then the user agent
|
|
must apply the ratio by increasing one dimension and leaving the
|
|
other unchanged.</p>
|
|
|
|
<p>The <dfn id="dom-video-videowidth" title="dom-video-videoWidth"><code>videoWidth</code></dfn> IDL
|
|
attribute must return the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic width</a> of the
|
|
video in CSS pixels. The <dfn id="dom-video-videoheight" title="dom-video-videoHeight"><code>videoHeight</code></dfn> IDL
|
|
attribute must return the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic height</a> of
|
|
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
|
|
attributes must return 0.</p>
|
|
|
|
</div><p>The <code><a href="#the-video-element">video</a></code> element supports <a href="the-map-element.html#dimension-attributes">dimension
|
|
attributes</a>.</p><div class="impl">
|
|
|
|
<p>In the absence of style rules to the contrary, video content
|
|
should be rendered inside the element's playback area such that the
|
|
video content is shown centered in the playback area at the largest
|
|
possible size that fits completely within it, with the video
|
|
content's aspect ratio being preserved. Thus, if the aspect ratio of
|
|
the playback area does not match the aspect ratio of the video, the
|
|
video will be shown letterboxed or pillarboxed. Areas of the
|
|
element's playback area that do not contain the video represent
|
|
nothing.</p>
|
|
|
|
<p class="note">In user agents that implement CSS, the above
|
|
requirement can be implemented by using the <a href="rendering.html#video-object-fit">style rule suggested in the rendering
|
|
section</a>.</p>
|
|
|
|
<p>The intrinsic width of a <code><a href="#the-video-element">video</a></code> element's playback
|
|
area is the <a href="#concept-video-intrinsic-width" title="concept-video-intrinsic-width">intrinsic
|
|
width</a> of the video resource, if that is available; otherwise
|
|
it is the intrinsic width of the <a href="#poster-frame">poster frame</a>, if that
|
|
is available; otherwise it is 300 CSS pixels.</p>
|
|
|
|
<p>The intrinsic height of a <code><a href="#the-video-element">video</a></code> element's playback
|
|
area is the <a href="#concept-video-intrinsic-height" title="concept-video-intrinsic-height">intrinsic
|
|
height</a> of the video resource, if that is available; otherwise
|
|
it is the intrinsic height of the <a href="#poster-frame">poster frame</a>, if that
|
|
is available; otherwise it is 150 CSS pixels.</p>
|
|
|
|
<hr><p>User agents should provide controls to enable or disable the
|
|
display of closed captions, audio description tracks, and other
|
|
additional data associated with the video stream, though such
|
|
features should, again, not interfere with the page's normal
|
|
rendering.</p>
|
|
|
|
<p>User agents may allow users to view the video content in manners
|
|
more suitable to the user (e.g. full-screen or in an independent
|
|
resizable window). As for the other user interface features,
|
|
controls to enable this should not interfere with the page's normal
|
|
rendering unless the user agent is <a href="#expose-a-user-interface-to-the-user" title="expose a user
|
|
interface to the user">exposing a user interface</a>. In such an
|
|
independent context, however, user agents may make full user
|
|
interfaces visible, with, e.g., play, pause, seeking, and volume
|
|
controls, even if the <code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code> attribute is absent.</p>
|
|
|
|
<p>User agents may allow video playback to affect system features
|
|
that could interfere with the user's experience; for example, user
|
|
agents could disable screensavers while video playback is in
|
|
progress.</p>
|
|
|
|
<hr><p>The <dfn id="dom-video-poster" title="dom-video-poster"><code>poster</code></dfn> IDL
|
|
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>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>This example shows how to detect when a video has failed to play
|
|
correctly:</p>
|
|
|
|
<pre><script>
|
|
function failed(e) {
|
|
// video playback failed - show a message saying why
|
|
switch (e.target.error.code) {
|
|
case e.target.error.MEDIA_ERR_ABORTED:
|
|
alert('You aborted the video playback.');
|
|
break;
|
|
case e.target.error.MEDIA_ERR_NETWORK:
|
|
alert('A network error caused the video download to fail part-way.');
|
|
break;
|
|
case e.target.error.MEDIA_ERR_DECODE:
|
|
alert('The video playback was aborted due to a corruption problem or because the video used features your browser did not support.');
|
|
break;
|
|
case e.target.error.MEDIA_ERR_SRC_NOT_SUPPORTED:
|
|
alert('The video could not be loaded, either because the server or network failed or because the format is not supported.');
|
|
break;
|
|
default:
|
|
alert('An unknown error occurred.');
|
|
break;
|
|
}
|
|
}
|
|
</script>
|
|
<p><video src="tgif.vid" autoplay controls onerror="failed(event)"></video></p>
|
|
<p><a href="tgif.vid">Download the video file</a>.</p></pre>
|
|
|
|
</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>
|
|
<dd><a href="content-models.html#flow-content">Flow content</a>.</dd>
|
|
<dd><a href="content-models.html#phrasing-content">Phrasing content</a>.</dd>
|
|
<dd><a href="content-models.html#embedded-content">Embedded content</a>.</dd>
|
|
<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>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<dd>Where <a href="content-models.html#embedded-content">embedded content</a> is expected.</dd>
|
|
<dt>Content model:</dt>
|
|
<dd>If the element has a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute:
|
|
zero or more <code><a href="#the-track-element">track</a></code> elements, then
|
|
<a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
|
|
<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
|
|
zero or more <code><a href="#the-track-element">track</a></code> elements, then
|
|
<a href="content-models.html#transparent">transparent</a>, but with no <a href="#media-element">media element</a> descendants.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-media-src"><a href="#attr-media-src">src</a></code></dd>
|
|
<dd><code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code></dd>
|
|
<dd><code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code></dd>
|
|
<dd><code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code></dd>
|
|
<dd><code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code></dd>
|
|
<dd><code title="attr-media-muted"><a href="#attr-media-muted">muted</a></code></dd>
|
|
<dd><code title="attr-media-controls"><a href="#attr-media-controls">controls</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">[NamedConstructor=<a href="#dom-audio" title="dom-Audio">Audio</a>(),
|
|
NamedConstructor=<a href="#dom-audio-s" title="dom-Audio-s">Audio</a>(in DOMString src)]
|
|
interface <dfn id="htmlaudioelement">HTMLAudioElement</dfn> : <a href="#htmlmediaelement">HTMLMediaElement</a> {};</pre>
|
|
</dd>
|
|
</dl><p>An <code><a href="#the-audio-element">audio</a></code> element <a href="rendering.html#represents">represents</a> a sound or
|
|
audio stream.</p><p>Content may be provided inside the <code><a href="#the-audio-element">audio</a></code>
|
|
element<span class="impl">. User agents should not show this content
|
|
to the user</span>; it is intended for older Web browsers which do
|
|
not support <code><a href="#the-audio-element">audio</a></code>, so that legacy audio plugins can be
|
|
tried, or to show text to the users of these older browsers informing
|
|
them of how to access the audio contents.</p><p class="note">In particular, this content is not intended to
|
|
address accessibility concerns. To make audio content accessible to
|
|
the deaf or to those with other physical or cognitive disabilities,
|
|
authors are expected to provide alternative media streams and/or to
|
|
embed accessibility aids (such as transcriptions) into their media
|
|
streams.</p><p>The <code><a href="#the-audio-element">audio</a></code> element is a <a href="#media-element">media element</a>
|
|
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>,
|
|
<code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
|
|
<code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
|
|
<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
|
|
elements</a>.</p><div class="impl">
|
|
|
|
<p>When an <code><a href="#the-audio-element">audio</a></code> element is <a href="#potentially-playing">potentially
|
|
playing</a>, it must have its audio data played synchronized with
|
|
the <a href="#current-playback-position">current playback position</a>, at the element's
|
|
<a href="#effective-media-volume">effective media volume</a>.</p>
|
|
|
|
<p>When an <code><a href="#the-audio-element">audio</a></code> element is not <a href="#potentially-playing">potentially
|
|
playing</a>, audio must not play for the element.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<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
|
|
passed in the argument, if applicable.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>Two constructors are provided for creating
|
|
<code><a href="#htmlaudioelement">HTMLAudioElement</a></code> objects (in addition to the factory
|
|
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,
|
|
these must return a new <code><a href="#htmlaudioelement">HTMLAudioElement</a></code> object (a new
|
|
<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
|
|
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
|
|
its <code title="attr-media-src"><a href="#attr-media-src">src</a></code> content attribute set to
|
|
the provided value, and the user agent must invoke the object's
|
|
<a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> before returning. The element's document must be
|
|
the <a href="browsers.html#active-document">active document</a> of the <a href="browsers.html#browsing-context">browsing
|
|
context</a> of the <code><a href="browsers.html#window">Window</a></code> object on which the
|
|
interface object of the invoked constructor is found.</p>
|
|
|
|
</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>
|
|
<dd>None.</dd>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<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>
|
|
or <code><a href="#the-track-element">track</a></code> elements.</dd>
|
|
<dt>Content model:</dt>
|
|
<dd>Empty.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-source-src"><a href="#attr-source-src">src</a></code></dd>
|
|
<dd><code title="attr-source-type"><a href="#attr-source-type">type</a></code></dd>
|
|
<dd><code title="attr-source-media"><a href="#attr-source-media">media</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmlsourceelement">HTMLSourceElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
attribute DOMString <a href="#dom-source-src" title="dom-source-src">src</a>;
|
|
attribute DOMString <a href="#dom-source-type" title="dom-source-type">type</a>;
|
|
attribute DOMString <a href="#dom-source-media" title="dom-source-media">media</a>;
|
|
};</pre>
|
|
</dd>
|
|
</dl><p>The <code><a href="#the-source-element">source</a></code> element allows authors to specify
|
|
multiple alternative <a href="#media-resource" title="media resource">media
|
|
resources</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-source-src" title="attr-source-src"><code>src</code></dfn> attribute
|
|
gives the address of the <a href="#media-resource">media resource</a>. The value must
|
|
be a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
|
|
spaces</a>. This attribute must be present.</p><p class="note">Dynamically modifying a <code><a href="#the-source-element">source</a></code> element
|
|
and its attribute when the element is already inserted in a
|
|
<code><a href="#the-video-element">video</a></code> or <code><a href="#the-audio-element">audio</a></code> element will have no
|
|
effect. To change what is playing, either just use the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute on the <a href="#media-element">media
|
|
element</a> directly, or call the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code> method on the <a href="#media-element">media
|
|
element</a> after manipulating the <code><a href="#the-source-element">source</a></code>
|
|
elements.</p><p>The <dfn id="attr-source-type" title="attr-source-type"><code>type</code></dfn>
|
|
attribute gives the type of the <a href="#media-resource">media resource</a>, to help
|
|
the user agent determine if it can play this <a href="#media-resource">media
|
|
resource</a> before fetching it. If specified, its value must be
|
|
a <a href="infrastructure.html#valid-mime-type">valid MIME type</a>. The <code title="">codecs</code>
|
|
parameter, which certain MIME types define, might be necessary to
|
|
specify exactly how the resource is encoded. <a href="references.html#refsRFC4281">[RFC4281]</a></p><div class="example">
|
|
|
|
<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>
|
|
|
|
<dl><dt>H.264 Constrained baseline profile video (main and extended video compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
|
|
<dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'></pre></dd>
|
|
|
|
<dt>H.264 Extended profile video (baseline-compatible) level 3 and Low-Complexity AAC audio in MP4 container</dt>
|
|
<dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.58A01E, mp4a.40.2"'></pre></dd>
|
|
|
|
<dt>H.264 Main profile video level 3 and Low-Complexity AAC audio in MP4 container</dt>
|
|
<dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.4D401E, mp4a.40.2"'></pre></dd>
|
|
|
|
<dt>H.264 'High' profile video (incompatible with main, baseline, or extended profiles) level 3 and Low-Complexity AAC audio in MP4 container</dt>
|
|
<dd><pre><source src='video.mp4' type='video/mp4; codecs="avc1.64001E, mp4a.40.2"'></pre></dd>
|
|
|
|
|
|
<dt>MPEG-4 Visual Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
|
|
<dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.8, mp4a.40.2"'></pre></dd>
|
|
|
|
<dt>MPEG-4 Advanced Simple Profile Level 0 video and Low-Complexity AAC audio in MP4 container</dt>
|
|
<dd><pre><source src='video.mp4' type='video/mp4; codecs="mp4v.20.240, mp4a.40.2"'></pre></dd>
|
|
|
|
<dt>MPEG-4 Visual Simple Profile Level 0 video and AMR audio in 3GPP container</dt>
|
|
<dd><pre><source src='video.3gp' type='video/3gpp; codecs="mp4v.20.8, samr"'></pre></dd>
|
|
|
|
|
|
<dt>Theora video and Vorbis audio in Ogg container</dt>
|
|
<dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'></pre></dd>
|
|
|
|
<dt>Theora video and Speex audio in Ogg container</dt>
|
|
<dd><pre><source src='video.ogv' type='video/ogg; codecs="theora, speex"'></pre></dd>
|
|
|
|
<dt>Vorbis audio alone in Ogg container</dt>
|
|
<dd><pre><source src='audio.ogg' type='audio/ogg; codecs=vorbis'></pre></dd>
|
|
|
|
<dt>Speex audio alone in Ogg container</dt>
|
|
<dd><pre><source src='audio.spx' type='audio/ogg; codecs=speex'></pre></dd>
|
|
|
|
<dt>FLAC audio alone in Ogg container</dt>
|
|
<dd><pre><source src='audio.oga' type='audio/ogg; codecs=flac'></pre></dd>
|
|
|
|
<dt>Dirac video and Vorbis audio in Ogg container</dt>
|
|
<dd><pre><source src='video.ogv' type='video/ogg; codecs="dirac, vorbis"'></pre></dd>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
</dl></div><p>The <dfn id="attr-source-media" title="attr-source-media"><code>media</code></dfn>
|
|
attribute gives the intended media type of the <a href="#media-resource">media
|
|
resource</a>, to help the user agent determine if this
|
|
<a href="#media-resource">media resource</a> is useful to the user before fetching
|
|
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
|
|
"<code title="">all</code>", meaning that by default the <a href="#media-resource">media
|
|
resource</a> is suitable for all media.</p><div class="impl">
|
|
|
|
<p>If a <code><a href="#the-source-element">source</a></code> element is inserted as a child of a
|
|
<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
|
|
<code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, the user
|
|
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
|
|
algorithm</a>.</p>
|
|
|
|
<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
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the same
|
|
name.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>If the author isn't sure if the user agents will all be able to
|
|
render the media resources provided, the author can listen to the
|
|
<code title="event-error">error</code> event on the last
|
|
<code><a href="#the-source-element">source</a></code> element and trigger fallback behavior:</p>
|
|
|
|
<pre><script>
|
|
function fallback(video) {
|
|
// replace <video> with its contents
|
|
while (video.hasChildNodes()) {
|
|
if (video.firstChild instanceof HTMLSourceElement)
|
|
video.removeChild(video.firstChild);
|
|
else
|
|
video.parentNode.insertBefore(video.firstChild, video);
|
|
}
|
|
video.parentNode.removeChild(video);
|
|
}
|
|
</script>
|
|
<video controls autoplay>
|
|
<source src='video.mp4' type='video/mp4; codecs="avc1.42E01E, mp4a.40.2"'>
|
|
<source src='video.ogv' type='video/ogg; codecs="theora, vorbis"'
|
|
onerror="fallback(parentNode)">
|
|
...
|
|
</video></pre>
|
|
|
|
</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>
|
|
<dd>None.</dd>
|
|
<dt>Contexts in which this element can be used:</dt>
|
|
<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>
|
|
<dt>Content model:</dt>
|
|
<dd>Empty.</dd>
|
|
<dt>Content attributes:</dt>
|
|
<dd><a href="elements.html#global-attributes">Global attributes</a></dd>
|
|
<dd><code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code></dd>
|
|
<dd><code title="attr-track-src"><a href="#attr-track-src">src</a></code></dd>
|
|
<dd><code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code></dd>
|
|
<dd><code title="attr-track-label"><a href="#attr-track-label">label</a></code></dd>
|
|
<dd><code title="attr-track-default"><a href="#attr-track-default">default</a></code></dd>
|
|
<dt>DOM interface:</dt>
|
|
<dd>
|
|
<pre class="idl">interface <dfn id="htmltrackelement">HTMLTrackElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
attribute DOMString <a href="#dom-track-kind" title="dom-track-kind">kind</a>;
|
|
attribute DOMString <a href="#dom-track-src" title="dom-track-src">src</a>;
|
|
attribute DOMString <a href="#dom-track-srclang" title="dom-track-srclang">srclang</a>;
|
|
attribute DOMString <a href="#dom-track-label" title="dom-track-label">label</a>;
|
|
attribute boolean <a href="#dom-track-default" title="dom-track-default">default</a>;
|
|
|
|
readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-track-track" title="dom-track-track">track</a>;
|
|
};</pre>
|
|
</dd>
|
|
</dl><p>The <code><a href="#the-track-element">track</a></code> element allows authors to specify explicit
|
|
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>
|
|
attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following
|
|
table lists the keywords defined for this attribute. The keyword
|
|
given in the first cell of each row maps to the state given in the
|
|
second cell.</p><table><thead><tr><th>Keyword
|
|
</th><th>State
|
|
</th><th>Brief description
|
|
</th></tr></thead><tbody><tr><td><dfn id="attr-track-kind-keyword-subtitles" title="attr-track-kind-keyword-subtitles"><code>subtitles</code></dfn>
|
|
</td><td><dfn id="attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</dfn>
|
|
</td><td>
|
|
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).
|
|
Displayed over the video.
|
|
</td></tr><tr><td><dfn id="attr-track-kind-keyword-captions" title="attr-track-kind-keyword-captions"><code>captions</code></dfn>
|
|
</td><td><dfn id="attr-track-kind-captions" title="attr-track-kind-captions">Captions</dfn>
|
|
</td><td>
|
|
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).
|
|
Displayed over the video; labeled as appropriate for the hard-of-hearing.
|
|
</td></tr><tr><td><dfn id="attr-track-kind-keyword-descriptions" title="attr-track-kind-keyword-descriptions"><code>descriptions</code></dfn>
|
|
</td><td><dfn id="attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</dfn>
|
|
</td><td>
|
|
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).
|
|
Synthesized as separate audio track.
|
|
</td></tr><tr><td><dfn id="attr-track-kind-keyword-chapters" title="attr-track-kind-keyword-chapters"><code>chapters</code></dfn>
|
|
</td><td><dfn id="attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</dfn>
|
|
</td><td>
|
|
Chapter titles, intended to be used for navigating the <a href="#media-resource">media resource</a>.
|
|
Displayed as an interactive list in the user agent's interface.
|
|
</td></tr><tr><td><dfn id="attr-track-kind-keyword-metadata" title="attr-track-kind-keyword-metadata"><code>metadata</code></dfn>
|
|
</td><td><dfn id="attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</dfn>
|
|
</td><td>
|
|
Tracks intended for use from script.
|
|
Not displayed by the user agent.
|
|
</td></tr></tbody></table><p>The attribute may be omitted. The <i>missing value default</i> is
|
|
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
|
|
gives the address of the text track data. The value must be a
|
|
<a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty URL potentially surrounded by
|
|
spaces</a>. This attribute must be present.</p><div class="impl">
|
|
|
|
<p>If the element has a <code title="attr-track-src"><a href="#attr-track-src">src</a></code>
|
|
attribute whose value is not the empty string and whose value, when
|
|
the attribute was set, could be successfully <a href="urls.html#resolve-a-url" title="resolve a
|
|
url">resolved</a> relative to the element, then the element's
|
|
<dfn id="track-url">track URL</dfn> is the resulting <a href="urls.html#absolute-url">absolute
|
|
URL</a>. Otherwise, the element's <a href="#track-url">track URL</a> is the
|
|
empty string.</p>
|
|
|
|
</div><p>The <dfn id="attr-track-srclang" title="attr-track-srclang"><code>srclang</code></dfn>
|
|
attribute gives the language of the text track data. The value must
|
|
be a valid BCP 47 language tag. This attribute must be present if
|
|
the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute is
|
|
in the <a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">subtitles</a>
|
|
state. <a href="references.html#refsBCP47">[BCP47]</a></p><div class="impl">
|
|
|
|
<p>If the element has a <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code> attribute whose value is
|
|
not the empty string, then the element's <dfn id="track-language">track language</dfn>
|
|
is the value of the attribute. Otherwise, the element has no
|
|
<a href="#track-language">track language</a>.</p>
|
|
|
|
</div><p>The <dfn id="attr-track-label" title="attr-track-label"><code>label</code></dfn>
|
|
attribute gives a user-readable title for the track. This title is
|
|
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
|
|
in their user interface.</p><p>The value of the <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
|
|
attribute, if the attribute is present, must not be the empty
|
|
string. Furthermore, there must not be two <code><a href="#the-track-element">track</a></code>
|
|
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
|
|
state, whose <code title="attr-track-srclang"><a href="#attr-track-srclang">srclang</a></code>
|
|
attributes are both missing or have values that represent the same
|
|
language, and whose <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
|
|
attributes are again both missing or both have the same value.</p><div class="impl">
|
|
|
|
<p>If the element has a <code title="attr-track-label"><a href="#attr-track-label">label</a></code>
|
|
attribute whose value is not the empty string, then the element's
|
|
<dfn id="track-label">track label</dfn> is the value of the attribute. Otherwise, the
|
|
element's <a href="#track-label">track label</a> is a user-agent defined string
|
|
(e.g. the string "untitled" in the user's locale, or a value
|
|
automatically generated from the other attributes).</p>
|
|
|
|
</div><p>The <dfn id="attr-track-default" title="attr-track-default"><code>default</code></dfn>
|
|
attribute, if specified, indicates that the track is to be enabled
|
|
if the user's preferences do not indicate that another track would
|
|
be more appropriate. There must not be more than one
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<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>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-track-track" title="dom-track-track"><code>track</code></dfn> IDL
|
|
attribute must, on getting, return the <code><a href="#the-track-element">track</a></code> element's
|
|
<a href="#text-track">text track</a>'s corresponding <code><a href="#texttrack">TextTrack</a></code>
|
|
object.</p>
|
|
|
|
<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
|
|
must <a href="common-dom-interfaces.html#reflect">reflect</a> the respective content attributes of the
|
|
same name. The <dfn id="dom-track-kind" title="dom-track-kind"><code>kind</code></dfn>
|
|
IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
|
|
same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>This video has subtitles in several languages:</p>
|
|
|
|
<pre><video src="brave.webm">
|
|
<track kind=subtitles src=brave.en.vtt srclang=en label="English">
|
|
<track kind=captions src=brave.en.vtt srclang=en label="English for the Hard of Hearing">
|
|
<track kind=subtitles src=brave.fr.vtt srclang=fr label="Français">
|
|
<track kind=subtitles src=brave.de.vtt srclang=de label="Deutsch">
|
|
</video></pre>
|
|
|
|
</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>
|
|
(<code><a href="#the-audio-element">audio</a></code> and <code><a href="#the-video-element">video</a></code>, in this specification)
|
|
implement the following interface:</p><pre class="idl">interface <dfn id="htmlmediaelement">HTMLMediaElement</dfn> : <a href="elements.html#htmlelement">HTMLElement</a> {
|
|
|
|
// error state
|
|
readonly attribute <a href="#mediaerror">MediaError</a> <a href="#dom-media-error" title="dom-media-error">error</a>;
|
|
|
|
// network state
|
|
attribute DOMString <a href="#dom-media-src" title="dom-media-src">src</a>;
|
|
readonly attribute DOMString <a href="#dom-media-currentsrc" title="dom-media-currentSrc">currentSrc</a>;
|
|
const unsigned short <a href="#dom-media-network_empty" title="dom-media-NETWORK_EMPTY">NETWORK_EMPTY</a> = 0;
|
|
const unsigned short <a href="#dom-media-network_idle" title="dom-media-NETWORK_IDLE">NETWORK_IDLE</a> = 1;
|
|
const unsigned short <a href="#dom-media-network_loading" title="dom-media-NETWORK_LOADING">NETWORK_LOADING</a> = 2;
|
|
const unsigned short <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a> = 3;
|
|
readonly attribute unsigned short <a href="#dom-media-networkstate" title="dom-media-networkState">networkState</a>;
|
|
attribute DOMString <a href="#dom-media-preload" title="dom-media-preload">preload</a>;
|
|
readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-buffered" title="dom-media-buffered">buffered</a>;
|
|
void <a href="#dom-media-load" title="dom-media-load">load</a>();
|
|
DOMString <a href="#dom-navigator-canplaytype" title="dom-navigator-canPlayType">canPlayType</a>(in DOMString type);
|
|
|
|
// ready state
|
|
const unsigned short <a href="#dom-media-have_nothing" title="dom-media-HAVE_NOTHING">HAVE_NOTHING</a> = 0;
|
|
const unsigned short <a href="#dom-media-have_metadata" title="dom-media-HAVE_METADATA">HAVE_METADATA</a> = 1;
|
|
const unsigned short <a href="#dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA">HAVE_CURRENT_DATA</a> = 2;
|
|
const unsigned short <a href="#dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA">HAVE_FUTURE_DATA</a> = 3;
|
|
const unsigned short <a href="#dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA">HAVE_ENOUGH_DATA</a> = 4;
|
|
readonly attribute unsigned short <a href="#dom-media-readystate" title="dom-media-readyState">readyState</a>;
|
|
readonly attribute boolean <a href="#dom-media-seeking" title="dom-media-seeking">seeking</a>;
|
|
|
|
// playback state
|
|
attribute double <a href="#dom-media-currenttime" title="dom-media-currentTime">currentTime</a>;
|
|
readonly attribute double <a href="#dom-media-initialtime" title="dom-media-initialTime">initialTime</a>;
|
|
readonly attribute double <a href="#dom-media-duration" title="dom-media-duration">duration</a>;
|
|
readonly attribute <span>Date</span> <a href="#dom-media-startoffsettime" title="dom-media-startOffsetTime">startOffsetTime</a>;
|
|
readonly attribute boolean <a href="#dom-media-paused" title="dom-media-paused">paused</a>;
|
|
attribute double <a href="#dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate">defaultPlaybackRate</a>;
|
|
attribute double <a href="#dom-media-playbackrate" title="dom-media-playbackRate">playbackRate</a>;
|
|
readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-played" title="dom-media-played">played</a>;
|
|
readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-media-seekable" title="dom-media-seekable">seekable</a>;
|
|
readonly attribute boolean <a href="#dom-media-ended" title="dom-media-ended">ended</a>;
|
|
attribute boolean <a href="#dom-media-autoplay" title="dom-media-autoplay">autoplay</a>;
|
|
attribute boolean <a href="#dom-media-loop" title="dom-media-loop">loop</a>;
|
|
void <a href="#dom-media-play" title="dom-media-play">play</a>();
|
|
void <a href="#dom-media-pause" title="dom-media-pause">pause</a>();
|
|
|
|
// media controller
|
|
attribute <span>DOMString</span> <a href="#dom-media-mediagroup" title="dom-media-mediaGroup">mediaGroup</a>;
|
|
attribute <a href="#mediacontroller">MediaController</a> <a href="#dom-media-controller" title="dom-media-controller">controller</a>;
|
|
|
|
// controls
|
|
attribute boolean <a href="#dom-media-controls" title="dom-media-controls">controls</a>;
|
|
attribute double <a href="#dom-media-volume" title="dom-media-volume">volume</a>;
|
|
attribute boolean <a href="#dom-media-muted" title="dom-media-muted">muted</a>;
|
|
attribute boolean <a href="#dom-media-defaultmuted" title="dom-media-defaultMuted">defaultMuted</a>;
|
|
|
|
// tracks
|
|
readonly attribute <a href="#multipletracklist">MultipleTrackList</a> <a href="#dom-media-audiotracks" title="dom-media-audioTracks">audioTracks</a>;
|
|
readonly attribute <a href="#exclusivetracklist">ExclusiveTrackList</a> <a href="#dom-media-videotracks" title="dom-media-videoTracks">videoTracks</a>;
|
|
readonly attribute <a href="#texttrack">TextTrack</a>[] <a href="#dom-media-texttracks" title="dom-media-textTracks">textTracks</a>;
|
|
<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);
|
|
};</pre><p>The <dfn id="media-element-attributes">media element attributes</dfn>, <code title="attr-media-src"><a href="#attr-media-src">src</a></code>, <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code>, <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code>,
|
|
<code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>,
|
|
<code title="attr-media-loop"><a href="#attr-media-loop">loop</a></code>,
|
|
<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
|
|
this section.</p><p><a href="#media-element" title="media element">Media elements</a> are used to
|
|
present audio data, or video and audio data, to the user. This is
|
|
referred to as <dfn id="media-data">media data</dfn> in this section, since this
|
|
section applies equally to <a href="#media-element" title="media element">media
|
|
elements</a> for audio or for video.
|
|
The term <dfn id="media-resource">media resource</dfn> is used to refer to the complete
|
|
set of media data, e.g. the complete video file, or complete audio
|
|
file.
|
|
</p><p>A <a href="#media-resource">media resource</a> can have multiple audio and video
|
|
tracks. For the purposes of a <a href="#media-element">media element</a>, the video
|
|
data of the <a href="#media-resource">media resource</a> is only that of the
|
|
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
|
|
audio data of the <a href="#media-resource">media resource</a> is the result of
|
|
mixing all the currently enabled tracks (if any) given by the
|
|
element's <code title="dom-media-audioTracks"><a href="#dom-media-audiotracks">audioTracks</a></code>
|
|
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>
|
|
elements can be used for both audio and video. The main difference
|
|
between the two is simply that the <code><a href="#the-audio-element">audio</a></code> element has no
|
|
playback area for visual content (such as video or captions),
|
|
whereas the <code><a href="#the-video-element">video</a></code> element does.</p><div class="impl">
|
|
|
|
<p>Except where otherwise specified, the <a href="webappapis.html#task-source">task source</a>
|
|
for all the tasks <a href="webappapis.html#queue-a-task" title="queue a task">queued</a> in this
|
|
section and its subsections is the <dfn id="media-element-event-task-source">media element event task
|
|
source</dfn>.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#mediaerror">MediaError</a></code> object representing the
|
|
current error state of the element.</p>
|
|
|
|
<p>Returns null if there is no error.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>All <a href="#media-element" title="media element">media elements</a> have an
|
|
associated error status, which records the last error the element
|
|
encountered since its <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> was last invoked. The <dfn id="dom-media-error" title="dom-media-error"><code>error</code></dfn> attribute, on
|
|
getting, must return the <code><a href="#mediaerror">MediaError</a></code> object created for
|
|
this last error, or null if there has not been an error.</p>
|
|
|
|
</div><pre class="idl">interface <dfn id="mediaerror">MediaError</dfn> {
|
|
const unsigned short <a href="#dom-mediaerror-media_err_aborted" title="dom-MediaError-MEDIA_ERR_ABORTED">MEDIA_ERR_ABORTED</a> = 1;
|
|
const unsigned short <a href="#dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK">MEDIA_ERR_NETWORK</a> = 2;
|
|
const unsigned short <a href="#dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE">MEDIA_ERR_DECODE</a> = 3;
|
|
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;
|
|
readonly attribute unsigned short <a href="#dom-mediaerror-code" title="dom-MediaError-code">code</a>;
|
|
};</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current error's error code, from the list below.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-mediaerror-code" title="dom-MediaError-code"><code>code</code></dfn>
|
|
attribute of a <code><a href="#mediaerror">MediaError</a></code> object must return the code
|
|
for the error, which must be one of the following:</p>
|
|
|
|
</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>
|
|
|
|
<dd>The fetching process for the <a href="#media-resource">media resource</a> was
|
|
aborted by the user agent at the user's request.</dd>
|
|
|
|
<dt><dfn id="dom-mediaerror-media_err_network" title="dom-MediaError-MEDIA_ERR_NETWORK"><code>MEDIA_ERR_NETWORK</code></dfn> (numeric value 2)</dt>
|
|
|
|
<dd>A network error of some description caused the user agent to
|
|
stop fetching the <a href="#media-resource">media resource</a>, after the resource
|
|
was established to be usable.</dd>
|
|
|
|
<dt><dfn id="dom-mediaerror-media_err_decode" title="dom-MediaError-MEDIA_ERR_DECODE"><code>MEDIA_ERR_DECODE</code></dfn> (numeric value 3)</dt>
|
|
|
|
<dd>An error of some description occurred while decoding the
|
|
<a href="#media-resource">media resource</a>, after the resource was established to
|
|
be usable.</dd>
|
|
|
|
<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>
|
|
|
|
<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>
|
|
|
|
</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
|
|
attribute on <a href="#media-element" title="media element">media elements</a> gives
|
|
the address of the media resource (video, audio) to show. The
|
|
attribute, if present, must contain a <a href="urls.html#valid-non-empty-url-potentially-surrounded-by-spaces">valid non-empty
|
|
URL potentially surrounded by spaces</a>.</p><div class="impl">
|
|
|
|
<p>If a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute of a
|
|
<a href="#media-element">media element</a> is set or changed, the user agent must
|
|
invoke the <a href="#media-element">media element</a>'s <a href="#media-element-load-algorithm">media element load
|
|
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
|
|
if there are <code><a href="#the-source-element">source</a></code> elements present.)</p>
|
|
|
|
<p>The <dfn id="dom-media-src" title="dom-media-src"><code>src</code></dfn> IDL
|
|
attribute on <a href="#media-element" title="media element">media elements</a> must
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the same name.</p>
|
|
|
|
</div><dl class="domintro"><dt><var title="">media</var> . <code title="dom-media-currentSrc"><a href="#dom-media-currentsrc">currentSrc</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the address of the current <a href="#media-resource">media resource</a>.</p>
|
|
|
|
<p>Returns the empty string when there is no <a href="#media-resource">media resource</a>.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-currentsrc" title="dom-media-currentSrc"><code>currentSrc</code></dfn> IDL
|
|
attribute is initially the empty string. Its value is changed by the
|
|
<a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> defined below.</p>
|
|
|
|
</div><p class="note">There are two ways to specify a <a href="#media-resource">media
|
|
resource</a>, the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
|
|
attribute, or <code><a href="#the-source-element">source</a></code> elements. The attribute overrides
|
|
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
|
|
<em>type</em>, specifically a <a href="infrastructure.html#mime-type">MIME type</a>, in some cases
|
|
with a <code title="">codecs</code> parameter. (Whether the <code title="">codecs</code> parameter is allowed or not depends on the
|
|
MIME type.) <a href="references.html#refsRFC4281">[RFC4281]</a></p><p>Types are usually somewhat incomplete descriptions; for example
|
|
"<code title="">video/mpeg</code>" doesn't say anything except what
|
|
the container type is, and even a type like "<code title="">video/mp4; codecs="avc1.42E01E,
|
|
mp4a.40.2"</code>" doesn't include information like the actual
|
|
bitrate (only the maximum bitrate). Thus, given a type, a user agent
|
|
can often only know whether it <em>might</em> be able to play
|
|
media of that type (with varying levels of confidence), or whether
|
|
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
|
|
one that describes a resource that the user agent definitely does
|
|
not support, for example because it doesn't recognize the container
|
|
type, or it doesn't support the listed codecs.</p><p>The <a href="infrastructure.html#mime-type">MIME type</a>
|
|
"<code>application/octet-stream</code>" with no parameters is never
|
|
<a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user agent knows it cannot render</a>. User
|
|
agents must treat that type as equivalent to the lack of any
|
|
explicit <a href="fetching-resources.html#content-type" title="Content-Type">Content-Type metadata</a>
|
|
when it is used to label a potential <a href="#media-resource">media
|
|
resource</a>.</p><p class="note">
|
|
"<code>application/octet-stream</code>"
|
|
is special-cased here; if any parameter appears with it, it
|
|
should
|
|
|
|
be treated just like any other <a href="infrastructure.html#mime-type">MIME type</a>.
|
|
|
|
This is a deviation from the rule that unknown <a href="infrastructure.html#mime-type">MIME type</a> parameters
|
|
should be ignored.
|
|
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the empty string (a negative response), "maybe", or
|
|
"probably" based on how confident the user agent is that it can
|
|
play media resources of the given type.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-navigator-canplaytype" title="dom-navigator-canPlayType"><code>canPlayType(<var title="">type</var>)</code></dfn> method must return the empty
|
|
string if <var title="">type</var> is <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that the user
|
|
agent knows it cannot render</a> or is the type
|
|
"<code>application/octet-stream</code>"; it must return "<code title="">probably</code>" if the user agent is confident that the
|
|
type represents a <a href="#media-resource">media resource</a> that it can render if
|
|
used in with this <code><a href="#the-audio-element">audio</a></code> or <code><a href="#the-video-element">video</a></code> element;
|
|
and it must return "<code title="">maybe</code>" otherwise.
|
|
Implementors are encouraged to return "<code title="">maybe</code>"
|
|
unless the type can be confidently established as being supported or
|
|
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
|
|
present.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>This script tests to see if the user agent supports a
|
|
(fictional) new format to dynamically decide whether to use a
|
|
<code><a href="#the-video-element">video</a></code> element or a plugin:</p>
|
|
|
|
<pre><section id="video">
|
|
<p><a href="playing-cats.nfv">Download video</a></p>
|
|
</section>
|
|
<script>
|
|
var videoSection = document.getElementById('video');
|
|
var videoElement = document.createElement('video');
|
|
var support = videoElement.canPlayType('video/x-new-fictional-format;codecs="kittens,bunnies"');
|
|
if (support != "probably" && "New Fictional Video Plug-in" in navigator.plugins) {
|
|
// not confident of browser support
|
|
// but we have a plugin
|
|
// so use plugin instead
|
|
videoElement = document.createElement("embed");
|
|
} else if (support == "") {
|
|
// no support from browser and no plugin
|
|
// do nothing
|
|
videoElement = null;
|
|
}
|
|
if (videoElement) {
|
|
while (videoSection.hasChildNodes())
|
|
videoSection.removeChild(videoSection.firstChild);
|
|
videoElement.setAttribute("src", "playing-cats.nfv");
|
|
videoSection.appendChild(videoElement);
|
|
}
|
|
</script></pre>
|
|
|
|
</div><p class="note">The <code title="attr-source-type"><a href="#attr-source-type">type</a></code>
|
|
attribute of the <code><a href="#the-source-element">source</a></code> element allows the user agent
|
|
to avoid downloading resources that use formats it cannot
|
|
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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current state of network activity for the element,
|
|
from the codes in the list below.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>As <a href="#media-element" title="media element">media elements</a> interact
|
|
with the network, their current network activity is represented by
|
|
the <dfn id="dom-media-networkstate" title="dom-media-networkState"><code>networkState</code></dfn>
|
|
attribute. On getting, it must return the current network state of
|
|
the element, which must be one of the following values:</p>
|
|
|
|
</div><dl><dt><dfn id="dom-media-network_empty" title="dom-media-NETWORK_EMPTY"><code>NETWORK_EMPTY</code></dfn> (numeric value 0)</dt>
|
|
|
|
<dd>The element has not yet been initialized. All attributes are in
|
|
their initial states.</dd>
|
|
|
|
<dt><dfn id="dom-media-network_idle" title="dom-media-NETWORK_IDLE"><code>NETWORK_IDLE</code></dfn> (numeric value 1)</dt>
|
|
|
|
<dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> is active and</span> has selected a <a href="#media-resource" title="media resource">resource</a>, but it is not actually
|
|
using the network at this time.</dd>
|
|
|
|
<dt><dfn id="dom-media-network_loading" title="dom-media-NETWORK_LOADING"><code>NETWORK_LOADING</code></dfn> (numeric value 2)</dt>
|
|
|
|
<dd>The user agent is actively trying to download data.</dd>
|
|
|
|
<dt><dfn id="dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE"><code>NETWORK_NO_SOURCE</code></dfn> (numeric value 3)</dt>
|
|
|
|
<dd>The element<span class="impl">'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> is active, but it</span> has not yet found a <a href="#media-resource" title="media resource">resource</a> to use.</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> defined below describes exactly when the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute changes
|
|
value and what events fire to indicate changes in this state.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Causes the element to reset and start selecting and loading a
|
|
new <a href="#media-resource">media resource</a> from scratch.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>All <a href="#media-element" title="media element">media elements</a> have an
|
|
<dfn id="autoplaying-flag">autoplaying flag</dfn>, which must begin in the true state, and
|
|
a <dfn id="delaying-the-load-event-flag">delaying-the-load-event flag</dfn>, which must begin in the
|
|
false state. While the <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> is
|
|
true, the element must <a href="the-end.html#delay-the-load-event">delay the load event</a> of its
|
|
document.</p>
|
|
|
|
<p>When the <dfn id="dom-media-load" title="dom-media-load"><code>load()</code></dfn>
|
|
method on a <a href="#media-element">media element</a> is invoked, the user agent
|
|
must run the <a href="#media-element-load-algorithm">media element load algorithm</a>.</p>
|
|
|
|
<p>The <dfn id="media-element-load-algorithm">media element load algorithm</dfn> consists of the
|
|
following steps.</p>
|
|
|
|
<ol><li><p>Abort any already-running instance of the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> for this element.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If there are any <a href="webappapis.html#concept-task" title="concept-task">tasks</a> from
|
|
the <a href="#media-element">media element</a>'s <a href="#media-element-event-task-source">media element event task
|
|
source</a> in one of the <a href="webappapis.html#task-queue" title="task queue">task
|
|
queues</a>, then remove those tasks.</p>
|
|
|
|
<p class="note">Basically, pending events and callbacks for the
|
|
media element are discarded when the media element starts loading
|
|
a new resource.</p>
|
|
|
|
</li>
|
|
|
|
<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
|
|
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
|
|
element</a>.</p></li>
|
|
|
|
<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 not set to
|
|
<code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, then
|
|
run these substeps:</p>
|
|
|
|
<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
|
|
event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code> at the <a href="#media-element">media
|
|
element</a>.</p></li>
|
|
|
|
<li><p>If a fetching process is in progress for the <a href="#media-element">media
|
|
element</a>, the user agent should stop it.</p></li>
|
|
|
|
<li><p>Set the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
<code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>.</p></li>
|
|
|
|
<li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
|
|
text tracks</a>.</p></li>
|
|
|
|
<li><p>If <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is
|
|
not set to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, then set it
|
|
to that state.
|
|
|
|
</p></li>
|
|
|
|
<li><p>If the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
|
|
attribute is false, then set it to true.</p></li>
|
|
|
|
<li><p>If <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> is true,
|
|
set it to false.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Set the <a href="#current-playback-position">current playback position</a> to 0.</p>
|
|
|
|
<p>If this changed the <a href="#current-playback-position">current playback position</a>,
|
|
then <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 <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
|
|
<a href="#media-element">media element</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Set the <a href="#initial-playback-position">initial playback position</a> to
|
|
0.</p></li>
|
|
|
|
<li><p>Set the <a href="#timeline-offset">timeline offset</a> to Not-a-Number
|
|
(NaN).</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
|
|
attribute to Not-a-Number (NaN).</p>
|
|
|
|
<p class="note">The user agent <a href="#durationChange">will
|
|
not</a> fire a <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event
|
|
for this particular change of the duration.</p>
|
|
|
|
</li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p>Set the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attribute to the
|
|
value of the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
|
|
attribute.</p></li>
|
|
|
|
<li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code> attribute
|
|
to null and the <a href="#autoplaying-flag">autoplaying flag</a> to true.</p></li>
|
|
|
|
<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
|
|
algorithm</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p class="note">Playback of any previously playing <a href="#media-resource">media
|
|
resource</a> for this element stops.</p>
|
|
|
|
</li>
|
|
|
|
</ol><p>The <dfn id="concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</dfn> for a <a href="#media-element">media element</a> is as follows. This
|
|
algorithm is always invoked synchronously, but one of the first
|
|
steps in the algorithm is to return and continue running the
|
|
remaining steps asynchronously, meaning that it runs in the
|
|
background with scripts and other <a href="webappapis.html#concept-task" title="concept-task">tasks</a> running in parallel. In addition,
|
|
this algorithm interacts closely with the <a href="webappapis.html#event-loop">event loop</a>
|
|
mechanism; in particular, it has <a href="webappapis.html#synchronous-section" title="synchronous
|
|
section">synchronous sections</a> (which are triggered as part of
|
|
the <a href="webappapis.html#event-loop">event loop</a> algorithm). Steps in such sections are
|
|
marked with ⌛.</p>
|
|
|
|
<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>
|
|
|
|
<li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
|
|
the <a href="webappapis.html#concept-task" title="concept-task">task</a> that invoked this
|
|
algorithm to continue. The <a href="webappapis.html#synchronous-section">synchronous section</a>
|
|
consists of all the remaining steps of this algorithm until the
|
|
algorithm says the <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 marked with ⌛.)</p></li>
|
|
|
|
<li>
|
|
|
|
<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>
|
|
|
|
<p>⌛ Otherwise, if the <a href="#media-element">media element</a> does not
|
|
have a <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute but has a
|
|
<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>
|
|
element child in <a href="infrastructure.html#tree-order">tree order</a>.</p>
|
|
|
|
<p>⌛ Otherwise the <a href="#media-element">media element</a> has neither a
|
|
<code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute nor a
|
|
<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
|
|
these steps; the <a href="webappapis.html#synchronous-section">synchronous section</a> ends.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>⌛ Set the <a href="#media-element">media element</a>'s
|
|
<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
|
|
its <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> to
|
|
<code title="dom-media-NETWORK_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p></li>
|
|
|
|
<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> named <code title="event-media-loadstart"><a href="#event-media-loadstart">loadstart</a></code> at the <a href="#media-element">media
|
|
element</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If <var title="">mode</var> is <i title="">attribute</i>, then
|
|
run these substeps:</p>
|
|
|
|
<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
|
|
string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
|
|
down to the <i title="">failed</i> step below.</p></li>
|
|
|
|
<li><p>⌛ Let <var title="">absolute URL</var> be the
|
|
<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>
|
|
specified by the <code title="attr-media-src"><a href="#attr-media-src">src</a></code>
|
|
attribute's value relative to the <a href="#media-element">media element</a> when
|
|
the <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute was last
|
|
changed.</p>
|
|
</li><li><p>⌛ If <var title="">absolute URL</var> was obtained
|
|
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>
|
|
|
|
<li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
|
|
remaining steps asynchronously.</p></li>
|
|
|
|
<li><p>If <var title="">absolute URL</var> was obtained
|
|
successfully, run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
|
|
algorithm</a> with <var title="">absolute URL</var>. If that
|
|
algorithm returns without aborting <em>this</em> one, then the
|
|
load failed.</p></li>
|
|
|
|
<li>
|
|
|
|
<p><i>Failed</i>: Reaching this step indicates that the media
|
|
resource failed to load or that the given <a href="urls.html#url">URL</a> could
|
|
not be <a href="urls.html#resolve-a-url" title="resolve a url">resolved</a>. In one
|
|
atomic operation, run the following steps:</p>
|
|
|
|
<ol><li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
|
|
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
|
|
<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>
|
|
|
|
<li><p><a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's media-resource-specific
|
|
text tracks</a>.</p></li>
|
|
|
|
<li><p>Set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
|
|
value.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<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> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
|
|
at the <a href="#media-element">media element</a>.</p></li>
|
|
|
|
<li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a>
|
|
to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying
|
|
the load event</a>.</p></li>
|
|
|
|
<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
|
|
<code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute is changed, the
|
|
element won't attempt to load another resource.</p></li>
|
|
|
|
|
|
</ol><p>Otherwise, the <code><a href="#the-source-element">source</a></code> elements will be used; run
|
|
these substeps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>⌛ Let <var title="">pointer</var> be a position
|
|
defined by two adjacent nodes in the <a href="#media-element">media
|
|
element</a>'s child list, treating the start of the list
|
|
(before the first child in the list, if any) and end of the list
|
|
(after the last child in the list, if any) as nodes in their own
|
|
right. One node is the node before <var title="">pointer</var>,
|
|
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
|
|
any, or the end of the list, if it is the last node.</p>
|
|
|
|
<p>As nodes are inserted and removed into the <a href="#media-element">media
|
|
element</a>, <var title="">pointer</var> must be updated as
|
|
follows:</p>
|
|
|
|
<dl><dt>If a new node is inserted between the two nodes that
|
|
define <var title="">pointer</var></dt>
|
|
|
|
<dd>Let <var title="">pointer</var> be the point between the
|
|
node before <var title="">pointer</var> and the new node. In
|
|
other words, insertions at <var title="">pointer</var> go after
|
|
<var title="">pointer</var>.</dd>
|
|
|
|
<dt>If the node before <var title="">pointer</var> is removed</dt>
|
|
|
|
<dd>Let <var title="">pointer</var> be the point between the
|
|
node after <var title="">pointer</var> and the node before the
|
|
node after <var title="">pointer</var>. In other words, <var title="">pointer</var> doesn't move relative to the remaining
|
|
nodes.</dd>
|
|
|
|
<dt>If the node after <var title="">pointer</var> is removed</dt>
|
|
|
|
<dd>Let <var title="">pointer</var> be the point between the
|
|
node before <var title="">pointer</var> and the node after the
|
|
node before <var title="">pointer</var>. Just as with the
|
|
previous case, <var title="">pointer</var> doesn't move
|
|
relative to the remaining nodes.</dd>
|
|
|
|
</dl><p>Other changes don't affect <var title="">pointer</var>.</p>
|
|
|
|
</li>
|
|
|
|
<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
|
|
string, then end the <a href="webappapis.html#synchronous-section">synchronous section</a>, and jump
|
|
down to the <i title="">failed</i> step below.</p></li>
|
|
|
|
<li><p>⌛ Let <var title="">absolute URL</var> be the
|
|
<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>
|
|
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
|
|
the <var title="">candidate</var> when the <code title="attr-source-src"><a href="#attr-source-src">src</a></code> attribute was last
|
|
changed.</p>
|
|
</li><li><p>⌛ If <var title="">absolute URL</var> was not
|
|
obtained successfully, then end the <a href="webappapis.html#synchronous-section">synchronous
|
|
section</a>, and jump down to the <i title="">failed</i> step
|
|
below.</p></li>
|
|
|
|
<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
|
|
parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
|
|
described by the <code title="">codecs</code> parameter, for
|
|
types that define that parameter), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
|
|
the user agent knows it cannot render</a>, then end the
|
|
<a href="webappapis.html#synchronous-section">synchronous section</a>, and jump down to the <i title="">failed</i> step below.</p></li>
|
|
|
|
<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
|
|
not <a href="common-microsyntaxes.html#matches-the-environment" title="matches the environment">match the
|
|
environment</a>, then end the <a href="webappapis.html#synchronous-section">synchronous
|
|
section</a>, and jump down to the <i title="">failed</i> step
|
|
below.</p></li>
|
|
|
|
<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>
|
|
|
|
<li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
|
|
remaining steps asynchronously.</p></li>
|
|
|
|
<li><p>Run the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource
|
|
fetch algorithm</a> with <var title="">absolute URL</var>. If
|
|
that algorithm returns without aborting <em>this</em> one, then
|
|
the load failed.</p></li>
|
|
|
|
<li><p><i title="">Failed</i>: <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 <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
|
|
obtain <var title="">candidate</var>'s corresponding <a href="#media-resource">media
|
|
resource</a> in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
|
|
algorithm</a>.</p></li>
|
|
|
|
<li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
|
|
<a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
|
|
steps of this algorithm until the algorithm says the
|
|
<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
|
|
marked with ⌛.)</p></li>
|
|
|
|
<li><p>⌛ <a href="#forget-the-media-element-s-media-resource-specific-text-tracks">Forget the media element's
|
|
media-resource-specific text tracks</a>.</p></li>
|
|
|
|
<li><p>⌛ <i title="">Find next candidate</i>: Let <var title="">candidate</var> be null.</p></li>
|
|
|
|
<li><p>⌛ <i title="">Search loop</i>: If the node after
|
|
<var title="">pointer</var> is the end of the list, then jump to
|
|
the <i title="">waiting</i> step below.</p></li>
|
|
|
|
<li><p>⌛ If the node after <var title="">pointer</var> is
|
|
a <code><a href="#the-source-element">source</a></code> element, let <var title="">candidate</var>
|
|
be that element.</p></li>
|
|
|
|
<li><p>⌛ Advance <var title="">pointer</var> so that the
|
|
node before <var title="">pointer</var> is now the node that was
|
|
after <var title="">pointer</var>, and the node after <var title="">pointer</var> is the node after the node that used to be
|
|
after <var title="">pointer</var>, if any.</p></li>
|
|
|
|
<li><p>⌛ If <var title="">candidate</var> is null, jump
|
|
back to the <i title="">search loop</i> step. Otherwise, jump
|
|
back to the <i title="">process candidate</i> step.</p></li>
|
|
|
|
<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
|
|
the <a href="#dom-media-network_no_source" title="dom-media-NETWORK_NO_SOURCE">NETWORK_NO_SOURCE</a>
|
|
value.</p></li>
|
|
|
|
<li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
|
|
flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
|
|
event">delaying the load event</a>.</p></li>
|
|
|
|
<li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
|
|
remaining steps asynchronously.</p></li>
|
|
|
|
<li><p>Wait until the node after <var title="">pointer</var> is a
|
|
node other than the end of the list. (This step might wait
|
|
forever.)</p></li>
|
|
|
|
<li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>. The
|
|
<a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the remaining
|
|
steps of this algorithm until the algorithm says the
|
|
<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
|
|
marked with ⌛.)</p></li>
|
|
|
|
<li><p>⌛ Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
|
|
flag</a> back to true (this <a href="the-end.html#delay-the-load-event" title="delay the load
|
|
event">delays the load event</a> again, in case it hasn't been
|
|
fired yet).</p>
|
|
|
|
</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>
|
|
|
|
<li><p>⌛ Jump back to the <i title="">find next
|
|
candidate</i> step above.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
</ol><p>The <dfn id="concept-media-load-resource" title="concept-media-load-resource">resource fetch
|
|
algorithm</dfn> for a <a href="#media-element">media element</a> and a given
|
|
<a href="urls.html#absolute-url">absolute URL</a> is as follows:</p>
|
|
|
|
<ol><li><p>Let the <var title="">current media resource</var> be the
|
|
resource given by the <a href="urls.html#absolute-url">absolute URL</a> passed to this
|
|
algorithm. This is now the element's <a href="#media-resource">media
|
|
resource</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Begin to <a href="fetching-resources.html#fetch">fetch</a> the <var title="">current media
|
|
resource</var>, from the <a href="#media-element">media element</a>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, with the <i>force
|
|
same-origin flag</i> set.</p>
|
|
<p>Every 350ms (±200ms) or for every byte received, whichever
|
|
is <em>least</em> frequent, <a href="webappapis.html#queue-a-task">queue a task</a> to
|
|
<a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the element.</p>
|
|
|
|
<p>The <dfn id="stall-timeout">stall timeout</dfn> is a user-agent defined length of
|
|
time, which should be about three seconds. When a <a href="#media-element">media
|
|
element</a> that is actively attempting to obtain <a href="#media-data">media
|
|
data</a> has failed to receive any data for a duration equal to
|
|
the <a href="#stall-timeout">stall timeout</a>, 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 event</a> named <code title="event-media-stalled"><a href="#event-media-stalled">stalled</a></code> at the element.</p>
|
|
|
|
<p>User agents may allow users to selectively block or slow
|
|
<a href="#media-data">media data</a> downloads. When a <a href="#media-element">media
|
|
element</a>'s download has been blocked altogether, the user
|
|
agent must act as if it was stalled (as opposed to acting as if
|
|
the connection was closed). The rate of the download may also be
|
|
throttled automatically by the user agent, e.g. to balance the
|
|
download with other connections sharing the same bandwidth.</p>
|
|
|
|
<p>User agents may decide to not download more content at any
|
|
time, e.g. after buffering five minutes of a one hour media
|
|
resource, while waiting for the user to decide whether to play the
|
|
resource or not, or while waiting for user input in an interactive
|
|
resource. When a <a href="#media-element">media element</a>'s download has been
|
|
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
|
|
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
|
|
when downloading of the resource resumes, 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_LOADING"><a href="#dom-media-network_loading">NETWORK_LOADING</a></code>.</p>
|
|
|
|
<p class="note">The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute provides a
|
|
hint regarding how much buffering the author thinks is advisable,
|
|
even in the absence of the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute.</p>
|
|
|
|
<p>When a user agent decides to completely stall a download,
|
|
e.g. if it is waiting until the user starts playback before
|
|
downloading any further content, the element's
|
|
<a href="#delaying-the-load-event-flag">delaying-the-load-event flag</a> must be set to
|
|
false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load event">delaying the
|
|
load event</a>.</p>
|
|
|
|
<p>The user agent may use whatever means necessary to fetch the
|
|
resource (within the constraints put forward by this and other
|
|
specifications); for example, reconnecting to the server in the
|
|
face of network errors, using HTTP range retrieval requests, or
|
|
switching to a streaming protocol. The user agent must consider a
|
|
resource erroneous only if it has given up trying to fetch it.</p>
|
|
|
|
<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
|
|
being fetched must, when appropriate, include the relevant
|
|
substeps from the following list:</p>
|
|
|
|
<dl class="switch"><dt>If the <a href="#media-data">media data</a> cannot be fetched at all, due
|
|
to network errors, causing the user agent to give up trying to
|
|
fetch the resource</dt>
|
|
|
|
<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
|
|
parsed as a <a href="infrastructure.html#mime-type">MIME type</a> (including any codecs
|
|
described by the <code title="">codecs</code> parameter, if the
|
|
parameter is defined for that type), represents <a href="#a-type-that-the-user-agent-knows-it-cannot-render">a type that
|
|
the user agent knows it cannot render</a> (even if the actual
|
|
<a href="#media-data">media data</a> is in a supported format)</dt>
|
|
|
|
<dt>If the <a href="#media-data">media data</a> can be fetched but is found by
|
|
inspection to be in an unsupported format, or can otherwise not
|
|
be rendered at all</dt>
|
|
|
|
<dd>
|
|
|
|
<p>DNS errors, HTTP 4xx and 5xx errors (and equivalents in
|
|
other protocols), and other fatal network errors that occur
|
|
before the user agent has established whether the <var title="">current media resource</var> is usable, as well as
|
|
the file using an unsupported container format, or using
|
|
unsupported codecs for all the data, must cause the user agent
|
|
to execute the following steps:</p>
|
|
|
|
<ol><li><p>The user agent should cancel the fetching
|
|
process.</p></li>
|
|
|
|
<li><p>Abort this subalgorithm, returning to the <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p>
|
|
|
|
</li></ol></dd>
|
|
|
|
|
|
|
|
|
|
|
|
<dt id="getting-media-metadata">Once enough of the <a href="#media-data">media
|
|
data</a> has been fetched to determine the duration of the
|
|
<a href="#media-resource">media resource</a>, its dimensions, and other
|
|
metadata,
|
|
and once <a href="#the-text-tracks-are-ready">the text tracks are ready</a>
|
|
</dt>
|
|
|
|
<dd>
|
|
|
|
<p>This indicates that the resource is usable. The user agent
|
|
must follow these substeps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p><a href="#defineTimeline">Establish the media timeline</a> for the purposes
|
|
of the <a href="#current-playback-position">current playback position</a>, the
|
|
<a href="#earliest-possible-position">earliest possible position</a>, and the <a href="#initial-playback-position">initial
|
|
playback position</a>, based on the <a href="#media-data">media
|
|
data</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Update the <a href="#timeline-offset">timeline offset</a> to the date and
|
|
time that corresponds to the zero time in the <a href="#media-timeline">media
|
|
timeline</a> established in the previous step, if any. If
|
|
no explicit time and date is given by the <a href="#media-resource">media
|
|
resource</a>, the <a href="#timeline-offset">timeline offset</a> must be set
|
|
to Not-a-Number (NaN).</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Set the <a href="#current-playback-position">current playback position</a> to the
|
|
<a href="#earliest-possible-position">earliest possible position</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code>
|
|
attribute with the time of the last frame of the resource, if
|
|
known, on the <a href="#media-timeline">media timeline</a> established above.
|
|
If it is not known (e.g. a stream that is in principle
|
|
infinite), update the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute to the
|
|
value positive Infinity.</p>
|
|
|
|
<p class="note">The user agent <a href="#durationChange">will</a> <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 <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
|
|
element at this point.</p>
|
|
|
|
</li>
|
|
|
|
<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>
|
|
attributes.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Set the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to
|
|
<code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>.</p>
|
|
|
|
<p class="note">A <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> DOM
|
|
event <a href="#fire-loadedmetadata">will be fired</a> as part
|
|
of setting the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to a
|
|
new value.</p>
|
|
|
|
|
|
|
|
</li>
|
|
|
|
<li><p>Let <var title="">jumped</var> be false.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If either the <a href="#media-resource">media resource</a> or the address of
|
|
the <var title="">current media resource</var> indicate a
|
|
particular start time, then set the <a href="#initial-playback-position">initial playback
|
|
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
|
|
(if the position is out of range, it is effectively
|
|
ignored).</p>
|
|
|
|
<p class="example">For example, with media formats that
|
|
support the <cite>Media Fragments URI</cite> fragment
|
|
identifier syntax, the fragment identifier can be used to
|
|
indicate a start position. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
|
|
|
|
</li>
|
|
|
|
<li><p>If either the <a href="#media-resource">media resource</a> or the address
|
|
of the <var title="">current media resource</var> indicate a
|
|
particular set of audio or video tracks to enable, then the
|
|
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
|
|
the first selected video track must be selected in the
|
|
element's <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code>
|
|
object.</p></li>
|
|
|
|
<li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
|
|
media controller</a>, then: if <var title="">jumped</var> is
|
|
true and the <a href="#initial-playback-position">initial playback position</a>, relative
|
|
to the <a href="#current-media-controller">current media controller</a>'s timeline, is
|
|
greater than the <a href="#current-media-controller">current media controller</a>'s
|
|
<a href="#media-controller-position">media controller position</a>, then <a href="#seek-the-media-controller">seek the
|
|
media controller</a> to the <a href="#media-element">media element</a>'s
|
|
<a href="#initial-playback-position">initial playback position</a>, relative to the
|
|
<a href="#current-media-controller">current media controller</a>'s timeline; otherwise,
|
|
<a href="#dom-media-seek" title="dom-media-seek">seek</a> the <a href="#media-element">media
|
|
element</a> to the <a href="#media-controller-position">media controller position</a>,
|
|
relative to the <a href="#media-element">media element</a>'s timeline,
|
|
discarding any resulting exceptions.</p></li>
|
|
<li>
|
|
|
|
<p>Once the <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
|
|
reaches <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
|
|
<a href="#fire-loadeddata">after the <code title="event-media-loadeddata">loadeddata</code> event has been
|
|
fired</a>, set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
|
|
flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
|
|
event">delaying the load event</a>.</p>
|
|
|
|
<p class="note">A user agent that is attempting to reduce
|
|
network usage while still fetching the metadata for each
|
|
<a href="#media-resource">media resource</a> would also stop buffering at this
|
|
point, causing the <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute
|
|
to switch to the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code> value.</p>
|
|
|
|
</li>
|
|
|
|
</ol><p class="note">The user agent is <em>required</em> to
|
|
determine the duration of the <a href="#media-resource">media resource</a> and
|
|
go through this step before playing.</p>
|
|
</dd>
|
|
|
|
|
|
<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
|
|
has been decoded)</dt>
|
|
|
|
<dd>
|
|
|
|
<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>
|
|
named <code title="event-media-progress"><a href="#event-media-progress">progress</a></code> at the
|
|
<a href="#media-element">media element</a>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<dt>If the connection is interrupted, causing the user agent to
|
|
give up trying to fetch the resource</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Fatal network errors that occur after the user agent has
|
|
established whether the <var title="">current media
|
|
resource</var> is usable must cause the user agent to execute
|
|
the following steps:</p>
|
|
|
|
<ol><li><p>The user agent should cancel the fetching
|
|
process.</p></li>
|
|
|
|
<li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
|
|
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
|
|
<code title="dom-MediaError-MEDIA_ERR_NETWORK"><a href="#dom-mediaerror-media_err_network">MEDIA_ERR_NETWORK</a></code>.</p></li>
|
|
|
|
<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> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
|
|
at the <a href="#media-element">media element</a>.</p></li>
|
|
|
|
<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
|
|
value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
|
|
element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
|
|
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
|
|
event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
|
|
at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
|
|
value.</p></li>
|
|
|
|
<li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
|
|
flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
|
|
event">delaying the load event</a>.</p></li>
|
|
|
|
<li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p></li>
|
|
|
|
</ol></dd>
|
|
|
|
|
|
<dt id="fatal-decode-error">If the <a href="#media-data">media data</a> is
|
|
corrupted</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Fatal errors in decoding the <a href="#media-data">media data</a> that
|
|
occur after the user agent has established whether the <var title="">current media resource</var> is usable must cause the
|
|
user agent to execute the following steps:</p>
|
|
|
|
<ol><li><p>The user agent should cancel the fetching
|
|
process.</p></li>
|
|
|
|
<li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
|
|
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
|
|
<code title="dom-MediaError-MEDIA_ERR_DECODE"><a href="#dom-mediaerror-media_err_decode">MEDIA_ERR_DECODE</a></code>.</p></li>
|
|
|
|
<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> named <code title="event-media-error"><a href="#event-media-error">error</a></code>
|
|
at the <a href="#media-element">media element</a>.</p></li>
|
|
|
|
<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
|
|
value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
|
|
element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
|
|
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
|
|
event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
|
|
at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
|
|
value.</p></li>
|
|
|
|
<li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
|
|
flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
|
|
event">delaying the load event</a>.</p></li>
|
|
|
|
<li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p></li>
|
|
|
|
</ol></dd>
|
|
|
|
|
|
<dt>If the <a href="#media-data">media data</a> fetching process is aborted by
|
|
the user</dt>
|
|
|
|
<dd>
|
|
|
|
<p>The fetching process is aborted by the user, e.g. because the
|
|
user navigated the browsing context to another page, the user
|
|
agent must execute the following steps. These steps are not
|
|
followed if the <code title="dom-media-load"><a href="#dom-media-load">load()</a></code>
|
|
method itself is invoked while these steps are running, as the
|
|
steps above handle that particular kind of abort.</p>
|
|
|
|
<ol><li><p>The user agent should cancel the fetching
|
|
process.</p></li>
|
|
|
|
<li><p>Set the <code title="dom-media-error"><a href="#dom-media-error">error</a></code>
|
|
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
|
|
<code title="dom-MediaError-MEDIA_ERR_ABORTED"><a href="#dom-mediaerror-media_err_aborted">MEDIA_ERR_ABORTED</a></code>.</p></li>
|
|
|
|
<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> named <code title="event-media-abort"><a href="#event-media-abort">abort</a></code>
|
|
at the <a href="#media-element">media element</a>.</p></li>
|
|
|
|
<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
|
|
value equal to <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>, set the
|
|
element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>
|
|
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
|
|
event</a> named <code title="event-media-emptied"><a href="#event-media-emptied">emptied</a></code>
|
|
at the element. Otherwise, set the element's <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code> attribute to
|
|
the <code title="dom-media-NETWORK_IDLE"><a href="#dom-media-network_idle">NETWORK_IDLE</a></code>
|
|
value.</p></li>
|
|
|
|
<li><p>Set the element's <a href="#delaying-the-load-event-flag">delaying-the-load-event
|
|
flag</a> to false. This stops <a href="the-end.html#delay-the-load-event" title="delay the load
|
|
event">delaying the load event</a>.</p></li>
|
|
|
|
<li><p>Abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p></li>
|
|
|
|
</ol></dd>
|
|
|
|
|
|
<dt id="non-fatal-media-error">If the <a href="#media-data">media data</a> can
|
|
be fetched but has non-fatal errors or uses, in part, codecs that
|
|
are unsupported, preventing the user agent from rendering the
|
|
content completely correctly but not preventing playback
|
|
altogether</dt>
|
|
|
|
<dd>
|
|
|
|
<p>The server returning data that is partially usable but cannot
|
|
be optimally rendered must cause the user agent to render just
|
|
the bits it can handle, and ignore the rest.</p>
|
|
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>If the <a href="#media-resource">media resource</a>'s <a href="origin-0.html#origin">origin</a> is
|
|
the <a href="origin-0.html#same-origin">same origin</a> as the <a href="#media-element">media element</a>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, <a href="webappapis.html#queue-a-task">queue a
|
|
task</a> to run the <a href="#steps-to-expose-a-media-resource-specific-text-track">steps to expose a
|
|
media-resource-specific text track</a> with the relevant
|
|
data.</p> <!-- CORS -->
|
|
|
|
<p class="note">Cross-origin files do not expose their subtitles
|
|
in the DOM, for security reasons. However, user agents may still
|
|
provide the user with access to such data in their user
|
|
interface.</p>
|
|
|
|
</dd>
|
|
|
|
</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>
|
|
(i.e. once the download has completed), if the fetching process
|
|
completes without errors, including decoding the media data, and
|
|
if all of the data is available to the user agent without network
|
|
access, then, the user agent must move on to the next step. This
|
|
might never happen, e.g. when streaming an infinite resource such
|
|
as Web radio, or if the resource is longer than the user agent's
|
|
ability to cache data.</p>
|
|
|
|
<p>While the user agent might still need network access to obtain
|
|
parts of the <a href="#media-resource">media resource</a>, the user agent must
|
|
remain on this step.</p>
|
|
|
|
<p class="example">For example, if the user agent has discarded
|
|
the first half of a video, the user agent will remain at this step
|
|
even once the <a href="#ended-playback" title="ended playback">playback has
|
|
ended</a>, because there is always the chance the user will
|
|
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
|
|
will end up dispatching a <code title="event-media-stalled"><a href="#event-media-stalled">stalled</a></code> event, as described
|
|
earlier.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>If the user agent ever reaches this step (which can only
|
|
happen if the entire resource gets loaded and kept available):
|
|
abort the overall <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p></li>
|
|
|
|
</ol></div><hr><p>The <dfn id="attr-media-preload" title="attr-media-preload"><code>preload</code></dfn>
|
|
attribute is an <a href="common-microsyntaxes.html#enumerated-attribute">enumerated attribute</a>. The following table
|
|
lists the keywords and states for the attribute — the keywords
|
|
in the left column map to the states in the cell in the second
|
|
column on the same row as the keyword.</p><table><thead><tr><th> Keyword
|
|
</th><th> State
|
|
</th><th> Brief description
|
|
</th></tr></thead><tbody><tr><td><dfn id="attr-media-preload-none" title="attr-media-preload-none"><code>none</code></dfn>
|
|
</td><td><dfn id="attr-media-preload-none-state" title="attr-media-preload-none-state">None</dfn>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="attr-media-preload-metadata" title="attr-media-preload-metadata"><code>metadata</code></dfn>
|
|
</td><td><dfn id="attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</dfn>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="attr-media-preload-auto" title="attr-media-preload-auto"><code>auto</code></dfn>
|
|
</td><td><dfn id="attr-media-preload-auto-state" title="attr-media-preload-auto-state">Automatic</dfn>
|
|
</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.
|
|
</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
|
|
attribute's <i>missing value default</i> is user-agent defined,
|
|
though the <a href="#attr-media-preload-metadata-state" title="attr-media-preload-metadata-state">Metadata</a> state is
|
|
suggested as a compromise between reducing server load and providing
|
|
an optimal user experience.</p><div class="impl">
|
|
|
|
<p>The <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute is
|
|
intended to provide a hint to the user agent about what the author
|
|
thinks will lead to the best user experience. The attribute may be
|
|
ignored altogether, for example based on explicit user preferences
|
|
or based on the available connectivity.</p>
|
|
|
|
<p>The <dfn id="dom-media-preload" title="dom-media-preload"><code>preload</code></dfn> IDL
|
|
attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
|
|
same name, <a href="common-dom-interfaces.html#limited-to-only-known-values">limited to only known values</a>.</p>
|
|
|
|
</div><p class="note">The <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute can override
|
|
the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute (since
|
|
if the media plays, it naturally has to buffer first, regardless of
|
|
the hint given by the <code title="attr-media-preload"><a href="#attr-media-preload">preload</a></code> attribute). Including
|
|
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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
|
|
ranges of the <a href="#media-resource">media resource</a> that the user agent has
|
|
buffered.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-buffered" title="dom-media-buffered"><code>buffered</code></dfn>
|
|
attribute must return a new static <a href="#normalized-timeranges-object">normalized
|
|
<code>TimeRanges</code> object</a> that represents the ranges of
|
|
the <a href="#media-resource">media resource</a>, if any, that the user agent has
|
|
buffered, at the time the attribute is evaluated. Users agents must
|
|
accurately determine the ranges available, even for media streams
|
|
where this can only be determined by tedious inspection.</p>
|
|
|
|
<p class="note">Typically this will be a single range anchored at
|
|
the zero point, but if, e.g. the user agent uses HTTP range requests
|
|
in response to seeking, then there could be multiple ranges.</p>
|
|
|
|
<p>User agents may discard previously buffered data.</p>
|
|
|
|
<p class="note">Thus, a time position included within a range of the
|
|
objects return by the <code title="dom-media-buffered"><a href="#dom-media-buffered">buffered</a></code> attribute at one time can
|
|
end up being not included in the range(s) of objects returned by the
|
|
same attribute at later times.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the length of the <a href="#media-resource">media resource</a>, in
|
|
seconds, assuming that the start of the <a href="#media-resource">media
|
|
resource</a> is at time zero.</p>
|
|
|
|
<p>Returns NaN if the duration isn't available.</p><p>
|
|
|
|
</p><p>Returns Infinity for unbounded streams.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-currentTime"><a href="#dom-media-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds.</p>
|
|
|
|
<p>Can be set, to seek to the given time.</p><p>
|
|
|
|
</p><p>Will throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception if there
|
|
is no selected <a href="#media-resource">media resource</a>
|
|
or if there is a <a href="#current-media-controller">current media controller</a>.
|
|
Will throw an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception if the given time is not
|
|
within the ranges to which the user agent can seek.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-initialTime"><a href="#dom-media-initialtime">initialTime</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <a href="#initial-playback-position">initial playback position</a>, that is, time
|
|
to which the <a href="#media-resource">media resource</a> was automatically seeked
|
|
when it was loaded. Returns zero if the <a href="#initial-playback-position">initial playback
|
|
position</a> is still unknown.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>A <a href="#media-resource">media resource</a> has a <dfn id="media-timeline">media timeline</dfn>
|
|
that maps times (in seconds) to positions in the <a href="#media-resource">media
|
|
resource</a>. The origin of a timeline is its earliest defined
|
|
position. The duration of a timeline is its last defined
|
|
position.</p>
|
|
|
|
<p><dfn id="defineTimeline" title="establish the media
|
|
timeline">Establishing the media timeline</dfn>: If the <a href="#media-resource">media
|
|
resource</a> somehow specifies an explicit timeline whose origin
|
|
is not negative, then the <a href="#media-timeline">media timeline</a> should be that
|
|
timeline. (Whether the <a href="#media-resource">media resource</a> can specify a
|
|
timeline or not depends on the <a href="#media-resource" title="media resource">media
|
|
resource's</a> format.) If the <a href="#media-resource">media resource</a>
|
|
specifies an explicit start time <em>and date</em>, then that time
|
|
and date should be considered the zero point in the <a href="#media-timeline">media
|
|
timeline</a>; the <a href="#timeline-offset">timeline offset</a> will be the time
|
|
and date, exposed using the <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
|
|
attribute.</p>
|
|
|
|
<p>If the <a href="#media-resource">media resource</a> has a discontinuous timeline,
|
|
the user agent must extend the timeline used at the start of the
|
|
resource across the entire resource, so that the <a href="#media-timeline">media
|
|
timeline</a> of the <a href="#media-resource">media resource</a> increases
|
|
linearly starting from the <a href="#earliest-possible-position">earliest possible position</a>
|
|
(as defined below), even if the underlying <a href="#media-data">media data</a>
|
|
has out-of-order or even overlapping time codes.</p>
|
|
|
|
<p class="example">For example, if two clips have been concatenated
|
|
into one video file, but the video format exposes the original times
|
|
for the two clips, the video data might expose a timeline that goes,
|
|
say, 00:15..00:29 and then 00:05..00:38. However, the user agent
|
|
would not expose those times; it would instead expose the times as
|
|
00:15..00:29 and 00:29..01:02, as a single video.</p>
|
|
|
|
<p>In the absence of an explicit timeline, the zero time on the
|
|
<a href="#media-timeline">media timeline</a> should correspond to the first frame of
|
|
the <a href="#media-resource">media resource</a>. For static audio and video files
|
|
this is generally trivial. For streaming resources, if the user
|
|
agent will be able to seek to an earlier point than the first frame
|
|
originally provided by the server, then the zero time should
|
|
correspond to the earliest seekable time of the <a href="#media-resource">media
|
|
resource</a>; otherwise, it should correspond to the first frame
|
|
received from the server (the point in the <a href="#media-resource">media
|
|
resource</a> at which the user agent began receiving the
|
|
stream).</p>
|
|
|
|
<p class="example">Another example would be a stream that carries a
|
|
video with several concatenated fragments, broadcast by a server
|
|
that does not allow user agents to request specific times but
|
|
instead just streams the video data in a predetermined order. If a
|
|
user agent connects to this stream and receives fragments defined as
|
|
covering timestamps 2010-03-20 23:15:00 UTC to 2010-03-21 00:05:00
|
|
UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC, it would
|
|
expose this with a <a href="#media-timeline">media timeline</a> starting at 0s and
|
|
extending to 3,600s (one hour). Assuming the streaming server
|
|
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
|
|
return 3,600. The <code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code> attribute
|
|
would return a <code>Date</code> object with a time corresponding to
|
|
2010-03-20 23:15:00 UTC. However, if a different user agent
|
|
connected five minutes later, <em>it</em> would (presumably) receive
|
|
fragments covering timestamps 2010-03-20 23:20:00 UTC to 2010-03-21
|
|
00:05:00 UTC and 2010-02-12 14:25:00 UTC to 2010-02-12 14:35:00 UTC,
|
|
and would expose this with a <a href="#media-timeline">media timeline</a> starting at
|
|
0s and extending to 3,300s (fifty five minutes). In this case, the
|
|
<code title="dom-media-startOffsetTime"><a href="#dom-media-startoffsettime">startOffsetTime</a></code>
|
|
attribute would return a <code>Date</code> object with a time
|
|
corresponding to 2010-03-20 23:20:00 UTC.</p>
|
|
|
|
<p>In any case, the user agent must ensure that the <a href="#earliest-possible-position">earliest
|
|
possible position</a> (as defined below) using the established
|
|
<a href="#media-timeline">media timeline</a>, is greater than or equal to zero.</p>
|
|
|
|
<p>The <a href="#media-timeline">media timeline</a> also has an associated clock.
|
|
Which clock is used is user-agent defined, and may be <a href="#media-resource">media
|
|
resource</a>-dependent, but it should approximate the user's wall
|
|
clock.</p>
|
|
|
|
<p class="note">All the <a href="#media-element" title="media element">media
|
|
elements</a> that share <a href="#current-media-controller">current media controller</a> use
|
|
the same clock for their <a href="#media-timeline">media timeline</a>.</p>
|
|
|
|
<p><a href="#media-element" title="media element">Media elements</a> have a
|
|
<dfn id="current-playback-position">current playback position</dfn>, which must initially (i.e. in
|
|
the absence of <a href="#media-data">media data</a>) be zero seconds. The
|
|
<a href="#current-playback-position">current playback position</a> is a time on the <a href="#media-timeline">media
|
|
timeline</a>.</p>
|
|
|
|
<p>The <dfn id="dom-media-currenttime" title="dom-media-currentTime"><code>currentTime</code></dfn>
|
|
attribute must, on getting, return the <a href="#current-playback-position">current playback
|
|
position</a>, expressed in seconds. On setting,
|
|
if the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, then it must throw an
|
|
<code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception; otherwise,
|
|
the user agent
|
|
must <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the new value
|
|
(which might raise an exception).</p>
|
|
|
|
<p><a href="#media-element" title="media element">Media elements</a> have an
|
|
<dfn id="initial-playback-position">initial playback position</dfn>, which must initially (i.e. in
|
|
the absence of <a href="#media-data">media data</a>) be zero seconds. The
|
|
<a href="#initial-playback-position">initial playback position</a> is updated when a <a href="#media-resource">media
|
|
resource</a> is loaded. The <a href="#initial-playback-position">initial playback
|
|
position</a> is a time on the <a href="#media-timeline">media timeline</a>.</p>
|
|
|
|
<p>The <dfn id="dom-media-initialtime" title="dom-media-initialTime"><code>initialTime</code></dfn>
|
|
attribute must, on getting, return the <a href="#initial-playback-position">initial playback
|
|
position</a>, expressed in seconds.</p>
|
|
|
|
<p>If the <a href="#media-resource">media resource</a> is a streaming resource, then
|
|
the user agent might be unable to obtain certain parts of the
|
|
resource after it has expired from its buffer. Similarly, some <a href="#media-resource" title="media resource">media resources</a> might have a
|
|
<a href="#media-timeline">media timeline</a> that doesn't start at zero. The
|
|
<dfn id="earliest-possible-position">earliest possible position</dfn> is the earliest position in
|
|
the stream or resource that the user agent can ever obtain
|
|
again. It is also a time on the <a href="#media-timeline">media timeline</a>.</p>
|
|
|
|
<p class="note">The <a href="#earliest-possible-position">earliest possible position</a> is not
|
|
explicitly exposed in the API; it corresponds to the start time of
|
|
the first range in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute's
|
|
<code><a href="#timeranges">TimeRanges</a></code> object, if any, or the <a href="#current-playback-position">current
|
|
playback position</a> otherwise.</p>
|
|
|
|
<p>When the <a href="#earliest-possible-position">earliest possible position</a> changes, then:
|
|
if the <a href="#current-playback-position">current playback position</a> is before the
|
|
<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
|
|
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
|
|
element in the past 15 to 250ms and is not still running event
|
|
handlers for such an event, then 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 event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p>
|
|
|
|
<p class="note">Because of the above requirement and the requirement
|
|
in the <a href="#concept-media-load-resource" title="concept-media-load-resource">resource fetch
|
|
algorithm</a> that kicks in <a href="#getting-media-metadata">when the metadata of the clip becomes
|
|
known</a>, the <a href="#current-playback-position">current playback position</a> can never be
|
|
less than the <a href="#earliest-possible-position">earliest possible position</a>.</p>
|
|
|
|
<p>The <dfn id="dom-media-duration" title="dom-media-duration"><code>duration</code></dfn>
|
|
attribute must return the time of the end of the <a href="#media-resource">media
|
|
resource</a>, in seconds, on the <a href="#media-timeline">media timeline</a>. If
|
|
no <a href="#media-data">media data</a> is available, then the attributes must
|
|
return the Not-a-Number (NaN) value. If the <a href="#media-resource">media
|
|
resource</a> is known to be unbounded (e.g. a streaming radio),
|
|
then the attribute must return the positive Infinity value.</p>
|
|
|
|
<p>The user agent must determine the duration of the <a href="#media-resource">media
|
|
resource</a> before playing any part of the <a href="#media-data">media
|
|
data</a> and before setting <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> to a value equal to
|
|
or greater than <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, even if doing
|
|
so requires fetching multiple parts of the resource.</p>
|
|
|
|
<p id="durationChange">When the length of the <a href="#media-resource">media
|
|
resource</a> changes to a known value (e.g. from being unknown to
|
|
known, or from a previously established length to a new length) 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
|
|
event</a> named <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> at the
|
|
<a href="#media-element">media element</a>. (The event is not fired when the
|
|
duration is reset as part of loading a new media resource.)</p>
|
|
|
|
<p class="example">If an "infinite" stream ends for some reason,
|
|
then the duration would change from positive Infinity to the time of
|
|
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
|
|
be fired. Similarly, if the user agent initially estimated the
|
|
<a href="#media-resource">media resource</a>'s duration instead of determining it
|
|
precisely, and later revises the estimate based on new information,
|
|
then the duration would change and the <code title="event-media-durationchange"><a href="#event-media-durationchange">durationchange</a></code> event would
|
|
be fired.</p>
|
|
|
|
<p>Some video files also have an explicit date and time
|
|
corresponding to the zero time in the <a href="#media-timeline">media timeline</a>,
|
|
known as the <dfn id="timeline-offset">timeline offset</dfn>. Initially, the
|
|
<a href="#timeline-offset">timeline offset</a> must be set to Not-a-Number (NaN).</p>
|
|
|
|
<p>The <dfn id="dom-media-startoffsettime" title="dom-media-startOffsetTime"><code>startOffsetTime</code></dfn>
|
|
attribute must return a new <code>Date</code> object representing
|
|
the current <a href="#timeline-offset">timeline offset</a>.</p>
|
|
|
|
</div><hr><p>The <dfn id="attr-media-loop" title="attr-media-loop"><code>loop</code></dfn>
|
|
attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a> that, if specified,
|
|
indicates that the <a href="#media-element">media element</a> is to seek back to the
|
|
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
|
|
effect while the element has a <a href="#current-media-controller">current media
|
|
controller</a>.</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-loop" title="dom-media-loop"><code>loop</code></dfn> IDL
|
|
attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
|
|
same name.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a value that expresses the current state of the element
|
|
with respect to rendering the <a href="#current-playback-position">current playback
|
|
position</a>, from the codes in the list below.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p><a href="#media-element" title="media element">Media elements</a> have a
|
|
<i>ready state</i>, which describes to what degree they are ready
|
|
to be rendered at the <a href="#current-playback-position">current playback position</a>. The
|
|
possible values are as follows; the ready state of a media element
|
|
at any particular time is the greatest value describing the state of
|
|
the element:</p>
|
|
|
|
</div><dl><dt><dfn id="dom-media-have_nothing" title="dom-media-HAVE_NOTHING"><code>HAVE_NOTHING</code></dfn> (numeric value 0)</dt>
|
|
|
|
<dd>No information regarding the <a href="#media-resource">media resource</a> is
|
|
available. No data for the <a href="#current-playback-position">current playback position</a>
|
|
is available. <a href="#media-element" title="media element">Media elements</a>
|
|
whose <code title="dom-media-networkState"><a href="#dom-media-networkstate">networkState</a></code>
|
|
attribute are set to <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code> are always in
|
|
the <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>
|
|
state.</dd>
|
|
|
|
<dt><dfn id="dom-media-have_metadata" title="dom-media-HAVE_METADATA"><code>HAVE_METADATA</code></dfn> (numeric value 1)</dt>
|
|
|
|
<dd>Enough of the resource has been obtained that the duration of
|
|
the resource is available. In the case of a <code><a href="#the-video-element">video</a></code>
|
|
element, the dimensions of the video are also available. The API
|
|
will no longer raise an exception when seeking. No <a href="#media-data">media
|
|
data</a> is available for the immediate <a href="#current-playback-position">current playback
|
|
position</a>.
|
|
The <a href="#text-track" title="text track">text tracks</a>
|
|
are <a href="#the-text-tracks-are-ready" title="the text tracks are ready">ready</a>.
|
|
</dd>
|
|
|
|
<dt><dfn id="dom-media-have_current_data" title="dom-media-HAVE_CURRENT_DATA"><code>HAVE_CURRENT_DATA</code></dfn> (numeric value 2)</dt>
|
|
|
|
<dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
|
|
is available, but either not enough data is available that the user
|
|
agent could successfully advance the <a href="#current-playback-position">current playback
|
|
position</a> in the <a href="#direction-of-playback">direction of playback</a> at all
|
|
without immediately reverting to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> state, or
|
|
there is no more data to obtain in the <a href="#direction-of-playback">direction of
|
|
playback</a>. For example, in video this corresponds to the user
|
|
agent having data from the current frame, but not the next frame;
|
|
and to when <a href="#ended-playback" title="ended playback">playback has
|
|
ended</a>.</dd>
|
|
|
|
<dt><dfn id="dom-media-have_future_data" title="dom-media-HAVE_FUTURE_DATA"><code>HAVE_FUTURE_DATA</code></dfn> (numeric value 3)</dt>
|
|
|
|
<dd>Data for the immediate <a href="#current-playback-position">current playback position</a>
|
|
is available, as well as enough data for the user agent to advance
|
|
the <a href="#current-playback-position">current playback position</a> in the <a href="#direction-of-playback">direction
|
|
of playback</a> at least a little without immediately reverting
|
|
to the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
|
|
state. For example, in video this corresponds to the user agent
|
|
having data for at least the current frame and the next frame. The
|
|
user agent cannot be in this state if <a href="#ended-playback" title="ended
|
|
playback">playback has ended</a>, as the <a href="#current-playback-position">current playback
|
|
position</a> can never advance in this case.</dd>
|
|
|
|
<dt><dfn id="dom-media-have_enough_data" title="dom-media-HAVE_ENOUGH_DATA"><code>HAVE_ENOUGH_DATA</code></dfn> (numeric value 4)</dt>
|
|
|
|
<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
|
|
are met, and, in addition, the user agent estimates that data is
|
|
being fetched at a rate where the <a href="#current-playback-position">current playback
|
|
position</a>, if it were to advance at the <a href="#effective-playback-rate">effective
|
|
playback rate</a>, would not overtake the available data before
|
|
playback reaches the end of the <a href="#media-resource">media resource</a>.</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<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
|
|
user agent must follow the steps given below:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>Apply the first applicable set of substeps from the following
|
|
list:</p>
|
|
|
|
|
|
<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
|
|
ready state is <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code></dt>
|
|
|
|
<dd id="fire-loadedmetadata">
|
|
|
|
<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>
|
|
named <code title="event-media-loadedmetadata"><a href="#event-media-loadedmetadata">loadedmetadata</a></code> at the
|
|
element.</p>
|
|
|
|
<p class="note">Before this task is run, as part of the event
|
|
loop mechanism, the rendering will have been updated to resize
|
|
the <code><a href="#the-video-element">video</a></code> element if appropriate.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
|
|
<dt id="handling-first-frame-available">If the previous ready state
|
|
was <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code> 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
|
|
greater</dt>
|
|
|
|
<dd>
|
|
|
|
<p id="fire-loadeddata">If this is the first time this occurs for
|
|
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,
|
|
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 event</a> named <code title="event-media-loadeddata"><a href="#event-media-loadeddata">loadeddata</a></code> at the element.</p>
|
|
|
|
<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
|
|
<code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>,
|
|
then the relevant steps below must then be run also.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<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,
|
|
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
|
|
less</dt>
|
|
|
|
<dd>
|
|
|
|
<p id="fire-waiting-when-waiting">If the <a href="#media-element">media
|
|
element</a> was <a href="#potentially-playing">potentially playing</a> before its
|
|
<code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute
|
|
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
|
|
the element has not <a href="#ended-playback">ended playback</a>, and playback
|
|
has not <a href="#stopped-due-to-errors">stopped due to errors</a>, and playback has not
|
|
<a href="#paused-for-user-interaction">paused for user interaction</a>, 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 event</a>
|
|
named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at
|
|
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
|
|
simple event</a> named <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the element.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<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
|
|
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>
|
|
|
|
<dd>
|
|
|
|
<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
|
|
simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>.</p>
|
|
|
|
<p>If the element's <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
|
|
attribute is false, 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 event</a> named <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
|
|
|
|
</dd>
|
|
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<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
|
|
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
|
|
a simple event</a> named <code title="event-media-canplay"><a href="#event-media-canplay">canplay</a></code>, and, if the element's
|
|
<code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute is false,
|
|
<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 <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
|
|
|
|
<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
|
|
<a href="#media-element">media element</a> has an <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute specified,
|
|
and the <a href="#media-element">media element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s
|
|
<a href="browsers.html#browsing-context">browsing context</a> did not have the <a href="#sandboxed-automatic-features-browsing-context-flag">sandboxed
|
|
automatic features browsing context flag</a> set when the
|
|
<code><a href="infrastructure.html#document">Document</a></code> was created, then the user agent may also
|
|
set the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute to
|
|
false, <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 <code title="event-media-play"><a href="#event-media-play">play</a></code>, and
|
|
<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 <code title="event-media-playing"><a href="#event-media-playing">playing</a></code>.</p>
|
|
|
|
<p class="note">User agents do not need to support autoplay,
|
|
and it is suggested that user agents honor user preferences on the
|
|
matter. Authors are urged to use the <code title="attr-media-autoplay"><a href="#attr-media-autoplay">autoplay</a></code> attribute rather than
|
|
using script to force the video to play, so as to allow the user
|
|
to override the behavior if so desired.</p>
|
|
|
|
<p>In any case, the user agent must finally <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 <code title="event-media-canplaythrough"><a href="#event-media-canplaythrough">canplaythrough</a></code>.</p>
|
|
|
|
</dd>
|
|
|
|
</dl></li>
|
|
|
|
<li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
|
|
for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
|
|
controller</a>.</p></li>
|
|
|
|
</ol></div><p class="note">It is possible for the ready state of a media
|
|
element to jump between these states discontinuously. For example,
|
|
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
|
|
passing through the <code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code> and
|
|
<code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>
|
|
states.</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-readystate" title="dom-media-readyState"><code>readyState</code></dfn> IDL
|
|
attribute must, on getting, return the value described above that
|
|
describes the current ready state of the <a href="#media-element">media
|
|
element</a>.</p>
|
|
|
|
</div><p>The <dfn id="attr-media-autoplay" title="attr-media-autoplay"><code>autoplay</code></dfn>
|
|
attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. When present, the
|
|
user agent <span class="impl">(as described in the algorithm
|
|
described herein)</span> will automatically begin playback of the
|
|
<a href="#media-resource">media resource</a> as soon as it can do so without
|
|
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
|
|
using script to trigger automatic playback, as this allows the user
|
|
to override the automatic playback when it is not desired, e.g. when
|
|
using a screen reader. Authors are also encouraged to consider not
|
|
using the automatic playback behavior at all, and instead to let the
|
|
user agent wait for the user to start playback explicitly.</p><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-autoplay" title="dom-media-autoplay"><code>autoplay</code></dfn>
|
|
IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
|
|
same name.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if playback is paused; false otherwise.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if playback has reached the end of the <a href="#media-resource">media resource</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the default rate of playback, for when the user is not
|
|
fast-forwarding or reversing through the <a href="#media-resource">media
|
|
resource</a>.</p>
|
|
|
|
<p>Can be set, to change the default rate of playback.</p>
|
|
|
|
<p>The default rate has no direct effect on playback, but if the
|
|
user switches to a fast-forward mode, when they return to the
|
|
normal playback mode, it is expected that the rate of playback
|
|
will be returned to the default rate of playback.</p>
|
|
|
|
<p>When the element has a <a href="#current-media-controller">current media controller</a>,
|
|
the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>
|
|
attribute is ignored and the <a href="#current-media-controller">current media
|
|
controller</a>'s <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code>
|
|
is used instead.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current rate playback, where 1.0 is normal speed.</p>
|
|
|
|
<p>Can be set, to change the rate of playback.</p>
|
|
|
|
<p>When the element has a <a href="#current-media-controller">current media controller</a>,
|
|
the <code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>
|
|
attribute is ignored and the <a href="#current-media-controller">current media
|
|
controller</a>'s <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> is
|
|
used instead.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-played"><a href="#dom-media-played">played</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
|
|
ranges of the <a href="#media-resource">media resource</a> that the user agent has
|
|
played.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-play"><a href="#dom-media-play">play</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
|
|
to false, loading the <a href="#media-resource">media resource</a> and beginning
|
|
playback if necessary. If the playback had ended, will restart it
|
|
from the start.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-pause"><a href="#dom-media-pause">pause</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Sets the <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> attribute
|
|
to true, loading the <a href="#media-resource">media resource</a> if necessary.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-paused" title="dom-media-paused"><code>paused</code></dfn>
|
|
attribute represents whether the <a href="#media-element">media element</a> is
|
|
paused or not. The attribute must initially be true.</p>
|
|
|
|
<p>A <a href="#media-element">media element</a> is a <dfn id="blocked-media-element">blocked media
|
|
element</dfn> if its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute is in the
|
|
<code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code> state or
|
|
the <code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>
|
|
state, or if the element has <a href="#paused-for-user-interaction">paused for user
|
|
interaction</a>.</p>
|
|
|
|
<p>A <a href="#media-element">media element</a> is said to be <dfn id="potentially-playing">potentially
|
|
playing</dfn> when its <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code>
|
|
attribute is false, the element has not <a href="#ended-playback">ended playback</a>,
|
|
playback has not <a href="#stopped-due-to-errors">stopped due to errors</a>,
|
|
the element either has no <a href="#current-media-controller">current media controller</a> or
|
|
has a <a href="#current-media-controller">current media controller</a> but is not <a href="#blocked-on-its-media-controller">blocked
|
|
on its media controller</a>,
|
|
and the element is not a <a href="#blocked-media-element">blocked media element</a>.</p>
|
|
|
|
<p>A <a href="#media-element">media element</a> is said to have <dfn id="ended-playback">ended
|
|
playback</dfn> when:</p>
|
|
|
|
<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,
|
|
and
|
|
|
|
</li><li>
|
|
|
|
<p>Either:
|
|
|
|
</p><ul><li>The <a href="#current-playback-position">current playback position</a> is the end of the
|
|
<a href="#media-resource">media resource</a>, and
|
|
|
|
</li><li>The <a href="#direction-of-playback">direction of playback</a> is forwards, and
|
|
|
|
</li><li>
|
|
Either
|
|
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,
|
|
or the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>.
|
|
|
|
</li></ul><p>Or:
|
|
|
|
</p><ul><li>The <a href="#current-playback-position">current playback position</a> is the
|
|
<a href="#earliest-possible-position">earliest possible position</a>, and
|
|
|
|
</li><li>The <a href="#direction-of-playback">direction of playback</a> is backwards.
|
|
|
|
</li></ul></li>
|
|
|
|
</ul><p>The <dfn id="dom-media-ended" title="dom-media-ended"><code>ended</code></dfn>
|
|
attribute must return true if the <a href="#media-element">media element</a> has
|
|
<a href="#ended-playback">ended playback</a> and the <a href="#direction-of-playback">direction of
|
|
playback</a> is forwards, and false otherwise.</p>
|
|
|
|
<p>A <a href="#media-element">media element</a> is said to have <dfn id="stopped-due-to-errors">stopped due to
|
|
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
|
|
the user agent <a href="#non-fatal-media-error">encounters a
|
|
non-fatal error</a> during the processing of the <a href="#media-data">media
|
|
data</a>, and due to that error, is not able to play the content
|
|
at the <a href="#current-playback-position">current playback position</a>.</p>
|
|
|
|
<p>A <a href="#media-element">media element</a> is said to have <dfn id="paused-for-user-interaction">paused for user
|
|
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
|
|
<code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
|
|
<code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code> and
|
|
the user agent has reached a point in the <a href="#media-resource">media
|
|
resource</a> where the user has to make a selection for the
|
|
resource to continue.
|
|
If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a> when this happens, then the user agent must
|
|
<a href="#report-the-controller-state">report the controller state</a> for the <a href="#media-element">media
|
|
element</a>'s <a href="#current-media-controller">current media controller</a>. If If the
|
|
<a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a> when the user makes a selection, allowing playback
|
|
to resume, the user agent must similarly <a href="#report-the-controller-state">report the controller
|
|
state</a> for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current
|
|
media controller</a>.
|
|
</p>
|
|
|
|
<p>It is possible for a <a href="#media-element">media element</a> to have both
|
|
<a href="#ended-playback">ended playback</a> and <a href="#paused-for-user-interaction">paused for user
|
|
interaction</a> at the same time.</p>
|
|
|
|
<p>When a <a href="#media-element">media element</a> that is <a href="#potentially-playing">potentially
|
|
playing</a> stops playing because it has <a href="#paused-for-user-interaction">paused for user
|
|
interaction</a>, 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 event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p>
|
|
|
|
<p class="note">A <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code>
|
|
DOM event <a href="#fire-waiting-when-waiting">can be fired</a> as a
|
|
result of an element that is <a href="#potentially-playing">potentially playing</a>
|
|
stopping playback due to its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute changing to
|
|
a value lower than <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code>.</p>
|
|
|
|
<p>When the <a href="#current-playback-position">current playback position</a> reaches the end
|
|
of the <a href="#media-resource">media resource</a> when the <a href="#direction-of-playback">direction of
|
|
playback</a> is forwards, then the user agent must follow these
|
|
steps:</p>
|
|
|
|
<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
|
|
and does not have a <a href="#current-media-controller">current media controller</a>,
|
|
then <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
|
|
possible position</a> of the <a href="#media-resource">media resource</a> and
|
|
abort these steps.</p></li>
|
|
<li><p>Stop playback.</p><p class="note">The <code title="dom-media-ended"><a href="#dom-media-ended">ended</a></code> attribute becomes
|
|
true.</p></li>
|
|
|
|
<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
|
|
a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
|
|
|
|
<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
|
|
a simple event</a> named <code title="event-media-ended"><a href="#event-media-ended">ended</a></code>
|
|
at the element.</p></li>
|
|
|
|
</ol><p>When the <a href="#current-playback-position">current playback position</a> reaches the
|
|
<a href="#earliest-possible-position">earliest possible position</a> of the <a href="#media-resource">media
|
|
resource</a> when the <a href="#direction-of-playback">direction of playback</a> is
|
|
backwards, then the user agent must follow these steps:</p>
|
|
|
|
<ol><li><p>Stop playback.</p></li>
|
|
|
|
<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
|
|
a simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.</p></li>
|
|
|
|
</ol><hr><p>The <dfn id="dom-media-defaultplaybackrate" title="dom-media-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
|
|
attribute gives the desired speed at which the <a href="#media-resource">media
|
|
resource</a> is to play, as a multiple of its intrinsic
|
|
speed. The attribute is mutable: on getting it must return the last
|
|
value it was set to, or 1.0 if it hasn't yet been set; on setting
|
|
the attribute must be set to the new value.</p>
|
|
|
|
<p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> is
|
|
used by the user agent when it <a href="#expose-a-user-interface-to-the-user" title="expose a user interface
|
|
to the user">exposes a user interface to the user</a>.</p>
|
|
|
|
<p>The <dfn id="dom-media-playbackrate" title="dom-media-playbackRate"><code>playbackRate</code></dfn>
|
|
attribute gives the <a href="#effective-playback-rate">effective playback rate</a>
|
|
(assuming there is no <a href="#current-media-controller">current media controller</a> overriding it),
|
|
which is the speed at which the <a href="#media-resource">media resource</a> plays,
|
|
as a multiple of its intrinsic speed. If it is not equal to the
|
|
<code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code>,
|
|
then the implication is that the user is using a feature such as
|
|
fast forward or slow motion playback. The attribute is mutable: on
|
|
getting it must return the last value it was set to, or 1.0 if it
|
|
hasn't yet been set; on setting the attribute must be set to the new
|
|
value, and the playback will change speed
|
|
(if the element is <a href="#potentially-playing">potentially playing</a> and there is no
|
|
<a href="#current-media-controller">current media controller</a>).</p>
|
|
|
|
<p id="rateUpdate">When the <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> or
|
|
<code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
|
|
change value (either by being set by script or by being changed
|
|
directly by the user agent, e.g. in response to user control) 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
|
|
event</a> named <code title="event-media-ratechange"><a href="#event-media-ratechange">ratechange</a></code> at the <a href="#media-element">media
|
|
element</a>.</p>
|
|
|
|
<p class="note">The <code title="dom-media-defaultPlaybackRate"><a href="#dom-media-defaultplaybackrate">defaultPlaybackRate</a></code> and
|
|
<code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code> attributes
|
|
have no effect when the <a href="#media-element">media element</a> has a
|
|
<a href="#current-media-controller">current media controller</a>; the namesake attributes on
|
|
the <code><a href="#mediacontroller">MediaController</a></code> object are used instead in that
|
|
situation.</p>
|
|
|
|
<hr><p>The <dfn id="dom-media-played" title="dom-media-played"><code>played</code></dfn>
|
|
attribute must return a new static <a href="#normalized-timeranges-object">normalized
|
|
<code>TimeRanges</code> object</a> that represents the ranges of
|
|
the <a href="#media-resource">media resource</a>, if any, that the user agent has so
|
|
far rendered, at the time the attribute is evaluated.</p>
|
|
|
|
<hr><p>When the <dfn id="dom-media-play" title="dom-media-play"><code>play()</code></dfn>
|
|
method on a <a href="#media-element">media element</a> is invoked, the user agent
|
|
must run the following steps.</p>
|
|
|
|
<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
|
|
the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
|
|
<a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If the <a href="#ended-playback" title="ended playback">playback has ended</a>
|
|
and the <a href="#direction-of-playback">direction of playback</a> is forwards,
|
|
and the <a href="#media-element">media element</a> does not have a <a href="#current-media-controller">current
|
|
media controller</a>,
|
|
<a href="#dom-media-seek" title="dom-media-seek">seek</a> to the <a href="#earliest-possible-position">earliest
|
|
possible position</a> of the <a href="#media-resource">media resource</a>.</p>
|
|
|
|
<p class="note">This <a href="#seekUpdate">will cause</a> the user
|
|
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
|
|
event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the <a href="#media-element">media
|
|
element</a>.</p>
|
|
</li>
|
|
|
|
<li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current
|
|
media controller</a>, then <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 controller</a>.</p>
|
|
|
|
</li><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 true, run
|
|
the following substeps:</p>
|
|
|
|
<ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to false.</p></li>
|
|
|
|
<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>
|
|
named <code title="event-media-play"><a href="#event-media-play">play</a></code> at the element.</p></li>
|
|
|
|
<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 the
|
|
value <code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>,
|
|
<code title="dom-media-HAVE_METADATA"><a href="#dom-media-have_metadata">HAVE_METADATA</a></code>, or
|
|
<code title="dom-media-HAVE_CURRENT_DATA"><a href="#dom-media-have_current_data">HAVE_CURRENT_DATA</a></code>,
|
|
<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 <code title="event-media-waiting"><a href="#event-media-waiting">waiting</a></code> at the
|
|
element.</p>
|
|
|
|
<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
|
|
value <code title="dom-media-HAVE_FUTURE_DATA"><a href="#dom-media-have_future_data">HAVE_FUTURE_DATA</a></code> or
|
|
<code title="dom-media-HAVE_ENOUGH_DATA"><a href="#dom-media-have_enough_data">HAVE_ENOUGH_DATA</a></code>:
|
|
<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 <code title="event-media-playing"><a href="#event-media-playing">playing</a></code> at the
|
|
element.</p>
|
|
|
|
</li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
|
|
flag</a> to false.</p></li>
|
|
|
|
<li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
|
|
for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
|
|
controller</a>.</p></li>
|
|
|
|
</ol><hr><p>When the <dfn id="dom-media-pause" title="dom-media-pause"><code>pause()</code></dfn>
|
|
method is invoked, and when the user agent is required to pause the
|
|
<a href="#media-element">media element</a>, the user agent must run the following
|
|
steps:</p>
|
|
|
|
<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
|
|
the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, invoke the
|
|
<a href="#media-element">media element</a>'s <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a>.</p></li>
|
|
|
|
<li><p>Set the <a href="#media-element">media element</a>'s <a href="#autoplaying-flag">autoplaying
|
|
flag</a> to false.</p></li>
|
|
|
|
<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
|
|
following steps:</p>
|
|
|
|
<ol><li><p>Change the value of <code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> to true.</p></li>
|
|
|
|
<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> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
|
|
element.</p></li>
|
|
|
|
<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> named <code title="event-media-pause"><a href="#event-media-pause">pause</a></code>
|
|
at the element.</p></li>
|
|
|
|
</ol></li>
|
|
|
|
<li><p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, then <a href="#report-the-controller-state">report the controller state</a>
|
|
for the <a href="#media-element">media element</a>'s <a href="#current-media-controller">current media
|
|
controller</a>.</p></li>
|
|
|
|
</ol><hr><p>The
|
|
<dfn id="effective-playback-rate">effective playback rate</dfn> is not necessarily the element's
|
|
<code title="dom-media-playbackRate"><a href="#dom-media-playbackrate">playbackRate</a></code>. When a
|
|
<a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, its <a href="#effective-playback-rate">effective playback rate</a> is the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
|
|
rate</a>. Otherwise, the
|
|
<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>.
|
|
Thus, the <a href="#current-media-controller">current media controller</a> overrides the
|
|
<a href="#media-element">media element</a>.
|
|
</p>
|
|
|
|
<p>If the <a href="#effective-playback-rate">effective playback rate</a> is positive or zero,
|
|
then the <dfn id="direction-of-playback">direction of playback</dfn> is forwards. Otherwise, it
|
|
is backwards.</p>
|
|
|
|
<p id="media-playback">When a <a href="#media-element">media element</a> is
|
|
<a href="#potentially-playing">potentially playing</a> and its <code><a href="infrastructure.html#document">Document</a></code> is a
|
|
<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
|
|
playback position</a> must increase monotonically at
|
|
<a href="#effective-playback-rate">effective playback rate</a> units of media time per unit time
|
|
of the <a href="#media-timeline">media timeline</a>'s clock.</p>
|
|
|
|
<p class="note">The <a href="#effective-playback-rate">effective playback rate</a> can be 0.0,
|
|
in which case the <a href="#current-playback-position">current playback position</a> doesn't
|
|
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
|
|
<code title="event-media-pause"><a href="#event-media-pause">pause</a></code> event doesn't
|
|
fire).</p>
|
|
|
|
<p class="note">This specification doesn't define how the user agent
|
|
achieves the appropriate playback rate — depending on the
|
|
protocol and media available, it is plausible that the user agent
|
|
could negotiate with the server to have the server provide the media
|
|
data at the appropriate rate, so that (except for the period between
|
|
when the rate is changed and when the server updates the stream's
|
|
playback rate) the client doesn't actually have to drop or
|
|
interpolate any frames.</p>
|
|
|
|
<p>When the <a href="#direction-of-playback">direction of playback</a> is backwards, any
|
|
corresponding audio must be muted. When the <a href="#effective-playback-rate">effective playback
|
|
rate</a> is so low or so high that the user agent cannot play
|
|
audio usefully, the corresponding audio must also be muted. If the
|
|
<a href="#effective-playback-rate">effective playback rate</a> is not 1.0, the user agent may
|
|
apply pitch adjustments to the audio as necessary to render it
|
|
faithfully.</p>
|
|
|
|
<p><a href="#media-element" title="media element">Media elements</a> that are
|
|
<a href="#potentially-playing">potentially playing</a> while not <a href="infrastructure.html#in-a-document">in a
|
|
<code>Document</code></a> must not play any video, but should
|
|
play any audio component. Media elements must not stop playing just
|
|
because all references to them have been removed; only once a media
|
|
element is in a state where no further audio could ever be played by
|
|
that element may the element be garbage collected.</p>
|
|
|
|
<p class="note">It is possible for an element to which no explicit
|
|
references exist to play audio, even if such an element is not still
|
|
actively playing: for instance, it could have a <a href="#current-media-controller">current media
|
|
controller</a> that still has references and can still be
|
|
unpaused, or it could be unpaused but stalled waiting for content to
|
|
buffer.</p>
|
|
|
|
<hr><p>When the <a href="#current-playback-position">current playback position</a> of a <a href="#media-element">media
|
|
element</a> changes (e.g. due to playback or seeking), the user
|
|
agent must run the following steps. If the <a href="#current-playback-position">current playback
|
|
position</a> changes while the steps are running, then the user
|
|
agent must wait for the steps to complete, and then must immediately
|
|
rerun the steps.
|
|
(These steps are thus run as often as possible or needed — if
|
|
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
|
|
agent rushes ahead to "catch up".)
|
|
</p>
|
|
|
|
<ol><li><p>Let <var title="">current cues</var> be an ordered list of
|
|
<a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
|
|
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
|
|
showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track showing by
|
|
default">showing by default</a> <a href="#text-track" title="text track">text
|
|
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
|
|
or equal to the <a href="#current-playback-position">current playback position</a> and whose
|
|
<a href="#text-track-cue-end-time" title="text track cue end time">end times</a> are greater
|
|
than the <a href="#current-playback-position">current playback position</a>, in <a href="#text-track-cue-order">text
|
|
track cue order</a>.</p></li>
|
|
|
|
<li><p>Let <var title="">other cues</var> be an ordered list of
|
|
<a href="#text-track-cue" title="text track cue">cues</a>, initialized to contain
|
|
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
|
|
showing">showing</a>, and <a href="#text-track-showing-by-default" title="text track showing by
|
|
default">showing by default</a> <a href="#text-track" title="text track">text
|
|
tracks</a> of the <a href="#media-element">media element</a> that are not
|
|
present in <var title="">current cues</var>, also in <a href="#text-track-cue-order">text
|
|
track cue order</a>.</p></li>
|
|
|
|
<li><p>If the time was reached through the usual monotonic increase
|
|
of the <a href="#current-playback-position">current playback position</a> during normal
|
|
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
|
|
element in the past 15 to 250ms and is not still running event
|
|
handlers for such an event, then 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 event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the element.
|
|
(In the other cases, such as explicit seeks, relevant events get
|
|
fired as part of the overall process of changing the <a href="#current-playback-position">current
|
|
playback position</a>.)</p>
|
|
|
|
<p class="note">The event thus is not to be fired faster than about
|
|
66Hz or slower than 4Hz (assuming the event handlers don't take
|
|
longer than 250ms to run). User agents are encouraged to vary the
|
|
frequency of the event based on the system load and the average
|
|
cost of processing the event each time, so that the UI updates are
|
|
not any more frequent than the user agent can comfortably handle
|
|
while decoding the video.</p></li>
|
|
|
|
<li><p>If all of the <a href="#text-track-cue" title="text track cue">cues</a> in
|
|
<var title="">current cues</var> have their <a href="#text-track-cue-active-flag">text track cue
|
|
active flag</a> set, and none of the <a href="#text-track-cue" title="text track
|
|
cue">cues</a> in <var title="">other cues</var> have their
|
|
<a href="#text-track-cue-active-flag">text track cue active flag</a> set, then abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>If the time was reached through the usual monotonic increase
|
|
of the <a href="#current-playback-position">current playback position</a> during normal
|
|
playback, and there are <a href="#text-track-cue" title="text track cue">cues</a> in
|
|
<var title="">other cues</var> that have both their <a href="#text-track-cue-active-flag">text
|
|
track cue active flag</a> set and their <a href="#text-track-cue-pause-on-exit-flag">text track cue
|
|
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
|
|
element</a>. (In the other cases, such as explicit
|
|
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
|
|
track cue">cue</a> has its <a href="#text-track-cue-pause-on-exit-flag">text track cue pause-on-exit
|
|
flag</a> set.)</p></li>
|
|
|
|
<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>
|
|
|
|
<li><p>For each <a href="#text-track-cue" title="text track cue">text track
|
|
cue</a> in <var title="">other cues</var> that has its
|
|
<a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
|
|
<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
|
|
<code title="event-exit">exit</code> at the
|
|
<code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
|
|
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
|
|
list.</p></li>
|
|
|
|
<li><p>For each <a href="#text-track-cue" title="text track cue">text track
|
|
cue</a> in <var title="">current cues</var> that does not have
|
|
its <a href="#text-track-cue-active-flag">text track cue active flag</a> set, in list order,
|
|
<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
|
|
<code title="event-enter">enter</code> at the
|
|
<code><a href="#texttrackcue">TextTrackCue</a></code> object, and add the <a href="#text-track-cue" title="text
|
|
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
|
|
list.</p></li>
|
|
|
|
<li><p>For each <a href="#text-track">text track</a> in <var title="">affected
|
|
tracks</var>, in the order they were added to the list (which will
|
|
match the relative order of the <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>), <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 <code title="event-cuechange">cuechange</code> at the
|
|
<code><a href="#texttrack">TextTrack</a></code> object, and, if the <a href="#text-track">text
|
|
track</a> has a corresponding <code><a href="#the-track-element">track</a></code> element, to
|
|
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>
|
|
element as well.</p></li>
|
|
|
|
<li><p>Set the <a href="#text-track-cue-active-flag">text track cue active flag</a> of all the
|
|
<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
|
|
active flag</a> of all the <a href="#text-track-cue" title="text track
|
|
cue">cues</a> in the <var title="">other cues</var>.</p></li>
|
|
|
|
<li><p>Run the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
|
|
rendering</a> of each of the <a href="#text-track" title="text track">text
|
|
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
|
|
track showing by default">showing by default</a>.
|
|
</p></li>
|
|
|
|
</ol><p>For the purposes of the algorithm above, a <a href="#text-track-cue">text track
|
|
cue</a> is considered to be part of a <a href="#text-track">text track</a>
|
|
only if it is listed in the <a href="#text-track-list-of-cues">text track list of cues</a>,
|
|
not merely if it is associated with the <a href="#text-track">text
|
|
track</a>.</p>
|
|
|
|
<p class="note">If the <a href="#media-element">media element</a>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code> stops being a <a href="browsers.html#fully-active">fully active</a>
|
|
document, then the playback will <a href="#media-playback">stop</a>
|
|
until the document is active again.</p>
|
|
|
|
<p>When a <a href="#media-element">media element</a> is <a href="infrastructure.html#remove-an-element-from-a-document" title="remove an
|
|
element from a document">removed from a
|
|
<code>Document</code></a>, the user agent must run
|
|
the following steps:</p>
|
|
|
|
<ol><li><p>Asynchronously <a href="webappapis.html#await-a-stable-state">await a stable state</a>, allowing
|
|
the <a href="webappapis.html#concept-task" title="concept-task">task</a> that removed the
|
|
<a href="#media-element">media element</a> from the <code><a href="infrastructure.html#document">Document</a></code> to
|
|
continue. The <a href="webappapis.html#synchronous-section">synchronous section</a> consists of all the
|
|
remaining steps of this algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous
|
|
section</a> are marked with ⌛.)</p></li>
|
|
|
|
<li><p>⌛ If the <a href="#media-element">media element</a> is <a href="infrastructure.html#in-a-document">in a
|
|
<code>Document</code></a>, abort these steps.</p></li>
|
|
|
|
<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
|
|
the value <code title="dom-media-NETWORK_EMPTY"><a href="#dom-media-network_empty">NETWORK_EMPTY</a></code>, abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>⌛ <a href="#dom-media-pause" title="dom-media-pause">Pause</a> the
|
|
<a href="#media-element">media element</a>.</p>
|
|
|
|
</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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if the user agent is currently seeking.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
|
|
ranges of the <a href="#media-resource">media resource</a> to which it is possible
|
|
for the user agent to seek.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-seeking" title="dom-media-seeking"><code>seeking</code></dfn>
|
|
attribute must initially have the value false.</p>
|
|
|
|
<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
|
|
playback position</var> in the <a href="#media-resource">media resource</a>, it means
|
|
that the user agent must run the following steps. This algorithm
|
|
interacts closely with the <a href="webappapis.html#event-loop">event loop</a> mechanism; in
|
|
particular, it has a <a href="webappapis.html#synchronous-section">synchronous
|
|
section</a> (which is triggered as part of the <a href="webappapis.html#event-loop">event
|
|
loop</a> algorithm). Steps in that section are marked with
|
|
⌛.</p>
|
|
|
|
<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
|
|
<code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception (if the seek was in
|
|
response to a DOM method call or setting of an IDL attribute), and
|
|
abort these steps.</p></li>
|
|
|
|
<li><p>If the element's <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute is true,
|
|
then another instance of this algorithm is already running. Abort
|
|
that other instance of the algorithm without waiting for the step
|
|
that it is running to complete.</p></li>
|
|
|
|
<li><p>Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL
|
|
attribute to true.</p></li>
|
|
|
|
<li><p>If the seek was in response to a DOM method call or setting
|
|
of an IDL attribute, then continue the script. The remainder of
|
|
these steps must be run asynchronously. With the exception of the
|
|
steps marked with ⌛, they could be aborted at any time by
|
|
another instance of this algorithm being invoked.</p></li>
|
|
|
|
<li><p>If the <var title="">new playback position</var> is later
|
|
than the end of the <a href="#media-resource">media resource</a>, then let it be the
|
|
end of the <a href="#media-resource">media resource</a> instead.</p></li>
|
|
|
|
<li><p>If the <var title="">new playback position</var> is less
|
|
than the <a href="#earliest-possible-position">earliest possible position</a>, let it be that
|
|
position instead.</p></li>
|
|
|
|
<li><p>If the (possibly now changed) <var title="">new playback
|
|
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
|
|
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
|
|
nearest to the <var title="">new playback position</var>. If two
|
|
positions both satisfy that constraint (i.e. the <var title="">new
|
|
playback position</var> is exactly in the middle between two ranges
|
|
in the <code title="dom-media-seekable"><a href="#dom-media-seekable">seekable</a></code> attribute)
|
|
then use the position that is closest to the <a href="#current-playback-position">current playback
|
|
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
|
|
<code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
|
|
false and abort these steps.</p></li>
|
|
|
|
<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> named <code title="event-media-seeking"><a href="#event-media-seeking">seeking</a></code>
|
|
at the element.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Set the <a href="#current-playback-position">current playback position</a> to the given
|
|
<var title="">new playback position</var>.</p>
|
|
|
|
<p class="note">If the <a href="#media-element">media element</a> was
|
|
<a href="#potentially-playing">potentially playing</a> immediately before it started
|
|
seeking, but seeking caused its <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> attribute to change
|
|
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
|
|
<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
|
|
element.</p>
|
|
|
|
|
|
</li>
|
|
|
|
<li><p>Wait until the user agent has established whether or not the
|
|
<a href="#media-data">media data</a> for the <var title="">new playback
|
|
position</var> is available, and, if it is, until it has decoded
|
|
enough data to play back that position.</p>
|
|
</li>
|
|
|
|
<li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
|
|
section</a> consists of all the remaining steps of this
|
|
algorithm. (Steps in the <a href="webappapis.html#synchronous-section">synchronous section</a> are
|
|
marked with ⌛.)</p></li>
|
|
|
|
<li><p>⌛ Set the <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute to
|
|
false.</p></li>
|
|
|
|
<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
|
|
simple event</a> named <code title="event-media-timeupdate"><a href="#event-media-timeupdate">timeupdate</a></code> at the
|
|
element.</p></li>
|
|
|
|
<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> named <code title="event-media-seeked"><a href="#event-media-seeked">seeked</a></code>
|
|
at the element.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-media-seekable" title="dom-media-seekable"><code>seekable</code></dfn>
|
|
attribute must return a new static <a href="#normalized-timeranges-object">normalized
|
|
<code>TimeRanges</code> object</a> that represents the ranges of
|
|
the <a href="#media-resource">media resource</a>, if any, that the user agent is able
|
|
to seek to, at the time the attribute is evaluated.</p>
|
|
|
|
<p class="note">If the user agent can seek to anywhere in the
|
|
<a href="#media-resource">media resource</a>, e.g. because it is a simple movie file
|
|
and the user agent and the server support HTTP Range requests, then
|
|
the attribute would return an object with one range, whose start is
|
|
the time of the first frame (the <a href="#earliest-possible-position">earliest possible
|
|
position</a>, typically zero), and whose end is the same as the
|
|
time of the first frame plus the <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute's value (which
|
|
would equal the time of the last frame, and might be positive
|
|
Infinity).</p>
|
|
|
|
<p class="note">The range might be continuously changing, e.g. if
|
|
the user agent is buffering a sliding window on an infinite
|
|
stream. This is the behavior seen with DVRs viewing live TV, for
|
|
instance.</p>
|
|
|
|
<p><a href="#media-resource" title="media resource">Media resources</a> might be
|
|
internally scripted or interactive. Thus, a <a href="#media-element">media
|
|
element</a> could play in a non-linear fashion. If this happens,
|
|
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
|
|
<a href="#current-playback-position">current playback position</a> changes in a discontinuous
|
|
fashion (so that the relevant events fire).
|
|
If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, then the user agent must <a href="#seek-the-media-controller">seek the media
|
|
controller</a> appropriately instead.
|
|
</p>
|
|
|
|
</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
|
|
and video tracks. For example, in addition to the primary video and
|
|
audio tracks, a <a href="#media-resource">media resource</a> could have
|
|
foreign-language dubbed dialogues, director's commentaries, audio
|
|
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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
|
|
the audio tracks available in the <a href="#media-resource">media resource</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns an <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object representing
|
|
the video tracks available in the <a href="#media-resource">media resource</a>.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-audiotracks" title="dom-media-audioTracks"><code>audioTracks</code></dfn>
|
|
attribute of a <a href="#media-element">media element</a> must return a
|
|
<a href="infrastructure.html#live">live</a> <code><a href="#multipletracklist">MultipleTrackList</a></code> object representing
|
|
the audio tracks available in the <a href="#media-element">media element</a>'s
|
|
<a href="#media-resource">media resource</a>. The same object must be returned each
|
|
time.</p>
|
|
|
|
<p>The <dfn id="dom-media-videotracks" title="dom-media-videoTracks"><code>videoTracks</code></dfn>
|
|
attribute of a <a href="#media-element">media element</a> must return a
|
|
<a href="infrastructure.html#live">live</a> <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object
|
|
representing the video tracks available in the <a href="#media-element">media
|
|
element</a>'s <a href="#media-resource">media resource</a>. The same object must
|
|
be returned each time.</p>
|
|
|
|
<p class="note">There are only ever two <code><a href="#tracklist">TrackList</a></code>
|
|
objects (one <code><a href="#multipletracklist">MultipleTrackList</a></code> object and one
|
|
<code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object) per <a href="#media-element">media
|
|
element</a>, even if another <a href="#media-resource">media resource</a> is
|
|
loaded into the element: the objects are reused.</p>
|
|
|
|
</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
|
|
<code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> interfaces, used by the attributes
|
|
defined in the previous section, are substantially similar. Their
|
|
common features are defined in the <code><a href="#tracklist">TrackList</a></code> interface,
|
|
from which they both inherit.</p><pre class="idl">interface <dfn id="tracklist">TrackList</dfn> {
|
|
readonly attribute unsigned long <a href="#dom-tracklist-length" title="dom-TrackList-length">length</a>;
|
|
DOMString <a href="#dom-tracklist-getid" title="dom-TrackList-getID">getID</a>(in unsigned long index);
|
|
DOMString <a href="#dom-tracklist-getkind" title="dom-TrackList-getKind">getKind</a>(in unsigned long index);
|
|
DOMString <a href="#dom-tracklist-getlabel" title="dom-TrackList-getLabel">getLabel</a>(in unsigned long index);
|
|
DOMString <a href="#dom-tracklist-getlanguage" title="dom-TrackList-getLanguage">getLanguage</a>(in unsigned long index);
|
|
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-tracklist-onchange" title="handler-TrackList-onchange">onchange</a>;
|
|
};
|
|
|
|
interface <dfn id="multipletracklist">MultipleTrackList</dfn> : <a href="#tracklist">TrackList</a> {
|
|
boolean <a href="#dom-tracklist-isenabled" title="dom-TrackList-isEnabled">isEnabled</a>(in unsigned long index);
|
|
void <a href="#dom-tracklist-enable" title="dom-TrackList-enable">enable</a>(in unsigned long index);
|
|
void <a href="#dom-tracklist-disable" title="dom-TrackList-disable">disable</a>(in unsigned long index);
|
|
};
|
|
|
|
interface <dfn id="exclusivetracklist">ExclusiveTrackList</dfn> : <a href="#tracklist">TrackList</a> {
|
|
readonly attribute unsigned long <a href="#dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex">selectedIndex</a>;
|
|
void <a href="#dom-tracklist-select" title="dom-TrackList-select">select</a>(in unsigned long index);
|
|
};</pre><dl class="domintro"><dt><var title="">tracks</var> . <code title="dom-TrackList-length"><a href="#dom-tracklist-length">length</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the number of tracks in the list.</p>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the ID of the given track. This is the ID that can be
|
|
used with a fragment identifier if the format supports the
|
|
<cite>Media Fragments URI</cite> syntax. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the category the given track falls into. The <a href="#dom-TrackList-getKind-categories">possible track categories</a> are given below.</p>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the label of the given track, if known, or the empty string otherwise.</p>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the language of the given track, if known, or the empty string otherwise.</p>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if the given track is active, and false otherwise.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">audioTracks</var> . <code title="dom-TrackList-enable"><a href="#dom-tracklist-enable">enable</a></code>( <var title="">index</var> )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Enables the given track.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">audioTracks</var> . <code title="dom-TrackList-disable"><a href="#dom-tracklist-disable">disable</a></code>( <var title="">index</var> )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Disables the given track.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">videoTracks</var> . <code title="dom-TrackList-selectedIndex"><a href="#dom-tracklist-selectedindex">isEnabled</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the index of the currently selected track, if any, or −1 otherwise.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">videoTracks</var> . <code title="dom-TrackList-select"><a href="#dom-tracklist-select">select</a></code>( <var title="">index</var> )</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Selects the given track.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-tracklist-length" title="dom-TrackList-length"><code>length</code></dfn>
|
|
attribute must return the number of tracks represented by the
|
|
<code><a href="#tracklist">TrackList</a></code> object at the time of getting.</p>
|
|
|
|
<p>Tracks in a <code><a href="#tracklist">TrackList</a></code> object must be consistently
|
|
ordered. If the <a href="#media-resource">media resource</a> is in a format that
|
|
defines an order, then that order must be used; otherwise, the order
|
|
must be the relative order in which the tracks are declared in the
|
|
<a href="#media-resource">media resource</a>. Each track in a <code><a href="#tracklist">TrackList</a></code>
|
|
thus has an index; the first has the index 0, and each subsequent
|
|
track is numbered one higher than the previous one.</p>
|
|
|
|
<p>The <dfn id="dom-tracklist-getid" title="dom-TrackList-getID"><code>getID(<var title="">index</var>)</code></dfn> method must return the identifier
|
|
of the track with index <var title="">index</var>, if there is one.
|
|
If there is no such track, then the method must instead throw an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If the <a href="#media-resource">media
|
|
resource</a> is in a format that supports the <cite>Media
|
|
Fragments URI</cite> fragment identifier syntax, the returned
|
|
identifier must be the same identifier that would enable the track
|
|
if used as the name of a track in the track dimension of such a
|
|
fragment identifier. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
|
|
|
|
<p>The <dfn id="dom-tracklist-getkind" title="dom-TrackList-getKind"><code>getKind(<var title="">index</var>)</code></dfn> method must return the category
|
|
of the track with index <var title="">index</var>, if there is one.
|
|
If there is no such track, then the method must instead throw an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
|
|
|
|
<p>The category of a track is the string given in the first column
|
|
of the table below that is the most appropriate for the track based
|
|
on the definitions in the table's second and third columns, as
|
|
determined by the metadata included in the track in the <a href="#media-resource">media
|
|
resource</a>. For Ogg files, the Role header of the track gives
|
|
the relevant metadata. The cell in the third column of a row says
|
|
what the category given in the cell in the first column of that row
|
|
applies to; a category is only appropriate for an audio track if it
|
|
applies to audio tracks, and a category is only appropriate for
|
|
video tracks if it applies to video tracks.</p>
|
|
|
|
</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>
|
|
<thead><tr><th>Category
|
|
</th><th>Definition
|
|
</th><th>Applies to...</th>
|
|
<th>Examples
|
|
</th></tr></thead><tbody><tr><td>"<dfn id="dom-tracklist-getkind-alternate" title="dom-TrackList-getKind-alternate"><code>alternative</code></dfn>"
|
|
</td><td>A possible alternative to the main track, e.g. a different take of a song (audio), or a different angle (video).
|
|
</td><td>Audio and video.
|
|
</td><td>Ogg: "audio/alterate" or "video/alternate".
|
|
|
|
</td></tr><tr><td>"<dfn id="dom-tracklist-getkind-description" title="dom-TrackList-getKind-description"><code>description</code></dfn>"
|
|
</td><td>An audio description of a video track.
|
|
</td><td>Audio only.
|
|
</td><td>Ogg: "audio/audiodesc".
|
|
|
|
</td></tr><tr><td>"<dfn id="dom-tracklist-getkind-main" title="dom-TrackList-getKind-main"><code>main</code></dfn>"
|
|
</td><td>The primary audio or video track.
|
|
</td><td>Audio and video.
|
|
</td><td>Ogg: "audio/main" or "video/main"; WebM: the "FlagDefault" element is set.
|
|
|
|
</td></tr><tr><td>"<dfn id="dom-tracklist-getkind-sign" title="dom-TrackList-getKind-sign"><code>sign</code></dfn>"
|
|
</td><td>A sign-language interpretation of an audio track.
|
|
</td><td>Video only.
|
|
</td><td>Ogg: "video/sign".
|
|
|
|
</td></tr><tr><td>"<dfn id="dom-tracklist-getkind-translation" title="dom-TrackList-getKind-translation"><code>translation</code></dfn>"
|
|
</td><td>A translated version of the main track.
|
|
</td><td>Audio only.
|
|
</td><td>Ogg: "audio/dub".
|
|
|
|
</td></tr><tr><td>"<dfn id="dom-tracklist-getkind-none" title="dom-TrackList-getKind-none"><code></code></dfn>" (empty string)
|
|
</td><td>No explicit kind, or the kind given by the track's metadata is not recognised by the user agent.
|
|
</td><td>Audio and video.
|
|
</td><td>Any other track type or track role.
|
|
|
|
</td></tr></tbody></table><div class="impl">
|
|
|
|
<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
|
|
the track with index <var title="">index</var>, if there is one and
|
|
it has a label. If there is no such track, then the method must
|
|
instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is
|
|
a track with index <var title="">index</var>, but it has no label,
|
|
then the method must return the empty string.</p>
|
|
|
|
<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
|
|
language tag of the language of the track with index <var title="">index</var>, if there is one and it has a language. If
|
|
there is no such track, then the method must instead throw an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception. If there is a track with
|
|
index <var title="">index</var>, but it has no language, or the user
|
|
agent is not able to express that language as a BCP 47 language tag
|
|
(for example because the language information in the <a href="#media-resource">media
|
|
resource</a>'s format is a free-form string without a defined
|
|
interpretation), then the method must return the empty string.</p>
|
|
|
|
<hr><p>A <code><a href="#multipletracklist">MultipleTrackList</a></code> object represents a track list
|
|
where multiple tracks can be enabled simultaneously. Each track is
|
|
either enabled or disabled.</p>
|
|
|
|
<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
|
|
is a track with index <var title="">index</var>, and it is currently
|
|
enabled, false if there is a track with index <var title="">index</var>, but it is currently disabled, and must throw
|
|
an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception if there is no track with
|
|
index <var title="">index</var>.</p>
|
|
|
|
<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
|
|
index <var title="">index</var>, if there is one. If there is not,
|
|
it must instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
|
|
|
|
<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
|
|
index <var title="">index</var>, if there is one. If there is not,
|
|
it must instead throw an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
|
|
|
|
<p>Whenever a track is enabled or disabled, 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 event</a> named
|
|
<code title="event-media-change">change</code> at the
|
|
<code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
|
|
|
|
<hr><p>An <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object represents a track list
|
|
where exactly one track is selected at a time.</p>
|
|
|
|
<p>The <dfn id="dom-tracklist-selectedindex" title="dom-TrackList-selectedIndex"><code>selectedIndex</code></dfn>
|
|
attribute must return the index of the currently selected track. If
|
|
the <code><a href="#exclusivetracklist">ExclusiveTrackList</a></code> object does not represent any
|
|
tracks, it must instead return −1.</p>
|
|
|
|
<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
|
|
<var title="">index</var>, if there is one, unselecting whichever
|
|
track was previously selected. If there is no track with index <var title="">index</var>, it must instead throw an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception.</p>
|
|
|
|
<p>Whenever the selected track is changed, 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 event</a> named
|
|
<code title="event-media-change">change</code> at the
|
|
<code><a href="#multipletracklist">MultipleTrackList</a></code> object.</p>
|
|
|
|
<hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> (and their
|
|
corresponding <a href="webappapis.html#event-handler-event-type" title="event handler event type">event handler
|
|
event types</a>) that must be supported, as IDL attributes, by
|
|
all objects implementing the <code><a href="#tracklist">TrackList</a></code>
|
|
interface:</p>
|
|
|
|
<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>
|
|
</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>
|
|
</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
|
|
<a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
|
|
|
|
|
|
|
|
</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
|
|
<code title="dom-media-videoTracks"><a href="#dom-media-videotracks">videoTracks</a></code> attributes
|
|
allow scripts to select which track should play, but it is also
|
|
possible to select specific tracks declaratively, by specifying
|
|
particular tracks in the fragment identifier of the <a href="urls.html#url">URL</a>
|
|
of the <a href="#media-resource">media resource</a>. The format of the fragment
|
|
identifier depends on the <a href="infrastructure.html#mime-type">MIME type</a> of the <a href="#media-resource">media
|
|
resource</a>. <a href="references.html#refsRFC2046">[RFC2046]</a> <a href="references.html#refsRFC3986">[RFC3986]</a></p><div class="example">
|
|
|
|
<p>In this example, a video that uses a format that supports the
|
|
<cite>Media Fragments URI</cite> fragment identifier syntax is
|
|
embedded in such a way that the alternative angles labeled
|
|
"Alternative" are enabled instead of the default video track. <a href="references.html#refsMEDIAFRAG">[MEDIAFRAG]</a></p>
|
|
|
|
<pre><video src="myvideo#track=Alternative"></video></pre>
|
|
|
|
|
|
</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
|
|
<code><a href="#mediacontroller">MediaController</a></code>. A <code><a href="#mediacontroller">MediaController</a></code> is an
|
|
object that coordinates the playback of multiple <a href="#media-element" title="media
|
|
element">media elements</a>, for instance so that a sign-language
|
|
interpreter track can be overlaid on a video track, with the two
|
|
being kept in sync.</p><p>By default, a <a href="#media-element">media element</a> has no
|
|
<code><a href="#mediacontroller">MediaController</a></code>. An implicit
|
|
<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.
|
|
An explicit <code><a href="#mediacontroller">MediaController</a></code> can be assigned directly
|
|
using the <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> IDL
|
|
attribute.</p><p><a href="#media-element" title="media element">Media elements</a> with a
|
|
<code><a href="#mediacontroller">MediaController</a></code> are said to be <i>slaved</i> to their
|
|
controller. The <code><a href="#mediacontroller">MediaController</a></code> modifies the playback
|
|
rate and the playback volume of each of the <a href="#media-element" title="media
|
|
element">media elements</a> slaved to it, and ensures that when
|
|
any of its slaved <a href="#media-element" title="media element">media elements</a>
|
|
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
|
|
<code><a href="#mediacontroller">MediaController</a></code>, its playback rate is fixed to that of
|
|
the other tracks in the same <code><a href="#mediacontroller">MediaController</a></code>, and any
|
|
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>]
|
|
interface <dfn id="mediacontroller">MediaController</dfn> {
|
|
readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-buffered" title="dom-MediaController-buffered">buffered</a>;
|
|
readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-seekable" title="dom-MediaController-seekable">seekable</a>;
|
|
readonly attribute double <a href="#dom-mediacontroller-duration" title="dom-MediaController-duration">duration</a>;
|
|
attribute double <a href="#dom-mediacontroller-currenttime" title="dom-MediaController-currentTime">currentTime</a>;
|
|
|
|
readonly attribute boolean <a href="#dom-mediacontroller-paused" title="dom-MediaController-paused">paused</a>;
|
|
readonly attribute <a href="#timeranges">TimeRanges</a> <a href="#dom-mediacontroller-played" title="dom-MediaController-played">played</a>;
|
|
void <a href="#dom-mediacontroller-play" title="dom-MediaController-play">play</a>();
|
|
void <a href="#dom-mediacontroller-pause" title="dom-MediaController-pause">pause</a>();
|
|
|
|
attribute double <a href="#dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate">defaultPlaybackRate</a>;
|
|
attribute double <a href="#dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate">playbackRate</a>;
|
|
|
|
attribute double <a href="#dom-mediacontroller-volume" title="dom-MediaController-volume">volume</a>;
|
|
attribute boolean <a href="#dom-mediacontroller-muted" title="dom-MediaController-muted">muted</a>;
|
|
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onemptied" title="handler-MediaController-onemptied">onemptied</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onloadedmetadata" title="handler-MediaController-onloadedmetadata">onloadedmetadata</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onloadeddata" title="handler-MediaController-onloadeddata">onloadeddata</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-oncanplay" title="handler-MediaController-oncanplay">oncanplay</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-oncanplaythrough" title="handler-MediaController-oncanplaythrough">oncanplaythrough</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onplaying" title="handler-MediaController-onplaying">onplaying</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onwaiting" title="handler-MediaController-onwaiting">onwaiting</a>;
|
|
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-ondurationchange" title="handler-MediaController-ondurationchange">ondurationchange</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-ontimeupdate" title="handler-MediaController-ontimeupdate">ontimeupdate</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onplay" title="handler-MediaController-onplay">onplay</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onpause" title="handler-MediaController-onpause">onpause</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onratechange" title="handler-MediaController-onratechange">onratechange</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-mediacontroller-onvolumechange" title="handler-MediaController-onvolumechange">onvolumechange</a>;
|
|
};</pre><dl class="domintro"><dt><var title="">controller</var> = new <code title="dom-MediaController"><a href="#dom-mediacontroller">MediaController</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a new <code><a href="#mediacontroller">MediaController</a></code> object.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-controller"><a href="#dom-media-controller">controller</a></code> [ = <var title="">controller</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<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>
|
|
|
|
<p>Can be set, to set an explicit <code><a href="#mediacontroller">MediaController</a></code>.
|
|
Doing so removes the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, if
|
|
any.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-buffered"><a href="#dom-mediacontroller-buffered">buffered</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
|
|
intersection of the time ranges for which the user agent has all
|
|
relevant media data for all the slaved <a href="#media-element" title="media
|
|
element">media elements</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-seekable"><a href="#dom-mediacontroller-seekable">seekable</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
|
|
intersection of the time ranges into which the user agent can seek
|
|
for all the slaved <a href="#media-element" title="media element">media
|
|
elements</a>.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the difference between the earliest playable moment and
|
|
the latest playable moment (not considering whether the data in
|
|
question is actually buffered or directly seekable, but not
|
|
including time in the future for infinite streams). Will return
|
|
zero if there is no media.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-currentTime"><a href="#dom-mediacontroller-currenttime">currentTime</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the <a href="#current-playback-position">current playback position</a>, in seconds,
|
|
as a position between zero time and the current <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code>.</p>
|
|
|
|
<p>Can be set, to seek to the given time.</p><p>
|
|
|
|
</p></dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if playback is paused; false otherwise. When this
|
|
attribute is true, any <a href="#media-element">media element</a> slaved to this
|
|
controller will be stopped.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-played"><a href="#dom-mediacontroller-played">played</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns a <code><a href="#timeranges">TimeRanges</a></code> object that represents the
|
|
union of the time ranges in all the slaved <a href="#media-element" title="media
|
|
element">media elements</a> that have been played.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-play"><a href="#dom-mediacontroller-play">play</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
|
|
attribute to false.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-pause"><a href="#dom-mediacontroller-pause">pause</a></code>()</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Sets the <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code>
|
|
attribute to true.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-defaultPlaybackRate"><a href="#dom-mediacontroller-defaultplaybackrate">defaultPlaybackRate</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the default rate of playback.</p>
|
|
|
|
<p>Can be set, to change the default rate of playback.</p>
|
|
|
|
<p>This default rate has no direct effect on playback, but if the
|
|
user switches to a fast-forward mode, when they return to the
|
|
normal playback mode, it is expected that rate of playback (<code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code>) will
|
|
be returned to this default rate.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-playbackRate"><a href="#dom-mediacontroller-playbackrate">playbackRate</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current rate of playback.</p>
|
|
|
|
<p>Can be set, to change the rate of playback.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-volume"><a href="#dom-mediacontroller-volume">volume</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current playback volume multiplier, as a number in
|
|
the range 0.0 to 1.0, where 0.0 is the quietest and 1.0 the
|
|
loudest.</p>
|
|
|
|
<p>Can be set, to change the volume multiplier.</p>
|
|
|
|
<p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
|
|
in the range 0.0 .. 1.0.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">controller</var> . <code title="dom-MediaController-muted"><a href="#dom-mediacontroller-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns true if all audio is muted (regardless of other
|
|
attributes either on the controller or on any <a href="#media-element" title="media
|
|
element">media elements</a> slaved to this controller), and
|
|
false otherwise.</p>
|
|
|
|
<p>Can be set, to change whether the audio is muted or not.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>A <a href="#media-element">media element</a> can have a <dfn id="current-media-controller">current media
|
|
controller</dfn>, which is a <code><a href="#mediacontroller">MediaController</a></code> object.
|
|
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
|
|
not have a <a href="#current-media-controller">current media controller</a>. (If it is created
|
|
<em>with</em> such an attribute, then that attribute initializes the
|
|
<a href="#current-media-controller">current media controller</a>, as defined below.)</p>
|
|
|
|
<p>The <dfn id="slaved-media-elements">slaved media elements</dfn> of a
|
|
<code><a href="#mediacontroller">MediaController</a></code> are the <a href="#media-element" title="media
|
|
element">media elements</a> whose <a href="#current-media-controller">current media
|
|
controller</a> is that <code><a href="#mediacontroller">MediaController</a></code>. All the
|
|
<a href="#slaved-media-elements">slaved media elements</a> of a <code><a href="#mediacontroller">MediaController</a></code>
|
|
must use the same clock for their definition of their <a href="#media-timeline">media
|
|
timeline</a>'s unit time.</p>
|
|
|
|
<hr><p>The <dfn id="dom-media-controller" title="dom-media-controller"><code>controller</code></dfn> attribute
|
|
on a <a href="#media-element">media element</a>, on getting, must return the
|
|
element's <a href="#current-media-controller">current media controller</a>, if any, or null
|
|
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,
|
|
and then set the <a href="#current-media-controller">current media controller</a> to the given
|
|
value. If the given value is null, the element no longer has a
|
|
<a href="#current-media-controller">current media controller</a>; if it is not null, then the
|
|
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
|
|
new media controller</a>.</p>
|
|
|
|
<hr><p>The <dfn id="dom-mediacontroller" title="dom-MediaController"><code>MediaController()</code></dfn>
|
|
constructor, when invoked, must return a newly created
|
|
<code><a href="#mediacontroller">MediaController</a></code> object.</p>
|
|
|
|
<hr><p>The <dfn id="dom-mediacontroller-seekable" title="dom-MediaController-seekable"><code>seekable</code></dfn>
|
|
attribute must return a new static <a href="#normalized-timeranges-object">normalized
|
|
<code>TimeRanges</code> object</a> that represents the
|
|
intersection of the ranges of the <a href="#media-resource" title="media resource">media
|
|
resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
|
|
user agent is able to seek to, at the time the attribute is
|
|
evaluated.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-buffered" title="dom-MediaController-buffered"><code>buffered</code></dfn>
|
|
attribute must return a new static <a href="#normalized-timeranges-object">normalized
|
|
<code>TimeRanges</code> object</a> that represents the
|
|
intersection of the ranges of the <a href="#media-resource" title="media resource">media
|
|
resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
|
|
user agent has buffered, at the time the attribute is evaluated.
|
|
Users agents must accurately determine the ranges available, even
|
|
for media streams where this can only be determined by tedious
|
|
inspection.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-duration" title="dom-MediaController-duration"><code>duration</code></dfn>
|
|
attribute must return the <a href="#media-controller-duration">media controller
|
|
duration</a>.</p>
|
|
|
|
<p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
|
|
<a href="#media-controller-duration">media controller duration</a> changes, whichever happens
|
|
least often, 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 event</a> named <code title="event-MediaController-durationchange"><a href="#event-mediacontroller-durationchange">durationchange</a></code>
|
|
at the <code><a href="#mediacontroller">MediaController</a></code>. If the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-duration">media controller
|
|
duration</a> decreases such that the <a href="#media-controller-position">media controller
|
|
position</a> is greater than the <a href="#media-controller-duration">media controller
|
|
duration</a>, the user agent must immediately <a href="#seek-the-media-controller">seek the
|
|
media controller</a> to <a href="#media-controller-duration">media controller
|
|
duration</a>.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-currenttime" title="dom-MediaController-currentTime"><code>currentTime</code></dfn>
|
|
attribute must return the <a href="#media-controller-position">media controller position</a> on
|
|
getting, and on setting must <a href="#seek-the-media-controller">seek the media controller</a>
|
|
to the new value.</p>
|
|
|
|
<p>Every 15 to 250ms, or whenever the <code><a href="#mediacontroller">MediaController</a></code>'s
|
|
<a href="#media-controller-position">media controller position</a> changes, whichever happens
|
|
least often, 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 event</a> named <code title="event-MediaController-timeupdate"><a href="#event-mediacontroller-timeupdate">timeupdate</a></code> at the
|
|
<code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
<hr><p>When a <code><a href="#mediacontroller">MediaController</a></code> is created it is a
|
|
<dfn id="playing-media-controller">playing media controller</dfn>. It can be changed into a
|
|
<dfn id="paused-media-controller">paused media controller</dfn> and back either via the user
|
|
agent's user interface (when the element is <a href="#expose-a-user-interface-to-the-user" title="expose a
|
|
user interface to the user">exposing a user interface to the
|
|
user</a>) or by script using the APIs defined in this section
|
|
(see below).</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-paused" title="dom-MediaController-paused"><code>paused</code></dfn>
|
|
attribute must return true if the <code><a href="#mediacontroller">MediaController</a></code>
|
|
object is a <a href="#paused-media-controller">paused media controller</a>, and false
|
|
otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-played" title="dom-MediaController-played"><code>played</code></dfn>
|
|
attribute must return a new static <a href="#normalized-timeranges-object">normalized
|
|
<code>TimeRanges</code> object</a> that represents the union of
|
|
the ranges of the <a href="#media-resource" title="media resource">media
|
|
resources</a> of the <a href="#slaved-media-elements">slaved media elements</a> that the
|
|
user agent has so far rendered, at the time the attribute is
|
|
evaluated.</p>
|
|
|
|
<p>When the <dfn id="dom-mediacontroller-pause" title="dom-MediaController-pause"><code>pause()</code></dfn> method
|
|
is invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#playing-media-controller">playing
|
|
media controller</a> then the user agent must change the
|
|
<code><a href="#mediacontroller">MediaController</a></code> into a <a href="#paused-media-controller">paused media
|
|
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
|
|
event</a> named <code title="event-MediaController-pause"><a href="#event-mediacontroller-pause">pause</a></code> at the
|
|
<code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
|
|
state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
<p>When the <dfn id="dom-mediacontroller-play" title="dom-MediaController-play"><code>play()</code></dfn> method is
|
|
invoked, if the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#paused-media-controller">paused media
|
|
controller</a>, the user agent must change the
|
|
<code><a href="#mediacontroller">MediaController</a></code> into a <a href="#playing-media-controller">playing media
|
|
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
|
|
event</a> named <code title="event-MediaController-play"><a href="#event-mediacontroller-play">play</a></code> at the
|
|
<code><a href="#mediacontroller">MediaController</a></code>, and then <a href="#report-the-controller-state">report the controller
|
|
state</a> of the <code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
<hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-default-playback-rate">media controller
|
|
default playback rate</dfn> and a <dfn id="media-controller-playback-rate">media controller playback
|
|
rate</dfn>, which must both be set to 1.0 when the
|
|
<code><a href="#mediacontroller">MediaController</a></code> object is created.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-defaultplaybackrate" title="dom-MediaController-defaultPlaybackRate"><code>defaultPlaybackRate</code></dfn>
|
|
attribute, on getting, must return the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
|
|
playback rate</a>, and on setting, must set the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-default-playback-rate">media controller default
|
|
playback rate</a> to the new value, then <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 <code title="event-MediaController-ratechange"><a href="#event-mediacontroller-ratechange">ratechange</a></code> at the
|
|
<code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-playbackrate" title="dom-MediaController-playbackRate"><code>playbackRate</code></dfn>
|
|
attribute, on getting, must return the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
|
|
rate</a>, and on setting, must set the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-playback-rate">media controller playback
|
|
rate</a> to the new value, then <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 <code title="event-MediaController-ratechange"><a href="#event-mediacontroller-ratechange">ratechange</a></code> at the
|
|
<code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
<hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-volume-multiplier">media controller volume
|
|
multiplier</dfn>, which must be set to 1.0 when the
|
|
<code><a href="#mediacontroller">MediaController</a></code> object is created, and a <dfn id="media-controller-mute-override">media
|
|
controller mute override</dfn>, much must initially be false.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-volume" title="dom-MediaController-volume"><code>volume</code></dfn>
|
|
attribute, on getting, must return the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-volume-multiplier">media controller volume
|
|
multiplier</a>, and on setting, if the new value is in the range
|
|
0.0 to 1.0 inclusive, must set the <code><a href="#mediacontroller">MediaController</a></code>'s
|
|
<a href="#media-controller-volume-multiplier">media controller volume multiplier</a> to the new 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 event</a> named
|
|
<code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code>
|
|
at the <code><a href="#mediacontroller">MediaController</a></code>. If the new value is outside the
|
|
range 0.0 to 1.0 inclusive, then, on setting, an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
|
|
|
|
<p>The <dfn id="dom-mediacontroller-muted" title="dom-MediaController-muted"><code>muted</code></dfn>
|
|
attribute, on getting, must return the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
|
|
override</a>, and on setting, must set the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-mute-override">media controller mute
|
|
override</a> to the new 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 event</a> named <code title="event-MediaController-volumechange"><a href="#event-mediacontroller-volumechange">volumechange</a></code> at
|
|
the <code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
<hr><p>The <a href="#media-resource" title="media resource">media resources</a> of all
|
|
the <a href="#slaved-media-elements">slaved media elements</a> of a
|
|
<code><a href="#mediacontroller">MediaController</a></code> have a defined temporal relationship
|
|
which provides relative offsets between the zero time of each such
|
|
<a href="#media-resource">media resource</a>: for <a href="#media-resource" title="media resource">media
|
|
resources</a> with a <a href="#timeline-offset">timeline offset</a>, their relative
|
|
offsets are the difference between their <a href="#timeline-offset">timeline
|
|
offset</a>; the zero times of all the <a href="#media-resource" title="media
|
|
resource">media resources</a> without a <a href="#timeline-offset">timeline
|
|
offset</a> are not offset from each other (i.e. the origins of
|
|
their timelines are cotemporal); and finally, the zero time of the
|
|
<a href="#media-resource">media resource</a> with the earliest <a href="#timeline-offset">timeline
|
|
offset</a> (if any) is not offset from the zero times of the
|
|
<a href="#media-resource" title="media resource">media resources</a> without a
|
|
<a href="#timeline-offset">timeline offset</a> (i.e. the origins of <a href="#media-resource" title="media
|
|
resource">media resources</a> without a <a href="#timeline-offset">timeline
|
|
offset</a> are further cotemporal with the earliest defined point
|
|
on the timeline of the <a href="#media-resource">media resource</a> with the earliest
|
|
<a href="#timeline-offset">timeline offset</a>).</p>
|
|
|
|
<p>The <dfn id="media-resource-end-position">media resource end position</dfn> of a <a href="#media-resource">media
|
|
resource</a> in a <a href="#media-element">media element</a> is defined as
|
|
follows: if the <a href="#media-resource">media resource</a> has a finite and known
|
|
duration, the <a href="#media-resource-end-position">media resource end position</a> is the
|
|
duration of the <a href="#media-resource">media resource</a>'s timeline (the last
|
|
defined position on that timeline); otherwise, the <a href="#media-resource">media
|
|
resource</a>'s duration is infinite or unknown, and the
|
|
<a href="#media-resource-end-position">media resource end position</a> is the time of the last
|
|
frame of <a href="#media-data">media data</a> currently available for that
|
|
<a href="#media-resource">media resource</a>.</p>
|
|
|
|
<p>Each <code><a href="#mediacontroller">MediaController</a></code> also has its own defined
|
|
timeline. On this timeline, all the <a href="#media-resource" title="media
|
|
resource">media resources</a> of all the <a href="#slaved-media-elements">slaved media
|
|
elements</a> of the <code><a href="#mediacontroller">MediaController</a></code> are temporally
|
|
aligned according to their defined offsets. The <dfn id="media-controller-duration">media
|
|
controller duration</dfn> of that <code><a href="#mediacontroller">MediaController</a></code> is
|
|
the time from the earliest <a href="#earliest-possible-position">earliest possible position</a>,
|
|
relative to this <code><a href="#mediacontroller">MediaController</a></code> timeline, of any of
|
|
the <a href="#media-resource" title="media resource">media resources</a> of the
|
|
<a href="#slaved-media-elements">slaved media elements</a> of the
|
|
<code><a href="#mediacontroller">MediaController</a></code>, to the time of the latest <a href="#media-resource-end-position">media
|
|
resource end position</a> of the <a href="#media-resource" title="media
|
|
resource">media resources</a> of the <a href="#slaved-media-elements">slaved media
|
|
elements</a> of the <code><a href="#mediacontroller">MediaController</a></code>, again relative
|
|
to this <code><a href="#mediacontroller">MediaController</a></code> timeline.</p>
|
|
|
|
<p>Each <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="media-controller-position">media controller
|
|
position</dfn>. This is the time on the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s timeline at which the user agent is
|
|
trying to play the <a href="#slaved-media-elements">slaved media elements</a>. When a
|
|
<code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#media-controller-position">media controller
|
|
position</a> is initially zero.</p>
|
|
|
|
<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
|
|
to speed with its new media controller">bring a media element up to
|
|
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>
|
|
to the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#media-controller-position">media controller
|
|
position</a> relative to the <a href="#media-element">media element</a>'s
|
|
timeline, discarding any resulting exceptions.</p>
|
|
|
|
<p>When the user agent is to <dfn id="seek-the-media-controller">seek the media controller</dfn> to
|
|
a particular <var title="">new playback position</var>, it must
|
|
follow these steps:</p>
|
|
|
|
<ol><li><p>If the <var title="">new playback position</var> is less
|
|
than zero, then set it to zero.</p></li>
|
|
|
|
<li><p>If the <var title="">new playback position</var> is greater
|
|
than the <a href="#media-controller-duration">media controller duration</a>, then set it to the
|
|
<a href="#media-controller-duration">media controller duration</a>.</p></li>
|
|
|
|
<li><p>Set the <a href="#media-controller-position">media controller position</a> to the <var title="">new playback position</var>.</p></li>
|
|
|
|
<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
|
|
<var title="">new playback position</var> relative to the
|
|
<a href="#media-element">media element</a> timeline, discarding any resulting
|
|
exceptions.</p></li>
|
|
</ol><p>A <code><a href="#mediacontroller">MediaController</a></code> is a <dfn id="blocked-media-controller">blocked media
|
|
controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
|
|
<a href="#paused-media-controller">paused media controller</a>, or if any of its <a href="#slaved-media-elements">slaved
|
|
media elements</a> are <a href="#blocked-media-element" title="blocked media
|
|
element">blocked media elements</a>, or if any of its
|
|
<a href="#slaved-media-elements">slaved media elements</a> whose <a href="#autoplaying-flag">autoplaying
|
|
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
|
|
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>
|
|
|
|
<p>A <a href="#media-element">media element</a> is <dfn id="blocked-on-its-media-controller">blocked on its media
|
|
controller</dfn> if the <code><a href="#mediacontroller">MediaController</a></code> is a
|
|
<a href="#blocked-media-controller">blocked media controller</a>, or if its <a href="#media-controller-position">media
|
|
controller position</a> is either before the <a href="#media-resource">media
|
|
resource</a>'s <a href="#earliest-possible-position">earliest possible position</a> relative
|
|
to the <code><a href="#mediacontroller">MediaController</a></code>'s timeline or after the end of
|
|
the <a href="#media-resource">media resource</a> relative to the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s timeline.</p>
|
|
|
|
<p id="controller-playback">When a <code><a href="#mediacontroller">MediaController</a></code> is
|
|
not a <a href="#blocked-media-controller">blocked media controller</a> and it has at least one
|
|
<a href="#slaved-media-elements" title="slaved media elements">slaved media element</a>
|
|
whose <code><a href="infrastructure.html#document">Document</a></code> is a <a href="browsers.html#fully-active">fully active</a>
|
|
<code><a href="infrastructure.html#document">Document</a></code>, the <code><a href="#mediacontroller">MediaController</a></code>'s
|
|
<a href="#media-controller-position">media controller position</a> must increase monotonically
|
|
at <a href="#media-controller-playback-rate">media controller playback rate</a> units of time on the
|
|
<code><a href="#mediacontroller">MediaController</a></code>'s timeline per unit time of the clock
|
|
used by its <a href="#slaved-media-elements">slaved media elements</a>.</p>
|
|
|
|
<p>When the zero point on the timeline of a
|
|
<code><a href="#mediacontroller">MediaController</a></code> moves relative to the timelines of the
|
|
<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
|
|
<a href="#media-controller-position">media controller position</a> must be decremented by <var title="">ΔT</var>.</p>
|
|
|
|
<p class="note">In some situations, e.g. when playing back a live
|
|
stream without buffering anything, the <a href="#media-controller-position">media controller
|
|
position</a> would increase motonically as described above at the
|
|
same rate as the <var title="">ΔT</var> described in the
|
|
previous paragraph decreases it, with the end result that for all
|
|
intents and purposes, the <a href="#media-controller-position">media controller position</a>
|
|
would appear to remain constant (probably with the value 0).</p>
|
|
|
|
<hr><p>A <code><a href="#mediacontroller">MediaController</a></code> has a <dfn id="most-recently-reported-readiness-state">most recently reported
|
|
readiness state</dfn>, which is a number from 0 to 4 derived from
|
|
the numbers used for the <a href="#media-element">media element</a> <code title="attr-media-readyState">readyState</code> attribute, and a
|
|
<dfn id="most-recently-reported-playback-state">most recently reported playback state</dfn>, which is either
|
|
<i>playing</i>, <i>waiting</i>, or <i>ended</i>.</p>
|
|
|
|
<p>When a <code><a href="#mediacontroller">MediaController</a></code> is created, its <a href="#most-recently-reported-readiness-state">most
|
|
recently reported readiness state</a> must be set to 0, and its
|
|
<a href="#most-recently-reported-playback-state">most recently reported playback state</a> must be set to
|
|
<i>waiting</i>.</p>
|
|
|
|
<p>When a user agent is required to <dfn id="report-the-controller-state">report the controller
|
|
state</dfn> for a <code><a href="#mediacontroller">MediaController</a></code>, the user agent must
|
|
run the following steps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved media
|
|
elements</a>, let <var title="">new readiness state</var> be
|
|
0.</p>
|
|
|
|
<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
|
|
all of its <a href="#slaved-media-elements">slaved media elements</a>.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
|
|
reported readiness state</a> is not equal to <var title="">new
|
|
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
|
|
a simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
|
|
whose name is the event name corresponding to the value of <var title="">new readiness state</var> given in the table below:</p>
|
|
|
|
|
|
<table><thead><tr><th>Value of <var title="">new readiness state</var>
|
|
</th><th>Event name
|
|
|
|
</th></tr></thead><tbody><tr><td> 0
|
|
</td><td> <code title="event-MediaController-emptied"><a href="#event-mediacontroller-emptied">emptied</a></code>
|
|
|
|
</td></tr><tr><td> 1
|
|
</td><td> <code title="event-MediaController-loadedmetadata"><a href="#event-mediacontroller-loadedmetadata">loadedmetadata</a></code>
|
|
|
|
</td></tr><tr><td> 2
|
|
</td><td> <code title="event-MediaController-loadeddata"><a href="#event-mediacontroller-loadeddata">loadeddata</a></code>
|
|
|
|
</td></tr><tr><td> 3
|
|
</td><td> <code title="event-MediaController-canplay"><a href="#event-mediacontroller-canplay">canplay</a></code>
|
|
|
|
</td></tr><tr><td> 4
|
|
</td><td> <code title="event-MediaController-canplaythrough"><a href="#event-mediacontroller-canplaythrough">canplaythrough</a></code>
|
|
|
|
</td></tr></tbody></table></li>
|
|
|
|
<li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-readiness-state">most recently
|
|
reported readiness state</a> be <var title="">new readiness
|
|
state</var>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Initialize <var title="">new playback state</var> by setting it
|
|
to the state given for the first matching condition from the
|
|
following list:</p>
|
|
|
|
<dl class="switch"><dt>If the <code><a href="#mediacontroller">MediaController</a></code> has no <a href="#slaved-media-elements">slaved
|
|
media elements</a></dt>
|
|
|
|
<dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
|
|
|
|
<dt>If all of the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#slaved-media-elements">slaved
|
|
media elements</a> have <a href="#ended-playback">ended playback</a> and the
|
|
<a href="#media-controller-playback-rate">media controller playback rate</a> is positive or
|
|
zero</dt>
|
|
|
|
<dd>Let <var title="">new playback state</var> be <i>ended</i>.</dd>
|
|
|
|
<dt>If the <code><a href="#mediacontroller">MediaController</a></code> is a <a href="#blocked-media-controller">blocked media
|
|
controller</a></dt>
|
|
|
|
<dd>Let <var title="">new playback state</var> be <i>waiting</i>.</dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>Let <var title="">new playback state</var> be <i>playing</i>.</dd>
|
|
|
|
</dl></li>
|
|
|
|
<li><p>If the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
|
|
reported playback state</a> is not equal to <var title="">new
|
|
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
|
|
simple event</a> at the <code><a href="#mediacontroller">MediaController</a></code> object,
|
|
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>
|
|
otherwise.</p></li>
|
|
|
|
<li><p>Let the <code><a href="#mediacontroller">MediaController</a></code>'s <a href="#most-recently-reported-playback-state">most recently
|
|
reported playback state</a> be <var title="">new playback
|
|
state</var>.</p></li>
|
|
|
|
</ol><hr><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
|
|
supported, as IDL attributes, by all objects implementing the
|
|
<code><a href="#mediacontroller">MediaController</a></code> interface:</p>
|
|
|
|
<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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</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
|
|
<a href="webappapis.html#dom-manipulation-task-source">DOM manipulation task source</a>.</p>
|
|
|
|
</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
|
|
attribute on <a href="#media-element" title="media element">media elements</a> can
|
|
be used to link multiple <a href="#media-element" title="media element">media
|
|
elements</a> together by implicitly creating a
|
|
<code><a href="#mediacontroller">MediaController</a></code>.</p><div class="impl">
|
|
|
|
<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
|
|
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,
|
|
changed, or removed, the user agent must run the following
|
|
steps:</p>
|
|
|
|
<ol><li><p>Let <var title="">m</var> be the <a href="#media-element">media element</a>
|
|
in question.</p></li>
|
|
|
|
<li><p>Let <var title="">m</var> have no <a href="#current-media-controller">current
|
|
media controller</a>, if it currently has one.</p></li>
|
|
|
|
<li><p>If <var title="">m</var>'s <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute is being
|
|
removed, then abort these steps.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>If there is another <a href="#media-element">media element</a> whose
|
|
<code><a href="infrastructure.html#document">Document</a></code> is the same as <var title="">m</var>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code> (even if one or both of these elements are
|
|
not actually <a href="infrastructure.html#in-a-document" title="in a Document"><em>in</em> the
|
|
<code>Document</code></a>), and which also has a <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, and
|
|
whose <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code>
|
|
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
|
|
let <var title="">controller</var> be that <a href="#media-element">media
|
|
element</a>'s <a href="#current-media-controller">current media controller</a>.</p>
|
|
|
|
<p>Otherwise, let <var title="">controller</var> be a newly created
|
|
<code><a href="#mediacontroller">MediaController</a></code>.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Let <var title="">m</var>'s <a href="#current-media-controller">current media
|
|
controller</a> be <var title="">controller</var>.</p></li>
|
|
|
|
<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
|
|
controller</a>.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-media-mediagroup" title="dom-media-mediaGroup"><code>mediaGroup</code></dfn> IDL
|
|
attribute on <a href="#media-element" title="media element">media elements</a> must
|
|
<a href="common-dom-interfaces.html#reflect">reflect</a> the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> content
|
|
attribute.</p>
|
|
|
|
</div><div class="example">
|
|
|
|
<p>Multiple <a href="#media-element" title="media element">media elements</a>
|
|
referencing the same <a href="#media-resource">media resource</a> will share a
|
|
single network request. This can be used to efficiently play two
|
|
(video) tracks from the same <a href="#media-resource">media resource</a> in two
|
|
different places on the screen. Used with the <code title="attr-media-mediagroup"><a href="#attr-media-mediagroup">mediagroup</a></code> attribute, these
|
|
elements can also be kept synchronised.</p>
|
|
|
|
<p>In this example, a sign-languge interpreter track from a movie
|
|
file is overlaid on the primary video track of that same video file
|
|
using two <code><a href="#the-video-element">video</a></code> elements, some CSS, and an implicit
|
|
<code><a href="#mediacontroller">MediaController</a></code>:</p>
|
|
|
|
<pre><article>
|
|
<style scoped>
|
|
div { margin: 1em auto; position: relative; width: 400px; height: 300px; }
|
|
video { position; absolute; bottom: 0; right: 0; }
|
|
video:first-child { width: 100%; height: 100%; }
|
|
video:last-child { width: 30%; }
|
|
</style>
|
|
<div>
|
|
<video src="movie.vid#track=Video&amp;track=English" autoplay controls mediagroup=movie></video>
|
|
<video src="movie.vid#track=sign" autoplay mediagroup=movie></video>
|
|
</div>
|
|
</article></pre>
|
|
|
|
</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
|
|
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
|
|
to <code><a href="#the-track-element">track</a></code> element children of the <a href="#media-element">media
|
|
element</a>, in <a href="infrastructure.html#tree-order">tree order</a>.</li>
|
|
|
|
<li>Any <a href="#text-track" title="text track">text tracks</a> added using
|
|
the <code title="dom-media-addTextTrack"><a href="#dom-media-addtexttrack">addTextTrack()</a></code> method, in
|
|
the order they were added, oldest first.</li>
|
|
|
|
<li>Any <a href="#media-resource-specific-text-track" title="media-resource-specific text
|
|
track">media-resource-specific text tracks</a> (<a href="#text-track" title="text track">text tracks</a> corresponding to data in
|
|
the <a href="#media-resource">media resource</a>), in the order defined by the
|
|
<a href="#media-resource">media resource</a>'s format specification.</li>
|
|
|
|
</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>
|
|
|
|
</dt><dd>
|
|
|
|
<p>This decides how the track is handled by the user agent. The
|
|
kind is represented by a string. The possible strings are:</p>
|
|
|
|
<ul class="brief"><li><dfn id="dom-texttrack-kind-subtitles" title="dom-TextTrack-kind-subtitles"><code>subtitles</code></dfn>
|
|
</li><li><dfn id="dom-texttrack-kind-captions" title="dom-TextTrack-kind-captions"><code>captions</code></dfn>
|
|
</li><li><dfn id="dom-texttrack-kind-descriptions" title="dom-TextTrack-kind-descriptions"><code>descriptions</code></dfn>
|
|
</li><li><dfn id="dom-texttrack-kind-chapters" title="dom-TextTrack-kind-chapters"><code>chapters</code></dfn>
|
|
</li><li><dfn id="dom-texttrack-kind-metadata" title="dom-TextTrack-kind-metadata"><code>metadata</code></dfn>
|
|
</li></ul><p>The <a href="#text-track-kind" title="text track kind">kind of track</a> can
|
|
change dynamically, in the case of a <a href="#text-track">text track</a>
|
|
corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-label" title="text track label">A label</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>This is a human-readable string intended to identify the track
|
|
for the user. In certain cases, the label might be generated
|
|
automatically.</p>
|
|
|
|
<p>The <a href="#text-track-label" title="text track label">label of a track</a> can
|
|
change dynamically, in the case of a <a href="#text-track">text track</a>
|
|
corresponding to a <code><a href="#the-track-element">track</a></code> element or in the case of an
|
|
automatically-generated label whose value depends on variable
|
|
factors such as the user's preferred user interface language.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-language" title="text track language">A language</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>This is a string (a BCP 47 language tag) representing the
|
|
language of the text track's cues. <a href="references.html#refsBCP47">[BCP47]</a></p>
|
|
|
|
<p>The <a href="#text-track-language" title="text track language">language of a text
|
|
track</a> can change dynamically, in the case of a <a href="#text-track">text
|
|
track</a> corresponding to a <code><a href="#the-track-element">track</a></code> element.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-readiness-state" title="text track readiness state">A readiness state</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>One of the following:</p>
|
|
|
|
<dl><dt><dfn id="text-track-not-loaded" title="text track not loaded">Not loaded</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>Indicates that the text track is known to exist (e.g. it has
|
|
been declared with a <code><a href="#the-track-element">track</a></code> element), but its cues
|
|
have not been obtained.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-loading" title="text track loading">Loading</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>Indicates that the text track is loading and there have been
|
|
no fatal errors encountered so far. Further cues might still be
|
|
added to the track.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-loaded" title="text track loaded">Loaded</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>Indicates that the text track has been loaded with no fatal
|
|
errors. No new cues will be added to the track except if the
|
|
<a href="#text-track">text track</a> corresponds to a
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> object.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-failed-to-load" title="text track failed to load">Failed to load</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>Indicates that the text track was enabled, but when the user
|
|
agent attempted to obtain it, this failed in some way
|
|
(e.g. <a href="urls.html#url">URL</a> could not be <a href="urls.html#resolve-a-url" title="resolve a
|
|
url">resolved</a>, network error, unknown text track
|
|
format). Some or all of the cues are likely missing and will not
|
|
be obtained.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>The <a href="#text-track-readiness-state" title="text track readiness state">readiness
|
|
state</a> of a <a href="#text-track">text track</a> changes dynamically as
|
|
the track is obtained.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-mode" title="text track mode">A mode</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>One of the following:</p>
|
|
|
|
<dl><dt><dfn id="text-track-disabled" title="text track disabled">Disabled</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>Indicates that the text track is not active. Other than for
|
|
the purposes of exposing the track in the DOM, the user agent is
|
|
ignoring the text track. No cues are active, no events are
|
|
fired, and the user agent will not attempt to obtain the track's
|
|
cues.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-hidden" title="text track hidden">Hidden</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>Indicates that the text track is active, but that the user
|
|
agent is not actively displaying the cues. If no attempt has yet
|
|
been made to obtain the track's cues, the user agent will
|
|
perform such an attempt momentarily. The user agent is
|
|
maintaining a list of which cues are active, and events are
|
|
being fired accordingly.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-showing" title="text track showing">Showing</dfn>
|
|
<dt><dfn id="text-track-showing-by-default" title="text track showing by default">Showing by default</dfn>
|
|
|
|
</dt></dt><dd>
|
|
|
|
<p>Indicates that the text track is active. If no attempt has
|
|
yet been made to obtain the track's cues, the user agent will
|
|
perform such an attempt momentarily. The user agent is
|
|
maintaining a list of which cues are active, and events are
|
|
being fired accordingly. In addition, for text tracks whose
|
|
<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
|
|
are being displayed over the video as appropriate; for text
|
|
tracks whose <a href="#text-track-kind" title="text track kind">kind</a> is <code title="dom-mediatrack-kind-descriptions">descriptions</code>,
|
|
the user agent is making the cues available to the user in a
|
|
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
|
|
agent is making available to the user a mechanism by which the
|
|
user can navigate to any point in the <a href="#media-resource">media
|
|
resource</a> by selecting a cue.</p>
|
|
|
|
<p>The <a href="#text-track-showing-by-default" title="text track showing by default">showing by
|
|
default</a> state is used in conjunction with the <code title="attr-track-default"><a href="#attr-track-default">default</a></code> attribute on
|
|
<code><a href="#the-track-element">track</a></code> elements to indicate that the text track was
|
|
enabled due to that attribute. This allows the user agent to
|
|
override the state if a later track is discovered that is more
|
|
appropriate per the user's preferences.</p>
|
|
|
|
</dd>
|
|
|
|
</dl></dd>
|
|
|
|
<dt><dfn id="text-track-list-of-cues" title="text track list of cues">A list of zero or more cues</dfn>
|
|
|
|
</dt><dd>
|
|
|
|
<p>A list of <a href="#text-track-cue" title="text track cue">text track
|
|
cues</a>, along with <dfn id="rules-for-updating-the-text-track-rendering">rules for updating the text track
|
|
rendering</dfn>.
|
|
</p>
|
|
|
|
<p>The <a href="#text-track-list-of-cues" title="text track list of cues">list of cues of a
|
|
text track</a> can change dynamically, either because the
|
|
<a href="#text-track">text track</a> has <a href="#text-track-not-loaded" title="text track not
|
|
loaded">not yet been loaded</a> or is still <a href="#text-track-loading" title="text
|
|
track loading">loading</a>, or because the <a href="#text-track">text
|
|
track</a> corresponds to a <code><a href="#mutabletexttrack">MutableTextTrack</a></code>
|
|
object, whose API allows individual cues can be added or removed
|
|
dynamically.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>Each <a href="#text-track">text track</a> has a corresponding
|
|
<code><a href="#texttrack">TextTrack</a></code> object.</p><p>The <a href="#text-track" title="text track">text tracks</a> of a
|
|
<a href="#media-element">media element</a> are <dfn id="the-text-tracks-are-ready" title="the text tracks are
|
|
ready">ready</dfn> if all the <a href="#text-track" title="text track">text
|
|
tracks</a> whose <a href="#text-track-mode" title="text track mode">mode</a> was
|
|
not in the <a href="#text-track-disabled" title="text track disabled">disabled</a> state
|
|
when the element's <a href="#concept-media-load-algorithm" title="concept-media-load-algorithm">resource selection
|
|
algorithm</a> last started now have a <a href="#text-track-readiness-state">text track readiness
|
|
state</a> of <a href="#text-track-loaded" title="text track loaded">loaded</a> or
|
|
<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
|
|
in a <a href="#text-track">text track</a>, corresponding for instance for
|
|
subtitles and captions to the text that appears at a particular time
|
|
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>
|
|
</dt><dd>
|
|
<p>An arbitrary string.</p>
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-cue-start-time" title="text track cue start time">A start time</dfn>
|
|
</dt><dd>
|
|
<p>A time, in seconds and fractions of a second, at which the cue
|
|
becomes relevant.</p>
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-cue-end-time" title="text track cue end time">An end time</dfn>
|
|
</dt><dd>
|
|
<p>A time, in seconds and fractions of a second, at which the cue
|
|
stops being relevant.</p>
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-cue-pause-on-exit-flag" title="text track cue pause-on-exit flag">A pause-on-exit flag</dfn>
|
|
</dt><dd>
|
|
<p>A boolean indicating whether playback of the <a href="#media-resource">media
|
|
resource</a> is to pause when the cue stops being relevant.</p>
|
|
</dd>
|
|
|
|
<dt><dfn id="text-track-cue-writing-direction" title="text track cue writing direction">A writing direction</dfn>
|
|
</dt><dd>
|
|
<p>A writing direction, either <dfn id="text-track-cue-horizontal-writing-direction" title="text track cue
|
|
horizontal writing direction">horizontal</dfn> (a line extends
|
|
horizontally and is positioned vertically, with consecutive lines
|
|
displayed below each other), <dfn id="text-track-cue-vertical-growing-left-writing-direction" title="text track cue vertical
|
|
growing left writing direction">vertical growing left</dfn> (a
|
|
line extends vertically and is positioned horizontally, with
|
|
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
|
|
growing right writing direction">vertical growing right</dfn> (a
|
|
line extends vertically and is positioned horizontally, with
|
|
consecutive lines displayed to the right of each other).</p>
|
|
|
|
|
|
</dd>
|
|
|
|
|
|
<dt><dfn id="text-track-cue-size" title="text track cue size">A size</dfn>
|
|
</dt><dd>
|
|
<p>A number giving the size of the box within which the text of
|
|
each line of the cue is to be aligned, to be interpreted as a
|
|
percentage of the video, as defined by the <a href="#text-track-cue-writing-direction" title="text
|
|
track cue writing direction">writing direction</a>.</p>
|
|
</dd>
|
|
|
|
|
|
<dt><dfn id="text-track-cue-text" title="text track cue text">The text of the cue</dfn>
|
|
</dt><dd>
|
|
<p>The raw text of the cue, and rules for its interpretation,
|
|
allowing the text to be rendered and converted to a DOM fragment.</p>
|
|
</dd>
|
|
|
|
</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
|
|
<code><a href="#texttrackcue">TextTrackCue</a></code> object, and can be associated with a
|
|
particular <a href="#text-track">text track</a>. Once a <a href="#text-track-cue">text track
|
|
cue</a> is associated with a particular <a href="#text-track">text track</a>,
|
|
the association is permanent.</p><p>In addition, each <a href="#text-track-cue">text track cue</a> has two pieces of
|
|
dynamic information:</p><dl><dt>The <dfn id="text-track-cue-active-flag" title="text track cue active flag">active flag</dfn>
|
|
</dt><dd>
|
|
|
|
<p>This flag must be initially unset. The flag is used to ensure
|
|
events are fired appropriately when the cue becomes active or
|
|
inactive, and to make sure the right cues are rendered.</p>
|
|
|
|
<p>The user agent must synchronously unset this flag whenever the
|
|
<a href="#text-track-cue">text track cue</a> is removed from its <a href="#text-track">text
|
|
track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>; whenever the
|
|
<a href="#text-track">text track</a> itself is removed from its <a href="#media-element">media
|
|
element</a>'s <a href="#list-of-text-tracks">list of text tracks</a> or has its
|
|
<a href="#text-track-mode">text track mode</a> changed to <a href="#text-track-disabled" title="text track
|
|
disabled">disabled</a>; and whenever the <a href="#media-element">media
|
|
element</a>'s <code title="dom-media-readyState"><a href="#dom-media-readystate">readyState</a></code> is changed back to
|
|
<code title="dom-media-HAVE_NOTHING"><a href="#dom-media-have_nothing">HAVE_NOTHING</a></code>. When the
|
|
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
|
|
track showing by default">showing by default</a> prior to the
|
|
relevant incident, the user agent must, after having unset the
|
|
flag for all the affected cues, apply the <a href="#rules-for-updating-the-text-track-rendering">rules for updating
|
|
the text track rendering</a> of those <a href="#text-track" title="text
|
|
track">text tracks</a>.
|
|
</p></dd>
|
|
|
|
<dt>The <dfn id="text-track-cue-display-state" title="text track cue display state">display state</dfn>
|
|
</dt><dd>
|
|
|
|
<p>This is used as part of the rendering model, to keep cues in a
|
|
consistent position. It must initially be empty. Whenever the
|
|
<a href="#text-track-cue-active-flag">text track cue active flag</a> is unset, the user agent
|
|
must empty the <a href="#text-track-cue-display-state">text track cue display state</a>.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>The <a href="#text-track-cue" title="text track cue">text track cues</a> of a
|
|
<a href="#media-element">media element</a>'s <a href="#text-track" title="text track">text
|
|
tracks</a> are ordered relative to each other in the <dfn id="text-track-cue-order">text
|
|
track cue order</dfn>, which is determined as follows: first group
|
|
the <a href="#text-track-cue" title="text track cue">cues</a> by their <a href="#text-track">text
|
|
track</a>, with the groups being sorted in the same order as
|
|
their <a href="#text-track" title="text track">text tracks</a> appear in the
|
|
<a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>;
|
|
then, within each group, <a href="#text-track-cue" title="text track cue">cues</a>
|
|
must be sorted by their <a href="#text-track-cue-start-time" title="text track cue start
|
|
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
|
|
track cue start time">start time</a> must be sorted by their
|
|
<a href="#text-track-cue-end-time" title="text track cue end time">end time</a>, earliest
|
|
first; and finally, any <a href="#text-track-cue" title="text track cue">cues</a>
|
|
with identical <a href="#text-track-cue-end-time" title="text track cue end time">end
|
|
times</a> must be sorted in the order they were created (so
|
|
e.g. for cues from a <span>WebVTT</span> file, that would be the
|
|
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
|
|
track</a> that corresponds to data found in the <a href="#media-resource">media
|
|
resource</a>.</p><div class="impl">
|
|
|
|
<p>Rules for processing and rendering such data are defined by the
|
|
relevant specifications, e.g. the specification of the video format
|
|
if the <a href="#media-resource">media resource</a> is a video.</p>
|
|
|
|
<p>When a <a href="#media-resource">media resource</a> contains data that the user
|
|
agent recognises and supports as being equivalent to a <a href="#text-track">text
|
|
track</a>, the user agent <a href="#found-a-media-resource-specific-timed-track">runs</a> the
|
|
<dfn id="steps-to-expose-a-media-resource-specific-text-track">steps to expose a media-resource-specific text track</dfn>
|
|
with the relevant data, as follows:</p>
|
|
|
|
<ol><li><p>Associate the relevant data with a new <a href="#text-track">text
|
|
track</a> and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
|
|
object. The <a href="#text-track">text track</a> is a
|
|
<a href="#media-resource-specific-text-track">media-resource-specific text track</a>.</p></li>
|
|
|
|
<li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-kind" title="text track
|
|
kind">kind</a>, <a href="#text-track-label" title="text track label">label</a>,
|
|
and <a href="#text-track-language" title="text track language">language</a> based on the
|
|
semantics of the relevant data, as defined by the relevant
|
|
specification.</p></li>
|
|
|
|
<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
|
|
parsed so far, folllowing the <span>guidelines for exposing
|
|
cues</span>, and begin updating it dynamically as
|
|
necessary.</p></li>
|
|
|
|
<li>
|
|
|
|
<p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-readiness-state" title="text track
|
|
readiness state">readiness state</a> to the value that most
|
|
correctly describes the current state, and begin updating it
|
|
dynamically as necessary.</p>
|
|
|
|
<p class="example">For example, if the relevant data in the
|
|
<a href="#media-resource">media resource</a> has been fully parsed and completely
|
|
describes the cues, then the <a href="#text-track">text track</a> would be
|
|
<a href="#text-track-loaded" title="text track loaded">loaded</a>. On the other hand,
|
|
if the data for the cues is interleaved with the <a href="#media-data">media
|
|
data</a>, and the <a href="#media-resource">media resource</a> as a whole is
|
|
still being downloaded, then the <a href="#text-track-loading" title="text track
|
|
loading">loading</a> state might be more accurate.</p>
|
|
|
|
</li>
|
|
|
|
<li><p>Set the new <a href="#text-track">text track</a>'s <a href="#text-track-mode" title="text
|
|
track mode">mode</a> to the mode consistent with the user's
|
|
preferences and the requirements of the relevant specification for
|
|
the data.</p></li>
|
|
|
|
<li><p>Leave the <a href="#text-track-list-of-cues">text track list of cues</a> empty, and
|
|
associate with it the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text track
|
|
rendering</a> appropriate for the format in question.</p>
|
|
|
|
</li><li><p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
|
|
element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p></li>
|
|
|
|
</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
|
|
element's media-resource-specific text tracks</dfn>, the user
|
|
agent must remove from the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list
|
|
of text tracks</a> all the <a href="#media-resource-specific-text-track" title="media-resource-specific
|
|
text track">media-resource-specific text tracks</a>.</p>
|
|
|
|
</div><div class="impl">
|
|
|
|
<h6 id="sourcing-out-of-band-text-tracks"><span class="secno">4.8.10.12.3 </span>Sourcing out-of-band text tracks</h6>
|
|
|
|
<p>When a <code><a href="#the-track-element">track</a></code> element is created, it must be
|
|
associated with a new <a href="#text-track">text track</a> (with its value set
|
|
as defined below) and its corresponding new <code><a href="#texttrack">TextTrack</a></code>
|
|
object.</p>
|
|
|
|
<p>The <a href="#text-track-kind">text track kind</a> is determined from the state of
|
|
the element's <code title="attr-track-kind"><a href="#attr-track-kind">kind</a></code> attribute
|
|
according to the following table; for a state given in a cell of the
|
|
first column, the <a href="#text-track-kind" title="text track kind">kind</a> is the
|
|
string given in the second column:</p>
|
|
|
|
<table><thead><tr><th>State
|
|
</th><th>String
|
|
</th></tr></thead><tbody><tr><td><a href="#attr-track-kind-subtitles" title="attr-track-kind-subtitles">Subtitles</a>
|
|
</td><td><code title="dom-timedtrack-kind-subtitles">subtitles</code>
|
|
</td></tr><tr><td><a href="#attr-track-kind-captions" title="attr-track-kind-captions">Captions</a>
|
|
</td><td><code title="dom-timedtrack-kind-captions">captions</code>
|
|
</td></tr><tr><td><a href="#attr-track-kind-descriptions" title="attr-track-kind-descriptions">Descriptions</a>
|
|
</td><td><code title="dom-timedtrack-kind-descriptions">descriptions</code>
|
|
</td></tr><tr><td><a href="#attr-track-kind-chapters" title="attr-track-kind-chapters">Chapters</a>
|
|
</td><td><code title="dom-timedtrack-kind-chapters">chapters</code>
|
|
</td></tr><tr><td><a href="#attr-track-kind-metadata" title="attr-track-kind-metadata">Metadata</a>
|
|
</td><td><code title="dom-timedtrack-kind-metadata">metadata</code>
|
|
</td></tr></tbody></table><p>The <a href="#text-track-label">text track label</a> is the element's <a href="#track-label">track
|
|
label</a>.</p>
|
|
|
|
<p>The <a href="#text-track-language">text track language</a> is the element's
|
|
<a href="#track-language">track language</a>, if any, or the empty string
|
|
otherwise.</p>
|
|
|
|
<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,
|
|
changed, or removed, the <a href="#text-track">text track</a> must update
|
|
accordingly, as per the definitions above.</p>
|
|
|
|
<p class="note">Changes to the <a href="#track-url">track URL</a> are handled in
|
|
the algorithm below.</p>
|
|
|
|
<p>The <a href="#text-track-list-of-cues">text track list of cues</a> is initially empty. It
|
|
is dynamically modified when the referenced file is parsed.
|
|
Associated with the list are the <a href="#rules-for-updating-the-text-track-rendering">rules for updating the text
|
|
track rendering</a> appropriate for the format in question; for
|
|
<span>WebVTT</span>, this is the <a href="rendering.html#rules-for-updating-the-display-of-webvtt-text-tracks">rules for updating the
|
|
display of WebVTT text tracks</a>.</p>
|
|
|
|
<p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
|
|
the new parent is a <a href="#media-element">media element</a>, then the user agent
|
|
must add the <code><a href="#the-track-element">track</a></code> element's corresponding <a href="#text-track">text
|
|
track</a> to the <a href="#media-element">media element</a>'s <a href="#list-of-text-tracks">list of text
|
|
tracks</a>.</p>
|
|
|
|
<p>When a <code><a href="#the-track-element">track</a></code> element's parent element changes and
|
|
the old parent was a <a href="#media-element">media element</a>, then the user agent
|
|
must remove the <code><a href="#the-track-element">track</a></code> element's corresponding
|
|
<a href="#text-track">text track</a> from the <a href="#media-element">media element</a>'s
|
|
<a href="#list-of-text-tracks">list of text tracks</a>.</p>
|
|
|
|
<p>When a <a href="#text-track">text track</a> corresponding to a
|
|
<code><a href="#the-track-element">track</a></code> element is added to a <a href="#media-element">media
|
|
element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>, the user agent
|
|
must set the <a href="#text-track-mode">text track mode</a> appropriately, as
|
|
determined by the following conditions:</p>
|
|
|
|
<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
|
|
has indicated an interest in having a track with this <a href="#text-track-kind">text
|
|
track kind</a>, <a href="#text-track-language">text track language</a>, and
|
|
<a href="#text-track-label">text track label</a> enabled, and there is no other
|
|
<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> with a <a href="#text-track-kind">text track
|
|
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
|
|
<a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
|
|
showing">showing</a></dt>
|
|
|
|
<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
|
|
the user has indicated an interest in having text descriptions with
|
|
this <a href="#text-track-language">text track language</a> and <a href="#text-track-label">text track
|
|
label</a> enabled, and there is no other <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> 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
|
|
<a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
|
|
showing">showing</a></dt>
|
|
|
|
<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
|
|
<a href="#text-track-language">text track language</a> is one that the user agent has
|
|
reason to believe is appropriate for the user, and there is no
|
|
other <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> with a <a href="#text-track-kind">text track
|
|
kind</a> of <code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code> whose
|
|
<a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing" title="text track
|
|
showing">showing</a></dt>
|
|
|
|
<dd>
|
|
<p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing" title="text
|
|
track showing">showing</a>.</p>
|
|
|
|
<p>If there is a <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> whose
|
|
<a href="#text-track-mode">text track mode</a> is <a href="#text-track-showing-by-default" title="text track showing
|
|
by default">showing by default</a>, the user agent must
|
|
furthermore change <em>that</em> <a href="#text-track">text track</a>'s
|
|
<a href="#text-track-mode">text track mode</a> to <a href="#text-track-hidden" title="text track
|
|
hidden">hidden</a>.</p>
|
|
</dd>
|
|
|
|
<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
|
|
there is no other <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> whose
|
|
<a href="#text-track-mode">text track mode</a> is <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></dt>
|
|
|
|
<dd>
|
|
<p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-showing-by-default" title="text
|
|
track showing by default">showing by default</a>.</p>
|
|
</dd>
|
|
|
|
<dt>Otherwise</dt>
|
|
|
|
<dd>
|
|
<p>Let the <a href="#text-track-mode">text track mode</a> be <a href="#text-track-disabled" title="text
|
|
track disabled">disabled</a>.</p>
|
|
</dd>
|
|
|
|
</dl><p>When a <a href="#text-track">text track</a> corresponding to a
|
|
<code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
|
|
mode</a> set to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
|
|
<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>,
|
|
and when a <a href="#text-track">text track</a> corresponding to a
|
|
<code><a href="#the-track-element">track</a></code> element is created with <a href="#text-track-mode">text track
|
|
mode</a> set to <a href="#text-track-disabled" title="text track
|
|
disabled">disabled</a> and subsequently changes its <a href="#text-track-mode">text
|
|
track mode</a> to <a href="#text-track-hidden" title="text track hidden">hidden</a>,
|
|
<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
|
|
the first time, the user agent must immediately and synchronously
|
|
run the following algorithm. This algorithm interacts closely with
|
|
the <a href="webappapis.html#event-loop">event loop</a> mechanism; in particular, it has a
|
|
<a href="webappapis.html#synchronous-section">synchronous section</a> (which is triggered as part of the
|
|
<a href="webappapis.html#event-loop">event loop</a> algorithm). The step in that section is
|
|
marked with ⌛.</p>
|
|
|
|
<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>
|
|
|
|
<li><p>Let <var title="">URL</var> be the <a href="#track-url">track URL</a> of
|
|
the <code><a href="#the-track-element">track</a></code> element.</p></li>
|
|
|
|
<li><p>Asynchronously run the remaining steps, while continuing
|
|
with whatever task was responsible for creating the <a href="#text-track">text
|
|
track</a> or changing the <a href="#text-track-mode">text track
|
|
mode</a>.</p></li>
|
|
|
|
<li>
|
|
|
|
<p><i>Download</i>: If <var title="">URL</var> is not the empty
|
|
string, and its <a href="origin-0.html#origin">origin</a> is the same as the <a href="#media-element">media
|
|
element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, then
|
|
<a href="fetching-resources.html#fetch">fetch</a> <var title="">URL</var>, from the <a href="#media-element">media
|
|
element</a>'s <code><a href="infrastructure.html#document">Document</a></code>'s <a href="origin-0.html#origin">origin</a>, with
|
|
the <i>force same-origin flag</i> set.</p>
|
|
<p>The <a href="webappapis.html#concept-task" title="concept-task">tasks</a> <a href="webappapis.html#queue-a-task" title="queue
|
|
a task">queued</a> by the <a href="fetching-resources.html#fetch" title="fetch">fetching
|
|
algorithm</a> on the <a href="webappapis.html#networking-task-source">networking task source</a> to
|
|
process the data as it is being fetched must examine the
|
|
resource's <a href="fetching-resources.html#content-type" title="Content-Type">Content Type
|
|
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
|
|
available, or if the type is not recognised as a text track
|
|
format, then the resource's format must be assumed to be
|
|
unsupported (this causes the load to fail, as described below). If
|
|
a type is obtained, and represents a supported text track format,
|
|
then the resource's data must be passed to the appropriate parser
|
|
as it is received, with the <a href="#text-track-list-of-cues">text
|
|
track list of cues</a> being used for that parser's output.</p>
|
|
|
|
<p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> fails for
|
|
any reason (network error, the server returns an error code, a
|
|
cross-origin check fails, etc), or if <var title="">URL</var> is
|
|
the empty string or has the wrong <a href="origin-0.html#origin">origin</a> as
|
|
determined by the condition at the start of this step, or if the
|
|
fetched resource is not in a supported format, then <a href="webappapis.html#queue-a-task">queue a
|
|
task</a> to first change the <a href="#text-track-readiness-state">text track readiness
|
|
state</a> to <a href="#text-track-failed-to-load" title="text track failed to load">failed to
|
|
load</a> and then <a href="webappapis.html#fire-a-simple-event">fire a simple event</a> named <code title="event-error">error</code> at the <code><a href="#the-track-element">track</a></code>
|
|
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
|
|
task">queued</a>, move on to the step below labeled
|
|
<i>monitoring</i>.</p>
|
|
|
|
<p>If the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> does not
|
|
fail, then, when it completes, <a href="webappapis.html#queue-a-task">queue a task</a> to first
|
|
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
|
|
simple event</a> named <code title="event-load">load</code> at
|
|
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
|
|
task">queued</a>, move on to the step below labeled
|
|
<i>monitoring</i>.</p>
|
|
|
|
<p>If, while the <a href="fetching-resources.html#fetch" title="fetch">fetching algorithm</a> is
|
|
active, either:</p>
|
|
|
|
<ul><li>the <a href="#track-url">track URL</a> changes so that it is no longer
|
|
equal to <var title="">URL</var>, while the <a href="#text-track-mode">text track
|
|
mode</a> is set to <a href="#text-track-hidden" title="text track
|
|
hidden">hidden</a>, <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>; or</li>
|
|
|
|
<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
|
|
track showing">showing</a>, or <a href="#text-track-showing-by-default" title="text track
|
|
showing by default">showing by default</a>, while the
|
|
<a href="#track-url">track URL</a> is not equal to <var title="">URL</var></li>
|
|
|
|
</ul><p>...then the user agent must run the following steps:</p>
|
|
|
|
<ol><li><p>Abort the <a href="fetching-resources.html#fetch" title="fetch">fetching
|
|
algorithm</a>.</p></li>
|
|
|
|
<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> named <code title="event-abort">abort</code> at
|
|
the <code><a href="#the-track-element">track</a></code> element.</p></li>
|
|
|
|
<li><p>Let <var title="">URL</var> be the new <a href="#track-url">track
|
|
URL</a>.</p></li>
|
|
|
|
<li><p>Jump back to the top of the step labeled
|
|
<i>download</i>.</p></li>
|
|
|
|
</ol><p>Until one of the above circumstances occurs, the user agent
|
|
must remain on this step.</p>
|
|
|
|
</li>
|
|
|
|
<li><p><i>Monitoring</i>: Wait until the <a href="#track-url">track URL</a> is
|
|
no longer equal to <var title="">URL</var>, at the same time as the
|
|
<a href="#text-track-mode">text track mode</a> is set to <a href="#text-track-hidden" title="text track
|
|
hidden">hidden</a>, <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>.</p></li>
|
|
|
|
<li><p>Wait until the <a href="#text-track-readiness-state">text track readiness state</a> is
|
|
no longer set to <a href="#text-track-loading" title="text track
|
|
loading">loading</a>.</p></li>
|
|
|
|
<li><p><a href="webappapis.html#await-a-stable-state">Await a stable state</a>. The <a href="webappapis.html#synchronous-section">synchronous
|
|
section</a> consists of the following step. (The step in the
|
|
<a href="webappapis.html#synchronous-section">synchronous section</a> is marked with ⌛.)</p></li>
|
|
|
|
<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>
|
|
|
|
|
|
<li><p>End the <a href="webappapis.html#synchronous-section">synchronous section</a>, continuing the
|
|
remaining steps asynchronously.</p></li>
|
|
|
|
<li><p>Jump to the step labeled <i>download</i>.</p></li>
|
|
|
|
</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>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
<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>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
<dt><var title="">track</var> . <code title="dom-track-track"><a href="#dom-track-track">track</a></code></dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-texttracks" title="dom-media-textTracks"><code>textTracks</code></dfn>
|
|
attribute of <a href="#media-element" title="media element">media elements</a> must
|
|
return an <span title="array host objects">array host object</span>
|
|
for objects of type <code><a href="#texttrack">TextTrack</a></code> that is <i>fixed
|
|
length</i> and <i>read only</i>. The same object must be returned
|
|
each time the attribute is accessed. <a href="references.html#refsWEBIDL">[WEBIDL]</a></p>
|
|
|
|
<p>The array must contain the <code><a href="#texttrack">TextTrack</a></code> objects of the
|
|
<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>, in the same
|
|
order as in the <a href="#list-of-text-tracks">list of text tracks</a>.</p>
|
|
|
|
</div><hr><pre class="idl">interface <dfn id="texttrack">TextTrack</dfn> {
|
|
readonly attribute DOMString <a href="#dom-texttrack-kind" title="dom-TextTrack-kind">kind</a>;
|
|
readonly attribute DOMString <a href="#dom-texttrack-label" title="dom-TextTrack-label">label</a>;
|
|
readonly attribute DOMString <a href="#dom-texttrack-language" title="dom-TextTrack-language">language</a>;
|
|
|
|
const unsigned short <a href="#dom-texttrack-none" title="dom-TextTrack-NONE">NONE</a> = 0;
|
|
const unsigned short <a href="#dom-texttrack-loading" title="dom-TextTrack-LOADING">LOADING</a> = 1;
|
|
const unsigned short <a href="#dom-texttrack-loaded" title="dom-TextTrack-LOADED">LOADED</a> = 2;
|
|
const unsigned short <a href="#dom-texttrack-error" title="dom-TextTrack-ERROR">ERROR</a> = 3;
|
|
readonly attribute unsigned short <a href="#dom-texttrack-readystate" title="dom-TextTrack-readyState">readyState</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-onload" title="handler-TextTrack-onload">onload</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-onerror" title="handler-TextTrack-onerror">onerror</a>;
|
|
|
|
const unsigned short <a href="#dom-texttrack-off" title="dom-TextTrack-OFF">OFF</a> = 0;
|
|
const unsigned short <a href="#dom-texttrack-hidden" title="dom-TextTrack-HIDDEN">HIDDEN</a> = 1;
|
|
const unsigned short <a href="#dom-texttrack-showing" title="dom-TextTrack-SHOWING">SHOWING</a> = 2;
|
|
attribute unsigned short <a href="#dom-texttrack-mode" title="dom-TextTrack-mode">mode</a>;
|
|
|
|
readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a> <a href="#dom-texttrack-cues" title="dom-TextTrack-cues">cues</a>;
|
|
readonly attribute <a href="#texttrackcuelist">TextTrackCueList</a> <a href="#dom-texttrack-activecues" title="dom-TextTrack-activeCues">activeCues</a>;
|
|
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrack-oncuechange" title="handler-TextTrack-oncuechange">oncuechange</a>;
|
|
};
|
|
<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>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-kind">text track kind</a> string.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-label"><a href="#dom-texttrack-label">label</a></code></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-label">text track label</a>.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-language"><a href="#dom-texttrack-language">language</a></code></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-language">text track language</a> string.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-readyState"><a href="#dom-texttrack-readystate">readyState</a></code></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-readiness-state">text track readiness state</a>,
|
|
represented by a number from the following list:</p>
|
|
<dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-NONE"><a href="#dom-texttrack-none">NONE</a></code> (0)</dt>
|
|
<dd>
|
|
<p>The <a href="#text-track-not-loaded">text track not loaded</a> state.</p>
|
|
</dd>
|
|
<dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADING"><a href="#dom-texttrack-loading">LOADING</a></code> (1)</dt>
|
|
<dd>
|
|
<p>The <a href="#text-track-loading">text track loading</a> state.</p>
|
|
</dd>
|
|
<dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-LOADED"><a href="#dom-texttrack-loaded">LOADED</a></code> (2)</dt>
|
|
<dd>
|
|
<p>The <a href="#text-track-loaded">text track loaded</a> state.</p>
|
|
</dd>
|
|
<dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-ERROR"><a href="#dom-texttrack-error">ERROR</a></code> (3)</dt>
|
|
<dd>
|
|
<p>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</p>
|
|
</dd>
|
|
</dl></dd>
|
|
|
|
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-mode">text track mode</a>, represented by a
|
|
number from the following list:</p>
|
|
<dl><dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-OFF"><a href="#dom-texttrack-off">OFF</a></code> (0)</dt>
|
|
<dd>
|
|
<p>The <a href="#text-track-disabled">text track disabled</a> mode.</p>
|
|
</dd>
|
|
<dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-HIDDEN"><a href="#dom-texttrack-hidden">HIDDEN</a></code> (1)</dt>
|
|
<dd>
|
|
<p>The <a href="#text-track-hidden">text track hidden</a> mode.</p>
|
|
</dd>
|
|
<dt><code><a href="#texttrack">TextTrack</a></code> . <code title="dom-TextTrack-SHOWING"><a href="#dom-texttrack-showing">SHOWING</a></code> (2)</dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
</dl><p>Can be set, to change the mode.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-cues"><a href="#dom-texttrack-cues">cues</a></code></dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
<dt><var title="">textTrack</var> . <code title="dom-TextTrack-activeCues"><a href="#dom-texttrack-activecues">activeCues</a></code></dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-texttrack-kind" title="dom-TextTrack-kind"><code>kind</code></dfn>
|
|
attribute must return the <a href="#text-track-kind">text track kind</a> of the
|
|
<a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
|
|
represents.</p>
|
|
|
|
<p>The <dfn id="dom-texttrack-label" title="dom-TextTrack-label"><code>label</code></dfn>
|
|
attribute must return the <a href="#text-track-label">text track label</a> of the
|
|
<a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
|
|
represents.</p>
|
|
|
|
<p>The <dfn id="dom-texttrack-language" title="dom-TextTrack-language"><code>language</code></dfn>
|
|
attribute must return the <a href="#text-track-language">text track language</a> of the
|
|
<a href="#text-track">text track</a> that the <code><a href="#texttrack">TextTrack</a></code> object
|
|
represents.</p>
|
|
|
|
<p>The <dfn id="dom-texttrack-readystate" title="dom-TextTrack-readyState"><code>readyState</code></dfn>
|
|
attribute must return the numeric value corresponding to the
|
|
<a href="#text-track-readiness-state">text track readiness state</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents, as
|
|
defined by the following list:</p>
|
|
|
|
<dl><dt><dfn id="dom-texttrack-none" title="dom-TextTrack-NONE"><code>NONE</code></dfn> (numeric value 0)</dt>
|
|
<dd>The <a href="#text-track-not-loaded">text track not loaded</a> state.</dd>
|
|
<dt><dfn id="dom-texttrack-loading" title="dom-TextTrack-LOADING"><code>LOADING</code></dfn> (numeric value 1)</dt>
|
|
<dd>The <a href="#text-track-loading">text track loading</a> state.</dd>
|
|
<dt><dfn id="dom-texttrack-loaded" title="dom-TextTrack-LOADED"><code>LOADED</code></dfn> (numeric value 2)</dt>
|
|
<dd>The <a href="#text-track-loaded">text track loaded</a> state.</dd>
|
|
<dt><dfn id="dom-texttrack-error" title="dom-TextTrack-ERROR"><code>ERROR</code></dfn> (numeric value 3)</dt>
|
|
<dd>The <a href="#text-track-failed-to-load">text track failed to load</a> state.</dd>
|
|
</dl><p>The <dfn id="dom-texttrack-mode" title="dom-TextTrack-mode"><code>mode</code></dfn>
|
|
attribute, on getting, must return the numeric value corresponding
|
|
to the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text track</a>
|
|
that the <code><a href="#texttrack">TextTrack</a></code> object represents, as defined by
|
|
the following list:</p>
|
|
|
|
<dl><dt><dfn id="dom-texttrack-off" title="dom-TextTrack-OFF"><code>OFF</code></dfn> (numeric value 0)</dt>
|
|
<dd>The <a href="#text-track-disabled">text track disabled</a> mode.</dd>
|
|
<dt><dfn id="dom-texttrack-hidden" title="dom-TextTrack-HIDDEN"><code>HIDDEN</code></dfn> (numeric value 1)</dt>
|
|
<dd>The <a href="#text-track-hidden">text track hidden</a> mode.</dd>
|
|
<dt><dfn id="dom-texttrack-showing" title="dom-TextTrack-SHOWING"><code>SHOWING</code></dfn> (numeric value 2)</dt>
|
|
<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>
|
|
</dl><p>On setting, if the new value is not either 0, 1, or 2, the user
|
|
agent must throw an <code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code>
|
|
exception. Otherwise, if the new value isn't equal to what the
|
|
attribute would currently return, the new value must be processed as
|
|
follows:</p>
|
|
|
|
<dl class="switch"><dt>If the new value is 0</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
|
|
the <a href="#text-track-disabled">text track disabled</a> mode.</p>
|
|
|
|
</dd>
|
|
|
|
<dt>If the new value is 1</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
|
|
the <a href="#text-track-hidden">text track hidden</a> mode.</p>
|
|
|
|
</dd>
|
|
|
|
<dt>If the new value is 2</dt>
|
|
|
|
<dd>
|
|
|
|
<p>Set the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents to
|
|
the <a href="#text-track-showing">text track showing</a> mode.</p>
|
|
|
|
<p class="note">If the mode had been <a href="#text-track-showing-by-default" title="text track
|
|
showing by default">showing by default</a>, this will change it
|
|
to <a href="#text-track-showing" title="text track showing">showing</a>, even though
|
|
the value of <code title="dom-TextTrack-mode"><a href="#dom-texttrack-mode">mode</a></code> would
|
|
appear not to change.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
|
|
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
|
|
return a <a href="infrastructure.html#live">live</a> <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
|
|
that represents the subset of the <a href="#text-track-list-of-cues">text track list of
|
|
cues</a> of the <a href="#text-track">text track</a> that the
|
|
<code><a href="#texttrack">TextTrack</a></code> object represents whose <a href="#text-track-cue-start-time" title="text
|
|
track cue start time">start times</a> occur before the
|
|
<a href="#earliest-possible-position-when-the-script-started">earliest possible position when the script started</a>, in
|
|
<a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
|
|
null. When an object is returned, the same object must be returned
|
|
each time.</p>
|
|
|
|
<p>The <dfn id="earliest-possible-position-when-the-script-started">earliest possible position when the script started</dfn>
|
|
is whatever the <a href="#earliest-possible-position">earliest possible position</a> was the last
|
|
time the <a href="webappapis.html#event-loop">event loop</a> reached step 1.</p>
|
|
|
|
<p>If the <a href="#text-track-mode">text track mode</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents is
|
|
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>
|
|
attribute must return a <a href="infrastructure.html#live">live</a>
|
|
<code><a href="#texttrackcuelist">TextTrackCueList</a></code> object that represents the subset of
|
|
the <a href="#text-track-list-of-cues">text track list of cues</a> of the <a href="#text-track">text
|
|
track</a> that the <code><a href="#texttrack">TextTrack</a></code> object represents
|
|
whose <a href="#active-flag-was-set-when-the-script-started">active flag was set when the script started</a>, in
|
|
<a href="#text-track-cue-order">text track cue order</a>. Otherwise, it must return
|
|
null. When an object is returned, the same object must be returned
|
|
each time.</p>
|
|
|
|
<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
|
|
the script started</dfn> if its <a href="#text-track-cue-active-flag">text track cue active
|
|
flag</a> was set the last time the <a href="webappapis.html#event-loop">event loop</a>
|
|
reached step 1.</p>
|
|
|
|
</div><hr><pre class="idl">interface <dfn id="mutabletexttrack">MutableTextTrack</dfn> : <a href="#texttrack">TextTrack</a> {
|
|
void <a href="#dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue">addCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
|
|
void <a href="#dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue">removeCue</a>(in <a href="#texttrackcue">TextTrackCue</a> cue);
|
|
};</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>
|
|
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
<dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-addCue"><a href="#dom-mutabletexttrack-addcue">addCue</a></code>( <var title="">cue</var> )</dt>
|
|
<dd>
|
|
<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>
|
|
<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>
|
|
</dd>
|
|
|
|
<dt><var title="">mutableTextTrack</var> . <code title="dom-MutableTextTrack-removeCue"><a href="#dom-mutabletexttrack-removecue">removeCue</a></code>( <var title="">cue</var> )</dt>
|
|
<dd>
|
|
<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>
|
|
<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>
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<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
|
|
element">media elements</a>, when invoked, must run the following
|
|
steps:</p>
|
|
|
|
<ol><li>
|
|
|
|
<p>If <var title="">kind</var> is not one of the following
|
|
strings, then throw a <code><a href="common-dom-interfaces.html#syntax_err">SYNTAX_ERR</a></code> exception and abort
|
|
these steps:</p>
|
|
|
|
<ul class="brief"><li><code title="dom-TextTrack-kind-subtitles"><a href="#dom-texttrack-kind-subtitles">subtitles</a></code>
|
|
</li><li><code title="dom-TextTrack-kind-captions"><a href="#dom-texttrack-kind-captions">captions</a></code>
|
|
</li><li><code title="dom-TextTrack-kind-descriptions"><a href="#dom-texttrack-kind-descriptions">descriptions</a></code>
|
|
</li><li><code title="dom-TextTrack-kind-chapters"><a href="#dom-texttrack-kind-chapters">chapters</a></code>
|
|
</li><li><code title="dom-TextTrack-kind-metadata"><a href="#dom-texttrack-kind-metadata">metadata</a></code>
|
|
</li></ul></li>
|
|
|
|
<li>
|
|
|
|
<p>If the <var title="">label</var> argument was omitted, let <var title="">label</var> be the empty string.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>If the <var title="">language</var> argument was omitted, let
|
|
<var title="">language</var> be the empty string.</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Create a new <a href="#text-track">text track</a>, and set its <a href="#text-track-kind">text
|
|
track kind</a> to <var title="">kind</var>, its <a href="#text-track-label">text
|
|
track label</a> to <var title="">label</var>, its <a href="#text-track-language">text
|
|
track language</a> to <var title="">language</var>, its
|
|
<a href="#text-track-readiness-state">text track readiness state</a> to the <a href="#text-track-loaded">text track
|
|
loaded</a> state, its <a href="#text-track-mode">text track mode</a> to the
|
|
<a href="#text-track-hidden">text track hidden</a> mode, and its <a href="#text-track-list-of-cues">text track
|
|
list of cues</a> to an empty list.
|
|
</p>
|
|
|
|
</li>
|
|
|
|
<li>
|
|
|
|
<p>Add the new <a href="#text-track">text track</a> to the <a href="#media-element">media
|
|
element</a>'s <a href="#list-of-text-tracks">list of text tracks</a>.</p>
|
|
|
|
</li></ol><p>The <dfn id="dom-mutabletexttrack-addcue" title="dom-MutableTextTrack-addCue"><code>addCue(<var title="">cue</var>)</code></dfn> method of
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
|
|
following steps:</p>
|
|
|
|
<ol><li><p>If <var title="">cue</var> is null, then throw an
|
|
<code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>If the given <var title="">cue</var> is already associated
|
|
with a <a href="#text-track">text track</a> other than the method's
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
|
|
then throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception and abort
|
|
these steps.</p></li>
|
|
|
|
<li><p>Associate <var title="">cue</var> with the method's
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>,
|
|
if it is not currently associated with a <a href="#text-track">text
|
|
track</a>.</p></li>
|
|
|
|
<li><p>If the given <var title="">cue</var> is already listed in
|
|
the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
|
|
track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw an
|
|
<code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code> exception.</p></li>
|
|
|
|
<li><p>Add <var title="">cue</var> to the method's
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
|
|
<a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
|
|
|
|
</ol><p>The <dfn id="dom-mutabletexttrack-removecue" title="dom-MutableTextTrack-removeCue"><code>removeCue(<var title="">cue</var>)</code></dfn> method of
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> objects, when invoked, must run the
|
|
following steps:</p>
|
|
|
|
<ol><li><p>If <var title="">cue</var> is null, then throw an
|
|
<code><a href="common-dom-interfaces.html#invalid_access_err">INVALID_ACCESS_ERR</a></code> exception and abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>If the given <var title="">cue</var> is not associated with
|
|
the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
|
|
track</a>, then throw an <code><a href="common-dom-interfaces.html#invalid_state_err">INVALID_STATE_ERR</a></code>
|
|
exception.</p></li>
|
|
|
|
<li><p>If the given <var title="">cue</var> is not currently listed
|
|
in the method's <code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text
|
|
track</a>'s <a href="#text-track-list-of-cues">text track list of cues</a>, then throw a
|
|
<code><a href="common-dom-interfaces.html#not_found_err">NOT_FOUND_ERR</a></code> exception.</p></li>
|
|
|
|
<li><p>Remove <var title="">cue</var> from the method's
|
|
<code><a href="#mutabletexttrack">MutableTextTrack</a></code> object's <a href="#text-track">text track</a>'s
|
|
<a href="#text-track-list-of-cues">text track list of cues</a>.</p></li>
|
|
|
|
</ol></div><div class="example">
|
|
|
|
<p>In this example, an <code><a href="#the-audio-element">audio</a></code> element is used to play a
|
|
specific sound-effect from a sound file containing many sound
|
|
effects. A cue is used to pause the audio, so that it ends exactly
|
|
at the end of the clip, even if the browser is busy running some
|
|
script. If the page had relied on script to pause the audio, then
|
|
the start of the next clip might be heard if the browser was not
|
|
able to run the script at the exact time specified.</p>
|
|
|
|
<pre>var sfx = new Audio('sfx.wav');
|
|
var sounds = a.addTextTrack('metadata');
|
|
|
|
// add sounds we care about
|
|
sounds.addCue(new TextTrackCue('dog bark', 12.783, 13.612, '', '', '', true));
|
|
sounds.addCue(new TextTrackCue('kitten mew', 13.612, 15.091, '', '', '', true));
|
|
|
|
function playSound(id) {
|
|
sfx.currentTime = sounds.getCueById(id).startTime;
|
|
sfx.play();
|
|
}
|
|
|
|
sfx.oncanplaythrough = function () {
|
|
playSound('dog bark');
|
|
}
|
|
window.onbeforeunload = function () {
|
|
playSound('kitten mew');
|
|
return 'Are you sure you want to leave this awesome page?';
|
|
}</pre>
|
|
|
|
</div><hr><pre class="idl">interface <dfn id="texttrackcuelist">TextTrackCueList</dfn> {
|
|
readonly attribute unsigned long <a href="#dom-texttrackcuelist-length" title="dom-TextTrackCueList-length">length</a>;
|
|
getter <a href="#texttrackcue">TextTrackCue</a> (in unsigned long index);
|
|
<a href="#texttrackcue">TextTrackCue</a> <a href="#dom-texttrackcuelist-getcuebyid" title="dom-TextTrackCueList-getCueById">getCueById</a>(in DOMString id);
|
|
};</pre><dl class="domintro"><dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-length"><a href="#dom-texttrackcuelist-length">length</a></code></dt>
|
|
<dd>
|
|
<p>Returns the number of <a href="#text-track-cue" title="text track cue">cues</a> in the list.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">cuelist</var>[<var title="">index</var>]</dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
<dt><var title="">cuelist</var> . <code title="dom-TextTrackCueList-getCueById"><a href="#dom-texttrackcuelist-getcuebyid">getCueById</a></code>( <var title="">id</var> )</dt>
|
|
<dd>
|
|
<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>
|
|
<p>Returns null if none of the cues have the given identifier or if the argument is the empty string.</p>
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>A <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object represents a dynamically
|
|
updating list of <a href="#text-track-cue" title="text track cue">text track
|
|
cues</a> in a given order.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcuelist-length" title="dom-TextTrackCueList-length"><code>length</code></dfn>
|
|
attribute must return the number of <a href="#text-track-cue" title="text track
|
|
cue">cues</a> in the list represented by the
|
|
<code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
|
|
|
|
<p>The <span>supported property indicies</span> of a
|
|
<code><a href="#texttrackcuelist">TextTrackCueList</a></code> object at any instant are the numbers
|
|
from zero to the number of <a href="#text-track-cue" title="text track cue">cues</a>
|
|
in the list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object
|
|
minus one, if any. If there are no <a href="#text-track-cue" title="text track
|
|
cue">cues</a> in the list, there are no <span>supported property
|
|
indicies</span>.</p>
|
|
|
|
<p>To <span>determine the value of an indexed property</span> for a
|
|
given index <var title="">index</var>, the user agent must return
|
|
the <var title="">index</var>th <a href="#text-track-cue">text track cue</a> in the
|
|
list represented by the <code><a href="#texttrackcuelist">TextTrackCueList</a></code> object.</p>
|
|
|
|
<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
|
|
other than the empty string, must return the first <a href="#text-track-cue">text track
|
|
cue</a> in the list represented by the
|
|
<code><a href="#texttrackcuelist">TextTrackCueList</a></code> object whose <a href="#text-track-cue-identifier">text track cue
|
|
identifier</a> is <var title="">id</var>, if any, or null
|
|
otherwise. If the argument is the empty string, then the method must
|
|
return null.</p>
|
|
|
|
</div><hr><pre class="idl">
|
|
interface <dfn id="texttrackcue">TextTrackCue</dfn> {
|
|
readonly attribute <a href="#texttrack">TextTrack</a> <a href="#dom-texttrackcue-track" title="dom-TextTrackCue-track">track</a>;
|
|
readonly attribute DOMString <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a>;
|
|
|
|
readonly attribute double <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a>;
|
|
readonly attribute double <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a>;
|
|
readonly attribute boolean <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a>;
|
|
|
|
|
|
DOMString <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>();
|
|
<a href="infrastructure.html#documentfragment">DocumentFragment</a> <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>();
|
|
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrackcue-onenter" title="handler-TextTrackCue-onenter">onenter</a>;
|
|
attribute <a href="webappapis.html#function">Function</a> <a href="#handler-texttrackcue-onexit" title="handler-TextTrackCue-onexit">onexit</a>;
|
|
};
|
|
<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>
|
|
<dd>
|
|
<p>Returns the <code><a href="#texttrack">TextTrack</a></code> object to which this
|
|
<a href="#text-track-cue">text track cue</a> belongs, if any, or null
|
|
otherwise.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">cue</var> . <a href="#dom-texttrackcue-id" title="dom-TextTrackCue-id">id</a></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-cue-identifier">text track cue identifier</a>.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">cue</var> . <a href="#dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime">startTime</a></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-cue-start-time">text track cue start time</a>, in seconds.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">cue</var> . <a href="#dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime">endTime</a></dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-cue-end-time">text track cue end time</a>, in seconds.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">cue</var> . <a href="#dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit">pauseOnExit</a></dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
|
|
<dt><var title="">source</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource">getCueAsSource</a>()</dt>
|
|
<dd>
|
|
<p>Returns the <a href="#text-track-cue-text">text track cue text</a> in raw unparsed form.</p>
|
|
</dd>
|
|
|
|
<dt><var title="">fragment</var> = <var title="">cue</var> . <a href="#dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML">getCueAsHTML</a>()</dt>
|
|
<dd>
|
|
<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>
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
|
|
<p>The <dfn id="dom-texttrackcue-track" title="dom-TextTrackCue-track"><code>track</code></dfn>
|
|
attribute must return the <code><a href="#texttrack">TextTrack</a></code> object of the
|
|
<a href="#text-track">text track</a> with which the <a href="#text-track-cue">text track cue</a>
|
|
that the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is associated,
|
|
if any; or null otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcue-id" title="dom-TextTrackCue-id"><code>id</code></dfn>
|
|
attribute must return the <a href="#text-track-cue-identifier">text track cue identifier</a> of
|
|
the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
|
|
object represents.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcue-starttime" title="dom-TextTrackCue-startTime"><code>startTime</code></dfn>
|
|
attribute must return the <a href="#text-track-cue-start-time">text track cue start time</a> of
|
|
the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
|
|
object represents, in seconds.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcue-endtime" title="dom-TextTrackCue-endTime"><code>endTime</code></dfn>
|
|
attribute must return the <a href="#text-track-cue-end-time">text track cue end time</a> of
|
|
the <a href="#text-track-cue">text track cue</a> that the <code><a href="#texttrackcue">TextTrackCue</a></code>
|
|
object represents, in seconds.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcue-pauseonexit" title="dom-TextTrackCue-pauseOnExit"><code>pauseOnExit</code></dfn>
|
|
attribute must return true if the <a href="#text-track-cue-pause-on-exit-flag">text track cue
|
|
pause-on-exit flag</a> of the <a href="#text-track-cue">text track cue</a> that
|
|
the <code><a href="#texttrackcue">TextTrackCue</a></code> object represents is set; or false
|
|
otherwise.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcue-direction" title="dom-TextTrackCue-direction"><code>direction</code></dfn>
|
|
attribute must return the <a href="#text-track-cue-writing-direction">text track cue writing
|
|
direction</a> of the <a href="#text-track-cue">text track cue</a> that the
|
|
<code><a href="#texttrackcue">TextTrackCue</a></code> object represents.</p>
|
|
|
|
|
|
<p>The <dfn id="dom-texttrackcue-getcueassource" title="dom-TextTrackCue-getCueAsSource"><code>getCueAsSource()</code></dfn>
|
|
method must return the raw <a href="#text-track-cue-text">text track cue text</a>.</p>
|
|
|
|
<p>The <dfn id="dom-texttrackcue-getcueashtml" title="dom-TextTrackCue-getCueAsHTML"><code>getCueAsHTML()</code></dfn>
|
|
method must convert the <a href="#text-track-cue-text">text track cue text</a> to a
|
|
<code><a href="infrastructure.html#documentfragment">DocumentFragment</a></code> for the <a href="#media-element">media element</a>'s
|
|
<code><a href="infrastructure.html#document">Document</a></code>, using the appropriate rules for doing
|
|
so.
|
|
</p>
|
|
|
|
</div><div class="impl">
|
|
|
|
<h6 id="cue-events"><span class="secno">4.8.10.12.5 </span>Event definitions</h6>
|
|
|
|
<p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
|
|
supported, as IDL attributes, by all objects implementing the
|
|
<code><a href="#texttrack">TextTrack</a></code> interface:</p>
|
|
|
|
<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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
</td></tr></tbody></table><p>The following are the <a href="webappapis.html#event-handlers">event handlers</a> that must be
|
|
supported, as IDL attributes, by all objects implementing the
|
|
<code><a href="#texttrackcue">TextTrackCue</a></code> interface:</p>
|
|
|
|
<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>
|
|
</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>
|
|
</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>
|
|
</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>
|
|
attribute is a <a href="common-microsyntaxes.html#boolean-attribute">boolean attribute</a>. If present, it
|
|
indicates that the author has not provided a scripted controller and
|
|
would like the user agent to provide its own set of controls.</p><div class="impl">
|
|
|
|
<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
|
|
<a href="#media-element">media element</a>, then the user agent should <dfn id="expose-a-user-interface-to-the-user">expose a
|
|
user interface to the user</dfn>. This user interface should include
|
|
features to begin playback, pause playback, seek to an arbitrary
|
|
position in the content (if the content supports arbitrary seeking),
|
|
change the volume, change the display of closed captions or embedded
|
|
sign-language tracks, select different audio tracks or turn on audio
|
|
descriptions, and show the media content in manners more suitable to
|
|
the user (e.g. full-screen video or in an independent resizable
|
|
window). Other controls may also be made available.</p>
|
|
|
|
<p>If the <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, then the user agent should expose audio tracks
|
|
from all the <a href="#slaved-media-elements">slaved media elements</a> (although avoiding
|
|
duplicates if the same <a href="#media-resource">media resource</a> is being used
|
|
several times). If a <a href="#media-resource">media resource</a>'s audio track
|
|
exposed in this way has no known name, and it is the only audio
|
|
track for a particular <a href="#media-element">media element</a>, the user agent
|
|
should use the element's <code title="attr-title"><a href="elements.html#the-title-attribute">title</a></code>
|
|
attribute, if any, as the name (or as part of the name) of that
|
|
track.</p>
|
|
|
|
<p>Even when the attribute is absent, however, user agents may
|
|
provide controls to affect playback of the media resource
|
|
(e.g. play, pause, seeking, and volume controls), but such features
|
|
should not interfere with the page's normal rendering. For example,
|
|
such features could be exposed in the <a href="#media-element">media element</a>'s
|
|
context menu.</p>
|
|
|
|
<p>Where possible (specifically, for starting, stopping, pausing,
|
|
and unpausing playback, for seeking, for changing the rate of
|
|
playback, for fast-forwarding or rewinding,
|
|
for listing, enabling, and disabling text tracks,
|
|
and for muting or changing the volume of the audio), user interface
|
|
features exposed by the user agent must be implemented in terms of
|
|
the DOM API described above, so that, e.g., all the same events
|
|
fire.</p>
|
|
|
|
<p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, the user agent's user interface for pausing and
|
|
unpausing playback, for seeking, for changing the rate of playback,
|
|
for fast-forwarding or rewinding, and for muting or changing the
|
|
volume of audio of the entire group must be implemented in terms of
|
|
the <code><a href="#mediacontroller">MediaController</a></code> API exposed on that <a href="#current-media-controller">current
|
|
media controller</a>.</p>
|
|
|
|
<p>The "play" function in the user agent's interface must set the
|
|
<code title="">playbackRate</code> attribute to the value of the
|
|
<code title="">defaultPlaybackRate</code> attribute before invoking
|
|
the <code title="">play()</code> method.
|
|
When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, the attributes and method with those names on
|
|
that <code><a href="#mediacontroller">MediaController</a></code> object must be used. Otherwise,
|
|
the attributes and method with those names on the <a href="#media-element">media
|
|
element</a> itself must be used.
|
|
</p>
|
|
|
|
<p>Features such as fast-forward or rewind must be implemented by
|
|
only changing the <code title="">playbackRate</code> attribute (and
|
|
not the <code title="">defaultPlaybackRate</code> attribute).
|
|
Again, when a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, the attributes with those names on that
|
|
<code><a href="#mediacontroller">MediaController</a></code> object must be used; otherwise, the
|
|
attributes with those names on the <a href="#media-element">media element</a> itself
|
|
must be used.
|
|
</p>
|
|
|
|
<p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, and all the <a href="#slaved-media-elements">slaved media elements</a> of
|
|
that <code><a href="#mediacontroller">MediaController</a></code> are paused, the user agent should
|
|
unpause all the <a href="#slaved-media-elements">slaved media elements</a> when the user
|
|
invokes a user agent interface control for beginning playback.</p>
|
|
|
|
<p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, seeking must be implemented in terms of the <code title="dom-MediaController-seek">seek()</code> method on that
|
|
<code><a href="#mediacontroller">MediaController</a></code> object. Otherwise, the user agent must
|
|
directly <a href="#dom-media-seek" title="dom-media-seek">seek</a> to the requested
|
|
position in the <a href="#media-element">media element</a>'s <a href="#media-timeline">media
|
|
timeline</a>.</p>
|
|
|
|
<p>When a <a href="#media-element">media element</a> has a <a href="#current-media-controller">current media
|
|
controller</a>, user agents may additionally provide the user
|
|
with controls that directly manipulate an individual <a href="#media-element">media
|
|
element</a> without affecting the <code><a href="#mediacontroller">MediaController</a></code>,
|
|
but such features are considered relatively advanced and unlikely to
|
|
be useful to most users.
|
|
|
|
</p><p>For the purposes of listing chapters in the <a href="#media-resource">media
|
|
resource</a>, only <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> <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> and whose <a href="#text-track-kind">text track kind</a> is <code title="dom-timedtrack-kind-chapters">chapters</code> should be used.
|
|
Each <a href="#text-track-cue" title="text track cue">cue</a> in such a <a href="#text-track">text
|
|
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
|
|
the chapter is the <a href="#text-track-cue-text">text track cue text</a>, interpreted
|
|
literally.</p>
|
|
|
|
<p>The <dfn id="dom-media-controls" title="dom-media-controls"><code>controls</code></dfn>
|
|
IDL attribute must <a href="common-dom-interfaces.html#reflect">reflect</a> the content attribute of the
|
|
same name.</p>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the current playback volume, as a number in the range
|
|
0.0 to 1.0, where 0.0 is the quietest and 1.0 the loudest.</p>
|
|
|
|
<p>Can be set, to change the volume.</p>
|
|
|
|
<p>Throws an <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> if the new value is not
|
|
in the range 0.0 .. 1.0.</p>
|
|
|
|
</dd>
|
|
|
|
<dt><var title="">media</var> . <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> [ = <var title="">value</var> ]</dt>
|
|
|
|
<dd>
|
|
|
|
<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
|
|
<code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute is being
|
|
honored.</p>
|
|
|
|
<p>Can be set, to change whether the audio is muted or not.</p>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-media-volume" title="dom-media-volume"><code>volume</code></dfn>
|
|
attribute must return the playback volume of any audio portions of
|
|
the <a href="#media-element">media element</a>, in the range 0.0 (silent) to 1.0
|
|
(loudest). Initially, the volume must be 1.0, but user agents may
|
|
remember the last set value across sessions, on a per-site basis or
|
|
otherwise, so the volume may start at other values. On setting, if
|
|
the new value is in the range 0.0 to 1.0 inclusive, the attribute
|
|
must be set to the new value. If the new value is outside the range
|
|
0.0 to 1.0 inclusive, then, on setting, an
|
|
<code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exception must be raised instead.</p>
|
|
|
|
<p>The <dfn id="dom-media-muted" title="dom-media-muted"><code>muted</code></dfn>
|
|
attribute must return true if the audio channels are muted and false
|
|
otherwise. Initially, the audio channels should not be muted
|
|
(false), but user agents may remember the last set value across
|
|
sessions, on a per-site basis or otherwise, so the muted state may
|
|
start as muted (true). On setting, the attribute must be set to the
|
|
new value.</p>
|
|
|
|
<p>Whenever either the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> or
|
|
<code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attributes are changed,
|
|
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
|
|
event</a> named <code title="event-media-volumechange"><a href="#event-media-volumechange">volumechange</a></code> at the <a href="#media-element">media
|
|
element</a>.</p>
|
|
|
|
<p>An element's <dfn id="effective-media-volume">effective media volume</dfn> is determined as
|
|
follows:</p>
|
|
|
|
<ol><li><p>If the element's <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code>
|
|
attribute is true, the element's <a href="#effective-media-volume">effective media
|
|
volume</a> is zero. Abort these steps.</p></li>
|
|
|
|
<li><p>If the element has a <a href="#current-media-controller">current media controller</a>
|
|
and that <code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-mute-override">media
|
|
controller mute override</a> is true, the element's
|
|
<a href="#effective-media-volume">effective media volume</a> is zero. Abort these
|
|
steps.</p></li>
|
|
|
|
<li><p>Let <var title="">volume</var> be the value of the element's
|
|
<code title="dom-media-volume"><a href="#dom-media-volume">volume</a></code> attribute.</p></li>
|
|
|
|
<li><p>If the element has a <a href="#current-media-controller">current media controller</a>,
|
|
multiply <var title="">volume</var> by that
|
|
<code><a href="#mediacontroller">MediaController</a></code> object's <a href="#media-controller-volume-multiplier">media controller volume
|
|
multiplier</a>.</p></li>
|
|
|
|
<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
|
|
1.0, with 0.0 being silent, and 1.0 being the loudest setting,
|
|
values in between increasing in loudness. The range need not be
|
|
linear. The loudest setting may be lower than the system's loudest
|
|
possible setting; for example the user could have set a maximum
|
|
volume.</p></li>
|
|
|
|
</ol></div><p>The <dfn id="attr-media-muted" title="attr-media-muted"><code>muted</code></dfn>
|
|
attribute on the <code><a href="#the-video-element">video</a></code> element controls the default
|
|
state of the audio channel of the <a href="#media-resource">media resource</a>,
|
|
potentially overriding user preferences.</p><div class="impl">
|
|
|
|
<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
|
|
agent must set the <code title="dom-media-muted"><a href="#dom-media-muted">muted</a></code> IDL
|
|
attribute to true, overriding any user preference.</p>
|
|
|
|
<p>The <dfn id="dom-media-defaultmuted" title="dom-media-defaultMuted"><code>defaultMuted</code></dfn> IDL
|
|
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>
|
|
|
|
</div><p class="note">This attribute has no dynamic effect (it only
|
|
controls the default state of the element).</p><div class="example">
|
|
|
|
<p>This video (an advertisment) autoplays, but to avoid annoying
|
|
users, it does so without sound, and allows the user to turn the
|
|
sound on.</p>
|
|
|
|
<pre><video src="adverts.cgi?kind=video" controls autoplay loop muted></video></pre>
|
|
|
|
</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
|
|
represent a list of ranges (periods) of time.</p><pre class="idl">interface <dfn id="timeranges">TimeRanges</dfn> {
|
|
readonly attribute unsigned long <a href="#dom-timeranges-length" title="dom-TimeRanges-length">length</a>;
|
|
double <a href="#dom-timeranges-start" title="dom-TimeRanges-start">start</a>(in unsigned long index);
|
|
double <a href="#dom-timeranges-end" title="dom-TimeRanges-end">end</a>(in unsigned long index);
|
|
};</pre><dl class="domintro"><dt><var title="">media</var> . <code title="dom-TimeRanges-length"><a href="#dom-timeranges-length">length</a></code></dt>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the number of ranges in the object.</p>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the time for the start of the range with the given index.</p>
|
|
|
|
<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>
|
|
|
|
</dd>
|
|
|
|
<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>
|
|
|
|
<dd>
|
|
|
|
<p>Returns the time for the end of the range with the given index.</p>
|
|
|
|
<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>
|
|
|
|
</dd>
|
|
|
|
</dl><div class="impl">
|
|
|
|
<p>The <dfn id="dom-timeranges-length" title="dom-TimeRanges-length"><code>length</code></dfn>
|
|
IDL attribute must return the number of ranges represented by the object.</p>
|
|
|
|
<p>The <dfn id="dom-timeranges-start" title="dom-TimeRanges-start"><code>start(<var title="">index</var>)</code></dfn> method must return the position
|
|
of the start of the <var title="">index</var>th range represented by
|
|
the object, in seconds measured from the start of the timeline that
|
|
the object covers.</p>
|
|
|
|
<p>The <dfn id="dom-timeranges-end" title="dom-TimeRanges-end"><code>end(<var title="">index</var>)</code></dfn> method must return the position
|
|
of the end of the <var title="">index</var>th range represented by
|
|
the object, in seconds measured from the start of the timeline that
|
|
the object covers.</p>
|
|
|
|
<p>These methods must raise <code><a href="common-dom-interfaces.html#index_size_err">INDEX_SIZE_ERR</a></code> exceptions
|
|
if called with an <var title="">index</var> argument greater than or
|
|
equal to the number of ranges represented by the object.</p>
|
|
|
|
<p>When a <code><a href="#timeranges">TimeRanges</a></code> object is said to be a
|
|
<dfn id="normalized-timeranges-object">normalized <code>TimeRanges</code> object</dfn>, the ranges it
|
|
represents must obey the following criteria:</p>
|
|
|
|
<ul><li>The start of a range must be greater than the end of all
|
|
earlier ranges.</li>
|
|
|
|
<li>The start of a range must be less than the end of that same
|
|
range.</li>
|
|
|
|
</ul><p>In other words, the ranges in such an object are ordered, don't
|
|
overlap, aren't empty, and don't touch (adjacent ranges are folded
|
|
into one bigger range).</p>
|
|
|
|
<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
|
|
<a href="#media-timeline">media timeline</a>.</p>
|
|
|
|
</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
|
|
elements</a> as part of the processing model described above:</p><table><thead><tr><th>Event name
|
|
</th><th>Interface
|
|
</th><th>Dispatched when...
|
|
</th><th>Preconditions
|
|
|
|
</th></tr></thead><tbody><tr><td><dfn id="event-media-loadstart" title="event-media-loadstart"><code>loadstart</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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>.
|
|
</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>
|
|
</td></tr><tr><td><dfn id="event-media-progress" title="event-media-progress"><code>progress</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The user agent is fetching <a href="#media-data">media data</a>.
|
|
</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>
|
|
</td></tr><tr><td><dfn id="event-media-suspend" title="event-media-suspend"><code>suspend</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</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>
|
|
</td></tr><tr><td><dfn id="event-media-abort" title="event-media-abort"><code>abort</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</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>.
|
|
<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.
|
|
</td></tr><tr><td><dfn id="event-media-error" title="event-media-error"><code>error</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>An error occurs while fetching the <a href="#media-data">media data</a>.
|
|
</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.
|
|
<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.
|
|
</td></tr><tr><td><dfn id="event-media-emptied" title="event-media-emptied"><code>emptied</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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).
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-media-stalled" title="event-media-stalled"><code>stalled</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The user agent is trying to fetch <a href="#media-data">media data</a>, but data is unexpectedly not forthcoming.
|
|
</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>.
|
|
|
|
</td></tr></tbody><tbody><tr><td><dfn id="event-media-loadedmetadata" title="event-media-loadedmetadata"><code>loadedmetadata</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The user agent has just determined the duration and dimensions of the <a href="#media-resource">media resource</a>
|
|
and <a href="#the-text-tracks-are-ready">the text tracks are ready</a>.
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-media-loadeddata" title="event-media-loadeddata"><code>loadeddata</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-media-canplay" title="event-media-canplay"><code>canplay</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-media-canplaythrough" title="event-media-canplaythrough"><code>canplaythrough</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</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>.
|
|
</td></tr><tr><td><dfn id="event-media-playing" title="event-media-playing"><code>playing</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>Playback is ready to start after having been paused or delayed due to lack of <a href="#media-data">media data</a>.
|
|
</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
|
|
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
|
|
the element is <a href="#paused-for-user-interaction">paused for user interaction</a>.
|
|
</td></tr><tr><td><dfn id="event-media-waiting" title="event-media-waiting"><code>waiting</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</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.
|
|
the element is newly <a href="#blocked-on-its-media-controller">blocked on its media controller</a>, or
|
|
<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>.
|
|
</td></tr></tbody><tbody><tr><td><dfn id="event-media-seeking" title="event-media-seeking"><code>seeking</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td><td>
|
|
</td></tr><tr><td><dfn id="event-media-seeked" title="event-media-seeked"><code>seeked</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code title="dom-media-seeking"><a href="#dom-media-seeking">seeking</a></code> IDL attribute changed to false.
|
|
</td><td>
|
|
</td></tr><tr><td><dfn id="event-media-ended" title="event-media-ended"><code>ended</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>Playback has stopped because the end of the <a href="#media-resource">media resource</a> was reached.
|
|
</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.
|
|
|
|
</td></tr></tbody><tbody><tr><td><dfn id="event-media-durationchange" title="event-media-durationchange"><code>durationchange</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code title="dom-media-duration"><a href="#dom-media-duration">duration</a></code> attribute has just been updated.
|
|
</td><td>
|
|
</td></tr><tr><td><dfn id="event-media-timeupdate" title="event-media-timeupdate"><code>timeupdate</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td><td>
|
|
</td></tr><tr><td><dfn id="event-media-play" title="event-media-play"><code>play</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly false.
|
|
</td></tr><tr><td><dfn id="event-media-pause" title="event-media-pause"><code>pause</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td><td><code title="dom-media-paused"><a href="#dom-media-paused">paused</a></code> is newly true.
|
|
</td></tr><tr><td><dfn id="event-media-ratechange" title="event-media-ratechange"><code>ratechange</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td><td>
|
|
</td></tr><tr><td><dfn id="event-media-volumechange" title="event-media-volumechange"><code>volumechange</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td><td>
|
|
</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
|
|
</th><th>Interface
|
|
</th><th>Dispatched when...
|
|
|
|
</th></tr></thead><tbody><tr><td><dfn id="event-mediacontroller-emptied" title="event-MediaController-emptied"><code>emptied</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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>.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-loadedmetadata" title="event-MediaController-loadedmetadata"><code>loadedmetadata</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-loadeddata" title="event-MediaController-loadeddata"><code>loadeddata</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-canplay" title="event-MediaController-canplay"><code>canplay</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-canplaythrough" title="event-MediaController-canplaythrough"><code>canplaythrough</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-playing" title="event-MediaController-playing"><code>playing</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code><a href="#mediacontroller">MediaController</a></code> is no longer a <a href="#blocked-media-controller">blocked media controller</a>.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-waiting" title="event-MediaController-waiting"><code>waiting</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code><a href="#mediacontroller">MediaController</a></code> is now a <a href="#blocked-media-controller">blocked media controller</a>.
|
|
</td></tr><tr><td><dfn id="event-mediacontcoller-ended" title="event-MediaContcoller-ended"><code>ended</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>All the <a href="#slaved-media-elements">slaved media elements</a> have newly <a href="#ended-playback">ended playback</a>.
|
|
|
|
</td></tr></tbody><tbody><tr><td><dfn id="event-mediacontroller-durationchange" title="event-MediaController-durationchange"><code>durationchange</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code title="dom-MediaController-duration"><a href="#dom-mediacontroller-duration">duration</a></code> attribute has just been updated.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-timeupdate" title="event-MediaController-timeupdate"><code>timeupdate</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <a href="#media-controller-position">media controller position</a> changed.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-play" title="event-MediaController-play"><code>play</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly false.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-pause" title="event-MediaController-pause"><code>pause</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</td><td>The <code title="dom-MediaController-paused"><a href="#dom-mediacontroller-paused">paused</a></code> attribute is newly true.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-ratechange" title="event-MediaController-ratechange"><code>ratechange</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td></tr><tr><td><dfn id="event-mediacontroller-volumechange" title="event-MediaController-volumechange"><code>volumechange</code></dfn>
|
|
</td><td><code><a href="infrastructure.html#event">Event</a></code>
|
|
</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.
|
|
</td></tr></tbody></table><div class="impl">
|
|
|
|
<h5 id="security-and-privacy-considerations"><span class="secno">4.8.10.16 </span>Security and privacy considerations</h5>
|
|
|
|
<p>The main security and privacy implications of the
|
|
<code><a href="#the-video-element">video</a></code> and <code><a href="#the-audio-element">audio</a></code> elements come from the
|
|
ability to embed media cross-origin. There are two directions that
|
|
threats can flow: from hostile content to a victim page, and from a
|
|
hostile page to victim content.</p>
|
|
|
|
<hr><p>If a victim page embeds hostile content, the threat is that the
|
|
content might contain scripted code that attempts to interact with
|
|
the <code><a href="infrastructure.html#document">Document</a></code> that embeds the content. To avoid this,
|
|
user agents must ensure that there is no access from the content to
|
|
the embedding page. In the case of media content that uses DOM
|
|
concepts, the embedded content must be treated as if it was in its
|
|
own unrelated <a href="browsers.html#top-level-browsing-context">top-level browsing context</a>.</p>
|
|
|
|
<p class="example">For instance, if an SVG animation was embedded in
|
|
a <code><a href="#the-video-element">video</a></code> element, the user agent would not give it
|
|
access to the DOM of the outer page. From the perspective of scripts
|
|
in the SVG resource, the SVG file would appear to be in a lone
|
|
top-level browsing context with no parent.</p>
|
|
|
|
<hr><p>If a hostile page embeds victim content, the threat is that the
|
|
embedding page could obtain information from the content that it
|
|
would not otherwise have access to. The API does expose some
|
|
information: the existence of the media, its type, its duration, its
|
|
size, and the performance characteristics of its host. Such
|
|
information is already potentially problematic, but in practice the
|
|
same information can more or less be obtained using the
|
|
<code><a href="embedded-content-1.html#the-img-element">img</a></code> element, and so it has been deemed acceptable.</p>
|
|
|
|
<p>However, significantly more sensitive information could be
|
|
obtained if the user agent further exposes metadata within the
|
|
content such as subtitles or chapter titles. This version of the API
|
|
does not expose such information. Future extensions to this API will
|
|
likely reuse a mechanism such as CORS to check that the embedded
|
|
content's site has opted in to exposing such information. <a href="references.html#refsCORS">[CORS]</a></p>
|
|
|
|
<p class="example">An attacker could trick a user running within a
|
|
corporate network into visiting a site that attempts to load a video
|
|
from a previously leaked location on the corporation's intranet. If
|
|
such a video included confidential plans for a new product, then
|
|
being able to read the subtitles would present a confidentiality
|
|
breach.</p>
|
|
|
|
</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
|
|
set-top boxes or mobile phones is often constrained by limited
|
|
hardware resources in the device. For example, a device might only
|
|
support three simultaneous videos. For this reason, it is a good
|
|
practice to release resources held by <a href="#media-element" title="media
|
|
element">media elements</a> when they are done playing, either by
|
|
being very careful about removing all references to the element and
|
|
allowing it to be garbage collected, or, even better, by removing
|
|
the element's <code title="attr-media-src"><a href="#attr-media-src">src</a></code> attribute and
|
|
any <code><a href="#the-source-element">source</a></code> element descendants, and invoking the
|
|
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,
|
|
software, or format limitations can cause video frames to be dropped
|
|
and audio to be choppy or muted.</p><div class="impl">
|
|
|
|
<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>
|
|
|
|
<p><i>This section is non-normative.</i></p>
|
|
|
|
<p>How accurately various aspects of the <a href="#media-element">media element</a>
|
|
API are implemented is considered a quality-of-implementation issue.</p>
|
|
|
|
<p>For example, when implementing the <code title="attr-media-buffered">buffered</code> attribute, how precise
|
|
an implementation reports the ranges that have been buffered depends
|
|
on how carefully the user agent inspects the data. Since the API
|
|
reports ranges as times, but the data is obtained in byte streams, a
|
|
user agent receiving a variable-bit-rate stream might only be able
|
|
to determine precise times by actually decoding all of the data.
|
|
User agents aren't required to do this, however; they can instead
|
|
return estimates (e.g. based on the average bit rate seen so far)
|
|
which get revised as more information becomes available.</p>
|
|
|
|
<p>As a general rule, user agents are urged to be conservative
|
|
rather than optimistic. For example, it would be bad to report that
|
|
everything had been buffered when it had not.</p>
|
|
|
|
<p>Another quality-of-implementation issue would be playing a video
|
|
backwards when the codec is designed only for forward playback (e.g.
|
|
there aren't many key frames, and they are far apart, and the
|
|
intervening frames only have deltas from the previous frame). User
|
|
agents could do a poor job, e.g. only showing key frames; however,
|
|
better implementations would do more work and thus do a better job,
|
|
e.g. actually decoding parts of the video forwards, storing the
|
|
complete frames, and then playing the frames backwards.</p>
|
|
|
|
<p>Similarly, while implementations are allowed to drop buffered
|
|
data at any time (there is no requirement that a user agent keep all
|
|
the media data obtained for the lifetime of the media element), it
|
|
is again a quality of implementation issue: user agents with
|
|
sufficient resources to keep all the data around are encouraged to
|
|
do so, as this allows for a better user experience. For example, if
|
|
the user is watching a live stream, a user agent could allow the
|
|
user only to view the live video; however, a better user agent would
|
|
buffer everything and allow the user to seek through the earlier
|
|
material, pause it, play it forwards and backwards, etc.</p>
|
|
|
|
<p>When multiple tracks are synchronised with a
|
|
<code><a href="#mediacontroller">MediaController</a></code>, it is possible for scripts to add and
|
|
remove media elements from the <code><a href="#mediacontroller">MediaController</a></code>'s list
|
|
of <a href="#slaved-media-elements">slaved media elements</a>, even while these tracks are
|
|
playing. How smoothly the media plays back in such situations is
|
|
another quality-of-implementation issue.</p>
|
|
|
|
<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
|
|
document</a> and not reinserted before the next time the
|
|
<a href="webappapis.html#event-loop">event loop</a> spins, implementations that are resource
|
|
constrained are encouraged to take that opportunity to release all
|
|
hardware resources (like video planes, networking resources, and
|
|
data buffers) used by the <a href="#media-element">media element</a>. (User agents
|
|
still have to keep track of the playback position and so forth,
|
|
though, in case playback is later restarted.)</p>
|
|
|
|
</div></body></html>
|