@clarionhq/recorder 0.0.1 → 0.1.0

package/ios/HybridClarionRecorder.swift

@@ -0,0 +1,186 @@
+import Foundation
+import NitroModules
+
+public typealias StateClosure = (String) -> Void
+public typealias AudioLevelClosure = (Double, Double) -> Void
+public typealias ChunkClosure = (String, Double, Double, Double) -> Void
+public typealias ErrorClosure = (NativeRecorderError) -> Void
+
+public final class HybridClarionRecorder: HybridClarionRecorderSpec {
+  private var session: RecorderSession?
+  private var currentStateValue: String = "idle"
+
+  private var nextListenerId: Int = 1
+  private var stateListeners: [Int: StateClosure] = [:]
+  private var audioLevelListeners: [Int: AudioLevelClosure] = [:]
+  private var chunkListeners: [Int: ChunkClosure] = [:]
+  private var errorListeners: [Int: ErrorClosure] = [:]
+
+  private let listenerLock = NSLock()
+
+  public var state: String { currentStateValue }
+
+  public func prepare(config: NativeRecorderConfig) throws -> Promise<Void> {
+    return Promise.async { [weak self] in
+      guard let self else { return }
+      let parsed = config.toSwiftConfig()
+      let newSession = RecorderSession(config: parsed, callbacks: self)
+      self.emit(state: "preparing")
+      try await newSession.prepare()
+      self.session = newSession
+      self.emit(state: "ready")
+    }
+  }
+
+  public func start() throws -> Promise<Void> {
+    return Promise.async { [weak self] in
+      guard let self else { return }
+      guard let session = self.session else {
+        throw RecorderError(code: "ENGINE_NOT_READY", message: "Call prepare() first")
+      }
+      self.emit(state: "starting")
+      try session.start()
+    }
+  }
+
+  public func pause() throws -> Promise<Void> {
+    return Promise.async { [weak self] in
+      try self?.session?.pause()
+    }
+  }
+
+  public func resume() throws -> Promise<Void> {
+    return Promise.async { [weak self] in
+      try self?.session?.resume()
+    }
+  }
+
+  public func stop() throws -> Promise<NativeRecorderResult> {
+    return Promise.async { [weak self] in
+      guard let self, let session = self.session else {
+        throw RecorderError(code: "ENGINE_NOT_READY", message: "No session")
+      }
+      let output = try await session.stop()
+      return output.toNative()
+    }
+  }
+
+  public func discard() throws -> Promise<Void> {
+    return Promise.async { [weak self] in
+      await self?.session?.discard()
+    }
+  }
+
+  public func release() throws -> Promise<Void> {
+    return Promise.async { [weak self] in
+      guard let self else { return }
+      await self.session?.release()
+      self.session = nil
+      self.removeAllListeners()
+    }
+  }
+
+  public func addStateListener(listener: @escaping StateClosure) throws -> Double {
+    register { id in stateListeners[id] = listener }
+  }
+
+  public func addAudioLevelListener(listener: @escaping AudioLevelClosure) throws -> Double {
+    register { id in audioLevelListeners[id] = listener }
+  }
+
+  public func addChunkListener(listener: @escaping ChunkClosure) throws -> Double {
+    register { id in chunkListeners[id] = listener }
+  }
+
+  public func addErrorListener(listener: @escaping ErrorClosure) throws -> Double {
+    register { id in errorListeners[id] = listener }
+  }
+
+  public func removeListener(id: Double) throws {
+    listenerLock.lock(); defer { listenerLock.unlock() }
+    let key = Int(id)
+    stateListeners.removeValue(forKey: key)
+    audioLevelListeners.removeValue(forKey: key)
+    chunkListeners.removeValue(forKey: key)
+    errorListeners.removeValue(forKey: key)
+  }
+
+  public func removeAllListeners() {
+    listenerLock.lock(); defer { listenerLock.unlock() }
+    stateListeners.removeAll()
+    audioLevelListeners.removeAll()
+    chunkListeners.removeAll()
+    errorListeners.removeAll()
+  }
+
+  private func register(_ assign: (Int) -> Void) -> Double {
+    listenerLock.lock(); defer { listenerLock.unlock() }
+    let id = nextListenerId
+    nextListenerId += 1
+    assign(id)
+    return Double(id)
+  }
+
+  private func emit(state: String) {
+    currentStateValue = state
+    snapshotListeners(stateListeners).forEach { $0(state) }
+  }
+
+  private func snapshotListeners<T>(_ map: [Int: T]) -> [T] {
+    listenerLock.lock(); defer { listenerLock.unlock() }
+    return Array(map.values)
+  }
+}
+
+extension HybridClarionRecorder: RecorderCallbacks {
+  func onState(_ state: String) {
+    emit(state: state)
+  }
+
+  func onAudioLevel(rms: Double, peak: Double) {
+    snapshotListeners(audioLevelListeners).forEach { $0(rms, peak) }
+  }
+
+  func onChunk(uri: String, startMs: Double, endMs: Double, sizeBytes: Double) {
+    snapshotListeners(chunkListeners).forEach { $0(uri, startMs, endMs, sizeBytes) }
+  }
+
+  func onError(_ error: RecorderError) {
+    currentStateValue = "error"
+    let payload = NativeRecorderError(
+      code: error.code,
+      message: error.message,
+      recoverable: error.recoverable
+    )
+    snapshotListeners(errorListeners).forEach { $0(payload) }
+  }
+}
+
+private extension NativeRecorderConfig {
+  func toSwiftConfig() -> RecorderConfig {
+    return RecorderConfig(
+      sampleRate: sampleRate,
+      channels: UInt32(channels),
+      bitDepth: UInt32(bitDepth),
+      outputDirectory: outputDirectory,
+      filenamePrefix: filenamePrefix,
+      rotateAfterMs: rotateAfterMs,
+      emitAudioLevel: emitAudioLevel,
+      audioLevelIntervalMs: audioLevelIntervalMs,
+      aacBitrate: Int(aacBitrate)
+    )
+  }
+}
+
+private extension RecorderOutput {
+  func toNative() -> NativeRecorderResult {
+    return NativeRecorderResult(
+      uri: uri,
+      durationMs: durationMs,
+      sizeBytes: sizeBytes,
+      sampleRate: sampleRate,
+      channels: Double(channels),
+      bitDepth: Double(bitDepth)
+    )
+  }
+}

package/ios/RecorderConstants.swift

@@ -0,0 +1,11 @@
+import Foundation
+
+internal enum RecorderConstants {
+  static let defaultCacheSubdir = "clarion-recorder"
+  static let defaultFilenamePrefix = "clarion"
+  static let outputExtension = "m4a"
+  static let uriScheme = "file://"
+  static let captureBufferFractionOfSecond: UInt32 = 5
+  static let writeQueueLabel = "dev.clarionhq.recorder.write"
+  static let captureQueueLabel = "dev.clarionhq.recorder.capture"
+}

package/ios/RecorderSession.swift

@@ -0,0 +1,278 @@
+import AVFoundation
+import Foundation
+
+internal final class RecorderSession {
+  private let config: RecorderConfig
+  private weak var callbacks: RecorderCallbacks?
+
+  private let audioEngine = AVAudioEngine()
+  private var converter: AVAudioConverter?
+  private var targetFormat: AVAudioFormat?
+
+  private var encodeFile: EncodeFile?
+  private let writeQueue = DispatchQueue(label: RecorderConstants.writeQueueLabel)
+
+  private var running = false
+  private var paused = false
+
+  private var sessionStartHostTime: UInt64 = 0
+  private var sessionStartWallMs: Double = 0
+  private var fileStartedAtMs: Double = 0
+  private var lastLevelEmitMs: Double = 0
+  private var totalBytesWritten: Int64 = 0
+
+  init(config: RecorderConfig, callbacks: RecorderCallbacks) {
+    self.config = config
+    self.callbacks = callbacks
+  }
+
+  func prepare() async throws {
+    try await ensurePermission()
+    try configureAudioSession()
+
+    let inputNode = audioEngine.inputNode
+    let inputFormat = inputNode.outputFormat(forBus: 0)
+    let target = try makeTargetFormat()
+    targetFormat = target
+
+    if inputFormat.sampleRate != target.sampleRate
+      || inputFormat.channelCount != target.channelCount {
+      converter = AVAudioConverter(from: inputFormat, to: target)
+    }
+  }
+
+  func start() throws {
+    guard let target = targetFormat else {
+      throw RecorderError(code: "ENGINE_NOT_READY", message: "Call prepare() first")
+    }
+
+    let directory = resolveOutputDirectory()
+    encodeFile = try EncodeFile.open(
+      in: directory,
+      filenamePrefix: config.filenamePrefix ?? RecorderConstants.defaultFilenamePrefix,
+      sampleRate: target.sampleRate,
+      channels: target.channelCount,
+      aacBitrate: config.aacBitrate
+    )
+
+    totalBytesWritten = 0
+    sessionStartHostTime = mach_absolute_time()
+    sessionStartWallMs = nowMs()
+    fileStartedAtMs = sessionStartWallMs
+
+    installTap()
+    try audioEngine.start()
+
+    running = true
+    paused = false
+    callbacks?.onState("recording")
+  }
+
+  func pause() throws {
+    guard running else { throw RecorderError(code: "INVALID_STATE", message: "Not recording") }
+    paused = true
+    callbacks?.onState("paused")
+  }
+
+  func resume() throws {
+    guard running else { throw RecorderError(code: "INVALID_STATE", message: "Not recording") }
+    paused = false
+    callbacks?.onState("recording")
+  }
+
+  func stop() async throws -> RecorderOutput {
+    guard running else { throw RecorderError(code: "INVALID_STATE", message: "Not recording") }
+    callbacks?.onState("stopping")
+
+    running = false
+    audioEngine.inputNode.removeTap(onBus: 0)
+    audioEngine.stop()
+
+    // Drain any frames still queued on the write queue before closing the file.
+    writeQueue.sync { }
+
+    guard let file = encodeFile else {
+      throw RecorderError(code: "INTERNAL_ERROR", message: "No output file")
+    }
+    file.close()
+    let durationMs = nowMs() - sessionStartWallMs
+    encodeFile = nil
+
+    callbacks?.onState("idle")
+    return RecorderOutput(
+      uri: "\(RecorderConstants.uriScheme)\(file.url.path)",
+      durationMs: durationMs,
+      sizeBytes: Double(totalBytesWritten),
+      sampleRate: config.sampleRate,
+      channels: config.channels,
+      bitDepth: config.bitDepth
+    )
+  }
+
+  func discard() async {
+    running = false
+    audioEngine.inputNode.removeTap(onBus: 0)
+    audioEngine.stop()
+    encodeFile?.cancel()
+    encodeFile = nil
+    callbacks?.onState("idle")
+  }
+
+  func release() async {
+    if running { await discard() }
+    try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+    callbacks?.onState("released")
+  }
+
+  private func installTap() {
+    let inputNode = audioEngine.inputNode
+    let inputFormat = inputNode.outputFormat(forBus: 0)
+    let bufferSize = AVAudioFrameCount(inputFormat.sampleRate / Double(RecorderConstants.captureBufferFractionOfSecond))
+
+    inputNode.installTap(onBus: 0, bufferSize: bufferSize, format: inputFormat) { [weak self] buffer, _ in
+      guard let self else { return }
+      self.handle(inputBuffer: buffer)
+    }
+  }
+
+  private func handle(inputBuffer: AVAudioPCMBuffer) {
+    guard running, !paused, let file = encodeFile else { return }
+    if config.emitAudioLevel { maybeEmitLevels(inputBuffer) }
+
+    guard let converted = convert(inputBuffer) else { return }
+
+    writeQueue.async { [weak self] in
+      guard let self else { return }
+      self.maybeRotate(currentFile: file)
+      self.append(converted, to: self.encodeFile)
+    }
+  }
+
+  private func convert(_ buffer: AVAudioPCMBuffer) -> AVAudioPCMBuffer? {
+    guard let target = targetFormat else { return nil }
+    guard let converter else { return buffer }
+
+    let ratio = target.sampleRate / buffer.format.sampleRate
+    let outFrames = AVAudioFrameCount(Double(buffer.frameLength) * ratio + 1)
+    guard let outBuffer = AVAudioPCMBuffer(pcmFormat: target, frameCapacity: outFrames) else {
+      return nil
+    }
+
+    var error: NSError?
+    var consumed = false
+    converter.convert(to: outBuffer, error: &error) { _, status in
+      if consumed {
+        status.pointee = .noDataNow
+        return nil
+      }
+      consumed = true
+      status.pointee = .haveData
+      return buffer
+    }
+    if error != nil { return nil }
+    return outBuffer
+  }
+
+  private func append(_ buffer: AVAudioPCMBuffer, to file: EncodeFile?) {
+    guard let file else { return }
+    do {
+      try file.write(buffer: buffer)
+      totalBytesWritten = file.bytesWritten
+    } catch {
+      callbacks?.onError(RecorderError(code: "IO_ERROR", message: error.localizedDescription))
+    }
+  }
+
+  private func maybeRotate(currentFile: EncodeFile) {
+    guard let rotateAfterMs = config.rotateAfterMs else { return }
+    let nowWall = nowMs()
+    if nowWall - fileStartedAtMs < rotateAfterMs { return }
+
+    currentFile.close()
+    callbacks?.onChunk(
+      uri: "\(RecorderConstants.uriScheme)\(currentFile.url.path)",
+      startMs: fileStartedAtMs,
+      endMs: nowWall,
+      sizeBytes: Double(currentFile.bytesWritten)
+    )
+    openNextFile(startedAtMs: nowWall)
+  }
+
+  private func openNextFile(startedAtMs: Double) {
+    do {
+      let directory = resolveOutputDirectory()
+      let next = try EncodeFile.open(
+        in: directory,
+        filenamePrefix: config.filenamePrefix ?? RecorderConstants.defaultFilenamePrefix,
+        sampleRate: config.sampleRate,
+        channels: config.channels,
+        aacBitrate: config.aacBitrate
+      )
+      encodeFile = next
+      fileStartedAtMs = startedAtMs
+    } catch let err as RecorderError {
+      callbacks?.onError(err)
+    } catch {
+      callbacks?.onError(RecorderError(code: "IO_ERROR", message: error.localizedDescription))
+    }
+  }
+
+  private func maybeEmitLevels(_ buffer: AVAudioPCMBuffer) {
+    let now = nowMs()
+    if now - lastLevelEmitMs < config.audioLevelIntervalMs { return }
+    lastLevelEmitMs = now
+    let levels = AudioLevelMeter.compute(buffer: buffer)
+    callbacks?.onAudioLevel(rms: levels.rms, peak: levels.peak)
+  }
+
+  private func makeTargetFormat() throws -> AVAudioFormat {
+    // AAC encoder requires interleaved int16 PCM input; float32 yields
+    // AudioCodecInitialize failed / err=-12651 (kAudioConverterErr_FormatNotSupported).
+    guard let fmt = AVAudioFormat(
+      commonFormat: .pcmFormatInt16,
+      sampleRate: config.sampleRate,
+      channels: AVAudioChannelCount(config.channels),
+      interleaved: true
+    ) else {
+      throw RecorderError(code: "UNSUPPORTED_FORMAT", message: "Invalid target format")
+    }
+    return fmt
+  }
+
+  private func resolveOutputDirectory() -> URL {
+    if let custom = config.outputDirectory {
+      return URL(fileURLWithPath: custom, isDirectory: true)
+    }
+    let cache = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
+    return cache.appendingPathComponent(RecorderConstants.defaultCacheSubdir, isDirectory: true)
+  }
+
+  private func configureAudioSession() throws {
+    let session = AVAudioSession.sharedInstance()
+    try session.setCategory(.playAndRecord, mode: .default, options: [.defaultToSpeaker, .allowBluetooth])
+    try session.setActive(true, options: .notifyOthersOnDeactivation)
+  }
+
+  private func ensurePermission() async throws {
+    let session = AVAudioSession.sharedInstance()
+    switch session.recordPermission {
+    case .granted:
+      return
+    case .denied:
+      throw RecorderError(code: "PERMISSION_DENIED", message: "Microphone permission denied")
+    default:
+      // Undetermined — prompt the user. iOS uses NSMicrophoneUsageDescription
+      // from Info.plist as the prompt copy.
+      let granted = await withCheckedContinuation { (cont: CheckedContinuation<Bool, Never>) in
+        session.requestRecordPermission { cont.resume(returning: $0) }
+      }
+      if !granted {
+        throw RecorderError(code: "PERMISSION_DENIED", message: "Microphone permission denied")
+      }
+    }
+  }
+
+  private func nowMs() -> Double {
+    return Date().timeIntervalSince1970 * 1_000
+  }
+}

package/ios/RecorderTypes.swift

@@ -0,0 +1,41 @@
+import Foundation
+
+internal struct RecorderError: Error {
+  let code: String
+  let message: String
+  let recoverable: Bool
+
+  init(code: String, message: String, recoverable: Bool = false) {
+    self.code = code
+    self.message = message
+    self.recoverable = recoverable
+  }
+}
+
+internal struct RecorderConfig {
+  let sampleRate: Double
+  let channels: UInt32
+  let bitDepth: UInt32
+  let outputDirectory: String?
+  let filenamePrefix: String?
+  let rotateAfterMs: Double?
+  let emitAudioLevel: Bool
+  let audioLevelIntervalMs: Double
+  let aacBitrate: Int
+}
+
+internal struct RecorderOutput {
+  let uri: String
+  let durationMs: Double
+  let sizeBytes: Double
+  let sampleRate: Double
+  let channels: UInt32
+  let bitDepth: UInt32
+}
+
+internal protocol RecorderCallbacks: AnyObject {
+  func onState(_ state: String)
+  func onAudioLevel(rms: Double, peak: Double)
+  func onChunk(uri: String, startMs: Double, endMs: Double, sizeBytes: Double)
+  func onError(_ error: RecorderError)
+}

package/lib/RecorderEngine.d.ts

@@ -0,0 +1,31 @@
+import { type ClarionEngine, type ClarionEvent, type EngineKind, type EngineState, type Listener, type RecorderEngineConfig, type Unsubscribe } from '@clarionhq/core';
+export interface RecorderEngineOptions extends RecorderEngineConfig {
+    aacBitrate?: number;
+}
+export declare class RecorderEngine implements ClarionEngine {
+    readonly kind: EngineKind;
+    private readonly emitter;
+    private readonly native;
+    private readonly listenerIds;
+    private readonly options;
+    private currentState;
+    constructor(options?: RecorderEngineOptions);
+    get state(): EngineState;
+    on(listener: Listener<ClarionEvent>): Unsubscribe;
+    prepare(): Promise<void>;
+    start(): Promise<void>;
+    pause(): Promise<void>;
+    resume(): Promise<void>;
+    stop(): Promise<void>;
+    discard(): Promise<void>;
+    release(): Promise<void>;
+    private buildNativeConfig;
+    private bindNativeListeners;
+    private transitionTo;
+    private setState;
+    private toRecorderResult;
+    private toClarionError;
+    private mapErrorCode;
+    private handleNativeError;
+}
+//# sourceMappingURL=RecorderEngine.d.ts.map

package/lib/RecorderEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RecorderEngine.d.ts","sourceRoot":"","sources":["../src/RecorderEngine.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,UAAU,EACf,KAAK,WAAW,EAChB,KAAK,QAAQ,EACb,KAAK,oBAAoB,EAEzB,KAAK,WAAW,EACjB,MAAM,iBAAiB,CAAC;AAiCzB,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,cAAe,YAAW,aAAa;IAClD,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAc;IAEvC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAgB;IAC5C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAEhD,OAAO,CAAC,YAAY,CAAuB;gBAE/B,OAAO,GAAE,qBAA0B;IAM/C,IAAI,KAAK,IAAI,WAAW,CAEvB;IAED,EAAE,CAAC,QAAQ,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,WAAW;IAI3C,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAYxB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAyBtB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAetB,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAevB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAcrB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IASxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAW9B,OAAO,CAAC,iBAAiB;IAuBzB,OAAO,CAAC,mBAAmB;IAoC3B,OAAO,CAAC,YAAY;IAMpB,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,gBAAgB;IAcxB,OAAO,CAAC,cAAc;IAQtB,OAAO,CAAC,YAAY;IAiBpB,OAAO,CAAC,iBAAiB;CAY1B"}