@capgo/native-audio 7.10.2 → 7.11.0

package/README.md

@@ -103,7 +103,40 @@ You can also consume the iOS implementation via Swift Package Manager. In Xcode
 
 ## Configuration
 
-No configuration required for this plugin.
+### Optional HLS/m3u8 Streaming (Android)
+
+By default, HLS streaming support is **enabled** for backward compatibility. However, it adds approximately **4MB** to your Android APK size due to the `media3-exoplayer-hls` dependency.
+
+If you don't need HLS/m3u8 streaming support, you can disable it to reduce your APK size:
+
+```typescript
+// capacitor.config.ts
+import type { CapacitorConfig } from '@capacitor/cli';
+
+const config: CapacitorConfig = {
+  appId: 'com.example.app',
+  appName: 'My App',
+  plugins: {
+    NativeAudio: {
+      hls: false  // Disable HLS to reduce APK size by ~4MB
+    }
+  }
+};
+
+export default config;
+```
+
+After changing the configuration, run:
+
+```bash
+npx cap sync
+```
+
+**Notes:**
+- iOS uses native AVPlayer for HLS, so this setting only affects Android
+- If HLS is disabled and you try to play an `.m3u8` file, you'll get a clear error message explaining how to enable it
+- The default is `hls: true` to maintain backward compatibility
+
 <docgen-config>
 <!--Update the source file JSDoc comments and rerun docgen to update the docs below-->
 

package/android/build.gradle

@@ -3,6 +3,10 @@ ext {
     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'
+
+    // Read HLS configuration from gradle.properties (set by hook script)
+    // Default to 'true' for backward compatibility
+    includeHls = project.findProperty('nativeAudio.hls.include') ?: 'true'
 }
 
 buildscript {
@@ -40,6 +44,16 @@ android {
         sourceCompatibility JavaVersion.VERSION_21
         targetCompatibility JavaVersion.VERSION_21
     }
+
+    // Exclude StreamAudioAsset when HLS is disabled
+    // StreamAudioAsset depends on HlsMediaSource which is only available with media3-exoplayer-hls
+    sourceSets {
+        main {
+            if (includeHls != 'true') {
+                java.exclude '**/StreamAudioAsset.java'
+            }
+        }
+    }
 }
 
 repositories {
@@ -56,7 +70,14 @@ dependencies {
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
     implementation 'androidx.media3:media3-exoplayer:1.8.0'
-    implementation 'androidx.media3:media3-exoplayer-hls:1.8.0'
+
+    // HLS (m3u8) streaming support - optional dependency
+    // When disabled, reduces APK size by ~4MB
+    // Configure via capacitor.config.ts: plugins.NativeAudio.hls = false
+    if (includeHls == 'true') {
+        implementation 'androidx.media3:media3-exoplayer-hls:1.8.0'
+    }
+
     implementation 'androidx.media3:media3-session:1.8.0'
     implementation 'androidx.media3:media3-transformer:1.5.1'
     implementation 'androidx.media3:media3-ui:1.5.1'

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

@@ -0,0 +1,84 @@
+package ee.forgr.audio;
+
+import android.util.Log;
+
+/**
+ * Utility class to check if HLS (m3u8) streaming dependencies are available at runtime.
+ *
+ * This allows the plugin to gracefully handle cases where the HLS dependency
+ * (media3-exoplayer-hls) is excluded to reduce APK size.
+ *
+ * Users who don't need HLS streaming support can disable it in capacitor.config.ts:
+ *
+ * plugins: {
+ *   NativeAudio: {
+ *     hls: false  // Reduces APK size by ~4MB
+ *   }
+ * }
+ */
+public class HlsAvailabilityChecker {
+
+    private static final String TAG = "HlsAvailabilityChecker";
+    private static Boolean hlsAvailable = null;
+
+    /**
+     * Check if a class is available at runtime using reflection.
+     */
+    private static boolean isClassAvailable(String className) {
+        try {
+            Class.forName(className);
+            return true;
+        } catch (ClassNotFoundException e) {
+            return false;
+        } catch (Exception e) {
+            Log.e(TAG, "Unexpected error checking class availability: " + className, e);
+            return false;
+        }
+    }
+
+    /**
+     * Check if HLS streaming dependencies are available.
+     * Results are cached for performance.
+     *
+     * @return true if HLS classes are available, false otherwise
+     */
+    public static boolean isHlsAvailable() {
+        if (hlsAvailable != null) {
+            return hlsAvailable;
+        }
+
+        // Check for the critical HLS classes from media3-exoplayer-hls
+        String[] hlsClasses = { "androidx.media3.exoplayer.hls.HlsMediaSource", "androidx.media3.exoplayer.hls.HlsMediaSource$Factory" };
+
+        boolean allAvailable = true;
+        for (String className : hlsClasses) {
+            if (!isClassAvailable(className)) {
+                allAvailable = false;
+                Log.w(TAG, "HLS dependency class not available: " + className);
+            }
+        }
+
+        hlsAvailable = allAvailable;
+
+        if (!allAvailable) {
+            Log.i(
+                TAG,
+                "HLS streaming support is not available. " +
+                    "To enable m3u8 streaming, set 'hls: true' in capacitor.config.ts under NativeAudio plugin config " +
+                    "and run 'npx cap sync'."
+            );
+        } else {
+            Log.d(TAG, "HLS streaming support is available.");
+        }
+
+        return allAvailable;
+    }
+
+    /**
+     * Reset the cached availability check.
+     * Useful for testing purposes.
+     */
+    public static void resetCache() {
+        hlsAvailable = null;
+    }
+}

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

@@ -665,8 +665,22 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
                         }
 
                         if (assetPath.endsWith(".m3u8")) {
-                            // HLS Stream - resolve immediately since it's a stream
-                            StreamAudioAsset streamAudioAsset = new StreamAudioAsset(this, audioId, uri, volume, requestHeaders);
+                            // HLS Stream - check if HLS support is available
+                            if (!HlsAvailabilityChecker.isHlsAvailable()) {
+                                call.reject(
+                                    "HLS streaming (.m3u8) is not available. " +
+                                        "The media3-exoplayer-hls dependency is not included. " +
+                                        "To enable HLS support, set 'hls: true' in capacitor.config.ts under NativeAudio plugin config " +
+                                        "and run 'npx cap sync'. This will increase APK size by ~4MB."
+                                );
+                                return;
+                            }
+                            // HLS Stream - create via reflection to allow compile-time exclusion
+                            AudioAsset streamAudioAsset = createStreamAudioAsset(audioId, uri, volume, requestHeaders);
+                            if (streamAudioAsset == null) {
+                                call.reject("Failed to create HLS stream player. HLS support may not be properly configured.");
+                                return;
+                            }
                             audioAssetList.put(audioId, streamAudioAsset);
                             call.resolve(status);
                         } else {
@@ -784,6 +798,37 @@ public class NativeAudio extends Plugin implements AudioManager.OnAudioFocusChan
         return (value != null && !value.isEmpty() && !value.equals("null"));
     }
 
+    /**
+     * Creates a StreamAudioAsset via reflection.
+     * This allows the StreamAudioAsset class to be excluded at compile time when HLS is disabled,
+     * reducing APK size by ~4MB.
+     *
+     * @param audioId The unique identifier for the audio asset
+     * @param uri The URI of the HLS stream
+     * @param volume The initial volume (0.0 to 1.0)
+     * @param headers Optional HTTP headers for the request
+     * @return The created AudioAsset, or null if creation failed
+     */
+    private AudioAsset createStreamAudioAsset(String audioId, Uri uri, float volume, java.util.Map<String, String> headers) {
+        try {
+            Class<?> streamAudioAssetClass = Class.forName("ee.forgr.audio.StreamAudioAsset");
+            java.lang.reflect.Constructor<?> constructor = streamAudioAssetClass.getConstructor(
+                NativeAudio.class,
+                String.class,
+                Uri.class,
+                float.class,
+                java.util.Map.class
+            );
+            return (AudioAsset) constructor.newInstance(this, audioId, uri, volume, headers);
+        } catch (ClassNotFoundException e) {
+            Log.e(TAG, "StreamAudioAsset class not found. HLS support is not included in this build.", e);
+            return null;
+        } catch (Exception e) {
+            Log.e(TAG, "Failed to create StreamAudioAsset", e);
+            return null;
+        }
+    }
+
     private void stopAudio(String audioId) throws Exception {
         if (!audioAssetList.containsKey(audioId)) {
             throw new Exception(ERROR_ASSET_NOT_LOADED);

package/ios/Sources/NativeAudioPlugin/Plugin.swift

@@ -13,7 +13,7 @@ enum MyError: Error {
 // swiftlint:disable type_body_length file_length
 @objc(NativeAudio)
 public class NativeAudio: CAPPlugin, AVAudioPlayerDelegate, CAPBridgedPlugin {
-    private let pluginVersion: String = "7.10.2"
+    private let pluginVersion: String = "7.11.0"
     public let identifier = "NativeAudio"
     public let jsName = "NativeAudio"
     public let pluginMethods: [CAPPluginMethod] = [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/native-audio",
-  "version": "7.10.2",
+  "version": "7.11.0",
   "description": "A native plugin for native audio engine",
   "license": "MPL-2.0",
   "main": "dist/plugin.cjs.js",
@@ -14,7 +14,8 @@
     "ios/Sources",
     "ios/Tests",
     "Package.swift",
-    "CapgoNativeAudio.podspec"
+    "CapgoNativeAudio.podspec",
+    "scripts/configure-dependencies.js"
   ],
   "author": "Martin Donadieu",
   "repository": {
@@ -33,6 +34,7 @@
     "native"
   ],
   "scripts": {
+    "capacitor:sync:after": "node scripts/configure-dependencies.js",
     "verify": "npm run verify:ios && npm run verify:android && npm run verify:web",
     "verify:ios": "xcodebuild -scheme CapgoNativeAudio -destination generic/platform=iOS",
     "verify:android": "cd android && ./gradlew clean build test && cd ..",
@@ -45,7 +47,8 @@
     "prettier": "prettier \"**/*.{css,html,ts,js,java}\" --plugin=prettier-plugin-java",
     "swiftlint": "node-swiftlint",
     "docgen": "docgen --api NativeAudio --output-readme README.md --output-json dist/docs.json",
-    "build": "npm run clean && npm run docgen && tsc && rollup -c rollup.config.mjs",
+    "build": "npm run clean && npm run docgen && npm run build:scripts && tsc && rollup -c rollup.config.mjs",
+    "build:scripts": "tsc -p scripts/tsconfig.json",
     "clean": "rimraf ./dist",
     "watch": "tsc --watch",
     "prepublishOnly": "npm run build"

package/scripts/configure-dependencies.js

@@ -0,0 +1,251 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * Capacitor Hook Script: Configure Optional HLS Dependency
+ *
+ * This script runs during `npx cap sync` and configures whether to include
+ * the HLS (m3u8) streaming dependency based on capacitor.config.ts settings.
+ *
+ * By default, HLS is enabled for backward compatibility.
+ * To disable HLS and reduce APK size by ~4MB, set:
+ *
+ * plugins: {
+ *   NativeAudio: {
+ *     hls: false
+ *   }
+ * }
+ *
+ * Environment variables provided by Capacitor:
+ * - CAPACITOR_ROOT_DIR: Root directory of the consuming app
+ * - CAPACITOR_CONFIG: JSON stringified config object
+ * - CAPACITOR_PLATFORM_NAME: Platform name (android, ios, web)
+ * - process.cwd(): Plugin root directory
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getConfig = getConfig;
+exports.configureAndroid = configureAndroid;
+exports.configureIOS = configureIOS;
+exports.configureWeb = configureWeb;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// Get environment variables
+const PLUGIN_ROOT = process.cwd();
+const CONFIG_JSON = process.env.CAPACITOR_CONFIG;
+const PLATFORM = process.env.CAPACITOR_PLATFORM_NAME;
+// File paths
+const gradlePropertiesPath = path.join(PLUGIN_ROOT, 'android', 'gradle.properties');
+// ============================================================================
+// Logging Utilities
+// ============================================================================
+const colors = {
+    reset: '\x1b[0m',
+    bright: '\x1b[1m',
+    green: '\x1b[32m',
+    red: '\x1b[31m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    cyan: '\x1b[36m',
+    gray: '\x1b[90m',
+};
+function log(message, emoji = '', color = '') {
+    const emojiPart = emoji ? `${emoji} ` : '';
+    const colorCode = color || colors.reset;
+    const resetCode = color ? colors.reset : '';
+    console.log(`${colorCode}${emojiPart}${message}${resetCode}`);
+}
+function logSuccess(message) {
+    log(message, '✔', colors.green);
+}
+function logError(message) {
+    log(message, '✖', colors.red);
+}
+function logInfo(message) {
+    log(message, 'ℹ', colors.blue);
+}
+function logWarning(message) {
+    log(message, '⚠', colors.yellow);
+}
+/**
+ * Parse NativeAudio configuration from Capacitor config
+ * Default: hls = true (for backward compatibility)
+ */
+function getConfig() {
+    const defaultConfig = {
+        hls: true, // Enabled by default for backward compatibility
+    };
+    try {
+        if (!CONFIG_JSON) {
+            logInfo('No CAPACITOR_CONFIG found, using defaults (HLS enabled)');
+            return defaultConfig;
+        }
+        const config = JSON.parse(CONFIG_JSON);
+        const nativeAudioConfig = config.plugins?.NativeAudio || {};
+        return {
+            hls: nativeAudioConfig.hls !== false, // Default to true unless explicitly set to false
+        };
+    }
+    catch (error) {
+        logError(`Error parsing config: ${error.message}`);
+        return defaultConfig;
+    }
+}
+/**
+ * Log the current configuration status
+ */
+function logConfig(config) {
+    log('\nNativeAudio configuration:', '', colors.bright);
+    if (config.hls) {
+        console.log(`  ${colors.green}✔${colors.reset} ${colors.bright}HLS (m3u8)${colors.reset}: ${colors.green}enabled${colors.reset} (includes media3-exoplayer-hls, adds ~4MB to APK)`);
+    }
+    else {
+        console.log(`  ${colors.yellow}○${colors.reset} ${colors.bright}HLS (m3u8)${colors.reset}: ${colors.yellow}disabled${colors.reset} (reduces APK size by ~4MB)`);
+    }
+    console.log('');
+}
+// ============================================================================
+// Android: Gradle Configuration
+// ============================================================================
+/**
+ * Write gradle.properties file for Android
+ * Injects NativeAudio properties while preserving existing content
+ */
+function configureAndroid(config) {
+    logInfo('Configuring Android dependencies...');
+    try {
+        // Read existing gradle.properties if it exists
+        let existingContent = '';
+        if (fs.existsSync(gradlePropertiesPath)) {
+            existingContent = fs.readFileSync(gradlePropertiesPath, 'utf8');
+        }
+        // Remove existing NativeAudio properties (if any)
+        const lines = existingContent.split('\n');
+        const filteredLines = [];
+        let inNativeAudioSection = false;
+        let lastWasEmpty = false;
+        for (const line of lines) {
+            // Check if this is a NativeAudio property or comment
+            if (line.trim().startsWith('# NativeAudio') ||
+                line.trim().startsWith('nativeAudio.') ||
+                line.trim() === '# Generated by NativeAudio hook script') {
+                inNativeAudioSection = true;
+                continue; // Skip this line
+            }
+            // If we were in NativeAudio section and hit a non-empty line, we're done
+            if (inNativeAudioSection && line.trim() !== '') {
+                inNativeAudioSection = false;
+            }
+            // Add non-NativeAudio lines, but avoid multiple consecutive empty lines
+            if (!inNativeAudioSection) {
+                if (line.trim() === '') {
+                    if (!lastWasEmpty) {
+                        filteredLines.push(line);
+                        lastWasEmpty = true;
+                    }
+                }
+                else {
+                    filteredLines.push(line);
+                    lastWasEmpty = false;
+                }
+            }
+        }
+        // Build new NativeAudio properties section
+        const nativeAudioProperties = [];
+        nativeAudioProperties.push('');
+        nativeAudioProperties.push('# NativeAudio Optional Dependencies (auto-generated)');
+        nativeAudioProperties.push('# Generated by NativeAudio hook script');
+        nativeAudioProperties.push(`nativeAudio.hls.include=${config.hls ? 'true' : 'false'}`);
+        // Combine: existing content + new NativeAudio properties
+        const newContent = filteredLines.join('\n') + '\n' + nativeAudioProperties.join('\n') + '\n';
+        fs.writeFileSync(gradlePropertiesPath, newContent, 'utf8');
+        logSuccess('Updated gradle.properties');
+    }
+    catch (error) {
+        logError(`Error updating gradle.properties: ${error.message}`);
+    }
+}
+// ============================================================================
+// iOS: No Configuration Needed (yet)
+// ============================================================================
+/**
+ * iOS platform - HLS is handled natively by AVPlayer
+ */
+function configureIOS() {
+    logInfo('iOS uses native AVPlayer for HLS - no additional configuration needed');
+}
+// ============================================================================
+// Web: No Configuration Needed
+// ============================================================================
+/**
+ * Web platform doesn't need native dependency configuration
+ */
+function configureWeb() {
+    logInfo('Web platform - no native dependency configuration needed');
+}
+// ============================================================================
+// Main Execution
+// ============================================================================
+function main() {
+    const config = getConfig();
+    switch (PLATFORM) {
+        case 'android':
+            log('Configuring optional dependencies for NativeAudio', '🔧', colors.cyan);
+            logConfig(config);
+            configureAndroid(config);
+            logSuccess('Configuration complete\n');
+            break;
+        case 'ios':
+            log('Configuring NativeAudio for iOS', '🔧', colors.cyan);
+            logConfig(config);
+            configureIOS();
+            logSuccess('Configuration complete\n');
+            break;
+        case 'web':
+            configureWeb();
+            break;
+        default:
+            // If platform is not specified, configure all platforms (backward compatibility)
+            log('Configuring optional dependencies for NativeAudio', '🔧', colors.blue);
+            logConfig(config);
+            logWarning(`Unknown platform: ${PLATFORM || 'undefined'}, configuring Android`);
+            configureAndroid(config);
+            logSuccess('Configuration complete\n');
+            break;
+    }
+}
+// Run if executed directly
+if (require.main === module) {
+    main();
+}