@capgo/native-audio 8.4.0 → 8.4.1

package/dist/docs.json

@@ -613,6 +613,35 @@
         ],
         "slug": "addlistenercurrenttime-"
       },
+      {
+        "name": "addListener",
+        "signature": "(eventName: 'playbackState', listenerFunc: PlaybackStateListener) => Promise<PluginListenerHandle>",
+        "parameters": [
+          {
+            "name": "eventName",
+            "docs": "",
+            "type": "'playbackState'"
+          },
+          {
+            "name": "listenerFunc",
+            "docs": "",
+            "type": "PlaybackStateListener"
+          }
+        ],
+        "returns": "Promise<PluginListenerHandle>",
+        "tags": [
+          {
+            "name": "since",
+            "text": "8.3.15\nreturn {@link PlaybackStateEvent}"
+          }
+        ],
+        "docs": "Listen for playback state changes, including notification and lock-screen transport controls.\nEmitted by Android and iOS. The current Web implementation does not emit this event.",
+        "complexTypes": [
+          "PluginListenerHandle",
+          "PlaybackStateListener"
+        ],
+        "slug": "addlistenerplaybackstate-"
+      },
       {
         "name": "clearCache",
         "signature": "() => Promise<void>",
@@ -1307,6 +1336,59 @@
           "type": "string"
         }
       ]
+    },
+    {
+      "name": "PlaybackStateEvent",
+      "slug": "playbackstateevent",
+      "docs": "",
+      "tags": [],
+      "methods": [],
+      "properties": [
+        {
+          "name": "assetId",
+          "tags": [],
+          "docs": "Asset Id of the audio",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "state",
+          "tags": [],
+          "docs": "Resolved playback state after a local or remote transport action.",
+          "complexTypes": [
+            "PlaybackStateValue"
+          ],
+          "type": "PlaybackStateValue"
+        },
+        {
+          "name": "reason",
+          "tags": [],
+          "docs": "Reason for the state change, for example `play`, `pause`, `remotePlay`, or `complete`.",
+          "complexTypes": [],
+          "type": "string"
+        },
+        {
+          "name": "isPlaying",
+          "tags": [],
+          "docs": "Whether the asset is currently playing.",
+          "complexTypes": [],
+          "type": "boolean"
+        },
+        {
+          "name": "currentTime",
+          "tags": [],
+          "docs": "Current playback position in seconds when available.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        },
+        {
+          "name": "duration",
+          "tags": [],
+          "docs": "Total playback duration in seconds when available.",
+          "complexTypes": [],
+          "type": "number | undefined"
+        }
+      ]
     }
   ],
   "enums": [],
@@ -1350,6 +1432,38 @@
           ]
         }
       ]
+    },
+    {
+      "name": "PlaybackStateListener",
+      "slug": "playbackstatelistener",
+      "docs": "",
+      "types": [
+        {
+          "text": "(state: PlaybackStateEvent): void",
+          "complexTypes": [
+            "PlaybackStateEvent"
+          ]
+        }
+      ]
+    },
+    {
+      "name": "PlaybackStateValue",
+      "slug": "playbackstatevalue",
+      "docs": "",
+      "types": [
+        {
+          "text": "'playing'",
+          "complexTypes": []
+        },
+        {
+          "text": "'paused'",
+          "complexTypes": []
+        },
+        {
+          "text": "'stopped'",
+          "complexTypes": []
+        }
+      ]
     }
   ],
   "pluginConfigs": []

package/dist/esm/definitions.d.ts

@@ -346,6 +346,34 @@ export interface CurrentTimeEvent {
     assetId: string;
 }
 export type CurrentTimeListener = (state: CurrentTimeEvent) => void;
+export type PlaybackStateValue = 'playing' | 'paused' | 'stopped';
+export interface PlaybackStateEvent {
+    /**
+     * Asset Id of the audio
+     */
+    assetId: string;
+    /**
+     * Resolved playback state after a local or remote transport action.
+     */
+    state: PlaybackStateValue;
+    /**
+     * Reason for the state change, for example `play`, `pause`, `remotePlay`, or `complete`.
+     */
+    reason: string;
+    /**
+     * Whether the asset is currently playing.
+     */
+    isPlaying: boolean;
+    /**
+     * Current playback position in seconds when available.
+     */
+    currentTime?: number;
+    /**
+     * Total playback duration in seconds when available.
+     */
+    duration?: number;
+}
+export type PlaybackStateListener = (state: PlaybackStateEvent) => void;
 export interface NativeAudio {
     /**
      * Configure the audio player
@@ -526,6 +554,14 @@ export interface NativeAudio {
      * return {@link CurrentTimeEvent}
      */
     addListener(eventName: 'currentTime', listenerFunc: CurrentTimeListener): Promise<PluginListenerHandle>;
+    /**
+     * Listen for playback state changes, including notification and lock-screen transport controls.
+     * Emitted by Android and iOS. The current Web implementation does not emit this event.
+     *
+     * @since 8.3.15
+     * return {@link PlaybackStateEvent}
+     */
+    addListener(eventName: 'playbackState', listenerFunc: PlaybackStateListener): Promise<PluginListenerHandle>;
     /**
      * Clear the audio cache for remote audio files
      * @since 6.5.0

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}\n\nexport type CompletedListener = (state: CompletedEvent) => void;\n\nexport interface Assets {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n}\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   * Time over which to fade to the target volume, in seconds. Default is 0s (immediate).\n   */\n  duration?: 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 AssetSetTime {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Time to set the audio, in seconds\n   */\n  time: 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 seconds\n   */\n  time?: number;\n  /**\n   * Delay to start playing the audio, in seconds\n   */\n  delay?: number;\n\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   */\n  volume?: number;\n\n  /**\n   * Whether to fade in the audio\n   */\n  fadeIn?: boolean;\n\n  /**\n   * Whether to fade out the audio\n   */\n  fadeOut?: boolean;\n\n  /**\n   * Fade in duration in seconds.\n   * Only used if fadeIn is true.\n   * Default is 1s.\n   */\n  fadeInDuration?: number;\n\n  /**\n   * Fade out duration in seconds.\n   * Only used if fadeOut is true.\n   * Default is 1s.\n   */\n  fadeOutDuration?: number;\n\n  /**\n   * Time in seconds from the start of the audio to start fading out.\n   * Only used if fadeOut is true.\n   * Default is fadeOutDuration before end of audio.\n   */\n  fadeOutStartTime?: number;\n}\n\nexport interface AssetStopOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n\n  /**\n   * Whether to fade out the audio before stopping\n   */\n  fadeOut?: boolean;\n\n  /**\n   * Fade out duration in seconds.\n   * Default is 1s.\n   */\n  fadeOutDuration?: number;\n}\n\nexport interface AssetPauseOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n\n  /**\n   * Whether to fade out the audio before pausing\n   */\n  fadeOut?: boolean;\n\n  /**\n   * Fade out duration in seconds.\n   * Default is 1s.\n   */\n  fadeOutDuration?: number;\n}\n\nexport interface AssetResumeOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n\n  /**\n   * Whether to fade in the audio during resume\n   */\n  fadeIn?: boolean;\n\n  /**\n   * Fade in duration in seconds.\n   * Default is 1s.\n   */\n  fadeInDuration?: number;\n}\n\nexport interface ConfigureOptions {\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}\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  /**\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  /**\n   * Play an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns\n   */\n  play(options: AssetPlayOptions): Promise<void>;\n\n  /**\n   * Pause an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPauseOptions}\n   * @returns\n   */\n  pause(options: AssetPauseOptions): Promise<void>;\n\n  /**\n   * Resume an audio file\n   * @since 5.0.0\n   * @param option {@link AssetResumeOptions}\n   * @returns\n   */\n  resume(options: AssetResumeOptions): Promise<void>;\n\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  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link AssetStopOptions}\n   * @returns\n   */\n  stop(options: AssetStopOptions): Promise<void>;\n\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  /**\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: AssetVolume): Promise<void>;\n\n  /**\n   * Set the rate of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetRate}\n   * @returns {Promise<void>}\n   */\n  setRate(options: AssetRate): Promise<void>;\n\n  /**\n   * Set the current time of an audio file\n   * @since 6.5.0\n   * @param option {@link AssetSetTime}\n   * @returns {Promise<void>}\n   */\n  setCurrentTime(options: AssetSetTime): Promise<void>;\n\n  /**\n   * Get the current time of an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns {Promise<{ currentTime: number }>}\n   */\n  getCurrentTime(options: Assets): Promise<{ currentTime: number }>;\n\n  /**\n   * Get the duration of an audio file in seconds\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns {Promise<{ duration: number }>}\n   */\n  getDuration(options: Assets): Promise<{ duration: number }>;\n\n  /**\n   * Check if an audio file is playing\n   *\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns {Promise<boolean>}\n   */\n  isPlaying(options: Assets): Promise<{ isPlaying: boolean }>;\n\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  /**\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   * Set debug mode logging\n   * @since 6.5.0\n   * @param options - Options to enable or disable debug mode\n   */\n  setDebugMode(options: { enabled: boolean }): 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}\n\nexport type CompletedListener = (state: CompletedEvent) => void;\n\nexport interface Assets {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n}\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   * Time over which to fade to the target volume, in seconds. Default is 0s (immediate).\n   */\n  duration?: 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 AssetSetTime {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n  /**\n   * Time to set the audio, in seconds\n   */\n  time: 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 seconds\n   */\n  time?: number;\n  /**\n   * Delay to start playing the audio, in seconds\n   */\n  delay?: number;\n\n  /**\n   * Volume of the audio, between 0.1 and 1.0\n   */\n  volume?: number;\n\n  /**\n   * Whether to fade in the audio\n   */\n  fadeIn?: boolean;\n\n  /**\n   * Whether to fade out the audio\n   */\n  fadeOut?: boolean;\n\n  /**\n   * Fade in duration in seconds.\n   * Only used if fadeIn is true.\n   * Default is 1s.\n   */\n  fadeInDuration?: number;\n\n  /**\n   * Fade out duration in seconds.\n   * Only used if fadeOut is true.\n   * Default is 1s.\n   */\n  fadeOutDuration?: number;\n\n  /**\n   * Time in seconds from the start of the audio to start fading out.\n   * Only used if fadeOut is true.\n   * Default is fadeOutDuration before end of audio.\n   */\n  fadeOutStartTime?: number;\n}\n\nexport interface AssetStopOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n\n  /**\n   * Whether to fade out the audio before stopping\n   */\n  fadeOut?: boolean;\n\n  /**\n   * Fade out duration in seconds.\n   * Default is 1s.\n   */\n  fadeOutDuration?: number;\n}\n\nexport interface AssetPauseOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n\n  /**\n   * Whether to fade out the audio before pausing\n   */\n  fadeOut?: boolean;\n\n  /**\n   * Fade out duration in seconds.\n   * Default is 1s.\n   */\n  fadeOutDuration?: number;\n}\n\nexport interface AssetResumeOptions {\n  /**\n   * Asset Id, unique identifier of the file\n   */\n  assetId: string;\n\n  /**\n   * Whether to fade in the audio during resume\n   */\n  fadeIn?: boolean;\n\n  /**\n   * Fade in duration in seconds.\n   * Default is 1s.\n   */\n  fadeInDuration?: number;\n}\n\nexport interface ConfigureOptions {\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}\n\nexport type CurrentTimeListener = (state: CurrentTimeEvent) => void;\n\nexport type PlaybackStateValue = 'playing' | 'paused' | 'stopped';\n\nexport interface PlaybackStateEvent {\n  /**\n   * Asset Id of the audio\n   */\n  assetId: string;\n  /**\n   * Resolved playback state after a local or remote transport action.\n   */\n  state: PlaybackStateValue;\n  /**\n   * Reason for the state change, for example `play`, `pause`, `remotePlay`, or `complete`.\n   */\n  reason: string;\n  /**\n   * Whether the asset is currently playing.\n   */\n  isPlaying: boolean;\n  /**\n   * Current playback position in seconds when available.\n   */\n  currentTime?: number;\n  /**\n   * Total playback duration in seconds when available.\n   */\n  duration?: number;\n}\n\nexport type PlaybackStateListener = (state: PlaybackStateEvent) => 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  /**\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  /**\n   * Play an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns\n   */\n  play(options: AssetPlayOptions): Promise<void>;\n\n  /**\n   * Pause an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPauseOptions}\n   * @returns\n   */\n  pause(options: AssetPauseOptions): Promise<void>;\n\n  /**\n   * Resume an audio file\n   * @since 5.0.0\n   * @param option {@link AssetResumeOptions}\n   * @returns\n   */\n  resume(options: AssetResumeOptions): Promise<void>;\n\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  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link AssetStopOptions}\n   * @returns\n   */\n  stop(options: AssetStopOptions): Promise<void>;\n\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  /**\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: AssetVolume): Promise<void>;\n\n  /**\n   * Set the rate of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetRate}\n   * @returns {Promise<void>}\n   */\n  setRate(options: AssetRate): Promise<void>;\n\n  /**\n   * Set the current time of an audio file\n   * @since 6.5.0\n   * @param option {@link AssetSetTime}\n   * @returns {Promise<void>}\n   */\n  setCurrentTime(options: AssetSetTime): Promise<void>;\n\n  /**\n   * Get the current time of an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns {Promise<{ currentTime: number }>}\n   */\n  getCurrentTime(options: Assets): Promise<{ currentTime: number }>;\n\n  /**\n   * Get the duration of an audio file in seconds\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns {Promise<{ duration: number }>}\n   */\n  getDuration(options: Assets): Promise<{ duration: number }>;\n\n  /**\n   * Check if an audio file is playing\n   *\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns {Promise<boolean>}\n   */\n  isPlaying(options: Assets): Promise<{ isPlaying: boolean }>;\n\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  /**\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   * Listen for playback state changes, including notification and lock-screen transport controls.\n   * Emitted by Android and iOS. The current Web implementation does not emit this event.\n   *\n   * @since 8.3.15\n   * return {@link PlaybackStateEvent}\n   */\n  addListener(eventName: 'playbackState', listenerFunc: PlaybackStateListener): 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   * Set debug mode logging\n   * @since 6.5.0\n   * @param options - Options to enable or disable debug mode\n   */\n  setDebugMode(options: { enabled: boolean }): 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

@@ -8,11 +8,17 @@ enum MyError: Error {
     case runtimeError(String)
 }
 
+private enum PlaybackStateValue: String {
+    case playing
+    case paused
+    case stopped
+}
+
 // swiftlint:disable file_length
 @objc(NativeAudio)
 // swiftlint:disable:next type_body_length
 public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.4.0"
+    private let pluginVersion: String = "8.4.1"
     public let identifier = "NativeAudio"
     public let jsName = "NativeAudio"
     public let pluginMethods: [CAPPluginMethod] = [
@@ -172,9 +178,58 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
         }
     }
 
+    private func resolvePlaybackState(assetId: String, audioAsset: AudioAsset?) -> PlaybackStateValue {
+        if let audioAsset, audioAsset.isPlaying() {
+            return .playing
+        }
+        if let data = audioAssetData[assetId],
+           data["timeBeforePause"] != nil || data["volumeBeforePause"] != nil {
+            return .paused
+        }
+        if currentlyPlayingAssetId == assetId {
+            return .paused
+        }
+        return .stopped
+    }
+
+    private func notifyPlaybackState(assetId: String, reason: String, state: PlaybackStateValue? = nil, audioAsset: AudioAsset? = nil) {
+        let emit = {
+            let asset = audioAsset ?? self.audioList[assetId] as? AudioAsset
+            let resolvedState = state ?? self.resolvePlaybackState(assetId: assetId, audioAsset: asset)
+            var data: [String: Any] = [
+                "assetId": assetId,
+                "state": resolvedState.rawValue,
+                "reason": reason,
+                "isPlaying": resolvedState == .playing
+            ]
+            if let asset {
+                data["currentTime"] = asset.getCurrentTime()
+                let duration = asset.getDuration()
+                if duration.isFinite {
+                    data["duration"] = duration
+                }
+            }
+            self.notifyListeners("playbackState", data: data)
+        }
+
+        if DispatchQueue.getSpecific(key: queueKey) != nil || DispatchQueue.getSpecific(key: audioQueueContextKey) == true {
+            emit()
+        } else {
+            audioQueue.async(execute: emit)
+        }
+    }
+
+    internal func handlePlaybackCompletion(assetId: String, audioAsset: AudioAsset? = nil) {
+        if currentlyPlayingAssetId == assetId {
+            currentlyPlayingAssetId = nil
+            clearNowPlayingInfo()
+        }
+        notifyPlaybackState(assetId: assetId, reason: "complete", state: .stopped, audioAsset: audioAsset)
+    }
+
     /// Must be called on `audioQueue`. If `timeBeforePause` is stored, clears it and seeks (async for remote) before running `resume` + Now Playing refresh.
     /// Mirrors `resume(_:)` (non–fade-in path): restores `volumeBeforePause` via `setVolume`, clears that key from `audioAssetData`, then `resume()`.
-    private func resumeAssetFromStoredPausePositionIfNeeded(assetId: String, asset: AudioAsset) {
+    private func resumeAssetFromStoredPausePositionIfNeeded(assetId: String, asset: AudioAsset, reason: String = "resume") {
         var restoredTime: TimeInterval?
         if var data = audioAssetData[assetId],
            let time = data["timeBeforePause"] as? TimeInterval {
@@ -198,10 +253,14 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                 self.audioAssetData[assetId] = data
             }
             asset.resume()
-            updateNowPlayingInfo(audioId: assetId, audioAsset: asset)
+            if self.showNotification {
+                self.currentlyPlayingAssetId = assetId
+                self.updateNowPlayingInfo(audioId: assetId, audioAsset: asset)
+            }
+            self.notifyPlaybackState(assetId: assetId, reason: reason, state: .playing, audioAsset: asset)
         }
-        if let t = restoredTime {
-            asset.setCurrentTime(time: t) { [weak self] in
+        if let resumeTime = restoredTime {
+            asset.setCurrentTime(time: resumeTime) { [weak self] in
                 guard let self else { return }
                 audioQueue.async(flags: .barrier, execute: resumeAndRefreshNowPlaying)
             }
@@ -226,7 +285,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                 }
 
                 if !asset.isPlaying() {
-                    self.resumeAssetFromStoredPausePositionIfNeeded(assetId: assetId, asset: asset)
+                    self.resumeAssetFromStoredPausePositionIfNeeded(assetId: assetId, asset: asset, reason: "remotePlay")
                 }
             }
             return .success
@@ -251,6 +310,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
 
                 asset.pause()
                 self.updatePlaybackState(isPlaying: false, elapsedTime: timeBeforePause, duration: asset.getDuration())
+                self.notifyPlaybackState(assetId: assetId, reason: "remotePause", state: .paused, audioAsset: asset)
             }
             return .success
         }
@@ -280,6 +340,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                         duration: duration
                     )
                 }
+                self.notifyPlaybackState(assetId: assetId, reason: "remoteStop", state: .stopped, audioAsset: asset)
             }
             return .success
         }
@@ -304,8 +365,9 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
 
                     asset.pause()
                     self.updatePlaybackState(isPlaying: false, elapsedTime: timeBeforePause, duration: asset.getDuration())
+                    self.notifyPlaybackState(assetId: assetId, reason: "remotePause", state: .paused, audioAsset: asset)
                 } else {
-                    self.resumeAssetFromStoredPausePositionIfNeeded(assetId: assetId, asset: asset)
+                    self.resumeAssetFromStoredPausePositionIfNeeded(assetId: assetId, asset: asset, reason: "remotePlay")
                 }
             }
             return .success
@@ -713,7 +775,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             }
 
             // Set up completion handler
-            asset.onComplete = { [weak self] in
+            asset.onComplete = {
                 cleanupHandler()
             }
 
@@ -728,6 +790,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                     self.updateNowPlayingInfo(audioId: assetId, audioAsset: asset)
                     self.updatePlaybackState(isPlaying: true)
                 }
+                self.notifyPlaybackState(assetId: assetId, reason: "playOnce", state: .playing, audioAsset: asset)
             }
 
             // Return the generated assetId
@@ -799,14 +862,13 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
         // Instead, check if all players are done and clear Now Playing if this asset was current
         audioQueue.async { [weak self] in
             guard let self = self else { return }
+            var completedAssetId: String?
 
             // Find which asset this player belongs to; if it was the currently playing one, clear notification
             for (audioId, asset) in self.audioList {
                 if let audioAsset = asset as? AudioAsset, audioAsset.channels.contains(player) {
-                    if self.currentlyPlayingAssetId == audioId {
-                        self.currentlyPlayingAssetId = nil
-                        self.clearNowPlayingInfo()
-                    }
+                    completedAssetId = audioId
+                    self.handlePlaybackCompletion(assetId: audioId, audioAsset: audioAsset)
                     break
                 }
             }
@@ -823,7 +885,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             // Only end the session if no more assets are playing
             if !hasPlayingAssets {
                 // If we didn't find the asset above (e.g. playOnce already removed it), clear notification when nothing is playing
-                if self.currentlyPlayingAssetId != nil {
+                if completedAssetId == nil, self.currentlyPlayingAssetId != nil {
                     self.currentlyPlayingAssetId = nil
                     self.clearNowPlayingInfo()
                 }
@@ -890,6 +952,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                             self.updateNowPlayingInfo(audioId: audioId, audioAsset: audioAsset)
                             self.updatePlaybackState(isPlaying: true)
                         }
+                        self.notifyPlaybackState(assetId: audioId, reason: "play", state: .playing, audioAsset: audioAsset)
                         call.resolve()
                     }
                 }
@@ -971,6 +1034,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
         }
     }
 
+    // swiftlint:disable:next function_body_length
     @objc func resume(_ call: CAPPluginCall) {
         let audioId = call.getString(Constant.AssetIdKey) ?? ""
         audioQueue.sync {
@@ -1015,13 +1079,15 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                     self.audioAssetData[audioAsset.assetId] = data
                 }
                 if self.showNotification {
+                    self.currentlyPlayingAssetId = audioId
                     self.updateNowPlayingInfo(audioId: audioId, audioAsset: audioAsset)
                 }
+                self.notifyPlaybackState(assetId: audioId, reason: "resume", state: .playing, audioAsset: audioAsset)
                 call.resolve()
             }
 
-            if let t = restoredTime {
-                audioAsset.setCurrentTime(time: t) { [weak self] in
+            if let resumeTime = restoredTime {
+                audioAsset.setCurrentTime(time: resumeTime) { [weak self] in
                     guard let self else { return }
                     self.audioQueue.async(flags: .barrier, execute: finishResume)
                 }
@@ -1064,6 +1130,9 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             }
 
             self.endSession()
+            if !fadeOut {
+                self.notifyPlaybackState(assetId: audioAsset.assetId, reason: "pause", state: .paused, audioAsset: audioAsset)
+            }
             call.resolve()
         }
     }
@@ -1120,6 +1189,13 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
                 }
 
                 self.endSession()
+                if !fadeOut {
+                    if let audioAsset = self.audioList[audioId] as? AudioAsset {
+                        self.notifyPlaybackState(assetId: audioId, reason: "stop", state: .stopped, audioAsset: audioAsset)
+                    } else {
+                        self.notifyPlaybackState(assetId: audioId, reason: "stop", state: .stopped)
+                    }
+                }
                 call.resolve()
             } catch {
                 call.reject(error.localizedDescription)
@@ -1137,6 +1213,12 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             }
 
             audioAsset.loop()
+            if self.showNotification {
+                self.currentlyPlayingAssetId = audioAsset.assetId
+                self.updateNowPlayingInfo(audioId: audioAsset.assetId, audioAsset: audioAsset)
+                self.updatePlaybackState(isPlaying: true)
+            }
+            self.notifyPlaybackState(assetId: audioAsset.assetId, reason: "loop", state: .playing, audioAsset: audioAsset)
             call.resolve()
         }
     }
@@ -1552,6 +1634,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
         call.resolve()
     }
 
+    // swiftlint:disable cyclomatic_complexity
     /// Updates the system Now Playing information for the specified audio asset.
     ///
     /// Looks up stored metadata for `audioId` and publishes title, artist, album, artwork (if provided),
@@ -1613,6 +1696,7 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             MPNowPlayingInfoCenter.default().nowPlayingInfo = nowPlayingInfo
         }
     }
+    // swiftlint:enable cyclomatic_complexity
 
     /// Clears the Now Playing info when the plugin is no longer the active notifier.
     private func clearNowPlayingInfo() {
@@ -1631,6 +1715,11 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             if self.showNotification && self.currentlyPlayingAssetId == assetId {
                 self.updatePlaybackState(isPlaying: false, elapsedTime: elapsedTime, duration: duration)
             }
+            if let audioAsset = self.audioList[assetId] as? AudioAsset {
+                self.notifyPlaybackState(assetId: assetId, reason: "pause", state: .paused, audioAsset: audioAsset)
+            } else {
+                self.notifyPlaybackState(assetId: assetId, reason: "pause", state: .paused)
+            }
         }
     }
 
@@ -1641,6 +1730,11 @@ public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
             if self.showNotification && self.currentlyPlayingAssetId == assetId {
                 self.updatePlaybackState(isPlaying: false, elapsedTime: elapsedTime, duration: duration)
             }
+            if let audioAsset = self.audioList[assetId] as? AudioAsset {
+                self.notifyPlaybackState(assetId: assetId, reason: "stop", state: .stopped, audioAsset: audioAsset)
+            } else {
+                self.notifyPlaybackState(assetId: assetId, reason: "stop", state: .stopped)
+            }
         }
     }
 

package/ios/Sources/NativeAudioPlugin/RemoteAudioAsset.swift

@@ -1,5 +1,6 @@
 @preconcurrency import AVFoundation
 
+// swiftlint:disable file_length
 // swiftlint:disable:next type_body_length
 public class RemoteAudioAsset: AudioAsset {
     var playerItems: [AVPlayerItem] = []
@@ -89,6 +90,7 @@ public class RemoteAudioAsset: AudioAsset {
             guard let self else { return }
             self.owner?.notifyListeners("complete", data: ["assetId": self.assetId])
             self.dispatchedCompleteMap[self.assetId] = true
+            self.owner?.handlePlaybackCompletion(assetId: self.assetId, audioAsset: self)
             self.onComplete?()
         }
     }
@@ -153,11 +155,11 @@ public class RemoteAudioAsset: AudioAsset {
             let lowerBound = max(time, 0)
             let validTime: TimeInterval
             if let item = player.currentItem {
-                let d = item.duration
-                if d == .indefinite || !d.isValid {
+                let itemDuration = item.duration
+                if itemDuration == .indefinite || !itemDuration.isValid {
                     validTime = lowerBound
                 } else {
-                    let durationSeconds = d.seconds
+                    let durationSeconds = itemDuration.seconds
                     if durationSeconds.isFinite && durationSeconds > 0 {
                         validTime = min(lowerBound, durationSeconds)
                     } else {
@@ -400,3 +402,4 @@ public class RemoteAudioAsset: AudioAsset {
     }
 
 }
+// swiftlint:enable file_length

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/native-audio",
-  "version": "8.4.0",
+  "version": "8.4.1",
   "description": "A native plugin for native audio engine",
   "license": "MPL-2.0",
   "main": "dist/plugin.cjs.js",
@@ -36,23 +36,29 @@
   ],
   "scripts": {
     "capacitor:sync:after": "node scripts/configure-dependencies.js",
-    "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
+    "verify": "bun run verify:ios && bun run verify:android && bun run verify:web",
     "verify:ios": "xcodebuild -scheme CapgoNativeAudio -destination generic/platform=iOS",
     "verify:android": "cd android && ./gradlew clean build test && cd ..",
-    "verify:web": "npm run build",
-    "test": "npm run test:ios",
+    "verify:web": "bun run build",
+    "test": "bun run test:ios",
     "test:ios": "cd ios && xcodebuild test -workspace Plugin.xcworkspace -scheme Plugin -destination 'platform=iOS Simulator,name=iPhone 16' && cd ..",
-    "lint": "npm run eslint && npm run prettier -- --check && npm run swiftlint -- lint",
-    "fmt": "npm run eslint -- --fix && npm run prettier -- --write && npm run swiftlint -- --fix --format",
+    "lint": "bun run eslint && bun run prettier -- --check && bun run swiftlint -- lint",
+    "fmt": "bun run eslint -- --fix && bun run prettier -- --write && bun run swiftlint -- --fix --format",
     "eslint": "eslint . --ext .ts",
     "prettier": "prettier-pretty-check \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
     "swiftlint": "node-swiftlint",
     "docgen": "docgen --api NativeAudio --output-readme README.md --output-json dist/docs.json",
-    "build": "npm run clean && npm run docgen && npm run build:scripts && tsc && rollup -c rollup.config.mjs",
+    "build": "bun run clean && bun run docgen && bun run build:scripts && tsc && rollup -c rollup.config.mjs",
     "build:scripts": "tsc -p scripts/tsconfig.json",
     "clean": "rimraf ./dist",
     "watch": "tsc --watch",
-    "prepublishOnly": "npm run build"
+    "example:install": "cd example-app && bun install",
+    "example:build": "cd example-app && bun run build",
+    "example:sync:android": "cd example-app && bun run sync:android",
+    "example:sync:ios": "cd example-app && bun run sync:ios",
+    "test:e2e:android": "maestro test .maestro/android/basic-features.yaml",
+    "test:e2e:ios": "maestro test .maestro/ios/basic-features.yaml",
+    "prepublishOnly": "bun run build"
   },
   "devDependencies": {
     "@capacitor/android": "^8.0.0",