This capacitor plugin allows iOS applications to get notified audio about interrupts & route changes (for example when a headset is connected), and also query and override the audio device in use.
npm install @capgo/capacitor-audio-session
This plugin works on iOS only.
This plugin is a port of
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/
| Plugin version | Capacitor compatibility | Maintained |
| -------------- | ----------------------- | ---------- |
| v8.\.\ | v8.\.\ | ✅ |
| v7.\.\ | v7.\.\ | On demand |
| v6.\.\ | v6.\.\ | ❌ |
| v5.\.\ | v5.\.\ | ❌ |
> Note: The major version of this plugin follows the major version of Capacitor. Use the version that matches your Capacitor installation (e.g., plugin v8 for Capacitor 8). Only the latest major version is actively maintained.
``bash`
npm install @capgo/capacitor-plugin-audiosession
npx cap sync
For 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.
`typescript`
currentOutputs() => Promise
Get the current active audio output routes.
On web and non-iOS platforms, this resolves to an empty array.
Returns: Promise<AudioSessionPorts[]>
--------------------
`typescript`
overrideOutput(type: OutputOverrideType) => Promise
Override the current audio output route.
Use speaker to force playback through the built-in speaker, ordefault to restore the system-selected route.
| Param | Type | Description |
| ---------- | ----------------------------------------------------------------- | --------------------------------- |
| type | OutputOverrideType | The desired output override type. |
Returns: Promise<OverrideResult>
--------------------
`typescript`
addListener(eventName: 'routeChanged', listenerFunc: RouteChangeListener) => Promise
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>
--------------------
`typescript`
addListener(eventName: 'interruption', listenerFunc: InterruptionListener) => Promise
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>
--------------------
`typescript`
getPluginVersion() => Promise<{ version: string; }>
Get the native Capacitor plugin version
Returns: Promise<{ version: string; }>
--------------------
#### PluginListenerHandle
| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |
#### OverrideResult
Result of an output override request.
{ success: boolean; message: string; }
#### OutputOverrideType
Output override type.
- default: Use the system-selected route.speaker
- : Force playback through the built-in speaker.
'default' | 'speaker'
#### RouteChangeListener
Listener called when the audio route changes.
(reason: RouteChangeReasons): void
#### InterruptionListener
Listener called when the audio session is interrupted or ends.
(type: InterruptionTypes): void
#### AudioSessionPorts
| 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' |
#### RouteChangeReasons
| 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' |
#### InterruptionTypes
| Members | Value |
| ----------- | -------------------- |
| BEGAN | 'began' |
| ENDED` | 'ended' |
MIT