@capgo/capacitor-plugin-audiosession

Know when audio is interrupted or the output route changes on iOS, for example when headphones are plugged in, and switch output to the speaker. Keeps call, voice and media apps in control of sound.

🤖 Building with an AI coding agent? Install Capgo skills so Claude Code, Codex, Cursor, Copilot, or Gemini CLI know how to install and use @capgo/capacitor-audio-session in your Capacitor app: npx skills add Cap-go/capgo-skills. Then ask your agent: "Add @capgo/capacitor-audio-session to my Capacitor app and wire it up." Agent setup guides · Hosted MCP

Key features

• Current route: currentOutputs() returns the active audio outputs.
• Override output: overrideOutput() forces the speaker or returns to the default route.
• Route changes: the routeChanged event fires when headphones or other devices connect or disconnect.
• Interruptions: the interruption event fires when a call or another app interrupts audio.
• Platforms: iOS. iOS only. Android and web are stubs.

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.

Why Capacitor AudioSession?

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.

Documentation

The most complete doc is available here: https://capgo.app/docs/plugins/audiosession/

Compatibility

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.

Install

You can use our AI-Assisted Setup to install the plugin. Add the Capgo skills to your AI tool using the following command:

npx skills add https://github.com/cap-go/capacitor-skills --skill capacitor-plugins

Then use the following prompt:

Use the `capacitor-plugins` skill from `cap-go/capacitor-skills` to install the `@capgo/capacitor-audio-session` plugin in my project.

If you prefer Manual Setup, install the plugin by running the following commands and follow the platform-specific instructions below:

npm install @capgo/capacitor-plugin-audiosession
npx cap sync

For now this plugin works only in Capacitor 4.0+.

API

• 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()

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(...)

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.

Returns: Promise<OverrideResult>

addListener('routeChanged', ...)

addListener(eventName: 'routeChanged', listenerFunc: RouteChangeListener) => Promise<PluginListenerHandle>

Listen for audio route changes (e.g. headset connected/disconnected).

Returns: Promise<PluginListenerHandle>

addListener('interruption', ...)

addListener(eventName: 'interruption', listenerFunc: InterruptionListener) => Promise<PluginListenerHandle>

Listen for audio session interruptions (e.g. incoming call) and their end.

Returns: Promise<PluginListenerHandle>

getPluginVersion()

getPluginVersion() => Promise<{ version: string; }>

Get the native Capacitor plugin version

Returns: Promise<{ version: string; }>

Interfaces

PluginListenerHandle

Type Aliases

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

Enums

AudioSessionPorts

RouteChangeReasons

InterruptionTypes

License

MIT