@livekit/rtc-node 0.13.24 → 0.13.26

package/src/audio_mixer.ts

@@ -239,7 +239,7 @@ export class AudioMixer {
 
       for (const result of results) {
         if (result.status !== 'fulfilled') {
-          log.warn('AudioMixer: Stream contribution failed:', result.reason);
+          log.warn({ reason: result.reason }, 'AudioMixer: Stream contribution failed');
           continue;
         }
 
@@ -311,7 +311,7 @@ export class AudioMixer {
     // Accumulate data until we have at least chunkSize samples
     while (buf.length < this.chunkSize * this.numChannels && !exhausted && !this.closed) {
       try {
-        const result = await Promise.race([iterator.next(), this.timeout(this.streamTimeoutMs)]);
+        const result = await this.timeoutRace(iterator.next(), this.streamTimeoutMs);
 
         if (result === 'timeout') {
           console.warn(`AudioMixer: stream timeout after ${this.streamTimeoutMs}ms`);
@@ -412,7 +412,13 @@ export class AudioMixer {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
 
-  private timeout(ms: number): Promise<'timeout'> {
-    return new Promise((resolve) => setTimeout(() => resolve('timeout'), ms));
+  /** Race a promise against a timeout. The losing setTimeout is automatically
+   *  cleared via `.finally()` so callers don't need to manage cleanup. */
+  private timeoutRace<T>(promise: Promise<T>, ms: number): Promise<T | 'timeout'> {
+    let timer: ReturnType<typeof setTimeout>;
+    const timeoutPromise = new Promise<'timeout'>((resolve) => {
+      timer = setTimeout(() => resolve('timeout'), ms);
+    });
+    return Promise.race([promise.finally(() => clearTimeout(timer)), timeoutPromise]);
   }
 }

package/src/audio_resampler.ts

@@ -1,20 +1,20 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { AudioFrame } from './audio_frame.js';
-import { FfiClient, FfiHandle } from './ffi_client.js';
 import type {
   FlushSoxResamplerResponse,
   NewSoxResamplerResponse,
   PushSoxResamplerResponse,
-} from './proto/audio_frame_pb.js';
+} from '@livekit/rtc-ffi-bindings';
 import {
   FlushSoxResamplerRequest,
   NewSoxResamplerRequest,
   PushSoxResamplerRequest,
   SoxQualityRecipe,
   SoxResamplerDataType,
-} from './proto/audio_frame_pb.js';
+} from '@livekit/rtc-ffi-bindings';
+import { AudioFrame } from './audio_frame.js';
+import { FfiClient, FfiHandle } from './ffi_client.js';
 
 /**
  * Resampler quality. Higher quality settings result in better audio quality but require more
@@ -97,6 +97,14 @@ export class AudioResampler {
     return this.#channels;
   }
 
+  /**
+   * Releases the underlying native resampler handle. Must be called when
+   * the resampler is no longer needed to avoid leaking the FD.
+   */
+  close() {
+    this.#ffiHandle.dispose();
+  }
+
   /**
    * Push audio data into the resampler and retrieve any available resampled data.
    *
@@ -131,12 +139,14 @@ export class AudioResampler {
     }
 
     const outputData = FfiClient.instance.copyBuffer(res.outputPtr, res.size!);
+
     return [
       new AudioFrame(
         new Int16Array(outputData.buffer),
         this.#outputRate,
         this.#channels,
         Math.trunc(outputData.length / this.#channels / 2),
+        data.userdata,
       ),
     ];
   }

package/src/audio_source.ts

@@ -1,22 +1,22 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import type { AudioFrame } from './audio_frame.js';
-import { FfiClient } from './ffi_client.js';
-import { FfiHandle } from './napi/native.js';
 import type {
   AudioSourceInfo,
   CaptureAudioFrameCallback,
   CaptureAudioFrameResponse,
   ClearAudioBufferResponse,
   NewAudioSourceResponse,
-} from './proto/audio_frame_pb.js';
+} from '@livekit/rtc-ffi-bindings';
 import {
   AudioSourceType,
   CaptureAudioFrameRequest,
   ClearAudioBufferRequest,
+  FfiHandle,
   NewAudioSourceRequest,
-} from './proto/audio_frame_pb.js';
+} from '@livekit/rtc-ffi-bindings';
+import type { AudioFrame } from './audio_frame.js';
+import { FfiClient } from './ffi_client.js';
 
 export class AudioSource {
   /** @internal */
@@ -145,6 +145,14 @@ export class AudioSource {
   }
 
   async close() {
+    // Clear any pending playout timeout so its callback doesn't fire after
+    // the handle is disposed, which would reference freed native state.
+    if (this.timeout) {
+      clearTimeout(this.timeout);
+      this.timeout = undefined;
+    }
+    // Resolve any pending waitForPlayout() promise so callers don't hang.
+    this.release();
     this.ffiHandle.dispose();
     this.closed = true;
   }

package/src/audio_stream.ts

@@ -1,14 +1,14 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import type { NewAudioStreamResponse } from '@livekit/rtc-ffi-bindings';
+import { AudioStreamType, NewAudioStreamRequest } from '@livekit/rtc-ffi-bindings';
 import type { UnderlyingSource } from 'node:stream/web';
 import { AudioFrame } from './audio_frame.js';
 import type { FfiEvent } from './ffi_client.js';
 import { FfiClient, FfiClientEvent, FfiHandle } from './ffi_client.js';
-import { FrameProcessor } from './frame_processor.js';
+import { type FrameProcessor, isFrameProcessor } from './frame_processor.js';
 import { log } from './log.js';
-import type { NewAudioStreamResponse } from './proto/audio_frame_pb.js';
-import { AudioStreamType, NewAudioStreamRequest } from './proto/audio_frame_pb.js';
 import type { Track } from './track.js';
 
 export interface AudioStreamOptions {
@@ -27,6 +27,7 @@ export interface NoiseCancellationOptions {
 class AudioStreamSource implements UnderlyingSource<AudioFrame> {
   private controller?: ReadableStreamDefaultController<AudioFrame>;
   private ffiHandle: FfiHandle;
+  private disposed = false;
   private sampleRate: number;
   private numChannels: number;
   private legacyNcOptions?: NoiseCancellationOptions;
@@ -41,7 +42,7 @@ class AudioStreamSource implements UnderlyingSource<AudioFrame> {
     if (sampleRateOrOptions !== undefined && typeof sampleRateOrOptions !== 'number') {
       this.sampleRate = sampleRateOrOptions.sampleRate ?? 48000;
       this.numChannels = sampleRateOrOptions.numChannels ?? 1;
-      if (sampleRateOrOptions.noiseCancellation instanceof FrameProcessor) {
+      if (isFrameProcessor(sampleRateOrOptions.noiseCancellation)) {
         this.frameProcessor = sampleRateOrOptions.noiseCancellation;
       } else {
         this.legacyNcOptions = sampleRateOrOptions.noiseCancellation;
@@ -106,7 +107,15 @@ class AudioStreamSource implements UnderlyingSource<AudioFrame> {
       case 'eos':
         FfiClient.instance.off(FfiClientEvent.FfiEvent, this.onEvent);
         this.controller.close();
-        this.frameProcessor?.close();
+        // Dispose the native handle so the FD is released on stream end,
+        // not just when cancel() is called explicitly by the consumer.
+        // Guard against double-dispose if cancel() is called after EOS
+        // while buffered frames are still in the ReadableStream queue.
+        if (!this.disposed) {
+          this.disposed = true;
+          this.ffiHandle.dispose();
+          this.frameProcessor?.close();
+        }
         break;
     }
   };
@@ -117,7 +126,13 @@ class AudioStreamSource implements UnderlyingSource<AudioFrame> {
 
   cancel() {
     FfiClient.instance.off(FfiClientEvent.FfiEvent, this.onEvent);
-    this.ffiHandle.dispose();
+    if (!this.disposed) {
+      this.disposed = true;
+      this.ffiHandle.dispose();
+      // Also close the frame processor on cancel for symmetry with the EOS path,
+      // so resources are released regardless of how the stream ends.
+      this.frameProcessor?.close();
+    }
   }
 }
 

package/src/data_streams/stream_reader.ts

@@ -1,8 +1,8 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
+import type { DataStream_Chunk } from '@livekit/rtc-ffi-bindings';
 import { log } from '../log.js';
-import type { DataStream_Chunk } from '../proto/room_pb.js';
 import { bigIntToNumber } from '../utils.js';
 import type { BaseStreamInfo, ByteStreamInfo, TextStreamInfo } from './types.js';
 
@@ -53,12 +53,18 @@ export class ByteStreamReader extends BaseStreamReader<ByteStreamInfo> {
         try {
           const { done, value } = await reader.read();
           if (done) {
+            // Release the lock when the stream is exhausted so the
+            // underlying ReadableStream can be garbage-collected.
+            reader.releaseLock();
             return { done: true, value: undefined as unknown };
           } else {
             this.handleChunkReceived(value);
             return { done: false, value: value.content! };
           }
         } catch (error: unknown) {
+          // Release the lock on error so it doesn't stay held when the
+          // consumer never calls return() (e.g. breaking out of for-await).
+          reader.releaseLock();
           log.error('error processing stream update: %s', error);
           return { done: true, value: undefined as unknown };
         }
@@ -121,12 +127,18 @@ export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
   [Symbol.asyncIterator]() {
     const reader = this.reader.getReader();
     const decoder = new TextDecoder();
+    const receivedChunks = this.receivedChunks;
 
     return {
       next: async (): Promise<IteratorResult<string>> => {
         try {
           const { done, value } = await reader.read();
           if (done) {
+            // Release the lock when the stream is exhausted so the
+            // underlying ReadableStream can be garbage-collected.
+            reader.releaseLock();
+            // Clear received chunks so the buffered data can be GC'd.
+            receivedChunks.clear();
             return { done: true, value: undefined };
           } else {
             this.handleChunkReceived(value);
@@ -136,6 +148,10 @@ export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
             };
           }
         } catch (error: unknown) {
+          // Release the lock on error so it doesn't stay held when the
+          // consumer never calls return() (e.g. breaking out of for-await).
+          reader.releaseLock();
+          receivedChunks.clear();
           log.error('error processing stream update: %s', error);
           return { done: true, value: undefined };
         }
@@ -143,6 +159,8 @@ export class TextStreamReader extends BaseStreamReader<TextStreamInfo> {
 
       return(): IteratorResult<string> {
         reader.releaseLock();
+        // Clear received chunks so the buffered data can be GC'd.
+        receivedChunks.clear();
         return { done: true, value: undefined };
       },
     };

package/src/data_streams/types.ts

@@ -1,7 +1,7 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import type { DataStream_Chunk, DataStream_Header } from '../proto/room_pb.js';
+import type { DataStream_Chunk, DataStream_Header } from '@livekit/rtc-ffi-bindings';
 import type { ByteStreamReader, TextStreamReader } from './stream_reader.js';
 
 export interface StreamController<T extends DataStream_Chunk> {

package/src/e2ee.ts

@@ -1,7 +1,6 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import { FfiClient } from './ffi_client.js';
 import type {
   E2eeManagerGetFrameCryptorsResponse,
   E2eeResponse,
@@ -9,7 +8,7 @@ import type {
   GetSharedKeyResponse,
   RatchetKeyResponse,
   RatchetSharedKeyResponse,
-} from './proto/e2ee_pb.js';
+} from '@livekit/rtc-ffi-bindings';
 import {
   E2eeManagerSetEnabledRequest,
   E2eeRequest,
@@ -22,7 +21,8 @@ import {
   RatchetSharedKeyRequest,
   SetKeyRequest,
   SetSharedKeyRequest,
-} from './proto/e2ee_pb.js';
+} from '@livekit/rtc-ffi-bindings';
+import { FfiClient } from './ffi_client.js';
 
 const DEFAULT_RATCHET_SALT = new TextEncoder().encode('LKFrameEncryptionKey');
 const DEFAULT_RATCHET_WINDOW_SIZE = 16;

package/src/ffi_client.ts

@@ -1,18 +1,20 @@
 // SPDX-FileCopyrightText: 2024 LiveKit, Inc.
 //
 // SPDX-License-Identifier: Apache-2.0
-import type { PartialMessage } from '@bufbuild/protobuf';
-import type { TypedEventEmitter as TypedEmitter } from '@livekit/typed-emitter';
-import EventEmitter from 'events';
 import {
+  FfiEvent,
   FfiHandle,
+  FfiRequest,
+  FfiResponse,
+  type PartialMessage,
   livekitCopyBuffer,
   livekitDispose,
   livekitFfiRequest,
   livekitInitialize,
   livekitRetrievePtr,
-} from './napi/native.js';
-import { FfiEvent, FfiRequest, FfiResponse } from './proto/ffi_pb.js';
+} from '@livekit/rtc-ffi-bindings';
+import type { TypedEventEmitter as TypedEmitter } from '@livekit/typed-emitter';
+import EventEmitter from 'events';
 import { SDK_VERSION } from './version.js';
 
 export { FfiHandle, type FfiEvent, type FfiResponse, FfiRequest, livekitDispose as dispose };
@@ -68,14 +70,37 @@ export class FfiClient extends (EventEmitter as new () => TypedEmitter<FfiClient
     return livekitRetrievePtr(data);
   }
 
-  async waitFor<T>(predicate: (ev: FfiEvent) => boolean): Promise<T> {
-    return new Promise<T>((resolve) => {
+  async waitFor<T>(
+    predicate: (ev: FfiEvent) => boolean,
+    options?: { signal?: AbortSignal },
+  ): Promise<T> {
+    return new Promise<T>((resolve, reject) => {
       const listener = (ev: FfiEvent) => {
         if (predicate(ev)) {
-          this.off(FfiClientEvent.FfiEvent, listener);
+          cleanup();
           resolve(ev.message.value as T);
         }
       };
+
+      const cleanup = () => {
+        this.off(FfiClientEvent.FfiEvent, listener);
+        options?.signal?.removeEventListener('abort', onAbort);
+      };
+
+      // If an AbortSignal is provided, remove the listener when the signal
+      // fires so that pending waitFor() calls don't leak listeners after
+      // the room disconnects or the operation is cancelled.
+      const onAbort = () => {
+        cleanup();
+        reject(options?.signal?.reason ?? new Error('waitFor aborted'));
+      };
+
+      if (options?.signal?.aborted) {
+        reject(options.signal.reason ?? new Error('waitFor aborted'));
+        return;
+      }
+
+      options?.signal?.addEventListener('abort', onAbort);
       this.on(FfiClientEvent.FfiEvent, listener);
     });
   }

package/src/frame_processor.ts

@@ -15,7 +15,28 @@ export type FrameProcessorCredentials = {
   url: string;
 };
 
+export const FrameProcessorSymbol = Symbol.for('lk.frame-processor');
+
+export function isFrameProcessor<
+  T extends FrameProcessor<AudioFrame> | FrameProcessor<VideoFrame> | unknown,
+>(
+  maybeProcessor: unknown,
+): maybeProcessor is T extends FrameProcessor<AudioFrame>
+  ? FrameProcessor<AudioFrame>
+  : T extends FrameProcessor<VideoFrame>
+    ? FrameProcessor<VideoFrame>
+    : FrameProcessor<AudioFrame> | FrameProcessor<VideoFrame> {
+  return (
+    maybeProcessor !== null &&
+    typeof maybeProcessor === 'object' &&
+    'symbol' in maybeProcessor &&
+    maybeProcessor.symbol === FrameProcessorSymbol
+  );
+}
+
 export abstract class FrameProcessor<Frame extends VideoFrame | AudioFrame> {
+  readonly symbol = FrameProcessorSymbol;
+
   abstract isEnabled(): boolean;
   abstract setEnabled(enabled: boolean): void;
 

package/src/index.ts

@@ -14,8 +14,8 @@ export { E2EEManager, FrameCryptor, KeyProvider } from './e2ee.js';
 export type { E2EEOptions, KeyProviderOptions } from './e2ee.js';
 export { dispose } from './ffi_client.js';
 export { LocalParticipant, Participant, RemoteParticipant } from './participant.js';
-export { EncryptionState, EncryptionType } from './proto/e2ee_pb.js';
-export { DisconnectReason, ParticipantKind } from './proto/participant_pb.js';
+export { EncryptionState, EncryptionType } from '@livekit/rtc-ffi-bindings';
+export { DisconnectReason, ParticipantKind } from '@livekit/rtc-ffi-bindings';
 export {
   ConnectionQuality,
   ConnectionState,
@@ -24,9 +24,9 @@ export {
   IceServer,
   IceTransportType,
   TrackPublishOptions,
-} from './proto/room_pb.js';
-export { StreamState, TrackKind, TrackSource } from './proto/track_pb.js';
-export { VideoBufferType, VideoCodec, VideoRotation } from './proto/video_frame_pb.js';
+} from '@livekit/rtc-ffi-bindings';
+export { StreamState, TrackKind, TrackSource } from '@livekit/rtc-ffi-bindings';
+export { VideoBufferType, VideoCodec, VideoRotation } from '@livekit/rtc-ffi-bindings';
 export { ConnectError, Room, RoomEvent, type RoomOptions, type RtcConfiguration } from './room.js';
 export { RpcError, type PerformRpcParams, type RpcInvocationData } from './rpc.js';
 export {
@@ -54,4 +54,5 @@ export {
   FrameProcessor,
   type FrameProcessorStreamInfo,
   type FrameProcessorCredentials,
+  isFrameProcessor,
 } from './frame_processor.js';