Design Review #1110

#1110: windowAudio for getDisplayMedia

Opened Jun 10, 2025

こんにちは TAG-さん!

I'm requesting a TAG review of windowAudio option for getDisplayMedia().

The windowAudio option extends the getDisplayMedia() API, allowing Web applications to provide a hint to the user agent regarding the preferred audio source. When getDisplayMedia() is called, the user agent allows the user to choose a tab, window or screen - and optionally a corresponding audio source.

For tabs the corresponding audio source is that tab’s audio.
For screens the corresponding audio source is system audio.

This new option affects the audio source associated with windows. In that case, the hint allows the Web application to indicate whether the UA should offer as the corresponding audio source the window’s audio, the system’s audio, or no audio at all. (The rationale for this is elaborated in the explainer, which is linked below.)

Explainer: https://github.com/drkron/explainers/blob/main/windowAudio_Explainer.md
Specification: https://w3c.github.io/mediacapture-screen-share/#dom-displaymediastreamoptions-windowaudio
WPT Tests: WPT tests are not feasible because (i) this option is but a hint which can be spec-compliantly ignored by the user agent and (ii) the hint may affect the UA’s own UX, e.g. by affecting which of several possible audio sources is most prominently presented to the user.
User research: N/A
Security and Privacy self-review: https://github.com/drkron/documents/blob/main/sp-questionnaire-window-audio.md
GitHub repo: https://github.com/w3c/mediacapture-screen-share
Primary contacts:
- Johannes Kron (@drkron), Google
- Olga Sharanova (@o1ka), Google
This work is being funded by: Google
Primary standards group developing this feature:
- WebRTC WG
Incubation and standards groups that have discussed the design:
- WebRTC WG
Multi-stakeholder support:
- The feature has consensus in the WebRTC WG with positive feedback from all major browsers. It was discussed in the WebRTC WG meeting on May 20, 2025 and later merged to the specification.
Major unresolved issues with or opposition to this specification: None.
Status/issue trackers for implementations:
- Chrome Status: https://chromestatus.com/feature/5072779506089984

Further details:

I have reviewed the TAG's Web Platform Design Principles
Relevant time constraints or deadlines: None at this time.

You should also know that...

We believe this fills a crucial gap in the existing API by offering a hint for window-specific audio behavior, mirroring the existing SystemAudioPreferenceEnum for monitor captures.

Discussions

Discussed Jun 16, 2025 (See Github)

Christian: We want to ask questions back to the proponents, fine for me but Martin thinks the naming isn't goof. We will ask questions, wait for responses

Comment by @christianliebel Jun 18, 2025 (See Github)

Thanks for your proposal. It introduces a new property called windowAudio that can be used to indicate the "level" of audio to share when a window is shared.

Your explainer mentions that the existing systemAudio preference hint should now be applied exclusively for monitor surfaces:

Existing functionality addresses preferences for monitor surfaces with SystemAudioPreferenceEnum (allowing include or exclude system audio).

However, the current normative text of your specification for systemAudio doesn’t support this:

If present, signals whether the application would like system audio to be included among the possible audio sources offered to the user. The user agent MAY ignore this hint.

We think the changed semantics of systemAudio may not be very obvious. Could systemAudio be deprecated in favor of discrete properties monitorAudio (for monitor surfaces), windowAudio (for window surfaces), and browserAudio (for browser surfaces) or a new abstract audio property that applies to all surfaces (acknowledging that is not the goal of your explainer)?

Comment by @drkron Jun 19, 2025 (See Github)

Thanks for your valuable feedback and thoughtful review.

Regarding the systemAudio property, our interpretation is that its application exclusively to monitor surfaces is not a change, but rather already implied by the SystemAudioPreferenceEnum's "include" enum description. This description states:

"The application prefers that options to share system audio be offered to the user for monitor display surfaces."

To address the potential for confusion and to make this relationship more explicit, we've created a PR (https://github.com/w3c/mediacapture-screen-share/pull/327) to clarify this relationship directly within the specification.

We appreciate the suggestion for more granular audio properties (monitorAudio, windowAudio, browserAudio). We will bring it up for broader working group discussion to determine the best path forward for audio sharing controls.

Discussed Jun 23, 2025 (See Github)

Jeffrey: Skip today.