diff --git a/index.html b/index.html index fdcd059..9c9b263 100644 --- a/index.html +++ b/index.html @@ -619,30 +619,45 @@

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:

+       in a track's underlying source, the [=User Agent=] MUST run the following steps:

       
    
         
  1. If track.{{MediaStreamTrack/muted}} is true, wait for track.{{MediaStreamTrack/muted}}
           to become false or track.{{MediaStreamTrack/readyState}} to be "ended".
    2. 
         
  2. If track.{{MediaStreamTrack/readyState}} is "ended", abort these steps.
    3. 
-        
  3. If track's capabilities, constraints and settings are matching source configuration, abort these steps.
         
  4. 
-          
-          
    Update track's capabilities, constraints and settings according track's underlying source.
    
+          
+          
    Update track's capabilities and settings according track's underlying source.
    
         
    5. 
-        
  5. 
-          
    [=Fire an event=] named configurationchange on track.
    
+        
  6. Let changes be an empty [=set=].
    7. 
+        
  7. [=map/For each=] key-value pair of source's settings, if track's settings does not have the same pair, [=set/append=] key to changes.
    8. 
+        
  8. [=map/For each=] key-value pair of track's settings, if source's settings does not have the same pair, [=set/append=] key to changes.
    9. 
+        
  9. [=map/For each=] key-value pair of source's capabilities, if track's capabilities does not have the same pair, [=set/append=] key to changes.
    10. 
+        
  10. [=map/For each=] key-value pair of track's capabilities, if source's capabilities does not have the same pair, [=set/append=] key to changes.
    11. 
+        
  11. If changes [=list/is empty=], abort these steps.
    12. 
+        
  12. [=list/Sort=] changes in lexicographical order.
    13. 
+        
  13.      
+          
    [=Fire an event=] named {{MediaStreamTrack/configurationchange}}
+          using {{ConfigurationChangeEvent}} at track, with its 
+          {{ConfigurationChangeEvent.changes}} attribute initialized to
+          changes.
    
         
    14. 
       

     

@@ -653,6 +668,38 @@ 
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.
+    if (track.getSettings().backgroundBlur) {
+      // Turn off web app own blurring so that video doesn't get double-blurred.
+    }
+  }
+});
+