Update index.bs with ChapterInformation

explainer.md

@@ -107,8 +107,9 @@ interface MediaSession : EventTarget {
 ### The `MediaMetadata` interface
 
 A `MediaMetadata` object can contain media metadata like title, artist, album
-and album art. To set the metadata for a `MediaSession`, the page should create
-a `MediaMetadata` object and assign it to a `MediaSession` object:
+album art and video chapter information. To set the metadata for a `MediaSession`,
+the page should create a `MediaMetadata` object and assign it to a `MediaSession`
+object:
 
 ```javascript
 navigator.mediaSession.metadata = new MediaMetadata(/* MediaMetadata constructor */);
@@ -123,13 +124,20 @@ interface MediaMetadata {
     attribute DOMString artist;
     attribute DOMString album;
     attribute FrozenArray<MediaImage> artwork;
+    readonly attribute FrozenArray<ChapterInformation> chapterInfo;
 };
 
 dictionary MediaImage {
   required USVString src;
   DOMString sizes = "";
   DOMString type = "";
 };
+
+interface ChapterInformation {
+  attribute DOMString title;
+  attribute double startTime;
+  readonly attribute FrozenArray<MediaImage> artwork;
+};
 ```
 
 ### The `MediaPositionState` dictionary

index.bs

@@ -940,13 +940,15 @@ interface MediaMetadata {
   attribute DOMString artist;
   attribute DOMString album;
   attribute FrozenArray<MediaImage> artwork;
+  [SameObject] readonly attribute FrozenArray<ChapterInformation> chapterInfo;
 };
 
 dictionary MediaMetadataInit {
   DOMString title = "";
   DOMString artist = "";
   DOMString album = "";
   sequence<MediaImage> artwork = [];
+  sequence<ChapterInformationInit> chapterInfo = [];
 };
 </pre>
 
@@ -972,6 +974,11 @@ dictionary MediaMetadataInit {
   images</dfn>.
 </p>
 
+<p>
+  A {{MediaMetadata}} has an associated list of <dfn for="MediaMetadata">
+  chapter information</dfn>.
+</p>
+
 <p>
   A {{MediaMetadata}} is said to be an <dfn>empty metadata</dfn> if it is equal
   to <code>null</code> or all the following conditions are true:
@@ -981,6 +988,8 @@ dictionary MediaMetadataInit {
     <li>Its <a for=MediaMetadata>album</a> is the empty string.</li>
     <li>Its <a for=MediaMetadata title='artwork image'>artwork images</a> length
     is <code>0</code>.</li>
+    <li>Its <a for=MediaMetadata>chapter information</a> length
+    is <code>0</code>.</li>
   </ul>
 </p>
 
@@ -1011,6 +1020,10 @@ dictionary MediaMetadataInit {
       <var>metadata</var>'s <a for="MediaMetadata">artwork images</a> as the
       result if it succeeded.
     </li>
+    <li>
+      Set <var>metadata</var>'s {{MediaMetadata/chapterInfo}} to
+      <var>init</var>'s {{MediaMetadataInit/chapterInfo}}.
+    </li>
     <li>
       Return <var>metadata</var>.
     </li>
@@ -1157,6 +1170,180 @@ invoked, the user agent MUST run the following steps:
   </ol>
 </p>
 
+<h2 id="the-chapterinformation-interface">The {{ChapterInformation}} interface</h2>
+
+<pre class="idl">
+interface ChapterInformation {
+  constructor(optional ChapterInformationInit init = {});
+  readonly attribute DOMString title;
+  readonly attribute double startTime;
+  [SameObject] readonly attribute FrozenArray&lt;MediaImage> artwork;
+};
+
+dictionary ChapterInformationInit {
+  DOMString title = "";
+  double startTime = 0;
+  sequence&lt;MediaImage> artwork = [];
+};
+
+</pre>
+
+<p>
+  A {{ChapterInformation}} object is a representation of metadata for an individual
+  chapter, such as the title of the section, its timestamp, and screenshot image data
+  of this section, that can be used by user agents to provide a customized user interface. 
+</p>
+
+<p>
+  A {{ChapterInformation}} can have an associated <dfn for="ChapterInformation">
+  MediaMetadata</dfn>.
+</p>
+
+<p>
+  A {{ChapterInformation}} has an associated <dfn for="ChapterInformation">title</dfn>
+  which is DOMString.
+</p>
+
+<p>
+  A {{ChapterInformation}} has an associated <dfn for="ChapterInformation">
+  startTime</dfn> which is double.
+</p>
+
+<p>
+  A {{ChapterInformation}} has an associated list of <dfn for="ChapterInformation">
+artwork images</dfn>.
+</p>
+
+<p>
+  A {{ChapterInformation}} is said to be an <dfn>empty chapterInfo</dfn> if it is equal
+  to `null` or all the following conditions are true:
+  <ul>
+    <li>Its <a for=ChapterInformation>title</a> is the empty string.</li>
+    <li>Its <a for=ChapterInformation>startTime</a> is <code>0</code>.</li>
+    <li>Its <a for=ChapterInformation title='artwork image'>artwork images</a> length
+    is <code>0</code>.</li>
+  </ul>
+</p>
+
+<p>
+  The <dfn constructor
+  for="ChapterInformation">ChapterInformation(<var>init</var>)</dfn>
+  constructor, when invoked, MUST run the following steps:
+
+  <ol>
+    <li>
+      Let <var>chapterInfo</var> be a new {{ChapterInformation}} object.
+    </li>
+    <li>
+      Set <var>chapterInfo</var>'s {{ChapterInformation/title}} to <var>init</var>'s
+      {{ChapterInformationInit/title}}.
+    </li>
+    <li>
+      Set <var>chapterInfo</var>'s {{ChapterInformation/startTime}} to <var>init</var>'s
+      {{ChapterInformationInit/startTime}}.
+    </li>
+    <li>
+      Run the <a>convert artwork algorithm</a> with <var>init</var>'s
+      {{ChapterInformationInit/artwork}} as <var>input</var> and set
+      <var>chapterInfo</var>'s <a for="ChapterInformation">artwork images</a> as the
+      result if it succeeded.
+    </li>
+    <li>
+      Return <var>chapterInfo</var>.
+    </li>
+  </ol>
+</p>
+
+When the <dfn>convert artwork algorithm</dfn> with <var>input</var> parameter is
+invoked, the user agent MUST run the following steps:
+<ol>
+  <li>
+    Let <var>output</var> be an empty list of type {{MediaImage}}.
+  </li>
+  <li>
+    For each <var>entry</var> in <var>input</var>'s
+    {{ChapterInformationInit/artwork}}, perform the following steps:
+    <ol>
+      <li>
+        Let <var>image</var> be a new {{MediaImage}}.
+      </li>
+      <li>Let <var>baseURL</var> be the API base URL specified by the <a>entry
+      settings object</a>. </li>
+      <li>
+        <a lt="url parser">Parse</a> <var>entry</var>'s {{MediaImage/src}} using
+        <var>baseURL</var>. If it does not return failure, set
+        <var>image</var>'s {{MediaImage/src}} to the return value. Otherwise,
+        throw a <a exception>TypeError</a> and abort these steps.
+      </li>
+      <li>
+        Set <var>image</var>'s {{MediaImage/sizes}} to <var>entry</var>'s
+        {{MediaImage/sizes}}.
+      </li>
+      <li>
+        Set <var>image</var>'s {{MediaImage/type}} to <var>entry</var>'s
+        {{MediaImage/type}}.
+      </li>
+      <li>
+        Append <var>image</var> to the <var>output</var>.
+      </li>
+    </ol>
+  </li>
+  <li>
+    Return <var>output</var> as result.
+  </li>
+</ol>
+
+<p>
+  The <dfn attribute for="ChapterInformation">title</dfn> attribute
+  reflects the {{ChapterInformation}}'s <a for=ChapterInformation>title</a>. On getting,
+  it MUST return the {{ChapterInformation}}'s <a for=ChapterInformation>title</a>. On
+  setting, it MUST set the {{ChapterInformation}}'s <a for=ChapterInformation>title</a> to
+  the given value.
+</p>
+
+<p>
+  The <dfn attribute for="ChapterInformation">startTime</dfn> attribute
+  reflects the {{ChapterInformation}}'s <a for=ChapterInformation>startTime</a>. On getting,
+  it MUST return the {{ChapterInformation}}'s <a for=ChapterInformation>startTime</a>. On
+  setting, it MUST set the {{ChapterInformation}}'s <a for=ChapterInformation>startTime</a>
+  to the given value. If the <a for=ChapterInformation>startTime</a> is negative or greater than
+  <a dict-member for="MediaPositionState">duration</a>, throw a <a exception>TypeError</a>
+</p>
+
+<p>
+  The <dfn attribute for="ChapterInformation">artwork</dfn>
+  attribute reflects the {{ChapterInformation}}'s <a for="ChapterInformation">artwork
+  images</a>. On getting, it MUST return the {{ChapterInformation}}'s <a for=ChapterInformation>
+  artwork</a>. On setting, it MUST run the <a>convert artwork algorithm</a> with the new value as
+  <var>input</var>, and set the {{ChapterInformation}}'s <a for="ChapterInformation">artwork
+  images</a> as the result if it succeeded.
+</p>
+
+<p>
+  When {{ChapterInformation}}'s <a for=ChapterInformation>title</a>, <a
+  for=ChapterInformation>startTime</a> or <a for=ChapterInformation>artwork images</a>
+  are modified, the user agent MUST run the following steps:
+  <ol>
+    <li>
+      If the instance has no associated [=ChapterInformation/media metadata=],
+      abort these steps.
+    </li>
+    <li>
+      Otherwise, <a>queue a task</a> to run the following substeps:
+      <ol>
+        <li>
+          If the instance no longer has an associated <a for=ChapterInformation>media
+          metadata</a>, abort these steps.
+        </li>
+        <li>
+          Otherwise, <a>in parallel</a>, run the <a>update metadata
+          algorithm</a>.
+        </li>
+      </ol>
+    </li>
+  </ol>
+</p>
+
 <h2 id="the-mediaimage-dictionary">The {{MediaImage}} dictionary</h2>
 
 <pre class="idl">
@@ -1300,14 +1487,18 @@ If disabled in the document, the User Agent MUST NOT select the document's media
       title: "Episode Title",
       artist: "Podcast Host",
       album: "Podcast Title",
-      artwork: [{src: "podcast.jpg"}]
+      artwork: [{src: "podcast.jpg"}],
+      chapterInfo: [
+        {title: "Chapter 1", startTime: 0, artwork: [{src: "chapter1.jpg"}]},
+        {title: "Chapter 2", startTime: 120, artwork: [{src: "chapter2.jpg"}]}
+      ]
     });
   </pre>
 
   Alternatively, providing multiple <a for="MediaMetadata" title="artwork
   image">artwork images</a> in the metadata can let the user agent be able to
   select different artwork images for different display purposes and better fit
-  for different screens:
+  for different screens (the same for the artwork in {{MediaMetadata/chapterInfo}}):
 
   <pre class="lang-javascript">
     navigator.mediaSession.metadata = new MediaMetadata({
@@ -1321,6 +1512,16 @@ If disabled in the document, the User Agent MUST NOT select the document's media
         {src: "podcast.png", sizes: "128x128", type: "image/png"},
         {src: "podcast_hd.png", sizes: "256x256", type: "image/png"},
         {src: "podcast.ico", sizes: "128x128 256x256", type: "image/x-icon"}
+      ],
+      chapterInfo: [
+        {title: "Chapter 1", startTime: 0, artwork: [
+           {src: "chapter1_a.jpg", sizes: "128x128", type: "image/jpeg"},
+           {src: "chapter1_b.png", sizes: "256x256", type: "image/png"}
+         ]},
+        {title: "Chapter 2", startTime: 120, artwork: [
+           {src: "chapter2_a.jpg", sizes: "128x128", type: "image/jpeg"},
+           {src: "chapter2_b.png", sizes: "256x256", type: "image/png"}
+         ]}
       ]
     });
   </pre>