Added region example to Introduction section under "Other features".
authorSilvia Pfeiffer
Wed, 12 Jun 2013 22:26:27 +1000
changeset 94 fe510aaf4b7b
parent 93 4d068e578a97
child 95 441cae500ea5
Added region example to Introduction section under "Other features".
Extended the Data Model section to include regions and list of regions.
webvtt/webvtt.html
--- a/webvtt/webvtt.html	Wed Jun 12 21:34:44 2013 +1000
+++ b/webvtt/webvtt.html	Wed Jun 12 22:26:27 2013 +1000
@@ -448,6 +448,37 @@
 ::cue(.loud) { font-size: 2em }</pre>
 
   </div>
+
+  <div class="example">
+  <p>This example shows two regions containing rollup captions for two different speakers. Fred's cues scroll up in a region in the left half of the video, Bill's cues scroll up in a region on the right half of the video. Fred's first cue disappears at 12.5sec  even through it is defined until 20sec because its region is limited to 3 lines and at 12.5sec a fourth cue appears:
+  </p>
+
+  <pre>WEBVTT
+Region: id=fred width=50% lines=3 regionanchor=0%,100% viewportanchor=10%,90% scroll=up
+Region: id=bill width=50% lines=3 regionanchor=100%,100% viewportanchor=90%,90% scroll=up
+
+00:00:00.000 --> 00:00:20.000 region:fred align:left
+&lt;v Fred>Hi, my name is Fred
+
+00:00:02.500 --> 00:00:22.500 region:bill align:right
+&lt;v Bill>Hi, I'm Bill
+
+00:00:05.000 --> 00:00:25.000 region:fred align:left
+&lt;v Fred>Would you like to get a coffee?
+
+00:00:07.500 --> 00:00:27.500 region:bill align:right
+&lt;v Bill>Sure! I've only had one today.
+
+00:00:10.000 --> 00:00:30.000 region:fred align:left
+&lt;v Fred>This is my fourth!
+
+00:00:12.500 --> 00:00:32.500 region:fred align:left
+&lt;v Fred>OK, let's go.</pre>
+
+  <p>Note that regions are only defined for horizontal cues.</p>
+
+  </div>
+
   </section>
 
   </section>
@@ -505,6 +536,9 @@
   <section>
   <h2>Data model</h2>
 
+  <section>
+  <h3>Text Track Cues</h3>
+
   <p>WebVTT cues are HTML <a title="text track cue">text track cues</a> that additionally
   consist of the following: <a href="#refsHTML5">[HTML5]</a></p>
 
@@ -603,9 +637,7 @@
 
    <dt><dfn title="text 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 title="text track cue writing
-    direction">writing direction</a>.</p>
+     <p>A number giving the position of the text of the cue within each line. If the cue is not within a region, to be interpreted as a percentage of the video, as defined by the <span title="text track cue writing direction">writing direction</span>, otherwise to be interpreted as a percentage of the region width.</p>
    </dd>
 
    <dt><dfn title="text track cue size">A size</dfn>
@@ -645,6 +677,11 @@
 
    </dd>
 
+   <dt><dfn title="text track cue region identifier">A region identifier</dfn></dt>
+   <dd>
+    <p>A string that references by identifier the region that a cue belongs to, if it is not null.</p>
+   </dd>
+
   </dl>
 
   <p>The associated <a>rules for updating the text track rendering</a> of WebVTT <a
@@ -658,16 +695,82 @@
   direction</a>, <a title="text track cue snap-to-lines flag">snap-to-lines flag</a>, <a
   title="text track cue line position">line position</a>, <a title="text track cue text
   position">text position</a>, <a title="text track cue size">size</a>, <a title="text
-  track cue alignment">alignment</a>, or <a title="text track cue text">text</a> change
-  value, then the user agent must empty the <a>text track cue display state</a>, and then
-  immediately run the <a>text track</a>'s <a>rules for updating the display of WebVTT text
-  tracks</a>.</p>
+  track cue alignment">alignment</a>, <a title="text track regon identifier">region</a>,
+  or <a title="text track cue text">text</a> change value, then the user agent must empty
+  the <a>text track cue display state</a>, and then immediately run the <a>text track</a>'s
+  <a>rules for updating the display of WebVTT text tracks</a>.</p>
 
   </div>
 
   </section>
 
   <section>
+  <h3>Text track region</h3>
+  
+  <p>A <dfn title="text track region">text track region</dfn> represents a subpart of the video viewport and provides a rendering area for <a title="text track cue">text track cues</a>.</p>
+
+  <p>Each <a tile="text track region">text track region</a> consists of:</p>
+
+  <dl>
+
+   <dt><dfn title="text track region identifier">An identifier</dfn></dt>
+   <dd>
+    <p>An arbitrary string.</p>
+   </dd>
+
+   <dt><dfn title="text track region width">A width</dfn></dt>
+   <dd>
+    <p>A number giving the width of the box within which the text of each line of the containing cues is to be rendered, to be interpreted as a percentage of the video width. Defaults to 100.</p>
+   </dd>
+
+   <dt><dfn title="text track region lines">A lines value</dfn></dt>
+   <dd>
+    <p>A number giving the number of lines of the box within which the text of each line of the containing cues is to be rendered. Defaults to 3.</p>
+   </dd>
+
+   <dt><dfn title="text track region anchor">A region anchor point</dfn></dt>
+   <dd>
+    <p>Two numbers giving the x and y coordinates within the region which is anchored to the video viewport and does not change location even when the region does, e.g. because of font size changes. Defaults to (0,100), i.e. the bottom left corner of the region.</p>
+   </dd>
+
+   <dt><dfn title="text track region viewport anchor">A region viewport anchor point</dfn></dt>
+   <dd>
+    <p>Two numbers giving the x and y coordinates within the video viewport to which the region anchor point is anchored. Defaults to (0,100), i.e. the bottom left corner of the viewport.</p>
+   </dd>
+
+   <dt><dfn title="text track region scroll">A scroll value</dfn></dt>
+   <dd>
+    <p>One of the following:</p>
+    <dl>
+      <dt><dfn title="text track region scroll none">None</dfn></dt>
+      <dd>Indicates that the cues in the region are not to scroll and instead stay fixed at the location they were first painted in.</dd>
+
+      <dt><dfn title="text track region scroll up">Up</dfn></dt>
+      <dd>Indicates that the cues in the region will be added at the bottom of the region and push any already displayed cues in the region up until all lines of the new cue are visible in the region.</dd>
+      <!-- in the future we may introduce scroll="down"-->
+    </dl>
+   </dd>
+  </dl>
+
+  </section>
+
+  <section>
+  <h3>Text track list of regions</h3>
+
+  <dl>
+  <dt><dfn title="text track list of regions">A text track list of regions</dfn></dfn>
+
+  <dd>
+
+   <p>A list of zero or more <a title="text track region">text track regions</a>. The <a title="text track list of regions">list of regions of a text track</a> can change dynamically, either because the <a title="text track">text track</a> has <a title="text track not loaded">not yet been loaded</a> or is still <a title="text track loading">loading</a>.</p>
+
+  </dd>
+  </dl>
+  </section>
+
+  </section>
+
+  <section>
   <h2>The WebVTT file format</h2>
 
   <section>