@capgo/native-audio 7.1.8 → 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 💥
 
@@ -481,7 +483,7 @@ Check if an audio file is playing
 ### addListener('complete', ...)
 
 ```typescript
-addListener(eventName: "complete", listenerFunc: CompletedListener) => Promise<PluginListenerHandle>
+addListener(eventName: 'complete', listenerFunc: CompletedListener) => Promise<PluginListenerHandle>
 ```
 
 Listen for complete event
@@ -499,27 +501,63 @@ return {@link CompletedEvent}
 --------------------
 
 
+### addListener('currentTime', ...)
+
+```typescript
+addListener(eventName: 'currentTime', listenerFunc: CurrentTimeListener) => Promise<PluginListenerHandle>
+```
+
+Listen for current time updates
+Emits every 100ms while audio is playing
+
+| Param              | Type                                                                |
+| ------------------ | ------------------------------------------------------------------- |
+| **`eventName`**    | <code>'currentTime'</code>                                          |
+| **`listenerFunc`** | <code><a href="#currenttimelistener">CurrentTimeListener</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#pluginlistenerhandle">PluginListenerHandle</a>&gt;</code>
+
+**Since:** 6.5.0
+return {@link CurrentTimeEvent}
+
+--------------------
+
+
+### clearCache()
+
+```typescript
+clearCache() => Promise<void>
+```
+
+Clear the audio cache for remote audio files
+
+**Since:** 6.5.0
+
+--------------------
+
+
 ### Interfaces
 
 
 #### 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
 
-| Prop                  | Type                 | Description                                                                                        |
-| --------------------- | -------------------- | -------------------------------------------------------------------------------------------------- |
-| **`assetPath`**       | <code>string</code>  | Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://) |
-| **`assetId`**         | <code>string</code>  | Asset Id, unique identifier of the file                                                            |
-| **`volume`**          | <code>number</code>  | Volume of the audio, between 0.1 and 1.0                                                           |
-| **`audioChannelNum`** | <code>number</code>  | Audio channel number, default is 1                                                                 |
-| **`isUrl`**           | <code>boolean</code> | Is the audio file a URL, pass true if assetPath is a `file://` url                                 |
+| Prop                  | Type                 | Description                                                                                                                                                                           |
+| --------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`assetPath`**       | <code>string</code>  | Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://) Supported formats: - MP3, WAV (all platforms) - M3U8/HLS streams (iOS and Android) |
+| **`assetId`**         | <code>string</code>  | Asset Id, unique identifier of the file                                                                                                                                               |
+| **`volume`**          | <code>number</code>  | Volume of the audio, between 0.1 and 1.0                                                                                                                                              |
+| **`audioChannelNum`** | <code>number</code>  | Audio channel number, default is 1                                                                                                                                                    |
+| **`isUrl`**           | <code>boolean</code> | Is the audio file a URL, pass true if assetPath is a `file://` url or a streaming URL (m3u8)                                                                                          |
 
 
 #### Assets
@@ -543,6 +581,14 @@ return {@link CompletedEvent}
 | **`assetId`** | <code>string</code> | Emit when a play completes | 5.0.0 |
 
 
+#### CurrentTimeEvent
+
+| Prop              | Type                | Description                          | Since |
+| ----------------- | ------------------- | ------------------------------------ | ----- |
+| **`currentTime`** | <code>number</code> | Current time of the audio in seconds | 6.5.0 |
+| **`assetId`**     | <code>string</code> | Asset Id of the audio                | 6.5.0 |
+
+
 ### Type Aliases
 
 
@@ -550,4 +596,27 @@ return {@link CompletedEvent}
 
 <code>(state: <a href="#completedevent">CompletedEvent</a>): void</code>
 
+
+#### CurrentTimeListener
+
+<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/android/build.gradle

@@ -1,8 +1,8 @@
 ext {
     junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
+    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
     androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.2.1'
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.6.1'
-    androidxAppCompatVersion = project.hasProperty('androidxAppCompatVersion') ? rootProject.ext.androidxAppCompatVersion : '1.7.0'
 }
 
 buildscript {
@@ -11,7 +11,7 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.7.2'
+        classpath 'com.android.tools.build:gradle:8.7.3'
     }
 }
 
@@ -35,8 +35,10 @@ android {
     }
     lintOptions {
         abortOnError false
-        disable "UnsafeExperimentalUsageError",
-                    "UnsafeExperimentalUsageWarning"
+    }
+    compileOptions {
+        sourceCompatibility JavaVersion.VERSION_21
+        targetCompatibility JavaVersion.VERSION_21
     }
 }
 
@@ -47,10 +49,17 @@ repositories {
 
 
 dependencies {
-    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
+    implementation "androidx.appcompat:appcompat:$androidxAppCompatVersion"
     testImplementation "junit:junit:$junitVersion"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
+    implementation 'androidx.media3:media3-exoplayer:1.5.1'
+    implementation 'androidx.media3:media3-exoplayer-hls:1.5.1'
+    implementation 'androidx.media3:media3-session:1.5.1'
+    implementation 'androidx.media3:media3-transformer:1.5.1'
+    implementation 'androidx.media3:media3-ui:1.5.1'
+    implementation 'androidx.media3:media3-database:1.5.1'
+    implementation 'androidx.media3:media3-common:1.5.1'
 }

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

@@ -2,190 +2,333 @@ package ee.forgr.audio;
 
 import android.content.res.AssetFileDescriptor;
 import android.os.Build;
+import android.os.Handler;
+import android.os.Looper;
+import android.util.Log;
 import androidx.annotation.RequiresApi;
 import java.util.ArrayList;
 
 public class AudioAsset {
 
-  private final String TAG = "AudioAsset";
-
-  private final ArrayList<AudioDispatcher> audioList;
-  private int playIndex = 0;
-  private final String assetId;
-  protected final NativeAudio owner;
-  protected AudioCompletionListener completionListener;
-
-  AudioAsset(
-    NativeAudio owner,
-    String assetId,
-    AssetFileDescriptor assetFileDescriptor,
-    int audioChannelNum,
-    float volume
-  ) throws Exception {
-    audioList = new ArrayList<>();
-    this.owner = owner;
-    this.assetId = assetId;
+    private final String TAG = "AudioAsset";
+
+    private final ArrayList<AudioDispatcher> audioList;
+    private int playIndex = 0;
+    protected final NativeAudio owner;
+    protected AudioCompletionListener completionListener;
+    protected String assetId;
+    private Handler currentTimeHandler;
+    private Runnable currentTimeRunnable;
+    private static final float FADE_STEP = 0.05f;
+    private static final int FADE_DELAY_MS = 80;
+    private float initialVolume;
+
+    AudioAsset(NativeAudio owner, String assetId, AssetFileDescriptor assetFileDescriptor, int audioChannelNum, float volume)
+        throws Exception {
+        audioList = new ArrayList<>();
+        this.owner = owner;
+        this.assetId = assetId;
+        this.initialVolume = volume;
+
+        if (audioChannelNum < 0) {
+            audioChannelNum = 1;
+        }
+
+        for (int x = 0; x < audioChannelNum; x++) {
+            AudioDispatcher audioDispatcher = new AudioDispatcher(assetFileDescriptor, volume);
+            audioList.add(audioDispatcher);
+            if (audioChannelNum == 1) audioDispatcher.setOwner(this);
+        }
+    }
 
-    if (audioChannelNum < 0) {
-      audioChannelNum = 1;
+    public void dispatchComplete() {
+        this.owner.dispatchComplete(this.assetId);
     }
 
-    for (int x = 0; x < audioChannelNum; x++) {
-      AudioDispatcher audioDispatcher = new AudioDispatcher(
-        assetFileDescriptor,
-        volume
-      );
-      audioList.add(audioDispatcher);
-      if (audioChannelNum == 1) audioDispatcher.setOwner(this);
+    public void play(Double time) throws Exception {
+        AudioDispatcher audio = audioList.get(playIndex);
+        if (audio != null) {
+            audio.play(time);
+            playIndex++;
+            playIndex = playIndex % audioList.size();
+            Log.d(TAG, "Starting timer from play"); // Debug log
+            startCurrentTimeUpdates(); // Make sure this is called
+        } else {
+            throw new Exception("AudioDispatcher is null");
+        }
     }
-  }
 
-  public void dispatchComplete() {
-    this.owner.dispatchComplete(this.assetId);
-  }
+    public double getDuration() {
+        if (audioList.size() != 1) return 0;
 
-  public void play(Double time) throws Exception {
-    AudioDispatcher audio = audioList.get(playIndex);
+        AudioDispatcher audio = audioList.get(playIndex);
 
-    if (audio != null) {
-      audio.play(time);
-      playIndex++;
-      playIndex = playIndex % audioList.size();
-    } else {
-      throw new Exception("AudioDispatcher is null");
+        if (audio != null) {
+            return audio.getDuration();
+        }
+        return 0;
     }
-  }
 
-  public double getDuration() {
-    if (audioList.size() != 1) return 0;
+    public void setCurrentPosition(double time) {
+        if (audioList.size() != 1) return;
 
-    AudioDispatcher audio = audioList.get(playIndex);
+        AudioDispatcher audio = audioList.get(playIndex);
 
-    if (audio != null) {
-      return audio.getDuration();
+        if (audio != null) {
+            audio.setCurrentPosition(time);
+        }
     }
-    return 0;
-  }
 
-  public void setCurrentPosition(double time) {
-    if (audioList.size() != 1) return;
+    public double getCurrentPosition() {
+        if (audioList.size() != 1) return 0;
 
-    AudioDispatcher audio = audioList.get(playIndex);
+        AudioDispatcher audio = audioList.get(playIndex);
 
-    if (audio != null) {
-      audio.setCurrentPosition(time);
+        if (audio != null) {
+            return audio.getCurrentPosition();
+        }
+        return 0;
     }
-  }
 
-  public double getCurrentPosition() {
-    if (audioList.size() != 1) return 0;
+    public boolean pause() throws Exception {
+        stopCurrentTimeUpdates(); // Stop updates when pausing
+        boolean wasPlaying = false;
+
+        for (int x = 0; x < audioList.size(); x++) {
+            AudioDispatcher audio = audioList.get(x);
+            wasPlaying |= audio.pause();
+        }
 
-    AudioDispatcher audio = audioList.get(playIndex);
+        return wasPlaying;
+    }
 
-    if (audio != null) {
-      return audio.getCurrentPosition();
+    public void resume() throws Exception {
+        if (!audioList.isEmpty()) {
+            AudioDispatcher audio = audioList.get(0);
+            if (audio != null) {
+                audio.resume();
+                Log.d(TAG, "Starting timer from resume"); // Debug log
+                startCurrentTimeUpdates(); // Make sure this is called
+            } else {
+                throw new Exception("AudioDispatcher is null");
+            }
+        }
     }
-    return 0;
-  }
 
-  public boolean pause() throws Exception {
-    boolean wasPlaying = false;
+    public void stop() throws Exception {
+        stopCurrentTimeUpdates(); // Stop updates when stopping
+        for (int x = 0; x < audioList.size(); x++) {
+            AudioDispatcher audio = audioList.get(x);
+
+            if (audio != null) {
+                audio.stop();
+            } else {
+                throw new Exception("AudioDispatcher is null");
+            }
+        }
+    }
 
-    for (int x = 0; x < audioList.size(); x++) {
-      AudioDispatcher audio = audioList.get(x);
-      wasPlaying |= audio.pause();
+    public void loop() throws Exception {
+        AudioDispatcher audio = audioList.get(playIndex);
+        if (audio != null) {
+            audio.loop();
+            playIndex++;
+            playIndex = playIndex % audioList.size();
+            startCurrentTimeUpdates(); // Add timer start
+        } else {
+            throw new Exception("AudioDispatcher is null");
+        }
     }
 
-    return wasPlaying;
-  }
+    public void unload() throws Exception {
+        this.stop();
 
-  public void resume() throws Exception {
-    if (!audioList.isEmpty()) {
-      AudioDispatcher audio = audioList.get(0);
+        for (int x = 0; x < audioList.size(); x++) {
+            AudioDispatcher audio = audioList.get(x);
 
-      if (audio != null) {
-        audio.resume();
-      } else {
-        throw new Exception("AudioDispatcher is null");
-      }
+            if (audio != null) {
+                audio.unload();
+            } else {
+                throw new Exception("AudioDispatcher is null");
+            }
+        }
+
+        audioList.clear();
     }
-  }
 
-  public void stop() throws Exception {
-    for (int x = 0; x < audioList.size(); x++) {
-      AudioDispatcher audio = audioList.get(x);
+    public void setVolume(float volume) throws Exception {
+        for (int x = 0; x < audioList.size(); x++) {
+            AudioDispatcher audio = audioList.get(x);
+
+            if (audio != null) {
+                audio.setVolume(volume);
+            } else {
+                throw new Exception("AudioDispatcher is null");
+            }
+        }
+    }
 
-      if (audio != null) {
-        audio.stop();
-      } else {
-        throw new Exception("AudioDispatcher is null");
-      }
+    @RequiresApi(api = Build.VERSION_CODES.M)
+    public void setRate(float rate) throws Exception {
+        for (int x = 0; x < audioList.size(); x++) {
+            AudioDispatcher audio = audioList.get(x);
+            if (audio != null) {
+                audio.setRate(rate);
+            }
+        }
     }
-  }
 
-  public void loop() throws Exception {
-    AudioDispatcher audio = audioList.get(playIndex);
+    public boolean isPlaying() throws Exception {
+        if (audioList.size() != 1) return false;
 
-    if (audio != null) {
-      audio.loop();
-      playIndex++;
-      playIndex = playIndex % audioList.size();
-    } else {
-      throw new Exception("AudioDispatcher is null");
+        return audioList.get(playIndex).isPlaying();
     }
-  }
 
-  public void unload() throws Exception {
-    this.stop();
+    public void setCompletionListener(AudioCompletionListener listener) {
+        this.completionListener = listener;
+    }
 
-    for (int x = 0; x < audioList.size(); x++) {
-      AudioDispatcher audio = audioList.get(x);
+    protected void notifyCompletion() {
+        if (completionListener != null) {
+            completionListener.onCompletion(this.assetId);
+        }
+    }
 
-      if (audio != null) {
-        audio.unload();
-      } else {
-        throw new Exception("AudioDispatcher is null");
-      }
+    protected String getAssetId() {
+        return assetId;
     }
 
-    audioList.clear();
-  }
+    public void setCurrentTime(double time) throws Exception {
+        owner
+            .getActivity()
+            .runOnUiThread(
+                new Runnable() {
+                    @Override
+                    public void run() {
+                        if (audioList.size() != 1) {
+                            return;
+                        }
+                        AudioDispatcher audio = audioList.get(playIndex);
+                        if (audio != null) {
+                            audio.setCurrentPosition(time);
+                        }
+                    }
+                }
+            );
+    }
 
-  public void setVolume(float volume) throws Exception {
-    for (int x = 0; x < audioList.size(); x++) {
-      AudioDispatcher audio = audioList.get(x);
+    protected void startCurrentTimeUpdates() {
+        Log.d(TAG, "Starting timer updates in AudioAsset");
+        if (currentTimeHandler == null) {
+            currentTimeHandler = new Handler(Looper.getMainLooper());
+        }
+
+        // Add small delay to let audio start playing
+        currentTimeHandler.postDelayed(
+            new Runnable() {
+                @Override
+                public void run() {
+                    startTimeUpdateLoop();
+                }
+            },
+            100
+        ); // 100ms delay
+    }
 
-      if (audio != null) {
-        audio.setVolume(volume);
-      } else {
-        throw new Exception("AudioDispatcher is null");
-      }
+    private void startTimeUpdateLoop() {
+        currentTimeRunnable = new Runnable() {
+            @Override
+            public void run() {
+                try {
+                    AudioDispatcher audio = audioList.get(playIndex);
+                    if (audio != null && audio.isPlaying()) {
+                        double currentTime = getCurrentPosition();
+                        Log.d(TAG, "Timer update: currentTime = " + currentTime);
+                        owner.notifyCurrentTime(assetId, currentTime);
+                        currentTimeHandler.postDelayed(this, 100);
+                    } else {
+                        Log.d(TAG, "Stopping timer - not playing");
+                        stopCurrentTimeUpdates();
+                    }
+                } catch (Exception e) {
+                    Log.e(TAG, "Error getting current time", e);
+                    stopCurrentTimeUpdates();
+                }
+            }
+        };
+        currentTimeHandler.post(currentTimeRunnable);
     }
-  }
 
-  @RequiresApi(api = Build.VERSION_CODES.M)
-  public void setRate(float rate) throws Exception {
-    for (int x = 0; x < audioList.size(); x++) {
-      AudioDispatcher audio = audioList.get(x);
-      if (audio != null) {
-        audio.setRate(rate);
-      }
+    void stopCurrentTimeUpdates() {
+        Log.d(TAG, "Stopping timer updates in AudioAsset");
+        if (currentTimeHandler != null && currentTimeRunnable != null) {
+            currentTimeHandler.removeCallbacks(currentTimeRunnable);
+        }
     }
-  }
 
-  public boolean isPlaying() throws Exception {
-    if (audioList.size() != 1) return false;
+    public void playWithFade(Double time) throws Exception {
+        AudioDispatcher audio = audioList.get(playIndex);
+        if (audio != null) {
+            audio.setVolume(0);
+            audio.play(time);
+            fadeIn(audio);
+            startCurrentTimeUpdates();
+        }
+    }
 
-    return audioList.get(playIndex).isPlaying();
-  }
+    private void fadeIn(final AudioDispatcher audio) {
+        final Handler handler = new Handler(Looper.getMainLooper());
+        final Runnable fadeRunnable = new Runnable() {
+            float currentVolume = 0;
+
+            @Override
+            public void run() {
+                if (currentVolume < initialVolume) {
+                    currentVolume += FADE_STEP;
+                    try {
+                        audio.setVolume(currentVolume);
+                        handler.postDelayed(this, FADE_DELAY_MS);
+                    } catch (Exception e) {
+                        Log.e(TAG, "Error during fade in", e);
+                    }
+                }
+            }
+        };
+        handler.post(fadeRunnable);
+    }
 
-  public void setCompletionListener(AudioCompletionListener listener) {
-    this.completionListener = listener;
-  }
+    public void stopWithFade() throws Exception {
+        AudioDispatcher audio = audioList.get(playIndex);
+        if (audio != null && audio.isPlaying()) {
+            fadeOut(audio);
+        }
+    }
 
-  protected void notifyCompletion() {
-    if (completionListener != null) {
-      completionListener.onCompletion(this.assetId);
+    private void fadeOut(final AudioDispatcher audio) {
+        final Handler handler = new Handler(Looper.getMainLooper());
+        final Runnable fadeRunnable = new Runnable() {
+            float currentVolume = initialVolume;
+
+            @Override
+            public void run() {
+                if (currentVolume > FADE_STEP) {
+                    currentVolume -= FADE_STEP;
+                    try {
+                        audio.setVolume(currentVolume);
+                        handler.postDelayed(this, FADE_DELAY_MS);
+                    } catch (Exception e) {
+                        Log.e(TAG, "Error during fade out", e);
+                    }
+                } else {
+                    try {
+                        audio.setVolume(0);
+                        stop();
+                    } catch (Exception e) {
+                        Log.e(TAG, "Error stopping after fade", e);
+                    }
+                }
+            }
+        };
+        handler.post(fadeRunnable);
     }
-  }
 }

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

@@ -1,5 +1,5 @@
 package ee.forgr.audio;
 
 public interface AudioCompletionListener {
-  void onCompletion(String assetId);
+    void onCompletion(String assetId);
 }