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

``typescript
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

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

For now this plugin works only in Capacitor 4.0+.

API

* currentOutputs()
* overrideOutput(...)
* addListener('routeChanged', ...)
* addListener('interruption', ...)
* configure(...)
* Interfaces
* Type Aliases
* Enums

$3

`typescript
currentOutputs() => Promise
`

Returns: Promise<AudioSessionPorts[]>

--------------------

$3

`typescript
overrideOutput(type: OutputOverrideType) => Promise
`

| Param | Type |
| ---------- | ----------------------------------------------------------------- |
| type | OutputOverrideType |

Returns: Promise<OverrideResult>

--------------------

$3

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

| Param | Type |
| ------------------ | ------------------------------------------------------------------- |
| eventName | 'routeChanged' |
| listenerFunc | RouteChangeListener |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

--------------------

$3

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

| Param | Type |
| ------------------ | --------------------------------------------------------------------- |
| eventName | 'interruption' |
| listenerFunc | InterruptionListener |

Returns: Promise<PluginListenerHandle> & PluginListenerHandle

--------------------

$3

`typescript
configure(options: AudioSessionOptions) => Promise
`

| Param | Type |
| ------------- | ------------------------------------------------------------------- |
| options | AudioSessionOptions |

--------------------

$3


#### PluginListenerHandle

| Prop | Type |
| ------------ | ----------------------------------------- |
| remove | () => Promise<void> |


#### AudioSessionOptions

| Prop | Type |
| ------------------------- | -------------------------------- |
| autoSwitchBluetooth | boolean |
| priorityOrder | AudioSessionPorts[] |

$3


#### OverrideResult

{ success: boolean; message: string; }


#### OutputOverrideType

'default' | 'speaker'


#### RouteChangeListener

(reason: RouteChangeReasons): void


#### InterruptionListener

(type: InterruptionTypes): void

$3


#### 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

Author

Martijn Swart

Based on work from: Saúl Ibarra Corretgé