Skip to content

Commit

Permalink
[giow] (0) Captions - Stage 3: defining what a timed track and a time…
Browse files Browse the repository at this point in the history 
…d track cue are.

git-svn-id: http://svn.whatwg.org/webapps@5072 340c8d12-0b0e-0410-8428-c7bf67bfef74
  • Loading branch information
@Hixie
Hixie committed May 4, 2010
1 parent 9ed60b7 commit 07eb316
Show file tree
Hide file tree
Showing 3 changed files with 686 additions and 51 deletions.
242 changes: 224 additions & 18 deletions complete.html
View file
Expand Up @@ -530,9 +530,12 @@ <h2 class="no-num no-toc" id=contents>Table of contents</h2>
<li><a href=#timed-tracks><span class=secno>4.8.10.10 </span>Timed tracks</a>
<ol>
<li><a href=#timed-track-model><span class=secno>4.8.10.10.1 </span>Timed track model</a></li>
<li><a href=#event-definitions><span class=secno>4.8.10.10.2 </span>Event definitions</a></li>
<li><a href=#timed-track-api><span class=secno>4.8.10.10.2 </span>Timed track API</a></li>
<li><a href=#in-band-timed-tracks><span class=secno>4.8.10.10.3 </span>In-band timed tracks</a></li>
<li><a href=#websrt><span class=secno>4.8.10.10.4 </span>WebSRT</a></ol></li>
<li><a href=#websrt-timed-tracks><span class=secno>4.8.10.10.4 </span>WebSRT timed tracks</a></li>
<li><a href=#sourcing-timed-tracks><span class=secno>4.8.10.10.5 </span>Sourcing timed tracks</a></li>
<li><a href=#timed-track-processing-model><span class=secno>4.8.10.10.6 </span>Timed track processing model</a></li>
<li><a href=#event-definitions><span class=secno>4.8.10.10.7 </span>Event definitions</a></ol></li>
<li><a href=#user-interface><span class=secno>4.8.10.11 </span>User interface</a></li>
<li><a href=#time-ranges><span class=secno>4.8.10.12 </span>Time ranges</a></li>
<li><a href=#mediaevents><span class=secno>4.8.10.13 </span>Event summary</a></li>
Expand Down Expand Up @@ -23700,8 +23703,8 @@ <h4 id=media-elements><span class=secno>4.8.10 </span>Media elements</h4>
};

interface <dfn id=mutablemediatrack>MutableMediaTrack</dfn> : <a href=#mediatrack>MediaTrack</a> {
void <span title=dom-MutableMediaTrack-addCue>addCue"&gt;(in <a href=#mediacue>MediaCue</a> cue);
void <span title=dom-MutableMediaTrack-removeCue>removeCue"&gt;(in <a href=#mediacue>MediaCue</a> cue);
void <span title=dom-MutableMediaTrack-addCue>addCue</span>(in <a href=#mediacue>MediaCue</a> cue);
void <span title=dom-MutableMediaTrack-removeCue>removeCue</span>(in <a href=#mediacue>MediaCue</a> cue);
};

interface <dfn id=mediacuelist>MediaCueList</dfn> {
Expand All @@ -23719,17 +23722,17 @@ <h4 id=media-elements><span class=secno>4.8.10 </span>Media elements</h4>
readonly attribute float <span title=dom-MediaCue-endTime>endTime</span>;
readonly attribute boolean <span title=dom-MediaCue-pauseOnExit>pauseOnExit</span>;

readonly attribute DOMString <span title=dom-MediaCue-direction>direction</span>;
readonly attribute boolean <span title=dom-MediaCue-snapToLines>snapToLines</span>;
readonly attribute long <span title=dom-MediaCue-linePosition>linePosition</span>;
readonly attribute long <span title=dom-MediaCue-textPosition>textPosition</span>;
readonly attribute long <span title=dom-MediaCue-size>size</span>;
readonly attribute DOMString <span title=dom-MediaCue-direction>direction</span>;
readonly attribute DOMString <span title=dom-MediaCue-alignment>alignment</span>;

readonly attribute DOMString <span title=dom-MediaCue-voice>voice</span>;
DOMString <span title=dom-MediaCue-getCueAsSource()>getCueAsSource</span>();
<a href=#documentfragment>DocumentFragment</a> <span title=dom-MediaCue-getCueAsHTML()>getCueAsHTML</span>();
};</span></span></pre>
};</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-loop><a href=#attr-media-loop>loop</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>
Expand Down Expand Up @@ -25789,7 +25792,193 @@ <h5 id=seeking><span class=secno>4.8.10.9 </span>Seeking</h5>

<h5 id=timed-tracks><span class=secno>4.8.10.10 </span>Timed tracks</h5>

<p class=XXX>processing model for timed tracks</p>
<h6 id=timed-track-model><span class=secno>4.8.10.10.1 </span>Timed track model</h6>

<p>A <a href=#media-element>media element</a> can have a group of associated <dfn id=timed-track title="timed track">timed tracks</dfn>, known as the <a href=#media-element>media
element</a>'s <dfn id=list-of-timed-tracks>list of timed tracks</dfn>. The <a href=#timed-track title="timed track">timed tracks</a> are sorted as follows:</p>

<ol class=brief><li>The <a href=#timed-track title="timed track">timed 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=#tree-order>tree order</a>.</li>

<li>Any <a href=#timed-track title="timed track">timed tracks</a> added using
the <code title=dom-media-addTrack>addTrack()</code> method, in
the order they were added, oldest first.</li>

<li>Any <a href=#timed-track title="timed track">timed 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=#timed-track>timed track</a> consists of:</p>

<dl><dt><dfn id=timed-track-kind title="timed track kind">The kind of timed track</dfn>

<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-mediatrack-kind-subtitles title=dom-MediaTrack-kind-subtitles><code>subtitles</code></dfn>
<li><dfn id=dom-mediatrack-kind-captions title=dom-MediaTrack-kind-captions><code>captions</code></dfn>
<li><dfn id=dom-mediatrack-kind-descriptions title=dom-MediaTrack-kind-descriptions><code>descriptions</code></dfn>
<li><dfn id=dom-mediatrack-kind-chapters title=dom-MediaTrack-kind-chapters><code>chapters</code></dfn>
<li><dfn id=dom-mediatrack-kind-metadata title=dom-MediaTrack-kind-metadata><code>metadata</code></dfn>
</ul><p>The <a href=#timed-track-kind title="timed track kind">kind of track</a> can
change dynamically, in the case of a <a href=#timed-track>timed track</a>
corresponding to a <code><a href=#the-track-element>track</a></code> element.</p>

</dd>

<dt><dfn id=timed-track-label title="timed track label">A label</dfn>

<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=#timed-track-label title="timed track label">label of a track</a> can
change dynamically, in the case of a <a href=#timed-track>timed 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=timed-track-language title="timed track language">A language</dfn>

<dd>

<p>This is a string (a BCP 47 language tag) representing the
language of the timed track's cues. <a href=#refsBCP47>[BCP47]</a></p>

<p>The <a href=#timed-track-language title="timed track language">language of a timed
track</a> can change dynamically, in the case of a <a href=#timed-track>timed
track</a> corresponding to a <code><a href=#the-track-element>track</a></code> element.</p>

</dd>

<dt><dfn id=timed-track-list-of-cues title="timed track list of cues">A list of zero or more cues</dfn>

<dd>

<p>A list of <a href=#timed-track-cue title="timed track cue">timed track cues</a>.</p>

<p>The <a href=#timed-track-list-of-cues title="timed track list of cues">list of cues of a
timed track</a> can change dynamically, in the case of a
<a href=#timed-track>timed track</a> corresponding to a
<code>MutableTimedTrack</code> object: individual cues can be
added or removed dynamically.</p>

</dd>

</dl><p>A <dfn id=timed-track-cue>timed track cue</dfn> is the unit of time-sensitive data
in a <a href=#timed-track>timed 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=#timed-track-cue>timed track cue</a> consists of:</p>

<dl><dt><dfn id=timed-track-cue-identifier title="timed track cue identifier">An identifier</dfn>
<dd>
<p>An arbitrary string.</p>
</dd>

<dt><dfn id=timed-track-cue-start-time title="timed track cue start time">A start time</dfn>
<dd>
<p>A time, in seconds and fractions of a second, at which the cue
becomes relevant.</p>
</dd>

<dt><dfn id=timed-track-cue-end-time title="timed track cue end time">An end time</dfn>
<dd>
<p>A time, in seconds and fractions of a second, at which the cue
stops being relevant.</p>
</dd>

<dt><dfn id=timed-track-cue-pause-on-exit-flag title="timed track cue pause-on-exit flag">A pause-on-exit flag</dfn>
<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=timed-track-cue-writing-direction title="timed track cue writing direction">A writing direction</dfn>
<dd>
<p>A writing direction, either <dfn id=timed-track-cue-horizontal-writing-direction title="timed track cue
horizontal writing direction">horizontal</dfn> (a line extends
horizontally and is positioned vertically, with consecutive lines
displayed below each other), <dfn id=timed-track-cue-vertical-growing-right-writing-direction title="timed 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<!-- used
for east asian-->), or <dfn id=timed-track-cue-vertical-growing-left-writing-direction title="timed 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<!-- used for
mongolian -->).</p>
</dd>

<dt><dfn id=timed-track-cue-snap-to-lines-flag title="timed track cue snap-to-lines flag">A snap-to-lines flag</dfn>
<dd>
<p>A boolean indicating whether the <a href=#timed-track-cue-line-position title="timed track cue
line position">line's position</a> is a line position
(positioned to a multiple of the line dimensions of the first line
of the cue), or whether it is a percentage of the dimension of the
video.</p>
</dd>

<dt><dfn id=timed-track-cue-line-position title="timed track cue line position">A line position</dfn>
<dd>
<p>A number giving the position of the lines of the cue, to be
interpreted as defined by the <a href=#timed-track-cue-writing-direction title="timed track cue writing
direction">writing direction</a> and <a href=#timed-track-cue-snap-to-lines-flag title="timed track
cue snap-to-lines flag">snap-to-lines flag</a> of the cue.</p>
</dd>

<dt><dfn id=timed-track-cue-text-position title="timed track cue text position">A text position</dfn>
<dd>
<p>A number giving the position of the text of the cue within each
line, to be interpreted as a percentage of the video, as defined
by the <a href=#timed-track-cue-writing-direction title="timed track cue writing direction">writing
direction</a>.</p>
</dd>

<dt><dfn id=timed-track-cue-size title="timed track cue size">A size</dfn>
<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=#timed-track-cue-writing-direction title="timed
track cue writing direction">writing direction</a>.</p>
</dd>

<dt><dfn id=timed-track-cue-alignment title="timed track cue alignment">An alignment</dfn>
<dd>
<p>An alignment for the text of each line of the cue, either <dfn id=timed-track-cue-start-alignment title="timed track cue start alignment">start alignment</dfn> (the
text is aligned towards its start side), <dfn id=timed-track-cue-middle-alignment title="timed track
cue middle alignment">middle alignment</dfn> (the text is aligned
centered between its start and end sides), <dfn id=timed-track-cue-end-alignment title="timed track
cue end alignment">end alignment</dfn> (the text is aligned
towards its end side). Which sides are the start and end sides
depends on the Unicode bidirectional algorithm and the <a href=#timed-track-cue-writing-direction title="timed track cue writing direction">writing
direction</a>. <a href=#refsBIDI>[BIDI]</a></p>
</dd>

<dt><dfn id=timed-track-cue-voice-identifier title="timed track cue voice identifier">A voice identifier</dfn>
<dd>
<p>A string identifying the voice with which the cue is associated.</p>
</dd>

<dt><dfn id=timed-track-cue-text title="timed track cue text">The text of the cue</dfn>
<dd>
<p>The raw text of the cue, and rules for its interpretation,
allowing the text to be converted to an equivalent fragment of
HTML.</p>
</dd>

</dl><p class=XXX>...


<h6 id=timed-track-api><span class=secno>4.8.10.10.2 </span>Timed track API</h6>

<!--
// timed tracks on HTMLMediaElement:
Expand All @@ -25813,8 +26002,8 @@ <h5 id=timed-tracks><span class=secno>4.8.10.10 </span>Timed tracks</h5>
};

interface <dfn>MutableMediaTrack</dfn> : <span>MediaTrack</span> {
void <span title="dom-MutableMediaTrack-addCue">addCue">(in <span>MediaCue</span> cue);
void <span title="dom-MutableMediaTrack-removeCue">removeCue">(in <span>MediaCue</span> cue);
void <span title="dom-MutableMediaTrack-addCue">addCue</span>(in <span>MediaCue</span> cue);
void <span title="dom-MutableMediaTrack-removeCue">removeCue</span>(in <span>MediaCue</span> cue);
};

interface <dfn>MediaCueList</dfn> {
Expand All @@ -25832,11 +26021,11 @@ <h5 id=timed-tracks><span class=secno>4.8.10.10 </span>Timed tracks</h5>
readonly attribute float <span title="dom-MediaCue-endTime">endTime</span>;
readonly attribute boolean <span title="dom-MediaCue-pauseOnExit">pauseOnExit</span>;

readonly attribute DOMString <span title="dom-MediaCue-direction">direction</span>;
readonly attribute boolean <span title="dom-MediaCue-snapToLines">snapToLines</span>;
readonly attribute long <span title="dom-MediaCue-linePosition">linePosition</span>;
readonly attribute long <span title="dom-MediaCue-textPosition">textPosition</span>;
readonly attribute long <span title="dom-MediaCue-size">size</span>;
readonly attribute DOMString <span title="dom-MediaCue-direction">direction</span>;
readonly attribute DOMString <span title="dom-MediaCue-alignment">alignment</span>;

readonly attribute DOMString <span title="dom-MediaCue-voice">voice</span>;
Expand All @@ -25845,28 +26034,45 @@ <h5 id=timed-tracks><span class=secno>4.8.10.10 </span>Timed tracks</h5>
};
-->

<h6 id=timed-track-model><span class=secno>4.8.10.10.1 </span>Timed track model</h6>
<p class=XXX>domintro

<div class=impl>

<p class=XXX>...

<h6 id=event-definitions><span class=secno>4.8.10.10.2 </span>Event definitions</h6>
</div>


<h6 id=in-band-timed-tracks><span class=secno>4.8.10.10.3 </span>In-band timed tracks</h6>

<p class=XXX>...

<!-- XXX
CueEvent
readonly attribute MediaCue cue;
-->

<h6 id=in-band-timed-tracks><span class=secno>4.8.10.10.3 </span>In-band timed tracks</h6>
<h6 id=websrt-timed-tracks><span class=secno>4.8.10.10.4 </span>WebSRT timed tracks</h6>

<p class=XXX>...


<h6 id=sourcing-timed-tracks><span class=secno>4.8.10.10.5 </span>Sourcing timed tracks</h6>

<p class=XXX>...

<h6 id=websrt><span class=secno>4.8.10.10.4 </span>WebSRT</h6>

<h6 id=timed-track-processing-model><span class=secno>4.8.10.10.6 </span>Timed track processing model</h6>

<p class=XXX>...


<h6 id=event-definitions><span class=secno>4.8.10.10.7 </span>Event definitions</h6>

<p class=XXX>...

<!-- XXX
CueEvent
readonly attribute MediaCue cue;
-->


<h5 id=user-interface><span class=secno>4.8.10.11 </span>User interface</h5>

<p>The <dfn id=attr-media-controls title=attr-media-controls><code>controls</code></dfn>
Expand Down

0 comments on commit 07eb316

Please sign in to comment.