ios-audio-routing

Fix web audio routing on iOS. Makes web apps behave like native apps for audio output (AirPods, Bluetooth speakers, etc.).

The Problem

Web apps on iOS don't get proper audio routing. Native apps use AVAudioSession to signal that they're media apps, so iOS routes audio correctly. Web apps can't access this API, so:

• Audio may not route to Bluetooth devices
• Audio may cut out when the app is backgrounded
• Your app doesn't appear in Control Center

This is an iOS platform limitation, not a browser bug.

The Fix

This library tricks iOS into treating your web app like a native media app:

1. Plays inaudible audio through an <audio> element (activates iOS audio routing)
2. Registers with the Media Session API (makes app appear in Control Center)
3. Reclaims audio routing when returning from background

Install

npm install ios-audio-routing

Usage

import { initIOSAudioSession, wakeUp, setPlaying, setPaused, cleanup } from 'ios-audio-routing';

// Initialize on first user interaction (required by iOS)
button.addEventListener('click', async () => {
  await initIOSAudioSession({
    title: 'My App',
    artist: 'Audio Player',
    onPlay: () => resumePlayback(),
    onPause: () => pausePlayback(),
  });
});

// Before playing audio, ensure routing is active
await wakeUp();
playMyAudio();
setPlaying();

// When paused
setPaused();

// On unmount
cleanup();

API

initIOSAudioSession(options?)

Initialize the audio session. Call from a user gesture.

interface AudioSessionOptions {
  title?: string;      // Control Center title
  artist?: string;     // Control Center artist
  album?: string;      // Control Center album
  artwork?: MediaImage[];
  onPlay?: () => void; // Control Center play button
  onPause?: () => void;
}

wakeUp()

Reclaim audio routing. Call before playing audio, especially after backgrounding.

setPlaying() / setPaused()

Update Control Center playback state.

updateMetadata(metadata)

Update Control Center display.

cleanup()

Remove event listeners and DOM elements.

isIOS() / isInitialized()

Utility functions.

How It Works

iOS requires AVAudioSession to properly route audio to Bluetooth devices. Since web apps can't access this API, we use a workaround:

• An <audio> element playing a silent MP3 at very low volume activates the iOS audio route
• The Media Session API registers the app with Control Center
• A visibility change listener reclaims routing when returning from background

The silent audio is inaudible (0.01 volume, ~0.5s duration) but tricks iOS into activating proper audio routing.

Requirements

• iOS Safari or iOS WebView (PWA)
• User gesture required for initialization (iOS restriction)

No-ops gracefully on non-iOS platforms.

License

MIT