Skip to content

Editorial: use named variables for media-resource-specific text tracks #11293

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+73 −58
Open

Editorial: use named variables for media-resource-specific text tracks #11293

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
131 changes: 73 additions & 58 deletions source
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37461,7 +37461,8 @@ interface <dfn interface>MediaError</dfn> {

<dd>
<p>If the <span>media data</span> is <span>CORS-same-origin</span>, run the <span>steps to
expose a media-resource-specific text track</span> with the relevant data.</p>
expose a media-resource-specific text track</span> with the relevant data,
the <span>media resource</span> and the <span>media element</span>.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Oxford comma. (Also wrapping doesn't look quite right.)


<p class="note">Cross-origin videos do not expose their subtitles, since that would allow
attacks such as hostile sites reading subtitles from confidential videos on a user's
Expand Down Expand Up @@ -39912,119 +39913,133 @@ interface <dfn interface>VideoTrack</dfn> {
some legacy formats can be found in <cite>Sourcing In-band Media Resource Tracks from Media
Containers into HTML</cite>. <ref>INBAND</ref></p>

<p>When a <span>media resource</span> contains data that the user agent recognizes and supports as
being equivalent to a <span>text track</span>, the user agent <a
href="#found-a-media-resource-specific-timed-track">runs</a> the <dfn>steps to expose a
media-resource-specific text track</dfn> with the relevant data, as follows.</p>
<p class="note">When a <span>media resource</span> contains data that the user agent recognizes
and supports as being equivalent to a <span>text track</span>, the user agent <a
href="#found-a-media-resource-specific-timed-track">runs</a> the <span>steps to expose a
media-resource-specific text track</span> with the relevant data.</p>

<p>The <dfn>steps to expose a media-resource-specific text track</dfn> given
some relevant data <var>data</var>,
a <span>media element</span> <var>element</var>, and
a <span>media resource</span> <var>resource</var> are:</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Wrapping doesn't look right.


<!-- this runs synchronously from a fetch task -->

<ol>
<li><p>Associate the relevant data with a new <span>text track</span> and its corresponding new
<code>TextTrack</code> object. The <span>text track</span> is a <span>media-resource-specific
text track</span>.</p></li>
<li>
<p>Let <var>track</var> be a new <span>text track</span>.</p>

<p class="note">This implicitly creates a corresponding new <code>TextTrack</code> object.</p>
</li>

<li><p>Mark <var>track</var> as being a <span>media-resource-specific text track</span>.</p></li>

<li><p>Set the new <span>text track</span>'s <span data-x="text track kind">kind</span>, <span
<li><p>Associate <var>data</var> with <var>track</var>.</p></li>

<li><p>Set <var>track</var>'s <span data-x="text track kind">kind</span>, <span
data-x="text track label">label</span>, and <span data-x="text track language">language</span>
based on the semantics of the relevant data, as defined by the relevant specification. If there
is no label in that data, then the <span data-x="text track label">label</span> must be set to the
empty string.</p></li>
based on the semantics of <var>data</var>, as defined by the relevant specification. If there
is no label in <var>data</var>, then set <var>track</var>'s
<span data-x="text track label">label</span> to the empty string.</p></li>

<li><p>Associate the <span>text track list of cues</span> with the <span>rules for updating the
text track rendering</span> appropriate for the format in question.</p>
<li><p>Set <var>track</var>'s <span data-x="text track list of cues">list of cues</span>'s
<span>rules for updating the text track rendering</span> to the rules appropriate for the format
in question.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"for data's format" maybe? Or resoure? What is the difference between data and resource?


<li>
<p>If the new <span>text track</span>'s <span data-x="text track kind">kind</span> is <code
<p>If <var>track</var>'s <span data-x="text track kind">kind</span> is <code
data-x="dom-TextTrack-kind-chapters">chapters</code> or <code
data-x="dom-TextTrack-kind-metadata">metadata</code>, then set the <span>text track in-band
metadata track dispatch type</span> as follows, based on the type of the <span>media
resource</span>:</p>
data-x="dom-TextTrack-kind-metadata">metadata</code>, then set <var>track</var>'s <span
data-x="text track in-band metadata track dispatch type">in-band metadata track dispatch
type</span> as follows, based on the type of <var>resource</var>:</p>

<dl class="switch">

<dt>If the <span>media resource</span> is an Ogg file</dt>
<dt>If <var>resource</var> is an Ogg file</dt>

<dd>The <span>text track in-band metadata track dispatch type</span> must be set to the value
of the Name header field. <ref>OGGSKELETONHEADERS</ref></dd>
<dd>Set <var>track</var>'s <span data-x="text track in-band metadata track dispatch
type">in-band metadata track dispatch type</span> to the value of the Name header field.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Where does the header come from?

<ref>OGGSKELETONHEADERS</ref></dd>

<dt>If the <span>media resource</span> is a WebM file</dt>
<dt>If <var>resource</var> is a WebM file</dt>

<dd>The <span>text track in-band metadata track dispatch type</span> must be set to the value
of the <code data-x="">CodecID</code> element. <ref>WEBMCG</ref></dd>
<dd>Set <var>track</var>'s <span data-x="text track in-band metadata track dispatch
type">in-band metadata track dispatch type</span> to the value of the
<code data-x="">CodecID</code> element. <ref>WEBMCG</ref></dd>

<dt>If the <span>media resource</span> is an MPEG-2 file</dt>
<dt>If <var>resource</var> is an MPEG-2 file</dt>

<dd>Let <var>stream type</var> be the value of the "stream_type" field describing the text
track's type in the file's program map section, interpreted as an 8-bit unsigned integer. Let
<var>length</var> be the value of the "ES_info_length" field for the track in the same part of
the program map section, interpreted as an integer as defined by <cite>Generic coding of moving
pictures and associated audio information</cite>. Let <var>descriptor bytes</var> be the
<var>length</var> bytes following the "ES_info_length" field. The <span>text track in-band
metadata track dispatch type</span> must be set to the concatenation of the <var>stream
type</var> byte and the zero or more <var>descriptor bytes</var> bytes, expressed in
hexadecimal using <span data-x="ASCII upper hex digit">ASCII upper hex digits</span>.
<ref>MPEG2</ref>
</dd>
<var>length</var> bytes following the "ES_info_length" field. Set <var>track</var>'s
<span data-x="text track in-band metadata track dispatch type">in-band metadata track dispatch
type</span> to the concatenation of the <var>stream type</var> byte and the zero or more
<var>descriptor bytes</var> bytes, expressed in hexadecimal using
<span data-x="ASCII upper hex digit">ASCII upper hex digits</span>. <ref>MPEG2</ref></dd>

<dt>If the <span>media resource</span> is an MPEG-4 file</dt>
<dt>If <var>resource</var> is an MPEG-4 file</dt>

<dd>Let the
first <code data-x="">stsd</code> box of the
first <code data-x="">stbl</code> box of the
first <code data-x="">minf</code> box of the
first <code data-x="">mdia</code> box of the
<span>text track</span>'s <code data-x="">trak</code> box in the
first <code data-x="">mdia</code> box of
<var>track</var>'s <code data-x="">trak</code> box in the
first <code data-x="">moov</code> box
of the file be the <i>stsd box</i>, if any.
Comment on lines 39985 to 39992
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should add <p> elements to this <dd>.


If the file has no <i>stsd box</i>, or if the <i>stsd box</i> has neither a <code
data-x="">mett</code> box nor a <code data-x="">metx</code> box, then the <span>text track
in-band metadata track dispatch type</span> must be set to the empty string.
data-x="">mett</code> box nor a <code data-x="">metx</code> box, then set <var>track</var>'s
<span data-x="text track in-band metadata track dispatch type">in-band metadata track dispatch
type</span> to the empty string.

Otherwise, if the <i>stsd box</i> has a <code data-x="">mett</code> box then the <span>text
track in-band metadata track dispatch type</span> must be set to the concatenation of the
string "<code data-x="">mett</code>", a U+0020 SPACE character, and the value of the first <code
data-x="">mime_format</code> field of the first <code data-x="">mett</code> box of the <i>stsd
box</i>, or the empty string if that field is absent in that box.
Otherwise, if the <i>stsd box</i> has a <code data-x="">mett</code> box then set
<var>track</var>'s <span data-x="text track in-band metadata track dispatch type">in-band
metadata track dispatch type</span> to the concatenation of the string
"<code data-x="">mett</code>", a U+0020 SPACE character, and the value of the first
<code data-x="">mime_format</code> field of the first <code data-x="">mett</code> box of the
<i>stsd box</i>, or the empty string if that field is absent in that box.

Otherwise, if the <i>stsd box</i> has no <code data-x="">mett</code> box but has a <code
data-x="">metx</code> box then the <span>text track in-band metadata track dispatch type</span>
must be set to the concatenation of the string "<code data-x="">metx</code>", a U+0020 SPACE
character, and the value of the first <code data-x="">namespace</code> field of the first <code
data-x="">metx</code> box of the <i>stsd box</i>, or the empty string if that field is absent in
that box.
data-x="">metx</code> box then set <var>track</var>'s <span data-x="text track in-band metadata
track dispatch type">in-band metadata track dispatch type</span> to the concatenation of the
string "<code data-x="">metx</code>", a U+0020 SPACE character, and the value of the first
<code data-x="">namespace</code> field of the first <code data-x="">metx</code> box of the
<i>stsd box</i>, or the empty string if that field is absent in that box.

<ref>MPEG4</ref>
</dd>
</dl>
</li>

<li><p>Populate the new <span>text track</span>'s <span data-x="text track list of cues">list of
cues</span> with the cues parsed so far, following the <span>guidelines for exposing
cues</span>, and begin updating it dynamically as necessary.</p></li>
<li><p>Populate <var>track</var>'s <span data-x="text track list of cues">list of cues</span>
with the cues parsed so far, following the <span>guidelines for exposing cues</span>, and begin
updating it dynamically as necessary.</p></li>

<li><p>Set the new <span>text track</span>'s <span data-x="text track readiness state">readiness
state</span> to <span data-x="text track loaded">loaded</span>.</p></li> <!-- otherwise, you'll
<li><p>Set <var>track</var>'s <span data-x="text track readiness state">readiness state</span> to
<span data-x="text track loaded">loaded</span>.</p></li> <!-- otherwise, you'll
have to load the whole media file just to start playing the first frame... -->

<li><p>Set the new <span>text track</span>'s <span data-x="text track mode">mode</span> to the
mode consistent with the user's preferences and the requirements of the relevant specification
for the data.</p>
<li>
<p>Set <var>track</var>'s <span data-x="text track mode">mode</span> to the mode consistent
with the user's preferences and the requirements of the relevant specification for the data.</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

data?


<p class="note">For instance, if there are no other active subtitles, and this is a forced
subtitle track (a subtitle track giving subtitles in the audio track's primary language, but
only for audio that is actually in another language), then those subtitles might be activated
here.</p>
</li> <!-- it's too late to apply the normal heuristic, so we don't bother -->

<li><p>Add the new <span>text track</span> to the <span>media element</span>'s <span>list of text
tracks</span>.</p></li>
<li><p>Add <var>track</var> to <var>element</var>'s <span>list of text tracks</span>.</p></li>

<li><p><span data-x="concept-event-fire">Fire an event</span> named <code
data-x="event-media-addtrack">addtrack</code> at the <span>media element</span>'s <code
data-x="event-media-addtrack">addtrack</code> at <var>element</var>'s <code
data-x="dom-media-textTracks">textTracks</code> attribute's <code>TextTrackList</code> object,
using <code>TrackEvent</code>, with the <code data-x="dom-TrackEvent-track">track</code>
attribute initialized to the <span>text track</span>'s <code>TextTrack</code> object.</p></li>
attribute initialized to <var>track</var>'s <code>TextTrack</code> object.</p></li>
</ol>

<!-- removetrack: we don't currently ever remove an in-band text track, because it might have been
Expand Down