/**/).
+This section is non-normative.
+ +A WebVTT file may include file-level metadata as key/value pairs on the lines immediately
+following the WEBVTT file header line. This is most useful for disambiguating the
+track kind and identifying the metadata schema in use, particularly for files
+delivered outside of an HTML context where a containing <track> element
+might not be available.
In this example, a captions track is identified with a kind, language, and human-readable + label.
+ ++ WEBVTT + kind: captions + lang: es-MX + label: Español (SDH) + + NOTE + Captions (SDH aka Subtitles for the Deaf and Hard-of-Hearing) + typically include spoken dialog as well as important audible + sounds such as "floor boards creak", "dogs barking", or in + this case, "[♫ música ♫]". + + 1 + 00:00:10.123 --> 00:00:15.432 + ¡Hola! ¿Qué tál? + + 2 + 00:00:47.462 --> 00:01:04.028 + [♫ música ♫] ++ +
In this example, a descriptions track for blind or low-vision audiences is identified. + Descriptions are typically rendered as text-to-speech or braille rather than as on-screen + text.
+ ++ WEBVTT + kind: descriptions + lang: en-US + label: English (AD) + + 1 + 00:00:10.123 --> 00:00:15.432 + A young girl tiptoes down a dark hallway. ++ +
This section is non-normative.
@@ -675,10 +732,13 @@ signifies the end of the WebVTT cue.In this example, a talk is split into each slide being a chapter.
+In this example, topics mentioned in a talk are provided as URLs for reference. The
+ kind: metadata WebVTT header metadata pair signals to consumers that the
+ cue payloads should be processed by a script rather than displayed as text.
WEBVTT + kind: metadata NOTE Thanks to http://output.jsbin.com/mugibo @@ -1455,6 +1515,69 @@ navigation tree. time-aligned metadata. +WebVTT header metadata
+ +WebVTT header metadata is an optional set of file-level key/value pairs declared at +the start of a WebVTT file, immediately following the
+ +WEBVTTfile header +line and terminated by a blank line. It is represented as an ordered list of (key, value) string +pairs.The keys listed below are reserved by this specification. Any pair whose key is not reserved +but which satisfies the syntactic requirements for an unreserved key (see [[#syntax]] — +in particular, the requirement that the key contain a U+002D HYPHEN-MINUS character and not +start with one) is an unrecognized header metadata pair and is preserved for use by +the consuming application. Pairs whose keys do not satisfy those requirements are dropped by +the parser and not exposed to the consuming application; this reserves the unhyphenated +key-name space for future standardization and prevents arbitrary applications from claiming +short, unnamespaced keys.
+ +
A BCP 47 language tag identifying the
+ primary language of the cue payloads. Mirrors the srclang attribute of the HTML
+ <track> element. [[!BCP47]]
One of "subtitles", "captions", "descriptions",
+ "chapters", or "metadata", identifying the intended use of the
+ cues. Mirrors the kind attribute of the HTML
+ <track> element.
A human-readable label suitable for presentation in a track selection menu. Mirrors the
+ label attribute of the HTML <track> element.
Reserved by this specification as the key used to identify the schema or application that + the metadata cues or + unrecognized header metadata pairs conform to.
+This specification does not itself define any values for type;
+ the name is reserved so that a follow-up specification can define a registry of
+ type values without colliding with author-defined keys. The first such value is
+ expected to be defined alongside the time-coded flashing-content metadata work in
+ WebVTT issue #512 (e.g.
+ video.strobing.general-flash). Until at least one value is registered, the
+ type key has no defined behavior beyond reserving the name.
How WebVTT header metadata values are exposed to, and combined with, the
+embedding context is defined by that context. In particular, HTML defines how
+lang, kind, and
+label interact with the corresponding attributes of an
+HTML <track> element; see
+whatwg/html issue #11665.
text/vtt. [[!RFC3629]]
followed by any number of characters that are not U+000A LINE FEED (LF) or U+000D CARRIAGE RETURN
(CR) characters.
- text/vtt. [[!RFC3629]]
A WebVTT header metadata pair consists of the following components, in the given +order:
+ +A WebVTT header metadata key is any sequence of one or more Unicode characters with +all of the following properties:
+ +:) or U+003D EQUALS SIGN (=)
+ characters.-->" (U+002D HYPHEN-MINUS, U+002D
+ HYPHEN-MINUS, U+003E GREATER-THAN SIGN).A WebVTT header metadata key must additionally satisfy one of the following:
+ +The hyphen requirement only applies to keys that are not reserved by this
+specification. It reserves the hyphen-free key-name space for future standardization (for
+example, by the taxonomies anticipated in
+WebVTT issue #512). Reserved keys
+themselves (such as "lang") have no hyphen and remain valid.
Keys are matched in a case-sensitive manner. Authors must use the +lowercase form of reserved keys.
+ +A WebVTT header metadata separator is one of the following:
+ +:").=").The U+003A COLON form is the recommended separator. The U+003D EQUALS SIGN form +is permitted for compatibility with files originally authored for delivery via HLS +(HTTP Live Streaming) and other transports that use the equals-sign convention; authoring tools +should prefer the colon form.
+ +A WebVTT header metadata value is any sequence of zero or more Unicode characters +with all of the following properties:
+ +-->" (U+002D HYPHEN-MINUS, U+002D
+ HYPHEN-MINUS, U+003E GREATER-THAN SIGN).A WebVTT header metadata pair whose WebVTT header metadata key is reserved by +this specification must use a WebVTT header metadata value that conforms to the +constraints given for that key in [[#header-metadata]]. A given reserved key must not appear +more than once in a single WebVTT file.
+A WebVTT region definition block consists of the following components, in the given order:
@@ -1691,8 +1895,14 @@ separated from the next by a WebVTT line terminator. (In other words, any have two consecutive WebVTT line terminators and does not start or end with a WebVTT line terminator.) -WebVTT metadata text cues are only useful for scripted applications (e.g. using the
-metadata text track kind in a HTML text track).
WebVTT metadata text cues are typically used by scripted applications (e.g. using the
+metadata text track kind in a HTML text track). Authors of metadata
+files delivered outside of an HTML context should declare a
+kind of "metadata" together with a
+type identifying the schema in use; see
+[[#header-metadata]]. Consumers that do not recognise the
+type value must not present the cue payloads as
+caption or subtitle text.
A WebVTT parser, given an input byte stream, a text track list of cues -|output|, and a collection of CSS style sheets |stylesheets|, must decode the byte -stream using the UTF-8 decode algorithm, and then must parse the resulting +|output|, a collection of CSS style sheets |stylesheets|, and optionally a +slot |header metadata| for a WebVTT header metadata object, must decode the byte stream +using the UTF-8 decode algorithm, and then must parse the resulting string according to the WebVTT parser algorithm below. This results in WebVTT cues -being added to |output|, and CSS style sheets being added to |stylesheets|. -[[!RFC3629]]
+being added to |output|, CSS style sheets being added to |stylesheets|, and, +if the file contains any WebVTT header metadata pairs, +the resulting WebVTT header metadata being assigned to |header metadata| (when +provided). [[!RFC3629]]A WebVTT parser, specifically its conversion and parsing steps, is typically run asynchronously, with the input byte stream being updated incrementally as the resource is @@ -2529,9 +2742,25 @@ stream lacks this WebVTT file signature, then the parser aborts.
processed, but it contains no useful data and so no WebVTT cues were added to |output|. -Header: If the character indicated by |position| is not a U+000A LINE FEED (LF) - character, then collect a WebVTT block with the in header flag set. Otherwise, - advance |position| to the next character in |input|.
Header: Run these substeps:
+If the character indicated by |position| is a U+000A LINE FEED (LF) character, then + advance |position| to the next character in |input| and skip the remaining substeps of + this step.
+Let |header block| be the result of running the steps to collect a WebVTT block with the in header flag set.
+If |header block| is a WebVTT header metadata object and a |header metadata| + slot was provided to this WebVTT parser, then set the |header metadata| slot to + |header block|.
+collect a sequence of code points that are U+000A LINE FEED (LF) characters.
Otherwise, if in header is set, then let |header metadata| be the result of + collecting WebVTT header metadata from |buffer|, + and return |header metadata|.
Otherwise, return null.
When the algorithm in [[#file-parsing]] says to collect WebVTT header metadata from a +string |input|, the user agent must run the following algorithm. The algorithm returns either a +WebVTT header metadata object or null.
+ +Let |metadata| be a new WebVTT header metadata object, with each of its + reserved keys (see [[#header-metadata]]) unset and with an empty list of + unrecognized header metadata pairs.
Let |lines| be the result of splitting |input| on U+000A LINE FEED (LF) + characters.
Let |had pair| be false.
For each string |line| in |lines|, run the following substeps:
+If |line| does not contain either a U+003A COLON character (":") or a
+ U+003D EQUALS SIGN character ("="), then jump to the step labeled next
+ line.
Let |separator index| be the lowest index in |line| at which either a U+003A COLON + character or a U+003D EQUALS SIGN character appears.
Let |name| be the substring of |line| from the first character up to but not + including the character at |separator index|, with any trailing U+0020 SPACE and U+0009 + CHARACTER TABULATION (tab) characters removed.
If |name| is not a WebVTT header metadata key, then jump to the step labeled + next line. Invalid lines are ignored individually; they do not invalidate other + pairs.
Let |value| be the substring of |line| starting from the character immediately after + |separator index| to the end of |line|, with any leading and trailing U+0020 SPACE and + U+0009 CHARACTER TABULATION (tab) characters removed.
If |value| is not a WebVTT header metadata value, then jump to the step + labeled next line.
Process |name| and |value| as follows:
+lang"kind"subtitles",
+ "captions", "descriptions", "chapters", or
+ "metadata", set kind on |metadata|
+ to |value|. Otherwise, do nothing.label"type"Set |had pair| to true.
Next line: Continue.
If |had pair| is false, return null.
Return |metadata|.
String comparisons of key names in this algorithm are exact (i.e.
+case-sensitive). Reserved keys are defined in lowercase; an input that uses any
+other case (for example "Lang" or "LANG") matches none of the
+reserved-key clauses. Furthermore, because such an input lacks a hyphen, it also fails the
+syntactic requirements for an unreserved key and is therefore ignored by the parser.
Parsers are not required to produce warnings for invalid or unrecognized +header metadata pairs. Pairs that fail validation are dropped without further effect; pairs +that pass validation but use a key not understood by the consuming application are surfaced +through the unrecognized header metadata pairs +list for that application to interpret as it sees fit.
+ +When the WebVTT parser algorithm says to collect WebVTT region settings from a