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.
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.
| Platform | Support | Notes |
|---|---|---|
| iOS | Yes | AVFoundation, optional Now Playing and audio session categories |
| Android | Yes | Media playback, notifications, optional foreground service for background |
| Web | Partial | Core 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.| Method | Description |
|---|---|
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. |
play | Play an audio file. |
pause | Pause an audio file. |
resume | Resume an audio file. |
loop | Stop an audio file. |
stop | Stop an audio file. |
unload | Unload an audio file. |
setVolume | Set the volume of an audio file. |
setRate | Set the rate of an audio file. |
setCurrentTime | Set the current time of an audio file. |
getCurrentTime | Get the current time of an audio file. |
getDuration | Get the duration of an audio file in seconds. |
getPlaybackState | Snapshot 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. |
getRate | Current 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. |
setQueue | Prepare an ordered queue; reuses preloaded assets when ids match. |
clearQueue | Clear the active queue. |
getQueueState | Active queue item, index, count, and ordered asset ids. |
queueNext | Select the next queue item. Stops the outgoing item and starts the selected item. |
queuePrevious | Select the previous queue item. Stops the outgoing item and starts the selected item. |
queueSelect | Jump to a queue item by assetId. Stops the outgoing item and starts the selected item. |
setSpeaker | Prefer built-in speaker (iOS, Android). On Web, emits audioRouteChange with speaker (not a no-op). |
setEarpiece | Route call-style audio to the earpiece (iOS, Android). On Web, emits audioRouteChange with earpiece (not a no-op). |
getAudioRoute | Active 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. |
isPlaying | Check if an audio file is playing. |
addListener | Listen for complete event. |
addListener | Listen for current time updates Emits every 100ms while audio is playing. |
addListener | Listen 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. |
addListener | Listen for coarse progress events; interval from configure({ progressInterval }). |
addListener | Listen for queueChange when the active queue item changes, including Web setQueue with autoPlay: true (reason setQueue). |
addListener | Listen 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). |
clearCache | Clear the audio cache for remote audio files. |
setDebugMode | Set debug mode logging. |
getPluginVersion | Get the native Capacitor plugin version. |
deinitPlugin | Deinitialize 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.
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.