Skip to content

Add changes to configurationchange MediaStreamTrack event #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add changes to configurationchange MediaStreamTrack event #83

Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
6c0aa31
Add changes to configurationchange event
beaufortfrancois Jan 27, 2023
9bb2380
Address feedback
beaufortfrancois Feb 2, 2023
54fdd5e
Update index.html
beaufortfrancois Feb 6, 2023
5294850
Fix nit
beaufortfrancois Feb 6, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 49 additions & 9 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is a pre-existing issue but it is not very clear whether each clone track will fire in its own event loop task or in the same event loop task.
We might want to file an issue about this.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I've filed an issue at #86.

<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>
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thinking more about it, if capabilities and settings are matching, why should constraints change?
Maybe we can remove constraints here (or we could leave that to a follow-up)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I definitely agree.

<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>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"For each change... add its name"
What is the name of a change? Should that be clarified? (Depending on the answer - the issue was raised of distinguishing capabilities and settings with a similar name. Have I missed the resolution of that discussion?)

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We tentatively settled on having a single array.
One reason is that both capabilities and settings might change at the same time.
Say bgblur is made mandatory, bgblur capabiliy becomes [true] and settings become true.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I agree with Elad, we can probably tidy a bit the language.
Source settings are dictionaries, ditto for capabilities, we could use for describing the matching algorithm, something like:

  • for each key-value pair of source settings, if track settings does not have the same pair, append key to the list if not already in the list.
  • for each key-value pair of track settings, if source settings does not have the same pair, append key to the list if not already in the list.
  • for each key-value pair of source capabilities, if track capabilities does not have the same pair, append key to the list if not already in the list.
  • for each key-value pair of track capabilities, if source set capabilities ings does not have the same pair, append key to the list if not already in the list.
  • If list is empty, abort these steps
  • Sort the list by lexicographical order.
  • Fire the event

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you! It is much better now!

<li>
<p>[=Fire an event=] named {{MediaStreamTrack/configurationchange}}
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think we should also specify the boolean values of bubbles and cancellable for this event. I'd say they should be both false. Do you agree?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These are the default values in EventInit so we might not need it.

at <var>track</var> using {{ConfigurationChangeEvent}}, with its
{{ConfigurationChangeEvent.changes}} attribute initialized to
<var>changes</var>.</p>
</li>
</ol>
</p>
Expand All @@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit, and completely up to you, but maybe a clearer example would also indicate why an app might care about this? Maybe the comment could mention it would toggle its own blurring to be the inverse, so as to always be blurred but never double-blurred?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for the suggestion!

}
});</pre>
</div>
</section>
</body>
</html>