diff options
Diffstat (limited to 'devdocs/html/element%2Ftrack.html')
| -rw-r--r-- | devdocs/html/element%2Ftrack.html | 182 |
1 files changed, 182 insertions, 0 deletions
diff --git a/devdocs/html/element%2Ftrack.html b/devdocs/html/element%2Ftrack.html new file mode 100644 index 00000000..4063ab96 --- /dev/null +++ b/devdocs/html/element%2Ftrack.html @@ -0,0 +1,182 @@ +<header><h1><track>: The Embed Text Track element</h1></header><div class="section-content"><p>The <code><track></code> <a href="../index">HTML</a> element is used as a child of the media elements, <a href="audio"><code><audio></code></a> and <a href="video"><code><video></code></a>. It lets you specify timed text tracks (or time-based data), for example to automatically handle subtitles. The tracks are formatted in <a href="https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API">WebVTT format</a> (<code>.vtt</code> files) — Web Video Text Tracks.</p></div> +<h2 id="try_it">Try it</h2> +<div class="section-content"> +<iframe class="interactive is-tabbed-standard-height" height="200" src="https://interactive-examples.mdn.mozilla.net/pages/tabbed/track.html" title="MDN Web Docs Interactive Example" loading="lazy"></iframe> <figure class="table-container"><div class="_table"><table class="properties"> <tbody> <tr> <th scope="row"><a href="../content_categories">Content categories</a></th> <td>None</td> </tr> <tr> <th scope="row">Permitted content</th> <td>None; it is a <a href="https://developer.mozilla.org/en-US/docs/Glossary/Void_element">void element</a>.</td> </tr> <tr> <th scope="row">Tag omission</th> <td> As it is a void element, the start tag must be present and the end tag must not be present. </td> </tr> <tr> <th scope="row">Permitted parents</th> <td> <p> A media element, <a href="audio"><code><audio></code></a> or <a href="video"><code><video></code></a>. </p> </td> </tr> <tr> <th scope="row">Implicit ARIA role</th> <td><a href="https://www.w3.org/TR/html-aria/#dfn-no-corresponding-role" target="_blank">No corresponding role</a></td> </tr> <tr> <th scope="row">Permitted ARIA roles</th> <td>No <code>role</code> permitted</td> </tr> <tr> <th scope="row">DOM interface</th> <td><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement"><code>HTMLTrackElement</code></a></td> </tr> </tbody> </table></div></figure> +</div> +<h2 id="attributes">Attributes</h2> +<div class="section-content"> +<p>This element includes the <a href="../global_attributes">global attributes</a>.</p> <dl> <dt id="default"><a href="#default"><code>default</code></a></dt> <dd> <p>This attribute indicates that the track should be enabled unless the user's preferences indicate that another track is more appropriate. This may only be used on one <code>track</code> element per media element.</p> </dd> <dt id="kind"><a href="#kind"><code>kind</code></a></dt> <dd> <p>How the text track is meant to be used. If omitted the default kind is <code>subtitles</code>. If the attribute contains an invalid value, it will use <code>metadata</code> (Versions of Chrome earlier than 52 treated an invalid value as <code>subtitles</code>). The following keywords are allowed:</p> <ul> <li> +<code>subtitles</code> <ul> <li>Subtitles provide translation of content that cannot be understood by the viewer. For example speech or text that is not English in an English language film.</li> <li>Subtitles may contain additional content, usually extra background information. For example the text at the beginning of the Star Wars films, or the date, time, and location of a scene.</li> </ul> </li> <li> +<code>captions</code> <ul> <li>Closed captions provide a transcription and possibly a translation of audio.</li> <li>It may include important non-verbal information such as music cues or sound effects. It may indicate the cue's source (e.g. music, text, character).</li> <li>Suitable for users who are deaf or when the sound is muted.</li> </ul> </li> <li> +<code>descriptions</code> <ul> <li>Textual description of the video content.</li> <li>Suitable for users who are blind or where the video cannot be seen.</li> </ul> </li> <li> +<code>chapters</code> <ul> <li>Chapter titles are intended to be used when the user is navigating the media resource.</li> </ul> </li> <li> +<code>metadata</code> <ul> <li>Tracks used by scripts. Not visible to the user.</li> </ul> </li> </ul> </dd> <dt id="label"><a href="#label"><code>label</code></a></dt> <dd> <p>A user-readable title of the text track which is used by the browser when listing available text tracks.</p> </dd> <dt id="src"><a href="#src"><code>src</code></a></dt> <dd> <p>Address of the track (<code>.vtt</code> file). Must be a valid URL. This attribute must be specified and its URL value must have the same origin as the document — unless the <a href="audio"><code><audio></code></a> or <a href="video"><code><video></code></a> parent element of the <code>track</code> element has a <a href="../attributes/crossorigin"><code>crossorigin</code></a> attribute.</p> </dd> <dt id="srclang"><a href="#srclang"><code>srclang</code></a></dt> <dd> <p>Language of the track text data. It must be a valid <a href="https://r12a.github.io/app-subtags/" target="_blank">BCP 47</a> language tag. If the <code>kind</code> attribute is set to <code>subtitles</code>, then <code>srclang</code> must be defined.</p> </dd> </dl> +</div> +<h2 id="usage_notes">Usage notes</h2> + +<h3 id="track_data_types">Track data types</h3> +<div class="section-content"> +<p>The type of data that <code>track</code> adds to the media is set in the <code>kind</code> attribute, which can take values of <code>subtitles</code>, <code>captions</code>, <code>descriptions</code>, <code>chapters</code> or <code>metadata</code>. The element points to a source file containing timed text that the browser exposes when the user requests additional data.</p> <p>A media element cannot have more than one <code>track</code> with the same <code>kind</code>, <code>srclang</code>, and <code>label</code>.</p> +</div> +<h3 id="detecting_cue_changes">Detecting cue changes</h3> +<div class="section-content"> +<p>The underlying <a href="https://developer.mozilla.org/en-US/docs/Web/API/TextTrack"><code>TextTrack</code></a>, indicated by the <a class="page-not-created"><code>track</code></a> property, receives a <code>cuechange</code> event every time the currently-presented cue is changed. This happens even if the track isn't associated with a media element.</p> <p>If the track <em>is</em> associated with a media element, using the <a href="track" aria-current="page"><code><track></code></a> element as a child of the <a href="audio"><code><audio></code></a> or <a href="video"><code><video></code></a> element, the <code>cuechange</code> event is also sent to the <a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLTrackElement"><code>HTMLTrackElement</code></a>.</p> <div class="code-example"> +<p class="example-header"><span class="language-name">js</span></p> +<pre data-signature="67EKowfAlq7TgNHfEdB8agM11XlfU8ZhSWymmTwPLKs=" data-language="js"><span class="token keyword">let</span> textTrackElem <span class="token operator">=</span> document<span class="token punctuation">.</span><span class="token function">getElementById</span><span class="token punctuation">(</span><span class="token string">"texttrack"</span><span class="token punctuation">)</span><span class="token punctuation">;</span> + +textTrackElem<span class="token punctuation">.</span><span class="token function">addEventListener</span><span class="token punctuation">(</span><span class="token string">"cuechange"</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">event</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span> + <span class="token keyword">let</span> cues <span class="token operator">=</span> event<span class="token punctuation">.</span>target<span class="token punctuation">.</span>track<span class="token punctuation">.</span>activeCues<span class="token punctuation">;</span> +<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span> +</pre> +</div> +</div> +<h2 id="examples">Examples</h2> +<div class="section-content"><div class="code-example"> +<p class="example-header"><span class="language-name">html</span></p> +<pre data-signature="bKQXYBuqH7YaVmBlgHrYOrXmYVHrlUhDCPQIWXo0ykg=" data-language="html"><span class="token tag"><span class="token tag"><span class="token punctuation"><</span>video</span> <span class="token attr-name">controls</span> <span class="token attr-name">poster</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>/images/sample.gif<span class="token punctuation">"</span></span><span class="token punctuation">></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>source</span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sample.mp4<span class="token punctuation">"</span></span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>video/mp4<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>source</span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sample.ogv<span class="token punctuation">"</span></span> <span class="token attr-name">type</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>video/ogv<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>captions<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleCaptions.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>descriptions<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleDescriptions.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>chapters<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleChapters.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>subtitles<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleSubtitles_de.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>de<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>subtitles<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleSubtitles_en.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>subtitles<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleSubtitles_ja.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>ja<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>subtitles<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>sampleSubtitles_oz.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>oz<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>metadata<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>keyStage1.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token attr-name">label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>Key Stage 1<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>metadata<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>keyStage2.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token attr-name">label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>Key Stage 2<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token tag"><span class="token tag"><span class="token punctuation"><</span>track</span> <span class="token attr-name">kind</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>metadata<span class="token punctuation">"</span></span> <span class="token attr-name">src</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>keyStage3.vtt<span class="token punctuation">"</span></span> <span class="token attr-name">srclang</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>en<span class="token punctuation">"</span></span> <span class="token attr-name">label</span><span class="token attr-value"><span class="token punctuation attr-equals">=</span><span class="token punctuation">"</span>Key Stage 3<span class="token punctuation">"</span></span> <span class="token punctuation">/></span></span> + <span class="token comment"><!-- Fallback --></span> + … +<span class="token tag"><span class="token tag"><span class="token punctuation"></</span>video</span><span class="token punctuation">></span></span> +</pre> +</div></div> +<h2 id="specifications">Specifications</h2> +<div class="_table"><table class="standard-table"> +<thead><tr><th scope="col">Specification</th></tr></thead> +<tbody><tr><td><a href="https://html.spec.whatwg.org/multipage/media.html#the-track-element">HTML Standard <br><small># the-track-element</small></a></td></tr></tbody> +</table></div> +<h2 id="browser_compatibility">Browser compatibility</h2> +<div class="_table"><table> +<thead> +<tr id="bct-browser-type"> +<th></th> +<th colspan="6">Desktop</th> +<th colspan="6">Mobile</th> +</tr> +<tr id="bct-browsers"> +<th></th> +<th>Chrome</th> +<th>Edge</th> +<th>Firefox</th> +<th>Internet Explorer</th> +<th>Opera</th> +<th>Safari</th> +<th>WebView Android</th> +<th>Chrome Android</th> +<th>Firefox for Android</th> +<th>Opera Android</th> +<th>Safari on IOS</th> +<th>Samsung Internet</th> +</tr> +</thead> +<tbody> +<tr> +<th><code>track</code></th> +<td class="bc-supports-yes">23</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes"><details><summary>4.4</summary>Doesn't work for fullscreen video.</details></td> +<td class="bc-supports-yes"><details><summary>25</summary>Doesn't work for fullscreen video.</details></td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes"><details><summary>1.5</summary>Doesn't work for fullscreen video.</details></td> +</tr> +<tr> +<th><code>default</code></th> +<td class="bc-supports-yes">23</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">25</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.5</td> +</tr> +<tr> +<th><code>kind</code></th> +<td class="bc-supports-yes">23</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">25</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.5</td> +</tr> +<tr> +<th><code>label</code></th> +<td class="bc-supports-yes">23</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">25</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.5</td> +</tr> +<tr> +<th><code>src</code></th> +<td class="bc-supports-yes">23</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">25</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.5</td> +</tr> +<tr> +<th><code>srclang</code></th> +<td class="bc-supports-yes">23</td> +<td class="bc-supports-yes">12</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">10</td> +<td class="bc-supports-yes">12.1</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">4.4</td> +<td class="bc-supports-yes">25</td> +<td class="bc-supports-yes">31</td> +<td class="bc-supports-yes">14</td> +<td class="bc-supports-yes">6</td> +<td class="bc-supports-yes">1.5</td> +</tr> +</tbody> +</table></div> +<h2 id="see_also">See also</h2> +<div class="section-content"><ul> <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/WebVTT_API">WebVTT text track format</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement/textTracks"><code>HTMLMediaElement.textTracks</code></a></li> </ul></div><div class="_attribution"> + <p class="_attribution-p"> + © 2005–2023 MDN contributors.<br>Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.<br> + <a href="https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track" class="_attribution-link">https://developer.mozilla.org/en-US/docs/Web/HTML/Element/track</a> + </p> +</div> |