sezo-audio-engine 0.0.13 → 0.0.14

package/README.md

@@ -38,7 +38,7 @@ allprojects {
 Optionally pin the engine version in `android/gradle.properties`:
 
 ```properties
-sezoAudioEngineVersion=android-engine-v0.1.6
+sezoAudioEngineVersion=android-engine-v0.1.7
 ```
 
 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.6"
+    def sezoAudioEngineVersion = project.findProperty("sezoAudioEngineVersion") ?: "android-engine-v0.1.7"
     implementation "com.github.Sepzie:SezoAudioEngine:${sezoAudioEngineVersion}"
   }
 }

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

@@ -5,6 +5,7 @@ import android.os.Bundle
 import android.util.Log
 import com.sezo.audioengine.AudioEngine
 import expo.modules.kotlin.Promise
+import expo.modules.kotlin.exception.CodedException
 import expo.modules.kotlin.modules.Module
 import expo.modules.kotlin.modules.ModuleDefinition
 import java.util.Collections
@@ -60,6 +61,10 @@ class ExpoAudioEngineModule : Module() {
     val operation: String
   )
 
+  private fun requireEngine(): AudioEngine {
+    return audioEngine ?: throw CodedException("ENGINE_NOT_INITIALIZED", "Engine not initialized")
+  }
+
   override fun definition() = ModuleDefinition {
     Name("ExpoAudioEngineModule")
 
@@ -151,7 +156,7 @@ class ExpoAudioEngineModule : Module() {
       val success = audioEngine?.initialize(sampleRate, maxTracks) ?: false
 
       if (!success) {
-        throw Exception("Failed to initialize audio engine")
+        throw CodedException("ENGINE_INIT_FAILED", "Failed to initialize audio engine", null)
       }
 
       ensureAudioFocusManager()
@@ -194,18 +199,24 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("loadTracks") { tracks: List<Map<String, Any?>> ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
 
       tracks.forEach { track ->
-        val id = track["id"] as? String ?: throw Exception("Missing track id")
-        val uri = track["uri"] as? String ?: throw Exception("Missing track uri")
+        val id = track["id"] as? String
+          ?: throw CodedException("TRACK_LOAD_FAILED", "Missing track id", null)
+        val uri = track["uri"] as? String
+          ?: 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)
 
         if (!engine.loadTrack(id, filePath, startTimeMs)) {
-          throw Exception("Failed to load track: $id from $filePath")
+          throw CodedException(
+            "TRACK_LOAD_FAILED",
+            "Failed to load track: $id from $filePath",
+            null
+          )
         }
 
         loadedTrackIds.add(id)
@@ -214,10 +225,10 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("unloadTrack") { trackId: String ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
 
       if (!engine.unloadTrack(trackId)) {
-        throw Exception("Failed to unload track: $trackId")
+        throw CodedException("TRACK_UNLOAD_FAILED", "Failed to unload track: $trackId", null)
       }
 
       loadedTrackIds.remove(trackId)
@@ -225,7 +236,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("unloadAllTracks") {
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.unloadAllTracks()
       loadedTrackIds.clear()
       Log.d(TAG, "All tracks unloaded")
@@ -236,27 +247,27 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("play") {
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       if (!startPlaybackInternal(engine, fromSystem = false)) {
-        throw Exception("Failed to start playback")
+        throw CodedException("PLAYBACK_START_FAILED", "Failed to start playback", null)
       }
       Log.d(TAG, "Playback started")
     }
 
     Function("pause") {
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       pausePlaybackInternal(engine, fromSystem = false)
       Log.d(TAG, "Playback paused")
     }
 
     Function("stop") {
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       stopPlaybackInternal(engine, fromSystem = false)
       Log.d(TAG, "Playback stopped")
     }
 
     Function("seek") { positionMs: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.seek(positionMs)
       Log.d(TAG, "Seeked to position: $positionMs ms")
     }
@@ -274,27 +285,27 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("setTrackVolume") { trackId: String, volume: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setTrackVolume(trackId, volume.toFloat())
     }
 
     Function("setTrackMuted") { trackId: String, muted: Boolean ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setTrackMuted(trackId, muted)
     }
 
     Function("setTrackSolo") { trackId: String, solo: Boolean ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setTrackSolo(trackId, solo)
     }
 
     Function("setTrackPan") { trackId: String, pan: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setTrackPan(trackId, pan.toFloat())
     }
 
     Function("setMasterVolume") { volume: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setMasterVolume(volume.toFloat())
     }
 
@@ -303,7 +314,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("setPitch") { semitones: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setPitch(semitones.toFloat())
     }
 
@@ -312,7 +323,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("setSpeed") { rate: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setSpeed(rate.toFloat())
     }
 
@@ -321,13 +332,13 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("setTempoAndPitch") { tempo: Double, pitch: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setSpeed(tempo.toFloat())
       engine.setPitch(pitch.toFloat())
     }
 
     Function("setTrackPitch") { trackId: String, semitones: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setTrackPitch(trackId, semitones.toFloat())
     }
 
@@ -336,7 +347,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("setTrackSpeed") { trackId: String, rate: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setTrackSpeed(trackId, rate.toFloat())
     }
 
@@ -345,7 +356,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("startRecording") { config: Map<String, Any?>? ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
 
       val sampleRate = (config?.get("sampleRate") as? Number)?.toInt() ?: 44100
       val channels = (config?.get("channels") as? Number)?.toInt() ?: 1
@@ -376,7 +387,7 @@ class ExpoAudioEngineModule : Module() {
       )
 
       if (!success) {
-        throw Exception("Failed to start recording")
+        throw CodedException("RECORDING_START_FAILED", "Failed to start recording", null)
       }
 
       activeRecordingFormat = format
@@ -384,13 +395,17 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("stopRecording") {
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
 
       Log.d(TAG, "Stopping recording")
       val result = engine.stopRecording()
 
       if (!result.success) {
-        throw Exception("Failed to stop recording: ${result.errorMessage}")
+        throw CodedException(
+          "RECORDING_STOP_FAILED",
+          "Failed to stop recording: ${result.errorMessage}",
+          null
+        )
       }
 
       Log.d(TAG, "Recording stopped: ${result.fileSize} bytes, ${result.durationSamples} samples")
@@ -426,12 +441,12 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("setRecordingVolume") { volume: Double ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       engine.setRecordingVolume(volume.toFloat())
     }
 
     AsyncFunction("extractTrack") { trackId: String, config: Map<String, Any?>?, promise: Promise ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
 
       val format = (config?.get("format") as? String) ?: "wav"
       val bitrate = (config?.get("bitrate") as? Number)?.toInt() ?: 128000
@@ -471,7 +486,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     AsyncFunction("extractAllTracks") { config: Map<String, Any?>?, promise: Promise ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
 
       val format = (config?.get("format") as? String) ?: "wav"
       val bitrate = (config?.get("bitrate") as? Number)?.toInt() ?: 128000
@@ -510,7 +525,7 @@ class ExpoAudioEngineModule : Module() {
     }
 
     Function("cancelExtraction") { jobId: Double? ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       val resolvedJobId = jobId?.toLong() ?: lastExtractionJobId
       if (resolvedJobId == null) {
         false
@@ -527,7 +542,7 @@ class ExpoAudioEngineModule : Module() {
     Function("getTrackLevel") { _trackId: String -> 0.0 }
 
     AsyncFunction("enableBackgroundPlayback") { metadata: Map<String, Any?> ->
-      val engine = audioEngine ?: throw Exception("Engine not initialized")
+      val engine = requireEngine()
       backgroundPlaybackEnabled = true
       mergeNowPlayingMetadata(metadata)
       ensureAudioFocusManager()
@@ -940,15 +955,27 @@ class ExpoAudioEngineModule : Module() {
       uri.startsWith("content://") -> {
         // TODO: Handle content:// URIs with ContentResolver
         // For now, throw an error - this will be implemented when needed
-        throw Exception("content:// URIs not yet supported. Use file:// or absolute paths.")
+        throw CodedException(
+          "UNSUPPORTED_URI",
+          "content:// URIs not yet supported. Use file:// or absolute paths.",
+          null
+        )
       }
       uri.startsWith("asset://") -> {
         // TODO: Handle asset:// URIs by copying to temp file
         // For now, throw an error - this will be implemented when needed
-        throw Exception("asset:// URIs not yet supported. Use file:// or absolute paths.")
+        throw CodedException(
+          "UNSUPPORTED_URI",
+          "asset:// URIs not yet supported. Use file:// or absolute paths.",
+          null
+        )
       }
       else -> {
-        throw Exception("Unsupported URI scheme: $uri. Use file:// or absolute paths.")
+        throw CodedException(
+          "UNSUPPORTED_URI",
+          "Unsupported URI scheme: $uri. Use file:// or absolute paths.",
+          null
+        )
       }
     }
   }

package/ios/AudioEngine/AudioSessionManager.swift

@@ -11,7 +11,7 @@ final class AudioSessionManager {
       try session.setCategory(
         .playAndRecord,
         mode: .default,
-        options: [.defaultToSpeaker, .allowBluetooth]
+        options: [.defaultToSpeaker, .allowBluetoothHFP]
       )
     } catch {
       lastError = "setCategory failed: \(error.localizedDescription)"
@@ -51,10 +51,12 @@ final class AudioSessionManager {
   func enableBackgroundPlayback(with config: AudioEngineConfig) -> Bool {
     lastError = nil
     do {
+      // The current engine graph always includes an input-side recording mixer path.
+      // Keep an input-capable category in background mode so engine.start() remains valid.
       try session.setCategory(
-        .playback,
+        .playAndRecord,
         mode: .default,
-        options: [.allowBluetooth, .allowAirPlay]
+        options: [.defaultToSpeaker, .allowBluetoothHFP, .allowAirPlay]
       )
     } catch {
       lastError = "setCategory failed: \(error.localizedDescription)"

package/ios/AudioEngine/NativeAudioEngine.swift

@@ -48,9 +48,13 @@ final class NativeAudioEngine {
   private var playCommandTarget: Any?
   private var pauseCommandTarget: Any?
   private var toggleCommandTarget: Any?
+  private var changePlaybackPositionCommandTarget: Any?
+  private var skipForwardCommandTarget: Any?
+  private var skipBackwardCommandTarget: Any?
   private var lastConfig = AudioEngineConfig(dictionary: [:])
   var onPlaybackStateChange: ((String, Double, Double) -> Void)?
   var onPlaybackComplete: ((Double, Double) -> Void)?
+  var onError: ((String, String, [String: Any]?) -> Void)?
 
   /// Bookkeeping for a live recording session.
   private struct RecordingState {
@@ -104,13 +108,15 @@ final class NativeAudioEngine {
   }
 
   /// Loads and attaches tracks into the engine graph.
-  func loadTracks(_ trackInputs: [[String: Any]]) {
-    queue.sync {
+  func loadTracks(_ trackInputs: [[String: Any]]) -> [String: Any]? {
+    return queue.sync {
       ensureInitializedIfNeeded()
       stopEngineIfRunning()
       stopAllPlayers()
+      var failedInputs: [[String: Any]] = []
       for input in trackInputs {
         guard let track = AudioTrack(input: input) else {
+          failedInputs.append(input)
           continue
         }
         if let existing = tracks[track.id] {
@@ -123,6 +129,20 @@ final class NativeAudioEngine {
       applyPitchSpeedForAllTracks()
       recalculateDuration()
       engine.prepare()
+      updateRemoteCommandStates()
+      if failedInputs.isEmpty {
+        return nil
+      }
+      var details: [String: Any] = ["failedCount": failedInputs.count]
+      let failedIds = failedInputs.compactMap { $0["id"] as? String }
+      if !failedIds.isEmpty {
+        details["failedTrackIds"] = failedIds
+      }
+      let failedUris = failedInputs.compactMap { $0["uri"] as? String }
+      if !failedUris.isEmpty {
+        details["failedTrackUris"] = failedUris
+      }
+      return details
     }
   }
 
@@ -134,6 +154,7 @@ final class NativeAudioEngine {
       }
       applyMixingForAllTracks()
       recalculateDuration()
+      updateRemoteCommandStates()
     }
   }
 
@@ -144,6 +165,7 @@ final class NativeAudioEngine {
       detachAllTracks()
       tracks.removeAll()
       recalculateDuration()
+      updateRemoteCommandStates()
     }
   }
 
@@ -486,20 +508,18 @@ final class NativeAudioEngine {
   }
 
   /// Offline export for a single track.
-  func extractTrack(trackId: String, config: [String: Any]?) -> [String: Any] {
-    return queue.sync {
+  func extractTrack(trackId: String, config: [String: Any]?) throws -> [String: Any] {
+    return try queue.sync {
       guard let track = tracks[trackId] else {
-        return [
-          "trackId": trackId,
-          "uri": "",
-          "duration": 0,
-          "format": "aac",
-          "fileSize": 0
-        ]
+        throw AudioEngineError(
+          "TRACK_NOT_FOUND",
+          "Track not found: \(trackId).",
+          details: ["trackId": trackId]
+        )
       }
 
       let durationMs = track.startTimeMs + track.durationMs
-      return renderOffline(
+      return try renderOffline(
         tracksToRender: [track],
         totalDurationMs: durationMs,
         config: config,
@@ -509,12 +529,18 @@ final class NativeAudioEngine {
   }
 
   /// Offline export for all tracks (one file per track).
-  func extractAllTracks(config: [String: Any]?) -> [[String: Any]] {
-    return queue.sync {
+  func extractAllTracks(config: [String: Any]?) throws -> [[String: Any]] {
+    return try queue.sync {
+      if tracks.isEmpty {
+        throw AudioEngineError(
+          "NO_TRACKS_LOADED",
+          "Cannot extract without loaded tracks."
+        )
+      }
       var results: [[String: Any]] = []
       for track in tracks.values {
         let durationMs = track.startTimeMs + track.durationMs
-        let result = renderOffline(
+        let result = try renderOffline(
           tracksToRender: [track],
           totalDurationMs: durationMs,
           config: config,
@@ -554,6 +580,7 @@ final class NativeAudioEngine {
       backgroundPlaybackEnabled = true
       nowPlayingMetadata.merge(metadata) { _, new in new }
       _ = sessionManager.enableBackgroundPlayback(with: lastConfig)
+      setRemoteControlEventsEnabled(true)
       configureRemoteCommandsIfNeeded()
       updateNowPlayingInfoInternal()
     }
@@ -574,6 +601,10 @@ final class NativeAudioEngine {
       nowPlayingMetadata.removeAll()
       removeRemoteCommands()
       MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
+      if #available(iOS 13.0, *) {
+        MPNowPlayingInfoCenter.default().playbackState = .stopped
+      }
+      setRemoteControlEventsEnabled(false)
       _ = sessionManager.configure(with: lastConfig)
     }
   }
@@ -592,10 +623,18 @@ final class NativeAudioEngine {
       return
     }
     let config = lastConfig
+    let configured: Bool
     if backgroundPlaybackEnabled {
-      _ = sessionManager.enableBackgroundPlayback(with: config)
+      configured = sessionManager.enableBackgroundPlayback(with: config)
     } else {
-      _ = sessionManager.configure(with: config)
+      configured = sessionManager.configure(with: config)
+    }
+    if !configured {
+      emitError(
+        code: "AUDIO_SESSION_FAILED",
+        message: sessionManager.lastErrorDescription() ?? "Audio session configuration failed",
+        details: ["backgroundPlaybackEnabled": backgroundPlaybackEnabled]
+      )
     }
     _ = ensureRecordingMixerConnected(
       sampleRate: AVAudioSession.sharedInstance().sampleRate,
@@ -951,7 +990,7 @@ final class NativeAudioEngine {
     totalDurationMs: Double,
     config: [String: Any]?,
     trackId: String
-  ) -> [String: Any] {
+  ) throws -> [String: Any] {
     ensureInitializedIfNeeded()
     stopEngineIfRunning()
     stopAllPlayers()
@@ -988,6 +1027,12 @@ final class NativeAudioEngine {
     let originalState = snapshotTrackState()
     applyExtractionMixOverrides(tracksToRender: tracksToRender, includeEffects: includeEffects)
 
+    let errorContext: [String: Any] = [
+      "trackId": trackId,
+      "format": formatInfo.format,
+      "outputUri": outputURL.absoluteString
+    ]
+
     do {
       try engine.enableManualRenderingMode(
         .offline,
@@ -1022,7 +1067,11 @@ final class NativeAudioEngine {
           pcmFormat: renderFormat,
           frameCapacity: frameCount
         ) else {
-          break
+          throw AudioEngineError(
+            "EXTRACTION_FAILED",
+            "Failed to allocate render buffer.",
+            details: errorContext
+          )
         }
 
         let status = try engine.renderOffline(frameCount, to: buffer)
@@ -1034,9 +1083,17 @@ final class NativeAudioEngine {
         case .cannotDoInCurrentContext:
           continue
         case .error:
-          break
+          throw AudioEngineError(
+            "EXTRACTION_FAILED",
+            "Offline render failed.",
+            details: errorContext
+          )
         @unknown default:
-          break
+          throw AudioEngineError(
+            "EXTRACTION_FAILED",
+            "Offline render failed with unknown status.",
+            details: errorContext
+          )
         }
       }
 
@@ -1045,13 +1102,16 @@ final class NativeAudioEngine {
     } catch {
       engine.disableManualRenderingMode()
       restoreTrackState(originalState)
-      return [
-        "trackId": trackId,
-        "uri": "",
-        "duration": 0,
-        "format": formatInfo.format,
-        "fileSize": 0
-      ]
+      if let codedError = error as? AudioEngineError {
+        throw codedError
+      }
+      var details = errorContext
+      details["nativeError"] = error.localizedDescription
+      throw AudioEngineError(
+        "EXTRACTION_FAILED",
+        "Failed to extract track \(trackId). \(error.localizedDescription)",
+        details: details
+      )
     }
 
     restoreTrackState(originalState)
@@ -1148,11 +1208,19 @@ final class NativeAudioEngine {
     }
   }
 
+  private func emitError(code: String, message: String, details: [String: Any]? = nil) {
+    onError?(code, message, details)
+  }
+
   /// Starts the AVAudioEngine if it is not already running.
   @discardableResult
   private func startEngineIfNeeded() -> Bool {
     if !isInitialized {
       lastEngineError = "audio engine not initialized"
+      emitError(
+        code: "ENGINE_NOT_INITIALIZED",
+        message: lastEngineError ?? "Audio engine not initialized"
+      )
       return false
     }
     if !engine.isRunning {
@@ -1161,6 +1229,20 @@ final class NativeAudioEngine {
         lastEngineError = nil
       } catch {
         lastEngineError = error.localizedDescription
+        let session = AVAudioSession.sharedInstance()
+        emitError(
+          code: "ENGINE_START_FAILED",
+          message: "Failed to start audio engine. \(error.localizedDescription)",
+          details: [
+            "nativeError": error.localizedDescription,
+            "category": session.category.rawValue,
+            "sampleRate": session.sampleRate,
+            "inputAvailable": session.isInputAvailable,
+            "inputChannels": session.inputNumberOfChannels,
+            "route": describeRoute(session),
+            "recordingMixerConnected": recordingMixerConnected
+          ]
+        )
         return false
       }
     }
@@ -1212,7 +1294,13 @@ final class NativeAudioEngine {
 
   /// Internal play logic (expects to run on the queue).
   private func playInternal() {
-    guard !tracks.isEmpty else { return }
+    guard !tracks.isEmpty else {
+      emitError(
+        code: "NO_TRACKS_LOADED",
+        message: "Cannot start playback without loaded tracks."
+      )
+      return
+    }
     ensureInitializedIfNeeded()
     if isPlayingFlag {
       return
@@ -1261,6 +1349,13 @@ final class NativeAudioEngine {
     updateNowPlayingInfoInternal()
   }
 
+  private func seekByIntervalInternal(deltaMs: Double) {
+    let current = isPlayingFlag ? currentPlaybackPositionMs() : currentPositionMs
+    let maxPosition = durationMs > 0 ? durationMs : Double.greatestFiniteMagnitude
+    let target = min(max(0.0, current + deltaMs), maxPosition)
+    seekInternal(positionMs: target)
+  }
+
   /// Updates Now Playing info based on stored metadata and playback state.
   private func updateNowPlayingInfoInternal() {
     guard backgroundPlaybackEnabled else { return }
@@ -1285,6 +1380,16 @@ final class NativeAudioEngine {
     info[MPNowPlayingInfoPropertyPlaybackRate] = isPlayingFlag ? 1.0 : 0.0
 
     MPNowPlayingInfoCenter.default().nowPlayingInfo = info
+    if #available(iOS 13.0, *) {
+      if isPlayingFlag {
+        MPNowPlayingInfoCenter.default().playbackState = .playing
+      } else if currentPositionMs > 0 {
+        MPNowPlayingInfoCenter.default().playbackState = .paused
+      } else {
+        MPNowPlayingInfoCenter.default().playbackState = .stopped
+      }
+    }
+    updateRemoteCommandStates()
   }
 
   private func emitPlaybackState(_ state: PlaybackState, positionMs: Double? = nil) {
@@ -1316,10 +1421,35 @@ final class NativeAudioEngine {
       }
       return .success
     }
+    changePlaybackPositionCommandTarget = commandCenter.changePlaybackPositionCommand.addTarget { [weak self] event in
+      guard let self = self,
+            let positionEvent = event as? MPChangePlaybackPositionCommandEvent else {
+        return .commandFailed
+      }
+      self.queue.async {
+        let targetMs = max(0.0, positionEvent.positionTime * 1000.0)
+        self.seekInternal(positionMs: targetMs)
+      }
+      return .success
+    }
+    skipForwardCommandTarget = commandCenter.skipForwardCommand.addTarget { [weak self] event in
+      guard let self = self else { return .commandFailed }
+      let seconds = (event as? MPSkipIntervalCommandEvent)?.interval ?? 15.0
+      self.queue.async {
+        self.seekByIntervalInternal(deltaMs: max(0.0, seconds) * 1000.0)
+      }
+      return .success
+    }
+    skipBackwardCommandTarget = commandCenter.skipBackwardCommand.addTarget { [weak self] event in
+      guard let self = self else { return .commandFailed }
+      let seconds = (event as? MPSkipIntervalCommandEvent)?.interval ?? 15.0
+      self.queue.async {
+        self.seekByIntervalInternal(deltaMs: -max(0.0, seconds) * 1000.0)
+      }
+      return .success
+    }
 
-    commandCenter.playCommand.isEnabled = true
-    commandCenter.pauseCommand.isEnabled = true
-    commandCenter.togglePlayPauseCommand.isEnabled = true
+    updateRemoteCommandStates()
   }
 
   /// Removes remote command handlers.
@@ -1334,9 +1464,61 @@ final class NativeAudioEngine {
     if let target = toggleCommandTarget {
       commandCenter.togglePlayPauseCommand.removeTarget(target)
     }
+    if let target = changePlaybackPositionCommandTarget {
+      commandCenter.changePlaybackPositionCommand.removeTarget(target)
+    }
+    if let target = skipForwardCommandTarget {
+      commandCenter.skipForwardCommand.removeTarget(target)
+    }
+    if let target = skipBackwardCommandTarget {
+      commandCenter.skipBackwardCommand.removeTarget(target)
+    }
     playCommandTarget = nil
     pauseCommandTarget = nil
     toggleCommandTarget = nil
+    changePlaybackPositionCommandTarget = nil
+    skipForwardCommandTarget = nil
+    skipBackwardCommandTarget = nil
+  }
+
+  private func updateRemoteCommandStates() {
+    let commandCenter = MPRemoteCommandCenter.shared()
+    let hasTracks = !tracks.isEmpty
+    let hasSeekableDuration = durationMs > 0
+    let seekStepSeconds = max(1.0, resolveSeekStepMs() / 1000.0)
+    commandCenter.playCommand.isEnabled = backgroundPlaybackEnabled && hasTracks && !isPlayingFlag
+    commandCenter.pauseCommand.isEnabled = backgroundPlaybackEnabled && hasTracks && isPlayingFlag
+    commandCenter.togglePlayPauseCommand.isEnabled = backgroundPlaybackEnabled && hasTracks
+    commandCenter.changePlaybackPositionCommand.isEnabled = backgroundPlaybackEnabled && hasTracks && hasSeekableDuration
+    commandCenter.skipForwardCommand.preferredIntervals = [NSNumber(value: seekStepSeconds)]
+    commandCenter.skipBackwardCommand.preferredIntervals = [NSNumber(value: seekStepSeconds)]
+    commandCenter.skipForwardCommand.isEnabled = backgroundPlaybackEnabled && hasTracks && hasSeekableDuration
+    commandCenter.skipBackwardCommand.isEnabled = backgroundPlaybackEnabled && hasTracks && hasSeekableDuration
+  }
+
+  private func resolveSeekStepMs() -> Double {
+    guard let playbackCard = nowPlayingMetadata["playbackCard"] as? [String: Any] else {
+      return 15000.0
+    }
+    if let seekStepMs = playbackCard["seekStepMs"] as? NSNumber {
+      return max(1000.0, seekStepMs.doubleValue)
+    }
+    return 15000.0
+  }
+
+  private func setRemoteControlEventsEnabled(_ enabled: Bool) {
+    let handler = {
+      if enabled {
+        UIApplication.shared.beginReceivingRemoteControlEvents()
+      } else {
+        UIApplication.shared.endReceivingRemoteControlEvents()
+      }
+    }
+    if Thread.isMainThread {
+      handler()
+    } else {
+      DispatchQueue.main.async(execute: handler)
+    }
   }
 
   /// Resolves artwork from a local file path or file URL.

package/ios/ExpoAudioEngineModule.swift

@@ -1,5 +1,36 @@
 import ExpoModulesCore
 
+struct AudioEngineError: CodedError, CustomNSError {
+  let code: String
+  let description: String
+  let details: [String: Any]?
+
+  init(_ code: String, _ description: String, details: [String: Any]? = nil) {
+    self.code = code
+    self.description = description
+    self.details = details
+  }
+
+  static var errorDomain: String {
+    return "ExpoAudioEngine"
+  }
+
+  var errorCode: Int {
+    return 0
+  }
+
+  var errorUserInfo: [String: Any] {
+    var info: [String: Any] = [
+      NSLocalizedDescriptionKey: description,
+      "code": code
+    ]
+    if let details = details {
+      info["details"] = details
+    }
+    return info
+  }
+}
+
 public class ExpoAudioEngineModule: Module {
   private let engine = NativeAudioEngine()
 
@@ -29,10 +60,23 @@ 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)
+        }
+      }
     }
     OnDestroy {
       engine.onPlaybackStateChange = nil
       engine.onPlaybackComplete = nil
+      engine.onError = nil
     }
 
     AsyncFunction("initialize") { (config: [String: Any]) in
@@ -41,8 +85,14 @@ public class ExpoAudioEngineModule: Module {
     AsyncFunction("release") {
       engine.releaseResources()
     }
-    AsyncFunction("loadTracks") { (tracks: [[String: Any]]) in
-      engine.loadTracks(tracks)
+    AsyncFunction("loadTracks") { (tracks: [[String: Any]]) throws in
+      if let failure = engine.loadTracks(tracks) {
+        let failedCount = failure["failedCount"] as? Int ?? 0
+        let message = failedCount > 0
+          ? "Failed to load \(failedCount) track(s)."
+          : "Failed to load tracks."
+        throw AudioEngineError("TRACK_LOAD_FAILED", message, details: failure)
+      }
     }
     AsyncFunction("unloadTrack") { (trackId: String) in
       engine.unloadTrack(trackId)
@@ -147,12 +197,12 @@ public class ExpoAudioEngineModule: Module {
       engine.setRecordingVolume(volume)
     }
 
-    AsyncFunction("extractTrack") { (trackId: String, config: [String: Any]?) in
-      return engine.extractTrack(trackId: trackId, config: config)
+    AsyncFunction("extractTrack") { (trackId: String, config: [String: Any]?) throws in
+      return try engine.extractTrack(trackId: trackId, config: config)
     }
 
-    AsyncFunction("extractAllTracks") { (config: [String: Any]?) in
-      return engine.extractAllTracks(config: config)
+    AsyncFunction("extractAllTracks") { (config: [String: Any]?) throws in
+      return try engine.extractAllTracks(config: config)
     }
 
     Function("cancelExtraction") { (jobId: Double?) in

package/package.json

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