This plugin works on iOS only.
This plugin is a port of https://github.com/saghul/cordova-plugin-audioroute and allows iOS applications to get notified about audio session interruptions and route changes (for example when a headset is connected). To query and override the audio device in use is also supported.
The only free and maintained iOS audio session plugin for Capacitor:
- Audio route control - Detect and manage headphones, Bluetooth, speakers
- Interruption handling - Respond to phone calls, alarms, and other interruptions
- Output override - Force audio to speaker or restore default routing
- Same JavaScript API - Compatible interface with paid alternatives
- iOS-specific - Leverages AVAudioSession for deep iOS integration
Essential for VoIP apps, music players, podcast apps, and any app requiring precise audio routing control.
The most complete doc is available here: https://capgo.app/docs/plugins/audiosession/
npm install @capgo/capacitor-plugin-audiosession
npx cap syncFor now this plugin works only in Capacitor 4.0+.
currentOutputs()overrideOutput(...)addListener('routeChanged', ...)addListener('interruption', ...)getPluginVersion()- Interfaces
- Type Aliases
- Enums
iOS-only plugin to query and control the audio session output and listen to route changes and interruptions.
currentOutputs() => Promise<AudioSessionPorts[]>Get the current active audio output routes.
On web and non-iOS platforms, this resolves to an empty array.
Returns: Promise<AudioSessionPorts[]>
overrideOutput(type: OutputOverrideType) => Promise<OverrideResult>Override the current audio output route.
Use speaker to force playback through the built-in speaker, or
default to restore the system-selected route.
| Param | Type | Description |
|---|---|---|
type |
OutputOverrideType |
The desired output override type. |
Returns: Promise<OverrideResult>
addListener(eventName: 'routeChanged', listenerFunc: RouteChangeListener) => Promise<PluginListenerHandle>Listen for audio route changes (e.g. headset connected/disconnected).
| Param | Type | Description |
|---|---|---|
eventName |
'routeChanged' |
The route change event name. |
listenerFunc |
RouteChangeListener |
Callback invoked with the route change reason. |
Returns: Promise<PluginListenerHandle>
addListener(eventName: 'interruption', listenerFunc: InterruptionListener) => Promise<PluginListenerHandle>Listen for audio session interruptions (e.g. incoming call) and their end.
| Param | Type | Description |
|---|---|---|
eventName |
'interruption' |
The interruption event name. |
listenerFunc |
InterruptionListener |
Callback invoked with the interruption type. |
Returns: Promise<PluginListenerHandle>
getPluginVersion() => Promise<{ version: string; }>Get the native Capacitor plugin version
Returns: Promise<{ version: string; }>
| Prop | Type |
|---|---|
remove |
() => Promise<void> |
Result of an output override request.
{ success: boolean; message: string; }
Output override type.
default: Use the system-selected route.speaker: Force playback through the built-in speaker.
'default' | 'speaker'
Listener called when the audio route changes.
(reason: RouteChangeReasons): void
Listener called when the audio session is interrupted or ends.
(type: InterruptionTypes): void
| Members | Value |
|---|---|
AIR_PLAY |
'airplay' |
BLUETOOTH_LE |
'bluetooth-le' |
BLUETOOTH_HFP |
'bluetooth-hfp' |
BLUETOOTH_A2DP |
'bluetooth-a2dp' |
BUILT_IN_SPEAKER |
'builtin-speaker' |
BUILT_IN_RECEIVER |
'builtin-receiver' |
HDMI |
'hdmi' |
HEADPHONES |
'headphones' |
LINE_OUT |
'line-out' |
| Members | Value |
|---|---|
NEW_DEVICE_AVAILABLE |
'new-device-available' |
OLD_DEVICE_UNAVAILABLE |
'old-device-unavailable' |
CATEGORY_CHANGE |
'category-change' |
OVERRIDE |
'override' |
WAKE_FROM_SLEEP |
'wake-from-sleep' |
NO_SUITABLE_ROUTE_FOR_CATEGORY |
'no-suitable-route-for-category' |
ROUTE_CONFIGURATION_CHANGE |
'route-config-change' |
UNKNOWN |
'unknown' |
| Members | Value |
|---|---|
BEGAN |
'began' |
ENDED |
'ended' |
MIT