@capgo/native-audio
Version:
A native plugin for native audio engine
1,090 lines • 31.6 kB
JSON
{
"api": {
"name": "NativeAudio",
"slug": "nativeaudio",
"docs": "",
"tags": [],
"methods": [
{
"name": "configure",
"signature": "(options: ConfigureOptions) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "ConfigureOptions"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "ConfigureOptions}"
},
{
"name": "returns"
}
],
"docs": "Configure the audio player",
"complexTypes": [
"ConfigureOptions"
],
"slug": "configure"
},
{
"name": "preload",
"signature": "(options: PreloadOptions) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "PreloadOptions"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "PreloadOptions}"
},
{
"name": "returns"
}
],
"docs": "Load an audio file",
"complexTypes": [
"PreloadOptions"
],
"slug": "preload"
},
{
"name": "playOnce",
"signature": "(options: PlayOnceOptions) => Promise<PlayOnceResult>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "PlayOnceOptions"
}
],
"returns": "Promise<PlayOnceResult>",
"tags": [
{
"name": "example",
"text": "```typescript\n// Simple one-shot playback\nawait NativeAudio.playOnce({ assetPath: 'audio/notification.mp3' });\n\n// Play and delete the file after completion\nawait NativeAudio.playOnce({\n assetPath: 'file:///path/to/temp/audio.mp3',\n isUrl: true,\n deleteAfterPlay: true\n});\n\n// Get the assetId to control playback\nconst { assetId } = await NativeAudio.playOnce({\n assetPath: 'audio/long-track.mp3',\n autoPlay: true\n});\n// Later, you can stop it manually if needed\nawait NativeAudio.stop({ assetId });\n```"
},
{
"name": "since",
"text": "7.11.0"
},
{
"name": "param",
"text": "options"
},
{
"name": "link",
"text": "PlayOnceOptions}"
},
{
"name": "returns",
"text": "Object containing the generated assetId"
}
],
"docs": "Play an audio file once with automatic cleanup\n\nMethod designed for simple, single-shot audio playback,\nsuch as notification sounds, UI feedback, or other short audio clips\nthat don't require manual state management.\n\n**Key Features:**\n- **Fire-and-forget**: No need to manually preload, play, stop, or unload\n- **Auto-cleanup**: Asset is automatically unloaded after playback completes\n- **Optional file deletion**: Can delete local files after playback (useful for temp files)\n- **Returns assetId**: Can still control playback if needed (pause, stop, etc.)\n\n**Use Cases:**\n- Notification sounds\n- UI sound effects (button clicks, alerts)\n- Short audio clips that play once\n- Temporary audio files that should be cleaned up\n\n**Comparison with regular play():**\n- `play()`: Requires manual preload, play, and unload steps\n- `playOnce()`: Handles everything automatically with a single call",
"complexTypes": [
"PlayOnceResult",
"PlayOnceOptions"
],
"slug": "playonce"
},
{
"name": "isPreloaded",
"signature": "(options: PreloadOptions) => Promise<{ found: boolean; }>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "PreloadOptions"
}
],
"returns": "Promise<{ found: boolean; }>",
"tags": [
{
"name": "since",
"text": "6.1.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "Assets}"
},
{
"name": "returns"
}
],
"docs": "Check if an audio file is preloaded",
"complexTypes": [
"PreloadOptions"
],
"slug": "ispreloaded"
},
{
"name": "play",
"signature": "(options: { assetId: string; time?: number; delay?: number; }) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "{ assetId: string; time?: number | undefined; delay?: number | undefined; }"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "PlayOptions}"
},
{
"name": "returns"
}
],
"docs": "Play an audio file",
"complexTypes": [],
"slug": "play"
},
{
"name": "pause",
"signature": "(options: Assets) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "Assets}"
},
{
"name": "returns"
}
],
"docs": "Pause an audio file",
"complexTypes": [
"Assets"
],
"slug": "pause"
},
{
"name": "resume",
"signature": "(options: Assets) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "Assets}"
},
{
"name": "returns"
}
],
"docs": "Resume an audio file",
"complexTypes": [
"Assets"
],
"slug": "resume"
},
{
"name": "loop",
"signature": "(options: Assets) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "Assets}"
},
{
"name": "returns"
}
],
"docs": "Stop an audio file",
"complexTypes": [
"Assets"
],
"slug": "loop"
},
{
"name": "stop",
"signature": "(options: Assets) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "Assets}"
},
{
"name": "returns"
}
],
"docs": "Stop an audio file",
"complexTypes": [
"Assets"
],
"slug": "stop"
},
{
"name": "unload",
"signature": "(options: Assets) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "Assets}"
},
{
"name": "returns"
}
],
"docs": "Unload an audio file",
"complexTypes": [
"Assets"
],
"slug": "unload"
},
{
"name": "setVolume",
"signature": "(options: { assetId: string; volume: number; }) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "{ assetId: string; volume: number; }"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "AssetVolume}"
},
{
"name": "returns"
}
],
"docs": "Set the volume of an audio file",
"complexTypes": [],
"slug": "setvolume"
},
{
"name": "setRate",
"signature": "(options: { assetId: string; rate: number; }) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "{ assetId: string; rate: number; }"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "AssetPlayOptions}"
},
{
"name": "returns"
}
],
"docs": "Set the rate of an audio file",
"complexTypes": [],
"slug": "setrate"
},
{
"name": "setCurrentTime",
"signature": "(options: { assetId: string; time: number; }) => Promise<void>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "{ assetId: string; time: number; }"
}
],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "6.5.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "AssetPlayOptions}"
},
{
"name": "returns"
}
],
"docs": "Set the current time of an audio file",
"complexTypes": [],
"slug": "setcurrenttime"
},
{
"name": "getCurrentTime",
"signature": "(options: { assetId: string; }) => Promise<{ currentTime: number; }>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "{ assetId: string; }"
}
],
"returns": "Promise<{ currentTime: number; }>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "AssetPlayOptions}"
},
{
"name": "returns"
}
],
"docs": "Get the current time of an audio file",
"complexTypes": [],
"slug": "getcurrenttime"
},
{
"name": "getDuration",
"signature": "(options: Assets) => Promise<{ duration: number; }>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<{ duration: number; }>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "AssetPlayOptions}"
},
{
"name": "returns"
}
],
"docs": "Get the duration of an audio file",
"complexTypes": [
"Assets"
],
"slug": "getduration"
},
{
"name": "isPlaying",
"signature": "(options: Assets) => Promise<{ isPlaying: boolean; }>",
"parameters": [
{
"name": "options",
"docs": "",
"type": "Assets"
}
],
"returns": "Promise<{ isPlaying: boolean; }>",
"tags": [
{
"name": "since",
"text": "5.0.0"
},
{
"name": "param",
"text": "option"
},
{
"name": "link",
"text": "AssetPlayOptions}"
},
{
"name": "returns"
}
],
"docs": "Check if an audio file is playing",
"complexTypes": [
"Assets"
],
"slug": "isplaying"
},
{
"name": "addListener",
"signature": "(eventName: 'complete', listenerFunc: CompletedListener) => Promise<PluginListenerHandle>",
"parameters": [
{
"name": "eventName",
"docs": "",
"type": "'complete'"
},
{
"name": "listenerFunc",
"docs": "",
"type": "CompletedListener"
}
],
"returns": "Promise<PluginListenerHandle>",
"tags": [
{
"name": "since",
"text": "5.0.0\nreturn {@link CompletedEvent}"
}
],
"docs": "Listen for complete event",
"complexTypes": [
"PluginListenerHandle",
"CompletedListener"
],
"slug": "addlistenercomplete-"
},
{
"name": "addListener",
"signature": "(eventName: 'currentTime', listenerFunc: CurrentTimeListener) => Promise<PluginListenerHandle>",
"parameters": [
{
"name": "eventName",
"docs": "",
"type": "'currentTime'"
},
{
"name": "listenerFunc",
"docs": "",
"type": "CurrentTimeListener"
}
],
"returns": "Promise<PluginListenerHandle>",
"tags": [
{
"name": "since",
"text": "6.5.0\nreturn {@link CurrentTimeEvent}"
}
],
"docs": "Listen for current time updates\nEmits every 100ms while audio is playing",
"complexTypes": [
"PluginListenerHandle",
"CurrentTimeListener"
],
"slug": "addlistenercurrenttime-"
},
{
"name": "clearCache",
"signature": "() => Promise<void>",
"parameters": [],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "6.5.0"
},
{
"name": "returns"
}
],
"docs": "Clear the audio cache for remote audio files",
"complexTypes": [],
"slug": "clearcache"
},
{
"name": "getPluginVersion",
"signature": "() => Promise<{ version: string; }>",
"parameters": [],
"returns": "Promise<{ version: string; }>",
"tags": [
{
"name": "returns",
"text": "an Promise with version for this device"
},
{
"name": "throws",
"text": "An error if the something went wrong"
}
],
"docs": "Get the native Capacitor plugin version",
"complexTypes": [],
"slug": "getpluginversion"
},
{
"name": "deinitPlugin",
"signature": "() => Promise<void>",
"parameters": [],
"returns": "Promise<void>",
"tags": [
{
"name": "since",
"text": "7.7.0"
},
{
"name": "returns"
}
],
"docs": "Deinitialize the plugin and restore original audio session settings\nThis method stops all playing audio and reverts any audio session changes made by the plugin\nUse this when you need to ensure compatibility with other audio plugins",
"complexTypes": [],
"slug": "deinitplugin"
}
],
"properties": []
},
"interfaces": [
{
"name": "ConfigureOptions",
"slug": "configureoptions",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "fade",
"tags": [],
"docs": "Play the audio with Fade effect, only available for IOS",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "focus",
"tags": [],
"docs": "focus the audio with Audio Focus",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "background",
"tags": [],
"docs": "Play the audio in the background",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "ignoreSilent",
"tags": [],
"docs": "Ignore silent mode, works only on iOS setting this will nuke other audio apps",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "showNotification",
"tags": [
{
"text": "https ://github.com/Cap-go/capacitor-native-audio/issues/202",
"name": "see"
}
],
"docs": "Show audio playback in the notification center (iOS and Android)\nWhen enabled, displays audio metadata (title, artist, album, artwork) in the system notification\nand Control Center (iOS) or lock screen.\n\n**Important iOS Behavior:**\nEnabling this option changes the audio session category to `.playback` with `.default` mode,\nwhich means your app's audio will **interrupt** other apps' audio (like background music from\nSpotify, Apple Music, etc.) instead of mixing with it. This is required for the Now Playing\ninfo to appear in Control Center and on the lock screen.\n\n**Trade-offs:**\n- `showNotification: true` → Shows Now Playing controls, but interrupts other audio\n- `showNotification: false` → Audio mixes with other apps, but no Now Playing controls\n\nUse this when your app is the primary audio source (music players, podcast apps, etc.).\nDisable this for secondary audio like sound effects or notification sounds where mixing\nwith background music is preferred.",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "backgroundPlayback",
"tags": [
{
"text": "false",
"name": "default"
},
{
"text": "Android",
"name": "platform"
},
{
"text": "8.2.0",
"name": "since"
}
],
"docs": "Enable background audio playback (Android only)\n\nWhen enabled, audio will continue playing when the app is backgrounded or the screen is locked.\nThe plugin will skip the automatic pause/resume logic that normally occurs when the app\nenters the background or returns to the foreground.\n\n**Important Android Requirements:**\nTo use background playback on Android, your app must:\n1. Declare the required permissions in `AndroidManifest.xml`:\n - `<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE\" />`\n - `<uses-permission android:name=\"android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK\" />`\n - `<uses-permission android:name=\"android.permission.WAKE_LOCK\" />`\n2. Start a Foreground Service with a media-style notification before backgrounding\n (the plugin does not automatically create or manage the foreground service)\n3. Use `showNotification: true` to display playback controls in the notification\n\n**Usage Example:**\n```typescript\nawait NativeAudio.configure({\n backgroundPlayback: true,\n showNotification: true\n});\n// Start your foreground service here\n// Then preload and play audio as normal\n```",
"complexTypes": [],
"type": "boolean | undefined"
}
]
},
{
"name": "PreloadOptions",
"slug": "preloadoptions",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "assetPath",
"tags": [],
"docs": "Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)\nSupported formats:\n- MP3, WAV (all platforms)\n- M3U8/HLS streams (iOS and Android)",
"complexTypes": [],
"type": "string"
},
{
"name": "assetId",
"tags": [],
"docs": "Asset Id, unique identifier of the file",
"complexTypes": [],
"type": "string"
},
{
"name": "volume",
"tags": [],
"docs": "Volume of the audio, between 0.1 and 1.0",
"complexTypes": [],
"type": "number | undefined"
},
{
"name": "audioChannelNum",
"tags": [],
"docs": "Audio channel number, default is 1",
"complexTypes": [],
"type": "number | undefined"
},
{
"name": "isUrl",
"tags": [],
"docs": "Is the audio file a URL, pass true if assetPath is a `file://` url\nor a streaming URL (m3u8)",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "notificationMetadata",
"tags": [
{
"text": "NotificationMetadata",
"name": "see"
}
],
"docs": "Metadata to display in the notification center when audio is playing.\nOnly used when `showNotification: true` is set in `configure()`.\n\nSee {@link ConfigureOptions.showNotification} for important details about\nhow this affects audio mixing behavior on iOS.",
"complexTypes": [
"NotificationMetadata"
],
"type": "NotificationMetadata"
},
{
"name": "headers",
"tags": [
{
"text": "7.10.0",
"name": "since"
}
],
"docs": "Custom HTTP headers to include when fetching remote audio files.\nOnly used when isUrl is true and assetPath is a remote URL (http/https).\nExample: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }",
"complexTypes": [
"Record"
],
"type": "Record<string, string>"
}
]
},
{
"name": "NotificationMetadata",
"slug": "notificationmetadata",
"docs": "Metadata to display in the notification center, Control Center (iOS), and lock screen\nwhen `showNotification` is enabled in `configure()`.\n\nNote: This metadata will only be displayed if `showNotification: true` is set in the\n`configure()` method. See {@link ConfigureOptions.showNotification} for important\nbehavior details about audio mixing on iOS.",
"tags": [],
"methods": [],
"properties": [
{
"name": "title",
"tags": [],
"docs": "The title to display in the notification center",
"complexTypes": [],
"type": "string | undefined"
},
{
"name": "artist",
"tags": [],
"docs": "The artist name to display in the notification center",
"complexTypes": [],
"type": "string | undefined"
},
{
"name": "album",
"tags": [],
"docs": "The album name to display in the notification center",
"complexTypes": [],
"type": "string | undefined"
},
{
"name": "artworkUrl",
"tags": [],
"docs": "URL or local path to the artwork/album art image",
"complexTypes": [],
"type": "string | undefined"
}
]
},
{
"name": "PlayOnceResult",
"slug": "playonceresult",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "assetId",
"tags": [],
"docs": "The internally generated asset ID for this playback\nCan be used to control playback (pause, stop, etc.) before completion",
"complexTypes": [],
"type": "string"
}
]
},
{
"name": "PlayOnceOptions",
"slug": "playonceoptions",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "assetPath",
"tags": [],
"docs": "Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)\nSupported formats:\n- MP3, WAV (all platforms)\n- M3U8/HLS streams (iOS and Android)",
"complexTypes": [],
"type": "string"
},
{
"name": "volume",
"tags": [
{
"text": "1.0",
"name": "default"
}
],
"docs": "Volume of the audio, between 0.1 and 1.0",
"complexTypes": [],
"type": "number | undefined"
},
{
"name": "isUrl",
"tags": [
{
"text": "false",
"name": "default"
}
],
"docs": "Is the audio file a URL, pass true if assetPath is a `file://` url\nor a streaming URL (m3u8)",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "autoPlay",
"tags": [
{
"text": "true",
"name": "default"
}
],
"docs": "Automatically start playback after loading",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "deleteAfterPlay",
"tags": [
{
"text": "false",
"name": "default"
},
{
"text": "7.11.0",
"name": "since"
}
],
"docs": "Delete the audio file from disk after playback completes\nOnly works for local files (file:// URLs), ignored for remote URLs",
"complexTypes": [],
"type": "boolean | undefined"
},
{
"name": "notificationMetadata",
"tags": [
{
"text": "NotificationMetadata *",
"name": "see"
},
{
"text": "7.10.0",
"name": "since"
}
],
"docs": "Metadata to display in the notification center when audio is playing.\nOnly used when `showNotification: true` is set in `configure()`.\n\nSee {@link ConfigureOptions.showNotification} for important details about\nhow this affects audio mixing behavior on iOS.",
"complexTypes": [
"NotificationMetadata"
],
"type": "NotificationMetadata"
},
{
"name": "headers",
"tags": [
{
"text": "7.10.0",
"name": "since"
}
],
"docs": "Custom HTTP headers to include when fetching remote audio files.\nOnly used when isUrl is true and assetPath is a remote URL (http/https).\nExample: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }",
"complexTypes": [
"Record"
],
"type": "Record<string, string>"
}
]
},
{
"name": "Assets",
"slug": "assets",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "assetId",
"tags": [],
"docs": "Asset Id, unique identifier of the file",
"complexTypes": [],
"type": "string"
}
]
},
{
"name": "PluginListenerHandle",
"slug": "pluginlistenerhandle",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "remove",
"tags": [],
"docs": "",
"complexTypes": [],
"type": "() => Promise<void>"
}
]
},
{
"name": "CompletedEvent",
"slug": "completedevent",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "assetId",
"tags": [
{
"text": "5.0.0",
"name": "since"
}
],
"docs": "Emit when a play completes",
"complexTypes": [],
"type": "string"
}
]
},
{
"name": "CurrentTimeEvent",
"slug": "currenttimeevent",
"docs": "",
"tags": [],
"methods": [],
"properties": [
{
"name": "currentTime",
"tags": [
{
"text": "6.5.0",
"name": "since"
}
],
"docs": "Current time of the audio in seconds",
"complexTypes": [],
"type": "number"
},
{
"name": "assetId",
"tags": [
{
"text": "6.5.0",
"name": "since"
}
],
"docs": "Asset Id of the audio",
"complexTypes": [],
"type": "string"
}
]
}
],
"enums": [],
"typeAliases": [
{
"name": "Record",
"slug": "record",
"docs": "Construct a type with a set of properties K of type T",
"types": [
{
"text": "{\r\n [P in K]: T;\r\n}",
"complexTypes": [
"K",
"T"
]
}
]
},
{
"name": "CompletedListener",
"slug": "completedlistener",
"docs": "",
"types": [
{
"text": "(state: CompletedEvent): void",
"complexTypes": [
"CompletedEvent"
]
}
]
},
{
"name": "CurrentTimeListener",
"slug": "currenttimelistener",
"docs": "",
"types": [
{
"text": "(state: CurrentTimeEvent): void",
"complexTypes": [
"CurrentTimeEvent"
]
}
]
}
],
"pluginConfigs": []
}