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()
• overrideOutput(...)
• addListener('routeChanged', ...)
• addListener('interruption', ...)
• configure(...)
• Interfaces
• Type Aliases
• Enums

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

InterruptionTypes

| Members | Value | | ----------- | -------------------- | | BEGAN | 'began' | | ENDED | 'ended' |

License

MIT

Author

Martijn Swart https://studiokloek.nl

Based on work from: Saúl Ibarra Corretgé [email protected]