opuslib 0.1.4 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+All notable changes to this project are documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+follows [Semantic Versioning](https://semver.org/).
+
+## [0.2.0]
+
+This release is **fully backward compatible** — everything below is additive.
+Existing code keeps working unchanged: `audioChunk` events still carry `data`,
+and all the new config fields are optional.
+
+### Fixed
+
+- **Encoding no longer runs on the real-time audio thread.** Capture and Opus
+  encoding now run on separate threads — the capture callback only converts and
+  copies PCM, then hands it to a dedicated serial encoding thread that owns all
+  encoder state. This removes the iOS crash that could occur when encoding on
+  the audio render thread, and keeps the real-time audio path unblocked.
+  (iOS: a serial `DispatchQueue`; Android: a `HandlerThread`.)
+- **Flush on stop.** When you call `stopStreaming()`, any buffered tail of audio
+  is padded with silence, encoded, and emitted before teardown — so the end of a
+  session is no longer dropped.
+
+### Added
+
+- **`audioStarted` event** — fired once when streaming begins, from the encoding
+  thread. Includes the active config and the Opus encoder `preSkip`
+  (`OPUS_GET_LOOKAHEAD`) so a decoder knows how many samples to skip at the start
+  of the stream.
+- **`audioEnd` event** — fired once when streaming stops (after the flush above),
+  with a session summary (`totalDuration`, `totalPackets`).
+- **`framesPerCallback` config** — batch N independently-encoded Opus frames into
+  a single `audioChunk` event to reduce bridge calls. Defaults to `1`.
+- **`audioChunk.frames` / `duration` / `frameCount`** — `frames` is an array of
+  independent, individually-decodable Opus packets (each with its own TOC byte;
+  never concatenated). `audioChunk.data` is retained and equals `frames[0].data`.
+- **`enableAudioLevel` config + `OpusFrame.audioLevel`** — opt-in per-frame audio
+  level in `0.0–1.0` (RMS mapped through dBFS). Off by default.
+- **`iosAudioSession` config (iOS only)** — customize the `AVAudioSession`
+  category / mode / options (e.g. `playAndRecord`, `defaultToSpeaker`,
+  `allowBluetooth`). Ignored on Android and web; omit to keep the default
+  recording session.
+- New helper methods `addAudioStartedListener()` and `addAudioEndListener()`,
+  plus `audioStarted` / `audioEnd` overloads on `addListener()`.
+- New exported types: `OpusFrame`, `AudioStartedEvent`, `AudioEndEvent`,
+  `IOSAudioSessionConfig`.
+
+### How to use the new features
+
+```typescript
+import Opuslib from 'opuslib'
+
+// Lifecycle events
+Opuslib.addAudioStartedListener((e) => {
+  // e.preSkip — samples a decoder should skip at the start of the stream
+  console.log(`started @ ${e.sampleRate}Hz, preSkip=${e.preSkip}`)
+})
+Opuslib.addAudioEndListener((e) => {
+  console.log(`ended: ${e.totalPackets} packets over ${e.totalDuration}ms`)
+})
+
+// Per-frame audio level + frame batching
+Opuslib.addListener('audioChunk', (e) => {
+  // e.data still works (back-compat) === e.frames[0].data
+  for (const frame of e.frames) {
+    websocket.send(frame.data)        // each frame is an independent Opus packet
+    meter(frame.audioLevel)           // present only when enableAudioLevel: true
+  }
+})
+
+await Opuslib.startStreaming({
+  sampleRate: 16000,
+  channels: 1,
+  bitrate: 24000,
+  frameSize: 20,
+  packetDuration: 100,
+  framesPerCallback: 5,   // 5 independent frames per audioChunk (80% fewer bridge calls)
+  enableAudioLevel: true, // populate frame.audioLevel
+  // iOS-only: record + play, route to speaker
+  iosAudioSession: {
+    category: 'playAndRecord',
+    mode: 'default',
+    options: ['defaultToSpeaker', 'allowBluetooth'],
+  },
+})
+```
+
+### Migration notes
+
+Nothing is required. To adopt the new behavior:
+
+- Reading `event.data` keeps working. To consume batched frames, switch to
+  iterating `event.frames` (with `framesPerCallback: 1`, the default, `frames`
+  has exactly one entry equal to `data`).
+- `framesPerCallback` supersedes `packetDuration` for deciding how many frames
+  are grouped per event. `packetDuration` remains accepted for compatibility.
+
+## [0.1.4]
+
+### Changed
+
+- Updated the vendored Opus codec from 1.6 to **1.6.1**.
+
+## [0.1.2]
+
+- Earlier published releases. See the Git history for details.

package/README.md

@@ -20,10 +20,13 @@ Created as I had a need for real-time voice communication in a React Native app.
 - **Opus 1.6.1** - Latest codec version compiled from the [official source](https://opus-codec.org/downloads/)
 - **Low Latency** - Real-time encoding with minimal overhead
 - **Native Performance** - Direct C/C++ integration, no JavaScript encoding
+- **Thread-safe encoding** - Capture and Opus encoding run on separate threads, so the real-time audio thread is never blocked
+- **Audio level metering** - Optional per-frame level (0.0–1.0) via `enableAudioLevel`
+- **Lifecycle events** - `audioStarted` / `audioEnd` with session metadata, plus flush-on-stop so no trailing audio is lost
 - **High Quality** - 24kbps achieves excellent speech quality
 - **Cross-Platform** - iOS and Android with a consistent API
 - **Zero Dependencies** - Self-contained with vendored Opus source
-- **Configurable** - Bitrate, sample rate, frame size
+- **Configurable** - Bitrate, sample rate, frame size, frame batching
 - **Event-Based** - Stream encoded audio chunks via events
 
 ### Why Opus 1.6.1?
@@ -141,13 +144,25 @@ interface AudioConfig {
   bitrate: number;                  // Target bitrate in bits/second (e.g., 24000)
   frameSize: number;                // Frame duration in ms (2.5, 5, 10, 20, 40, 60)
   packetDuration: number;           // Packet duration in ms (multiple of frameSize)
+  framesPerCallback?: number;       // Opus frames batched per audioChunk event (default: 1)
   dredDuration?: number;            // Reserved for future DRED support (default: 0)
   enableAmplitudeEvents?: boolean;  // Enable amplitude monitoring (default: false)
   amplitudeEventInterval?: number;  // Amplitude update interval in ms (default: 16)
+  enableAudioLevel?: boolean;       // Per-frame audio level (0.0-1.0) on each OpusFrame (default: false)
   saveDebugAudio?: boolean;         // Save raw PCM to a file for debugging (development only)
+  iosAudioSession?: {               // iOS AVAudioSession config (iOS only; ignored elsewhere)
+    category: 'record' | 'playAndRecord' | 'playback' | 'ambient';
+    mode: 'default' | 'voiceChat' | 'measurement' | 'spokenAudio';
+    options?: Array<'mixWithOthers' | 'defaultToSpeaker' | 'allowBluetooth' | 'allowAirPlay' | 'allowBluetoothA2DP'>;
+  };
 }
 ```
 
+> **Backward compatibility:** `framesPerCallback`, `enableAudioLevel`, and
+> `iosAudioSession` are all optional. Omitting them preserves the previous
+> behavior (one Opus packet per `audioChunk`, no level metering, default iOS
+> recording session).
+
 **Recommended Settings for Speech:**
 ```typescript
 {
@@ -189,18 +204,89 @@ Emitted when an encoded Opus packet is ready.
 
 ```typescript
 Opuslib.addListener('audioChunk', (event: AudioChunkEvent) => {
-  // event.data: ArrayBuffer - Raw Opus packet (ready to send/save)
+  // event.data: ArrayBuffer - First frame's Opus packet (back-compat; = frames[0].data)
+  // event.frames: OpusFrame[] - Independent Opus packets (one per encoded frame)
   // event.timestamp: number - Capture timestamp in milliseconds
-  // event.sequenceNumber: number - Packet sequence number (starts at 0)
+  // event.sequenceNumber: number - Event sequence number (starts at 0)
+  // event.duration: number - Total duration in ms (frameSize * frameCount)
+  // event.frameCount: number - Number of frames in this event
+
+  // Each frame is an independent, decodable Opus packet:
+  for (const frame of event.frames) {
+    websocket.send(frame.data);
+    // frame.audioLevel?: number - present only when enableAudioLevel is true
+  }
 });
 ```
 
 **Event Data:**
 ```typescript
+interface OpusFrame {
+  data: ArrayBuffer;         // Independent Opus packet (one opus_encode() output, own TOC byte)
+  audioLevel?: number;       // Per-frame level 0.0-1.0 (only when enableAudioLevel is true)
+}
+
 interface AudioChunkEvent {
-  data: ArrayBuffer;         // Raw Opus-encoded audio packet
+  data: ArrayBuffer;         // First frame's packet — kept for backward compatibility (= frames[0].data)
+  frames: OpusFrame[];       // Independent Opus packets (single entry unless framesPerCallback > 1)
   timestamp: number;         // Milliseconds since epoch
-  sequenceNumber: number;    // Incrementing packet counter
+  sequenceNumber: number;    // Incrementing event counter
+  duration: number;          // Total duration in ms (frameSize * frameCount)
+  frameCount: number;        // Number of Opus frames (= frames.length)
+}
+```
+
+> With the default `framesPerCallback` of 1, `frames` has a single entry and
+> `data === frames[0].data`, so existing `event.data` consumers are unaffected.
+> Frames are **never** concatenated — each is independently decodable.
+
+---
+
+#### `audioStarted`
+
+Emitted once when streaming starts. Carries the active config and the Opus
+encoder `preSkip` (lookahead) so a decoder knows how many samples to skip at the
+beginning of the stream.
+
+```typescript
+Opuslib.addAudioStartedListener((event: AudioStartedEvent) => {
+  console.log(`Started: ${event.sampleRate}Hz, preSkip=${event.preSkip}`);
+});
+// or: Opuslib.addListener('audioStarted', (event) => { ... })
+```
+
+**Event Data:**
+```typescript
+interface AudioStartedEvent {
+  timestamp: number;   // Milliseconds since epoch
+  sampleRate: number;  // Actual sample rate in Hz
+  channels: number;    // Number of channels
+  bitrate: number;     // Configured bitrate in bits/second
+  frameSize: number;   // Frame duration in milliseconds
+  preSkip: number;     // Encoder lookahead in samples (decoder should skip these)
+}
+```
+
+---
+
+#### `audioEnd`
+
+Emitted once when streaming stops, after the final buffered audio has been
+flushed (the trailing partial frame is padded with silence so no audio is lost).
+
+```typescript
+Opuslib.addAudioEndListener((event: AudioEndEvent) => {
+  console.log(`Ended: ${event.totalDuration}ms, ${event.totalPackets} packets`);
+});
+// or: Opuslib.addListener('audioEnd', (event) => { ... })
+```
+
+**Event Data:**
+```typescript
+interface AudioEndEvent {
+  timestamp: number;       // Milliseconds since epoch
+  totalDuration: number;   // Total session duration in milliseconds
+  totalPackets: number;    // Total audioChunk events emitted during the session
 }
 ```
 
@@ -254,7 +340,39 @@ interface ErrorEvent {
 ### iOS
 
 - **Minimum iOS Version:** 15.1+
-- **Audio Session:** Automatically configured for recording
+- **Audio Session:** Defaults to the `record` category with `measurement` mode (pure recording, system audio processing disabled). Override it per-session with the optional `iosAudioSession` config — e.g. for simultaneous playback or Bluetooth/speaker routing:
+  ```typescript
+  await Opuslib.startStreaming({
+    sampleRate: 24000, channels: 1, bitrate: 24000, frameSize: 20, packetDuration: 100,
+    iosAudioSession: {
+      category: 'playAndRecord',           // record + play at the same time
+      mode: 'default',                     // enable AGC / echo cancellation
+      options: ['defaultToSpeaker', 'allowBluetooth'],
+    },
+  });
+  ```
+
+  | `category` | Behavior |
+  |------------|----------|
+  | `record` | Pure recording (default) |
+  | `playAndRecord` | Record and play simultaneously |
+  | `playback` | Playback only |
+  | `ambient` | Mix with other audio without interrupting it |
+
+  | `mode` | Behavior |
+  |--------|----------|
+  | `measurement` | Disable system audio processing (default) |
+  | `default` | Enable AGC, echo cancellation, etc. |
+  | `voiceChat` | Optimized for voice calls |
+  | `spokenAudio` | Optimized for spoken content |
+
+  | `options[]` | Behavior |
+  |-------------|----------|
+  | `mixWithOthers` | Allow mixing with other audio apps |
+  | `defaultToSpeaker` | Route to speaker instead of earpiece |
+  | `allowBluetooth` | Allow Bluetooth HFP devices |
+  | `allowAirPlay` | Allow AirPlay output |
+  | `allowBluetoothA2DP` | Allow Bluetooth A2DP (high-quality audio) |
 - **Permissions:** Add to `app.json`:
   ```json
   {
@@ -355,20 +473,33 @@ cd ..
 
 ## Technical Details
 
-### Architecture
+Capture and encoding run on **separate threads**. The capture thread only reads
+PCM, converts it, and copies the samples onto a dedicated serial encoding
+thread; all Opus encoder state and `opus_encode()` calls happen there. This
+keeps the real-time audio thread unblocked and avoids encoding on it.
+
+```
+Capture thread                      Encoding thread (serial)
+  |  read PCM (AVAudioEngine / AudioRecord)
+  |  convert + copy ----- post ----> append to pending buffer
+  |                                  while (>= one frame) opus_encode() -> frame
+  |                                  per-frame audioLevel (if enabled)
+  |                                  batch framesPerCallback -> emit audioChunk
+  |  (stop) ------------- flush ---> pad silence + encode tail -> emit audioEnd
+```
 
 **iOS:**
 - AVAudioEngine for audio capture (48kHz PCM)
 - Custom resampler (48kHz → 16kHz)
+- Dedicated serial `DispatchQueue` for Opus encoding and event dispatch
 - Opus 1.6.1 encoder (native C via Swift)
 - Objective-C wrapper for CTL operations
 - Event emission via Expo modules
 
 **Android:**
 - AudioRecord for audio capture (16kHz PCM)
+- Dedicated `HandlerThread` for Opus encoding and event dispatch
 - JNI wrapper for Opus 1.6.1 C library
-- Background thread for recording loop
-- Kotlin coroutines for async operations
 - Event emission via Expo modules
 
 ### Opus Build Configuration

package/android/src/main/cpp/opus_jni_wrapper.cpp

@@ -144,6 +144,40 @@ Java_expo_modules_opuslib_OpusEncoder_nativeEncode(
   return result;
 }
 
+/**
+ * Get Opus encoder lookahead (pre-skip samples)
+ *
+ * Decoders should skip this many samples at the start of the stream to account
+ * for the encoder's algorithmic delay.
+ *
+ * @param env JNI environment
+ * @param thiz Java object instance
+ * @param encoder_ptr Encoder pointer from nativeCreate
+ * @return Lookahead in samples, or 0 on failure
+ */
+JNIEXPORT jint JNICALL
+Java_expo_modules_opuslib_OpusEncoder_nativeGetLookahead(
+    JNIEnv *env,
+    jobject thiz,
+    jlong encoder_ptr
+) {
+  OpusEncoder *encoder = reinterpret_cast<OpusEncoder*>(encoder_ptr);
+  if (!encoder) {
+    LOGE("Encoder pointer is null");
+    return 0;
+  }
+
+  opus_int32 lookahead = 0;
+  int result = opus_encoder_ctl(encoder, OPUS_GET_LOOKAHEAD(&lookahead));
+  if (result != OPUS_OK) {
+    LOGE("Failed to get lookahead: error %d", result);
+    return 0;
+  }
+
+  LOGI("Opus lookahead (pre-skip): %d samples", lookahead);
+  return static_cast<jint>(lookahead);
+}
+
 /**
  * Destroy Opus encoder and free resources
  *

package/android/src/main/java/expo/modules/opuslib/AudioProcessor.kt

@@ -0,0 +1,273 @@
+package expo.modules.opuslib
+
+import android.os.Handler
+import android.os.HandlerThread
+import android.util.Log
+import java.io.File
+import java.io.FileOutputStream
+import java.util.concurrent.CountDownLatch
+
+/**
+ * A single encoded Opus frame with optional per-frame audio level.
+ */
+data class EncodedFrame(
+  val data: ByteArray,
+  val audioLevel: Float?  // null when enableAudioLevel is false
+)
+
+/**
+ * AudioProcessor - Dedicated encoding thread for Opus 1.6.1 encoding and dispatch.
+ *
+ * The capture thread (AudioRecordManager) only reads PCM; this class owns the
+ * encoder and runs all encoding work on a single dedicated thread:
+ * - Owns a HandlerThread + Handler (a serial work queue)
+ * - The capture thread calls pushSamples() which copies the data and posts it
+ *   to this thread, so the capture loop never blocks on encoding
+ * - All mutable state (pendingSamples, encoder, sequenceNumber, packet buffer)
+ *   is only touched on the HandlerThread — no locks needed
+ * - audioStarted/audioEnd events are emitted from this thread too, so preSkip
+ *   and sequenceNumber are read without any cross-thread risk
+ */
+class AudioProcessor(private val config: AudioConfig) {
+  companion object {
+    private const val TAG = "AudioProcessor"
+  }
+
+  // Encoding thread + its serial work queue
+  private var handlerThread: HandlerThread? = null
+  private var handler: Handler? = null
+
+  // All fields below are only accessed on handlerThread — no locks needed
+  private var opusEncoder: OpusEncoder? = null
+  private val pendingSamples = mutableListOf<Short>()
+  private val samplesPerFrame: Int = (config.sampleRate * config.frameSize / 1000.0).toInt()
+  private val framesPerPacket: Int = Math.max(1, config.framesPerCallback)
+  private var packetFrames = mutableListOf<EncodedFrame>()  // independent Opus packets with per-frame level
+  private var sequenceNumber: Int = 0
+  private var startTime: Double = 0.0
+
+  // Whether to compute per-frame audio level
+  private val enableAudioLevel: Boolean = config.enableAudioLevel
+
+  // Debug file output
+  private var pcmFileOutputStream: FileOutputStream? = null
+
+  // Event callbacks (all invoked on encoding thread)
+  // onAudioChunk: (frames, timestamp, sequenceNumber, duration, frameCount)
+  private var onAudioChunk: ((List<EncodedFrame>, Double, Int, Double, Int) -> Unit)? = null
+  private var onStarted: ((timestamp: Double, sampleRate: Int, channels: Int, bitrate: Int, frameSize: Double, preSkip: Int) -> Unit)? = null
+  private var onEnd: ((timestamp: Double, totalDuration: Double, totalPackets: Int) -> Unit)? = null
+
+  /**
+   * Start the encoding thread, create the Opus encoder, emit audioStarted.
+   * Encoder init + preSkip read happen on the same thread — no cross-thread risk.
+   */
+  fun start(debugFile: File? = null) {
+    val thread = HandlerThread("OpusEncodingThread").apply { start() }
+    handlerThread = thread
+    handler = Handler(thread.looper)
+
+    val ready = CountDownLatch(1)
+    handler!!.post {
+      // Init encoder on encoding thread
+      _initEncoder()
+
+      // Debug file
+      if (debugFile != null) {
+        try {
+          pcmFileOutputStream = FileOutputStream(debugFile)
+          Log.d(TAG, "Debug PCM file: ${debugFile.absolutePath}")
+        } catch (e: Exception) {
+          Log.e(TAG, "Failed to create debug file: ${e.message}")
+        }
+      }
+
+      // Emit audioStarted on encoding thread — preSkip read is safe here
+      startTime = System.currentTimeMillis().toDouble()
+      val preSkip = opusEncoder?.preSkip ?: 0
+      onStarted?.invoke(
+        startTime,
+        config.sampleRate,
+        config.channels,
+        config.bitrate,
+        config.frameSize,
+        preSkip
+      )
+
+      ready.countDown()
+    }
+    ready.await()
+
+    Log.d(TAG, "Started: ${config.sampleRate}Hz, ${config.channels}ch, frame=$samplesPerFrame samples")
+  }
+
+  /**
+   * Push raw PCM samples from the capture thread (copy + post, no shared state).
+   */
+  fun pushSamples(samples: ShortArray, count: Int) {
+    val buf = samples.copyOf(count)
+    handler?.post {
+      for (s in buf) {
+        pendingSamples.add(s)
+      }
+      _processFrames()
+    }
+  }
+
+  /**
+   * Synchronously flush remaining audio, emit audioEnd, destroy encoder, stop thread.
+   * All sequenceNumber/encoder access happens on the encoding thread — no cross-thread risk.
+   */
+  fun flushAndStop() {
+    val h = handler ?: return
+    val done = CountDownLatch(1)
+    h.post {
+      _flushRemainingFrames()
+
+      // Emit audioEnd on encoding thread — sequenceNumber read is safe here
+      val stopTime = System.currentTimeMillis().toDouble()
+      val totalDuration = stopTime - startTime
+      onEnd?.invoke(stopTime, totalDuration, sequenceNumber)
+
+      // Destroy encoder on the same thread that used it
+      opusEncoder?.destroy()
+      opusEncoder = null
+      pendingSamples.clear()
+      pcmFileOutputStream?.close()
+      pcmFileOutputStream = null
+      done.countDown()
+    }
+    done.await()
+
+    handlerThread?.quitSafely()
+    handlerThread = null
+    handler = null
+
+    Log.d(TAG, "Flushed and stopped")
+  }
+
+  // MARK: - Event callback setters
+
+  fun setOnAudioChunk(callback: (List<EncodedFrame>, Double, Int, Double, Int) -> Unit) {
+    this.onAudioChunk = callback
+  }
+
+  fun setOnStarted(callback: (timestamp: Double, sampleRate: Int, channels: Int, bitrate: Int, frameSize: Double, preSkip: Int) -> Unit) {
+    this.onStarted = callback
+  }
+
+  fun setOnEnd(callback: (timestamp: Double, totalDuration: Double, totalPackets: Int) -> Unit) {
+    this.onEnd = callback
+  }
+
+  // MARK: - Encoding thread internals (all below only called on HandlerThread)
+
+  private fun _initEncoder() {
+    opusEncoder = OpusEncoder(
+      sampleRate = config.sampleRate,
+      channels = config.channels,
+      bitrate = config.bitrate,
+      frameSizeMs = config.frameSize,
+      dredDurationMs = config.dredDuration
+    )
+    Log.d(TAG, "Opus encoder created, preSkip=${opusEncoder?.preSkip}")
+  }
+
+  private fun _processFrames() {
+    val encoder = opusEncoder ?: return
+
+    while (pendingSamples.size >= samplesPerFrame) {
+      val frameData = ShortArray(samplesPerFrame)
+      for (i in 0 until samplesPerFrame) {
+        frameData[i] = pendingSamples.removeAt(0)
+      }
+
+      // Debug PCM file
+      pcmFileOutputStream?.let { fos ->
+        val bytes = ByteArray(frameData.size * 2)
+        java.nio.ByteBuffer.wrap(bytes).order(java.nio.ByteOrder.LITTLE_ENDIAN).asShortBuffer().put(frameData)
+        fos.write(bytes)
+      }
+
+      // Encode single frame to Opus
+      val opusData = try {
+        encoder.encode(frameData, samplesPerFrame)
+      } catch (e: Exception) {
+        Log.e(TAG, "Opus encode error: ${e.message}")
+        continue
+      }
+
+      if (opusData == null || opusData.isEmpty()) {
+        Log.w(TAG, "Opus encode returned null/empty")
+        continue
+      }
+
+      // Per-frame audio level (RMS → dBFS → 0~1)
+      var frameLevel: Float? = null
+      if (enableAudioLevel) {
+        var sumSquares = 0.0
+        for (sample in frameData) {
+          val s = sample.toDouble() / 32768.0
+          sumSquares += s * s
+        }
+        val rms = Math.sqrt(sumSquares / frameData.size)
+        val dB = 20.0 * Math.log10(Math.max(rms, 1e-10))
+        val dbFloor = -35.0
+        val dbCeiling = -6.0
+        frameLevel = Math.max(0.0, Math.min(1.0, (dB - dbFloor) / (dbCeiling - dbFloor))).toFloat()
+      }
+
+      // Accumulate encoded frame as an independent packet (no byte concatenation)
+      packetFrames.add(EncodedFrame(data = opusData, audioLevel = frameLevel))
+
+      // Emit when we have enough frames (framesPerCallback)
+      if (packetFrames.size >= framesPerPacket) {
+        val timestampMs = System.currentTimeMillis().toDouble()
+        val frameCount = packetFrames.size
+        val duration = frameCount * config.frameSize
+        onAudioChunk?.invoke(packetFrames.toList(), timestampMs, sequenceNumber, duration, frameCount)
+        sequenceNumber++
+        packetFrames.clear()
+      }
+    }
+  }
+
+  private fun _flushRemainingFrames() {
+    val encoder = opusEncoder ?: return
+
+    // Pad remaining PCM with silence to fill the last frame
+    if (pendingSamples.isNotEmpty() && pendingSamples.size < samplesPerFrame) {
+      while (pendingSamples.size < samplesPerFrame) {
+        pendingSamples.add(0)
+      }
+    }
+
+    // Encode remaining frames
+    while (pendingSamples.size >= samplesPerFrame) {
+      val frameData = ShortArray(samplesPerFrame)
+      for (i in 0 until samplesPerFrame) {
+        frameData[i] = pendingSamples.removeAt(0)
+      }
+
+      val opusData = try {
+        encoder.encode(frameData, samplesPerFrame)
+      } catch (e: Exception) {
+        continue
+      }
+
+      if (opusData == null || opusData.isEmpty()) continue
+      // Flush frames get level 0 (silence-padded)
+      packetFrames.add(EncodedFrame(data = opusData, audioLevel = if (enableAudioLevel) 0.0f else null))
+    }
+
+    // Flush any remaining frames (even if fewer than framesPerPacket)
+    if (packetFrames.isNotEmpty()) {
+      val timestampMs = System.currentTimeMillis().toDouble()
+      val frameCount = packetFrames.size
+      val duration = frameCount * config.frameSize
+      onAudioChunk?.invoke(packetFrames.toList(), timestampMs, sequenceNumber, duration, frameCount)
+      sequenceNumber++
+      packetFrames.clear()
+    }
+  }
+}