sezo-audio-engine 0.0.15 → 0.0.16

package/README.md

@@ -38,7 +38,7 @@ allprojects {
 Optionally pin the engine version in `android/gradle.properties`:
 
 ```properties
-sezoAudioEngineVersion=android-engine-v0.1.7
+sezoAudioEngineVersion=android-engine-v0.1.8
 ```
 
 If you want to build from source instead, include the local engine module in

package/android/build.gradle

@@ -46,7 +46,7 @@ dependencies {
   if (androidEngineProject != null) {
     implementation androidEngineProject
   } else {
-    def sezoAudioEngineVersion = project.findProperty("sezoAudioEngineVersion") ?: "android-engine-v0.1.7"
+    def sezoAudioEngineVersion = project.findProperty("sezoAudioEngineVersion") ?: "android-engine-v0.1.8"
     implementation "com.github.Sepzie:SezoAudioEngine:${sezoAudioEngineVersion}"
   }
 }

package/android/src/main/java/expo/modules/audioengine/ExpoAudioEngineModule.kt

@@ -62,7 +62,14 @@ class ExpoAudioEngineModule : Module() {
   )
 
   private fun requireEngine(): AudioEngine {
-    return audioEngine ?: throw CodedException("ENGINE_NOT_INITIALIZED", "Engine not initialized")
+    return audioEngine ?: run {
+      emitEngineError(
+        code = "ENGINE_NOT_INITIALIZED",
+        message = "Engine not initialized",
+        source = "engine"
+      )
+      throw CodedException("ENGINE_NOT_INITIALIZED", "Engine not initialized", null)
+    }
   }
 
   override fun definition() = ModuleDefinition {
@@ -70,6 +77,7 @@ class ExpoAudioEngineModule : Module() {
 
     OnActivityEntersBackground {
       Log.d(TAG, "Activity entering background")
+      emitDebugLog("debug", "Activity entering background")
       val engine = audioEngine ?: return@OnActivityEntersBackground
 
       if (backgroundPlaybackEnabled) {
@@ -81,31 +89,33 @@ class ExpoAudioEngineModule : Module() {
       if (wasPlayingBeforePause) {
         Log.d(TAG, "Pausing engine before background (was playing)")
         pausePlaybackInternal(engine, fromSystem = true, keepAudioFocus = false)
-        sendEvent("engineStateChanged", mapOf(
-          "reason" to "backgrounded",
-          "wasPlaying" to true
-        ))
+        emitEngineStateChanged(
+          reason = "backgrounded",
+          payload = mapOf("wasPlaying" to true)
+        )
       }
     }
 
     OnActivityEntersForeground {
       Log.d(TAG, "Activity entering foreground")
+      emitDebugLog("debug", "Activity entering foreground")
       val engine = audioEngine ?: return@OnActivityEntersForeground
 
       // Check stream health on resume
       if (!engine.isStreamHealthy()) {
         Log.w(TAG, "Stream unhealthy on resume, attempting restart")
         val restarted = engine.restartStream()
-        sendEvent("engineStateChanged", mapOf(
-          "reason" to "streamRestarted",
-          "success" to restarted
-        ))
+        emitEngineStateChanged(
+          reason = "streamRestarted",
+          payload = mapOf("success" to restarted)
+        )
         if (!restarted) {
           Log.e(TAG, "Failed to restart stream on resume")
-          sendEvent("error", mapOf(
-            "code" to "STREAM_DISCONNECTED",
-            "message" to "Audio stream could not be recovered after returning to foreground"
-          ))
+          emitEngineError(
+            code = "STREAM_DISCONNECTED",
+            message = "Audio stream could not be recovered after returning to foreground",
+            source = "engine"
+          )
           return@OnActivityEntersForeground
         }
       }
@@ -115,10 +125,9 @@ class ExpoAudioEngineModule : Module() {
         Log.d(TAG, "Resuming playback after returning to foreground")
         val resumed = startPlaybackInternal(engine, fromSystem = true)
         wasPlayingBeforePause = false
-        sendEvent(
-          "engineStateChanged",
-          mapOf(
-            "reason" to "resumed",
+        emitEngineStateChanged(
+          reason = "resumed",
+          payload = mapOf(
             "wasPlaying" to true,
             "success" to resumed
           )
@@ -148,6 +157,7 @@ class ExpoAudioEngineModule : Module() {
 
     AsyncFunction("initialize") { config: Map<String, Any?> ->
       Log.d(TAG, "Initialize called with config: $config")
+      emitDebugLog("info", "Initialize called", mapOf("config" to config))
 
       val sampleRate = (config["sampleRate"] as? Number)?.toInt() ?: 44100
       val maxTracks = (config["maxTracks"] as? Number)?.toInt() ?: 8
@@ -156,6 +166,11 @@ class ExpoAudioEngineModule : Module() {
       val success = audioEngine?.initialize(sampleRate, maxTracks) ?: false
 
       if (!success) {
+        emitEngineError(
+          code = "ENGINE_INIT_FAILED",
+          message = "Failed to initialize audio engine",
+          source = "engine"
+        )
         throw CodedException("ENGINE_INIT_FAILED", "Failed to initialize audio engine", null)
       }
 
@@ -171,6 +186,13 @@ class ExpoAudioEngineModule : Module() {
             "durationMs" to durationMs
           )
         )
+        sendEvent(
+          "positionUpdate",
+          mapOf(
+            "positionMs" to positionMs,
+            "durationMs" to durationMs
+          )
+        )
         handlePlaybackStateChange(state)
       }
 
@@ -179,6 +201,7 @@ class ExpoAudioEngineModule : Module() {
 
     AsyncFunction("release") {
       Log.d(TAG, "Release called")
+      emitDebugLog("info", "Release called")
       teardownBackgroundPlayback(clearMetadata = false, stopService = true)
       audioEngine?.let { engine ->
         synchronized(pendingExtractions) {
@@ -203,15 +226,47 @@ class ExpoAudioEngineModule : Module() {
 
       tracks.forEach { track ->
         val id = track["id"] as? String
-          ?: throw CodedException("TRACK_LOAD_FAILED", "Missing track id", null)
+          ?: run {
+            emitEngineError(
+              code = "TRACK_LOAD_FAILED",
+              message = "Missing track id",
+              details = track,
+              source = "engine"
+            )
+            throw CodedException("TRACK_LOAD_FAILED", "Missing track id", null)
+          }
         val uri = track["uri"] as? String
-          ?: throw CodedException("TRACK_LOAD_FAILED", "Missing track uri", null)
+          ?: run {
+            emitEngineError(
+              code = "TRACK_LOAD_FAILED",
+              message = "Missing track uri",
+              details = mapOf("trackId" to id),
+              source = "engine"
+            )
+            throw CodedException("TRACK_LOAD_FAILED", "Missing track uri", null)
+          }
         val startTimeMs = (track["startTimeMs"] as? Number)?.toDouble() ?: 0.0
 
         Log.d(TAG, "Loading track: id=$id, uri=$uri")
-        val filePath = convertUriToPath(uri)
+        val filePath = try {
+          convertUriToPath(uri)
+        } catch (error: CodedException) {
+          emitEngineError(
+            code = "UNSUPPORTED_URI",
+            message = error.message ?: "Unsupported URI",
+            details = mapOf("trackId" to id, "uri" to uri),
+            source = "system"
+          )
+          throw error
+        }
 
         if (!engine.loadTrack(id, filePath, startTimeMs)) {
+          emitEngineError(
+            code = "TRACK_LOAD_FAILED",
+            message = "Failed to load track: $id from $filePath",
+            details = mapOf("trackId" to id, "uri" to uri),
+            source = "engine"
+          )
           throw CodedException(
             "TRACK_LOAD_FAILED",
             "Failed to load track: $id from $filePath",
@@ -221,6 +276,7 @@ class ExpoAudioEngineModule : Module() {
 
         loadedTrackIds.add(id)
         Log.d(TAG, "Track loaded successfully: $id")
+        sendEvent("trackLoaded", mapOf("trackId" to id))
       }
     }
 
@@ -228,18 +284,27 @@ class ExpoAudioEngineModule : Module() {
       val engine = requireEngine()
 
       if (!engine.unloadTrack(trackId)) {
+        emitEngineError(
+          code = "TRACK_UNLOAD_FAILED",
+          message = "Failed to unload track: $trackId",
+          details = mapOf("trackId" to trackId),
+          source = "engine"
+        )
         throw CodedException("TRACK_UNLOAD_FAILED", "Failed to unload track: $trackId", null)
       }
 
       loadedTrackIds.remove(trackId)
       Log.d(TAG, "Track unloaded: $trackId")
+      sendEvent("trackUnloaded", mapOf("trackId" to trackId))
     }
 
     AsyncFunction("unloadAllTracks") {
       val engine = requireEngine()
+      val trackIdsToUnload = loadedTrackIds.toList()
       engine.unloadAllTracks()
       loadedTrackIds.clear()
       Log.d(TAG, "All tracks unloaded")
+      trackIdsToUnload.forEach { sendEvent("trackUnloaded", mapOf("trackId" to it)) }
     }
 
     Function("getLoadedTracks") {
@@ -249,6 +314,11 @@ class ExpoAudioEngineModule : Module() {
     AsyncFunction("play") {
       val engine = requireEngine()
       if (!startPlaybackInternal(engine, fromSystem = false)) {
+        emitEngineError(
+          code = "PLAYBACK_START_FAILED",
+          message = "Failed to start playback",
+          source = "playback"
+        )
         throw CodedException("PLAYBACK_START_FAILED", "Failed to start playback", null)
       }
       Log.d(TAG, "Playback started")
@@ -387,11 +457,23 @@ class ExpoAudioEngineModule : Module() {
       )
 
       if (!success) {
+        emitEngineError(
+          code = "RECORDING_START_FAILED",
+          message = "Failed to start recording",
+          details = mapOf(
+            "format" to format,
+            "sampleRate" to sampleRate,
+            "channels" to channels
+          ),
+          source = "recording"
+        )
         throw CodedException("RECORDING_START_FAILED", "Failed to start recording", null)
       }
 
       activeRecordingFormat = format
       Log.d(TAG, "Recording started successfully")
+      sendEvent("recordingStarted", mapOf<String, Any>())
+      emitEngineStateChanged("recordingStarted")
     }
 
     AsyncFunction("stopRecording") {
@@ -401,6 +483,12 @@ class ExpoAudioEngineModule : Module() {
       val result = engine.stopRecording()
 
       if (!result.success) {
+        emitEngineError(
+          code = "RECORDING_STOP_FAILED",
+          message = "Failed to stop recording: ${result.errorMessage}",
+          details = mapOf("errorMessage" to result.errorMessage),
+          source = "recording"
+        )
         throw CodedException(
           "RECORDING_STOP_FAILED",
           "Failed to stop recording: ${result.errorMessage}",
@@ -423,6 +511,7 @@ class ExpoAudioEngineModule : Module() {
           "fileSize" to result.fileSize
         )
       )
+      emitEngineStateChanged("recordingStopped")
 
       mapOf(
         "uri" to "file://${result.outputPath}",
@@ -469,6 +558,12 @@ class ExpoAudioEngineModule : Module() {
       )
 
       if (jobId <= 0L) {
+        emitEngineError(
+          code = "EXTRACTION_FAILED",
+          message = "Failed to start extraction",
+          details = mapOf("trackId" to trackId),
+          source = "extraction"
+        )
         promise.reject("EXTRACTION_FAILED", "Failed to start extraction", null)
         return@AsyncFunction
       }
@@ -508,6 +603,11 @@ class ExpoAudioEngineModule : Module() {
       )
 
       if (jobId <= 0L) {
+        emitEngineError(
+          code = "EXTRACTION_FAILED",
+          message = "Failed to start extraction",
+          source = "extraction"
+        )
         promise.reject("EXTRACTION_FAILED", "Failed to start extraction", null)
         return@AsyncFunction
       }
@@ -551,7 +651,7 @@ class ExpoAudioEngineModule : Module() {
         requestAudioFocus()
       }
       syncBackgroundService(engine.isPlaying())
-      sendEvent("engineStateChanged", mapOf("reason" to "backgroundPlaybackEnabled"))
+      emitEngineStateChanged("backgroundPlaybackEnabled")
     }
     Function("updateNowPlayingInfo") { metadata: Map<String, Any?> ->
       mergeNowPlayingMetadata(metadata)
@@ -568,7 +668,7 @@ class ExpoAudioEngineModule : Module() {
         abandonAudioFocus()
       }
       nowPlayingMetadata.clear()
-      sendEvent("engineStateChanged", mapOf("reason" to "backgroundPlaybackDisabled"))
+      emitEngineStateChanged("backgroundPlaybackDisabled")
     }
 
     Events(
@@ -582,6 +682,7 @@ class ExpoAudioEngineModule : Module() {
       "extractionProgress",
       "extractionComplete",
       "engineStateChanged",
+      "debugLog",
       "error"
     )
   }
@@ -621,6 +722,21 @@ class ExpoAudioEngineModule : Module() {
 
       if (!result.success) {
         Log.e(TAG, "Extraction failed for job=$jobId: ${result.errorMessage}")
+        val code = if (result.errorMessage == "Extraction cancelled") {
+          "EXTRACTION_CANCELLED"
+        } else {
+          "EXTRACTION_FAILED"
+        }
+        emitEngineError(
+          code = code,
+          message = result.errorMessage ?: "Unknown extraction error",
+          details = mapOf(
+            "jobId" to jobId,
+            "trackId" to pending.trackId,
+            "operation" to pending.operation
+          ),
+          source = "extraction"
+        )
         sendEvent(
           "extractionComplete",
           mapOf(
@@ -634,11 +750,6 @@ class ExpoAudioEngineModule : Module() {
             "operation" to pending.operation
           )
         )
-        val code = if (result.errorMessage == "Extraction cancelled") {
-          "EXTRACTION_CANCELLED"
-        } else {
-          "EXTRACTION_FAILED"
-        }
         pending.promise.reject(code, result.errorMessage, null)
       } else {
         Log.d(TAG, "Extraction successful: ${result.fileSize} bytes, ${result.durationSamples} samples")
@@ -696,12 +807,10 @@ class ExpoAudioEngineModule : Module() {
       Log.w(TAG, "Stream unhealthy before play, attempting restart")
       if (!engine.restartStream()) {
         if (!fromSystem) {
-          sendEvent(
-            "error",
-            mapOf(
-              "code" to "STREAM_DISCONNECTED",
-              "message" to "Audio stream is disconnected and could not be recovered"
-            )
+          emitEngineError(
+            code = "STREAM_DISCONNECTED",
+            message = "Audio stream is disconnected and could not be recovered",
+            source = "engine"
           )
         }
         return false
@@ -711,12 +820,10 @@ class ExpoAudioEngineModule : Module() {
     if (!requestAudioFocus()) {
       Log.w(TAG, "Audio focus request denied")
       if (!fromSystem) {
-        sendEvent(
-          "error",
-          mapOf(
-            "code" to "AUDIO_FOCUS_DENIED",
-            "message" to "Could not gain audio focus for playback"
-          )
+        emitEngineError(
+          code = "AUDIO_FOCUS_DENIED",
+          message = "Could not gain audio focus for playback",
+          source = "focus"
         )
       }
       return false
@@ -750,7 +857,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     if (fromSystem) {
-      sendEvent("engineStateChanged", mapOf("reason" to "pausedFromSystem"))
+      emitEngineStateChanged("pausedFromSystem")
     }
   }
 
@@ -769,7 +876,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     if (fromSystem) {
-      sendEvent("engineStateChanged", mapOf("reason" to "stoppedFromSystem"))
+      emitEngineStateChanged("stoppedFromSystem")
     }
   }
 
@@ -826,7 +933,7 @@ class ExpoAudioEngineModule : Module() {
         if (engine.isPlaying()) {
           shouldResumeAfterTransientFocusLoss = true
           pausePlaybackInternal(engine, fromSystem = true, keepAudioFocus = true)
-          sendEvent("engineStateChanged", mapOf("reason" to "audioFocusLossTransient"))
+          emitEngineStateChanged("audioFocusLossTransient")
         }
       }
       AudioManager.AUDIOFOCUS_LOSS_TRANSIENT_CAN_DUCK -> {
@@ -834,12 +941,9 @@ class ExpoAudioEngineModule : Module() {
           volumeBeforeDuck = engine.getMasterVolume()
           val duckedVolume = (volumeBeforeDuck!! * 0.3f).coerceAtLeast(0.05f)
           engine.setMasterVolume(duckedVolume)
-          sendEvent(
-            "engineStateChanged",
-            mapOf(
-              "reason" to "audioFocusDuck",
-              "volume" to duckedVolume.toDouble()
-            )
+          emitEngineStateChanged(
+            reason = "audioFocusDuck",
+            payload = mapOf("volume" to duckedVolume.toDouble())
           )
         }
       }
@@ -847,7 +951,7 @@ class ExpoAudioEngineModule : Module() {
         shouldResumeAfterTransientFocusLoss = false
         if (engine.isPlaying()) {
           pausePlaybackInternal(engine, fromSystem = true)
-          sendEvent("engineStateChanged", mapOf("reason" to "audioFocusLoss"))
+          emitEngineStateChanged("audioFocusLoss")
         } else {
           abandonAudioFocus()
         }
@@ -900,6 +1004,80 @@ class ExpoAudioEngineModule : Module() {
     abandonAudioFocus()
   }
 
+  private fun emitEngineStateChanged(
+    reason: String,
+    payload: Map<String, Any?> = emptyMap()
+  ) {
+    val eventPayload = payload.toMutableMap()
+    eventPayload["reason"] = reason
+    sendEvent("engineStateChanged", eventPayload)
+  }
+
+  private fun emitDebugLog(
+    level: String,
+    message: String,
+    context: Map<String, Any?>? = null
+  ) {
+    val payload = mutableMapOf<String, Any?>(
+      "level" to level,
+      "message" to message
+    )
+    if (context != null) {
+      payload["context"] = context
+    }
+    sendEvent("debugLog", payload)
+  }
+
+  private fun emitEngineError(
+    code: String,
+    message: String,
+    details: Any? = null,
+    source: String? = null
+  ) {
+    val resolvedSource = source ?: resolveErrorSource(code)
+    val (severity, recoverable) = classifyError(code)
+    val payload = mutableMapOf<String, Any?>(
+      "code" to code,
+      "message" to message,
+      "severity" to severity,
+      "recoverable" to recoverable,
+      "source" to resolvedSource,
+      "timestampMs" to System.currentTimeMillis(),
+      "platform" to "android"
+    )
+    if (details != null) {
+      payload["details"] = details
+    }
+    sendEvent("error", payload)
+    emitDebugLog(
+      level = if (severity == "fatal") "error" else "warn",
+      message = message,
+      context = payload
+    )
+  }
+
+  private fun resolveErrorSource(code: String): String {
+    return when {
+      code == "AUDIO_SESSION_FAILED" -> "session"
+      code == "AUDIO_FOCUS_DENIED" -> "focus"
+      code.startsWith("PLAYBACK_") || code == "NO_TRACKS_LOADED" -> "playback"
+      code.startsWith("RECORDING_") -> "recording"
+      code.startsWith("EXTRACTION_") -> "extraction"
+      code.startsWith("ENGINE_") || code.startsWith("TRACK_") || code == "STREAM_DISCONNECTED" -> "engine"
+      else -> "system"
+    }
+  }
+
+  private fun classifyError(code: String): Pair<String, Boolean> {
+    return when (code) {
+      "ENGINE_INIT_FAILED",
+      "ENGINE_START_FAILED",
+      "AUDIO_SESSION_FAILED",
+      "STREAM_DISCONNECTED" -> "fatal" to false
+      else -> "warning" to true
+    }
+  }
+
   private fun mapToBundle(map: Map<String, Any?>): Bundle {
     val bundle = Bundle()
     map.forEach { (key, value) ->

package/dist/AudioEngineModule.js

@@ -42,5 +42,5 @@ export const AudioEngineModule = {
     enableBackgroundPlayback: (metadata) => NativeAudioEngineModule.enableBackgroundPlayback(metadata),
     updateNowPlayingInfo: (metadata) => NativeAudioEngineModule.updateNowPlayingInfo(metadata),
     disableBackgroundPlayback: () => NativeAudioEngineModule.disableBackgroundPlayback(),
-    addListener: (event, callback) => NativeAudioEngineModule.addListener(event, callback)
+    addListener: ((event, callback) => NativeAudioEngineModule.addListener(event, callback))
 };

package/dist/AudioEngineModule.types.d.ts

@@ -64,11 +64,62 @@ export interface PlaybackCardOptions {
     showStop?: boolean;
     seekStepMs?: number;
 }
-export type AudioEngineEvent = 'playbackStateChange' | 'positionUpdate' | 'playbackComplete' | 'trackLoaded' | 'trackUnloaded' | 'recordingStarted' | 'recordingStopped' | 'extractionProgress' | 'extractionComplete' | 'error';
+export type AudioEngineEvent = 'playbackStateChange' | 'positionUpdate' | 'playbackComplete' | 'trackLoaded' | 'trackUnloaded' | 'recordingStarted' | 'recordingStopped' | 'extractionProgress' | 'extractionComplete' | 'engineStateChanged' | 'debugLog' | 'error';
+export type AudioEngineErrorSeverity = 'warning' | 'fatal';
+export type AudioEngineErrorSource = 'engine' | 'session' | 'playback' | 'recording' | 'extraction' | 'focus' | 'system';
 export interface AudioEngineError {
     code: string;
     message: string;
     details?: unknown;
+    severity: AudioEngineErrorSeverity;
+    recoverable: boolean;
+    source: AudioEngineErrorSource;
+    timestampMs: number;
+    platform: 'ios' | 'android';
+}
+export interface AudioEngineEventMap {
+    playbackStateChange: {
+        state: string;
+        positionMs: number;
+        durationMs: number;
+    };
+    positionUpdate: {
+        positionMs: number;
+        durationMs: number;
+    };
+    playbackComplete: {
+        positionMs: number;
+        durationMs: number;
+    };
+    trackLoaded: {
+        trackId: string;
+    };
+    trackUnloaded: {
+        trackId: string;
+    };
+    recordingStarted: Record<string, never>;
+    recordingStopped: {
+        uri: string;
+        duration: number;
+        startTimeMs: number;
+        startTimeSamples?: number;
+        sampleRate: number;
+        channels: number;
+        format: 'aac' | 'm4a' | 'mp3' | 'wav';
+        fileSize: number;
+    };
+    extractionProgress: Record<string, unknown>;
+    extractionComplete: Record<string, unknown>;
+    engineStateChanged: {
+        reason: string;
+        [key: string]: unknown;
+    };
+    debugLog: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+        message: string;
+        context?: unknown;
+    };
+    error: AudioEngineError;
 }
 export interface AudioEngine {
     initialize(config: AudioEngineConfig): Promise<void>;
@@ -112,7 +163,7 @@ export interface AudioEngine {
     enableBackgroundPlayback(metadata: MediaMetadata): Promise<void>;
     updateNowPlayingInfo(metadata: Partial<MediaMetadata>): void;
     disableBackgroundPlayback(): Promise<void>;
-    addListener(event: AudioEngineEvent, callback: Function): {
+    addListener<K extends keyof AudioEngineEventMap>(event: K, callback: (payload: AudioEngineEventMap[K]) => void): {
         remove: () => void;
     };
 }

package/ios/ExpoAudioEngineModule.swift

@@ -1,4 +1,5 @@
 import ExpoModulesCore
+import Foundation
 
 public class ExpoAudioEngineModule: Module {
   private let engine = AudioEngineFacade()
@@ -6,6 +7,7 @@ public class ExpoAudioEngineModule: Module {
   public func definition() -> ModuleDefinition {
     Name("ExpoAudioEngineModule")
     OnCreate {
+      emitDebugLog(level: "info", message: "ExpoAudioEngineModule created")
       engine.onPlaybackStateChange = { [weak self] state, positionMs, durationMs in
         DispatchQueue.main.async {
           self?.sendEvent(
@@ -16,6 +18,13 @@ public class ExpoAudioEngineModule: Module {
               "durationMs": durationMs
             ]
           )
+          self?.sendEvent(
+            "positionUpdate",
+            [
+              "positionMs": positionMs,
+              "durationMs": durationMs
+            ]
+          )
         }
       }
       engine.onPlaybackComplete = { [weak self] positionMs, durationMs in
@@ -31,14 +40,7 @@ public class ExpoAudioEngineModule: Module {
       }
       engine.onError = { [weak self] code, message, details in
         DispatchQueue.main.async {
-          var payload: [String: Any] = [
-            "code": code,
-            "message": message
-          ]
-          if let details = details {
-            payload["details"] = details
-          }
-          self?.sendEvent("error", payload)
+          self?.emitEngineError(code: code, message: message, details: details)
         }
       }
     }
@@ -46,13 +48,18 @@ public class ExpoAudioEngineModule: Module {
       engine.onPlaybackStateChange = nil
       engine.onPlaybackComplete = nil
       engine.onError = nil
+      emitDebugLog(level: "info", message: "ExpoAudioEngineModule destroyed")
     }
 
     AsyncFunction("initialize") { (config: [String: Any]) in
       engine.initialize(config: config)
+      emitEngineStateChanged(reason: "initialized")
+      emitDebugLog(level: "info", message: "Audio engine initialized", context: ["config": config])
     }
     AsyncFunction("release") {
       engine.releaseResources()
+      emitEngineStateChanged(reason: "released")
+      emitDebugLog(level: "info", message: "Audio engine released")
     }
     AsyncFunction("loadTracks") { (tracks: [[String: Any]]) throws in
       if let failure = engine.loadTracks(tracks) {
@@ -60,14 +67,25 @@ public class ExpoAudioEngineModule: Module {
         let message = failedCount > 0
           ? "Failed to load \(failedCount) track(s)."
           : "Failed to load tracks."
+        emitEngineError(code: "TRACK_LOAD_FAILED", message: message, details: failure, source: "engine")
         throw AudioEngineError("TRACK_LOAD_FAILED", message, details: failure)
       }
+      for track in tracks {
+        if let trackId = track["id"] as? String {
+          sendEvent("trackLoaded", ["trackId": trackId])
+        }
+      }
     }
     AsyncFunction("unloadTrack") { (trackId: String) in
       engine.unloadTrack(trackId)
+      sendEvent("trackUnloaded", ["trackId": trackId])
     }
     AsyncFunction("unloadAllTracks") {
+      let loadedTrackIds = engine.getLoadedTracks().compactMap { $0["id"] as? String }
       engine.unloadAllTracks()
+      for trackId in loadedTrackIds {
+        sendEvent("trackUnloaded", ["trackId": trackId])
+      }
     }
     Function("getLoadedTracks") {
       return engine.getLoadedTracks()
@@ -84,6 +102,13 @@ public class ExpoAudioEngineModule: Module {
     }
     Function("seek") { (positionMs: Double) in
       engine.seek(positionMs: positionMs)
+      sendEvent(
+        "positionUpdate",
+        [
+          "positionMs": engine.getCurrentPosition(),
+          "durationMs": engine.getDuration()
+        ]
+      )
     }
     Function("isPlaying") {
       return engine.isPlaying()
@@ -147,17 +172,23 @@ public class ExpoAudioEngineModule: Module {
       let didStart = engine.startRecording(config: config)
       if !didStart {
         let detail = engine.getLastRecordingError() ?? "audio input format is invalid or the audio session is not ready"
-        throw NSError(
-          domain: "ExpoAudioEngine",
-          code: 1,
-          userInfo: [
-            NSLocalizedDescriptionKey: "Failed to start recording. \(detail)."
-          ]
+        let message = "Failed to start recording. \(detail)."
+        emitEngineError(
+          code: "RECORDING_START_FAILED",
+          message: message,
+          details: ["detail": detail],
+          source: "recording"
         )
+        throw AudioEngineError("RECORDING_START_FAILED", message, details: ["detail": detail])
       }
+      sendEvent("recordingStarted", [String: Any]())
+      emitEngineStateChanged(reason: "recordingStarted")
     }
     AsyncFunction("stopRecording") {
-      return engine.stopRecording()
+      let result = engine.stopRecording()
+      sendEvent("recordingStopped", result)
+      emitEngineStateChanged(reason: "recordingStopped")
+      return result
     }
     Function("isRecording") {
       return engine.isRecording()
@@ -167,11 +198,67 @@ public class ExpoAudioEngineModule: Module {
     }
 
     AsyncFunction("extractTrack") { (trackId: String, config: [String: Any]?) throws in
-      return try engine.extractTrack(trackId: trackId, config: config)
+      do {
+        let result = try engine.extractTrack(trackId: trackId, config: config)
+        sendEvent("extractionProgress", ["trackId": trackId, "progress": 1.0, "operation": "track"])
+        var completionPayload: [String: Any] = [
+          "success": true,
+          "trackId": trackId
+        ]
+        for (key, value) in result {
+          completionPayload[key] = value
+        }
+        sendEvent("extractionComplete", completionPayload)
+        return result
+      } catch let error as AudioEngineError {
+        emitEngineError(
+          code: error.code,
+          message: error.description,
+          details: error.details,
+          source: "extraction"
+        )
+        sendEvent(
+          "extractionComplete",
+          [
+            "success": false,
+            "trackId": trackId,
+            "errorMessage": error.description
+          ]
+        )
+        throw error
+      }
     }
 
     AsyncFunction("extractAllTracks") { (config: [String: Any]?) throws in
-      return try engine.extractAllTracks(config: config)
+      do {
+        let results = try engine.extractAllTracks(config: config)
+        sendEvent("extractionProgress", ["progress": 1.0, "operation": "mix"])
+        sendEvent(
+          "extractionComplete",
+          [
+            "success": true,
+            "operation": "mix",
+            "count": results.count
+          ]
+        )
+        return results
+      } catch let error as AudioEngineError {
+        emitEngineError(
+          code: error.code,
+          message: error.description,
+          details: error.details,
+          source: "extraction"
+        )
+        sendEvent(
+          "extractionComplete",
+          [
+            "success": false,
+            "operation": "mix",
+            "errorMessage": error.description
+          ]
+        )
+        throw error
+      }
     }
 
     Function("cancelExtraction") { (jobId: Double?) in
@@ -190,12 +277,14 @@ public class ExpoAudioEngineModule: Module {
 
     AsyncFunction("enableBackgroundPlayback") { (metadata: [String: Any]) in
       engine.enableBackgroundPlayback(metadata: metadata)
+      emitEngineStateChanged(reason: "backgroundPlaybackEnabled")
     }
     Function("updateNowPlayingInfo") { (metadata: [String: Any]) in
       engine.updateNowPlayingInfo(metadata: metadata)
     }
     AsyncFunction("disableBackgroundPlayback") {
       engine.disableBackgroundPlayback()
+      emitEngineStateChanged(reason: "backgroundPlaybackDisabled")
     }
 
     Events(
@@ -208,8 +297,85 @@ public class ExpoAudioEngineModule: Module {
       "recordingStopped",
       "extractionProgress",
       "extractionComplete",
+      "engineStateChanged",
       "error",
       "debugLog"
     )
   }
+
+  private func emitEngineStateChanged(reason: String, payload: [String: Any] = [:]) {
+    var statePayload = payload
+    statePayload["reason"] = reason
+    sendEvent("engineStateChanged", statePayload)
+  }
+
+  private func emitDebugLog(level: String, message: String, context: [String: Any]? = nil) {
+    var payload: [String: Any] = [
+      "level": level,
+      "message": message
+    ]
+    if let context = context {
+      payload["context"] = context
+    }
+    sendEvent("debugLog", payload)
+  }
+
+  private func emitEngineError(
+    code: String,
+    message: String,
+    details: [String: Any]? = nil,
+    source: String? = nil
+  ) {
+    let sourceValue = source ?? resolveErrorSource(code: code)
+    let classification = classifyError(code: code)
+    var payload: [String: Any] = [
+      "code": code,
+      "message": message,
+      "severity": classification.severity,
+      "recoverable": classification.recoverable,
+      "source": sourceValue,
+      "timestampMs": Int(Date().timeIntervalSince1970 * 1000.0),
+      "platform": "ios"
+    ]
+    if let details = details {
+      payload["details"] = details
+    }
+    sendEvent("error", payload)
+    emitDebugLog(level: classification.severity == "fatal" ? "error" : "warn", message: message, context: payload)
+  }
+
+  private func resolveErrorSource(code: String) -> String {
+    if code == "AUDIO_SESSION_FAILED" {
+      return "session"
+    }
+    if code == "AUDIO_FOCUS_DENIED" {
+      return "focus"
+    }
+    if code.hasPrefix("PLAYBACK_") || code == "NO_TRACKS_LOADED" {
+      return "playback"
+    }
+    if code.hasPrefix("RECORDING_") {
+      return "recording"
+    }
+    if code.hasPrefix("EXTRACTION_") {
+      return "extraction"
+    }
+    if code.hasPrefix("ENGINE_") || code.hasPrefix("TRACK_") || code == "STREAM_DISCONNECTED" {
+      return "engine"
+    }
+    return "system"
+  }
+
+  private func classifyError(code: String) -> (severity: String, recoverable: Bool) {
+    let fatalCodes: Set<String> = [
+      "ENGINE_INIT_FAILED",
+      "ENGINE_START_FAILED",
+      "AUDIO_SESSION_FAILED",
+      "STREAM_DISCONNECTED"
+    ]
+    if fatalCodes.contains(code) {
+      return ("fatal", false)
+    }
+    return ("warning", true)
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sezo-audio-engine",
-  "version": "0.0.15",
+  "version": "0.0.16",
   "description": "Cross-platform Expo module for the Sezo Audio Engine with iOS implementation and background playback.",
   "license": "MIT",
   "author": "Sezo",