ios-audio-session

Capacitor Audio Session Plugin

A Capacitor plugin for iOS audio session management with comprehensive interruption handling.

Features

• Configure audio session for background playback
• Handle audio interruptions (calls, system alerts, etc.)
• Detect route changes (headphones plugged/unplugged)
• Background audio support
• TypeScript support

Installation

npm install ios-audio-session
npx cap sync

iOS Setup

Add background audio capability to your Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

Usage

import { AudioSession } from 'ios-audio-session';

// Configure the audio session
await AudioSession.configureAudioSession();

// Add listeners for interruptions
await AudioSession.addListeners();

// Listen for interruption events
AudioSession.addListener('audioInterruption', (event) => {
  if (event.type === 'began') {
    // Pause your audio
    console.log('Audio interrupted:', event.reason);
  } else if (event.type === 'ended' && event.options?.should_resume) {
    // Resume your audio
    console.log('Can resume audio');
  }
});

// Set audio session active/inactive
await AudioSession.setActive({ active: true });

API

configureAudioSession()

Configures the audio session for playback with background audio support.

await AudioSession.configureAudioSession();

addListeners()

Adds listeners for audio interruptions and route changes.

await AudioSession.addListeners();

removeAllListeners()

Removes all audio session listeners.

await AudioSession.removeAllListeners();

setActive(options)

Sets the audio session active or inactive.

await AudioSession.setActive({ active: true });

Event Listeners

audioInterruption

Fired when audio is interrupted or interruption ends.

AudioSession.addListener('audioInterruption', (event) => {
  console.log('Interruption event:', event);
});

Event object:

• type: 'began' | 'ended'
• reason: 'call' | 'app_suspended' | 'builtin_app' | 'system' | 'route_change' | 'category_change'
• options.should_resume: boolean (only for 'ended' events)

Platform Support

Platform	Status
iOS	✅
Android	❌
Web	⚠️ (stub implementation)

License

MIT