@capgo/native-audio 7.3.0 → 7.3.9

package/README.md

@@ -30,7 +30,9 @@
 # Capacitor Native Audio Plugin
 
 Capacitor plugin for native audio engine.
-Capacitor V6 - ✅ Support!
+Capacitor V7 - ✅ Support!
+
+Support local file, remote URL, and m3u8 stream
 
 Click on video to see example 💥
 
@@ -539,11 +541,12 @@ Clear the audio cache for remote audio files
 
 #### ConfigureOptions
 
-| Prop             | Type                 | Description                                             |
-| ---------------- | -------------------- | ------------------------------------------------------- |
-| **`fade`**       | <code>boolean</code> | Play the audio with Fade effect, only available for IOS |
-| **`focus`**      | <code>boolean</code> | focus the audio with Audio Focus                        |
-| **`background`** | <code>boolean</code> | Play the audio in the background                        |
+| Prop               | Type                 | Description                                                                   |
+| ------------------ | -------------------- | ----------------------------------------------------------------------------- |
+| **`fade`**         | <code>boolean</code> | Play the audio with Fade effect, only available for IOS                       |
+| **`focus`**        | <code>boolean</code> | focus the audio with Audio Focus                                              |
+| **`background`**   | <code>boolean</code> | Play the audio in the background                                              |
+| **`ignoreSilent`** | <code>boolean</code> | Ignore silent mode, works only on iOS setting this will nuke other audio apps |
 
 
 #### PreloadOptions
@@ -599,3 +602,21 @@ Clear the audio cache for remote audio files
 <code>(state: <a href="#currenttimeevent">CurrentTimeEvent</a>): void</code>
 
 </docgen-api>
+
+## Development and Testing
+
+### Building
+
+```bash
+npm run build
+```
+
+### Testing
+
+This plugin includes a comprehensive test suite for iOS:
+
+1. Open the iOS project in Xcode: `npx cap open ios`
+2. Navigate to the `PluginTests` directory
+3. Run tests using Product > Test (⌘+U)
+
+The tests cover core functionality including audio asset initialization, playback, volume control, fade effects, and more. See the [test documentation](ios/PluginTests/README.md) for more details.

package/dist/docs.json

@@ -612,6 +612,13 @@
           "docs": "Play the audio in the background",
           "complexTypes": [],
           "type": "boolean | undefined"
+        },
+        {
+          "name": "ignoreSilent",
+          "tags": [],
+          "docs": "Ignore silent mode, works only on iOS setting this will nuke other audio apps",
+          "complexTypes": [],
+          "type": "boolean | undefined"
         }
       ]
     },

package/dist/esm/definitions.d.ts

@@ -61,6 +61,10 @@ export interface ConfigureOptions {
      * Play the audio in the background
      */
     background?: boolean;
+    /**
+     * Ignore silent mode, works only on iOS setting this will nuke other audio apps
+     */
+    ignoreSilent?: boolean;
 }
 export interface PreloadOptions {
     /**

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\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\nexport interface CurrentTimeEvent {\n  /**\n   * Current time of the audio in seconds\n   * @since 6.5.0\n   */\n  currentTime: number;\n  /**\n   * Asset Id of the audio\n   * @since 6.5.0\n   */\n  assetId: string;\n}\nexport type CurrentTimeListener = (state: CurrentTimeEvent) => void;\n\nexport interface NativeAudio {\n  /**\n   * Configure the audio player\n   * @since 5.0.0\n   * @param option {@link ConfigureOptions}\n   * @returns\n   */\n  configure(options: ConfigureOptions): Promise<void>;\n  /**\n   * Load an audio file\n   * @since 5.0.0\n   * @param option {@link PreloadOptions}\n   * @returns\n   */\n  preload(options: PreloadOptions): Promise<void>;\n  /**\n   * Check if an audio file is preloaded\n   *\n   * @since 6.1.0\n   * @param option {@link Assets}\n   * @returns {Promise<boolean>}\n   */\n  isPreloaded(options: PreloadOptions): Promise<{ found: boolean }>;\n  /**\n   * Play an audio file\n   * @since 5.0.0\n   * @param option {@link PlayOptions}\n   * @returns\n   */\n  play(options: { assetId: string; time?: number; delay?: number }): Promise<void>;\n  /**\n   * Pause an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  pause(options: Assets): Promise<void>;\n  /**\n   * Resume an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  resume(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  loop(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  stop(options: Assets): Promise<void>;\n  /**\n   * Unload an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  unload(options: Assets): Promise<void>;\n  /**\n   * Set the volume of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetVolume}\n   * @returns {Promise<void>}\n   */\n  setVolume(options: { assetId: string; volume: number }): Promise<void>;\n  /**\n   * Set the rate of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setRate(options: { assetId: string; rate: number }): Promise<void>;\n  /**\n   * Set the current time of an audio file\n   * @since 6.5.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setCurrentTime(options: { assetId: string; time: number }): Promise<void>;\n  /**\n   * Get the current time of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ currentTime: number }>}\n   */\n  getCurrentTime(options: { assetId: string }): Promise<{ currentTime: number }>;\n  /**\n   * Get the duration of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ duration: number }>}\n   */\n  getDuration(options: Assets): Promise<{ duration: number }>;\n  /**\n   * Check if an audio file is playing\n   *\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<boolean>}\n   */\n  isPlaying(options: Assets): Promise<{ isPlaying: boolean }>;\n  /**\n   * Listen for complete event\n   *\n   * @since 5.0.0\n   * return {@link CompletedEvent}\n   */\n  addListener(eventName: 'complete', listenerFunc: CompletedListener): Promise<PluginListenerHandle>;\n  /**\n   * Listen for current time updates\n   * Emits every 100ms while audio is playing\n   *\n   * @since 6.5.0\n   * return {@link CurrentTimeEvent}\n   */\n  addListener(eventName: 'currentTime', listenerFunc: CurrentTimeListener): Promise<PluginListenerHandle>;\n  /**\n   * Clear the audio cache for remote audio files\n   * @since 6.5.0\n   * @returns {Promise<void>}\n   */\n  clearCache(): Promise<void>;\n}\n"]}
+{"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\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\nexport interface CurrentTimeEvent {\n  /**\n   * Current time of the audio in seconds\n   * @since 6.5.0\n   */\n  currentTime: number;\n  /**\n   * Asset Id of the audio\n   * @since 6.5.0\n   */\n  assetId: string;\n}\nexport type CurrentTimeListener = (state: CurrentTimeEvent) => void;\n\nexport interface NativeAudio {\n  /**\n   * Configure the audio player\n   * @since 5.0.0\n   * @param option {@link ConfigureOptions}\n   * @returns\n   */\n  configure(options: ConfigureOptions): Promise<void>;\n  /**\n   * Load an audio file\n   * @since 5.0.0\n   * @param option {@link PreloadOptions}\n   * @returns\n   */\n  preload(options: PreloadOptions): Promise<void>;\n  /**\n   * Check if an audio file is preloaded\n   *\n   * @since 6.1.0\n   * @param option {@link Assets}\n   * @returns {Promise<boolean>}\n   */\n  isPreloaded(options: PreloadOptions): Promise<{ found: boolean }>;\n  /**\n   * Play an audio file\n   * @since 5.0.0\n   * @param option {@link PlayOptions}\n   * @returns\n   */\n  play(options: { assetId: string; time?: number; delay?: number }): Promise<void>;\n  /**\n   * Pause an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  pause(options: Assets): Promise<void>;\n  /**\n   * Resume an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  resume(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  loop(options: Assets): Promise<void>;\n  /**\n   * Stop an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  stop(options: Assets): Promise<void>;\n  /**\n   * Unload an audio file\n   * @since 5.0.0\n   * @param option {@link Assets}\n   * @returns\n   */\n  unload(options: Assets): Promise<void>;\n  /**\n   * Set the volume of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetVolume}\n   * @returns {Promise<void>}\n   */\n  setVolume(options: { assetId: string; volume: number }): Promise<void>;\n  /**\n   * Set the rate of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setRate(options: { assetId: string; rate: number }): Promise<void>;\n  /**\n   * Set the current time of an audio file\n   * @since 6.5.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<void>}\n   */\n  setCurrentTime(options: { assetId: string; time: number }): Promise<void>;\n  /**\n   * Get the current time of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ currentTime: number }>}\n   */\n  getCurrentTime(options: { assetId: string }): Promise<{ currentTime: number }>;\n  /**\n   * Get the duration of an audio file\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<{ duration: number }>}\n   */\n  getDuration(options: Assets): Promise<{ duration: number }>;\n  /**\n   * Check if an audio file is playing\n   *\n   * @since 5.0.0\n   * @param option {@link AssetPlayOptions}\n   * @returns {Promise<boolean>}\n   */\n  isPlaying(options: Assets): Promise<{ isPlaying: boolean }>;\n  /**\n   * Listen for complete event\n   *\n   * @since 5.0.0\n   * return {@link CompletedEvent}\n   */\n  addListener(eventName: 'complete', listenerFunc: CompletedListener): Promise<PluginListenerHandle>;\n  /**\n   * Listen for current time updates\n   * Emits every 100ms while audio is playing\n   *\n   * @since 6.5.0\n   * return {@link CurrentTimeEvent}\n   */\n  addListener(eventName: 'currentTime', listenerFunc: CurrentTimeListener): Promise<PluginListenerHandle>;\n  /**\n   * Clear the audio cache for remote audio files\n   * @since 6.5.0\n   * @returns {Promise<void>}\n   */\n  clearCache(): Promise<void>;\n}\n"]}

package/ios/Plugin/AudioAsset.swift

@@ -8,6 +8,10 @@
 
 import AVFoundation
 
+/**
+ * AudioAsset class handles local audio playback via AVAudioPlayer
+ * Supports volume control, fade effects, rate changes, and looping
+ */
 public class AudioAsset: NSObject, AVAudioPlayerDelegate {
 
     var channels: [AVAudioPlayer] = []
@@ -15,159 +19,266 @@ public class AudioAsset: NSObject, AVAudioPlayerDelegate {
     var assetId: String = ""
     var initialVolume: Float = 1.0
     var fadeDelay: Float = 1.0
-    var owner: NativeAudio
+    weak var owner: NativeAudio?
 
+    // Constants for fade effect
     let FADESTEP: Float = 0.05
     let FADEDELAY: Float = 0.08
 
-    private var currentTimeTimer: Timer?
+    // Maximum number of channels to prevent excessive resource usage
+    private let MAX_CHANNELS = Constant.MaxChannels
 
+    private var currentTimeTimer: Timer?
+    internal var fadeTimer: Timer?
+
+    /**
+     * Initialize a new audio asset
+     * - Parameters:
+     *   - owner: The plugin that owns this asset
+     *   - assetId: Unique identifier for this asset
+     *   - path: File path to the audio file
+     *   - channels: Number of simultaneous playback channels (polyphony)
+     *   - volume: Initial volume (0.0-1.0)
+     *   - delay: Fade delay in seconds
+     */
     init(owner: NativeAudio, withAssetId assetId: String, withPath path: String!, withChannels channels: Int!, withVolume volume: Float!, withFadeDelay delay: Float!) {
 
         self.owner = owner
         self.assetId = assetId
         self.channels = []
-        self.initialVolume = volume ?? 1.0
+        self.initialVolume = min(max(volume ?? Constant.DefaultVolume, Constant.MinVolume), Constant.MaxVolume) // Validate volume range
+        self.fadeDelay = max(delay ?? Constant.DefaultFadeDelay, 0.0) // Ensure non-negative delay
 
         super.init()
 
-        let pathUrl: URL = URL(string: path.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed)!)!
+        guard let encodedPath = path.addingPercentEncoding(withAllowedCharacters: .urlQueryAllowed) else {
+            print("Failed to encode path: \(String(describing: path))")
+            return
+        }
+
+        // Try to create URL from string first, fall back to file URL if that fails
+        let pathUrl: URL
+        if let url = URL(string: encodedPath) {
+            pathUrl = url
+        } else {
+            pathUrl = URL(fileURLWithPath: encodedPath)
+        }
+
+        // Limit channels to a reasonable maximum to prevent resource issues
+        let channelCount = min(max(channels ?? 1, 1), MAX_CHANNELS)
 
         owner.executeOnAudioQueue { [self] in
-            for _ in 0..<channels {
+            for _ in 0..<channelCount {
                 do {
-                    let player: AVAudioPlayer! = try AVAudioPlayer(contentsOf: pathUrl)
+                    let player = try AVAudioPlayer(contentsOf: pathUrl)
                     player.delegate = self
-                    if player != nil {
-                        player.enableRate = true
-                        player.volume = volume
-                        player.rate = 1.0
-                        player.prepareToPlay()
-                        self.channels.append(player)
-                    }
-                } catch let error as NSError {
-                    print(error.debugDescription)
-                    print("Error loading \(String(describing: path))")
+                    player.enableRate = true
+                    player.volume = self.initialVolume
+                    player.rate = 1.0
+                    player.prepareToPlay()
+                    self.channels.append(player)
+                } catch {
+                    print("Error loading audio file: \(error.localizedDescription)")
+                    print("Path: \(String(describing: path))")
                 }
             }
         }
     }
 
+    deinit {
+        stopCurrentTimeUpdates()
+        stopFadeTimer()
+        // Clean up any players that might still be playing
+        for player in channels {
+            if player.isPlaying {
+                player.stop()
+            }
+        }
+    }
+
+    /**
+     * Get the current playback time
+     * - Returns: Current time in seconds
+     */
     func getCurrentTime() -> TimeInterval {
         var result: TimeInterval = 0
-        owner.executeOnAudioQueue { [self] in
-            if channels.count != 1 {
+        owner?.executeOnAudioQueue { [self] in
+            if channels.isEmpty || playIndex >= channels.count {
                 result = 0
                 return
             }
-            let player: AVAudioPlayer = channels[playIndex]
+            let player = channels[playIndex]
             result = player.currentTime
         }
         return result
     }
 
+    /**
+     * Set the current playback time
+     * - Parameter time: Time in seconds
+     */
     func setCurrentTime(time: TimeInterval) {
-        owner.executeOnAudioQueue { [self] in
-            if channels.count != 1 {
+        owner?.executeOnAudioQueue { [self] in
+            if channels.isEmpty || playIndex >= channels.count {
                 return
             }
-            let player: AVAudioPlayer = channels[playIndex]
-            player.currentTime = time
+            let player = channels[playIndex]
+            // Ensure time is valid
+            let validTime = min(max(time, 0), player.duration)
+            player.currentTime = validTime
         }
     }
 
+    /**
+     * Get the total duration of the audio file
+     * - Returns: Duration in seconds
+     */
     func getDuration() -> TimeInterval {
         var result: TimeInterval = 0
-        owner.executeOnAudioQueue { [self] in
-            if channels.count != 1 {
+        owner?.executeOnAudioQueue { [self] in
+            if channels.isEmpty || playIndex >= channels.count {
                 result = 0
                 return
             }
-            let player: AVAudioPlayer = channels[playIndex]
+            let player = channels[playIndex]
             result = player.duration
         }
         return result
     }
 
+    /**
+     * Play the audio from the specified time with optional delay
+     * - Parameters:
+     *   - time: Start time in seconds
+     *   - delay: Delay before playback in seconds
+     */
     func play(time: TimeInterval, delay: TimeInterval) {
-        owner.executeOnAudioQueue { [self] in
-            guard !channels.isEmpty else {
-                NSLog("No channels available")
-                return
-            }
-            guard playIndex < channels.count else {
-                NSLog("PlayIndex out of bounds")
+        owner?.executeOnAudioQueue { [self] in
+            guard !channels.isEmpty else { return }
+
+            // Reset play index if it's out of bounds
+            if playIndex >= channels.count {
                 playIndex = 0
-                return
             }
 
             let player = channels[playIndex]
-            player.currentTime = time
+            // Ensure time is within valid range
+            let validTime = min(max(time, 0), player.duration)
+            player.currentTime = validTime
             player.numberOfLoops = 0
-            if delay > 0 {
-                player.play(atTime: player.deviceCurrentTime + delay)
+
+            // Use a valid delay (non-negative)
+            let validDelay = max(delay, 0)
+
+            if validDelay > 0 {
+                player.play(atTime: player.deviceCurrentTime + validDelay)
             } else {
                 player.play()
             }
-            playIndex += 1
-            playIndex = playIndex % channels.count
-            NSLog("About to start timer updates")
+            playIndex = (playIndex + 1) % channels.count
             startCurrentTimeUpdates()
         }
     }
 
     func playWithFade(time: TimeInterval) {
-        owner.executeOnAudioQueue { [self] in
-            guard !channels.isEmpty else {
-                NSLog("No channels available")
-                return
-            }
-            guard playIndex < channels.count else {
-                NSLog("PlayIndex out of bounds")
+        owner?.executeOnAudioQueue { [self] in
+            guard !channels.isEmpty else { return }
+
+            // Reset play index if it's out of bounds
+            if playIndex >= channels.count {
                 playIndex = 0
-                return
             }
 
-            let player: AVAudioPlayer = channels[playIndex]
+            let player = channels[playIndex]
             player.currentTime = time
 
             if !player.isPlaying {
                 player.numberOfLoops = 0
-                player.volume = initialVolume
+                player.volume = 0 // Start with volume at 0
                 player.play()
-                playIndex += 1
-                playIndex = playIndex % channels.count
-                NSLog("PlayWithFade: About to start timer updates")
+                playIndex = (playIndex + 1) % channels.count
                 startCurrentTimeUpdates()
+
+                // Start fade-in
+                startVolumeRamp(from: 0, to: initialVolume, player: player)
             } else {
                 if player.volume < initialVolume {
-                    player.volume += self.FADESTEP
+                    // Continue fade-in if already in progress
+                    startVolumeRamp(from: player.volume, to: initialVolume, player: player)
                 }
             }
         }
     }
 
+    private func startVolumeRamp(from startVolume: Float, to endVolume: Float, player: AVAudioPlayer) {
+        stopFadeTimer()
+
+        let steps = abs(endVolume - startVolume) / FADESTEP
+        guard steps > 0 else { return }
+
+        let timeInterval = FADEDELAY / steps
+        var currentStep = 0
+        let totalSteps = Int(ceil(steps))
+
+        player.volume = startVolume
+
+        fadeTimer = Timer.scheduledTimer(withTimeInterval: TimeInterval(timeInterval), repeats: true) { [weak self, weak player] timer in
+            guard let strongSelf = self, let strongPlayer = player else {
+                timer.invalidate()
+                return
+            }
+
+            currentStep += 1
+            let progress = Float(currentStep) / Float(totalSteps)
+            let newVolume = startVolume + progress * (endVolume - startVolume)
+
+            strongPlayer.volume = newVolume
+
+            if currentStep >= totalSteps {
+                strongPlayer.volume = endVolume
+                timer.invalidate()
+                strongSelf.fadeTimer = nil
+            }
+        }
+        RunLoop.current.add(fadeTimer!, forMode: .common)
+    }
+
+    internal func stopFadeTimer() {
+        DispatchQueue.main.async { [weak self] in
+            self?.fadeTimer?.invalidate()
+            self?.fadeTimer = nil
+        }
+    }
+
     func pause() {
-        owner.executeOnAudioQueue { [self] in
+        owner?.executeOnAudioQueue { [self] in
             stopCurrentTimeUpdates()
-            let player: AVAudioPlayer = channels[playIndex]
+
+            // Check for valid playIndex
+            guard !channels.isEmpty && playIndex < channels.count else { return }
+
+            let player = channels[playIndex]
             player.pause()
         }
     }
 
     func resume() {
-        owner.executeOnAudioQueue { [self] in
-            let player: AVAudioPlayer = channels[playIndex]
+        owner?.executeOnAudioQueue { [self] in
+            // Check for valid playIndex
+            guard !channels.isEmpty && playIndex < channels.count else { return }
+
+            let player = channels[playIndex]
             let timeOffset = player.deviceCurrentTime + 0.01
             player.play(atTime: timeOffset)
-            NSLog("Resume: About to start timer updates")
             startCurrentTimeUpdates()
         }
     }
 
     func stop() {
-        owner.executeOnAudioQueue { [self] in
+        owner?.executeOnAudioQueue { [self] in
             stopCurrentTimeUpdates()
+            stopFadeTimer()
+
             for player in channels {
                 if player.isPlaying {
                     player.stop()
@@ -180,124 +291,131 @@ public class AudioAsset: NSObject, AVAudioPlayerDelegate {
     }
 
     func stopWithFade() {
-        owner.executeOnAudioQueue { [self] in
-            let player: AVAudioPlayer = channels[playIndex]
-            if player.isPlaying {
-                if player.volume > self.FADESTEP {
-                    player.volume -= self.FADESTEP
-                    // Schedule next fade step
-                    DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(Int(self.FADEDELAY * 1000))) { [weak self] in
-                        self?.stopWithFade()
+        // Store current player locally to avoid race conditions with playIndex
+        owner?.executeOnAudioQueue { [self] in
+            guard !channels.isEmpty && playIndex < channels.count else {
+                stop()
+                return
+            }
+
+            let player = channels[playIndex]
+            if player.isPlaying && player.volume > 0 {
+                startVolumeRamp(from: player.volume, to: 0, player: player)
+
+                // Schedule the stop when fade is complete
+                DispatchQueue.main.asyncAfter(deadline: .now() + .milliseconds(Int(FADEDELAY * 1000))) { [weak self, weak player] in
+                    guard let strongSelf = self, let strongPlayer = player else { return }
+
+                    if strongPlayer.volume < strongSelf.FADESTEP {
+                        strongSelf.stop()
                     }
-                } else {
-                    // Volume is near 0, actually stop
-                    player.volume = 0
-                    self.stop()
                 }
+            } else {
+                stop()
             }
         }
     }
 
     func loop() {
-        owner.executeOnAudioQueue { [self] in
+        owner?.executeOnAudioQueue { [self] in
             self.stop()
-            let player: AVAudioPlayer = channels[playIndex]
+
+            guard !channels.isEmpty && playIndex < channels.count else { return }
+
+            let player = channels[playIndex]
             player.delegate = self
             player.numberOfLoops = -1
             player.play()
-            playIndex += 1
-            playIndex = playIndex % channels.count
-            NSLog("Loop: About to start timer updates")
+            playIndex = (playIndex + 1) % channels.count
             startCurrentTimeUpdates()
         }
     }
 
     func unload() {
-        owner.executeOnAudioQueue { [self] in
+        owner?.executeOnAudioQueue { [self] in
             self.stop()
+            stopCurrentTimeUpdates()
+            stopFadeTimer()
             channels = []
         }
     }
 
+    /**
+     * Set the volume for all audio channels
+     * - Parameter volume: Volume level (0.0-1.0)
+     */
     func setVolume(volume: NSNumber!) {
-        owner.executeOnAudioQueue { [self] in
+        owner?.executeOnAudioQueue { [self] in
+            // Ensure volume is in valid range
+            let validVolume = min(max(volume.floatValue, Constant.MinVolume), Constant.MaxVolume)
             for player in channels {
-                player.volume = volume.floatValue
+                player.volume = validVolume
             }
         }
     }
 
+    /**
+     * Set the playback rate for all audio channels
+     * - Parameter rate: Playback rate (0.5-2.0 is typical range)
+     */
     func setRate(rate: NSNumber!) {
-        owner.executeOnAudioQueue { [self] in
+        owner?.executeOnAudioQueue { [self] in
+            // Ensure rate is in valid range
+            let validRate = min(max(rate.floatValue, Constant.MinRate), Constant.MaxRate)
             for player in channels {
-                player.rate = rate.floatValue
+                player.rate = validRate
             }
         }
     }
 
     public func audioPlayerDidFinishPlaying(_ player: AVAudioPlayer, successfully flag: Bool) {
-        owner.executeOnAudioQueue { [self] in
-            NSLog("playerDidFinish")
-            self.owner.notifyListeners("complete", data: [
+        owner?.executeOnAudioQueue { [self] in
+            self.owner?.notifyListeners("complete", data: [
                 "assetId": self.assetId
             ])
         }
     }
 
     func playerDecodeError(player: AVAudioPlayer!, error: NSError!) {
-
+        if let error = error {
+            print("AudioAsset decode error: \(error.localizedDescription)")
+        }
     }
 
     func isPlaying() -> Bool {
         var result: Bool = false
-        owner.executeOnAudioQueue { [self] in
-            if channels.count != 1 {
+        owner?.executeOnAudioQueue { [self] in
+            if channels.isEmpty || playIndex >= channels.count {
                 result = false
                 return
             }
-            let player: AVAudioPlayer = channels[playIndex]
+            let player = channels[playIndex]
             result = player.isPlaying
         }
         return result
     }
 
     internal func startCurrentTimeUpdates() {
-        NSLog("Starting timer updates")
         DispatchQueue.main.async { [weak self] in
-            guard let self = self else {
-                NSLog("Self is nil in timer start")
-                return
-            }
+            guard let strongSelf = self else { return }
 
-            self.currentTimeTimer?.invalidate()
-            self.currentTimeTimer = Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { [weak self] _ in
-                guard let self = self else {
-                    NSLog("Self is nil in timer callback")
-                    return
-                }
-
-                var shouldNotify = false
-                var currentTime: TimeInterval = 0
+            strongSelf.stopCurrentTimeUpdates() // Ensure no duplicate timers
 
-                self.owner.executeOnAudioQueue {
-                    shouldNotify = self.isPlaying()
-                    NSLog("isPlaying returned: \(shouldNotify)")
-                    if shouldNotify {
-                        currentTime = self.getCurrentTime()
-                        NSLog("getCurrentTime returned: \(currentTime)")
-                    }
+            strongSelf.currentTimeTimer = Timer.scheduledTimer(withTimeInterval: 0.1, repeats: true) { [weak self] _ in
+                guard let strongSelf = self, let strongOwner = strongSelf.owner else {
+                    self?.stopCurrentTimeUpdates()
+                    return
                 }
 
-                if shouldNotify {
-                    NSLog("Calling notifyCurrentTime")
-                    self.owner.notifyCurrentTime(self)
+                if strongSelf.isPlaying() {
+                    strongOwner.notifyCurrentTime(strongSelf)
                 } else {
-                    NSLog("Stopping timer - not playing")
-                    self.stopCurrentTimeUpdates()
+                    strongSelf.stopCurrentTimeUpdates()
                 }
             }
-            RunLoop.current.add(self.currentTimeTimer!, forMode: .common)
-            NSLog("Timer added to RunLoop")
+            if let timer = strongSelf.currentTimeTimer {
+                RunLoop.current.add(timer, forMode: .common)
+            }
         }
     }
 

package/ios/Plugin/Constant.swift

@@ -7,6 +7,7 @@
 //
 
 public class Constant {
+    // Parameter keys
     public static let FadeKey = "fade"
     public static let FocusAudio = "focus"
     public static let AssetPathKey = "assetPath"
@@ -17,6 +18,18 @@ public class Constant {
     public static let Background = "background"
     public static let IgnoreSilent = "ignoreSilent"
 
+    // Default values - used for consistency across the plugin
+    public static let DefaultVolume: Float = 1.0
+    public static let DefaultRate: Float = 1.0
+    public static let DefaultChannels: Int = 1
+    public static let DefaultFadeDelay: Float = 1.0
+    public static let MinRate: Float = 0.25
+    public static let MaxRate: Float = 4.0
+    public static let MinVolume: Float = 0.0
+    public static let MaxVolume: Float = 1.0
+    public static let MaxChannels: Int = 32
+
+    // Error messages
     public static let ErrorAssetId = "Asset Id is missing"
     public static let ErrorAssetPath = "Asset Path is missing"
     public static let ErrorAssetNotFound = "Asset is not loaded"