--- description: Capacitor plugin for audio playback using the device's speakers with background support. Available on Android, iOS, and Web. title: Capacitor Audio Player Plugin for Android, iOS & Web - Capawesome image: https://capawesome.io/docs/assets/images/social/plugins/audio-player.png --- [ Skip to content](#capawesome-teamcapacitor-audio-player) [ πŸŽ‰ Introducing **Capawesome Platform** β€” one platform for Live Updates, Native Builds, App Store Publishing, and Insider SDKs.](https://capawesome.io) * [ Usage ](#usage) * [ API ](#api) * [ Troubleshooting ](#troubleshooting) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Audio Recorder ](/docs/plugins/audio-recorder/) * [ Background Task ](/docs/plugins/background-task/) * [ Badge ](/docs/plugins/badge/) * [ Barometer ](/docs/plugins/barometer/) * [ Biometrics ](/docs/plugins/biometrics/) * [ Bluetooth Low Energy ](/docs/plugins/bluetooth-low-energy/) * [ Cloudinary ](/docs/plugins/cloudinary/) * [ Contacts ](/docs/plugins/contacts/) * [ Datetime Picker ](/docs/plugins/datetime-picker/) * [ File Compressor ](/docs/plugins/file-compressor/) * [ File Opener ](/docs/plugins/file-opener/) * [ File Picker ](/docs/plugins/file-picker/) * [ Firebase ](/docs/plugins/firebase/) * [ Formbricks ](/docs/plugins/formbricks/) * [ Geocoder ](/docs/plugins/geocoder/) * [ Google Sign-In ](/docs/plugins/google-sign-in/) * [ libSQL ](/docs/plugins/libsql/) * [ Live Update ](/docs/plugins/live-update/) * [ Managed Configurations ](/docs/plugins/managed-configurations/) * [ Media Session ](/docs/plugins/media-session/) * [ ML Kit ](/docs/plugins/mlkit/) * [ NFC ](/docs/plugins/nfc/) * [ OAuth ](/docs/plugins/oauth/) * [ Pedometer ](/docs/plugins/pedometer/) * [ Photo Editor ](/docs/plugins/photo-editor/) * [ PostHog ](/docs/plugins/posthog/) * [ Printer ](/docs/plugins/printer/) * [ Purchases ](/docs/plugins/purchases/) * [ RealtimeKit ](/docs/plugins/realtimekit/) * [ Screen Orientation ](/docs/plugins/screen-orientation/) * [ Screenshot ](/docs/plugins/screenshot/) * [ Secure Preferences ](/docs/plugins/secure-preferences/) * [ Speech Recognition ](/docs/plugins/speech-recognition/) * [ Speech Synthesis ](/docs/plugins/speech-synthesis/) * [ Share Target ](/docs/plugins/share-target/) * [ Square Mobile Payments ](/docs/plugins/square-mobile-payments/) * [ SQLite ](/docs/plugins/sqlite/) * [ Superwall ](/docs/plugins/superwall/) * [ Torch ](/docs/plugins/torch/) * [ Wifi ](/docs/plugins/wifi/) * [ Zip ](/docs/plugins/zip/) * [ Cloud ](/docs/cloud/) * [ Live Updates ](/docs/cloud/live-updates/) * Advanced * Integrations * [ Native Builds ](/docs/cloud/native-builds/) * [ Configuration ](/docs/cloud/native-builds/configuration/) * [ Environments ](/docs/cloud/native-builds/environments/) * Guides * [ Sample Projects ](/docs/cloud/native-builds/sample-projects/) * [ Troubleshooting ](/docs/cloud/native-builds/troubleshooting/) * [ Automations ](/docs/cloud/automations/) * [ Assist ](/docs/cloud/assist/) * Account * Organizations * [ Organization and User Management ](/docs/cloud/organizations/memberships/) * [ Single Sign-On (SSO) ](/docs/cloud/organizations/sso/) * [ Teams ](/docs/cloud/organizations/teams/) * [ Two-Factor Authentication ](/docs/cloud/organizations/two-factor-authentication/) * [ Integrations ](/docs/cloud/integrations/) * [ License Keys ](/docs/cloud/license-keys/) * [ Webhooks ](/docs/cloud/webhooks/) * [ Pricing ](https://capawesome.io/pricing/) * [ FAQ ](/docs/cloud/faq/) * [ Support ](/docs/cloud/support/) * [ Contributing ](/docs/contributing/) * [ LLMs ](/docs/llms/) * [ Insiders ](/docs/insiders/) * [ License ](https://capawesome.io/legal/eula/) * [ Support ](/docs/insiders/support/) * [ FAQ ](/docs/insiders/faq/) * [ Blog ](/blog/) * Categories * [ Usage ](#usage) * [ API ](#api) * [ Troubleshooting ](#troubleshooting) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # @capawesome-team/capacitor-audio-player[ΒΆ](#capawesome-teamcapacitor-audio-player "Permanent link") Capacitor plugin to play audio with background support. [ ![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") We are proud to offer one of the most complete and feature-rich Capacitor plugins for audio playback. Here are some of the key features: * πŸ–₯️ **Cross-platform**: Supports Android, iOS and Web. * πŸŒ™ **Background Mode**: Play audio even when the app is in the background. * 🎡 **Audio Focus Management**: Automatically manages audio focus on Android to pause other audio sources during playback. * ⏯️ **Full Control**: Play, pause, resume, stop, seek, and adjust volume. * πŸ”‚ **Loop Support**: Loop audio playback for continuous sound. * πŸ”Š **Volume Control**: Precise volume control from 0-100. * ⏩ **Playback Speed**: Adjustable playback rate with pitch preservation. * πŸ—‚οΈ **Web Assets**: Support for web asset paths alongside file URIs and remote URLs. * 🀝 **Compatibility**: Compatible with the [Audio Recorder](https://capawesome.io/docs/plugins/audio-recorder/), [Media Session](https://capawesome.io/docs/plugins/media-session/), [Speech Recognition](https://capawesome.io/docs/plugins/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/plugins/speech-synthesis/) plugins. * πŸ“¦ **CocoaPods & SPM**: Supports CocoaPods and Swift Package Manager for iOS. * πŸ” **Up-to-date**: Always supports the latest Capacitor version. * ⭐️ **Support**: Priority support from the Capawesome Team. * ✨ **Handcrafted**: Built from the ground up with care and expertise, not forked or AI-generated. Missing a feature? Just [open an issue](https://github.com/capawesome-team/capacitor-plugins/issues) and we'll take a look! ## 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/). ## Compatibility[ΒΆ](#compatibility "Permanent link") | Plugin Version | Capacitor Version | Status | | -------------- | ----------------- | -------------- | | 8.x.x | \>=8.x.x | Active support | | 0.2.x | 7.x.x | Deprecated | ## Installation[ΒΆ](#installation "Permanent link") This plugin is only available to [Capawesome Insiders](https://capawesome.io/insiders/). First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands: `[](#%5F%5Fcodelineno-0-1)npm config set @capawesome-team:registry https://npm.registry.capawesome.io [](#%5F%5Fcodelineno-0-2)npm config set //npm.registry.capawesome.io/:_authToken ` **Attention**: Replace `` with the license key you received from Polar. If you don't have a license key yet, you can get one by becoming a [Capawesome Insider](https://capawesome.io/insiders/). Next, 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-1-1)npx skills add capawesome-team/skills --skill capacitor-plugins ` Then use the following prompt: `` [](#%5F%5Fcodelineno-2-1)Use the `capacitor-plugins` skill from `capawesome-team/skills` to install the `@capawesome-team/capacitor-audio-player` 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-3-1)npm install @capawesome-team/capacitor-audio-player [](#%5F%5Fcodelineno-3-2)npx cap sync ` ### iOS[ΒΆ](#ios "Permanent link") #### Capabilities[ΒΆ](#capabilities "Permanent link") If you want to play audio in the background, ensure `Background Modes` capability is enabled with `Audio, AirPlay, and Picture in Picture` in your Xcode project. See [Add a capability to a target](https://help.apple.com/xcode/mac/current/#/dev88ff319e7) for more information. ## Usage[ΒΆ](#usage "Permanent link") `[](#%5F%5Fcodelineno-4-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-4-2)import { Capacitor } from '@capacitor/core'; [](#%5F%5Fcodelineno-4-3)import { Filesystem } from '@capacitor/filesystem'; [](#%5F%5Fcodelineno-4-4) [](#%5F%5Fcodelineno-4-5)const playFromWebAsset = async () => { [](#%5F%5Fcodelineno-4-6) await AudioPlayer.play({ [](#%5F%5Fcodelineno-4-7) src: '/assets/audio.mp3', [](#%5F%5Fcodelineno-4-8) loop: false, [](#%5F%5Fcodelineno-4-9) volume: 100, [](#%5F%5Fcodelineno-4-10) position: 0 [](#%5F%5Fcodelineno-4-11) }); [](#%5F%5Fcodelineno-4-12)}; [](#%5F%5Fcodelineno-4-13) [](#%5F%5Fcodelineno-4-14)const playFromNativeFile = async () => { [](#%5F%5Fcodelineno-4-15) const { uri } = await Filesystem.getUri({ [](#%5F%5Fcodelineno-4-16) directory: FilesystemDirectory.Documents, [](#%5F%5Fcodelineno-4-17) path: 'audio.mp3', [](#%5F%5Fcodelineno-4-18) }); [](#%5F%5Fcodelineno-4-19) await AudioPlayer.play({ uri, loop: false, volume: 100, position: 0 }); [](#%5F%5Fcodelineno-4-20)}; [](#%5F%5Fcodelineno-4-21) [](#%5F%5Fcodelineno-4-22)const playFromBlob = async () => { [](#%5F%5Fcodelineno-4-23) const assetUrl = 'https://www.example.com/audio.mp3'; [](#%5F%5Fcodelineno-4-24) const response = await fetch(assetUrl); [](#%5F%5Fcodelineno-4-25) const blob = await response.blob(); [](#%5F%5Fcodelineno-4-26) await AudioPlayer.play({ blob, loop: false, volume: 100, position: 0 }); [](#%5F%5Fcodelineno-4-27)}; [](#%5F%5Fcodelineno-4-28) [](#%5F%5Fcodelineno-4-29)const pause = async () => { [](#%5F%5Fcodelineno-4-30) await AudioPlayer.pause(); [](#%5F%5Fcodelineno-4-31)}; [](#%5F%5Fcodelineno-4-32) [](#%5F%5Fcodelineno-4-33)const resume = async () => { [](#%5F%5Fcodelineno-4-34) await AudioPlayer.resume(); [](#%5F%5Fcodelineno-4-35)}; [](#%5F%5Fcodelineno-4-36) [](#%5F%5Fcodelineno-4-37)const stop = async () => { [](#%5F%5Fcodelineno-4-38) await AudioPlayer.stop(); [](#%5F%5Fcodelineno-4-39)}; [](#%5F%5Fcodelineno-4-40) [](#%5F%5Fcodelineno-4-41)const seekTo = async () => { [](#%5F%5Fcodelineno-4-42) await AudioPlayer.seekTo({ position: 30_000 }); // Seek to 30 seconds [](#%5F%5Fcodelineno-4-43)}; [](#%5F%5Fcodelineno-4-44) [](#%5F%5Fcodelineno-4-45)const setVolume = async () => { [](#%5F%5Fcodelineno-4-46) await AudioPlayer.setVolume({ volume: 50 }); // Set volume to 50% [](#%5F%5Fcodelineno-4-47)}; [](#%5F%5Fcodelineno-4-48) [](#%5F%5Fcodelineno-4-49)const getCurrentPosition = async () => { [](#%5F%5Fcodelineno-4-50) const { position } = await AudioPlayer.getCurrentPosition(); [](#%5F%5Fcodelineno-4-51) console.log('Current position:', position); [](#%5F%5Fcodelineno-4-52)}; [](#%5F%5Fcodelineno-4-53) [](#%5F%5Fcodelineno-4-54)const getDuration = async () => { [](#%5F%5Fcodelineno-4-55) const { duration } = await AudioPlayer.getDuration(); [](#%5F%5Fcodelineno-4-56) console.log('Duration:', duration); [](#%5F%5Fcodelineno-4-57)}; [](#%5F%5Fcodelineno-4-58) [](#%5F%5Fcodelineno-4-59)const isPlaying = async () => { [](#%5F%5Fcodelineno-4-60) const { isPlaying } = await AudioPlayer.isPlaying(); [](#%5F%5Fcodelineno-4-61) console.log('Is playing:', isPlaying); [](#%5F%5Fcodelineno-4-62)}; ` ## API[ΒΆ](#api "Permanent link") * [getCurrentPosition()](#getcurrentposition) * [getDuration()](#getduration) * [isPlaying()](#isplaying) * [pause()](#pause) * [play(...)](#play) * [resume()](#resume) * [seekTo(...)](#seekto) * [setRate(...)](#setrate) * [setVolume(...)](#setvolume) * [stop(...)](#stop) * [addListener('stop', ...)](#addlistenerstop-) * [Interfaces](#interfaces) ### getCurrentPosition()[ΒΆ](#getcurrentposition "Permanent link") `[](#%5F%5Fcodelineno-5-1)getCurrentPosition() => Promise ` Get the current position of the audio playback in milliseconds. **Returns:** `Promise<[GetCurrentPositionResult](#getcurrentpositionresult)>` **Since:** 0.0.1 --- ### getDuration()[ΒΆ](#getduration "Permanent link") `[](#%5F%5Fcodelineno-6-1)getDuration() => Promise ` Get the duration of the audio playback in milliseconds. **Returns:** `Promise<[GetDurationResult](#getdurationresult)>` **Since:** 0.0.1 --- ### isPlaying()[ΒΆ](#isplaying "Permanent link") `[](#%5F%5Fcodelineno-7-1)isPlaying() => Promise ` Check whether the audio is currently playing. **Returns:** `Promise<[IsPlayingResult](#isplayingresult)>` **Since:** 0.0.1 --- ### pause()[ΒΆ](#pause "Permanent link") `[](#%5F%5Fcodelineno-8-1)pause() => Promise ` Pause the audio playback. **Since:** 0.0.1 --- ### play(...)[ΒΆ](#play "Permanent link") `[](#%5F%5Fcodelineno-9-1)play(options: PlayOptions) => Promise ` Play the audio playback. | Param | Type | | ----------- | --------------------------- | | **options** | [PlayOptions](#playoptions) | **Since:** 0.0.1 --- ### resume()[ΒΆ](#resume "Permanent link") `[](#%5F%5Fcodelineno-10-1)resume() => Promise ` Resume the audio playback. **Since:** 0.0.1 --- ### seekTo(...)[ΒΆ](#seekto "Permanent link") `[](#%5F%5Fcodelineno-11-1)seekTo(options: SeekToOptions) => Promise ` Seek to a specific position in the audio playback. | Param | Type | | ----------- | ------------------------------- | | **options** | [SeekToOptions](#seektooptions) | **Since:** 0.0.1 --- ### setRate(...)[ΒΆ](#setrate "Permanent link") `[](#%5F%5Fcodelineno-12-1)setRate(options: SetRateOptions) => Promise ` Set the playback rate for the audio playback. This only affects the current playback session and is not persisted. Only available on Android (SDK 23+), iOS and Web. | Param | Type | | ----------- | --------------------------------- | | **options** | [SetRateOptions](#setrateoptions) | **Since:** 8.2.0 --- ### setVolume(...)[ΒΆ](#setvolume "Permanent link") `[](#%5F%5Fcodelineno-13-1)setVolume(options: SetVolumeOptions) => Promise ` Set the volume level for the audio playback. This only affects the current playback session and is not persisted. | Param | Type | | ----------- | ------------------------------------- | | **options** | [SetVolumeOptions](#setvolumeoptions) | **Since:** 0.0.1 --- ### stop(...)[ΒΆ](#stop "Permanent link") `[](#%5F%5Fcodelineno-14-1)stop(options?: StopOptions | undefined) => Promise ` Stop the audio playback. | Param | Type | | ----------- | --------------------------- | | **options** | [StopOptions](#stopoptions) | **Since:** 0.0.1 --- ### addListener('stop', ...)[ΒΆ](#addlistenerstop "Permanent link") `[](#%5F%5Fcodelineno-15-1)addListener(eventName: 'stop', listenerFunc: () => void) => Promise ` Called when the audio has stopped playing. | Param | Type | | ---------------- | ---------- | | **eventName** | 'stop' | | **listenerFunc** | () => void | **Returns:** `Promise<[PluginListenerHandle](#pluginlistenerhandle)>` **Since:** 0.2.2 --- ### Interfaces[ΒΆ](#interfaces "Permanent link") #### GetCurrentPositionResult[ΒΆ](#getcurrentpositionresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ------ | ----------------------------------------------------------- | ----- | | **position** | number | The current position of the audio playback in milliseconds. | 0.0.1 | #### GetDurationResult[ΒΆ](#getdurationresult "Permanent link") | Prop | Type | Description | Since | | ------------ | ------ | --------------------------------------------------- | ----- | | **duration** | number | The duration of the audio playback in milliseconds. | 0.0.1 | #### IsPlayingResult[ΒΆ](#isplayingresult "Permanent link") | Prop | Type | Description | Since | | ------------- | ------- | --------------------------------------- | ----- | | **isPlaying** | boolean | Whether the audio is currently playing. | 0.0.1 | #### PlayOptions[ΒΆ](#playoptions "Permanent link") | Prop | Type | Description | Default | Since | | ------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **blob** | Blob | The audio file to play. If both blob and src are provided, blob takes priority. Only available on Web. | 0.0.1 | | | **loop** | boolean | Whether to loop the audio playback. | 0.0.1 | | | **position** | number | The position to start playback from (in milliseconds). | 0.0.1 | | | **rate** | number | The playback rate to use. Values between 0.5 and 2.0 are recommended. Other values may not be supported on all devices. Only available on Android (SDK 23+), iOS and Web. | 1.0 | 8.2.0 | | **src** | string | The path to the web asset file to play. If both blob and src are provided, blob takes priority. If both uri and src are provided, uri takes priority. Both web assets and remote URLs are supported on all platforms. | 0.1.2 | | | **uri** | string | The URI or path of the audio file to play. If both uri and src are provided, uri takes priority. Only available on Android and iOS. | 0.0.1 | | | **volume** | number | The volume level to set (0-100). | 100 | 0.0.1 | #### SeekToOptions[ΒΆ](#seektooptions "Permanent link") | Prop | Type | Description | Since | | ------------ | ------ | ------------------------------------------ | ----- | | **position** | number | The position to seek to (in milliseconds). | 0.0.1 | #### SetRateOptions[ΒΆ](#setrateoptions "Permanent link") | Prop | Type | Description | Since | | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------- | ----- | | **rate** | number | The playback rate to set. Values between 0.5 and 2.0 are recommended. Other values may not be supported on all devices. | 8.2.0 | #### SetVolumeOptions[ΒΆ](#setvolumeoptions "Permanent link") | Prop | Type | Description | Since | | ---------- | ------ | -------------------------------- | ----- | | **volume** | number | The volume level to set (0-100). | 0.0.1 | #### StopOptions[ΒΆ](#stopoptions "Permanent link") | Prop | Type | Description | Default | Since | | -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------- | ----- | | **deactivateAudioSession** | boolean | Whether to deactivate the audio session when stopping playback. Set to false if you intend to call play() again shortly after stopping, to avoid CoreMediaErrorDomain -16042 errors on iOS or audio focus issues on Android. Only available on Android and iOS. | true | 8.3.0 | #### PluginListenerHandle[ΒΆ](#pluginlistenerhandle "Permanent link") | Prop | Type | | ---------- | ------------------- | | **remove** | () => Promise | ## Troubleshooting[ΒΆ](#troubleshooting "Permanent link") ##### `CoreMediaErrorDomain -16042` error on iOS when calling `play()` after `stop()`[ΒΆ](#coremediaerrordomain-16042-error-on-ios-when-calling-play-after-stop "Permanent link") When `stop()` is called, the audio session is deactivated by default. If `play()` is called shortly after, `AVAudioSession.setActive(true)` can fail with `CoreMediaErrorDomain -16042`, breaking all subsequent playback. To avoid this, set `deactivateAudioSession` to `false` in the `stop()` options: `[](#%5F%5Fcodelineno-16-1)await AudioPlayer.stop({ deactivateAudioSession: false }); ` ## Changelog[ΒΆ](#changelog "Permanent link") See [CHANGELOG.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-player/CHANGELOG.md). ## Breaking Changes[ΒΆ](#breaking-changes "Permanent link") See [BREAKING.md](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-player/BREAKING.md). ## License[ΒΆ](#license "Permanent link") See [LICENSE](https://github.com/capawesome-team/capacitor-plugins/blob/main/packages/audio-player/LICENSE). May 17, 2026 Back to top