Add changes to configurationchange event

Author: beaufortfrancois

index.html

@@ -619,30 +619,41 @@ <h4>Processing considerations</h4>
   </section>
   <section>
     <h2>Exposing change of MediaStreamTrack configuration</h2>
+    <p>The configuration (capabilities, constraints or settings) of a {{MediaStreamTrack}} may be changed dynamically
+      outside the control of web applications. One example is when a user decides to switch on background blur through
+      the operating system. Web applications might want to know that the configuration
+      of a particular {{MediaStreamTrack}} has changed. For that purpose, a new event is defined below.
+   </p>
+    <h3>MediaStreamTrack Interface Extensions</h3>
     <div>
-      <p>The configuration (capabilities, constraints or settings) of a {{MediaStreamTrack}} may be changed dynamically
-        outside the control of web applications. One example is when a user decides to switch on background blur through
-        the operating system. Web applications might want to know that the configuration
-        of a particular {{MediaStreamTrack}} has changed. For that purpose, a new event is defined below.
-     </p>
-      <pre class="idl">
+    <pre class="idl">
 partial interface MediaStreamTrack {
   attribute EventHandler onconfigurationchange;
 };</pre>
+    <p>The <dfn data-dfn-for="MediaStreamTrack">onconfigurationchange</dfn> attribute
+      is an [=event handler IDL attribute=] for the `onconfigurationchange`
+      [=event handler=], whose [=event handler event type=] is
+      <dfn event for=MediaStreamTrack>configurationchange</dfn>.
+    </p>
     <p>
       <p>When the [=User Agent=] detects <dfn data-export id="change-track-configuration">a change of configuration</dfn>
        in a <var>track</var>'s underlying source, the [=User Agent=] MUST run the following steps:</p>
       <ol>
         <li><p>If <var>track</var>.{{MediaStreamTrack/muted}} is <code>true</code>, wait for <var>track</var>.{{MediaStreamTrack/muted}}
           to become <code>false</code> or <var>track</var>.{{MediaStreamTrack/readyState}} to be "ended".</p></li>
         <li><p>If <var>track</var>.{{MediaStreamTrack/readyState}} is "ended", abort these steps.</p></li>
-        <li><p>If <var>track</var>'s capabilities, constraints and settings are matching <var>source</var> configuration, abort these steps.
+        <li><p>If <var>track</var>'s capabilities, constraints and settings are matching <var>source</var> configuration, abort these steps.</li>
         <li>
           <!-- FIXME: Export capabilities, constraints and settings so that we can use them here. -->
           <p>Update <var>track</var>'s capabilities, constraints and settings according <var>track</var>'s underlying source.</p>
         </li>
-        <li>
-          <p>[=Fire an event=] named <var>configurationchange</var> on <var>track</var>.</p>
+        <li><p>Let <var>changes</var> be an empty [=sequence=].</p></li>
+        <li><p>For each change in <var>track</var>'s capabilities and settings, add its name to <var>changes</var>.</p></li>
+        <li>     
+          <p>[=Fire an event=] named {{MediaStreamTrack/configurationchange}}
+          at <var>track</var> using {{ConfigurationChangeEvent}}, with its 
+          {{ConfigurationChangeEvent.changes}} attribute initialized to
+          <var>changes</var>.</p>
         </li>
       </ol>
     </p>
@@ -653,6 +664,35 @@ <h2>Exposing change of MediaStreamTrack configuration</h2>
       </div>
     </p>
     </div>
+    <h3>ConfigurationChangeEvent Interface</h3>
+    <div>
+      <pre class="idl">
+[Exposed=Window]
+interface ConfigurationChangeEvent : Event {
+  constructor(DOMString type, ConfigurationChangeEventInit changeEventInitDict);
+  readonly attribute FrozenArray&lt;DOMString&gt; changes;
+};
+
+dictionary ConfigurationChangeEventInit : EventInit {
+  required sequence&lt;DOMString&gt; changes;
+};</pre>
+    <p>The <dfn data-dfn-for="ConfigurationChangeEvent">changes</dfn> getter
+      steps are to return the value that the corresponding attribute was
+      initialized to.
+    </p>
+    </div>
+    <h3>Example</h3>
+    <div>
+      <p>This example shows how to monitor external background blur changes.</p>
+      <pre class="example">
+const stream = await navigator.mediaDevices.getUserMedia({ video: true });
+const [track] = stream.getVideoTracks();
+track.addEventListener("configurationchange", (event) => {
+  if (event.changes.includes("backgroundBlur")) {
+    // Background blur configuration has changed.
+  }
+});</pre>
+    </div>
   </section>
 </body>
 </html>