audioPreferred capture in getDisplayMedia API

at a glance

naming: “audioPreferred” the feature, audioSelection the member

The ChromeStatus listing, the Intent to Ship thread, and the spec PR title all call this feature “audioPreferred”, and the ChromeStatus summary describes an “audioPreference attribute”. Neither string exists in the shipped platform. The member that actually landed — in the W3C specification, the Chromium IDL, and the explainer — is:

navigator.mediaDevices.getDisplayMedia({
  video: true,
  audio: true,
  audioSelection: "preferred"
});

gendn keeps the listing name for the page title and URL (per gendn invariant #1 the listing is authoritative), but every code sample on this page uses the real member name, audioSelection. If you search MDN or a spec for “audioPreferred” you will find nothing — search for audioSelection instead.

why it exists

In getDisplayMedia(), video capture is mandatory and audio is optional: the browser's picker offers audio sharing but leaves it off by default. Applications whose core function needs the audio — the explainer names transcription note-takers, co-watching apps, game streaming, and presentations with media — lose users at that unchecked box, and end up building instructions (“remember to tick share audio”) around a default they cannot influence.

The feature gives the application a declarative way to say audio matters to me, and lets the user agent present the picker accordingly. The user still makes the final call: the spec is explicit that the member is a hint the UA MAY ignore, and Chrome's implementation keeps the toggle fully under user control — including surfacing a recommendation banner rather than blocking when the user turns audio off.

An audio-only capture alternative was considered and rejected in the explainer: it would not serve co-watching-style uses, it departs from the “video anchors what is being shared” security model, and it raises new privacy questions.

how it works — Chrome's picker behavior

The hint is consumed entirely inside the browser's desktop media picker; there is no observable JavaScript-side state change in the call itself. Verified against the Chrome trunk implementation (desktop_media_picker_views.cc, fetched 2026-07-28), when audioSelection: "preferred" is passed and audio capture was also requested (audio: true or audio constraints):

All of these behaviors are gated on the GetDisplayMediaAudioSelection blink feature (stable at trunk) and degrade silently where it is absent: an unknown dictionary member is ignored per WebIDL dictionary semantics, so passing audioSelection to a browser that does not support it is not an error — the picker simply shows its historical defaults.

syntax

Verbatim WebIDL from the W3C Screen Capture Working Draft of 23 July 2026 — the enum and the dictionary member this feature adds:

enum AudioSelectionPreferenceEnum { "preferred" };

dictionary DisplayMediaStreamOptions {
  (boolean or MediaTrackConstraints) video = true;
  (boolean or MediaTrackConstraints) audio = false;
  CaptureController controller;
  SelfCapturePreferenceEnum selfBrowserSurface;
  SystemAudioPreferenceEnum systemAudio;
  WindowAudioPreferenceEnum windowAudio;
  SurfaceSwitchingPreferenceEnum surfaceSwitching;
  MonitorTypeSurfacesEnum monitorTypeSurfaces;
  AudioSelectionPreferenceEnum audioSelection;
};

The member has no default value: when it is absent, no preference is expressed and the picker behaves as it always has. The enum carries exactly one value, "preferred" — there is no way to express “prefer no audio”; omitting the member is the neutral state.

examples

Request a screen capture with audio, and hint that audio is preferred. Always handle the user declining audio anyway — the hint steers, it does not guarantee:

const stream = await navigator.mediaDevices.getDisplayMedia({
  video: true,
  audio: true,
  audioSelection: "preferred"  // hint: this app relies on shared audio
});

const audioTracks = stream.getAudioTracks();
if (audioTracks.length === 0) {
  // The user declined audio sharing (or the UA ignored the hint).
  // The hint never forces audio — decide whether your app can continue.
  showAudioMissingNotice();
}

Feature-detect by probing the picker-facing behavior indirectly — there is no capability query; the member is ignored where unsupported, so detection is best-effort (checking that the browser ships the feature is not exposed to script):

// There is no JS-visible capability surface for the hint itself.
// The safe pattern is unconditional use: unsupported browsers ignore
// the unknown dictionary member (WebIDL semantics) with no exception.
const options = { video: true, audio: true, audioSelection: "preferred" };

browser compatibility

Interim table. BCD has no DisplayMediaStreamOptions data file at all (BCD api/ listing, verified 2026-07-28) and no audioSelection subfeature under api.MediaDevices.getDisplayMedia — the newest sibling subfeature recorded there is windowAudio_option. Rows below are compiled from the linked primary sources, not from BCD.

Base method support for context (BCD): getDisplayMedia() — Chrome 72, Firefox 66, Safari 13; display audio capture at all — Chrome 74, not supported in Firefox or Safari per BCD audio_capture_support. The hint only steers an audio capability that itself remains Chrome-only today.

security and privacy

• No new capture capability — the member cannot turn audio on by itself; audio sharing along with screen video has always been possible. The user retains the final decision in the picker, and Chrome even warns them (the recommendation banner) when they decline audio against the hint.
• Hint, not permission — the spec states the UA MAY ignore the hint; the explainer's privacy analysis concludes no new privacy or security risk is introduced because no new information crosses the trust boundary and no new user control is removed.
• Fingerprinting surface unchanged — the member is write-only (an input to the picker); no state about it is readable back from script, and no new fingerprinting vector is created beyond the existing getDisplayMedia capability.
• Standard getDisplayMedia requirements still apply — secure context, the display-capture Permissions Policy, per-pick consent, and no persistence of the captured surface.

specifications

see also

• Chrome Platform Status — audioPreferred capture in getDisplayMedia API (API record)
• blink-dev — Intent to Ship: audioPreferred capture in getDisplayMedia API
• MDN — MediaDevices: getDisplayMedia() method (the host method; MDN does not document the audioSelection member — verified 2026-07-28, which is why this page exists)
• MDN — Screen Capture API
• WebKit standards-positions #696 — Audio Selection Preference for getDisplayMedia (open)
• w3c/mediacapture-screen-share-extensions #12 — the developer ask behind the feature
• Chromium tracking bug 535514300
• Chrome Platform Showcase — interactive demos for this feature (preferred capture, hint vs default, options inspector)