Capacitor-plugin-audiosession-bluetooth NPM

capacitor-plugin-audiosession-bluetooth

This plugin works on iOS only.

This plugin is a fork of studiokloek/capacitor-plugin-audiosession (which is a port of cordova-plugin-audioroute) with additional features for automatic audio device switching. It provides:

Bluetooth device auto-switching support
Priority-based output device selection
Real-time audio route change detection
Customizable device priority order

Key Features

Automatically switches to connected Bluetooth devices
Configurable device priority (wired > Bluetooth > built-in speaker)
Handles audio interruptions and route changes
Supports iOS audio session management

Usage Example

import { AudioSession, AudioSessionPorts } from 'capacitor-plugin-audiosession-bluetooth';

// Configure on app startup
await AudioSession.configure({
  autoSwitchBluetooth: true,
  priorityOrder: [
    AudioSessionPorts.LINE_OUT, // Wired connection
    AudioSessionPorts.HEADPHONES, // Headphone jack
    AudioSessionPorts.BLUETOOTH_A2DP, // Bluetooth audio
    AudioSessionPorts.BLUETOOTH_HFP, // Bluetooth headset
    AudioSessionPorts.BLUETOOTH_LE, // Bluetooth Low Energy
    AudioSessionPorts.AIR_PLAY, // AirPlay
    AudioSessionPorts.BUILT_IN_SPEAKER, // Built-in speaker
  ],
});

// Listen for route changes
AudioSession.addListener('routeChanged', (reason) => {
  console.log('Audio route changed:', reason);
});

Key Features Demonstrated:

Automatic device switching based on priority
Real-time route change monitoring
Custom priority configuration

Install

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

For now this plugin works only in Capacitor 4.0+.

API

currentOutputs()

currentOutputs() => Promise<AudioSessionPorts[]>

Returns: Promise<AudioSessionPorts[]>

overrideOutput(...)

overrideOutput(type: OutputOverrideType) => Promise<OverrideResult>

Param	Type
`type`	OutputOverrideType

Returns: Promise<OverrideResult>

addListener('routeChanged', ...)

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

Param	Type
`eventName`	'routeChanged'
`listenerFunc`	RouteChangeListener

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

addListener('interruption', ...)

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

Param	Type
`eventName`	'interruption'
`listenerFunc`	InterruptionListener

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

configure(...)

configure(options: AudioSessionOptions) => Promise<void>

Param	Type
`options`	AudioSessionOptions

Interfaces

PluginListenerHandle

Prop	Type
`remove`	() => Promise<void>

AudioSessionOptions

Prop	Type
`autoSwitchBluetooth`	boolean
`priorityOrder`	AudioSessionPorts[]

Type Aliases

OverrideResult

{ success: boolean; message: string; }

OutputOverrideType

'default' | 'speaker'

RouteChangeListener

(reason: RouteChangeReasons): void

InterruptionListener

(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'