Skip to content

Overview

Audio output methods route audio to a specific output device using the browser’s setSinkId API (Chrome / Chromium-based browsers). Call selectAudioOutput() first to trigger the browser permission grant that gates enumeration.

audioOutputs()

Enumerate available audio output devices. Resolves to MediaDeviceInfo[] via navigator.mediaDevices.enumerateDevices().

Browsers gate output-device enumeration behind a permission grant, so call selectAudioOutput() first to trigger the grant. Returns an empty array when navigator.mediaDevices is unavailable (e.g. non-HTTPS origin, SSR).

Returns: Promise<MediaDeviceInfo[]>

TypeScript
const outputs = await player.audioOutputs();
outputs.forEach((device) => {
  const option = document.createElement('option');
  option.value = device.deviceId;
  option.textContent = device.label;
  deviceSelect.appendChild(option);
});

selectAudioOutput()

Open the browser’s audio-output picker. Chrome 105+ exposes MediaDevices.selectAudioOutput(). Returns the selected MediaDeviceInfo, or null when the user cancels. Throws BrowserPolicyError on unsupported browsers.

Returns: Promise<MediaDeviceInfo | null>

Throws: BrowserPolicyError('core:policy/audioOutputPickerUnsupported'), Chrome 105+ only

TypeScript
const device = await player.selectAudioOutput();
if (device) {
  await player.audioOutput(device.deviceId);
}

audioOutput(deviceId?)

Read or write the active audio output device.

Read: audioOutput() returns the current sinkId (device id string), or null for system default output.

Write: audioOutput(deviceId) routes audio to deviceId via HTMLMediaElement.setSinkId() on the backend’s media element. Stores the id on success so a subsequent read reflects the change.

Returns: Promise<string | null> (read) or Promise<void> (write)

Throws: BrowserPolicyError('core:policy/setSinkIdUnsupported') when setSinkId is not supported or no media element is bound.

TypeScript
deviceSelect.addEventListener('change', async () => {
  await player.audioOutput(deviceSelect.value);
});

See also