diff --git a/index.html b/index.html index fdcd059..2fd512e 100644 --- a/index.html +++ b/index.html @@ -619,16 +619,22 @@

Processing considerations

Exposing change of MediaStreamTrack configuration

+

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. +

+

MediaStreamTrack Interface Extensions

-

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. -

- 
+    
 partial interface MediaStreamTrack {
   attribute EventHandler onconfigurationchange;
 };

+    
The onconfigurationchange attribute
+      is an [=event handler IDL attribute=] for the `onconfigurationchange`
+      [=event handler=], whose [=event handler event type=] is
+      configurationchange.
+    

     

       
When the [=User Agent=] detects a change of configuration
        in a track's underlying source, the [=User Agent=] MUST run the following steps:

@@ -636,13 +642,18 @@ 
Exposing change of MediaStreamTrack configuration

         
  • If track.{{MediaStreamTrack/muted}} is true, wait for track.{{MediaStreamTrack/muted}}
           to become false or track.{{MediaStreamTrack/readyState}} to be "ended".
    • 
         
  • If track.{{MediaStreamTrack/readyState}} is "ended", abort these steps.
    • 
-        
  • If track's capabilities, constraints and settings are matching source configuration, abort these steps.
+        
  • If track's capabilities, constraints and settings are matching source configuration, abort these steps.
    • 
         
  • 
           
           
    Update track's capabilities, constraints and settings according track's underlying source.
    
         
    • 
-        
  • 
-          
    [=Fire an event=] named configurationchange on track.
    
+        
  • Let changes be an empty [=sequence=].
    • 
+        
  • For each change in track's capabilities and settings, add its name to changes.
    • 
+        
  •      
+          
    [=Fire an event=] named {{MediaStreamTrack/configurationchange}}
+          at track using {{ConfigurationChangeEvent}}, with its 
+          {{ConfigurationChangeEvent.changes}} attribute initialized to
+          changes.
    
         
    • 
       
     
    
@@ -653,6 +664,35 @@ 
    Exposing change of MediaStreamTrack configuration

    +

    ConfigurationChangeEvent Interface

    +
    + 
    +[Exposed=Window]
+interface ConfigurationChangeEvent : Event {
+  constructor(DOMString type, ConfigurationChangeEventInit changeEventInitDict);
+  readonly attribute FrozenArray<DOMString> changes;
+};
+
+dictionary ConfigurationChangeEventInit : EventInit {
+  required sequence<DOMString> changes;
+};
    +

    The changes getter + steps are to return the value that the corresponding attribute was + initialized to. +

    +
    +

    Example

    +
    +

    This example shows how to monitor external background blur changes.

    + 
    +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.
+  }
+});
    +