Skip to main content

cordova-plugin-media Alternative for Capacitor

cordova-plugin-media alternative for Capacitor playback: @capgo/capacitor-native-audio for preload, queues, progress events, and background audio without Media callbacks.

Illustration of migrating a Cordova app to Capacitor, used for a media playback plugin guide

The cordova-plugin-media alternative for Capacitor playback is @capgo/capacitor-native-audio. It replaces the Cordova Media constructor and status callbacks with promise-based NativeAudio calls, asset ids, and listeners for completion and progress. Install @capgo/capacitor-native-audio on new projects; npm still publishes the older @capgo/native-audio name for existing apps. This guide focuses on playback, lists verifiable npm facts, and maps the Cordova Media API from www/Media.js.

Why leave cordova-plugin-media for playback

cordova-plugin-media on npm is version 7.0.0. The registry modified timestamp is 13 September 2023. The Apache plugin constructs audio with new Media(src, success, error, statusCallback, durationUpdateCallback) and exposes play, pause, stop, seekTo, getDuration, getCurrentPosition, setVolume, setRate, and release on the prototype (see apache/cordova-plugin-media).

In a Capacitor codebase, keeping Cordova Media for playback means:

  • one object per file with callback-based status codes (MEDIA_RUNNING, MEDIA_PAUSED, and similar)
  • duration and position updates driven by native messages instead of typed listeners
  • no built-in preload queue, Now Playing metadata, or playOnce helper for UI sounds

@capgo/capacitor-native-audio latest on npm is 8.5.4 with modified 13 November 2026. The legacy package @capgo/native-audio is 8.4.2. Capgo maintains the line for Capacitor 8 where a human still reviews, tests and merges 50+ pull requests daily.

Install

bun add @capgo/capacitor-native-audio
bunx cap sync

iOS: when you enable showNotification: true in configure(), read the README trade-off about interrupting background music versus mixing with other apps.

Android: background playback may require foreground service permissions listed in the plugin README when you set backgroundPlayback: true.

Usage example

import { NativeAudio } from '@capgo/capacitor-native-audio';

export async function playTrack(trackUrl: string) {
  await NativeAudio.configure({ focus: true, showNotification: true });

  await NativeAudio.preload({
    assetId: 'episode-1',
    assetPath: trackUrl,
    isUrl: true,
    notificationMetadata: { title: 'Episode 1', artist: 'Example Podcast' },
  });

  const progress = await NativeAudio.addListener('progress', (event) => {
    if (event.assetId === 'episode-1') {
      console.log(event.position, '/', event.duration);
    }
  });

  await NativeAudio.play({ assetId: 'episode-1' });

  await NativeAudio.addListener('complete', async (event) => {
    if (event.assetId === 'episode-1') {
      await progress.remove();
      await NativeAudio.unload({ assetId: 'episode-1' });
    }
  });
}

For short UI sounds, use playOnce({ assetPath: 'public/beep.mp3' }) instead of manual preload and unload.

Migrating from Cordova to Capacitor

Cordova playback keeps a Media instance and optional status callback. Capacitor uses a stable assetId string.

// Before (Cordova playback)
const media = new Media(
  'https://cdn.example.com/clip.mp3',
  () => console.log('done'),
  (code) => console.error(code),
  (status) => console.log('status', status),
);
media.play();
// After (Capacitor)
import { NativeAudio } from '@capgo/capacitor-native-audio';

await NativeAudio.preload({
  assetId: 'clip',
  assetPath: 'https://cdn.example.com/clip.mp3',
  isUrl: true,
});
await NativeAudio.addListener('playbackState', (event) => {
  if (event.assetId === 'clip') console.log(event.state, event.reason);
});
await NativeAudio.play({ assetId: 'clip' });

Do not migrate recording calls on the same Cordova Media object here. Point recording flows to @capgo/capacitor-audio-recorder instead of startRecord() on Media.

API mapping table (playback)

cordova-plugin-media (Media playback) @capgo/capacitor-native-audio
new Media(src, success, error, statusCb) preload({ assetId, assetPath, isUrl? }) then listeners
media.play(options) play({ assetId, time?, volume? })
media.pause() pause({ assetId })
media.stop() stop({ assetId })
Resume after pause resume({ assetId })
Looping (manual) loop({ assetId })
media.seekTo(milliseconds) setCurrentTime({ assetId, time: seconds })
media.getCurrentPosition(success, fail) getCurrentTime({ assetId }) returns { currentTime }
media.getDuration() cached field getDuration({ assetId }) returns { duration }
media.setVolume(volume) setVolume({ assetId, volume })
media.setRate(rate) (iOS/Android) setRate({ assetId, rate })
media.release() unload({ assetId })
statusCallback(MEDIA_*) addListener('playbackState', ...) and addListener('complete', ...)
Duration updates addListener('progress', ...) and addListener('currentTime', ...)
One-shot sound no direct helper
Cordova plugin install bun add @capgo/capacitor-native-audio plus bunx cap sync

Capgo adds queue APIs (setQueue, queueNext, queuePrevious) and route helpers (setSpeaker, setEarpiece, getAudioRoute) that Cordova Media does not document. Map them when you outgrow single-file playback.

Playback changes ship in a native binary, so plan a store build with Capgo Build. For the full Cordova to Capacitor move, read the migration guide.

Live updates for Capacitor apps

When a web-layer bug is live, ship the fix through Capgo instead of waiting days for app store approval. Users get the update in the background while native changes stay in the normal review path.

Latest from our Blog

Capgo gives you the best insights you need to create a truly professional mobile app.