sezo-audio-engine 0.0.3 → 0.0.5

package/README.md

@@ -22,6 +22,28 @@ Android recording:
 <uses-permission android:name="android.permission.RECORD_AUDIO" />
 ```
 
+## Android Engine Dependency
+
+The Expo module links to the Android engine from JitPack by default. Add the JitPack repository to your app:
+
+```gradle
+// android/build.gradle
+allprojects {
+  repositories {
+    maven { url "https://www.jitpack.io" }
+  }
+}
+```
+
+Optionally pin the engine version in `android/gradle.properties`:
+
+```properties
+sezoAudioEngineVersion=android-engine-v0.1.3
+```
+
+If you want to build from source instead, include the local engine module in
+`android/settings.gradle` and it will be picked up automatically.
+
 iOS recording or background playback:
 
 ```json

package/android/build.gradle

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

package/ios/AudioEngine/AudioSessionManager.swift

@@ -2,8 +2,11 @@ import AVFoundation
 
 final class AudioSessionManager {
   private let session = AVAudioSession.sharedInstance()
+  private var lastError: String?
 
-  func configure(with config: AudioEngineConfig) {
+  @discardableResult
+  func configure(with config: AudioEngineConfig) -> Bool {
+    lastError = nil
     do {
       try session.setCategory(
         .playAndRecord,
@@ -11,25 +14,42 @@ final class AudioSessionManager {
         options: [.defaultToSpeaker, .allowBluetooth]
       )
     } catch {
-      return
+      lastError = "setCategory failed: \(error.localizedDescription)"
+      return false
     }
 
     if let sampleRate = config.sampleRate {
-      try? session.setPreferredSampleRate(sampleRate)
+      do {
+        try session.setPreferredSampleRate(sampleRate)
+      } catch {
+        lastError = "setPreferredSampleRate failed: \(error.localizedDescription)"
+      }
     }
 
     if let bufferSize = config.bufferSize {
       let sampleRate = config.sampleRate ?? session.sampleRate
       if sampleRate > 0 {
         let duration = bufferSize / sampleRate
-        try? session.setPreferredIOBufferDuration(duration)
+        do {
+          try session.setPreferredIOBufferDuration(duration)
+        } catch {
+          lastError = "setPreferredIOBufferDuration failed: \(error.localizedDescription)"
+        }
       }
     }
 
-    try? session.setActive(true)
+    do {
+      try session.setActive(true)
+    } catch {
+      lastError = "setActive failed: \(error.localizedDescription)"
+      return false
+    }
+    return true
   }
 
-  func enableBackgroundPlayback(with config: AudioEngineConfig) {
+  @discardableResult
+  func enableBackgroundPlayback(with config: AudioEngineConfig) -> Bool {
+    lastError = nil
     do {
       try session.setCategory(
         .playback,
@@ -37,22 +57,41 @@ final class AudioSessionManager {
         options: [.allowBluetooth, .allowAirPlay]
       )
     } catch {
-      return
+      lastError = "setCategory failed: \(error.localizedDescription)"
+      return false
     }
 
     if let sampleRate = config.sampleRate {
-      try? session.setPreferredSampleRate(sampleRate)
+      do {
+        try session.setPreferredSampleRate(sampleRate)
+      } catch {
+        lastError = "setPreferredSampleRate failed: \(error.localizedDescription)"
+      }
     }
 
     if let bufferSize = config.bufferSize {
       let sampleRate = config.sampleRate ?? session.sampleRate
       if sampleRate > 0 {
         let duration = bufferSize / sampleRate
-        try? session.setPreferredIOBufferDuration(duration)
+        do {
+          try session.setPreferredIOBufferDuration(duration)
+        } catch {
+          lastError = "setPreferredIOBufferDuration failed: \(error.localizedDescription)"
+        }
       }
     }
 
-    try? session.setActive(true)
+    do {
+      try session.setActive(true)
+    } catch {
+      lastError = "setActive failed: \(error.localizedDescription)"
+      return false
+    }
+    return true
+  }
+
+  func lastErrorDescription() -> String? {
+    return lastError
   }
 
   func deactivate() {

package/ios/AudioEngine/NativeAudioEngine.swift

@@ -30,6 +30,11 @@ final class NativeAudioEngine {
   private var activePlaybackCount = 0
   private var playbackToken = UUID()
   private var recordingState: RecordingState?
+  private var lastRecordingError: String?
+  private var lastEngineError: String?
+  private let recordingMixer = AVAudioMixerNode()
+  private var recordingMixerConnected = false
+  private var recordingTapInstalled = false
   private var inputLevel: Double = 0.0
   private var backgroundPlaybackEnabled = false
   private var nowPlayingMetadata: [String: Any] = [:]
@@ -53,7 +58,11 @@ final class NativeAudioEngine {
     let parsedConfig = AudioEngineConfig(dictionary: config)
     queue.sync {
       lastConfig = parsedConfig
-      sessionManager.configure(with: parsedConfig)
+      _ = sessionManager.configure(with: parsedConfig)
+      _ = ensureRecordingMixerConnected(
+        sampleRate: AVAudioSession.sharedInstance().sampleRate,
+        channels: AVAudioSession.sharedInstance().inputNumberOfChannels
+      )
       engine.mainMixerNode.outputVolume = Float(masterVolume)
       engine.prepare()
       isInitialized = true
@@ -68,6 +77,7 @@ final class NativeAudioEngine {
       stopRecordingInternal()
       detachAllTracks()
       tracks.removeAll()
+      detachRecordingMixer()
       isPlayingFlag = false
       isRecordingFlag = false
       currentPositionMs = 0.0
@@ -290,16 +300,51 @@ final class NativeAudioEngine {
   }
 
   /// Starts recording from the input node into AAC or WAV.
-  func startRecording(config: [String: Any]?) {
-    queue.sync {
-      guard !isRecordingFlag else { return }
+  @discardableResult
+  func startRecording(config: [String: Any]?) -> Bool {
+    return queue.sync {
+      guard !isRecordingFlag else { return true }
+      lastRecordingError = nil
+      let session = AVAudioSession.sharedInstance()
+      let permission = session.recordPermission
+      if permission != .granted {
+        if permission == .undetermined {
+          requestRecordPermission()
+          lastRecordingError = "microphone permission not determined"
+        } else {
+          lastRecordingError = "microphone permission denied"
+        }
+        return false
+      }
+      if !sessionManager.configure(with: lastConfig) {
+        lastRecordingError = sessionManager.lastErrorDescription() ?? "audio session configuration failed"
+        return false
+      }
+      if !session.isInputAvailable {
+        let routeInfo = describeRoute(session)
+        lastRecordingError = "audio input not available (category=\(session.category.rawValue), route=\(routeInfo))"
+        return false
+      }
       ensureInitializedIfNeeded()
 
-      let inputNode = engine.inputNode
-      let inputFormat = inputNode.outputFormat(forBus: 0)
+      guard startEngineIfNeeded() else {
+        lastRecordingError = lastEngineError ?? "audio engine failed to start"
+        return false
+      }
+
+      let sampleRate = session.sampleRate
+      let channels = max(1, session.inputNumberOfChannels)
+      if !ensureRecordingMixerConnected(sampleRate: sampleRate, channels: channels) {
+        return false
+      }
+
+      let tapFormat = recordingMixer.outputFormat(forBus: 0)
+      guard tapFormat.sampleRate > 0, tapFormat.channelCount > 0 else {
+        let routeInfo = describeRoute(session)
+        lastRecordingError = "input format invalid (sampleRate=\(tapFormat.sampleRate), channels=\(tapFormat.channelCount), sessionRate=\(session.sampleRate), sessionChannels=\(session.inputNumberOfChannels), route=\(routeInfo))"
+        return false
+      }
       let requestedFormat = config?["format"] as? String ?? "aac"
-      let channels = config?["channels"] as? Int ?? Int(inputFormat.channelCount)
-      let sampleRate = config?["sampleRate"] as? Double ?? inputFormat.sampleRate
       let bitrate = resolveBitrate(config: config)
       let formatInfo = resolveRecordingFormat(requestedFormat: requestedFormat)
       let outputURL = resolveOutputURL(
@@ -339,33 +384,28 @@ final class NativeAudioEngine {
           startTimeMs: startTimeMs
         )
 
-        guard startEngineIfNeeded() else {
-          recordingState = nil
-          return
-        }
-
-        inputNode.removeTap(onBus: 0)
-        inputNode.installTap(onBus: 0, bufferSize: 1024, format: inputFormat) { [weak self] buffer, _ in
-          guard let self = self else { return }
-          self.queue.async {
-            guard let state = self.recordingState else { return }
-            self.applyRecordingGain(buffer: buffer)
-            self.updateInputLevel(buffer: buffer)
-            do {
-              try state.file.write(from: buffer)
-            } catch {
-              return
-            }
-          }
-        }
-
         isRecordingFlag = true
+        return true
       } catch {
+        lastRecordingError = "recording setup failed: \(error.localizedDescription)"
         recordingState = nil
+        return false
       }
     }
   }
 
+  private func requestRecordPermission() {
+    let session = AVAudioSession.sharedInstance()
+    let requestBlock = {
+      session.requestRecordPermission { _ in }
+    }
+    if Thread.isMainThread {
+      requestBlock()
+    } else {
+      DispatchQueue.main.async(execute: requestBlock)
+    }
+  }
+
   /// Stops recording and returns metadata about the output file.
   func stopRecording() -> [String: Any] {
     return queue.sync {
@@ -411,6 +451,10 @@ final class NativeAudioEngine {
     }
   }
 
+  func getLastRecordingError() -> String? {
+    return queue.sync { lastRecordingError }
+  }
+
   /// Offline export for a single track.
   func extractTrack(trackId: String, config: [String: Any]?) -> [String: Any] {
     return queue.sync {
@@ -479,7 +523,7 @@ final class NativeAudioEngine {
     queue.sync {
       backgroundPlaybackEnabled = true
       nowPlayingMetadata.merge(metadata) { _, new in new }
-      sessionManager.enableBackgroundPlayback(with: lastConfig)
+      _ = sessionManager.enableBackgroundPlayback(with: lastConfig)
       configureRemoteCommandsIfNeeded()
       updateNowPlayingInfoInternal()
     }
@@ -500,7 +544,7 @@ final class NativeAudioEngine {
       nowPlayingMetadata.removeAll()
       removeRemoteCommands()
       MPNowPlayingInfoCenter.default().nowPlayingInfo = nil
-      sessionManager.configure(with: lastConfig)
+      _ = sessionManager.configure(with: lastConfig)
     }
   }
 
@@ -519,10 +563,14 @@ final class NativeAudioEngine {
     }
     let config = lastConfig
     if backgroundPlaybackEnabled {
-      sessionManager.enableBackgroundPlayback(with: config)
+      _ = sessionManager.enableBackgroundPlayback(with: config)
     } else {
-      sessionManager.configure(with: config)
+      _ = sessionManager.configure(with: config)
     }
+    _ = ensureRecordingMixerConnected(
+      sampleRate: AVAudioSession.sharedInstance().sampleRate,
+      channels: AVAudioSession.sharedInstance().inputNumberOfChannels
+    )
     engine.mainMixerNode.outputVolume = Float(masterVolume)
     engine.prepare()
     isInitialized = true
@@ -668,11 +716,67 @@ final class NativeAudioEngine {
 
   /// Stops the input tap and clears recording state.
   private func stopRecordingInternal() {
-    engine.inputNode.removeTap(onBus: 0)
     recordingState = nil
     isRecordingFlag = false
   }
 
+  private func ensureRecordingMixerConnected(sampleRate: Double, channels: Int) -> Bool {
+    if recordingMixerConnected {
+      return true
+    }
+    if engine.isRunning {
+      lastRecordingError = "recording mixer unavailable while engine is running"
+      return false
+    }
+
+    let resolvedRate = sampleRate > 0 ? sampleRate : (lastConfig.sampleRate ?? 44100)
+    let resolvedChannels = channels > 0 ? channels : 1
+    guard let format = AVAudioFormat(
+      standardFormatWithSampleRate: resolvedRate,
+      channels: AVAudioChannelCount(resolvedChannels)
+    ) else {
+      lastRecordingError = "recording format invalid (sampleRate=\(resolvedRate), channels=\(resolvedChannels))"
+      return false
+    }
+
+    engine.attach(recordingMixer)
+    engine.connect(engine.inputNode, to: recordingMixer, format: format)
+    engine.connect(recordingMixer, to: engine.mainMixerNode, format: format)
+    recordingMixer.volume = 0.0
+    if !recordingTapInstalled {
+      recordingMixer.installTap(onBus: 0, bufferSize: 1024, format: format) { [weak self] buffer, _ in
+        guard let self = self else { return }
+        self.queue.async {
+          guard let state = self.recordingState else { return }
+          self.applyRecordingGain(buffer: buffer)
+          self.updateInputLevel(buffer: buffer)
+          do {
+            try state.file.write(from: buffer)
+          } catch {
+            return
+          }
+        }
+      }
+      recordingTapInstalled = true
+    }
+    recordingMixerConnected = true
+    return true
+  }
+
+  private func detachRecordingMixer() {
+    if !recordingMixerConnected {
+      return
+    }
+    if recordingTapInstalled {
+      recordingMixer.removeTap(onBus: 0)
+      recordingTapInstalled = false
+    }
+    engine.disconnectNodeInput(recordingMixer)
+    engine.disconnectNodeOutput(recordingMixer)
+    engine.detach(recordingMixer)
+    recordingMixerConnected = false
+  }
+
   /// Maps requested output formats to supported formats.
   private func resolveRecordingFormat(requestedFormat: String) -> (format: String, fileExtension: String) {
     if requestedFormat == "wav" {
@@ -717,6 +821,19 @@ final class NativeAudioEngine {
     return baseURL.appendingPathComponent(filename)
   }
 
+  private func selectPreferredInput(_ session: AVAudioSession) {
+    guard let inputs = session.availableInputs, !inputs.isEmpty else { return }
+    if let builtIn = inputs.first(where: { $0.portType == .builtInMic }) {
+      try? session.setPreferredInput(builtIn)
+    }
+  }
+
+  private func describeRoute(_ session: AVAudioSession) -> String {
+    let inputs = session.currentRoute.inputs.map { "\($0.portType.rawValue):\($0.portName)" }
+    let outputs = session.currentRoute.outputs.map { "\($0.portType.rawValue):\($0.portName)" }
+    return "inputs[\(inputs.joined(separator: ","))], outputs[\(outputs.joined(separator: ","))]"
+  }
+
   /// Returns file size for output metadata.
   private func resolveFileSize(url: URL) -> Int {
     let path = url.path
@@ -981,12 +1098,15 @@ final class NativeAudioEngine {
   @discardableResult
   private func startEngineIfNeeded() -> Bool {
     if !isInitialized {
+      lastEngineError = "audio engine not initialized"
       return false
     }
     if !engine.isRunning {
       do {
         try engine.start()
+        lastEngineError = nil
       } catch {
+        lastEngineError = error.localizedDescription
         return false
       }
     }

package/ios/ExpoAudioEngineModule.swift

@@ -95,8 +95,18 @@ public class ExpoAudioEngineModule: Module {
       engine.setTempoAndPitch(tempo: tempo, pitch: pitch)
     }
 
-    AsyncFunction("startRecording") { (config: [String: Any]?) in
-      engine.startRecording(config: config)
+    AsyncFunction("startRecording") { (config: [String: Any]?) throws in
+      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)."
+          ]
+        )
+      }
     }
     AsyncFunction("stopRecording") {
       return engine.stopRecording()

package/package.json

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