@anuradev/capacitor-audio-session

Audio session and output routing for Capacitor.

The plugin requires Android 10 (API 29) or newer. It supports voice communication, media, and ringtone audio-focus policies. iOS and Web are not implemented.

Install

npm install @anuradev/capacitor-audio-session
npx cap sync

Usage

import { AudioSession } from '@anuradev/capacitor-audio-session';

const state = await AudioSession.activate({
  usage: 'voiceCommunication',
  output: 'earpiece',
});

await AudioSession.setOutput({ output: 'speaker' });
await AudioSession.deactivate();

media and ringtone use MODE_NORMAL and support only the system-selected output:

await AudioSession.activate({ usage: 'media' });
await AudioSession.deactivate();

await AudioSession.activate({ usage: 'ringtone' });
await AudioSession.deactivate();

The player that produces a ringtone must also use native ringtone audio attributes. The focus request made by this plugin does not change the attributes of an existing player.

API

activate(options: ActivateOptions): Promise<AudioSessionState>;
deactivate(): Promise<AudioSessionState>;
setOutput(options: SetOutputOptions): Promise<AudioSessionState>;
getState(): Promise<AudioSessionState>;
addListener(eventName: 'routeChanged', listener: (event: RouteChangedEvent) => void): Promise<PluginListenerHandle>;
addListener(eventName: 'interruption', listener: (event: InterruptionEvent) => void): Promise<PluginListenerHandle>;
removeAllListeners(): Promise<void>;

An active session cannot change its usage. Deactivate it before activating a different usage. earpiece and speaker outputs are only supported by voiceCommunication sessions.

An interruption with type: 'began' indicates an audio-focus loss. shouldResume is true for transient losses and false for permanent losses. A matching ended event is emitted if Android later restores focus.