Skip to content

@capgo/capacitor-native-audio

Low latency sound effects and streaming audio with preload, Now Playing controls, and background playback options.

Playlist queue

setQueue, queueNext, queuePrevious, queueSelect, getQueueState, clearQueue, and the queueChange listener for ordered tracks. Lock screen and notification skip next/previous on iOS and Android with showNotification.

Playback snapshot

getPlaybackState returns playing, paused, or stopped with position and duration for UI rehydration. If the asset is currently playing, the live element state wins over a stale tracked snapshot. Otherwise the snapshot matches the last playbackState event for that asset. getRate reads the current speed set with setRate. On Web, play recreates the audio element and resets the rate, so call setRate after play.

Progress events

The progress listener fires on an interval from configure({ progressInterval }) (default 0.5s) for scrubbers and chapter UI.

Audio routing

Native setSpeaker, setEarpiece, and getAudioRoute on iOS and Android. Successful setSpeaker and setEarpiece calls emit audioRouteChange, even when the route does not change (repeated Web calls still emit). The event does not fire when headphones or Bluetooth connect on their own. On Android, getAudioRoute reports earpiece only in communication mode after setEarpiece; otherwise it reports speaker when no headset or Bluetooth is connected. On Web, setSpeaker emits audioRouteChange with speaker, setEarpiece emits it with earpiece, and getAudioRoute returns the last requested route (speaker after setSpeaker, earpiece after setEarpiece). The web platform cannot change the actual output.

Use @capgo/capacitor-native-audio when your Capacitor app needs responsive playback for UI sounds, short clips, or music style sessions without juggling multiple native audio APIs. Preload assets, loop tracks, fade volume, stream remote URLs or HLS, and optionally show lock screen transport controls.

Typical fits: game SFX, notification chimes, guided meditation, podcast players, and any flow that must coexist with other apps on the device audio session.

PlatformSupportNotes
iOSYesAVFoundation, optional Now Playing and audio session categories
AndroidYesMedia playback, notifications, optional foreground service for background
WebPartialCore playback; playbackState and progress on web; queue and routing APIs resolve with platform limits
  • configure - Configure the audio player.
  • preload - Load an audio file.
  • playOnce - Play an audio file once with automatic cleanup.
  • isPreloaded - Check if an audio file is preloaded.
MethodDescription
configureConfigure the audio player.
preloadLoad an audio file.
playOncePlay an audio file once with automatic cleanup.
isPreloadedCheck if an audio file is preloaded.
playPlay an audio file.
pausePause an audio file.
resumeResume an audio file.
loopStop an audio file.
stopStop an audio file.
unloadUnload an audio file.
setVolumeSet the volume of an audio file.
setRateSet the rate of an audio file.
setCurrentTimeSet the current time of an audio file.
getCurrentTimeGet the current time of an audio file.
getDurationGet the duration of an audio file in seconds.
getPlaybackStateSnapshot of playback for UI rehydration after navigation or missed events. If the asset is playing, the live state wins; otherwise the tracked snapshot is used to tell stopped from paused.
getRateCurrent playback rate for the given asset (same value set with setRate). On Web, play recreates the audio element and resets the rate; call setRate after play.
setQueuePrepare an ordered queue; reuses preloaded assets when ids match.
clearQueueClear the active queue.
getQueueStateActive queue item, index, count, and ordered asset ids.
queueNextSelect the next queue item. Stops the outgoing item and starts the selected item.
queuePreviousSelect the previous queue item. Stops the outgoing item and starts the selected item.
queueSelectJump to a queue item by assetId. Stops the outgoing item and starts the selected item.
setSpeakerPrefer built-in speaker (iOS, Android). On Web, emits audioRouteChange with speaker (not a no-op).
setEarpieceRoute call-style audio to the earpiece (iOS, Android). On Web, emits audioRouteChange with earpiece (not a no-op).
getAudioRouteActive route: speaker, earpiece, or external. On Android, earpiece is reported only in communication mode after setEarpiece; otherwise speaker when no headset or Bluetooth is connected. On Web, returns the last requested route (speaker after setSpeaker, earpiece after setEarpiece). The web platform cannot change the actual output.
isPlayingCheck if an audio file is playing.
addListenerListen for complete event.
addListenerListen for current time updates Emits every 100ms while audio is playing.
addListenerListen for playback state changes, including notification and lock-screen transport controls on iOS and Android. Emitted on Android, iOS, and Web when plugin transport methods change playback state, including play, pause, resume, loop, and complete.
addListenerListen for coarse progress events; interval from configure({ progressInterval }).
addListenerListen for queueChange when the active queue item changes, including Web setQueue with autoPlay: true (reason setQueue).
addListenerListen for audioRouteChange when a successful setSpeaker or setEarpiece call emits the event, even if the route does not change. Does not fire for system route changes such as headphones or Bluetooth. Emitted on iOS, Android, and Web (setSpeaker reports speaker, setEarpiece reports earpiece).
clearCacheClear the audio cache for remote audio files.
setDebugModeSet debug mode logging.
getPluginVersionGet the native Capacitor plugin version.
deinitPluginDeinitialize the plugin and restore original audio session settings This method stops all playing audio and reverts any audio session changes made by the plugin Use this when you need to ensure compatibility with other audio plugins.

This reference is synced from src/definitions.ts in capacitor-native-audio.

Keep going from @capgo/capacitor-native-audio

Section titled “Keep going from @capgo/capacitor-native-audio”

If you are using @capgo/capacitor-native-audio to plan native media and interface behavior, connect it with Using @capgo/capacitor-native-audio for the native capability in Using @capgo/capacitor-native-audio, Using @capgo/capacitor-live-activities for the native capability in Using @capgo/capacitor-live-activities, @capgo/capacitor-live-activities for the implementation detail in @capgo/capacitor-live-activities, Using @capgo/capacitor-video-player for the native capability in Using @capgo/capacitor-video-player, and @capgo/capacitor-video-player for the implementation detail in @capgo/capacitor-video-player.