--- description: Capacitor plugin to configure and observe the iOS audio session. Set the category, mode, and options, route audio output, and listen for interruptions. title: Capacitor Audio Session Plugin for iOS - Capawesome image: https://capawesome.io/docs/assets/images/social/sdks/capacitor/audio-session.png --- [Skip to content ](#capacitor-audio-session-plugin) [πŸ“² Introducing **Build Sharing** β€” get your builds onto testers' devices with a link & QR code. No account required. ](/blog/share-mobile-app-builds-with-testers/) * [ SDKs ](/docs/sdks/) * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Session Ownership ](#session-ownership) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) * [ Background Task ](/docs/sdks/capacitor/background-task/) * [ Badge ](/docs/sdks/capacitor/badge/) * [ Barometer ](/docs/sdks/capacitor/barometer/) * [ Battery ](/docs/sdks/capacitor/battery/) * [ Biometrics ](/docs/sdks/capacitor/biometrics/) * [ Bluetooth Low Energy ](/docs/sdks/capacitor/bluetooth-low-energy/) * [ Clipboard ](/docs/sdks/capacitor/clipboard/) * [ Cloudinary ](/docs/sdks/capacitor/cloudinary/) * [ Compass ](/docs/sdks/capacitor/compass/) * [ Contacts ](/docs/sdks/capacitor/contacts/) * [ Crisp ](/docs/sdks/capacitor/crisp/) * [ Datetime Picker ](/docs/sdks/capacitor/datetime-picker/) * [ Device Info ](/docs/sdks/capacitor/device-info/) * [ Dialog ](/docs/sdks/capacitor/dialog/) * [ Electron ](/docs/sdks/capacitor/electron/) * [ Exif ](/docs/sdks/capacitor/exif/) * [ Facebook Sign-In ](/docs/sdks/capacitor/facebook-sign-in/) * [ File Compressor ](/docs/sdks/capacitor/file-compressor/) * [ File Opener ](/docs/sdks/capacitor/file-opener/) * [ File Picker ](/docs/sdks/capacitor/file-picker/) * [ Firebase ](/docs/sdks/capacitor/firebase/) * [ Formbricks ](/docs/sdks/capacitor/formbricks/) * [ Geocoder ](/docs/sdks/capacitor/geocoder/) * [ Google Sign-In ](/docs/sdks/capacitor/google-sign-in/) * [ Grafana Faro ](/docs/sdks/capacitor/grafana-faro/) * [ Gyroscope ](/docs/sdks/capacitor/gyroscope/) * [ Haptics ](/docs/sdks/capacitor/haptics/) * [ Home Indicator ](/docs/sdks/capacitor/home-indicator/) * [ In-App Browser ](/docs/sdks/capacitor/in-app-browser/) * [ Install Referrer ](/docs/sdks/capacitor/install-referrer/) * [ Intercom ](/docs/sdks/capacitor/intercom/) * [ Intune ](/docs/sdks/capacitor/intune/) * [ Keep Awake ](/docs/sdks/capacitor/keep-awake/) * [ libSQL ](/docs/sdks/capacitor/libsql/) * [ Light Sensor ](/docs/sdks/capacitor/light-sensor/) * [ Live Update ](/docs/sdks/capacitor/live-update/) * [ Localization ](/docs/sdks/capacitor/localization/) * [ Mail Composer ](/docs/sdks/capacitor/mail-composer/) * [ Managed Configurations ](/docs/sdks/capacitor/managed-configurations/) * [ Maps Launcher ](/docs/sdks/capacitor/maps-launcher/) * [ Media Session ](/docs/sdks/capacitor/media-session/) * [ ML Kit ](/docs/sdks/capacitor/mlkit/) * [ Navigation Bar ](/docs/sdks/capacitor/navigation-bar/) * [ Network ](/docs/sdks/capacitor/network/) * [ NFC ](/docs/sdks/capacitor/nfc/) * [ Node.js ](/docs/sdks/capacitor/nodejs/) * [ OAuth ](/docs/sdks/capacitor/oauth/) * [ Passkeys ](/docs/sdks/capacitor/passkeys/) * [ Password Autofill ](/docs/sdks/capacitor/password-autofill/) * [ PDF Generator ](/docs/sdks/capacitor/pdf-generator/) * [ PDF Viewer ](/docs/sdks/capacitor/pdf-viewer/) * [ Pedometer ](/docs/sdks/capacitor/pedometer/) * [ Permissions ](/docs/sdks/capacitor/permissions/) * [ Phone Dialer ](/docs/sdks/capacitor/phone-dialer/) * [ Photo Editor ](/docs/sdks/capacitor/photo-editor/) * [ Photo Manipulator ](/docs/sdks/capacitor/photo-manipulator/) * [ PixLive ](/docs/sdks/capacitor/pixlive/) * [ PostHog ](/docs/sdks/capacitor/posthog/) * [ Printer ](/docs/sdks/capacitor/printer/) * [ Privacy Screen ](/docs/sdks/capacitor/privacy-screen/) * [ Proximity Sensor ](/docs/sdks/capacitor/proximity-sensor/) * [ Purchases ](/docs/sdks/capacitor/purchases/) * [ RealtimeKit ](/docs/sdks/capacitor/realtimekit/) * [ Root Detection ](/docs/sdks/capacitor/root-detection/) * [ Screen Brightness ](/docs/sdks/capacitor/screen-brightness/) * [ Screen Orientation ](/docs/sdks/capacitor/screen-orientation/) * [ Screen Reader ](/docs/sdks/capacitor/screen-reader/) * [ Screenshot ](/docs/sdks/capacitor/screenshot/) * [ Secure Preferences ](/docs/sdks/capacitor/secure-preferences/) * [ Settings Launcher ](/docs/sdks/capacitor/settings-launcher/) * [ Shake ](/docs/sdks/capacitor/shake/) * [ Silent Mode ](/docs/sdks/capacitor/silent-mode/) * [ SIM ](/docs/sdks/capacitor/sim/) * [ SMS Composer ](/docs/sdks/capacitor/sms-composer/) * [ Speech Recognition ](/docs/sdks/capacitor/speech-recognition/) * [ Speech Synthesis ](/docs/sdks/capacitor/speech-synthesis/) * [ Share Target ](/docs/sdks/capacitor/share-target/) * [ Square Mobile Payments ](/docs/sdks/capacitor/square-mobile-payments/) * [ SQLite ](/docs/sdks/capacitor/sqlite/) * [ Superwall ](/docs/sdks/capacitor/superwall/) * [ System WebView ](/docs/sdks/capacitor/system-webview/) * [ Tauri ](/docs/sdks/capacitor/tauri/) * [ Text Interaction ](/docs/sdks/capacitor/text-interaction/) * [ Text Zoom ](/docs/sdks/capacitor/text-zoom/) * [ Thermal State ](/docs/sdks/capacitor/thermal-state/) * [ Toast ](/docs/sdks/capacitor/toast/) * [ Torch ](/docs/sdks/capacitor/torch/) * [ Vault ](/docs/sdks/capacitor/vault/) * [ Volume ](/docs/sdks/capacitor/volume/) * [ Wallet ](/docs/sdks/capacitor/wallet/) * [ Wifi ](/docs/sdks/capacitor/wifi/) * [ YouTube Player ](/docs/sdks/capacitor/youtube-player/) * [ Zip ](/docs/sdks/capacitor/zip/) * [ Cordova ](/docs/sdks/cordova/) * [ Cloud ](/docs/cloud/) * [ Integrations ](/docs/cloud/live-updates/integrations/) * Concepts * Reference * [ Troubleshooting ](/docs/cloud/live-updates/troubleshooting/) * [ FAQ ](/docs/cloud/live-updates/faq/) * [ Native Builds ](/docs/cloud/native-builds/) * [ Set Up Environments ](/docs/cloud/native-builds/environments/) * [ Overwrite Native Configurations ](/docs/cloud/native-builds/native-configurations/) * [ Auto-Increment Build Numbers ](/docs/cloud/native-builds/auto-incrementing-build-numbers/) * [ Configure the Web Build Script ](/docs/cloud/native-builds/web-build-script/) * [ Build from a Monorepo ](/docs/cloud/native-builds/monorepo/) * [ Use pnpm, Yarn, or bun ](/docs/cloud/native-builds/package-managers/) * [ Install Private npm Packages ](/docs/cloud/native-builds/npm-private-registry/) * [ Override the Java Version ](/docs/cloud/native-builds/override-java-version/) * [ Custom iOS Provisioning Profiles ](/docs/cloud/native-builds/custom-ios-provisioning-profiles/) * [ Build without Git ](/docs/cloud/native-builds/build-without-git/) * [ Access Git Behind a Firewall ](/docs/cloud/native-builds/firewall-access/) * [ Integrations ](/docs/cloud/native-builds/integrations/) * Reference * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ FAQ ](/docs/cloud/native-builds/faq/) * [ App Store Publishing ](/docs/cloud/app-store-publishing/) * [ Submit a Build ](/docs/cloud/app-store-publishing/submit-a-build/) * [ Submit Automatically After a Build ](/docs/cloud/app-store-publishing/submit-automatically/) * [ Troubleshooting ](/docs/cloud/app-store-publishing/troubleshooting/) * [ FAQ ](/docs/cloud/app-store-publishing/faq/) * [ Automations ](/docs/cloud/automations/) * [ Reference ](/docs/cloud/automations/reference/) * [ Troubleshooting ](/docs/cloud/automations/troubleshooting/) * [ FAQ ](/docs/cloud/automations/faq/) * [ Assist ](/docs/cloud/assist/) * [ CLI ](/docs/cloud/cli/) * APIs and SDKs * [ Webhooks ](/docs/cloud/webhooks/) * [ Integrations ](/docs/cloud/integrations/) * Notifications * Account * [ Organization ](/docs/cloud/organizations/) * [ Two-Factor Enforcement ](/docs/cloud/organizations/two-factor-authentication/) * [ Audit Logs ](/docs/cloud/organizations/audit-logs/) * [ Billing ](/docs/cloud/organizations/billing/) * [ License Keys ](/docs/cloud/license-keys/) * [ AI ](/docs/ai/) * [ Insiders ](/docs/insiders/) * [ Billing & Plans ](/docs/insiders/billing-and-plans/) * [ FAQ ](/docs/insiders/faq/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/support/) * [ Contributing ](/docs/contributing/) * Contributing code * [ Code of Conduct ](/docs/contributing/code-of-conduct/) * [ Questions ](https://docs.github.com/en/discussions/collaborating-with-your-community-using-discussions/participating-in-a-discussion#creating-a-discussion) * [ Blog ](/blog/) * Categories * [ API ](#api) * [ Type Aliases ](#type-aliases) * [ Session Ownership ](#session-ownership) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ License ](#license) # Capacitor Audio Session Plugin[ΒΆ](#capacitor-audio-session-plugin "Permanent link") Capacitor plugin to configure and observe the iOS [audio session](https://developer.apple.com/documentation/avfaudio/avaudiosession). [ ![Deliver Live Updates to your Capacitor app with Capawesome Cloud](../../../assets/external/cloud.capawesome.io/assets/banners/cloud-build-and-deploy-capacitor-apps.69628c3f.png) ](https://cloud.capawesome.io/) ## Features[ΒΆ](#features "Permanent link") The Capacitor Audio Session plugin is one of the most complete audio session management solutions for Capacitor apps. Here are some of the key features: * πŸŽ›οΈ **Configuration**: Set the audio session category, mode and options. * πŸ”Œ **Activation**: Activate and deactivate the audio session. * πŸ”Š **Output routing**: Read the current audio outputs and override the output port. * πŸ“‘ **Events**: Observe interruption and route change events. * 🀝 **Compatibility**: Works alongside the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) and [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) plugins. * πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * πŸ” **Up-to-date**: Always supports the latest Capacitor version. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## Use Cases[ΒΆ](#use-cases "Permanent link") The Audio Session plugin is typically used whenever an app needs fine-grained control over how audio behaves on iOS, for example: * **Media playback apps**: Configure the `playback` category so audio keeps playing while other apps are silenced. * **Voice and video chat**: Switch between the receiver and the built-in speaker using the output override. * **Mixing with other apps**: Let your audio play alongside (or duck) audio from other apps using the category options. * **Handling phone calls**: Pause playback when the session is interrupted and resume it when the interruption ends. * **Headphone awareness**: React when headphones or Bluetooth devices are plugged in or out by observing route changes. ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 0.x.x | \>=8.x.x | Active support | ## Installation[ΒΆ](#installation "Permanent link") You can use our **AI-Assisted Setup** to install the plugin. Add the [Capawesome Skills](https://github.com/capawesome-team/skills) to your AI tool using the following command: `[](#%5F%5Fcodelineno-0-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-1-1) Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome/capacitor-audio-session` plugin in my project. `` If you prefer **Manual Setup**, install the plugin by running the following commands and follow the platform-specific instructions below: `[](#%5F%5Fcodelineno-2-1)npm install @capawesome/capacitor-audio-session [](#%5F%5Fcodelineno-2-2)npx cap sync ` This plugin is only available on **iOS**. On Android and Web, all methods reject as unimplemented. ## Configuration[ΒΆ](#configuration "Permanent link") No configuration required for this plugin. ## Usage[ΒΆ](#usage "Permanent link") The following examples show how to configure the audio session, activate or deactivate it, read the current audio outputs, route playback to the built-in speaker, listen for interruptions and route changes, and remove all listeners. ### Configure the audio session[ΒΆ](#configure-the-audio-session "Permanent link") Set the audio session category, mode and options, for example for movie playback that interrupts audio from other apps. All methods of this plugin are only available on iOS: `[](#%5F%5Fcodelineno-3-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-3-2) [](#%5F%5Fcodelineno-3-3)const configure = async () => { [](#%5F%5Fcodelineno-3-4) await AudioSession.configure({ [](#%5F%5Fcodelineno-3-5) category: 'playback', [](#%5F%5Fcodelineno-3-6) mode: 'moviePlayback', [](#%5F%5Fcodelineno-3-7) options: { [](#%5F%5Fcodelineno-3-8) mixWithOthers: false, [](#%5F%5Fcodelineno-3-9) }, [](#%5F%5Fcodelineno-3-10) }); [](#%5F%5Fcodelineno-3-11)}; ` ### Activate or deactivate the audio session[ΒΆ](#activate-or-deactivate-the-audio-session "Permanent link") Activate the audio session before playing or recording audio, and deactivate it when you are done so that other apps can resume their playback: `[](#%5F%5Fcodelineno-4-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3)const setActive = async () => { [](#%5F%5Fcodelineno-4-4) await AudioSession.setActive({ active: true }); [](#%5F%5Fcodelineno-4-5)}; ` ### Read the current audio outputs[ΒΆ](#read-the-current-audio-outputs "Permanent link") Get the audio outputs of the current audio route, for example to check whether headphones are connected: `[](#%5F%5Fcodelineno-5-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-5-2) [](#%5F%5Fcodelineno-5-3)const getCurrentOutputs = async () => { [](#%5F%5Fcodelineno-5-4) const { outputs } = await AudioSession.getCurrentOutputs(); [](#%5F%5Fcodelineno-5-5) return outputs; [](#%5F%5Fcodelineno-5-6)}; ` ### Route playback to the built-in speaker[ΒΆ](#route-playback-to-the-built-in-speaker "Permanent link") Override the audio output port that is used for playback, for example to switch from the receiver to the loudspeaker during a call: `[](#%5F%5Fcodelineno-6-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const overrideOutput = async () => { [](#%5F%5Fcodelineno-6-4) await AudioSession.overrideOutput({ type: 'speaker' }); [](#%5F%5Fcodelineno-6-5)}; ` ### Listen for interruptions[ΒΆ](#listen-for-interruptions "Permanent link") Get notified when the audio session is interrupted, e.g. by an incoming phone call. The `shouldResume` flag tells you whether playback should resume after the interruption ended: `[](#%5F%5Fcodelineno-7-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const addInterruptionListener = async () => { [](#%5F%5Fcodelineno-7-4) await AudioSession.addListener('interruption', event => { [](#%5F%5Fcodelineno-7-5) console.log('Interruption:', event.type, event.shouldResume); [](#%5F%5Fcodelineno-7-6) }); [](#%5F%5Fcodelineno-7-7)}; ` ### Listen for route changes[ΒΆ](#listen-for-route-changes "Permanent link") Get notified when the audio route changes, e.g. when headphones are plugged in or out: `[](#%5F%5Fcodelineno-8-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const addRouteChangeListener = async () => { [](#%5F%5Fcodelineno-8-4) await AudioSession.addListener('routeChange', event => { [](#%5F%5Fcodelineno-8-5) console.log('Route change:', event.reason, event.outputs); [](#%5F%5Fcodelineno-8-6) }); [](#%5F%5Fcodelineno-8-7)}; ` ### Remove all listeners[ΒΆ](#remove-all-listeners "Permanent link") Remove all listeners that were registered for this plugin: `[](#%5F%5Fcodelineno-9-1)import { AudioSession } from '@capawesome/capacitor-audio-session'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const removeAllListeners = async () => { [](#%5F%5Fcodelineno-9-4) await AudioSession.removeAllListeners(); [](#%5F%5Fcodelineno-9-5)}; ` ## API[ΒΆ](#api "Permanent link") * [configure(...)](#configure) * [getCurrentOutputs()](#getcurrentoutputs) * [overrideOutput(...)](#overrideoutput) * [setActive(...)](#setactive) * [addListener('interruption', ...)](#addlistenerinterruption-) * [addListener('routeChange', ...)](#addlistenerroutechange-) * [removeAllListeners()](#removealllisteners) * [Interfaces](#interfaces) * [Type Aliases](#type-aliases) ### configure(...)[ΒΆ](#configure "Permanent link") `[](#%5F%5Fcodelineno-10-1)configure(options: ConfigureOptions) => Promise ` Configure the audio session category, mode and options. Only available on iOS. | Param | Type | | ----------- | ------------------------------------- | | **options** | [ConfigureOptions](#configureoptions) | **Since:** 0.1.0 --- ### getCurrentOutputs()[ΒΆ](#getcurrentoutputs "Permanent link") `[](#%5F%5Fcodelineno-11-1)getCurrentOutputs() => Promise ` Get the audio outputs of the current audio route. Only available on iOS. **Returns:** `Promise<[GetCurrentOutputsResult](#getcurrentoutputsresult)>` **Since:** 0.1.0 --- ### overrideOutput(...)[ΒΆ](#overrideoutput "Permanent link") `[](#%5F%5Fcodelineno-12-1)overrideOutput(options: OverrideOutputOptions) => Promise ` Override the audio output port that is used for playback. Only available on iOS. | Param | Type | | ----------- | ----------------------------------------------- | | **options** | [OverrideOutputOptions](#overrideoutputoptions) | **Since:** 0.1.0 --- ### setActive(...)[ΒΆ](#setactive "Permanent link") `[](#%5F%5Fcodelineno-13-1)setActive(options: SetActiveOptions) => Promise ` Activate or deactivate the audio session. Only available on iOS. | Param | Type | | ----------- | ------------------------------------- | | **options** | [SetActiveOptions](#setactiveoptions) | **Since:** 0.1.0 --- ### addListener('interruption', ...)[ΒΆ](#addlistenerinterruption "Permanent link") `[](#%5F%5Fcodelineno-14-1)addListener(eventName: 'interruption', listenerFunc: (event: InterruptionEvent) => void) => Promise ` Called when the audio session is interrupted, e.g. by an incoming phone call. Only available on iOS. | Param | Type | | ---------------- | -------------------------------------------------------- | | **eventName** | 'interruption' | | **listenerFunc** | (event: [InterruptionEvent](#interruptionevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.1.0 --- ### addListener('routeChange', ...)[ΒΆ](#addlistenerroutechange "Permanent link") `[](#%5F%5Fcodelineno-15-1)addListener(eventName: 'routeChange', listenerFunc: (event: RouteChangeEvent) => void) => Promise ` Called when the audio route changes, e.g. when headphones are plugged in or out. Only available on iOS. | Param | Type | | ---------------- | ------------------------------------------------------ | | **eventName** | 'routeChange' | | **listenerFunc** | (event: [RouteChangeEvent](#routechangeevent)) => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.1.0 --- ### removeAllListeners()[ΒΆ](#removealllisteners "Permanent link") `[](#%5F%5Fcodelineno-16-1)removeAllListeners() => Promise ` Remove all listeners for this plugin. Only available on iOS. **Since:** 0.1.0 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### ConfigureOptions[ΒΆ](#configureoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------ | ----------------------------------------------------------- | ----------------------------------- | --------- | ----- | | **category** | [AudioSessionCategory](#audiosessioncategory) | The audio session category. | | 0.1.0 | | **mode** | [AudioSessionMode](#audiosessionmode) | The audio session mode. | 'default' | 0.1.0 | | **options** | [AudioSessionCategoryOptions](#audiosessioncategoryoptions) | The audio session category options. | | 0.1.0 | #### AudioSessionCategoryOptions[ΒΆ](#audiosessioncategoryoptions "Permanent link") | Prop | Type | Description | Default | Since | | ---------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------- | ----- | | **allowAirPlay** | boolean | Whether AirPlay devices can be used for output. | false | 0.1.0 | | **allowBluetooth** | boolean | Whether Bluetooth hands-free devices can be used for input and output. | false | 0.1.0 | | **allowBluetoothA2DP** | boolean | Whether Bluetooth A2DP devices can be used for output. | false | 0.1.0 | | **defaultToSpeaker** | boolean | Whether audio is routed to the built-in speaker instead of the receiver when no other audio route is connected. | false | 0.1.0 | | **duckOthers** | boolean | Whether audio from other sessions is reduced in volume (ducked) while audio from this session plays. | false | 0.1.0 | | **interruptSpokenAudioAndMixWithOthers** | boolean | Whether audio from other sessions using the spokenAudio mode is interrupted and audio from this session is mixed with the remaining audio. | false | 0.1.0 | | **mixWithOthers** | boolean | Whether audio from this session mixes with audio from other active sessions instead of interrupting them. | false | 0.1.0 | #### GetCurrentOutputsResult[ΒΆ](#getcurrentoutputsresult "Permanent link") | Prop | Type | Description | Since | | ----------- | ---------------------- | --------------------------------------------- | ----- | | **outputs** | AudioSessionOutput\[\] | The audio outputs of the current audio route. | 0.1.0 | #### AudioSessionOutput[ΒΆ](#audiosessionoutput "Permanent link") | Prop | Type | Description | Since | | ------------ | ------ | ------------------------------------------------- | ----- | | **portName** | string | The human-readable name of the audio output port. | 0.1.0 | | **portType** | string | The type of the audio output port. | 0.1.0 | #### OverrideOutputOptions[ΒΆ](#overrideoutputoptions "Permanent link") | Prop | Type | Description | Since | | -------- | ----------------------------------------- | ------------------------------------------- | ----- | | **type** | [OverrideOutputType](#overrideoutputtype) | The audio output port to route playback to. | 0.1.0 | #### SetActiveOptions[ΒΆ](#setactiveoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------------------------ | ------- | -------------------------------------------------------------------------------------------------------- | ------- | ----- | | **active** | boolean | Whether the audio session should be activated (true) or deactivated (false). | | 0.1.0 | | **notifyOthersOnDeactivation** | boolean | Whether other audio sessions are notified when this session is deactivated, so they can resume playback. | true | 0.1.0 | #### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link") | Prop | Type | | ---------- | ------------------- | | **remove** | () => Promise | #### InterruptionEvent[ΒΆ](#interruptionevent "Permanent link") | Prop | Type | Description | Since | | ---------------- | ------------------------------------- | ---------------------------------------------------------------------------------------- | ----- | | **shouldResume** | boolean | Whether playback should resume after the interruption ended. Only true if type is ended. | 0.1.0 | | **type** | [InterruptionType](#interruptiontype) | The type of the interruption. | 0.1.0 | #### RouteChangeEvent[ΒΆ](#routechangeevent "Permanent link") | Prop | Type | Description | Since | | ----------- | --------------------------------------- | ------------------------------------------------------ | ----- | | **outputs** | AudioSessionOutput\[\] | The audio outputs of the audio route after the change. | 0.1.0 | | **reason** | [RouteChangeReason](#routechangereason) | The reason why the audio route changed. | 0.1.0 | ### Type Aliases[ΒΆ](#type-aliases "Permanent link") #### AudioSessionCategory[ΒΆ](#audiosessioncategory "Permanent link") The audio session category. `'ambient' | 'multiRoute' | 'playAndRecord' | 'playback' | 'record' | 'soloAmbient'` #### AudioSessionMode[ΒΆ](#audiosessionmode "Permanent link") The audio session mode. `'default' | 'gameChat' | 'measurement' | 'moviePlayback' | 'spokenAudio' | 'videoChat' | 'videoRecording' | 'voiceChat' | 'voicePrompt'` #### OverrideOutputType[ΒΆ](#overrideoutputtype "Permanent link") The audio output port to route playback to. `'default' | 'speaker'` #### InterruptionType[ΒΆ](#interruptiontype "Permanent link") The type of an audio session interruption. `'began' | 'ended'` #### RouteChangeReason[ΒΆ](#routechangereason "Permanent link") The reason why the audio route changed. `'categoryChange' | 'newDeviceAvailable' | 'noSuitableRouteForCategory' | 'oldDeviceUnavailable' | 'override' | 'routeConfigurationChange' | 'unknown' | 'wakeFromSleep'` ## Session Ownership[ΒΆ](#session-ownership "Permanent link") The audio session returned by [AVAudioSession.sharedInstance()](https://developer.apple.com/documentation/avfaudio/avaudiosession) is a **single, app-wide** object. This plugin gives you **manual** control over it, but so do other audio-related plugins (such as the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/), [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) and Speech Recognition plugins) and the underlying platform APIs they use. Because the session is shared, the **last write wins**: calling `configure(...)` may override the category, mode or options that another plugin has set, and vice versa. This plugin cannot prevent that. If you combine this plugin with other audio plugins, make sure to reconfigure the session whenever you switch between playback, recording and other audio scenarios. ## FAQ[ΒΆ](#faq "Permanent link") ### How is this plugin different from other similar plugins?[ΒΆ](#how-is-this-plugin-different-from-other-similar-plugins "Permanent link") It gives you fine-grained control over the iOS audio session through one fully typed API: set the category, mode and options, activate or deactivate the session, read the current outputs and override the output route, and observe interruption and route-change events. It documents the shared, app-wide nature of the audio session honestly, so you know exactly how it behaves alongside other audio code, and it's actively maintained against the latest Capacitor and iOS versions. If you only play a simple sound, a basic setup is enough; if you need precise session control, this plugin is designed for exactly that. ### Is this plugin available on Android or the Web?[ΒΆ](#is-this-plugin-available-on-android-or-the-web "Permanent link") No, this plugin is only available on iOS since it controls the iOS-specific [audio session](https://developer.apple.com/documentation/avfaudio/avaudiosession). On Android and Web, all methods reject as unimplemented, so you can safely include the plugin in a cross-platform app. ### Why are my audio session settings overridden by other plugins?[ΒΆ](#why-are-my-audio-session-settings-overridden-by-other-plugins "Permanent link") The audio session is a single, app-wide object that is shared with other audio-related plugins (such as the [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/) and [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) plugins) and the underlying platform APIs they use. The last write wins, so another plugin may override the category, mode or options you have set. Reconfigure the session whenever you switch between playback, recording and other audio scenarios. See the [Session Ownership](#session-ownership) section for more details. ### How can my app play audio without interrupting other apps?[ΒΆ](#how-can-my-app-play-audio-without-interrupting-other-apps "Permanent link") Use the `mixWithOthers` category option when calling `configure(...)` to mix your audio with audio from other active sessions instead of interrupting them. Alternatively, use the `duckOthers` option to reduce the volume of other sessions while your audio plays. ### How do I resume playback after a phone call interrupted my app?[ΒΆ](#how-do-i-resume-playback-after-a-phone-call-interrupted-my-app "Permanent link") Add a listener for the `interruption` event. When the event's `type` is `ended` and `shouldResume` is `true`, playback should be resumed. See [Listen for interruptions](#listen-for-interruptions) for an example. ### How do I route audio to the loudspeaker?[ΒΆ](#how-do-i-route-audio-to-the-loudspeaker "Permanent link") Call `overrideOutput(...)` with the type `speaker` to route playback to the built-in speaker, and with `default` to restore the default route. If you want audio to be routed to the speaker by default when no other route is connected, use the `defaultToSpeaker` category option when calling `configure(...)`. ### Can I use this plugin with Ionic, React, Vue or Angular?[ΒΆ](#can-i-use-this-plugin-with-ionic-react-vue-or-angular "Permanent link") Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects. ## Related Plugins[ΒΆ](#related-plugins "Permanent link") * [Audio Player](https://capawesome.io/docs/sdks/capacitor/audio-player/): Play audio with background support. * [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/): Record audio using the device's microphone. * [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons. * [Volume](https://capawesome.io/docs/sdks/capacitor/volume/): Control the volume and observe hardware volume button presses. ## Newsletter[ΒΆ](#newsletter "Permanent link") Stay up to date with the latest news and updates about the Capawesome, Capacitor, and Ionic ecosystem by subscribing to our [Capawesome Newsletter](https://cloud.capawesome.io/newsletter/). ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-session/CHANGELOG.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-session/LICENSE). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/audio-session/#article", "headline": "Capacitor Audio Session Plugin for iOS", "name": "Capacitor Audio Session Plugin for iOS", "description": "Capacitor plugin to configure and observe the iOS audio session. Set the category, mode, and options, route audio output, and listen for interruptions.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/audio-session/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/audio-session/", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "about": {"@id": "https://capawesome.io/docs/sdks/capacitor/audio-session/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/audio-session/#software", "name": "Capacitor Audio Session Plugin for iOS", "description": "Capacitor plugin to configure and observe the iOS audio session. Set the category, mode, and options, route audio output, and listen for interruptions.", "url": "https://capawesome.io/docs/sdks/capacitor/audio-session/", "programmingLanguage": "TypeScript", "runtimePlatform": "Capacitor", "codeRepository": "https://github.com/capawesome-team", "author": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}, "publisher": {"@type": "Organization", "name": "Capawesome", "url": "https://capawesome.io", "logo": {"@type": "ImageObject", "url": "https://capawesome.io/assets/images/logo.svg"}}}]} {"@context": "https://schema.org", "@type": "FAQPage", "mainEntity": [{"@type": "Question", "name": "How is this plugin different from other similar plugins?", "acceptedAnswer": {"@type": "Answer", "text": "It gives you fine-grained control over the iOS audio session through one fully typed API: set the category, mode and options, activate or deactivate the session, read the current outputs and override the output route, and observe interruption and route-change events. It documents the shared, app-wide nature of the audio session honestly, so you know exactly how it behaves alongside other audio code, and it's actively maintained against the latest Capacitor and iOS versions. If you only play a simple sound, a basic setup is enough; if you need precise session control, this plugin is designed for exactly that."}}, {"@type": "Question", "name": "Is this plugin available on Android or the Web?", "acceptedAnswer": {"@type": "Answer", "text": "No, this plugin is only available on iOS since it controls the iOS-specific audio session. On Android and Web, all methods reject as unimplemented, so you can safely include the plugin in a cross-platform app."}}, {"@type": "Question", "name": "Why are my audio session settings overridden by other plugins?", "acceptedAnswer": {"@type": "Answer", "text": "The audio session is a single, app-wide object that is shared with other audio-related plugins (such as the Audio Player and Audio Recorder plugins) and the underlying platform APIs they use. The last write wins, so another plugin may override the category, mode or options you have set. Reconfigure the session whenever you switch between playback, recording and other audio scenarios. See the Session Ownership section for more details."}}, {"@type": "Question", "name": "How can my app play audio without interrupting other apps?", "acceptedAnswer": {"@type": "Answer", "text": "Use the mixWithOthers category option when calling configure(...) to mix your audio with audio from other active sessions instead of interrupting them. Alternatively, use the duckOthers option to reduce the volume of other sessions while your audio plays."}}, {"@type": "Question", "name": "How do I resume playback after a phone call interrupted my app?", "acceptedAnswer": {"@type": "Answer", "text": "Add a listener for the interruption event. When the event's type is ended and shouldResume is true, playback should be resumed. See Listen for interruptions for an example."}}, {"@type": "Question", "name": "How do I route audio to the loudspeaker?", "acceptedAnswer": {"@type": "Answer", "text": "Call overrideOutput(...) with the type speaker to route playback to the built-in speaker, and with default to restore the default route. If you want audio to be routed to the speaker by default when no other route is connected, use the defaultToSpeaker category option when calling configure(...)."}}, {"@type": "Question", "name": "Can I use this plugin with Ionic, React, Vue or Angular?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is framework-agnostic. It works in any Capacitor app regardless of the web framework, including Ionic with Angular, React, or Vue, as well as plain JavaScript projects."}}], "url": "https://capawesome.io/docs/sdks/capacitor/audio-session/"} ```