--- 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/sdks/capacitor/audio-player.png --- [Skip to content ](#capacitor-audio-player-plugin) [πŸ–₯️ Introducing the **Capacitor Electron Platform** β€” build desktop apps for macOS, Windows, and Linux. Free & open source. ](/blog/announcing-the-capacitor-electron-platform/) * [ SDKs ](/docs/sdks/) * [ Usage ](#usage) * [ API ](#api) * [ Troubleshooting ](#troubleshooting) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) * [ Audio Recorder ](/docs/sdks/capacitor/audio-recorder/) * [ Audio Session ](/docs/sdks/capacitor/audio-session/) * [ 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/) * 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 * [ Usage ](#usage) * [ API ](#api) * [ Troubleshooting ](#troubleshooting) * [ FAQ ](#faq) * [ Related Plugins ](#related-plugins) * [ Newsletter ](#newsletter) * [ Changelog ](#changelog) * [ Breaking Changes ](#breaking-changes) * [ License ](#license) # Capacitor Audio Player Plugin[ΒΆ](#capacitor-audio-player-plugin "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") The Capacitor Audio Player plugin is one of the most complete audio playback solutions for Capacitor apps. 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/sdks/capacitor/audio-recorder/), [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/), [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/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! ## Use Cases[ΒΆ](#use-cases "Permanent link") The Audio Player plugin is typically used whenever an app needs to play audio, for example: * **Music and podcast playback**: Play remote audio files and keep them playing while the app is in the background. * **Voice message playback**: Play voice messages recorded with the [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/) plugin in chat or support apps. * **Sound effects**: Play short sounds from your web assets with precise volume control and looping. * **Audiobooks and learning apps**: Let users adjust the playback speed and seek to specific positions. ## 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") The following examples show how to play audio from web assets, remote URLs, the file system, or a blob, and how to control, seek, adjust the volume of, and inspect the playback. ### Play an audio file from your web assets or a remote URL[ΒΆ](#play-an-audio-file-from-your-web-assets-or-a-remote-url "Permanent link") Use the `src` option to play a web asset or a remote URL. Both are supported on all platforms: `[](#%5F%5Fcodelineno-4-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-4-2) [](#%5F%5Fcodelineno-4-3)const playFromWebAsset = async () => { [](#%5F%5Fcodelineno-4-4) await AudioPlayer.play({ [](#%5F%5Fcodelineno-4-5) src: '/assets/audio.mp3', [](#%5F%5Fcodelineno-4-6) loop: false, [](#%5F%5Fcodelineno-4-7) volume: 100, [](#%5F%5Fcodelineno-4-8) position: 0 [](#%5F%5Fcodelineno-4-9) }); [](#%5F%5Fcodelineno-4-10)}; ` ### Play an audio file from the file system[ΒΆ](#play-an-audio-file-from-the-file-system "Permanent link") Use the `uri` option to play a file from the device's file system, for example one retrieved with the Capacitor Filesystem plugin. This option is only available on Android and iOS: `[](#%5F%5Fcodelineno-5-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-5-2)import { Filesystem, FilesystemDirectory } from '@capacitor/filesystem'; [](#%5F%5Fcodelineno-5-3) [](#%5F%5Fcodelineno-5-4)const playFromNativeFile = async () => { [](#%5F%5Fcodelineno-5-5) const { uri } = await Filesystem.getUri({ [](#%5F%5Fcodelineno-5-6) directory: FilesystemDirectory.Documents, [](#%5F%5Fcodelineno-5-7) path: 'audio.mp3', [](#%5F%5Fcodelineno-5-8) }); [](#%5F%5Fcodelineno-5-9) await AudioPlayer.play({ uri, loop: false, volume: 100, position: 0 }); [](#%5F%5Fcodelineno-5-10)}; ` ### Play an audio file from a blob[ΒΆ](#play-an-audio-file-from-a-blob "Permanent link") Use the `blob` option to play a `Blob` instance, for example one fetched from a server. This option is only available on Web: `[](#%5F%5Fcodelineno-6-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-6-2) [](#%5F%5Fcodelineno-6-3)const playFromBlob = async () => { [](#%5F%5Fcodelineno-6-4) const assetUrl = 'https://www.example.com/audio.mp3'; [](#%5F%5Fcodelineno-6-5) const response = await fetch(assetUrl); [](#%5F%5Fcodelineno-6-6) const blob = await response.blob(); [](#%5F%5Fcodelineno-6-7) await AudioPlayer.play({ blob, loop: false, volume: 100, position: 0 }); [](#%5F%5Fcodelineno-6-8)}; ` ### Pause, resume and stop the playback[ΒΆ](#pause-resume-and-stop-the-playback "Permanent link") Pause the playback and resume it later, or stop it entirely: `[](#%5F%5Fcodelineno-7-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-7-2) [](#%5F%5Fcodelineno-7-3)const pause = async () => { [](#%5F%5Fcodelineno-7-4) await AudioPlayer.pause(); [](#%5F%5Fcodelineno-7-5)}; [](#%5F%5Fcodelineno-7-6) [](#%5F%5Fcodelineno-7-7)const resume = async () => { [](#%5F%5Fcodelineno-7-8) await AudioPlayer.resume(); [](#%5F%5Fcodelineno-7-9)}; [](#%5F%5Fcodelineno-7-10) [](#%5F%5Fcodelineno-7-11)const stop = async () => { [](#%5F%5Fcodelineno-7-12) await AudioPlayer.stop(); [](#%5F%5Fcodelineno-7-13)}; ` ### Seek to a specific position[ΒΆ](#seek-to-a-specific-position "Permanent link") Jump to a specific position in the audio playback, given in milliseconds: `[](#%5F%5Fcodelineno-8-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-8-2) [](#%5F%5Fcodelineno-8-3)const seekTo = async () => { [](#%5F%5Fcodelineno-8-4) await AudioPlayer.seekTo({ position: 30_000 }); // Seek to 30 seconds [](#%5F%5Fcodelineno-8-5)}; ` ### Adjust the volume[ΒΆ](#adjust-the-volume "Permanent link") Set the volume level of the current playback session to a value between 0 and 100: `[](#%5F%5Fcodelineno-9-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-9-2) [](#%5F%5Fcodelineno-9-3)const setVolume = async () => { [](#%5F%5Fcodelineno-9-4) await AudioPlayer.setVolume({ volume: 50 }); // Set volume to 50% [](#%5F%5Fcodelineno-9-5)}; ` ### Get the current playback state[ΒΆ](#get-the-current-playback-state "Permanent link") Retrieve the current position and duration of the playback in milliseconds, and check whether the audio is currently playing: `[](#%5F%5Fcodelineno-10-1)import { AudioPlayer } from '@capawesome-team/capacitor-audio-player'; [](#%5F%5Fcodelineno-10-2) [](#%5F%5Fcodelineno-10-3)const getCurrentPosition = async () => { [](#%5F%5Fcodelineno-10-4) const { position } = await AudioPlayer.getCurrentPosition(); [](#%5F%5Fcodelineno-10-5) console.log('Current position:', position); [](#%5F%5Fcodelineno-10-6)}; [](#%5F%5Fcodelineno-10-7) [](#%5F%5Fcodelineno-10-8)const getDuration = async () => { [](#%5F%5Fcodelineno-10-9) const { duration } = await AudioPlayer.getDuration(); [](#%5F%5Fcodelineno-10-10) console.log('Duration:', duration); [](#%5F%5Fcodelineno-10-11)}; [](#%5F%5Fcodelineno-10-12) [](#%5F%5Fcodelineno-10-13)const isPlaying = async () => { [](#%5F%5Fcodelineno-10-14) const { isPlaying } = await AudioPlayer.isPlaying(); [](#%5F%5Fcodelineno-10-15) console.log('Is playing:', isPlaying); [](#%5F%5Fcodelineno-10-16)}; ` ## 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-11-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-12-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-13-1)isPlaying() => Promise ` Check whether the audio is currently playing. **Returns:** `Promise<[IsPlayingResult](#isplayingresult)>` **Since:** 0.0.1 --- ### pause()[ΒΆ](#pause "Permanent link") `[](#%5F%5Fcodelineno-14-1)pause() => Promise ` Pause the audio playback. **Since:** 0.0.1 --- ### play(...)[ΒΆ](#play "Permanent link") `[](#%5F%5Fcodelineno-15-1)play(options: PlayOptions) => Promise ` Play the audio playback. | Param | Type | | ----------- | --------------------------- | | **options** | [PlayOptions](#playoptions) | **Since:** 0.0.1 --- ### resume()[ΒΆ](#resume "Permanent link") `[](#%5F%5Fcodelineno-16-1)resume() => Promise ` Resume the audio playback. **Since:** 0.0.1 --- ### seekTo(...)[ΒΆ](#seekto "Permanent link") `[](#%5F%5Fcodelineno-17-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-18-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-19-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-20-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-21-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-22-1)await AudioPlayer.stop({ deactivateAudioSession: false }); ` ## FAQ[ΒΆ](#faq "Permanent link") ### Can I play audio while the app is in the background?[ΒΆ](#can-i-play-audio-while-the-app-is-in-the-background "Permanent link") Yes, the plugin supports background playback. On iOS, you need to enable the `Background Modes` capability with `Audio, AirPlay, and Picture in Picture` in your Xcode project, as described in the [Installation](#installation) section. ### Which audio sources can I play?[ΒΆ](#which-audio-sources-can-i-play "Permanent link") You can play web assets and remote URLs via the `src` option on all platforms. On Android and iOS, you can also play files from the device's file system via the `uri` option. On Web, you can play `Blob` instances via the `blob` option. See the [Usage](#usage) section for examples. ### How can I change the playback speed?[ΒΆ](#how-can-i-change-the-playback-speed "Permanent link") Use the `rate` option of the `play(...)` method or call `setRate(...)` during playback. Values between 0.5 and 2.0 are recommended, as other values may not be supported on all devices. The playback rate is adjusted with pitch preservation and is available on Android (SDK 23+), iOS and Web. ### Why does playback fail with a CoreMediaErrorDomain -16042 error on iOS?[ΒΆ](#why-does-playback-fail-with-a-coremediaerrordomain-16042-error-on-ios "Permanent link") This can happen when `play()` is called shortly after `stop()`, because the audio session is deactivated by default when stopping. Set the `deactivateAudioSession` option of the `stop(...)` method to `false` if you intend to play audio again shortly after stopping. See the [Troubleshooting](#troubleshooting) section for more details. ### Can I use this plugin together with other audio plugins?[ΒΆ](#can-i-use-this-plugin-together-with-other-audio-plugins "Permanent link") Yes, the plugin is compatible with the [Audio Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/), [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/), [Speech Recognition](https://capawesome.io/docs/sdks/capacitor/speech-recognition/) and [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/) plugins. For example, you can play back a recording created with the Audio Recorder plugin. ### 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 Recorder](https://capawesome.io/docs/sdks/capacitor/audio-recorder/): Record audio using the device's microphone. * [Audio Session](https://capawesome.io/docs/sdks/capacitor/audio-session/): Configure and observe the iOS audio session. * [Media Session](https://capawesome.io/docs/sdks/capacitor/media-session/): Interact with media controllers, volume keys and media buttons. * [Speech Synthesis](https://capawesome.io/docs/sdks/capacitor/speech-synthesis/): Synthesize speech from text with voice selection, pitch, and rate control. ## 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-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). July 8, 2026 Back to top ```json {"@context": "https://schema.org", "@graph": [{"@type": "TechArticle", "@id": "https://capawesome.io/docs/sdks/capacitor/audio-player/#article", "headline": "Capacitor Audio Player Plugin for Android, iOS & Web", "name": "Capacitor Audio Player Plugin for Android, iOS & Web", "description": "Capacitor plugin for audio playback using the device's speakers with background support. Available on Android, iOS, and Web.", "inLanguage": "en", "url": "https://capawesome.io/docs/sdks/capacitor/audio-player/", "mainEntityOfPage": "https://capawesome.io/docs/sdks/capacitor/audio-player/", "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-player/#software"}}, {"@type": "SoftwareSourceCode", "@id": "https://capawesome.io/docs/sdks/capacitor/audio-player/#software", "name": "Capacitor Audio Player Plugin for Android, iOS & Web", "description": "Capacitor plugin for audio playback using the device's speakers with background support. Available on Android, iOS, and Web.", "url": "https://capawesome.io/docs/sdks/capacitor/audio-player/", "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": "Can I play audio while the app is in the background?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin supports background playback. On iOS, you need to enable the Background Modes capability with Audio, AirPlay, and Picture in Picture in your Xcode project, as described in the Installation section."}}, {"@type": "Question", "name": "Which audio sources can I play?", "acceptedAnswer": {"@type": "Answer", "text": "You can play web assets and remote URLs via the src option on all platforms. On Android and iOS, you can also play files from the device's file system via the uri option. On Web, you can play Blob instances via the blob option. See the Usage section for examples."}}, {"@type": "Question", "name": "How can I change the playback speed?", "acceptedAnswer": {"@type": "Answer", "text": "Use the rate option of the play(...) method or call setRate(...) during playback. Values between 0.5 and 2.0 are recommended, as other values may not be supported on all devices. The playback rate is adjusted with pitch preservation and is available on Android (SDK 23+), iOS and Web."}}, {"@type": "Question", "name": "Why does playback fail with a CoreMediaErrorDomain -16042 error on iOS?", "acceptedAnswer": {"@type": "Answer", "text": "This can happen when play() is called shortly after stop(), because the audio session is deactivated by default when stopping. Set the deactivateAudioSession option of the stop(...) method to false if you intend to play audio again shortly after stopping. See the Troubleshooting section for more details."}}, {"@type": "Question", "name": "Can I use this plugin together with other audio plugins?", "acceptedAnswer": {"@type": "Answer", "text": "Yes, the plugin is compatible with the Audio Recorder, Media Session, Speech Recognition and Speech Synthesis plugins. For example, you can play back a recording created with the Audio Recorder plugin."}}, {"@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-player/"} ```