@capgo/native-audio 8.1.10 → 8.2.0

package/README.md

@@ -243,6 +243,97 @@ The media control buttons automatically handle:
 - iOS: Uses MPNowPlayingInfoCenter with MPRemoteCommandCenter
 - Android: Uses MediaSession with NotificationCompat.MediaStyle
 
+### Android Background Playback @since 8.2.0
+
+By default, Android apps pause audio when the app is backgrounded or the screen is locked. To enable continuous audio playback in the background (for meditation apps, music players, podcast players, etc.), use the `backgroundPlayback` flag.
+
+> **⚠️ Important Android Requirements**
+> 
+> To use background playback on Android, your app must meet these requirements:
+> 1. Declare the required permissions in `AndroidManifest.xml`
+> 2. Start an Android Foreground Service with a media notification
+> 3. Configure the plugin with `backgroundPlayback: true`
+
+**Step 1: Add required permissions to `AndroidManifest.xml`**
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+    <!-- Required for background audio playback -->
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+    <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+    <uses-permission android:name="android.permission.WAKE_LOCK" />
+    
+    <application>
+        <!-- Your app configuration -->
+    </application>
+</manifest>
+```
+
+**Step 2: Configure the plugin with background playback enabled**
+
+```typescript
+import { NativeAudio } from '@capgo/native-audio';
+
+// Enable background playback and notification center
+await NativeAudio.configure({
+  backgroundPlayback: true,  // Prevent automatic pause when backgrounded
+  showNotification: true,    // Show playback controls in notification
+  focus: true                // Request audio focus (optional but recommended)
+});
+```
+
+**Step 3: Start a Foreground Service (your responsibility)**
+
+The plugin does NOT automatically create or manage the Android Foreground Service. You must create and start your own foreground service using a Capacitor plugin like [`@capacitor/local-notifications`](https://capacitorjs.com/docs/apis/local-notifications) or a custom Android service.
+
+Here's a conceptual example:
+
+```typescript
+// 1. Configure the audio plugin
+await NativeAudio.configure({
+  backgroundPlayback: true,
+  showNotification: true
+});
+
+// 2. Start your foreground service (implementation depends on your app)
+// This is typically done with a native Android service or a plugin
+// that provides foreground service capabilities
+await startForegroundService();
+
+// 3. Preload and play audio as normal
+await NativeAudio.preload({
+  assetId: 'meditation',
+  assetPath: 'audio/meditation.mp3',
+  notificationMetadata: {
+    title: 'Meditation Session',
+    artist: 'Your App Name'
+  }
+});
+
+await NativeAudio.play({ assetId: 'meditation' });
+
+// Audio will continue playing when app is backgrounded
+// The foreground service ensures Android allows background playback
+```
+
+**Important timing notes:**
+- The foreground service should be started **before** the app enters the background
+- Start the service immediately after configuring the audio plugin and before playing audio
+- If the foreground service is not running, Android may still kill your audio playback
+
+**How it works:**
+- Without `backgroundPlayback: true`: The plugin automatically pauses all audio when the app enters the background
+- With `backgroundPlayback: true`: The plugin skips automatic pause/resume, allowing continuous playback
+
+**Important notes:**
+- This flag is **Android-only** (iOS already supports background playback via AVAudioSession)
+- You **must** start an Android Foreground Service separately (plugin does not handle this)
+- Combine with `showNotification: true` to display playback controls
+- Starting Android 14+, foreground services require the `FOREGROUND_SERVICE_MEDIA_PLAYBACK` permission type
+
+**Alternative approach:**
+If you need a complete solution including foreground service management, consider using a dedicated media playback plugin or implementing a custom Android service in your app's native code.
+
 ## Play Once (Fire-and-Forget) @since 7.11.0
 
 For simple one-shot audio playback (sound effects, notifications, etc.), use `playOnce()` which handles the entire asset lifecycle automatically:
@@ -825,13 +916,14 @@ Use this when you need to ensure compatibility with other audio plugins
 
 #### ConfigureOptions
 
-| Prop                   | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
-| ---------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`fade`**             | <code>boolean</code> | Play the audio with Fade effect, only available for IOS                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
-| **`focus`**            | <code>boolean</code> | focus the audio with Audio Focus                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| **`background`**       | <code>boolean</code> | Play the audio in the background                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
-| **`ignoreSilent`**     | <code>boolean</code> | Ignore silent mode, works only on iOS setting this will nuke other audio apps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
-| **`showNotification`** | <code>boolean</code> | Show audio playback in the notification center (iOS and Android) When enabled, displays audio metadata (title, artist, album, artwork) in the system notification and Control Center (iOS) or lock screen. **Important iOS Behavior:** Enabling this option changes the audio session category to `.playback` with `.default` mode, which means your app's audio will **interrupt** other apps' audio (like background music from Spotify, Apple Music, etc.) instead of mixing with it. This is required for the Now Playing info to appear in Control Center and on the lock screen. **Trade-offs:** - `showNotification: true` → Shows Now Playing controls, but interrupts other audio - `showNotification: false` → Audio mixes with other apps, but no Now Playing controls Use this when your app is the primary audio source (music players, podcast apps, etc.). Disable this for secondary audio like sound effects or notification sounds where mixing with background music is preferred. |
+| Prop                     | Type                 | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | Default            | Since |
+| ------------------------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ----- |
+| **`fade`**               | <code>boolean</code> | Play the audio with Fade effect, only available for IOS                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |                    |       |
+| **`focus`**              | <code>boolean</code> | focus the audio with Audio Focus                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                    |       |
+| **`background`**         | <code>boolean</code> | Play the audio in the background                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |                    |       |
+| **`ignoreSilent`**       | <code>boolean</code> | Ignore silent mode, works only on iOS setting this will nuke other audio apps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |                    |       |
+| **`showNotification`**   | <code>boolean</code> | Show audio playback in the notification center (iOS and Android) When enabled, displays audio metadata (title, artist, album, artwork) in the system notification and Control Center (iOS) or lock screen. **Important iOS Behavior:** Enabling this option changes the audio session category to `.playback` with `.default` mode, which means your app's audio will **interrupt** other apps' audio (like background music from Spotify, Apple Music, etc.) instead of mixing with it. This is required for the Now Playing info to appear in Control Center and on the lock screen. **Trade-offs:** - `showNotification: true` → Shows Now Playing controls, but interrupts other audio - `showNotification: false` → Audio mixes with other apps, but no Now Playing controls Use this when your app is the primary audio source (music players, podcast apps, etc.). Disable this for secondary audio like sound effects or notification sounds where mixing with background music is preferred.                                                                                                                                                                     |                    |       |
+| **`backgroundPlayback`** | <code>boolean</code> | Enable background audio playback (Android only) When enabled, audio will continue playing when the app is backgrounded or the screen is locked. The plugin will skip the automatic pause/resume logic that normally occurs when the app enters the background or returns to the foreground. **Important Android Requirements:** To use background playback on Android, your app must: 1. Declare the required permissions in `AndroidManifest.xml`: - `&lt;uses-permission android:name="android.permission.FOREGROUND_SERVICE" /&gt;` - `&lt;uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" /&gt;` - `&lt;uses-permission android:name="android.permission.WAKE_LOCK" /&gt;` 2. Start a Foreground Service with a media-style notification before backgrounding (the plugin does not automatically create or manage the foreground service) 3. Use `showNotification: true` to display playback controls in the notification **Usage Example:** ```typescript await NativeAudio.configure({ backgroundPlayback: true, showNotification: true }); // Start your foreground service here // Then preload and play audio as normal ``` | <code>false</code> | 8.2.0 |
 
 
 #### PreloadOptions

package/android/build.gradle

@@ -80,7 +80,7 @@ dependencies {
 
     implementation 'androidx.media3:media3-session:1.9.0'
     implementation 'androidx.media3:media3-transformer:1.9.0'
-    implementation 'androidx.media3:media3-ui:1.8.0'
+    implementation 'androidx.media3:media3-ui:1.9.0'
     implementation 'androidx.media3:media3-database:1.9.0'
     implementation 'androidx.media3:media3-common:1.9.0'
     // Media notification support

package/android/src/main/java/ee/forgr/audio/NativeAudio.java

@@ -90,6 +90,9 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
     // Track playOnce assets for automatic cleanup
     private Set<String> playOnceAssets = new HashSet<>();
 
+    // Background playback support
+    private boolean backgroundPlayback = false;
+
     /**
      * Initializes plugin runtime state by obtaining the system {@link AudioManager}, preparing the asset map,
      * and recording the device's original audio mode without requesting audio focus.
@@ -143,6 +146,12 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
     protected void handleOnPause() {
         super.handleOnPause();
 
+        // Skip automatic pause when background playback is enabled
+        if (backgroundPlayback) {
+            Log.d(TAG, "Background playback enabled - skipping automatic pause");
+            return;
+        }
+
         try {
             if (audioAssetList != null) {
                 for (HashMap.Entry<String, AudioAsset> entry : audioAssetList.entrySet()) {
@@ -166,6 +175,12 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
     protected void handleOnResume() {
         super.handleOnResume();
 
+        // Skip automatic resume when background playback is enabled
+        if (backgroundPlayback) {
+            Log.d(TAG, "Background playback enabled - skipping automatic resume");
+            return;
+        }
+
         try {
             if (resumeList != null) {
                 while (!resumeList.isEmpty()) {
@@ -199,6 +214,7 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
         boolean background = call.getBoolean("background", false);
         this.fadeMusic = call.getBoolean("fade", false);
         this.showNotification = call.getBoolean(SHOW_NOTIFICATION, false);
+        this.backgroundPlayback = call.getBoolean("backgroundPlayback", false);
 
         try {
             if (focus) {

package/dist/docs.json

@@ -708,6 +708,26 @@
           "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"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -87,6 +87,38 @@ export interface ConfigureOptions {
      * @see https://github.com/Cap-go/capacitor-native-audio/issues/202
      */
     showNotification?: boolean;
+    /**
+     * Enable background audio playback (Android only)
+     *
+     * When enabled, audio will continue playing when the app is backgrounded or the screen is locked.
+     * The plugin will skip the automatic pause/resume logic that normally occurs when the app
+     * enters the background or returns to the foreground.
+     *
+     * **Important Android Requirements:**
+     * To use background playback on Android, your app must:
+     * 1. Declare the required permissions in `AndroidManifest.xml`:
+     *    - `<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />`
+     *    - `<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />`
+     *    - `<uses-permission android:name="android.permission.WAKE_LOCK" />`
+     * 2. Start a Foreground Service with a media-style notification before backgrounding
+     *    (the plugin does not automatically create or manage the foreground service)
+     * 3. Use `showNotification: true` to display playback controls in the notification
+     *
+     * **Usage Example:**
+     * ```typescript
+     * await NativeAudio.configure({
+     *   backgroundPlayback: true,
+     *   showNotification: true
+     * });
+     * // Start your foreground service here
+     * // Then preload and play audio as normal
+     * ```
+     *
+     * @default false
+     * @platform Android
+     * @since 8.2.0
+     */
+    backgroundPlayback?: boolean;
 }
 /**
  * Metadata to display in the notification center, Control Center (iOS), and lock screen

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\nexport interface CompletedEvent {\n  /**\n   * Emit when a play completes\n   *\n   * @since  5.0.0\n   */\n  assetId: string;\n}\nexport type CompletedListener = (state: CompletedEvent) => void;\nexport interface Assets {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n}\nexport interface AssetVolume {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   */\n  volume: number;\n}\n\nexport interface AssetRate {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Rate of the audio, between 0.1 and 1.0\n   */\n  rate: number;\n}\n\nexport interface AssetPlayOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Time to start playing the audio, in milliseconds\n   */\n  time?: number;\n  /**\n   * Delay to start playing the audio, in milliseconds\n   */\n  delay?: number;\n}\n\nexport interface ConfigureOptions {\n  /**\n   * Play the audio with Fade effect, only available for IOS\n   */\n  fade?: boolean;\n  /**\n   * focus the audio with Audio Focus\n   */\n  focus?: boolean;\n  /**\n   * Play the audio in the background\n   */\n  background?: boolean;\n  /**\n   * Ignore silent mode, works only on iOS setting this will nuke other audio apps\n   */\n  ignoreSilent?: boolean;\n  /**\n   * Show audio playback in the notification center (iOS and Android)\n   * When enabled, displays audio metadata (title, artist, album, artwork) in the system notification\n   * and Control Center (iOS) or lock screen.\n   *\n   * **Important iOS Behavior:**\n   * Enabling this option changes the audio session category to `.playback` with `.default` mode,\n   * which means your app's audio will **interrupt** other apps' audio (like background music from\n   * Spotify, Apple Music, etc.) instead of mixing with it. This is required for the Now Playing\n   * info 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   *\n   * Use this when your app is the primary audio source (music players, podcast apps, etc.).\n   * Disable this for secondary audio like sound effects or notification sounds where mixing\n   * with background music is preferred.\n   *\n   * @see https://github.com/Cap-go/capacitor-native-audio/issues/202\n   */\n  showNotification?: boolean;\n}\n\n/**\n * Metadata to display in the notification center, Control Center (iOS), and lock screen\n * when `showNotification` is enabled in `configure()`.\n *\n * Note: This metadata will only be displayed if `showNotification: true` is set in the\n * `configure()` method. See {@link ConfigureOptions.showNotification} for important\n * behavior details about audio mixing on iOS.\n */\nexport interface NotificationMetadata {\n  /**\n   * The title to display in the notification center\n   */\n  title?: string;\n  /**\n   * The artist name to display in the notification center\n   */\n  artist?: string;\n  /**\n   * The album name to display in the notification center\n   */\n  album?: string;\n  /**\n   * URL or local path to the artwork/album art image\n   */\n  artworkUrl?: string;\n}\n\nexport interface PlayOnceOptions {\n  /**\n   * Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)\n   * Supported formats:\n   * - MP3, WAV (all platforms)\n   * - M3U8/HLS streams (iOS and Android)\n   */\n  assetPath: string;\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   * @default 1.0\n   */\n  volume?: number;\n  /**\n   * Is the audio file a URL, pass true if assetPath is a `file://` url\n   * or a streaming URL (m3u8)\n   * @default false\n   */\n  isUrl?: boolean;\n  /**\n   * Automatically start playback after loading\n   * @default true\n   */\n  autoPlay?: boolean;\n  /**\n   * Delete the audio file from disk after playback completes\n   * Only works for local files (file:// URLs), ignored for remote URLs\n   * @default false\n   * @since 7.11.0\n   */\n  deleteAfterPlay?: boolean;\n  /**\n   * Metadata to display in the notification center when audio is playing.\n   * Only used when `showNotification: true` is set in `configure()`.\n   *\n   * See {@link ConfigureOptions.showNotification} for important details about\n   * how this affects audio mixing behavior on iOS.\n   *\n   * @see NotificationMetadata\n   * @since 7.10.0\n   */\n  notificationMetadata?: NotificationMetadata;\n  /**\n   * Custom HTTP headers to include when fetching remote audio files.\n   * Only used when isUrl is true and assetPath is a remote URL (http/https).\n   * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }\n   *\n   * @since 7.10.0\n   */\n  headers?: Record<string, string>;\n}\n\nexport interface PlayOnceResult {\n  /**\n   * The internally generated asset ID for this playback\n   * Can be used to control playback (pause, stop, etc.) before completion\n   */\n  assetId: string;\n}\n\nexport interface PreloadOptions {\n  /**\n   * Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)\n   * Supported formats:\n   * - MP3, WAV (all platforms)\n   * - M3U8/HLS streams (iOS and Android)\n   */\n  assetPath: string;\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   */\n  volume?: number;\n  /**\n   * Audio channel number, default is 1\n   */\n  audioChannelNum?: number;\n  /**\n   * Is the audio file a URL, pass true if assetPath is a `file://` url\n   * or a streaming URL (m3u8)\n   */\n  isUrl?: boolean;\n  /**\n   * Metadata to display in the notification center when audio is playing.\n   * Only used when `showNotification: true` is set in `configure()`.\n   *\n   * See {@link ConfigureOptions.showNotification} for important details about\n   * how this affects audio mixing behavior on iOS.\n   *\n   * @see NotificationMetadata\n   */\n  notificationMetadata?: NotificationMetadata;\n  /**\n   * Custom HTTP headers to include when fetching remote audio files.\n   * Only used when isUrl is true and assetPath is a remote URL (http/https).\n   * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }\n   *\n   * @since 7.10.0\n   */\n  headers?: Record<string, string>;\n}\n\nexport interface CurrentTimeEvent {\n  /**\n   * Current time of the audio in seconds\n   * @since 6.5.0\n   */\n  currentTime: number;\n  /**\n   * Asset Id of the audio\n   * @since 6.5.0\n   */\n  assetId: string;\n}\nexport type CurrentTimeListener = (state: CurrentTimeEvent) => void;\n\nexport interface NativeAudio {\n  /**\n   * Configure the audio player\n   * @since 5.0.0\n   * @param option {@link ConfigureOptions}\n   * @returns\n   */\n  configure(options: ConfigureOptions): Promise<void>;\n  /**\n   * Load an audio file\n   * @since 5.0.0\n   * @param option {@link PreloadOptions}\n   * @returns\n   */\n  preload(options: PreloadOptions): Promise<void>;\n  /**\n   * Play an audio file once with automatic cleanup\n   *\n   * Method designed for simple, single-shot audio playback,\n   * such as notification sounds, UI feedback, or other short audio clips\n   * that 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\n   *\n   * @example\n   * ```typescript\n   * // Simple one-shot playback\n   * await NativeAudio.playOnce({ assetPath: 'audio/notification.mp3' });\n   *\n   * // Play and delete the file after completion\n   * await 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\n   * const { assetId } = await NativeAudio.playOnce({\n   *   assetPath: 'audio/long-track.mp3',\n   *   autoPlay: true\n   * });\n   * // Later, you can stop it manually if needed\n   * await NativeAudio.stop({ assetId });\n   * ```\n   *\n   * @since 7.11.0\n   * @param options {@link PlayOnceOptions}\n   * @returns {Promise<PlayOnceResult>} Object containing the generated assetId\n   */\n  playOnce(options: PlayOnceOptions): Promise<PlayOnceResult>;\n  /**\n   * Check if an audio file is preloaded\n   *\n   * @since 6.1.0\n   * @param option {@link Assets}\n   * @returns {Promise<boolean>}\n   */\n  isPreloaded(options: PreloadOptions): Promise<{ found: boolean }>;\n  /**\n   * Play an audio file\n   * @since 5.0.0\n   * @param option {@link PlayOptions}\n   * @returns\n   */\n  play(options: { assetId: string; time?: number; delay?: number }): Promise<void>;\n  /**\n   * Pause an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  pause(options: Assets): Promise<void>;\n  /**\n   * Resume an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  resume(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  loop(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  stop(options: Assets): Promise<void>;\n  /**\n   * Unload an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  unload(options: Assets): Promise<void>;\n  /**\n   * Set the volume of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetVolume}\n   * @returns {Promise<void>}\n   */\n  setVolume(options: { assetId: string; volume: number }): Promise<void>;\n  /**\n   * Set the rate of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setRate(options: { assetId: string; rate: number }): Promise<void>;\n  /**\n   * Set the current time of an audio file\n   * @since 6.5.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setCurrentTime(options: { assetId: string; time: number }): Promise<void>;\n  /**\n   * Get the current time of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ currentTime: number }>}\n   */\n  getCurrentTime(options: { assetId: string }): Promise<{ currentTime: number }>;\n  /**\n   * Get the duration of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ duration: number }>}\n   */\n  getDuration(options: Assets): Promise<{ duration: number }>;\n  /**\n   * Check if an audio file is playing\n   *\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<boolean>}\n   */\n  isPlaying(options: Assets): Promise<{ isPlaying: boolean }>;\n  /**\n   * Listen for complete event\n   *\n   * @since 5.0.0\n   * return {@link CompletedEvent}\n   */\n  addListener(eventName: 'complete', listenerFunc: CompletedListener): Promise<PluginListenerHandle>;\n  /**\n   * Listen for current time updates\n   * Emits every 100ms while audio is playing\n   *\n   * @since 6.5.0\n   * return {@link CurrentTimeEvent}\n   */\n  addListener(eventName: 'currentTime', listenerFunc: CurrentTimeListener): Promise<PluginListenerHandle>;\n  /**\n   * Clear the audio cache for remote audio files\n   * @since 6.5.0\n   * @returns {Promise<void>}\n   */\n  clearCache(): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Deinitialize the plugin and restore original audio session settings\n   * This method stops all playing audio and reverts any audio session changes made by the plugin\n   * Use this when you need to ensure compatibility with other audio plugins\n   *\n   * @since 7.7.0\n   * @returns {Promise<void>}\n   */\n  deinitPlugin(): Promise<void>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["import type { PluginListenerHandle } from '@capacitor/core';\n\nexport interface CompletedEvent {\n  /**\n   * Emit when a play completes\n   *\n   * @since  5.0.0\n   */\n  assetId: string;\n}\nexport type CompletedListener = (state: CompletedEvent) => void;\nexport interface Assets {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n}\nexport interface AssetVolume {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   */\n  volume: number;\n}\n\nexport interface AssetRate {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Rate of the audio, between 0.1 and 1.0\n   */\n  rate: number;\n}\n\nexport interface AssetPlayOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Time to start playing the audio, in milliseconds\n   */\n  time?: number;\n  /**\n   * Delay to start playing the audio, in milliseconds\n   */\n  delay?: number;\n}\n\nexport interface ConfigureOptions {\n  /**\n   * Play the audio with Fade effect, only available for IOS\n   */\n  fade?: boolean;\n  /**\n   * focus the audio with Audio Focus\n   */\n  focus?: boolean;\n  /**\n   * Play the audio in the background\n   */\n  background?: boolean;\n  /**\n   * Ignore silent mode, works only on iOS setting this will nuke other audio apps\n   */\n  ignoreSilent?: boolean;\n  /**\n   * Show audio playback in the notification center (iOS and Android)\n   * When enabled, displays audio metadata (title, artist, album, artwork) in the system notification\n   * and Control Center (iOS) or lock screen.\n   *\n   * **Important iOS Behavior:**\n   * Enabling this option changes the audio session category to `.playback` with `.default` mode,\n   * which means your app's audio will **interrupt** other apps' audio (like background music from\n   * Spotify, Apple Music, etc.) instead of mixing with it. This is required for the Now Playing\n   * info 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   *\n   * Use this when your app is the primary audio source (music players, podcast apps, etc.).\n   * Disable this for secondary audio like sound effects or notification sounds where mixing\n   * with background music is preferred.\n   *\n   * @see https://github.com/Cap-go/capacitor-native-audio/issues/202\n   */\n  showNotification?: boolean;\n  /**\n   * Enable background audio playback (Android only)\n   *\n   * When enabled, audio will continue playing when the app is backgrounded or the screen is locked.\n   * The plugin will skip the automatic pause/resume logic that normally occurs when the app\n   * enters the background or returns to the foreground.\n   *\n   * **Important Android Requirements:**\n   * To use background playback on Android, your app must:\n   * 1. 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\" />`\n   * 2. Start a Foreground Service with a media-style notification before backgrounding\n   *    (the plugin does not automatically create or manage the foreground service)\n   * 3. Use `showNotification: true` to display playback controls in the notification\n   *\n   * **Usage Example:**\n   * ```typescript\n   * await NativeAudio.configure({\n   *   backgroundPlayback: true,\n   *   showNotification: true\n   * });\n   * // Start your foreground service here\n   * // Then preload and play audio as normal\n   * ```\n   *\n   * @default false\n   * @platform Android\n   * @since 8.2.0\n   */\n  backgroundPlayback?: boolean;\n}\n\n/**\n * Metadata to display in the notification center, Control Center (iOS), and lock screen\n * when `showNotification` is enabled in `configure()`.\n *\n * Note: This metadata will only be displayed if `showNotification: true` is set in the\n * `configure()` method. See {@link ConfigureOptions.showNotification} for important\n * behavior details about audio mixing on iOS.\n */\nexport interface NotificationMetadata {\n  /**\n   * The title to display in the notification center\n   */\n  title?: string;\n  /**\n   * The artist name to display in the notification center\n   */\n  artist?: string;\n  /**\n   * The album name to display in the notification center\n   */\n  album?: string;\n  /**\n   * URL or local path to the artwork/album art image\n   */\n  artworkUrl?: string;\n}\n\nexport interface PlayOnceOptions {\n  /**\n   * Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)\n   * Supported formats:\n   * - MP3, WAV (all platforms)\n   * - M3U8/HLS streams (iOS and Android)\n   */\n  assetPath: string;\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   * @default 1.0\n   */\n  volume?: number;\n  /**\n   * Is the audio file a URL, pass true if assetPath is a `file://` url\n   * or a streaming URL (m3u8)\n   * @default false\n   */\n  isUrl?: boolean;\n  /**\n   * Automatically start playback after loading\n   * @default true\n   */\n  autoPlay?: boolean;\n  /**\n   * Delete the audio file from disk after playback completes\n   * Only works for local files (file:// URLs), ignored for remote URLs\n   * @default false\n   * @since 7.11.0\n   */\n  deleteAfterPlay?: boolean;\n  /**\n   * Metadata to display in the notification center when audio is playing.\n   * Only used when `showNotification: true` is set in `configure()`.\n   *\n   * See {@link ConfigureOptions.showNotification} for important details about\n   * how this affects audio mixing behavior on iOS.\n   *\n   * @see NotificationMetadata\n   * @since 7.10.0\n   */\n  notificationMetadata?: NotificationMetadata;\n  /**\n   * Custom HTTP headers to include when fetching remote audio files.\n   * Only used when isUrl is true and assetPath is a remote URL (http/https).\n   * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }\n   *\n   * @since 7.10.0\n   */\n  headers?: Record<string, string>;\n}\n\nexport interface PlayOnceResult {\n  /**\n   * The internally generated asset ID for this playback\n   * Can be used to control playback (pause, stop, etc.) before completion\n   */\n  assetId: string;\n}\n\nexport interface PreloadOptions {\n  /**\n   * Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://)\n   * Supported formats:\n   * - MP3, WAV (all platforms)\n   * - M3U8/HLS streams (iOS and Android)\n   */\n  assetPath: string;\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   */\n  volume?: number;\n  /**\n   * Audio channel number, default is 1\n   */\n  audioChannelNum?: number;\n  /**\n   * Is the audio file a URL, pass true if assetPath is a `file://` url\n   * or a streaming URL (m3u8)\n   */\n  isUrl?: boolean;\n  /**\n   * Metadata to display in the notification center when audio is playing.\n   * Only used when `showNotification: true` is set in `configure()`.\n   *\n   * See {@link ConfigureOptions.showNotification} for important details about\n   * how this affects audio mixing behavior on iOS.\n   *\n   * @see NotificationMetadata\n   */\n  notificationMetadata?: NotificationMetadata;\n  /**\n   * Custom HTTP headers to include when fetching remote audio files.\n   * Only used when isUrl is true and assetPath is a remote URL (http/https).\n   * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }\n   *\n   * @since 7.10.0\n   */\n  headers?: Record<string, string>;\n}\n\nexport interface CurrentTimeEvent {\n  /**\n   * Current time of the audio in seconds\n   * @since 6.5.0\n   */\n  currentTime: number;\n  /**\n   * Asset Id of the audio\n   * @since 6.5.0\n   */\n  assetId: string;\n}\nexport type CurrentTimeListener = (state: CurrentTimeEvent) => void;\n\nexport interface NativeAudio {\n  /**\n   * Configure the audio player\n   * @since 5.0.0\n   * @param option {@link ConfigureOptions}\n   * @returns\n   */\n  configure(options: ConfigureOptions): Promise<void>;\n  /**\n   * Load an audio file\n   * @since 5.0.0\n   * @param option {@link PreloadOptions}\n   * @returns\n   */\n  preload(options: PreloadOptions): Promise<void>;\n  /**\n   * Play an audio file once with automatic cleanup\n   *\n   * Method designed for simple, single-shot audio playback,\n   * such as notification sounds, UI feedback, or other short audio clips\n   * that 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\n   *\n   * @example\n   * ```typescript\n   * // Simple one-shot playback\n   * await NativeAudio.playOnce({ assetPath: 'audio/notification.mp3' });\n   *\n   * // Play and delete the file after completion\n   * await 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\n   * const { assetId } = await NativeAudio.playOnce({\n   *   assetPath: 'audio/long-track.mp3',\n   *   autoPlay: true\n   * });\n   * // Later, you can stop it manually if needed\n   * await NativeAudio.stop({ assetId });\n   * ```\n   *\n   * @since 7.11.0\n   * @param options {@link PlayOnceOptions}\n   * @returns {Promise<PlayOnceResult>} Object containing the generated assetId\n   */\n  playOnce(options: PlayOnceOptions): Promise<PlayOnceResult>;\n  /**\n   * Check if an audio file is preloaded\n   *\n   * @since 6.1.0\n   * @param option {@link Assets}\n   * @returns {Promise<boolean>}\n   */\n  isPreloaded(options: PreloadOptions): Promise<{ found: boolean }>;\n  /**\n   * Play an audio file\n   * @since 5.0.0\n   * @param option {@link PlayOptions}\n   * @returns\n   */\n  play(options: { assetId: string; time?: number; delay?: number }): Promise<void>;\n  /**\n   * Pause an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  pause(options: Assets): Promise<void>;\n  /**\n   * Resume an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  resume(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  loop(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  stop(options: Assets): Promise<void>;\n  /**\n   * Unload an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  unload(options: Assets): Promise<void>;\n  /**\n   * Set the volume of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetVolume}\n   * @returns {Promise<void>}\n   */\n  setVolume(options: { assetId: string; volume: number }): Promise<void>;\n  /**\n   * Set the rate of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setRate(options: { assetId: string; rate: number }): Promise<void>;\n  /**\n   * Set the current time of an audio file\n   * @since 6.5.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setCurrentTime(options: { assetId: string; time: number }): Promise<void>;\n  /**\n   * Get the current time of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ currentTime: number }>}\n   */\n  getCurrentTime(options: { assetId: string }): Promise<{ currentTime: number }>;\n  /**\n   * Get the duration of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ duration: number }>}\n   */\n  getDuration(options: Assets): Promise<{ duration: number }>;\n  /**\n   * Check if an audio file is playing\n   *\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<boolean>}\n   */\n  isPlaying(options: Assets): Promise<{ isPlaying: boolean }>;\n  /**\n   * Listen for complete event\n   *\n   * @since 5.0.0\n   * return {@link CompletedEvent}\n   */\n  addListener(eventName: 'complete', listenerFunc: CompletedListener): Promise<PluginListenerHandle>;\n  /**\n   * Listen for current time updates\n   * Emits every 100ms while audio is playing\n   *\n   * @since 6.5.0\n   * return {@link CurrentTimeEvent}\n   */\n  addListener(eventName: 'currentTime', listenerFunc: CurrentTimeListener): Promise<PluginListenerHandle>;\n  /**\n   * Clear the audio cache for remote audio files\n   * @since 6.5.0\n   * @returns {Promise<void>}\n   */\n  clearCache(): Promise<void>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Deinitialize the plugin and restore original audio session settings\n   * This method stops all playing audio and reverts any audio session changes made by the plugin\n   * Use this when you need to ensure compatibility with other audio plugins\n   *\n   * @since 7.7.0\n   * @returns {Promise<void>}\n   */\n  deinitPlugin(): Promise<void>;\n}\n"]}

package/ios/Sources/NativeAudioPlugin/Plugin.swift

@@ -13,7 +13,7 @@ enum MyError: Error {
 // swiftlint:disable type_body_length file_length
 @objc(NativeAudio)
 public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.1.10"
+    private let pluginVersion: String = "8.2.0"
     public let identifier = "NativeAudio"
     public let jsName = "NativeAudio"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/native-audio",
-  "version": "8.1.10",
+  "version": "8.2.0",
   "description": "A native plugin for native audio engine",
   "license": "MPL-2.0",
   "main": "dist/plugin.cjs.js",