opuslib 0.1.4 → 0.2.0

package/ios/AudioProcessor.swift

@@ -0,0 +1,246 @@
+import Foundation
+
+/**
+ * AudioProcessor - Dedicated encoding thread for Opus encoding and dispatch.
+ *
+ * The real-time audio tap must never block, and the Opus encoder is not safe to
+ * touch from multiple threads. This class isolates all encoder work onto a
+ * single serial queue:
+ * - The capture thread calls `pushSamples()`, which copies the PCM and posts it
+ *   to the encoding queue.
+ * - All mutable state (pendingSamples, encoder, sequenceNumber, level) is only
+ *   accessed on the encoding queue, so no locks are needed.
+ * - `audioStarted` / `audioEnd` events are emitted from the encoding queue, so
+ *   `preSkip` / `sequenceNumber` are read without cross-thread risk.
+ */
+
+/// A single encoded Opus frame with optional per-frame audio level
+struct EncodedFrame {
+  let data: Data
+  let audioLevel: Float?  // nil when enableAudioLevel is false
+}
+
+class AudioProcessor {
+  // Dedicated serial queue — all encoder access happens here
+  private let queue = DispatchQueue(label: "com.opuslib.encoding", qos: .userInitiated)
+
+  // All fields below are only accessed on `queue` — no locks needed
+  private var opusEncoder: OpusEncoder?
+  private var pendingSamples: [Int16] = []
+  private let samplesPerFrame: Int
+  private let framesPerPacket: Int  // how many frames to batch before emitting
+  private var packetFrames: [EncodedFrame] = []  // independent Opus packets with per-frame level
+  private var sequenceNumber: Int = 0
+  private var startTime: Double = 0
+
+  // Whether to compute per-frame audio level
+  private let enableAudioLevel: Bool
+
+  // Debug file
+  private var pcmFileHandle: FileHandle?
+
+  // Event callbacks (all invoked on the encoding queue)
+  // onAudioChunk: (frames, timestamp, sequenceNumber, duration, frameCount)
+  private var onAudioChunk: (([EncodedFrame], Double, Int, Double, Int) -> Void)?
+  private var onStarted: ((_ timestamp: Double, _ sampleRate: Int, _ channels: Int, _ bitrate: Int, _ frameSize: Double, _ preSkip: Int) -> Void)?
+  private var onEnd: ((_ timestamp: Double, _ totalDuration: Double, _ totalPackets: Int) -> Void)?
+
+  // Configuration (immutable)
+  private let config: AudioConfig
+
+  init(config: AudioConfig) {
+    self.config = config
+    self.samplesPerFrame = Int(Double(config.sampleRate) * config.frameSize / 1000.0)
+    let framesPerCallback = config.framesPerCallback ?? 1
+    self.framesPerPacket = max(1, framesPerCallback)
+    self.enableAudioLevel = config.enableAudioLevel ?? false
+  }
+
+  // MARK: - Public API
+
+  /**
+   * Start: create the Opus encoder on the encoding queue and emit audioStarted.
+   * All encoder init + preSkip read happen on the same thread — no cross-thread risk.
+   */
+  func start(debugFileURL: URL? = nil) throws {
+    var initError: Error?
+    queue.sync {
+      do {
+        self.opusEncoder = try OpusEncoder(
+          sampleRate: self.config.sampleRate,
+          channels: self.config.channels,
+          bitrate: self.config.bitrate,
+          frameSizeMs: self.config.frameSize,
+          dredDurationMs: self.config.dredDuration ?? 100
+        )
+      } catch {
+        initError = error
+        return
+      }
+
+      // Debug file
+      if let url = debugFileURL {
+        FileManager.default.createFile(atPath: url.path, contents: nil, attributes: nil)
+        self.pcmFileHandle = try? FileHandle(forWritingTo: url)
+      }
+
+      // Emit audioStarted on the encoding queue — preSkip read is safe here
+      self.startTime = Date().timeIntervalSince1970 * 1000
+      let preSkip = self.opusEncoder?.preSkip ?? 0
+      self.onStarted?(
+        self.startTime,
+        self.config.sampleRate,
+        self.config.channels,
+        self.config.bitrate,
+        self.config.frameSize,
+        preSkip
+      )
+    }
+
+    if let error = initError { throw error }
+
+    print("[AudioProcessor] Started: \(config.sampleRate)Hz, frame=\(samplesPerFrame) samples")
+  }
+
+  /**
+   * Push raw PCM samples from the capture thread (copy + post, no shared state).
+   */
+  func pushSamples(_ samples: [Int16]) {
+    queue.async { [weak self] in
+      guard let self = self else { return }
+      self.pendingSamples.append(contentsOf: samples)
+      self._processFrames()
+    }
+  }
+
+  /**
+   * Synchronously flush remaining audio, emit audioEnd, and destroy the encoder.
+   * All sequenceNumber/encoder access on the encoding queue — no cross-thread risk.
+   */
+  func flushAndStop() {
+    queue.sync {
+      self._flushRemainingFrames()
+
+      // Emit audioEnd on the encoding queue — sequenceNumber read is safe here
+      let stopTime = Date().timeIntervalSince1970 * 1000
+      let totalDuration = stopTime - self.startTime
+      self.onEnd?(stopTime, totalDuration, self.sequenceNumber)
+
+      // Destroy the encoder on the same thread that used it
+      self.opusEncoder = nil
+      self.pendingSamples.removeAll()
+      self.pcmFileHandle?.closeFile()
+      self.pcmFileHandle = nil
+    }
+
+    print("[AudioProcessor] Flushed and stopped")
+  }
+
+  // MARK: - Event callbacks
+
+  func setOnAudioChunk(_ callback: @escaping ([EncodedFrame], Double, Int, Double, Int) -> Void) {
+    self.onAudioChunk = callback
+  }
+
+  func setOnStarted(_ callback: @escaping (_ timestamp: Double, _ sampleRate: Int, _ channels: Int, _ bitrate: Int, _ frameSize: Double, _ preSkip: Int) -> Void) {
+    self.onStarted = callback
+  }
+
+  func setOnEnd(_ callback: @escaping (_ timestamp: Double, _ totalDuration: Double, _ totalPackets: Int) -> Void) {
+    self.onEnd = callback
+  }
+
+  // MARK: - Encoding queue internals (all below only called on `queue`)
+
+  private func _processFrames() {
+    guard let opusEncoder = opusEncoder else { return }
+
+    while pendingSamples.count >= samplesPerFrame {
+      let frameData = Array(pendingSamples.prefix(samplesPerFrame))
+      pendingSamples.removeFirst(samplesPerFrame)
+
+      // Debug PCM file
+      if let fileHandle = pcmFileHandle {
+        frameData.withUnsafeBufferPointer { ptr in
+          let data = Data(bytes: ptr.baseAddress!, count: frameData.count * MemoryLayout<Int16>.size)
+          fileHandle.write(data)
+        }
+      }
+
+      // Encode single frame to Opus
+      var encodedPacket: Data?
+      frameData.withUnsafeBufferPointer { bufferPointer in
+        guard let baseAddress = bufferPointer.baseAddress else { return }
+        encodedPacket = opusEncoder.encode(pcm: baseAddress, frameSize: samplesPerFrame)
+      }
+
+      guard let opusData = encodedPacket, !opusData.isEmpty else {
+        print("[AudioProcessor] Failed to encode Opus packet")
+        continue
+      }
+
+      // Per-frame audio level (RMS → dBFS → 0~1)
+      var frameLevel: Float? = nil
+      if enableAudioLevel {
+        var sumSquares: Double = 0.0
+        for sample in frameData {
+          let s = Double(sample) / 32768.0
+          sumSquares += s * s
+        }
+        let rms = sqrt(sumSquares / Double(frameData.count))
+        let dB = 20.0 * log10(max(rms, 1e-10))
+        let dbFloor = -35.0
+        let dbCeiling = -6.0
+        frameLevel = Float(max(0.0, min(1.0, (dB - dbFloor) / (dbCeiling - dbFloor))))
+      }
+
+      // Accumulate the encoded frame as an independent packet (no byte concatenation)
+      packetFrames.append(EncodedFrame(data: opusData, audioLevel: frameLevel))
+
+      // Emit once we have enough frames (framesPerCallback)
+      if packetFrames.count >= framesPerPacket {
+        let timestampMs = Date().timeIntervalSince1970 * 1000
+        let frameCount = packetFrames.count
+        let duration = Double(frameCount) * config.frameSize
+        onAudioChunk?(packetFrames, timestampMs, sequenceNumber, duration, frameCount)
+        sequenceNumber += 1
+        packetFrames.removeAll()
+      }
+    }
+  }
+
+  private func _flushRemainingFrames() {
+    guard let opusEncoder = opusEncoder else { return }
+
+    // Pad remaining PCM with silence to fill the last frame
+    if !pendingSamples.isEmpty && pendingSamples.count < samplesPerFrame {
+      pendingSamples.append(contentsOf: [Int16](repeating: 0, count: samplesPerFrame - pendingSamples.count))
+    }
+
+    // Encode remaining frames
+    while pendingSamples.count >= samplesPerFrame {
+      let frameData = Array(pendingSamples.prefix(samplesPerFrame))
+      pendingSamples.removeFirst(samplesPerFrame)
+
+      var encodedPacket: Data?
+      frameData.withUnsafeBufferPointer { bufferPointer in
+        guard let baseAddress = bufferPointer.baseAddress else { return }
+        encodedPacket = opusEncoder.encode(pcm: baseAddress, frameSize: samplesPerFrame)
+      }
+
+      guard let opusData = encodedPacket, !opusData.isEmpty else { continue }
+      // Flush frames get level 0 (silence-padded)
+      packetFrames.append(EncodedFrame(data: opusData, audioLevel: enableAudioLevel ? 0.0 : nil))
+    }
+
+    // Flush any remaining frames (even if fewer than framesPerPacket)
+    if !packetFrames.isEmpty {
+      let timestampMs = Date().timeIntervalSince1970 * 1000
+      let frameCount = packetFrames.count
+      let duration = Double(frameCount) * config.frameSize
+      onAudioChunk?(packetFrames, timestampMs, sequenceNumber, duration, frameCount)
+      sequenceNumber += 1
+      packetFrames.removeAll()
+    }
+  }
+}

package/ios/OpusCtlHelpers.h

@@ -56,6 +56,14 @@ NS_ASSUME_NONNULL_BEGIN
  */
 + (int)setDtx:(void *)encoder dtx:(int)dtx;
 
+/**
+ * Get encoder lookahead (pre-skip samples)
+ * @param encoder Pointer to OpusEncoder (as void*)
+ * @param lookahead Output pointer for lookahead value
+ * @return OPUS_OK on success, or negative error code
+ */
++ (int)getLookahead:(void *)encoder lookahead:(int *)lookahead;
+
 @end
 
 NS_ASSUME_NONNULL_END

package/ios/OpusCtlHelpers.m

@@ -27,4 +27,8 @@
     return opus_encoder_ctl((OpusEncoder *)encoder, OPUS_SET_DTX(dtx));
 }
 
++ (int)getLookahead:(void *)encoder lookahead:(int *)lookahead {
+    return opus_encoder_ctl((OpusEncoder *)encoder, OPUS_GET_LOOKAHEAD(lookahead));
+}
+
 @end

package/ios/OpusEncoder.swift

@@ -31,6 +31,9 @@ class OpusEncoder {
   // Buffer for encoded output
   private let maxPacketSize = 4000 // bytes
 
+  // Opus lookahead (pre-skip samples) — decoders should skip this many samples at the start
+  private(set) var preSkip: Int = 0
+
   /**
    * Initialize Opus 1.6.1 encoder with DRED support
    *
@@ -125,6 +128,15 @@ class OpusEncoder {
       print("[OpusEncoder] Warning: Failed to set DTX (error \(result))")
     }
 
+    // Get encoder lookahead (pre-skip)
+    var lookahead: Int32 = 0
+    result = Int32(OpusCtlHelpers.getLookahead(encoderPtr, lookahead: &lookahead))
+    if result == OPUS_OK {
+      self.preSkip = Int(lookahead)
+    } else {
+      print("[OpusEncoder] Warning: Failed to get lookahead (error \(result))")
+    }
+
     // Enable DRED (Opus 1.6.1 feature)
     if dredDurationMs > 0 {
       result = Int32(OpusCtlHelpers.setDredDuration(encoderPtr, durationMs: Int32(dredDurationMs)))
@@ -147,6 +159,7 @@ class OpusEncoder {
       - In-band FEC: \(inbandFec)
       - DTX: \(dtx)
       - DRED: \(dredDurationMs)ms
+      - Pre-skip: \(preSkip) samples
     """)
   }
 

package/ios/OpuslibModule.swift

@@ -15,7 +15,7 @@ public class OpuslibModule: Module {
     Name("Opuslib")
 
     // Events
-    Events("audioChunk", "amplitude", "error")
+    Events("audioChunk", "amplitude", "audioStarted", "audioEnd", "error")
 
     // Start streaming method
     AsyncFunction("startStreaming") { (config: AudioConfig) in
@@ -57,13 +57,46 @@ public class OpuslibModule: Module {
     let manager = AudioEngineManager(config: config)
     print("[OpuslibModule] ✅ AudioEngineManager created")
 
-    // Set up event callbacks
+    // Set up event callbacks — audioStarted/audioEnd are emitted from the encoding thread
     print("[OpuslibModule] 🔗 Setting up event callbacks...")
-    manager.setOnAudioChunk { [weak self] data, timestamp, sequenceNumber in
+    manager.setOnAudioChunk { [weak self] frames, timestamp, sequenceNumber, duration, frameCount in
+      // Each frame is an independent Opus packet wrapped in { data, audioLevel? }
+      let frameObjects: [[String: Any]] = frames.map { frame in
+        var obj: [String: Any] = ["data": frame.data]
+        if let level = frame.audioLevel {
+          obj["audioLevel"] = level
+        }
+        return obj
+      }
+      // `data` is the first frame's packet, kept for backward compatibility with
+      // consumers that read a single Opus packet per event.
+      let firstData = frames.first?.data ?? Data()
       self?.sendEvent("audioChunk", [
-        "data": data,
+        "data": firstData,
+        "frames": frameObjects,
         "timestamp": timestamp,
-        "sequenceNumber": sequenceNumber
+        "sequenceNumber": sequenceNumber,
+        "duration": duration,
+        "frameCount": frameCount
+      ])
+    }
+
+    manager.setOnStarted { [weak self] timestamp, sampleRate, channels, bitrate, frameSize, preSkip in
+      self?.sendEvent("audioStarted", [
+        "timestamp": timestamp,
+        "sampleRate": sampleRate,
+        "channels": channels,
+        "bitrate": bitrate,
+        "frameSize": frameSize,
+        "preSkip": preSkip
+      ])
+    }
+
+    manager.setOnEnd { [weak self] timestamp, totalDuration, totalPackets in
+      self?.sendEvent("audioEnd", [
+        "timestamp": timestamp,
+        "totalDuration": totalDuration,
+        "totalPackets": totalPackets
       ])
     }
 
@@ -83,7 +116,7 @@ public class OpuslibModule: Module {
       ])
     }
 
-    // Start audio capture
+    // Start audio capture + encoding
     print("[OpuslibModule] 🚀 Calling manager.start()...")
     try manager.start()
     print("[OpuslibModule] ✅ manager.start() completed")
@@ -99,6 +132,7 @@ public class OpuslibModule: Module {
       return
     }
 
+    // stop() triggers flushAndStop(), which emits audioEnd from the encoding thread
     audioEngineManager?.stop()
     audioEngineManager = nil
     isStreaming = false
@@ -167,11 +201,26 @@ struct AudioConfig: Record {
   @Field var channels: Int = 1
   @Field var bitrate: Int = 24000
   @Field var frameSize: Double = 20.0
+  // Retained for backward compatibility; framesPerCallback supersedes it for batching.
   @Field var packetDuration: Double = 20.0
+  // Number of Opus frames to batch per audioChunk event (default 1 = one packet per event).
+  @Field var framesPerCallback: Int? = 1
   @Field var dredDuration: Int? = 100  // NEW: DRED recovery duration in ms
   @Field var enableAmplitudeEvents: Bool? = false
   @Field var amplitudeEventInterval: Double? = 16.0
+  @Field var enableAudioLevel: Bool? = false  // Enable per-frame audio level calculation
   @Field var saveDebugAudio: Bool? = false
+  @Field var iosAudioSession: IOSAudioSessionConfig? = nil
+}
+
+/**
+ * iOS AudioSession configuration (category, mode, options).
+ * Maps JS string values to AVAudioSession enums.
+ */
+struct IOSAudioSessionConfig: Record {
+  @Field var category: String = "record"
+  @Field var mode: String = "measurement"
+  @Field var options: [String]? = nil
 }
 
 // MARK: - Errors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opuslib",
-  "version": "0.1.4",
+  "version": "0.2.0",
   "description": "Opuslib wrapper",
   "main": "build/index.js",
   "types": "build/index.d.ts",

package/src/Opuslib.types.ts

@@ -12,26 +12,99 @@ 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
 }
 
 /**
@@ -46,6 +119,37 @@ export interface AmplitudeEvent {
   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/src/OpuslibModule.ts

@@ -4,6 +4,8 @@ import type {
   AudioConfig,
   AudioChunkEvent,
   AmplitudeEvent,
+  AudioStartedEvent,
+  AudioEndEvent,
   ErrorEvent,
   Subscription,
 } from './Opuslib.types'
@@ -96,6 +98,14 @@ export 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)
@@ -107,8 +117,20 @@ export default {
    * ```
    */
   addListener: ((
-    eventName: 'audioChunk' | 'amplitude' | 'error',
-    listener: (event: AudioChunkEvent | AmplitudeEvent | ErrorEvent) => void,
+    eventName:
+      | 'audioChunk'
+      | 'amplitude'
+      | 'audioStarted'
+      | 'audioEnd'
+      | 'error',
+    listener: (
+      event:
+        | AudioChunkEvent
+        | AmplitudeEvent
+        | AudioStartedEvent
+        | AudioEndEvent
+        | ErrorEvent,
+    ) => void,
   ): Subscription => (emitter as any).addListener(eventName, listener)) as {
     (
       eventName: 'audioChunk',
@@ -118,6 +140,14 @@ export default {
       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
   },
 
@@ -131,6 +161,29 @@ export default {
     listener: (event: AmplitudeEvent) => void,
   ): Subscription => (emitter as any).addListener('amplitude', listener),
 
+  /**
+   * 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 => (emitter as any).addListener('audioStarted', listener),
+
+  /**
+   * 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 => (emitter as any).addListener('audioEnd', listener),
+
   /**
    * Listen for error events
    *

package/src/OpuslibModule.web.ts

@@ -39,6 +39,14 @@ export default {
     remove: () => {},
   }),
 
+  addAudioStartedListener: () => ({
+    remove: () => {},
+  }),
+
+  addAudioEndListener: () => ({
+    remove: () => {},
+  }),
+
   addErrorListener: () => ({
     remove: () => {},
   }),