@capgo/capacitor-audio-session

@capgo/capacitor-plugin-audiosession

➡️ Get Instant updates for your App with Capgo

Missing a feature? We’ll build the plugin for you 💪

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.

Install

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', ...)
• 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.

Param	Type	Description
type	OutputOverrideType	The desired output override type.

Returns: Promise<OverrideResult>

addListener('routeChanged', ...)

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('interruption', ...)

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>

Interfaces

PluginListenerHandle

Prop	Type
remove	() => Promise<void>

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

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'

License

MIT