Getting Started

Copy a setup prompt with the install steps and the full markdown guide for this plugin.

        Set up this Capacitor plugin in the project.

Use the package manager already used by the project.
Install these package(s): `@capgo/capacitor-audio-session`, `@capgo/capacitor-audiosession`
Run the required Capacitor sync/update step after installation.
Read this markdown guide for the full setup steps: https://raw.githubusercontent.com/Cap-go/website/refs/heads/main/apps/docs/src/content/docs/docs/plugins/audiosession/getting-started.mdx
Use that guide for platform-specific steps, native file edits, permissions, config changes, imports, and usage setup.
If that guide references other docs pages, read them too.

Install

bun add @capgo/capacitor-audio-session
bunx cap sync

Import

import { AudioSession } from '@capgo/capacitor-audio-session';

API Overview

`currentOutputs`

Get the current active audio output routes.

On web and non-iOS platforms, this resolves to an empty array.

import { AudioSession } from '@capgo/capacitor-audio-session';

await AudioSession.currentOutputs();

`overrideOutput`

Override the current audio output route.

Use speaker to force playback through the built-in speaker, or default to restore the system-selected route.

import { AudioSession } from '@capgo/capacitor-audio-session';

await AudioSession.overrideOutput({} as OutputOverrideType);

Type Reference

`AudioSessionPorts`

Available audio output routes on iOS.

export enum AudioSessionPorts {
  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',
}

`OutputOverrideType`

Output override type. - default: Use the system-selected route. - speaker: Force playback through the built-in speaker.

export type OutputOverrideType = 'default' | 'speaker';

`OverrideResult`

Result of an output override request.

export type OverrideResult = {
  success: boolean;
  message: string;
};

`RouteChangeListener`

Listener called when the audio route changes.

export type RouteChangeListener = (reason: RouteChangeReasons) => void;

`InterruptionListener`

Listener called when the audio session is interrupted or ends.

export type InterruptionListener = (type: InterruptionTypes) => void;

`RouteChangeReasons`

export enum RouteChangeReasons {
  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`

export enum InterruptionTypes {
  BEGAN = 'began',
  ENDED = 'ended',
}

Source Of Truth

This page is generated from the plugin’s src/definitions.ts. Re-run the sync when the public API changes upstream.