diff --git a/docs/controls.md b/docs/controls.md index 09bf50d4..e5469143 100644 --- a/docs/controls.md +++ b/docs/controls.md @@ -10,12 +10,12 @@ A few aspects of Element Call's interface can be controlled through a global API ## Audio output devices -These functions must be used in conjunction with the `controlledMediaDevices` URL parameter in order to have any effect. +On mobile platforms (iOS, Android), web views do not reliably support selecting audio output devices such as the main speaker, earpiece, or headset. To address this limitation, the following functions allow the hosting application (e.g., Element Web, Element X) to manage audio devices via exposed JavaScript interfaces. These functions must be enabled using the URL parameter `controlledAudioDevices` to take effect. -- `controls.setAvailableOutputDevices(devices: { id: string, name: string, forEarpiece?: boolean, isEarpiece?: boolean isSpeaker?: boolean, isExternalHeadset?, boolean; }[]): void` Sets the list of available audio outputs. `forEarpiece` is used on iOS only. +- `controls.setAvailableAudioDevices(devices: { id: string, name: string, forEarpiece?: boolean, isEarpiece?: boolean isSpeaker?: boolean, isExternalHeadset?, boolean; }[]): void` Sets the list of available audio outputs. `forEarpiece` is used on iOS only. It flags the device that should be used if the user selects earpiece mode. This should be the main stereo loudspeaker of the device. -- `controls.onOutputDeviceSelect: ((id: string) => void) | undefined` Callback called whenever the user or application selects a new audio output. -- `controls.setOutputDevice(id: string): void` Sets the selected audio device in Element Call's menu. This should be used if the OS decides to automatically switch to Bluetooth, for example. -- `controls.setOutputEnabled(enabled: boolean)` Enables/disables all audio output from the application. This can be useful for temporarily pausing audio while the controlling application is switching output devices. Output is enabled by default. -- `showNativeOutputDevicePicker: (() => void) | undefined`. Callback called whenever the user presses the output button in the settings menu. +- `controls.onAudioDeviceSelect: ((id: string) => void) | undefined` Callback called whenever the user or application selects a new audio output. +- `controls.setAudioDevice(id: string): void` Sets the selected audio device in Element Call's menu. This should be used if the OS decides to automatically switch to Bluetooth, for example. +- `controls.setAudioEnabled(enabled: boolean)` Enables/disables all audio output from the application. This can be useful for temporarily pausing audio while the controlling application is switching output devices. Output is enabled by default. +- `showNativeAudioDevicePicker: (() => void) | undefined`. Callback called whenever the user presses the output button in the settings menu. This button is only shown on iOS. (`userAgent.includes("iPhone")`) diff --git a/src/controls.ts b/src/controls.ts index f5c8c0f1..320f41ca 100644 --- a/src/controls.ts +++ b/src/controls.ts @@ -11,11 +11,21 @@ export interface Controls { canEnterPip(): boolean; enablePip(): void; disablePip(): void; + /** @deprecated use setAvailableAudioDevices instead*/ setAvailableOutputDevices(devices: OutputDevice[]): void; + setAvailableAudioDevices(devices: OutputDevice[]): void; + /** @deprecated use setAudioDevice instead*/ setOutputDevice(id: string): void; + setAudioDevice(id: string): void; + /** @deprecated use onAudioDeviceSelect instead*/ onOutputDeviceSelect?: (id: string) => void; + onAudioDeviceSelect?: (id: string) => void; + /** @deprecated use setAudioEnabled instead*/ setOutputEnabled(enabled: boolean): void; + setAudioEnabled(enabled: boolean): void; + /** @deprecated use showNativeAudioDevicePicker instead*/ showNativeOutputDevicePicker?: () => void; + showNativeAudioDevicePicker?: () => void; } export interface OutputDevice { @@ -43,7 +53,7 @@ export const outputDevice$ = new BehaviorSubject(undefined); * * This should also be used to display a darkened overlay screen letting the user know that audio is muted. */ -export const setOutputEnabled$ = new Subject(); +export const setAudioEnabled$ = new Subject(); window.controls = { canEnterPip(): boolean { @@ -57,17 +67,28 @@ window.controls = { if (!setPipEnabled$.observed) throw new Error("No call is running"); setPipEnabled$.next(false); }, - setAvailableOutputDevices(devices: OutputDevice[]): void { + setAvailableAudioDevices(devices: OutputDevice[]): void { availableOutputDevices$.next(devices); }, - setOutputDevice(id: string): void { + setAudioDevice(id: string): void { outputDevice$.next(id); }, - setOutputEnabled(enabled: boolean): void { - if (!setOutputEnabled$.observed) + setAudioEnabled(enabled: boolean): void { + if (!setAudioEnabled$.observed) throw new Error( - "Output controls are disabled. No setOutputEnabled$ observer", + "Output controls are disabled. No setAudioEnabled$ observer", ); - setOutputEnabled$.next(enabled); + setAudioEnabled$.next(enabled); + }, + + // wrappers for the deprecated controls fields + setOutputEnabled(enabled: boolean): void { + this.setAudioEnabled(enabled); + }, + setAvailableOutputDevices(devices: OutputDevice[]): void { + this.setAvailableAudioDevices(devices); + }, + setOutputDevice(id: string): void { + this.setAudioDevice(id); }, }; diff --git a/src/livekit/MediaDevicesContext.tsx b/src/livekit/MediaDevicesContext.tsx index de3c514c..32fda847 100644 --- a/src/livekit/MediaDevicesContext.tsx +++ b/src/livekit/MediaDevicesContext.tsx @@ -367,7 +367,11 @@ function useControlledOutput(): MediaDeviceHandle { // This information is probably only of interest if the earpiece mode has been // selected - for example, Element X iOS listens to this to determine whether it // should enable the proximity sensor. - if (selectedId) window.controls.onOutputDeviceSelect?.(selectedId); + if (selectedId) { + window.controls.onAudioDeviceSelect?.(selectedId); + // Call deprecated method for backwards compatibility. + window.controls.onOutputDeviceSelect?.(selectedId); + } setAsEarpiece(selectedId === EARPIECE_CONFIG_ID); }, [selectedId]); diff --git a/src/settings/SettingsModal.tsx b/src/settings/SettingsModal.tsx index e0324188..74307d02 100644 --- a/src/settings/SettingsModal.tsx +++ b/src/settings/SettingsModal.tsx @@ -133,6 +133,8 @@ export const SettingsModal: FC = ({