@capgo/native-audio 7.11.2 → 8.1.0

package/CapgoNativeAudio.podspec

@@ -11,6 +11,6 @@ Pod::Spec.new do |s|
   s.author = package['author']
   s.source = { :git => package['repository']['url'], :tag => s.version.to_s }
   s.source_files = 'ios/Sources/**/*.{swift,h,m,c,cc,mm,cpp}'
-  s.ios.deployment_target = '14.0'
+  s.ios.deployment_target = '15.0'
   s.dependency 'Capacitor'
 end

package/Package.swift

@@ -13,7 +13,7 @@ let package = Package(
         )
     ],
     dependencies: [
-        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "7.0.0")
+        .package(url: "https://github.com/ionic-team/capacitor-swift-pm.git", from: "8.0.0")
     ],
     targets: [
         .target(

package/README.md

@@ -243,6 +243,71 @@ The media control buttons automatically handle:
 - iOS: Uses MPNowPlayingInfoCenter with MPRemoteCommandCenter
 - Android: Uses MediaSession with NotificationCompat.MediaStyle
 
+## Play Once (Fire-and-Forget) @since 7.11.0
+
+For simple one-shot audio playback (sound effects, notifications, etc.), use `playOnce()` which handles the entire asset lifecycle automatically:
+
+```typescript
+// Basic usage - automatic cleanup after playback
+await NativeAudio.playOnce({
+  assetPath: 'audio/notification.mp3',
+});
+
+// With volume control
+await NativeAudio.playOnce({
+  assetPath: 'audio/beep.wav',
+  volume: 0.8,
+});
+
+// Remote audio with notification metadata
+await NativeAudio.playOnce({
+  assetPath: 'https://example.com/audio.mp3',
+  isUrl: true,
+  autoPlay: true,
+  notificationMetadata: {
+    title: 'Song Name',
+    artist: 'Artist Name',
+  }
+});
+
+// Temporary file with automatic deletion
+await NativeAudio.playOnce({
+  assetPath: 'file:///path/to/temp-audio.wav',
+  deleteAfterPlay: true, // File deleted after playback completes
+  volume: 0.5,
+});
+```
+
+#### Advanced: Manual Control
+
+If you need to control playback timing, set `autoPlay: false` and use the returned `assetId`:
+
+```typescript
+const { assetId } = await NativeAudio.playOnce({
+  assetPath: 'audio/sound.wav',
+  autoPlay: false,
+});
+
+// Play later when needed
+await NativeAudio.play({ assetId });
+
+// Stop if needed (will auto-cleanup)
+await NativeAudio.stop({ assetId });
+```
+
+**Key Features:**
+- ✅ Automatic asset loading and unloading
+- ✅ Cleanup on completion or error
+- ✅ Optional file deletion after playback
+- ✅ Notification metadata support
+- ✅ Works with local files and remote URLs
+
+**Notes:**
+- Assets are automatically cleaned up after playback completes or on error
+- `deleteAfterPlay` only works for local `file://` URLs, not remote URLs
+- The returned `assetId` can be used with `play()`, `stop()`, `unload()` methods
+- Manual cleanup via `stop()` or `unload()` is optional but supported
+
 ## Example app
 
 This repository now ships with an interactive Capacitor project under `example/` that exercises the main APIs on web, iOS, and Android shells.
@@ -403,6 +468,45 @@ Load an audio file
 --------------------
 
 
+### playOnce(...)
+
+```typescript
+playOnce(options: PlayOnceOptions) => Promise<PlayOnceResult>
+```
+
+Play an audio file once with automatic cleanup
+
+Method designed for simple, single-shot audio playback,
+such as notification sounds, UI feedback, or other short audio clips
+that don't require manual state management.
+
+**Key Features:**
+- **Fire-and-forget**: No need to manually preload, play, stop, or unload
+- **Auto-cleanup**: Asset is automatically unloaded after playback completes
+- **Optional file deletion**: Can delete local files after playback (useful for temp files)
+- **Returns assetId**: Can still control playback if needed (pause, stop, etc.)
+
+**Use Cases:**
+- Notification sounds
+- UI sound effects (button clicks, alerts)
+- Short audio clips that play once
+- Temporary audio files that should be cleaned up
+
+**Comparison with regular play():**
+- `play()`: Requires manual preload, play, and unload steps
+- `playOnce()`: Handles everything automatically with a single call
+
+| Param         | Type                                                        |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | <code><a href="#playonceoptions">PlayOnceOptions</a></code> |
+
+**Returns:** <code>Promise&lt;<a href="#playonceresult">PlayOnceResult</a>&gt;</code>
+
+**Since:** 7.11.0
+
+--------------------
+
+
 ### isPreloaded(...)
 
 ```typescript
@@ -760,6 +864,26 @@ behavior details about audio mixing on iOS.
 | **`artworkUrl`** | <code>string</code> | URL or local path to the artwork/album art image      |
 
 
+#### PlayOnceResult
+
+| Prop          | Type                | Description                                                                                                               |
+| ------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| **`assetId`** | <code>string</code> | The internally generated asset ID for this playback Can be used to control playback (pause, stop, etc.) before completion |
+
+
+#### PlayOnceOptions
+
+| Prop                       | Type                                                                  | Description                                                                                                                                                                                                                                                                                     | Default            | Since  |
+| -------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------ |
+| **`assetPath`**            | <code>string</code>                                                   | Path to the audio file, relative path of the file, absolute url (file://) or remote url (https://) Supported formats: - MP3, WAV (all platforms) - M3U8/HLS streams (iOS and Android)                                                                                                           |                    |        |
+| **`volume`**               | <code>number</code>                                                   | Volume of the audio, between 0.1 and 1.0                                                                                                                                                                                                                                                        | <code>1.0</code>   |        |
+| **`isUrl`**                | <code>boolean</code>                                                  | Is the audio file a URL, pass true if assetPath is a `file://` url or a streaming URL (m3u8)                                                                                                                                                                                                    | <code>false</code> |        |
+| **`autoPlay`**             | <code>boolean</code>                                                  | Automatically start playback after loading                                                                                                                                                                                                                                                      | <code>true</code>  |        |
+| **`deleteAfterPlay`**      | <code>boolean</code>                                                  | Delete the audio file from disk after playback completes Only works for local files (file:// URLs), ignored for remote URLs                                                                                                                                                                     | <code>false</code> | 7.11.0 |
+| **`notificationMetadata`** | <code><a href="#notificationmetadata">NotificationMetadata</a></code> | Metadata to display in the notification center when audio is playing. Only used when `showNotification: true` is set in `configure()`. See {@link <a href="#configureoptions">ConfigureOptions.showNotification</a>} for important details about how this affects audio mixing behavior on iOS. |                    | 7.10.0 |
+| **`headers`**              | <code><a href="#record">Record</a>&lt;string, string&gt;</code>       | Custom HTTP headers to include when fetching remote audio files. Only used when isUrl is true and assetPath is a remote URL (http/https). Example: { 'x-api-key': 'abc123', 'Authorization': 'Bearer token' }                                                                                   |                    | 7.10.0 |
+
+
 #### Assets
 
 | Prop          | Type                | Description                             |

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.1'
+    androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
+    androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
 
     // Read HLS configuration from gradle.properties (set by hook script)
     // Default to 'true' for backward compatibility
@@ -15,18 +15,18 @@ buildscript {
         mavenCentral()
     }
     dependencies {
-        classpath 'com.android.tools.build:gradle:8.7.3'
+        classpath 'com.android.tools.build:gradle:8.13.0'
     }
 }
 
 apply plugin: 'com.android.library'
 
 android {
-    namespace "ee.forgr.audio.nativeaudio"
-    compileSdk project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 35
+    namespace = "ee.forgr.audio.nativeaudio"
+    compileSdk = project.hasProperty('compileSdkVersion') ? rootProject.ext.compileSdkVersion : 36
     defaultConfig {
-        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 23
-        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 35
+        minSdkVersion project.hasProperty('minSdkVersion') ? rootProject.ext.minSdkVersion : 24
+        targetSdkVersion project.hasProperty('targetSdkVersion') ? rootProject.ext.targetSdkVersion : 36
         versionCode 1
         versionName "1.0"
         testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
@@ -38,7 +38,7 @@ android {
         }
     }
     lintOptions {
-        abortOnError false
+        abortOnError = false
     }
     compileOptions {
         sourceCompatibility JavaVersion.VERSION_21