@capgo/native-audio 8.2.12 → 8.2.13

package/dist/esm/definitions.d.ts

@@ -23,6 +23,10 @@ export interface AssetVolume {
      * Volume of the audio, between 0.1 and 1.0
      */
     volume: number;
+    /**
+     * Time over which to fade to the target volume, in seconds. Default is 0s (immediate).
+     */
+    duration?: number;
 }
 export interface AssetRate {
     /**
@@ -34,25 +38,106 @@ export interface AssetRate {
      */
     rate: number;
 }
+export interface AssetSetTime {
+    /**
+     * Asset Id, unique identifier of the file
+     */
+    assetId: string;
+    /**
+     * Time to set the audio, in seconds
+     */
+    time: number;
+}
 export interface AssetPlayOptions {
     /**
      * Asset Id, unique identifier of the file
      */
     assetId: string;
     /**
-     * Time to start playing the audio, in milliseconds
+     * Time to start playing the audio, in seconds
      */
     time?: number;
     /**
-     * Delay to start playing the audio, in milliseconds
+     * Delay to start playing the audio, in seconds
      */
     delay?: number;
+    /**
+     * Volume of the audio, between 0.1 and 1.0
+     */
+    volume?: number;
+    /**
+     * Whether to fade in the audio
+     */
+    fadeIn?: boolean;
+    /**
+     * Whether to fade out the audio
+     */
+    fadeOut?: boolean;
+    /**
+     * Fade in duration in seconds.
+     * Only used if fadeIn is true.
+     * Default is 1s.
+     */
+    fadeInDuration?: number;
+    /**
+     * Fade out duration in seconds.
+     * Only used if fadeOut is true.
+     * Default is 1s.
+     */
+    fadeOutDuration?: number;
+    /**
+     * Time in seconds from the start of the audio to start fading out.
+     * Only used if fadeOut is true.
+     * Default is fadeOutDuration before end of audio.
+     */
+    fadeOutStartTime?: number;
 }
-export interface ConfigureOptions {
+export interface AssetStopOptions {
+    /**
+     * Asset Id, unique identifier of the file
+     */
+    assetId: string;
+    /**
+     * Whether to fade out the audio before stopping
+     */
+    fadeOut?: boolean;
+    /**
+     * Fade out duration in seconds.
+     * Default is 1s.
+     */
+    fadeOutDuration?: number;
+}
+export interface AssetPauseOptions {
+    /**
+     * Asset Id, unique identifier of the file
+     */
+    assetId: string;
+    /**
+     * Whether to fade out the audio before pausing
+     */
+    fadeOut?: boolean;
+    /**
+     * Fade out duration in seconds.
+     * Default is 1s.
+     */
+    fadeOutDuration?: number;
+}
+export interface AssetResumeOptions {
+    /**
+     * Asset Id, unique identifier of the file
+     */
+    assetId: string;
     /**
-     * Play the audio with Fade effect, only available for IOS
+     * Whether to fade in the audio during resume
      */
-    fade?: boolean;
+    fadeIn?: boolean;
+    /**
+     * Fade in duration in seconds.
+     * Default is 1s.
+     */
+    fadeInDuration?: number;
+}
+export interface ConfigureOptions {
     /**
      * focus the audio with Audio Focus
      */
@@ -338,28 +423,24 @@ export interface NativeAudio {
     /**
      * Play an audio file
      * @since 5.0.0
-     * @param option {@link PlayOptions}
+     * @param option {@link AssetPlayOptions}
      * @returns
      */
-    play(options: {
-        assetId: string;
-        time?: number;
-        delay?: number;
-    }): Promise<void>;
+    play(options: AssetPlayOptions): Promise<void>;
     /**
      * Pause an audio file
      * @since 5.0.0
-     * @param option {@link Assets}
+     * @param option {@link AssetPauseOptions}
      * @returns
      */
-    pause(options: Assets): Promise<void>;
+    pause(options: AssetPauseOptions): Promise<void>;
     /**
      * Resume an audio file
      * @since 5.0.0
-     * @param option {@link Assets}
+     * @param option {@link AssetResumeOptions}
      * @returns
      */
-    resume(options: Assets): Promise<void>;
+    resume(options: AssetResumeOptions): Promise<void>;
     /**
      * Stop an audio file
      * @since 5.0.0
@@ -370,10 +451,10 @@ export interface NativeAudio {
     /**
      * Stop an audio file
      * @since 5.0.0
-     * @param option {@link Assets}
+     * @param option {@link AssetStopOptions}
      * @returns
      */
-    stop(options: Assets): Promise<void>;
+    stop(options: AssetStopOptions): Promise<void>;
     /**
      * Unload an audio file
      * @since 5.0.0
@@ -387,45 +468,34 @@ export interface NativeAudio {
      * @param option {@link AssetVolume}
      * @returns {Promise<void>}
      */
-    setVolume(options: {
-        assetId: string;
-        volume: number;
-    }): Promise<void>;
+    setVolume(options: AssetVolume): Promise<void>;
     /**
      * Set the rate of an audio file
      * @since 5.0.0
-     * @param option {@link AssetPlayOptions}
+     * @param option {@link AssetRate}
      * @returns {Promise<void>}
      */
-    setRate(options: {
-        assetId: string;
-        rate: number;
-    }): Promise<void>;
+    setRate(options: AssetRate): Promise<void>;
     /**
      * Set the current time of an audio file
      * @since 6.5.0
-     * @param option {@link AssetPlayOptions}
+     * @param option {@link AssetSetTime}
      * @returns {Promise<void>}
      */
-    setCurrentTime(options: {
-        assetId: string;
-        time: number;
-    }): Promise<void>;
+    setCurrentTime(options: AssetSetTime): Promise<void>;
     /**
      * Get the current time of an audio file
      * @since 5.0.0
-     * @param option {@link AssetPlayOptions}
+     * @param option {@link Assets}
      * @returns {Promise<{ currentTime: number }>}
      */
-    getCurrentTime(options: {
-        assetId: string;
-    }): Promise<{
+    getCurrentTime(options: Assets): Promise<{
         currentTime: number;
     }>;
     /**
-     * Get the duration of an audio file
+     * Get the duration of an audio file in seconds
      * @since 5.0.0
-     * @param option {@link AssetPlayOptions}
+     * @param option {@link Assets}
      * @returns {Promise<{ duration: number }>}
      */
     getDuration(options: Assets): Promise<{
@@ -435,7 +505,7 @@ export interface NativeAudio {
      * Check if an audio file is playing
      *
      * @since 5.0.0
-     * @param option {@link AssetPlayOptions}
+     * @param option {@link Assets}
      * @returns {Promise<boolean>}
      */
     isPlaying(options: Assets): Promise<{
@@ -462,6 +532,14 @@ export interface NativeAudio {
      * @returns {Promise<void>}
      */
     clearCache(): Promise<void>;
+    /**
+     * Set debug mode logging
+     * @since 6.5.0
+     * @param options - Options to enable or disable debug mode
+     */
+    setDebugMode(options: {
+        enabled: boolean;
+    }): Promise<void>;
     /**
      * Get the native Capacitor plugin version
      *

package/dist/esm/definitions.js.map

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

package/dist/esm/web.d.ts

@@ -1,31 +1,36 @@
 import { WebPlugin } from '@capacitor/core';
-import type { ConfigureOptions, PlayOnceOptions, PlayOnceResult, PreloadOptions } from './definitions';
+import type { Assets, AssetPauseOptions, AssetPlayOptions, AssetRate, AssetResumeOptions, AssetSetTime, AssetStopOptions, AssetVolume, ConfigureOptions, PlayOnceOptions, PlayOnceResult, PreloadOptions } from './definitions';
 import { NativeAudio } from './definitions';
 export declare class NativeAudioWeb extends WebPlugin implements NativeAudio {
+    private static readonly LOG_TAG;
     private static readonly FILE_LOCATION;
+    private static readonly DEFAULT_FADE_DURATION_SEC;
+    private static readonly CURRENT_TIME_UPDATE_INTERVAL;
+    private static readonly AUDIO_PRELOAD_OPTIONS_MAP;
+    private static readonly AUDIO_DATA_MAP;
     private static readonly AUDIO_ASSET_BY_ASSET_ID;
+    private static readonly AUDIO_CONTEXT_MAP;
+    private static readonly MEDIA_ELEMENT_SOURCE_MAP;
+    private static readonly GAIN_NODE_MAP;
     private static readonly playOnceAssets;
+    private debugMode;
+    private currentTimeIntervals;
+    private readonly zeroVolume;
     constructor();
-    resume(options: {
-        assetId: string;
-    }): Promise<void>;
-    pause(options: {
-        assetId: string;
-    }): Promise<void>;
-    setCurrentTime(options: {
-        assetId: string;
-        time: number;
-    }): Promise<void>;
-    getCurrentTime(options: {
-        assetId: string;
-    }): Promise<{
+    resume(options: AssetResumeOptions): Promise<void>;
+    private doResume;
+    pause(options: AssetPauseOptions): Promise<void>;
+    private doPause;
+    setCurrentTime(options: AssetSetTime): Promise<void>;
+    getCurrentTime(options: Assets): Promise<{
         currentTime: number;
     }>;
-    getDuration(options: {
-        assetId: string;
-    }): Promise<{
+    getDuration(options: Assets): Promise<{
         duration: number;
     }>;
+    setDebugMode(options: {
+        enabled: boolean;
+    }): Promise<void>;
     configure(options: ConfigureOptions): Promise<void>;
     isPreloaded(options: PreloadOptions): Promise<{
         found: boolean;
@@ -33,35 +38,41 @@ export declare class NativeAudioWeb extends WebPlugin implements NativeAudio {
     preload(options: PreloadOptions): Promise<void>;
     playOnce(options: PlayOnceOptions): Promise<PlayOnceResult>;
     private onEnded;
-    play(options: {
-        assetId: string;
-        time?: number;
-    }): Promise<void>;
-    loop(options: {
-        assetId: string;
-    }): Promise<void>;
-    stop(options: {
-        assetId: string;
-    }): Promise<void>;
-    unload(options: {
-        assetId: string;
-    }): Promise<void>;
-    setVolume(options: {
-        assetId: string;
-        volume: number;
-    }): Promise<void>;
-    setRate(options: {
-        assetId: string;
-        rate: number;
-    }): Promise<void>;
-    isPlaying(options: {
-        assetId: string;
-    }): Promise<{
+    play(options: AssetPlayOptions): Promise<void>;
+    private doPlay;
+    private doFadeIn;
+    private doFadeOut;
+    loop(options: Assets): Promise<void>;
+    stop(options: AssetStopOptions): Promise<void>;
+    private doStop;
+    private reset;
+    private clearFadeOutToStopTimer;
+    private clearStartTimer;
+    unload(options: Assets): Promise<void>;
+    private cleanupAudioContext;
+    setVolume(options: AssetVolume): Promise<void>;
+    setRate(options: AssetRate): Promise<void>;
+    isPlaying(options: Assets): Promise<{
         isPlaying: boolean;
     }>;
     clearCache(): Promise<void>;
     private getAudioAsset;
     private checkAssetId;
+    private getOrCreateAudioContext;
+    private getOrCreateMediaElementSource;
+    private getOrCreateGainNode;
+    private setGainNodeVolume;
+    private exponentialRampGainNodeVolume;
+    private linearRampGainNodeVolume;
+    private cancelGainNodeRamp;
+    private startCurrentTimeUpdates;
+    private stopCurrentTimeUpdates;
+    private getAudioAssetData;
+    private setAudioAssetData;
+    private logError;
+    private logWarning;
+    private logInfo;
+    private logDebug;
     getPluginVersion(): Promise<{
         version: string;
     }>;