@clarionhq/recorder 0.0.1 → 0.1.0

package/android/src/main/java/com/clarionhq/recorder/RecorderSession.kt

@@ -0,0 +1,336 @@
+package com.clarionhq.recorder
+
+import android.Manifest
+import android.content.Context
+import android.content.pm.PackageManager
+import android.media.AudioFormat
+import android.media.AudioRecord
+import android.media.MediaCodec
+import android.media.MediaRecorder
+import androidx.core.content.ContextCompat
+import java.io.File
+import java.nio.ByteBuffer
+import java.util.concurrent.LinkedBlockingQueue
+import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicBoolean
+import kotlin.math.max
+
+internal class RecorderSession(
+  private val context: Context,
+  private val config: RecorderConfig,
+  private val callbacks: RecorderCallbacks,
+) {
+  private val channelMask = if (config.channels == 1) {
+    AudioFormat.CHANNEL_IN_MONO
+  } else {
+    AudioFormat.CHANNEL_IN_STEREO
+  }
+
+  private val encoding = AudioFormat.ENCODING_PCM_16BIT
+  private val bytesPerFrame = config.channels * 2
+  private val bytesPerSecond = config.sampleRate * bytesPerFrame
+
+  private val minBufferBytes by lazy {
+    val min = AudioRecord.getMinBufferSize(config.sampleRate, channelMask, encoding)
+    if (min <= 0) throw RecorderError("UNSUPPORTED_FORMAT", "AudioRecord rejected format")
+    val target = max(min, bytesPerSecond / RecorderConstants.CAPTURE_BUFFER_FRACTION_OF_SECOND)
+    target + (target % bytesPerFrame)
+  }
+
+  private var audioRecord: AudioRecord? = null
+  private var captureThread: Thread? = null
+  private var encodeThread: Thread? = null
+
+  private val running = AtomicBoolean(false)
+  private val paused = AtomicBoolean(false)
+
+  private val pcmQueue = LinkedBlockingQueue<PcmChunk>(RecorderConstants.PCM_QUEUE_CAPACITY)
+
+  @Volatile private var sessionStartMs = 0L
+  @Volatile private var currentFilePath: String? = null
+  @Volatile private var totalBytesWritten = 0L
+  @Volatile private var lastLevelEmitMs = 0L
+
+  private data class PcmChunk(val bytes: ByteArray, val isEos: Boolean)
+
+  fun prepare() {
+    requirePermission()
+    audioRecord = AudioRecord.Builder()
+      .setAudioSource(MediaRecorder.AudioSource.MIC)
+      .setAudioFormat(
+        AudioFormat.Builder()
+          .setSampleRate(config.sampleRate)
+          .setChannelMask(channelMask)
+          .setEncoding(encoding)
+          .build(),
+      )
+      .setBufferSizeInBytes(minBufferBytes * 2)
+      .build()
+      .also {
+        if (it.state != AudioRecord.STATE_INITIALIZED) {
+          it.release()
+          throw RecorderError("ENGINE_NOT_READY", "AudioRecord failed to initialize")
+        }
+      }
+  }
+
+  fun start() {
+    val record = audioRecord ?: throw RecorderError("ENGINE_NOT_READY", "Call prepare() first")
+    sessionStartMs = System.currentTimeMillis()
+    totalBytesWritten = 0L
+    pcmQueue.clear()
+
+    record.startRecording()
+    running.set(true)
+    paused.set(false)
+
+    captureThread = Thread(::captureLoop, "Clarion-Capture").apply { start() }
+    encodeThread = Thread(::encodeLoop, "Clarion-Encode").apply { start() }
+
+    callbacks.onState("recording")
+  }
+
+  fun pause() {
+    if (!running.get()) throw RecorderError("INVALID_STATE", "Not recording")
+    paused.set(true)
+    callbacks.onState("paused")
+  }
+
+  fun resume() {
+    if (!running.get()) throw RecorderError("INVALID_STATE", "Not recording")
+    paused.set(false)
+    callbacks.onState("recording")
+  }
+
+  fun stop(): RecorderResult {
+    if (!running.get()) throw RecorderError("INVALID_STATE", "Not recording")
+    callbacks.onState("stopping")
+
+    running.set(false)
+    pcmQueue.offer(PcmChunk(ByteArray(0), isEos = true))
+
+    encodeThread?.join(RecorderConstants.ENCODE_THREAD_JOIN_TIMEOUT_MS)
+    captureThread?.join(RecorderConstants.CAPTURE_THREAD_JOIN_TIMEOUT_MS)
+
+    runCatching { audioRecord?.stop() }
+    audioRecord?.release()
+    audioRecord = null
+
+    val finalUri = currentFilePath?.let { "${RecorderConstants.URI_SCHEME}$it" }
+      ?: throw RecorderError("INTERNAL_ERROR", "No output file produced")
+
+    val durationMs = System.currentTimeMillis() - sessionStartMs
+    callbacks.onState("idle")
+
+    return RecorderResult(
+      uri = finalUri,
+      durationMs = durationMs,
+      sizeBytes = totalBytesWritten,
+      sampleRate = config.sampleRate,
+      channels = config.channels,
+      bitDepth = config.bitDepth,
+    )
+  }
+
+  fun discard() {
+    val wasRecording = running.getAndSet(false)
+    pcmQueue.offer(PcmChunk(ByteArray(0), isEos = true))
+    encodeThread?.join(RecorderConstants.CANCEL_ENCODE_JOIN_TIMEOUT_MS)
+    captureThread?.join(RecorderConstants.CANCEL_CAPTURE_JOIN_TIMEOUT_MS)
+    runCatching { audioRecord?.stop() }
+    audioRecord?.release()
+    audioRecord = null
+
+    if (wasRecording) {
+      // Only delete in-progress recordings; never delete a finalized file.
+      currentFilePath?.let { runCatching { File(it).delete() } }
+    }
+    currentFilePath = null
+    callbacks.onState("idle")
+  }
+
+  fun release() {
+    if (running.get()) discard()
+    audioRecord?.release()
+    audioRecord = null
+    callbacks.onState("released")
+  }
+
+  private fun captureLoop() {
+    val buffer = ByteArray(minBufferBytes)
+    callbacks.runCatchingRecorder("IO_ERROR", "Capture failed") {
+      while (running.get()) {
+        val read = audioRecord?.read(buffer, 0, buffer.size) ?: -1
+        when {
+          read > 0 -> {
+            if (!paused.get()) {
+              if (config.emitAudioLevel) maybeEmitLevels(buffer, read)
+              pcmQueue.put(PcmChunk(buffer.copyOf(read), isEos = false))
+            }
+          }
+          read == AudioRecord.ERROR_INVALID_OPERATION ||
+          read == AudioRecord.ERROR_BAD_VALUE ||
+          read == AudioRecord.ERROR_DEAD_OBJECT ||
+          read == AudioRecord.ERROR -> {
+            throw RecorderError("IO_ERROR", "AudioRecord.read() returned $read")
+          }
+        }
+      }
+    }
+  }
+
+  private fun encodeLoop() {
+    var session: EncodeFile? = null
+    var presentationUs = 0L
+    var fileStartedAtMs = System.currentTimeMillis()
+
+    callbacks.runCatchingRecorder("INTERNAL_ERROR", "Encode failed") {
+      session = openEncodeFile().also { currentFilePath = it.path }
+      val rotateMs = config.rotateAfterMs
+
+      while (true) {
+        val chunk = pcmQueue.poll(
+          RecorderConstants.PCM_QUEUE_POLL_TIMEOUT_MS,
+          TimeUnit.MILLISECONDS,
+        ) ?: continue
+
+        val activeSession = session ?: break
+        val rotateNow = !chunk.isEos && rotateMs != null &&
+          (System.currentTimeMillis() - fileStartedAtMs) >= rotateMs
+
+        if (chunk.isEos || rotateNow) {
+          drainAndFinalize(activeSession, presentationUs, isEos = true)
+          emitChunkComplete(activeSession, fileStartedAtMs)
+          activeSession.close()
+
+          if (chunk.isEos) {
+            currentFilePath = activeSession.path
+            break
+          }
+
+          presentationUs = 0L
+          fileStartedAtMs = System.currentTimeMillis()
+          session = openEncodeFile().also { currentFilePath = it.path }
+          if (chunk.bytes.isNotEmpty()) {
+            presentationUs = feedPcm(session!!, chunk.bytes, presentationUs)
+          }
+        } else {
+          presentationUs = feedPcm(activeSession, chunk.bytes, presentationUs)
+          drainEncoder(activeSession, endOfStream = false)
+        }
+      }
+    }
+    session?.runCatching { close() }
+  }
+
+  private fun feedPcm(session: EncodeFile, pcm: ByteArray, basePtsUs: Long): Long {
+    val inIndex = session.codec.dequeueInputBuffer(RecorderConstants.CODEC_DEQUEUE_TIMEOUT_US)
+    if (inIndex < 0) return basePtsUs
+
+    val inBuf: ByteBuffer = session.codec.getInputBuffer(inIndex)
+      ?: throw RecorderError("INTERNAL_ERROR", "Null input buffer")
+    inBuf.clear()
+    inBuf.put(pcm)
+    session.codec.queueInputBuffer(inIndex, 0, pcm.size, basePtsUs, 0)
+
+    return basePtsUs + (pcm.size.toLong() * 1_000_000L) / bytesPerSecond
+  }
+
+  private fun drainAndFinalize(session: EncodeFile, ptsUs: Long, isEos: Boolean) {
+    if (isEos) {
+      val inIndex = session.codec.dequeueInputBuffer(RecorderConstants.CODEC_DEQUEUE_TIMEOUT_US)
+      if (inIndex >= 0) {
+        session.codec.queueInputBuffer(
+          inIndex, 0, 0, ptsUs, MediaCodec.BUFFER_FLAG_END_OF_STREAM,
+        )
+      }
+    }
+    drainEncoder(session, endOfStream = isEos)
+  }
+
+  private fun drainEncoder(session: EncodeFile, endOfStream: Boolean) {
+    val info = MediaCodec.BufferInfo()
+    val dequeueTimeoutUs = if (endOfStream) RecorderConstants.CODEC_DEQUEUE_TIMEOUT_US else 0L
+    while (true) {
+      val outIndex = session.codec.dequeueOutputBuffer(info, dequeueTimeoutUs)
+      when {
+        outIndex == MediaCodec.INFO_TRY_AGAIN_LATER -> if (!endOfStream) return
+        outIndex == MediaCodec.INFO_OUTPUT_FORMAT_CHANGED -> startMuxer(session)
+        outIndex >= 0 -> {
+          if (writeOutputBuffer(session, outIndex, info)) return
+        }
+      }
+    }
+  }
+
+  private fun startMuxer(session: EncodeFile) {
+    if (session.muxerTrackIndex >= 0) {
+      throw RecorderError("INTERNAL_ERROR", "Format changed after muxer start")
+    }
+    session.muxerTrackIndex = session.muxer.addTrack(session.codec.outputFormat)
+    session.muxer.start()
+    session.muxerStarted = true
+  }
+
+  private fun writeOutputBuffer(
+    session: EncodeFile,
+    outIndex: Int,
+    info: MediaCodec.BufferInfo,
+  ): Boolean {
+    val outBuf: ByteBuffer = session.codec.getOutputBuffer(outIndex)
+      ?: throw RecorderError("INTERNAL_ERROR", "Null output buffer")
+
+    if (info.flags and MediaCodec.BUFFER_FLAG_CODEC_CONFIG != 0) info.size = 0
+
+    if (info.size > 0 && session.muxerStarted) {
+      outBuf.position(info.offset)
+      outBuf.limit(info.offset + info.size)
+      session.muxer.writeSampleData(session.muxerTrackIndex, outBuf, info)
+      session.bytesWritten += info.size
+      totalBytesWritten += info.size
+    }
+
+    session.codec.releaseOutputBuffer(outIndex, false)
+    return info.flags and MediaCodec.BUFFER_FLAG_END_OF_STREAM != 0
+  }
+
+  private fun emitChunkComplete(session: EncodeFile, fileStartedAtMs: Long) {
+    callbacks.onChunk(
+      uri = "${RecorderConstants.URI_SCHEME}${session.path}",
+      startMs = fileStartedAtMs,
+      endMs = System.currentTimeMillis(),
+      sizeBytes = session.bytesWritten,
+    )
+  }
+
+  private fun openEncodeFile(): EncodeFile {
+    val baseDir = config.outputDirectory?.let { File(it) }
+      ?: File(context.cacheDir, RecorderConstants.DEFAULT_CACHE_SUBDIR)
+    return EncodeFile.open(
+      outputDir = baseDir,
+      filenamePrefix = config.filenamePrefix ?: RecorderConstants.DEFAULT_FILENAME_PREFIX,
+      sampleRate = config.sampleRate,
+      channels = config.channels,
+      aacBitrate = config.aacBitrate,
+      maxInputSize = minBufferBytes * 2,
+    )
+  }
+
+  private fun maybeEmitLevels(buffer: ByteArray, length: Int) {
+    val now = System.currentTimeMillis()
+    if (now - lastLevelEmitMs < config.audioLevelIntervalMs) return
+    lastLevelEmitMs = now
+    val levels = AudioLevelMeter.compute(buffer, length)
+    callbacks.onAudioLevel(levels.rms, levels.peak)
+  }
+
+  private fun requirePermission() {
+    val granted = ContextCompat.checkSelfPermission(
+      context,
+      Manifest.permission.RECORD_AUDIO,
+    ) == PackageManager.PERMISSION_GRANTED
+    if (!granted) {
+      throw RecorderError("PERMISSION_DENIED", "RECORD_AUDIO permission not granted")
+    }
+  }
+}

package/android/src/main/java/com/clarionhq/recorder/RecorderTypes.kt

@@ -0,0 +1,29 @@
+package com.clarionhq.recorder
+
+internal class RecorderError(
+  val code: String,
+  message: String,
+  val recoverable: Boolean = false,
+  cause: Throwable? = null,
+) : Exception(message, cause)
+
+internal interface RecorderCallbacks {
+  fun onState(state: String)
+  fun onAudioLevel(rms: Double, peak: Double)
+  fun onChunk(uri: String, startMs: Long, endMs: Long, sizeBytes: Long)
+  fun onError(error: RecorderError)
+}
+
+internal inline fun RecorderCallbacks.runCatchingRecorder(
+  fallbackCode: String,
+  fallbackPrefix: String,
+  block: () -> Unit,
+) {
+  try {
+    block()
+  } catch (e: RecorderError) {
+    onError(e)
+  } catch (e: Throwable) {
+    onError(RecorderError(fallbackCode, "$fallbackPrefix: ${e.message}", cause = e))
+  }
+}

package/android/src/main/java/com/margelo/nitro/clarion/recorder/HybridClarionRecorder.kt

@@ -0,0 +1,174 @@
+package com.margelo.nitro.clarion.recorder
+
+import android.content.Context
+import com.clarionhq.recorder.RecorderCallbacks
+import com.clarionhq.recorder.RecorderConfig
+import com.clarionhq.recorder.RecorderError
+import com.clarionhq.recorder.RecorderResult
+import com.clarionhq.recorder.RecorderSession
+import com.facebook.proguard.annotations.DoNotStrip
+import com.margelo.nitro.NitroModules
+import com.margelo.nitro.core.Promise
+import java.util.concurrent.atomic.AtomicInteger
+
+@DoNotStrip
+class HybridClarionRecorder : HybridClarionRecorderSpec() {
+  override val memorySize: Long get() = 0L
+
+  private val context: Context = NitroModules.applicationContext
+    ?: error("Nitro applicationContext is null — was the module initialized?")
+
+  private val nextListenerId = AtomicInteger(1)
+  private val stateListeners = mutableMapOf<Int, (String) -> Unit>()
+  private val audioLevelListeners = mutableMapOf<Int, (Double, Double) -> Unit>()
+  private val chunkListeners = mutableMapOf<Int, (String, Double, Double, Double) -> Unit>()
+  private val errorListeners = mutableMapOf<Int, (NativeRecorderError) -> Unit>()
+
+  @Volatile private var session: RecorderSession? = null
+  @Volatile private var currentState: String = "idle"
+
+  private val callbacks = object : RecorderCallbacks {
+    override fun onState(state: String) {
+      currentState = state
+      stateListeners.values.toList().forEach { runCatching { it(state) } }
+    }
+    override fun onAudioLevel(rms: Double, peak: Double) {
+      audioLevelListeners.values.toList().forEach { runCatching { it(rms, peak) } }
+    }
+    override fun onChunk(uri: String, startMs: Long, endMs: Long, sizeBytes: Long) {
+      chunkListeners.values.toList().forEach {
+        runCatching { it(uri, startMs.toDouble(), endMs.toDouble(), sizeBytes.toDouble()) }
+      }
+    }
+    override fun onError(error: RecorderError) {
+      currentState = "error"
+      val payload = NativeRecorderError(
+        code = error.code,
+        message = error.message ?: "Unknown error",
+        recoverable = error.recoverable,
+      )
+      errorListeners.values.toList().forEach { runCatching { it(payload) } }
+    }
+  }
+
+  override val state: String get() = currentState
+
+  override fun prepare(config: NativeRecorderConfig): Promise<Unit> =
+    Promise.async {
+      runOrThrow {
+        val parsed = config.toKotlinConfig()
+        val newSession = RecorderSession(context, parsed, callbacks)
+        callbacks.onState("preparing")
+        newSession.prepare()
+        session = newSession
+        callbacks.onState("ready")
+      }
+    }
+
+  override fun start(): Promise<Unit> = Promise.async {
+    runOrThrow {
+      val s = session ?: throw RecorderError("ENGINE_NOT_READY", "Call prepare() first")
+      callbacks.onState("starting")
+      s.start()
+    }
+  }
+
+  override fun pause(): Promise<Unit> = Promise.async {
+    runOrThrow {
+      session?.pause() ?: throw RecorderError("ENGINE_NOT_READY", "No session")
+    }
+  }
+
+  override fun resume(): Promise<Unit> = Promise.async {
+    runOrThrow {
+      session?.resume() ?: throw RecorderError("ENGINE_NOT_READY", "No session")
+    }
+  }
+
+  override fun stop(): Promise<NativeRecorderResult> = Promise.async {
+    runOrThrow {
+      val s = session ?: throw RecorderError("ENGINE_NOT_READY", "No session")
+      val result = s.stop().toNative()
+      session = null
+      result
+    }
+  }
+
+  override fun discard(): Promise<Unit> = Promise.async {
+    runOrThrow {
+      session?.discard()
+      session = null
+    }
+  }
+
+  override fun release(): Promise<Unit> = Promise.async {
+    runOrThrow {
+      session?.release()
+      session = null
+      removeAllListeners()
+    }
+  }
+
+  private inline fun <T> runOrThrow(block: () -> T): T {
+    return try {
+      block()
+    } catch (e: RecorderError) {
+      throw RuntimeException("[${e.code}] ${e.message}", e)
+    }
+  }
+
+  override fun addStateListener(listener: (String) -> Unit): Double =
+    register(stateListeners, listener)
+
+  override fun addAudioLevelListener(listener: (Double, Double) -> Unit): Double =
+    register(audioLevelListeners, listener)
+
+  override fun addChunkListener(
+    listener: (String, Double, Double, Double) -> Unit,
+  ): Double = register(chunkListeners, listener)
+
+  override fun addErrorListener(listener: (NativeRecorderError) -> Unit): Double =
+    register(errorListeners, listener)
+
+  override fun removeListener(id: Double) {
+    val key = id.toInt()
+    stateListeners.remove(key)
+    audioLevelListeners.remove(key)
+    chunkListeners.remove(key)
+    errorListeners.remove(key)
+  }
+
+  override fun removeAllListeners() {
+    stateListeners.clear()
+    audioLevelListeners.clear()
+    chunkListeners.clear()
+    errorListeners.clear()
+  }
+
+  private fun <T> register(map: MutableMap<Int, T>, listener: T): Double {
+    val id = nextListenerId.getAndIncrement()
+    map[id] = listener
+    return id.toDouble()
+  }
+}
+
+private fun NativeRecorderConfig.toKotlinConfig(): RecorderConfig = RecorderConfig(
+  sampleRate = sampleRate.toInt(),
+  channels = channels.toInt(),
+  bitDepth = bitDepth.toInt(),
+  outputDirectory = outputDirectory,
+  filenamePrefix = filenamePrefix,
+  rotateAfterMs = rotateAfterMs?.toLong(),
+  emitAudioLevel = emitAudioLevel,
+  audioLevelIntervalMs = audioLevelIntervalMs.toInt(),
+  aacBitrate = aacBitrate.toInt(),
+)
+
+private fun RecorderResult.toNative(): NativeRecorderResult = NativeRecorderResult(
+  uri = uri,
+  durationMs = durationMs.toDouble(),
+  sizeBytes = sizeBytes.toDouble(),
+  sampleRate = sampleRate.toDouble(),
+  channels = channels.toDouble(),
+  bitDepth = bitDepth.toDouble(),
+)

package/clarionhq-recorder.podspec

@@ -0,0 +1,31 @@
+require "json"
+
+package = JSON.parse(File.read(File.join(__dir__, "package.json")))
+
+Pod::Spec.new do |s|
+  s.name         = "clarionhq-recorder"
+  s.module_name  = "ClarionRecorder"
+  s.version      = package["version"]
+  s.summary      = package["description"]
+  s.homepage     = "https://github.com/Th4nderG0d/clarion"
+  s.license      = package["license"]
+  s.author       = { "Clarion" => "hello@clarionhq.dev" }
+  s.platforms    = { :ios => "15.1" }
+  s.source       = { :git => "https://github.com/Th4nderG0d/clarion.git", :tag => "v#{s.version}" }
+
+  s.source_files = "ios/**/*.{swift,h,m,mm,cpp}"
+  s.exclude_files = "ios/**/*.swift.bak"
+
+  s.frameworks = "AVFoundation", "AudioToolbox", "CoreMedia"
+
+  s.pod_target_xcconfig = {
+    "DEFINES_MODULE" => "YES",
+    "SWIFT_VERSION" => "5.9",
+    "OTHER_SWIFT_FLAGS" => "$(inherited) -DCLARION_RECORDER"
+  }
+
+  load "nitrogen/generated/ios/ClarionRecorder+autolinking.rb"
+  add_nitrogen_files(s)
+
+  s.dependency "React-Core"
+end

package/ios/AudioLevelMeter.swift

@@ -0,0 +1,37 @@
+import AVFoundation
+import Foundation
+
+internal struct AudioLevels {
+  let rms: Double
+  let peak: Double
+}
+
+internal enum AudioLevelMeter {
+  static func compute(buffer: AVAudioPCMBuffer) -> AudioLevels {
+    guard let floatData = buffer.floatChannelData else {
+      return AudioLevels(rms: 0, peak: 0)
+    }
+    let channelCount = Int(buffer.format.channelCount)
+    let frameCount = Int(buffer.frameLength)
+    if frameCount == 0 || channelCount == 0 {
+      return AudioLevels(rms: 0, peak: 0)
+    }
+
+    var sumSquares: Double = 0
+    var peakAbs: Float = 0
+
+    for channel in 0..<channelCount {
+      let samples = floatData[channel]
+      for frame in 0..<frameCount {
+        let sample = samples[frame]
+        let absSample = abs(sample)
+        if absSample > peakAbs { peakAbs = absSample }
+        sumSquares += Double(sample) * Double(sample)
+      }
+    }
+
+    let totalSamples = Double(frameCount * channelCount)
+    let rms = (sumSquares > 0) ? (sumSquares / totalSamples).squareRoot() : 0
+    return AudioLevels(rms: min(rms, 1.0), peak: min(Double(peakAbs), 1.0))
+  }
+}

package/ios/EncodeFile.swift

@@ -0,0 +1,69 @@
+import AVFoundation
+import Foundation
+
+/// Wraps a single AVAudioFile write target. Simpler than driving AVAssetWriter
+/// directly — the file negotiates AAC encoding internally and accepts
+/// AVAudioPCMBuffer in our chosen PCM format without any CMSampleBuffer dance.
+internal final class EncodeFile {
+  let url: URL
+  private var audioFile: AVAudioFile?
+  private(set) var bytesWritten: Int64 = 0
+  private(set) var finished: Bool = false
+
+  private init(url: URL) {
+    self.url = url
+  }
+
+  static func open(
+    in directory: URL,
+    filenamePrefix: String,
+    sampleRate: Double,
+    channels: UInt32,
+    aacBitrate: Int
+  ) throws -> EncodeFile {
+    try FileManager.default.createDirectory(at: directory, withIntermediateDirectories: true)
+    let filename = "\(filenamePrefix)-\(UUID().uuidString).\(RecorderConstants.outputExtension)"
+    let url = directory.appendingPathComponent(filename)
+
+    // Don't pass AVEncoderBitRateKey — iOS rejects bitrates that the encoder's
+    // tables don't list as valid for the (sampleRate, channels) combo with
+    // kAudioFormatUnsupportedDataFormatError. Letting the encoder pick a
+    // sensible default for the format is the robust path.
+    var outputSettings: [String: Any] = [
+      AVFormatIDKey: kAudioFormatMPEG4AAC,
+      AVSampleRateKey: sampleRate,
+      AVNumberOfChannelsKey: channels,
+    ]
+    // 32 kbps is the safe AAC-LC bitrate for 16 kHz mono. Apply only when
+    // explicitly requested via a sensible value; otherwise rely on the default.
+    if aacBitrate > 0 && aacBitrate <= 48_000 {
+      outputSettings[AVEncoderBitRateKey] = aacBitrate
+    }
+
+    let file = EncodeFile(url: url)
+    file.audioFile = try AVAudioFile(
+      forWriting: url,
+      settings: outputSettings,
+      commonFormat: .pcmFormatInt16,
+      interleaved: true
+    )
+    return file
+  }
+
+  func write(buffer: AVAudioPCMBuffer) throws {
+    guard !finished, let audioFile else { return }
+    try audioFile.write(from: buffer)
+    let bytesPerFrame = Int64(buffer.format.streamDescription.pointee.mBytesPerFrame)
+    bytesWritten += Int64(buffer.frameLength) * bytesPerFrame
+  }
+
+  func close() {
+    finished = true
+    audioFile = nil
+  }
+
+  func cancel() {
+    close()
+    try? FileManager.default.removeItem(at: url)
+  }
+}