@capgo/native-audio 7.9.9 → 7.9.11

package/README.md

@@ -136,6 +136,19 @@ No configuration required for this plugin.
 
 You can display audio playback information in the system notification center. This is perfect for music players, podcast apps, and any app that plays audio in the background.
 
+> **⚠️ Important iOS Behavior**
+> 
+> Enabling `showNotification: true` changes how your app's audio interacts with other apps on iOS:
+> 
+> - **With notifications enabled** (showNotification: true): Your audio will **interrupt** other apps' audio (like Spotify, Apple Music, etc.). This is required for Now Playing controls to appear in Control Center and on the lock screen.
+> - **With notifications disabled** (showNotification: false): Your audio will **mix** with other apps' audio, allowing background music to continue playing.
+> 
+> **When to use each:**
+> - ✅ Use `showNotification: true` for: Music players, podcast apps, audiobook players (primary audio source)
+> - ❌ Use `showNotification: false` for: Sound effects, notification sounds, secondary audio where mixing is preferred
+> 
+> See [Issue #202](https://github.com/Cap-go/capacitor-native-audio/issues/202) for technical details.
+
 **Step 1: Configure the plugin with notification support**
 
 ```typescript
@@ -193,6 +206,7 @@ The media control buttons automatically handle:
 - All metadata fields are optional
 - Artwork can be a local file path or remote URL
 - The notification only appears when `showNotification: true` is set in configure()
+- ⚠️ **iOS:** Enabling notifications will interrupt other apps' audio (see warning above)
 - iOS: Uses MPNowPlayingInfoCenter with MPRemoteCommandCenter
 - Android: Uses MediaSession with NotificationCompat.MediaStyle
 
@@ -674,29 +688,37 @@ 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 |
+| 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. |
 
 
 #### PreloadOptions
 
-| Prop                       | Type                                                                  | Description                                                                                                                                                                           |
-| -------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **`assetPath`**            | <code>string</code>                                                   | Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://) Supported formats: - MP3, WAV (all platforms) - M3U8/HLS streams (iOS and Android) |
-| **`assetId`**              | <code>string</code>                                                   | Asset Id, unique identifier of the file                                                                                                                                               |
-| **`volume`**               | <code>number</code>                                                   | Volume of the audio, between 0.1 and 1.0                                                                                                                                              |
-| **`audioChannelNum`**      | <code>number</code>                                                   | Audio channel number, default is 1                                                                                                                                                    |
-| **`isUrl`**                | <code>boolean</code>                                                  | Is the audio file a URL, pass true if assetPath is a `file://` url or a streaming URL (m3u8)                                                                                          |
-| **`notificationMetadata`** | <code><a href="#notificationmetadata">NotificationMetadata</a></code> | Metadata to display in the notification center when audio is playing Only used when showNotification is enabled in configure()                                                        |
+| Prop                       | Type                                                                  | Description                                                                                                                                                                                                                                                                                     | Since  |
+| -------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ |
+| **`assetPath`**            | <code>string</code>                                                   | Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://) Supported formats: - MP3, WAV (all platforms) - M3U8/HLS streams (iOS and Android)                                                                                                           |        |
+| **`assetId`**              | <code>string</code>                                                   | Asset Id, unique identifier of the file                                                                                                                                                                                                                                                         |        |
+| **`volume`**               | <code>number</code>                                                   | Volume of the audio, between 0.1 and 1.0                                                                                                                                                                                                                                                        |        |
+| **`audioChannelNum`**      | <code>number</code>                                                   | Audio channel number, default is 1                                                                                                                                                                                                                                                              |        |
+| **`isUrl`**                | <code>boolean</code>                                                  | Is the audio file a URL, pass true if assetPath is a `file://` url or a streaming URL (m3u8)                                                                                                                                                                                                    |        |
+| **`notificationMetadata`** | <code><a href="#notificationmetadata">NotificationMetadata</a></code> | Metadata to display in the notification center when audio is playing. Only used when `showNotification: true` is set in `configure()`. See {@link <a href="#configureoptions">ConfigureOptions.showNotification</a>} for important details about how this affects audio mixing behavior on iOS. |        |
+| **`headers`**              | <code><a href="#record">Record</a>&lt;string, string&gt;</code>       | Custom HTTP headers to include when fetching remote audio files. Only used when isUrl is true and assetPath is a remote URL (http/https). Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }                                                                                   | 7.10.0 |
 
 
 #### NotificationMetadata
 
+Metadata to display in the notification center, Control Center (iOS), and lock screen
+when `showNotification` is enabled in `configure()`.
+
+Note: This metadata will only be displayed if `showNotification: true` is set in the
+`configure()` method. See {@link <a href="#configureoptions">ConfigureOptions.showNotification</a>} for important
+behavior details about audio mixing on iOS.
+
 | Prop             | Type                | Description                                           |
 | ---------------- | ------------------- | ----------------------------------------------------- |
 | **`title`**      | <code>string</code> | The title to display in the notification center       |
@@ -737,6 +759,13 @@ Use this when you need to ensure compatibility with other audio plugins
 ### Type Aliases
 
 
+#### Record
+
+Construct a type with a set of properties K of type T
+
+<code>{
 [P in K]: T;
 }</code>
+
+
 #### CompletedListener
 
 <code>(state: <a href="#completedevent">CompletedEvent</a>): void</code>

package/android/build.gradle

@@ -64,5 +64,5 @@ dependencies {
     implementation 'androidx.media3:media3-common:1.8.0'
     // Media notification support
     implementation 'androidx.media:media:1.7.1'
-    implementation 'androidx.core:core:1.17.0'
+    implementation 'androidx.core:core:1.13.1'
 }

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

@@ -50,6 +50,7 @@ import java.net.URI;
 import java.net.URL;
 import java.util.ArrayList;
 import java.util.HashMap;
+import java.util.Iterator;
 import java.util.Map;
 
 @UnstableApi
@@ -644,14 +645,40 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
                     if (uri.getScheme() != null && (uri.getScheme().equals("http") || uri.getScheme().equals("https"))) {
                         // Remote URL
                         Log.d("AudioPlugin", "Debug: Remote URL detected: " + uri.toString());
+
+                        // Extract headers if provided
+                        Map<String, String> requestHeaders = null;
+                        JSObject headersObj = call.getObject("headers");
+                        if (headersObj != null) {
+                            requestHeaders = new HashMap<>();
+                            for (Iterator<String> it = headersObj.keys(); it.hasNext(); ) {
+                                String key = it.next();
+                                try {
+                                    String value = headersObj.getString(key);
+                                    if (value != null) {
+                                        requestHeaders.put(key, value);
+                                    }
+                                } catch (Exception e) {
+                                    Log.w("AudioPlugin", "Skipping non-string header: " + key);
+                                }
+                            }
+                        }
+
                         if (assetPath.endsWith(".m3u8")) {
                             // HLS Stream - resolve immediately since it's a stream
-                            StreamAudioAsset streamAudioAsset = new StreamAudioAsset(this, audioId, uri, volume);
+                            StreamAudioAsset streamAudioAsset = new StreamAudioAsset(this, audioId, uri, volume, requestHeaders);
                             audioAssetList.put(audioId, streamAudioAsset);
                             call.resolve(status);
                         } else {
                             // Regular remote audio
-                            RemoteAudioAsset remoteAudioAsset = new RemoteAudioAsset(this, audioId, uri, audioChannelNum, volume);
+                            RemoteAudioAsset remoteAudioAsset = new RemoteAudioAsset(
+                                this,
+                                audioId,
+                                uri,
+                                audioChannelNum,
+                                volume,
+                                requestHeaders
+                            );
                             remoteAudioAsset.setCompletionListener(this::dispatchComplete);
                             audioAssetList.put(audioId, remoteAudioAsset);
                             call.resolve(status);

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

@@ -18,6 +18,7 @@ import androidx.media3.exoplayer.source.MediaSource;
 import androidx.media3.exoplayer.source.ProgressiveMediaSource;
 import java.io.File;
 import java.util.ArrayList;
+import java.util.Map;
 
 @UnstableApi
 public class RemoteAudioAsset extends AudioAsset {
@@ -36,13 +37,16 @@ public class RemoteAudioAsset extends AudioAsset {
     private float initialVolume;
     private Handler currentTimeHandler;
     private Runnable currentTimeRunnable;
+    private final Map<String, String> headers;
 
-    public RemoteAudioAsset(NativeAudio owner, String assetId, Uri uri, int audioChannelNum, float volume) throws Exception {
+    public RemoteAudioAsset(NativeAudio owner, String assetId, Uri uri, int audioChannelNum, float volume, Map<String, String> headers)
+        throws Exception {
         super(owner, assetId, null, 0, volume);
         this.uri = uri;
         this.volume = volume;
         this.initialVolume = volume;
         this.players = new ArrayList<>();
+        this.headers = headers;
 
         if (audioChannelNum < 1) {
             audioChannelNum = 1;
@@ -87,12 +91,17 @@ public class RemoteAudioAsset extends AudioAsset {
             );
         }
 
-        // Create cached data source factory
+        // Create cached data source factory with custom headers
         DefaultHttpDataSource.Factory httpDataSourceFactory = new DefaultHttpDataSource.Factory()
             .setAllowCrossProtocolRedirects(true)
             .setConnectTimeoutMs(15000)
             .setReadTimeoutMs(15000);
 
+        // Add custom headers if provided
+        if (headers != null && !headers.isEmpty()) {
+            httpDataSourceFactory.setDefaultRequestProperties(headers);
+        }
+
         CacheDataSource.Factory cacheDataSourceFactory = new CacheDataSource.Factory()
             .setCache(cache)
             .setUpstreamDataSourceFactory(httpDataSourceFactory)
@@ -301,10 +310,46 @@ public class RemoteAudioAsset extends AudioAsset {
 
     @Override
     public void unload() throws Exception {
-        for (ExoPlayer player : players) {
-            player.release();
+        if (Looper.myLooper() == Looper.getMainLooper()) {
+            // Synchronous cleanup when already on the main thread
+            stopCurrentTimeUpdates();
+            for (ExoPlayer player : new ArrayList<>(players)) {
+                try {
+                    player.release();
+                } catch (Exception e) {
+                    Log.w(TAG, "Error releasing player", e);
+                }
+            }
+            players.clear();
+            isPrepared = false;
+            playIndex = 0;
+            return;
+        }
+        // Ensure cleanup completes before returning when called off the main thread
+        final java.util.concurrent.CountDownLatch latch = new java.util.concurrent.CountDownLatch(1);
+        new Handler(Looper.getMainLooper()).post(() -> {
+            try {
+                stopCurrentTimeUpdates();
+                for (ExoPlayer player : new ArrayList<>(players)) {
+                    try {
+                        player.release();
+                    } catch (Exception e) {
+                        Log.w(TAG, "Error releasing player", e);
+                    }
+                }
+                players.clear();
+                isPrepared = false;
+                playIndex = 0;
+            } finally {
+                latch.countDown();
+            }
+        });
+        try {
+            // Don't block forever; adjust timeout as needed
+            latch.await(2, java.util.concurrent.TimeUnit.SECONDS);
+        } catch (InterruptedException ie) {
+            Thread.currentThread().interrupt();
         }
-        players.clear();
     }
 
     @Override

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

@@ -27,12 +27,15 @@ public class StreamAudioAsset extends AudioAsset {
     private static final float FADE_STEP = 0.05f;
     private static final int FADE_DELAY_MS = 80; // 80ms between steps
     private static final long LIVE_OFFSET_MS = 5000; // 5 seconds behind live
+    private final java.util.Map<String, String> headers;
 
-    public StreamAudioAsset(NativeAudio owner, String assetId, Uri uri, float volume) throws Exception {
+    public StreamAudioAsset(NativeAudio owner, String assetId, Uri uri, float volume, java.util.Map<String, String> headers)
+        throws Exception {
         super(owner, assetId, null, 0, volume);
         this.uri = uri;
         this.volume = volume;
         this.initialVolume = volume;
+        this.headers = headers;
 
         createPlayer();
     }
@@ -74,6 +77,11 @@ public class StreamAudioAsset extends AudioAsset {
             .setReadTimeoutMs(15000)
             .setUserAgent("ExoPlayer");
 
+        // Add custom headers if provided
+        if (headers != null && !headers.isEmpty()) {
+            httpDataSourceFactory.setDefaultRequestProperties(headers);
+        }
+
         HlsMediaSource mediaSource = new HlsMediaSource.Factory(httpDataSourceFactory)
             .setAllowChunklessPreparation(true)
             .setTimestampAdjusterInitializationTimeoutMs(LIVE_OFFSET_MS) // 30 seconds timeout
@@ -216,6 +224,11 @@ public class StreamAudioAsset extends AudioAsset {
                     .setReadTimeoutMs(15000)
                     .setUserAgent("ExoPlayer");
 
+                // Add custom headers if provided
+                if (headers != null && !headers.isEmpty()) {
+                    httpDataSourceFactory.setDefaultRequestProperties(headers);
+                }
+
                 HlsMediaSource mediaSource = new HlsMediaSource.Factory(httpDataSourceFactory)
                     .setAllowChunklessPreparation(true)
                     .setTimestampAdjusterInitializationTimeoutMs(LIVE_OFFSET_MS)
@@ -461,6 +474,11 @@ public class StreamAudioAsset extends AudioAsset {
                         .setReadTimeoutMs(15000)
                         .setUserAgent("ExoPlayer");
 
+                    // Add custom headers if provided
+                    if (headers != null && !headers.isEmpty()) {
+                        httpDataSourceFactory.setDefaultRequestProperties(headers);
+                    }
+
                     HlsMediaSource mediaSource = new HlsMediaSource.Factory(httpDataSourceFactory)
                         .setAllowChunklessPreparation(true)
                         .setTimestampAdjusterInitializationTimeoutMs(LIVE_OFFSET_MS)

package/dist/docs.json

@@ -659,8 +659,13 @@
         },
         {
           "name": "showNotification",
-          "tags": [],
-          "docs": "Show audio playback in the notification center (iOS and Android)\nWhen enabled, displays audio metadata (title, artist, album, artwork) in the system notification",
+          "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"
         }
@@ -710,19 +715,38 @@
         },
         {
           "name": "notificationMetadata",
-          "tags": [],
-          "docs": "Metadata to display in the notification center when audio is playing\nOnly used when showNotification is enabled in configure()",
+          "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": "",
+      "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": [
@@ -845,6 +869,20 @@
   ],
   "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",

package/dist/esm/definitions.d.ts

@@ -68,9 +68,34 @@ export interface ConfigureOptions {
     /**
      * 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.
+     *
+     * @see https://github.com/Cap-go/capacitor-native-audio/issues/202
      */
     showNotification?: boolean;
 }
+/**
+ * Metadata to display in the notification center, Control Center (iOS), and lock screen
+ * when `showNotification` is enabled in `configure()`.
+ *
+ * Note: This metadata will only be displayed if `showNotification: true` is set in the
+ * `configure()` method. See {@link ConfigureOptions.showNotification} for important
+ * behavior details about audio mixing on iOS.
+ */
 export interface NotificationMetadata {
     /**
      * The title to display in the notification center
@@ -115,10 +140,23 @@ export interface PreloadOptions {
      */
     isUrl?: boolean;
     /**
-     * Metadata to display in the notification center when audio is playing
-     * Only used when showNotification is enabled in configure()
+     * Metadata to display in the notification center when audio is playing.
+     * Only used when `showNotification: true` is set in `configure()`.
+     *
+     * See {@link ConfigureOptions.showNotification} for important details about
+     * how this affects audio mixing behavior on iOS.
+     *
+     * @see NotificationMetadata
      */
     notificationMetadata?: NotificationMetadata;
+    /**
+     * Custom HTTP headers to include when fetching remote audio files.
+     * Only used when isUrl is true and assetPath is a remote URL (http/https).
+     * Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }
+     *
+     * @since 7.10.0
+     */
+    headers?: Record<string, string>;
 }
 export interface CurrentTimeEvent {
     /**

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   */\n  showNotification?: boolean;\n}\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 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 is enabled in configure()\n   */\n  notificationMetadata?: NotificationMetadata;\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   * 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\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 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   * 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

@@ -254,7 +254,21 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
         // Use a single audio session configuration block for better atomicity
         do {
             // Set category first
-            if focus {
+            // Fix for issue #202: When showNotification is enabled, use .playback without
+            // .mixWithOthers or .duckOthers to allow Now Playing info to display in
+            // Control Center and lock screen.
+            //
+            // IMPORTANT: This is a behavior trade-off:
+            // - With .playback + .default mode: Now Playing info shows, but interrupts other audio
+            // - With .mixWithOthers or .duckOthers: Audio mixes, but no Now Playing info
+            //
+            // This is required because iOS only shows Now Playing controls for audio sessions
+            // that use the .playback category without mixing options. This means the app becomes
+            // the primary audio source and will interrupt background music from other apps.
+            if self.showNotification {
+                // Use playback category with default mode for notification support
+                try self.session.setCategory(AVAudioSession.Category.playback, mode: .default)
+            } else if focus {
                 try self.session.setCategory(AVAudioSession.Category.playback, options: .duckOthers)
             } else if !ignoreSilent {
                 try self.session.setCategory(AVAudioSession.Category.ambient, options: focus ? .duckOthers : .mixWithOthers)
@@ -667,7 +681,17 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                     }
                 } else {
                     // Handle remote URL
-                    let remoteAudioAsset = RemoteAudioAsset(owner: self, withAssetId: audioId, withPath: assetPath, withChannels: channels, withVolume: volume, withFadeDelay: delay)
+                    // Extract headers if provided
+                    var headers: [String: String]?
+                    if let headersObj = call.getObject("headers") {
+                        headers = [:]
+                        for (key, value) in headersObj {
+                            if let stringValue = value as? String {
+                                headers?[key] = stringValue
+                            }
+                        }
+                    }
+                    let remoteAudioAsset = RemoteAudioAsset(owner: self, withAssetId: audioId, withPath: assetPath, withChannels: channels, withVolume: volume, withFadeDelay: delay, withHeaders: headers)
                     self.audioList[audioId] = remoteAudioAsset
                     call.resolve()
                     return

package/ios/Sources/NativeAudioPlugin/RemoteAudioAsset.swift

@@ -12,7 +12,7 @@ public class RemoteAudioAsset: AudioAsset {
     var duration: TimeInterval = 0
     var asset: AVURLAsset?
 
-    override init(owner: NativeAudio, withAssetId assetId: String, withPath path: String!, withChannels channels: Int!, withVolume volume: Float!, withFadeDelay delay: Float!) {
+    init(owner: NativeAudio, withAssetId assetId: String, withPath path: String!, withChannels channels: Int!, withVolume volume: Float!, withFadeDelay delay: Float!, withHeaders headers: [String: String]?) {
         super.init(owner: owner, withAssetId: assetId, withPath: path, withChannels: channels ?? 1, withVolume: volume ?? 1.0, withFadeDelay: delay ?? 0.0)
 
         owner.executeOnAudioQueue { [weak self] in
@@ -23,7 +23,13 @@ public class RemoteAudioAsset: AudioAsset {
                 return
             }
 
-            let asset = AVURLAsset(url: url, options: [AVURLAssetPreferPreciseDurationAndTimingKey: true])
+            // Build AVURLAsset options with custom headers if provided
+            var options: [String: Any] = [AVURLAssetPreferPreciseDurationAndTimingKey: true]
+            if let headers = headers, !headers.isEmpty {
+                options["AVURLAssetHTTPHeaderFieldsKey"] = headers
+            }
+
+            let asset = AVURLAsset(url: url, options: options)
             self.asset = asset
 
             // Limit channels to a reasonable maximum to prevent resource issues

package/package.json

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