@capawesome-team/capacitor-audio-player¶

Capacitor plugin to play audio with background support.

Deliver Live Updates to your Capacitor app with Capawesome Cloud

Features¶

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.
⏯️ 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.
🗂️ Web Assets: Support for web asset paths alongside file URIs and remote URLs.
🤝 Compatibility: Compatible with the Audio Recorder, Media Session, Speech Recognition and Speech Synthesis plugins.
📦 SPM: Supports 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 and we'll take a look!

Compatibility¶

Plugin Version	Capacitor Version	Status
7.x.x	>=7.x.x	Active support

Installation¶

This plugin is only available to Capawesome Insiders. First, make sure you have the Capawesome npm registry set up. You can do this by running the following commands:

npm config set @capawesome-team:registry https://npm.registry.capawesome.io
npm config set //npm.registry.capawesome.io/:_authToken <YOUR_LICENSE_KEY>

Attention: Replace <YOUR_LICENSE_KEY> 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.

Next, install the package:

npm install @capawesome-team/capacitor-audio-player
npx cap sync

iOS¶

Capabilities¶

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 for more information.

Usage¶

import { AudioPlayer } from '@capawesome-team/capacitor-audio-player';
import { Capacitor } from '@capacitor/core';
import { Filesystem } from '@capacitor/filesystem';

const playFromWebAsset = async () => {
  await AudioPlayer.play({ 
    src: '/assets/audio.mp3', 
    loop: false, 
    volume: 100, 
    position: 0 
  });
};

const playFromNativeFile = async () => {
  const { uri } = await Filesystem.getUri({
    directory: FilesystemDirectory.Documents,
    path: 'audio.mp3',
  });
  await AudioPlayer.play({ uri, loop: false, volume: 100, position: 0 });
};

const playFromBlob = async () => {
  const assetUrl = 'https://www.example.com/audio.mp3';
  const response = await fetch(assetUrl);
  const blob = await response.blob();
  await AudioPlayer.play({ blob, loop: false, volume: 100, position: 0 });
};

const pause = async () => {
  await AudioPlayer.pause();
};

const resume = async () => {
  await AudioPlayer.resume();
};

const stop = async () => {
  await AudioPlayer.stop();
};

const seekTo = async () => {
  await AudioPlayer.seekTo({ position: 30_000 }); // Seek to 30 seconds
};

const setVolume = async () => {
  await AudioPlayer.setVolume({ volume: 50 }); // Set volume to 50%
};

const getCurrentPosition = async () => {
  const { position } = await AudioPlayer.getCurrentPosition();
  console.log('Current position:', position);
};

const getDuration = async () => {
  const { duration } = await AudioPlayer.getDuration();
  console.log('Duration:', duration);
};

const isPlaying = async () => {
  const { isPlaying } = await AudioPlayer.isPlaying();
  console.log('Is playing:', isPlaying);
};

getCurrentPosition()¶

getCurrentPosition() => Promise<GetCurrentPositionResult>

Get the current position of the audio playback in milliseconds.

Returns: Promise<GetCurrentPositionResult>

Since: 0.0.1

getDuration()¶

getDuration() => Promise<GetDurationResult>

Get the duration of the audio playback in milliseconds.

Returns: Promise<GetDurationResult>

Since: 0.0.1

isPlaying()¶

isPlaying() => Promise<IsPlayingResult>

Check whether the audio is currently playing.

Returns: Promise<IsPlayingResult>

Since: 0.0.1

pause()¶

pause() => Promise<void>

Pause the audio playback.

Since: 0.0.1

play(...)¶

play(options: PlayOptions) => Promise<void>

Play the audio playback.

Param	Type
`options`	`PlayOptions`

Since: 0.0.1

resume()¶

resume() => Promise<void>

Resume the audio playback.

Since: 0.0.1

seekTo(...)¶

seekTo(options: SeekToOptions) => Promise<void>

Seek to a specific position in the audio playback.

Param	Type
`options`	`SeekToOptions`

Since: 0.0.1

setVolume(...)¶

setVolume(options: SetVolumeOptions) => Promise<void>

Set the volume level for the audio playback.

Param	Type
`options`	`SetVolumeOptions`

Since: 0.0.1

stop()¶

stop() => Promise<void>

Stop the audio playback.

Since: 0.0.1

Interfaces¶

GetCurrentPositionResult¶

Prop	Type	Description	Since
`position`	`number`	The current position of the audio playback in milliseconds.	0.0.1

GetDurationResult¶

Prop	Type	Description	Since
`duration`	`number`	The duration of the audio playback in milliseconds.	0.0.1

IsPlayingResult¶

Prop	Type	Description	Since
`isPlaying`	`boolean`	Whether the audio is currently playing.	0.0.1

PlayOptions¶

Prop	Type	Description	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
`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. On Android, only web assets are supported. On iOS and Web, both web assets and remote URLs are supported.	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).	0.0.1

SeekToOptions¶

Prop	Type	Description	Since
`position`	`number`	The position to seek to (in milliseconds).	0.0.1

SetVolumeOptions¶

Prop	Type	Description	Since
`volume`	`number`	The volume level to set (0-100).	0.0.1

Changelog¶

See CHANGELOG.md.

Breaking Changes¶

See BREAKING.md.

License¶

See LICENSE.