@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 and iOS.
🌙 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.
🤝 Compatibility: Compatible with the Audio Recorder, 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.

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 play = async () => {
  if (Capacitor.getPlatform() === 'web') {
    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 });
  } else {
  const { uri } = await Filesystem.getUri({
    directory: FilesystemDirectory.Documents,
    path: 'audio.mp3',
  });
    await AudioPlayer.play({ uri, 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. Only available on Web.	0.0.1
`uri`	`string`	The URI of the audio file to play. Only available on Android and iOS.	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
`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.