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;
+    attribute FrozenArray<ChapterInformation> chapterInfo;
 };
 
 dictionary MediaImage {
   required USVString src;
   DOMString sizes = "";
   DOMString type = "";
 };
+
+interface ChapterInformation {
+  attribute DOMString title;
+  attribute double startTime;
+  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;
+  attribute sequence<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,82 @@ 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 = {});
+  attribute DOMString title;
+  attribute double startTime;
+  attribute FrozenArray&lt;MediaImage> artwork;
+};
+
+dictionary ChapterInformationInit {
+  DOMString title = "";
+  double startTime = 0;
+  attribute FrozenArray&lt;MediaImage> artwork = [];
+};
+
+</pre>
+
+The <dfn dict-member for="ChapterInformation">title</dfn> <a>dictionary member</a> is
+used to specify the {{ChapterInformation}} object's {{MediaImage/title}}. 
+
+The <dfn dict-member for="ChapterInformation">startTime</dfn> <a>dictionary member</a>
+is used to specify the {{ChapterInformation}} object's {{MediaImage/startTime}} in
+seconds. It should not be negative.
+
+The <dfn dict-member for="ChapterInformation">artwork</dfn> <a>dictionary member</a>
+is used to specify the {{ChapterInformation}} object's {{MediaImage/artwork}}. On 
+getting, it MUST return the result of the following steps:
+  <ol>
+    <li>
+      Let <var>frozenArtwork</var> be an empty list of type {{MediaImage}}.
+    </li>
+    <li>
+      For each <var>entry</var> in the {{ChapterInformation}}'s <a
+      for="ChapterInformation">artwork images</a>, perform the following steps:
+      <ol>
+        <li>
+          Let <var>image</var> be a new {{MediaImage}}.
+        </li>
+        <li>
+          Set <var>image</var>'s {{MediaImage/src}} to <var>entry</var>'s
+          {{MediaImage/src}}.
+        </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>
+        <!-- XXX IDL dictionaries are usually returned by value, so don't need
+        to be immutable. But FrozenArray reifies the dictionaries to mutable JS
+        objects accessed by reference, so we explicitly freeze them. It would be
+        better to do this with IDL primitives instead of JS - see
+        https://www.w3.org/Bugs/Public/show_bug.cgi?id=29004 -->
+        <li>
+          Call <a lt="freeze">Object.freeze</a> on <var>image</var>, to prevent
+          accidental mutation by scripts.
+        </li>
+        <li>
+          Append <var>image</var> to <var>frozenArtwork</var>.
+        </li>
+      </ol>
+    </li>
+    <li>
+      <a>Create a frozen array</a> from <var>frozenArtwork</var>.
+    </li>
+  </ol>
+
+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.
+
+
 <h2 id="the-mediaimage-dictionary">The {{MediaImage}} dictionary</h2>
 
 <pre class="idl">
@@ -1300,14 +1389,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 +1414,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>