Skip to content
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

Add changes to configurationchange MediaStreamTrack event #83

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

Add changes to configurationchange MediaStreamTrack event #83

Changes from all commits
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
71 changes: 59 additions & 12 deletions index.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -619,30 +619,45 @@ <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>
in a <var>track</var>'s underlying <var>source</var>, 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>
<!-- 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>
<!-- FIXME: Export capabilities and settings so that we can use them here. -->
<p>Update <var>track</var>'s capabilities 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 [=set=].</p></li>
<li><p>[=map/For each=] <var>key</var>-<var>value</var> pair of <var>source</var>'s settings, if <var>track</var>'s settings does not have the same pair, [=set/append=] <var>key</var> to <var>changes</var>.</p></li>
<li><p>[=map/For each=] <var>key</var>-<var>value</var> pair of <var>track</var>'s settings, if <var>source</var>'s settings does not have the same pair, [=set/append=] <var>key</var> to <var>changes</var>.</p></li>
<li><p>[=map/For each=] <var>key</var>-<var>value</var> pair of <var>source</var>'s capabilities, if <var>track</var>'s capabilities does not have the same pair, [=set/append=] <var>key</var> to <var>changes</var>.</p></li>
<li><p>[=map/For each=] <var>key</var>-<var>value</var> pair of <var>track</var>'s capabilities, if <var>source</var>'s capabilities does not have the same pair, [=set/append=] <var>key</var> to <var>changes</var>.</p></li>
<li><p>If <var>changes</var> [=list/is empty=], abort these steps.</p></li>
<li><p>[=list/Sort=] <var>changes</var> in lexicographical order.</p></li>
<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.

beaufortfrancois marked this conversation as resolved.
Show resolved Hide resolved
using {{ConfigurationChangeEvent}} at <var>track</var>, with its
{{ConfigurationChangeEvent.changes}} attribute initialized to
<var>changes</var>.</p>
</li>
</ol>
</p>
Expand All @@ -653,6 +668,38 @@ <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!

if (track.getSettings().backgroundBlur) {
// Turn off web app own blurring so that video doesn't get double-blurred.
}
}
});</pre>
</div>
</section>
</body>
</html>