opuslib 0.1.4 → 0.2.0

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

@@ -6,19 +6,16 @@ import android.media.AudioRecord
 import android.media.MediaRecorder
 import android.util.Log
 import java.io.File
-import java.io.FileOutputStream
-import java.nio.ByteBuffer
-import java.nio.ByteOrder
 import kotlin.concurrent.thread
 
 /**
- * AudioRecordManager - Manages AudioRecord for real-time audio capture with Opus 1.6.1 DRED
+ * AudioRecordManager - Manages AudioRecord for real-time audio capture.
  *
- * This class handles:
- * - AudioRecord setup and lifecycle
- * - Real-time PCM audio capture
- * - Opus 1.6.1 encoding with DRED support
- * - Background recording thread management
+ * This class is responsible only for audio capture: it owns the AudioRecord
+ * lifecycle and runs the PCM read loop. All Opus 1.6.1 encoding is delegated to
+ * AudioProcessor, which runs on a separate dedicated encoding thread. The
+ * capture thread calls processor.pushSamples(), which copies the PCM and posts
+ * it to the encoding thread, so the read loop never blocks on encoding.
  */
 class AudioRecordManager(
   private val context: Context,
@@ -32,28 +29,21 @@ class AudioRecordManager(
   private var audioRecord: AudioRecord? = null
   private var recordingThread: Thread? = null
 
-  // Opus encoder
-  private var opusEncoder: OpusEncoder? = null
+  // Encoding processor (owns the encoder, runs on a separate HandlerThread)
+  private var processor: AudioProcessor? = null
 
   // State
   private var isRecording = false
   private var isPaused = false
-  private var sequenceNumber = 0
   private var loggedFirstBuffer = false
 
-  // Frame accumulation for packet duration
-  private val frameBuffer = mutableListOf<ShortArray>()
-  private val framesPerPacket: Int = (config.packetDuration / config.frameSize).toInt()
-
   // Event callbacks
-  private var onAudioChunk: ((ByteArray, Double, Int) -> Unit)? = null
+  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
   private var onAmplitude: ((Float, Float, Double) -> Unit)? = null
   private var onError: ((Exception) -> Unit)? = null
 
-  // Debug file output
-  private var pcmFileOutputStream: FileOutputStream? = null
-  private var pcmFile: File? = null
-
   // MARK: - Public Methods
 
   fun start() {
@@ -61,16 +51,6 @@ class AudioRecordManager(
       throw AudioStreamException("ALREADY_STREAMING", "Already recording")
     }
 
-    // Create Opus encoder with DRED support
-    val dredDuration = config.dredDuration
-    opusEncoder = OpusEncoder(
-      sampleRate = config.sampleRate,
-      channels = config.channels,
-      bitrate = config.bitrate,
-      frameSizeMs = config.frameSize,
-      dredDurationMs = dredDuration
-    )
-
     // Calculate buffer size
     val samplesPerFrame = (config.sampleRate * config.frameSize / 1000.0).toInt()
     val bufferSize = samplesPerFrame * 2 // 2 bytes per sample (Int16)
@@ -118,33 +98,48 @@ class AudioRecordManager(
       )
     }
 
-    // Create debug output file if enabled
-    if (config.saveDebugAudio) {
-      try {
-        val timestamp = System.currentTimeMillis()
-        pcmFile = File(context.filesDir, "debug_pcm_$timestamp.raw")
-        pcmFileOutputStream = FileOutputStream(pcmFile)
-        Log.d(TAG, "Debug PCM file created: ${pcmFile?.absolutePath}")
-      } catch (e: Exception) {
-        Log.e(TAG, "Failed to create debug file: ${e.message}")
-      }
+    // Create and start AudioProcessor (encoding thread). It owns the encoder and
+    // emits audioStarted (with preSkip) once the encoder is ready.
+    val proc = AudioProcessor(config)
+    proc.setOnAudioChunk { frames, timestamp, seq, duration, frameCount ->
+      onAudioChunk?.invoke(frames, timestamp, seq, duration, frameCount)
     }
+    proc.setOnStarted { timestamp, sampleRate, channels, bitrate, frameSize, preSkip ->
+      onStarted?.invoke(timestamp, sampleRate, channels, bitrate, frameSize, preSkip)
+    }
+    proc.setOnEnd { timestamp, totalDuration, totalPackets ->
+      onEnd?.invoke(timestamp, totalDuration, totalPackets)
+    }
+
+    // Debug PCM file (written on the encoding thread, per frame)
+    val debugFile = if (config.saveDebugAudio) {
+      val timestamp = System.currentTimeMillis()
+      File(context.filesDir, "debug_pcm_$timestamp.raw").also {
+        Log.d(TAG, "Debug PCM file: ${it.absolutePath}")
+      }
+    } else null
+
+    proc.start(debugFile)
+    processor = proc
 
     // Start recording
     try {
       record.startRecording()
     } catch (e: Exception) {
+      // Tear down the encoding thread we just started before bailing out
+      proc.flushAndStop()
+      processor = null
       throw AudioStreamException("AUDIO_RECORD_ERROR", "Failed to start recording: ${e.message}")
     }
 
     isRecording = true
 
-    // Start recording thread
+    // Start capture thread — only reads PCM and pushes to the processor
     recordingThread = thread(start = true, name = "AudioRecordThread") {
-      recordAudioLoop(record, samplesPerFrame)
+      captureLoop(record, samplesPerFrame)
     }
 
-    Log.d(TAG, "Started recording: ${config.sampleRate}Hz, ${config.channels}ch, DRED: ${dredDuration}ms")
+    Log.d(TAG, "Started recording: ${config.sampleRate}Hz, ${config.channels}ch, DRED: ${config.dredDuration}ms")
   }
 
   fun stop() {
@@ -154,7 +149,7 @@ class AudioRecordManager(
 
     isRecording = false
 
-    // Stop recording
+    // Stop AudioRecord
     audioRecord?.let { record ->
       try {
         if (record.recordingState == AudioRecord.RECORDSTATE_RECORDING) {
@@ -165,26 +160,20 @@ class AudioRecordManager(
       }
     }
 
-    // Wait for recording thread to finish
+    // Wait for capture thread to finish
     recordingThread?.join(1000)
     recordingThread = null
 
-    // Release resources
+    // Flush and stop the encoding thread (synchronous — drains remaining
+    // samples, pads the final partial frame with silence, emits audioEnd).
+    processor?.flushAndStop()
+    processor = null
+
+    // Release AudioRecord
     audioRecord?.release()
     audioRecord = null
 
-    opusEncoder?.destroy()
-    opusEncoder = null
-
-    frameBuffer.clear()
-    sequenceNumber = 0
-
-    // Close debug file
-    pcmFileOutputStream?.close()
-    pcmFileOutputStream = null
-    if (pcmFile != null) {
-      Log.d(TAG, "Closed PCM debug file: ${pcmFile?.absolutePath}")
-    }
+    loggedFirstBuffer = false
 
     Log.d(TAG, "Stopped recording")
   }
@@ -201,10 +190,18 @@ class AudioRecordManager(
 
   // MARK: - Event Handlers
 
-  fun setOnAudioChunk(callback: (ByteArray, Double, Int) -> Unit) {
+  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
+  }
+
   fun setOnAmplitude(callback: (Float, Float, Double) -> Unit) {
     this.onAmplitude = callback
   }
@@ -213,12 +210,12 @@ class AudioRecordManager(
     this.onError = callback
   }
 
-  // MARK: - Private Methods
+  // MARK: - Capture thread (only reads PCM, no encoding)
 
-  private fun recordAudioLoop(record: AudioRecord, samplesPerFrame: Int) {
+  private fun captureLoop(record: AudioRecord, samplesPerFrame: Int) {
     val buffer = ShortArray(samplesPerFrame)
 
-    Log.d(TAG, "Recording thread started, frame size: $samplesPerFrame samples")
+    Log.d(TAG, "Capture thread started, frame size: $samplesPerFrame samples")
 
     while (isRecording) {
       try {
@@ -232,7 +229,7 @@ class AudioRecordManager(
         }
 
         if (samplesRead == 0) {
-          // No data available, continue
+          // No data available, wait briefly and retry
           Thread.sleep(10)
           continue
         }
@@ -248,99 +245,19 @@ class AudioRecordManager(
           continue
         }
 
-        // Write to debug file if enabled
-        pcmFileOutputStream?.let { fos ->
-          val byteBuffer = ByteBuffer.allocate(samplesRead * 2)
-          byteBuffer.order(ByteOrder.LITTLE_ENDIAN)
-          for (i in 0 until samplesRead) {
-            byteBuffer.putShort(buffer[i])
-          }
-          fos.write(byteBuffer.array())
-        }
-
-        // Process the buffer
-        processBuffer(buffer.copyOf(samplesRead))
+        // Copy + post to the encoding thread (never blocks the capture loop)
+        processor?.pushSamples(buffer, samplesRead)
 
       } catch (e: InterruptedException) {
-        Log.d(TAG, "Recording thread interrupted")
+        Log.d(TAG, "Capture thread interrupted")
         break
       } catch (e: Exception) {
-        Log.e(TAG, "Error in recording loop: ${e.message}", e)
+        Log.e(TAG, "Error in capture loop: ${e.message}", e)
         onError?.invoke(e)
         break
       }
     }
 
-    Log.d(TAG, "Recording thread stopped")
-  }
-
-  private fun processBuffer(pcmData: ShortArray) {
-    // Add to frame buffer
-    frameBuffer.add(pcmData)
-
-    // Calculate how many samples we need for one packet
-    val samplesPerPacket = (config.sampleRate * config.packetDuration / 1000.0).toInt()
-    val currentSampleCount = frameBuffer.sumOf { it.size }
-
-    // When we have enough samples for a packet, encode and send
-    if (currentSampleCount >= samplesPerPacket) {
-      encodeAndSendPacket()
-    }
-  }
-
-  private fun encodeAndSendPacket() {
-    val encoder = opusEncoder ?: return
-
-    // Flatten frame buffer into continuous PCM data
-    val pcmData = ShortArray(frameBuffer.sumOf { it.size })
-    var offset = 0
-    for (frame in frameBuffer) {
-      frame.copyInto(pcmData, offset)
-      offset += frame.size
-    }
-
-    // Calculate samples per frame
-    val samplesPerFrame = (config.sampleRate * config.frameSize / 1000.0).toInt()
-
-    // We should only encode when we have at least one frame
-    if (pcmData.size < samplesPerFrame) {
-      return
-    }
-
-    // Take only ONE frame worth of samples
-    val frameData = pcmData.copyOfRange(0, samplesPerFrame)
-
-    // Encode this single frame to Opus (with DRED padding if enabled)
-    val opusData = try {
-      encoder.encode(frameData, samplesPerFrame)
-    } catch (e: Exception) {
-      Log.e(TAG, "Failed to encode Opus packet: ${e.message}")
-      frameBuffer.clear()
-      return
-    }
-
-    if (opusData == null || opusData.isEmpty()) {
-      Log.w(TAG, "Failed to encode Opus packet (null or empty)")
-      frameBuffer.clear()
-      return
-    }
-
-    // Calculate timestamp in milliseconds
-    val timestampMs = System.currentTimeMillis().toDouble()
-
-    // Emit audioChunk event with Opus packet (may be larger due to DRED)
-    onAudioChunk?.invoke(opusData, timestampMs, sequenceNumber)
-
-    sequenceNumber++
-
-    // Keep any remaining samples for next packet
-    val remainingSamples = pcmData.size - samplesPerFrame
-    if (remainingSamples > 0) {
-      val remaining = pcmData.copyOfRange(samplesPerFrame, pcmData.size)
-      frameBuffer.clear()
-      frameBuffer.add(remaining)
-    } else {
-      frameBuffer.clear()
-    }
+    Log.d(TAG, "Capture thread stopped")
   }
 }

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

@@ -35,6 +35,14 @@ class OpusEncoder(
   val frameSize: Int = (sampleRate * frameSizeMs / 1000.0).toInt()
   private var encoderPtr: Long = 0
 
+  /**
+   * Encoder lookahead (pre-skip) in samples. Decoders should skip this many
+   * samples at the start of the stream to account for the encoder's
+   * algorithmic delay.
+   */
+  var preSkip: Int = 0
+    private set
+
   init {
     // Create native encoder
     encoderPtr = nativeCreate(sampleRate, channels, bitrate, dredDurationMs)
@@ -42,12 +50,16 @@ class OpusEncoder(
       throw RuntimeException("Failed to create Opus encoder")
     }
 
+    // Read encoder lookahead (pre-skip)
+    preSkip = nativeGetLookahead(encoderPtr)
+
     Log.i(TAG, """
       Opus encoder initialized:
         - Sample rate: ${sampleRate}Hz
         - Channels: $channels
         - Bitrate: ${bitrate / 1000}kbps
         - Frame size: $frameSize samples (${frameSizeMs}ms)
+        - Pre-skip: $preSkip samples
         - DRED: ${dredDurationMs}ms
     """.trimIndent())
   }
@@ -100,4 +112,6 @@ class OpusEncoder(
   ): ByteArray?
 
   private external fun nativeDestroy(encoderPtr: Long)
+
+  private external fun nativeGetLookahead(encoderPtr: Long): Int
 }

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

@@ -23,7 +23,7 @@ class OpuslibModule : Module() {
     Name("Opuslib")
 
     // Events
-    Events("audioChunk", "amplitude", "error")
+    Events("audioChunk", "amplitude", "audioStarted", "audioEnd", "error")
 
     // Start streaming method
     AsyncFunction("startStreaming") { config: AudioConfig ->
@@ -79,13 +79,43 @@ class OpuslibModule : Module() {
     val manager = AudioRecordManager(context, config)
     android.util.Log.d(TAG, "✅ AudioRecordManager created")
 
-    // Set up event callbacks
+    // Set up event callbacks — audioStarted/audioEnd come from the encoding thread
     android.util.Log.d(TAG, "🔗 Setting up event callbacks...")
-    manager.setOnAudioChunk { data, timestamp, sequenceNumber ->
+    manager.setOnAudioChunk { frames, timestamp, sequenceNumber, duration, frameCount ->
+      // Each frame is an independent Opus packet wrapped in { data, audioLevel? }.
+      val frameObjects = frames.map { frame ->
+        val obj = mutableMapOf<String, Any>("data" to frame.data)
+        frame.audioLevel?.let { obj["audioLevel"] = it }
+        obj
+      }
+      // `data` is kept for backward compatibility: the FIRST frame's Opus packet,
+      // sent in the same ByteArray representation existing consumers already read.
       sendEvent("audioChunk", mapOf(
-        "data" to data,
+        "data" to frames.first().data,
+        "frames" to frameObjects,
         "timestamp" to timestamp,
-        "sequenceNumber" to sequenceNumber
+        "sequenceNumber" to sequenceNumber,
+        "duration" to duration,
+        "frameCount" to frameCount
+      ))
+    }
+
+    manager.setOnStarted { timestamp, sampleRate, channels, bitrate, frameSize, preSkip ->
+      sendEvent("audioStarted", mapOf(
+        "timestamp" to timestamp,
+        "sampleRate" to sampleRate,
+        "channels" to channels,
+        "bitrate" to bitrate,
+        "frameSize" to frameSize,
+        "preSkip" to preSkip
+      ))
+    }
+
+    manager.setOnEnd { timestamp, totalDuration, totalPackets ->
+      sendEvent("audioEnd", mapOf(
+        "timestamp" to timestamp,
+        "totalDuration" to totalDuration,
+        "totalPackets" to totalPackets
       ))
     }
 
@@ -121,6 +151,7 @@ class OpuslibModule : Module() {
       return
     }
 
+    // stop() flushes the encoding thread and emits audioEnd before tearing down.
     audioRecordManager?.stop()
     audioRecordManager = null
     isStreaming = false
@@ -169,9 +200,16 @@ class AudioConfig : Record {
   @Field
   var frameSize: Double = 20.0
 
+  // Legacy field, still accepted from existing callers. Superseded by
+  // framesPerCallback; kept so existing configs continue to deserialize.
   @Field
   var packetDuration: Double = 20.0
 
+  // Number of independent Opus frames batched into one audioChunk event.
+  // Defaults to 1 to match the previous one-frame-per-event behavior.
+  @Field
+  var framesPerCallback: Int = 1
+
   @Field
   var dredDuration: Int = 100  // NEW: DRED recovery duration in ms
 
@@ -181,6 +219,10 @@ class AudioConfig : Record {
   @Field
   var amplitudeEventInterval: Double = 16.0
 
+  // Per-frame audio level (RMS-derived, 0.0..1.0) attached to each frame.
+  @Field
+  var enableAudioLevel: Boolean = false
+
   @Field
   var saveDebugAudio: Boolean = false
 }

package/build/Opuslib.types.d.ts

@@ -12,25 +12,90 @@ export interface AudioConfig {
     frameSize: number;
     /** Packet duration in milliseconds (typically 20-100ms) */
     packetDuration: number;
+    /**
+     * Number of independently-encoded Opus frames to batch into a single
+     * `audioChunk` event (default 1). Each entry in `AudioChunkEvent.frames` is a
+     * complete, independently decodable Opus packet — frames are never
+     * concatenated. Batching reduces the number of bridge calls.
+     */
+    framesPerCallback?: number;
     /** DRED recovery duration in milliseconds (0-100, default 100) - NEW in Opus 1.6 */
     dredDuration?: number;
     /** Enable amplitude events for waveform visualization */
     enableAmplitudeEvents?: boolean;
     /** Amplitude event interval in milliseconds (default 16) */
     amplitudeEventInterval?: number;
+    /**
+     * Enable per-frame audio level calculation (default false). When enabled,
+     * each `OpusFrame` carries an `audioLevel` (0.0 - 1.0) derived from RMS.
+     * Disabled by default to save computation.
+     */
+    enableAudioLevel?: boolean;
     /** Save debug PCM audio to file (development only) */
     saveDebugAudio?: boolean;
+    /**
+     * iOS AudioSession configuration (iOS only; ignored on Android and web).
+     * Omit to keep the default recording session
+     * (`record` category, `measurement` mode, no options).
+     */
+    iosAudioSession?: IOSAudioSessionConfig;
+}
+/**
+ * iOS `AVAudioSession` configuration. iOS only — ignored on Android and web.
+ */
+export interface IOSAudioSessionConfig {
+    /**
+     * `AVAudioSession.Category`
+     * - `record`: pure recording (default)
+     * - `playAndRecord`: record and play simultaneously
+     * - `playback`: playback only
+     * - `ambient`: mix with other audio without interrupting it
+     */
+    category: 'record' | 'playAndRecord' | 'playback' | 'ambient';
+    /**
+     * `AVAudioSession.Mode`
+     * - `measurement`: disable system audio processing (default)
+     * - `default`: enable system audio processing (AGC, echo cancellation)
+     * - `voiceChat`: optimized for voice calls
+     * - `spokenAudio`: optimized for spoken content
+     */
+    mode: 'default' | 'voiceChat' | 'measurement' | 'spokenAudio';
+    /** `AVAudioSession.CategoryOptions` (combinable) */
+    options?: ('mixWithOthers' | 'defaultToSpeaker' | 'allowBluetooth' | 'allowAirPlay' | 'allowBluetoothA2DP')[];
+}
+/**
+ * A single Opus frame — one complete `opus_encode()` output with its own TOC
+ * byte, decodable on its own.
+ */
+export interface OpusFrame {
+    /** Opus-encoded packet data (independent, decodable) */
+    data: ArrayBuffer;
+    /** Per-frame audio level (0.0 - 1.0). Present only when `enableAudioLevel` is true. */
+    audioLevel?: number;
 }
 /**
  * Audio chunk event payload (Opus-encoded data)
  */
 export interface AudioChunkEvent {
-    /** Opus-encoded audio data as ArrayBuffer */
+    /**
+     * The first frame's Opus packet, kept for backward compatibility — equivalent
+     * to `frames[0].data`. With the default `framesPerCallback` of 1 this is the
+     * single packet for the event. Prefer `frames` for new code.
+     */
     data: ArrayBuffer;
+    /**
+     * Independently decodable Opus packets in this event (one per encoded frame).
+     * Contains a single entry unless `framesPerCallback` > 1.
+     */
+    frames: OpusFrame[];
     /** Timestamp in milliseconds */
     timestamp: number;
-    /** Sequence number (increments with each packet) */
+    /** Sequence number (increments with each event) */
     sequenceNumber: number;
+    /** Duration of all frames in milliseconds (`frameSize * frameCount`) */
+    duration: number;
+    /** Number of Opus frames in this event (= `frames.length`) */
+    frameCount: number;
 }
 /**
  * Amplitude event payload (for waveform visualization)
@@ -43,6 +108,35 @@ export interface AmplitudeEvent {
     /** Timestamp in milliseconds */
     timestamp: number;
 }
+/**
+ * Audio started event payload. Emitted once when streaming begins.
+ */
+export interface AudioStartedEvent {
+    /** Timestamp in milliseconds when streaming started */
+    timestamp: number;
+    /** Actual sample rate in Hz */
+    sampleRate: number;
+    /** Number of channels */
+    channels: number;
+    /** Configured bitrate in bits/second */
+    bitrate: number;
+    /** Frame duration in milliseconds */
+    frameSize: number;
+    /** Opus encoder lookahead in samples — decoders should skip this many samples at the start */
+    preSkip: number;
+}
+/**
+ * Audio end event payload. Emitted once when streaming stops, after the final
+ * buffered audio has been flushed.
+ */
+export interface AudioEndEvent {
+    /** Timestamp in milliseconds when streaming stopped */
+    timestamp: number;
+    /** Total session duration in milliseconds */
+    totalDuration: number;
+    /** Total number of packets (audioChunk events) emitted during the session */
+    totalPackets: number;
+}
 /**
  * Error event payload
  */

package/build/Opuslib.types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Opuslib.types.d.ts","sourceRoot":"","sources":["../src/Opuslib.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAA;IACtB,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,4DAA4D;IAC5D,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B,sDAAsD;IACtD,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,6CAA6C;IAC7C,IAAI,EAAE,WAAW,CAAA;IACjB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,cAAc,EAAE,MAAM,CAAA;CACvB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAA;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB"}
+{"version":3,"file":"Opuslib.types.d.ts","sourceRoot":"","sources":["../src/Opuslib.types.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,CAAA;IAChB,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAA;IACf,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAA;IACjB,2DAA2D;IAC3D,cAAc,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;IAC1B,oFAAoF;IACpF,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,yDAAyD;IACzD,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,4DAA4D;IAC5D,sBAAsB,CAAC,EAAE,MAAM,CAAA;IAC/B;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,sDAAsD;IACtD,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB;;;;OAIG;IACH,eAAe,CAAC,EAAE,qBAAqB,CAAA;CACxC;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;;;;OAMG;IACH,QAAQ,EAAE,QAAQ,GAAG,eAAe,GAAG,UAAU,GAAG,SAAS,CAAA;IAC7D;;;;;;OAMG;IACH,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,aAAa,GAAG,aAAa,CAAA;IAC7D,oDAAoD;IACpD,OAAO,CAAC,EAAE,CACN,eAAe,GACf,kBAAkB,GAClB,gBAAgB,GAChB,cAAc,GACd,oBAAoB,CACvB,EAAE,CAAA;CACJ;AAED;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,wDAAwD;IACxD,IAAI,EAAE,WAAW,CAAA;IACjB,uFAAuF;IACvF,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;OAIG;IACH,IAAI,EAAE,WAAW,CAAA;IACjB;;;OAGG;IACH,MAAM,EAAE,SAAS,EAAE,CAAA;IACnB,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;IACjB,mDAAmD;IACnD,cAAc,EAAE,MAAM,CAAA;IACtB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAA;IAChB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,CAAA;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,6CAA6C;IAC7C,GAAG,EAAE,MAAM,CAAA;IACX,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,gCAAgC;IAChC,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,+BAA+B;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,yBAAyB;IACzB,QAAQ,EAAE,MAAM,CAAA;IAChB,wCAAwC;IACxC,OAAO,EAAE,MAAM,CAAA;IACf,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAA;IACjB,8FAA8F;IAC9F,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,6CAA6C;IAC7C,aAAa,EAAE,MAAM,CAAA;IACrB,6EAA6E;IAC7E,YAAY,EAAE,MAAM,CAAA;CACrB;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,iBAAiB;IACjB,IAAI,EAAE,MAAM,CAAA;IACZ,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,IAAI,CAAA;CACnB"}

package/build/Opuslib.types.js.map

@@ -1 +1 @@
-{"version":3,"file":"Opuslib.types.js","sourceRoot":"","sources":["../src/Opuslib.types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Audio configuration for Opus encoding\n */\nexport interface AudioConfig {\n  /** Sample rate in Hz (8000, 12000, 16000, 24000, 48000) */\n  sampleRate: number\n  /** Number of channels (1 = mono, 2 = stereo) */\n  channels: number\n  /** Target bitrate in bits/second (e.g., 24000 for 24kbps) */\n  bitrate: number\n  /** Frame duration in milliseconds (2.5, 5, 10, 20, 40, 60) */\n  frameSize: number\n  /** Packet duration in milliseconds (typically 20-100ms) */\n  packetDuration: number\n  /** DRED recovery duration in milliseconds (0-100, default 100) - NEW in Opus 1.6 */\n  dredDuration?: number\n  /** Enable amplitude events for waveform visualization */\n  enableAmplitudeEvents?: boolean\n  /** Amplitude event interval in milliseconds (default 16) */\n  amplitudeEventInterval?: number\n  /** Save debug PCM audio to file (development only) */\n  saveDebugAudio?: boolean\n}\n\n/**\n * Audio chunk event payload (Opus-encoded data)\n */\nexport interface AudioChunkEvent {\n  /** Opus-encoded audio data as ArrayBuffer */\n  data: ArrayBuffer\n  /** Timestamp in milliseconds */\n  timestamp: number\n  /** Sequence number (increments with each packet) */\n  sequenceNumber: number\n}\n\n/**\n * Amplitude event payload (for waveform visualization)\n */\nexport interface AmplitudeEvent {\n  /** Root mean square amplitude (0.0 - 1.0) */\n  rms: number\n  /** Peak amplitude (0.0 - 1.0) */\n  peak: number\n  /** Timestamp in milliseconds */\n  timestamp: number\n}\n\n/**\n * Error event payload\n */\nexport interface ErrorEvent {\n  /** Error code */\n  code: string\n  /** Error message */\n  message: string\n}\n\n/**\n * Event subscription\n */\nexport interface Subscription {\n  remove: () => void\n}\n"]}
+{"version":3,"file":"Opuslib.types.js","sourceRoot":"","sources":["../src/Opuslib.types.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Audio configuration for Opus encoding\n */\nexport interface AudioConfig {\n  /** Sample rate in Hz (8000, 12000, 16000, 24000, 48000) */\n  sampleRate: number\n  /** Number of channels (1 = mono, 2 = stereo) */\n  channels: number\n  /** Target bitrate in bits/second (e.g., 24000 for 24kbps) */\n  bitrate: number\n  /** Frame duration in milliseconds (2.5, 5, 10, 20, 40, 60) */\n  frameSize: number\n  /** Packet duration in milliseconds (typically 20-100ms) */\n  packetDuration: number\n  /**\n   * Number of independently-encoded Opus frames to batch into a single\n   * `audioChunk` event (default 1). Each entry in `AudioChunkEvent.frames` is a\n   * complete, independently decodable Opus packet — frames are never\n   * concatenated. Batching reduces the number of bridge calls.\n   */\n  framesPerCallback?: number\n  /** DRED recovery duration in milliseconds (0-100, default 100) - NEW in Opus 1.6 */\n  dredDuration?: number\n  /** Enable amplitude events for waveform visualization */\n  enableAmplitudeEvents?: boolean\n  /** Amplitude event interval in milliseconds (default 16) */\n  amplitudeEventInterval?: number\n  /**\n   * Enable per-frame audio level calculation (default false). When enabled,\n   * each `OpusFrame` carries an `audioLevel` (0.0 - 1.0) derived from RMS.\n   * Disabled by default to save computation.\n   */\n  enableAudioLevel?: boolean\n  /** Save debug PCM audio to file (development only) */\n  saveDebugAudio?: boolean\n  /**\n   * iOS AudioSession configuration (iOS only; ignored on Android and web).\n   * Omit to keep the default recording session\n   * (`record` category, `measurement` mode, no options).\n   */\n  iosAudioSession?: IOSAudioSessionConfig\n}\n\n/**\n * iOS `AVAudioSession` configuration. iOS only — ignored on Android and web.\n */\nexport interface IOSAudioSessionConfig {\n  /**\n   * `AVAudioSession.Category`\n   * - `record`: pure recording (default)\n   * - `playAndRecord`: record and play simultaneously\n   * - `playback`: playback only\n   * - `ambient`: mix with other audio without interrupting it\n   */\n  category: 'record' | 'playAndRecord' | 'playback' | 'ambient'\n  /**\n   * `AVAudioSession.Mode`\n   * - `measurement`: disable system audio processing (default)\n   * - `default`: enable system audio processing (AGC, echo cancellation)\n   * - `voiceChat`: optimized for voice calls\n   * - `spokenAudio`: optimized for spoken content\n   */\n  mode: 'default' | 'voiceChat' | 'measurement' | 'spokenAudio'\n  /** `AVAudioSession.CategoryOptions` (combinable) */\n  options?: (\n    | 'mixWithOthers'\n    | 'defaultToSpeaker'\n    | 'allowBluetooth'\n    | 'allowAirPlay'\n    | 'allowBluetoothA2DP'\n  )[]\n}\n\n/**\n * A single Opus frame — one complete `opus_encode()` output with its own TOC\n * byte, decodable on its own.\n */\nexport interface OpusFrame {\n  /** Opus-encoded packet data (independent, decodable) */\n  data: ArrayBuffer\n  /** Per-frame audio level (0.0 - 1.0). Present only when `enableAudioLevel` is true. */\n  audioLevel?: number\n}\n\n/**\n * Audio chunk event payload (Opus-encoded data)\n */\nexport interface AudioChunkEvent {\n  /**\n   * The first frame's Opus packet, kept for backward compatibility — equivalent\n   * to `frames[0].data`. With the default `framesPerCallback` of 1 this is the\n   * single packet for the event. Prefer `frames` for new code.\n   */\n  data: ArrayBuffer\n  /**\n   * Independently decodable Opus packets in this event (one per encoded frame).\n   * Contains a single entry unless `framesPerCallback` > 1.\n   */\n  frames: OpusFrame[]\n  /** Timestamp in milliseconds */\n  timestamp: number\n  /** Sequence number (increments with each event) */\n  sequenceNumber: number\n  /** Duration of all frames in milliseconds (`frameSize * frameCount`) */\n  duration: number\n  /** Number of Opus frames in this event (= `frames.length`) */\n  frameCount: number\n}\n\n/**\n * Amplitude event payload (for waveform visualization)\n */\nexport interface AmplitudeEvent {\n  /** Root mean square amplitude (0.0 - 1.0) */\n  rms: number\n  /** Peak amplitude (0.0 - 1.0) */\n  peak: number\n  /** Timestamp in milliseconds */\n  timestamp: number\n}\n\n/**\n * Audio started event payload. Emitted once when streaming begins.\n */\nexport interface AudioStartedEvent {\n  /** Timestamp in milliseconds when streaming started */\n  timestamp: number\n  /** Actual sample rate in Hz */\n  sampleRate: number\n  /** Number of channels */\n  channels: number\n  /** Configured bitrate in bits/second */\n  bitrate: number\n  /** Frame duration in milliseconds */\n  frameSize: number\n  /** Opus encoder lookahead in samples — decoders should skip this many samples at the start */\n  preSkip: number\n}\n\n/**\n * Audio end event payload. Emitted once when streaming stops, after the final\n * buffered audio has been flushed.\n */\nexport interface AudioEndEvent {\n  /** Timestamp in milliseconds when streaming stopped */\n  timestamp: number\n  /** Total session duration in milliseconds */\n  totalDuration: number\n  /** Total number of packets (audioChunk events) emitted during the session */\n  totalPackets: number\n}\n\n/**\n * Error event payload\n */\nexport interface ErrorEvent {\n  /** Error code */\n  code: string\n  /** Error message */\n  message: string\n}\n\n/**\n * Event subscription\n */\nexport interface Subscription {\n  remove: () => void\n}\n"]}

package/build/OpuslibModule.d.ts

@@ -1,4 +1,4 @@
-import type { AudioConfig, AudioChunkEvent, AmplitudeEvent, ErrorEvent, Subscription } from './Opuslib.types';
+import type { AudioConfig, AudioChunkEvent, AmplitudeEvent, AudioStartedEvent, AudioEndEvent, ErrorEvent, Subscription } from './Opuslib.types';
 /**
  * Opuslib - Opus 1.6.1 Audio Encoding with DRED Support
  *
@@ -49,6 +49,14 @@ declare const _default: {
      *   websocket.send(event.data)
      * })
      *
+     * // Listen for session lifecycle
+     * Opuslib.addListener('audioStarted', (event) => {
+     *   console.log('Started; decoder pre-skip:', event.preSkip)
+     * })
+     * Opuslib.addListener('audioEnd', (event) => {
+     *   console.log(`Ended: ${event.totalPackets} packets in ${event.totalDuration}ms`)
+     * })
+     *
      * // Listen for errors
      * const errorSub = Opuslib.addListener('error', (event) => {
      *   console.error('Error:', event.message)
@@ -62,6 +70,8 @@ declare const _default: {
     addListener: {
         (eventName: "audioChunk", listener: (event: AudioChunkEvent) => void): Subscription;
         (eventName: "amplitude", listener: (event: AmplitudeEvent) => void): Subscription;
+        (eventName: "audioStarted", listener: (event: AudioStartedEvent) => void): Subscription;
+        (eventName: "audioEnd", listener: (event: AudioEndEvent) => void): Subscription;
         (eventName: "error", listener: (event: ErrorEvent) => void): Subscription;
     };
     /**
@@ -71,6 +81,23 @@ declare const _default: {
      * @returns Subscription object with remove() method
      */
     addAmplitudeListener: (listener: (event: AmplitudeEvent) => void) => Subscription;
+    /**
+     * Listen for the `audioStarted` event, emitted once when streaming begins.
+     * Carries the active config and the Opus encoder `preSkip` (lookahead) so a
+     * decoder knows how many samples to skip at the start of the stream.
+     *
+     * @param listener Event listener callback
+     * @returns Subscription object with remove() method
+     */
+    addAudioStartedListener: (listener: (event: AudioStartedEvent) => void) => Subscription;
+    /**
+     * Listen for the `audioEnd` event, emitted once when streaming stops (after
+     * the final buffered audio has been flushed). Carries the session summary.
+     *
+     * @param listener Event listener callback
+     * @returns Subscription object with remove() method
+     */
+    addAudioEndListener: (listener: (event: AudioEndEvent) => void) => Subscription;
     /**
      * Listen for error events
      *