Skip to main content
@capgo/capacitor-audio-session Media Open source

Audio Session Capacitor plugin

Configure iOS audio session for background playback, mixing, and routing control

Install

bun add @capgo/capacitor-audio-session bunx cap sync
npm, pnpm or yarn
  • npm install @capgo/capacitor-audio-session
  • pnpm add @capgo/capacitor-audio-session
  • yarn add @capgo/capacitor-audio-session

Guide

How to use Audio Session in Capacitor

Test on device

Download the Capgo app, then scan the QR code.

App Store Google Play
Audio Session plugin preview QR code

Using @capgo/capacitor-audio-session

iOS-only plugin to query and control the audio session output and listen to route changes and interruptions.

Install

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

bunx cap sync copies the plugin's native code into your native projects. Run it again after every plugin upgrade.

Import

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

API at a glance

Method Description
currentOutputs Get the current active audio output routes.
overrideOutput Override the current audio output route.

Examples

currentOutputs()

Get the current active audio output routes.

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

const result = await AudioSession.currentOutputs();
console.log(result);

overrideOutput()

Override the current audio output route.

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

const result = await AudioSession.overrideOutput('default');
console.log(result);

Listen to events

addListener returns a handle. Call handle.remove() when the screen unmounts.

Full reference

Keep going from Using @capgo/capacitor-audio-session

If you are using Using @capgo/capacitor-audio-session to plan native media and interface behavior, connect it with @capgo/capacitor-audio-session for the implementation detail in @capgo/capacitor-audio-session, Getting Started for the implementation detail in Getting Started, Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities for the implementation detail in @capgo/capacitor-live-activities, and Using @capgo/capacitor-video-player for the native capability in Using @capgo/capacitor-video-player.

FAQ

Audio Session plugin FAQ

How do I install the Audio Session plugin in a Capacitor app?

Run "bun add @capgo/capacitor-audio-session" (or "npm install @capgo/capacitor-audio-session"), then run "bunx cap sync" so the iOS and Android projects pick up the native code. Import it from "@capgo/capacitor-audio-session" in your app code.

Does @capgo/capacitor-audio-session work with React, Vue and Angular?

Yes. Audio Session is a Capacitor package, so it works with any web framework that runs inside Capacitor, including Ionic, React, Vue, Angular, Svelte and plain JavaScript.

Which Capacitor version does @capgo/capacitor-audio-session support?

Capgo plugins follow Capacitor's major version: use the plugin major version that matches your Capacitor major version (for example plugin v8 with Capacitor 8). The compatibility table in the GitHub README lists the maintained versions.

Is @capgo/capacitor-audio-session free and open source?

Yes. The source code is public on GitHub at https://github.com/Cap-go/capacitor-audiosession/ and the package is free to install from npm. Bug reports and pull requests are welcome.

Can I update code that uses Audio Session without an App Store review?

Installing or upgrading the plugin changes native code, so it needs a new store build. After that, JavaScript, HTML and CSS changes that call the plugin can ship instantly with Capgo live updates.

Media

Related plugins

Browse all plugins →

Ship Audio Session changes without waiting for app review

Once the plugin is in your store build, Capgo live updates push your JavaScript, HTML and CSS changes to users in minutes.

Start with Capgo