@livekit/rtc-node 0.13.28 → 0.13.30

package/src/bun_runtime.test.ts

@@ -0,0 +1,27 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { describe, expect, it } from 'vitest';
+
+// Guard: the "Bun" CI job runs vitest via `bun --bun run test` so test bodies
+// execute on the bun runtime (with vitest still providing module mocking). The
+// `--bun` flag is load-bearing — without it, bun honors vitest's
+// `#!/usr/bin/env node` shebang and silently runs everything under node, making
+// the bun job a meaningless duplicate of the node job.
+//
+// When EXPECT_BUN_RUNTIME=1 (set only by the bun CI step), assert that this test
+// body is actually executing under bun. It runs through the exact same vitest
+// path as the real suite, so it catches a regression where the runtime falls
+// back to node. In every other run (the node CI job, local dev) the var is
+// unset and this is skipped.
+describe('bun runtime guard', () => {
+  const enforced = process.env.EXPECT_BUN_RUNTIME === '1';
+
+  it.skipIf(!enforced)('test bodies execute on the bun runtime', () => {
+    expect(
+      process.versions.bun,
+      'EXPECT_BUN_RUNTIME=1 but tests are not running under bun — `bun --bun run test` ' +
+        'fell back to node (check the --bun flag / invocation).',
+    ).toBeTruthy();
+  });
+});

package/src/ffi_client.ts

@@ -41,6 +41,8 @@ export class FfiClient extends (EventEmitter as new () => TypedEmitter<FfiClient
     return globalThis._ffiClientInstance;
   }
 
+  private _nextRequestAsyncId = BigInt(0);
+
   constructor() {
     super();
     this.setMaxListeners(0);
@@ -70,6 +72,10 @@ export class FfiClient extends (EventEmitter as new () => TypedEmitter<FfiClient
     return livekitRetrievePtr(data);
   }
 
+  getNextRequestAsyncId() {
+    return ++this._nextRequestAsyncId;
+  }
+
   async waitFor<T>(
     predicate: (ev: FfiEvent) => boolean,
     options?: { signal?: AbortSignal },

package/src/frame_processor.ts

@@ -43,7 +43,11 @@ export abstract class FrameProcessor<Frame extends VideoFrame | AudioFrame> {
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   onStreamInfoUpdated(_info: FrameProcessorStreamInfo): void {}
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onStreamInfoCleared(): void {}
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
   onCredentialsUpdated(_credentials: FrameProcessorCredentials): void {}
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  onCredentialsCleared(): void {}
 
   abstract process(frame: Frame): Frame;
   abstract close(): void;

package/src/participant.ts

@@ -731,6 +731,14 @@ export class LocalParticipant extends Participant {
         case 'publication':
           const track_publication = new LocalTrackPublication(cb.message.value!);
           track_publication.track = track;
+          // Stamp the server-assigned publication
+          // SID onto the track so track.sid == publication.sid. Both
+          // Track.pushProcessorMetadataToStream and the localTrackRepublished
+          // handler look up the local publication by this SID; without it they
+          // depend on createAudioTrack's provisional SID happening to match.
+          if (track.info && track_publication.sid) {
+            track.info.sid = track_publication.sid;
+          }
           this.trackPublications.set(track_publication.sid!, track_publication);
 
           return track_publication;
@@ -767,6 +775,15 @@ export class LocalParticipant extends Participant {
 
       const pub = this.trackPublications.get(trackSid);
       if (pub) {
+        // Clear the processor's room context here too: this path races the
+        // localTrackUnpublished room event, and whichever loses finds the
+        // publication already gone and skips its own setRoom(null). Calling it
+        // from both paths guarantees the processor is cleared (and the
+        // tokenRefreshed listener detached); setRoom(null) is idempotent, so a
+        // double-clear when this path wins is safe.
+        if (pub.track) {
+          pub.track.setRoom(null);
+        }
         pub.track = undefined;
       }
       this.trackPublications.delete(trackSid);

package/src/room.ts

@@ -3,7 +3,11 @@
 // SPDX-License-Identifier: Apache-2.0
 import { Mutex } from '@livekit/mutex';
 import { EncryptionState, type EncryptionType } from '@livekit/rtc-ffi-bindings';
-import type { FfiEvent } from '@livekit/rtc-ffi-bindings';
+import type {
+  FfiEvent,
+  GetSessionStatsCallback,
+  GetSessionStatsResponse,
+} from '@livekit/rtc-ffi-bindings';
 import { DisconnectReason, type OwnedParticipant } from '@livekit/rtc-ffi-bindings';
 import type {
   DataStream_Trailer,
@@ -24,6 +28,7 @@ import {
   RoomOptions as FfiRoomOptions,
   type IceServer,
   IceTransportType,
+  type ReadyForRoomEventResponse,
   type RoomInfo,
   type SimulateScenarioCallback,
   type SimulateScenarioKind,
@@ -191,6 +196,36 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
     return this.sidPromise;
   }
 
+  async getRtcStats() {
+    if (!this.isConnected || !this.ffiHandle) {
+      throw new Error('getRtcStats requires a connected room');
+    }
+    // subscribe before issuing the request
+    const requestId = FfiClient.instance.getNextRequestAsyncId();
+    const cbPromise = FfiClient.instance.waitFor<GetSessionStatsCallback>(
+      (ev: FfiEvent) =>
+        ev.message.case === 'getSessionStats' && ev.message.value.asyncId === requestId,
+      { signal: this.disconnectController.signal },
+    );
+    FfiClient.instance.request<GetSessionStatsResponse>({
+      message: {
+        case: 'getSessionStats',
+        value: {
+          roomHandle: this.ffiHandle.handle,
+          requestAsyncId: requestId,
+        },
+      },
+    });
+    const cb = await cbPromise;
+    if (cb.message.case === 'error') {
+      throw new Error(cb.message.value);
+    } else if (cb.message.case === 'result') {
+      return cb.message.value;
+    } else {
+      throw new Error('could not retrieve rtc stats');
+    }
+  }
+
   get numParticipants(): number {
     return this.info?.numParticipants ?? 0;
   }
@@ -292,6 +327,15 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
             }
           }
           this.updateConnectionState(ConnectionState.CONN_CONNECTED);
+          // Release the FFI room event gate after our listener and local state are ready.
+          FfiClient.instance.request<ReadyForRoomEventResponse>({
+            message: {
+              case: 'readyForRoomEvent',
+              value: {
+                roomHandle: this.ffiHandle.handle,
+              },
+            },
+          });
           break;
         case 'error':
         default:
@@ -400,6 +444,23 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
     }
     this.textStreamControllers.clear();
 
+    // Detach every track from this room so attached FrameProcessors receive
+    // onStreamInfoCleared/onCredentialsCleared and the tokenRefreshed listener
+    // is removed. Otherwise a server-initiated disconnect leaves processors with
+    // stale room context and the Room holding a strong ref to each Track's bound
+    // listener until GC. setRoom(null) is idempotent, so this is safe even if a
+    // track was already detached (e.g. via unsubscribe/unpublish).
+    if (this.localParticipant) {
+      for (const pub of this.localParticipant.trackPublications.values()) {
+        pub.track?.setRoom(null);
+      }
+    }
+    for (const participant of this.remoteParticipants.values()) {
+      for (const pub of participant.trackPublications.values()) {
+        pub.track?.setRoom(null);
+      }
+    }
+
     // Clear sidPromise before removing listeners so that a reconnect
     // doesn't return a stale, permanently-pending promise.
     this.sidPromise = undefined;
@@ -513,11 +574,27 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
       }
     } else if (ev.case == 'localTrackPublished') {
       const publication = this.localParticipant.trackPublications.get(ev.value.trackSid!);
+      if (publication?.track) {
+        publication.track.setRoom(this);
+      }
       this.emit(RoomEvent.LocalTrackPublished, publication!, this.localParticipant);
     } else if (ev.case == 'localTrackUnpublished') {
       const publication = this.localParticipant.trackPublications.get(ev.value.publicationSid!);
+      const track = publication?.track;
+      if (track) {
+        track.setRoom(null);
+      }
       this.localParticipant.trackPublications.delete(ev.value.publicationSid!);
+      // Emit while `publication.track` is still set, preserving the pre-existing
+      // payload for callbacks. The handler is synchronous, so nulling the track
+      // right after still completes before any other turn can observe it.
       this.emit(RoomEvent.LocalTrackUnpublished, publication!, this.localParticipant!);
+      // Mirror trackUnsubscribed: drop the publication's track reference. This
+      // also makes unpublishTrack's own setRoom(null) a no-op when it loses the
+      // race (its `pub.track` guard short-circuits), avoiding a redundant clear.
+      if (track && publication) {
+        publication.track = undefined;
+      }
     } else if ((ev.case as string) == 'localTrackRepublished') {
       const value = (ev as any).value;
       const previousSid: string = value.previousSid!;
@@ -527,6 +604,15 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
         publication.updateInfo(newInfo);
         this.localParticipant.trackPublications.delete(previousSid);
         this.localParticipant.trackPublications.set(publication.sid!, publication);
+        if (publication.track?.info) {
+          // Keep the local-track invariant (track.sid == publication.sid, set at
+          // publishTrack) intact across republish, then re-push metadata so any
+          // attached FrameProcessor learns the new publication SID / credentials.
+          // setRoom with the same room is a no-op for the tokenRefreshed listener
+          // but re-fans the metadata to every registered AudioStream.
+          publication.track.info.sid = publication.sid;
+          publication.track.setRoom(this);
+        }
         this.emit(RoomEvent.LocalTrackRepublished, publication, previousSid, this.localParticipant);
       } else {
         log.warn(`RoomEvent.LocalTrackRepublished: previous publication not found: ${previousSid}`);
@@ -576,6 +662,7 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
         } else if (trackInfo.kind == TrackKind.KIND_AUDIO) {
           publication.track = new RemoteAudioTrack(ownedTrack);
         }
+        publication.track?.setRoom(this);
 
         this.emit(RoomEvent.TrackSubscribed, publication.track!, publication, participant);
       } catch (e: unknown) {
@@ -588,6 +675,7 @@ export class Room extends (EventEmitter as new () => TypedEmitter<RoomCallbacks>
           ev.value.trackSid!,
         );
         const track = publication.track!;
+        track.setRoom(null);
         publication.track = undefined;
         publication.subscribed = false;
         this.emit(RoomEvent.TrackUnsubscribed, track, publication, participant);

package/src/track.ts

@@ -11,7 +11,9 @@ import type {
 } from '@livekit/rtc-ffi-bindings';
 import { CreateAudioTrackRequest, CreateVideoTrackRequest } from '@livekit/rtc-ffi-bindings';
 import type { AudioSource } from './audio_source.js';
+import type { AudioStreamSource } from './audio_stream.js';
 import { FfiClient, FfiHandle } from './ffi_client.js';
+import type { Room } from './room.js';
 import type { VideoSource } from './video_source.js';
 
 export abstract class Track {
@@ -21,9 +23,148 @@ export abstract class Track {
   /** @internal */
   ffi_handle: FfiHandle;
 
+  private roomRef: WeakRef<Room> | null = null;
+  private audioStreams: Set<WeakRef<AudioStreamSource>> = new Set();
+  private streamFinalizationRegistry: FinalizationRegistry<WeakRef<AudioStreamSource>>;
+  private onRoomTokenRefreshed = () => {
+    const room = this.resolveRoom();
+    if (!room || !room.token || !room.serverUrl) {
+      return;
+    }
+    for (const stream of this.iterateStreams()) {
+      const processor = stream.processor;
+      if (!processor) {
+        continue;
+      }
+      processor.onCredentialsUpdated({ token: room.token, url: room.serverUrl });
+    }
+  };
+
   constructor(owned: OwnedTrack) {
     this.info = owned.info;
     this.ffi_handle = new FfiHandle(owned.handle!.id!);
+    this.streamFinalizationRegistry = new FinalizationRegistry<WeakRef<AudioStreamSource>>(
+      (ref) => {
+        this.audioStreams.delete(ref);
+      },
+    );
+  }
+
+  /** @internal */
+  resolveRoom(): Room | null {
+    return this.roomRef?.deref() ?? null;
+  }
+
+  /** @internal */
+  setRoom(room: Room | null): void {
+    const oldRoom = this.resolveRoom();
+    if (!oldRoom && !room) {
+      // Already roomless — nothing to detach and nothing to re-clear. Without
+      // this guard a second setRoom(null) (e.g. the unpublishTrack /
+      // localTrackUnpublished race calling it from both paths) would re-fire
+      // onStreamInfoCleared / onCredentialsCleared on every registered processor.
+      return;
+    }
+    if (oldRoom && oldRoom !== room) {
+      oldRoom.off('tokenRefreshed', this.onRoomTokenRefreshed);
+    }
+    if (room) {
+      room.off('tokenRefreshed', this.onRoomTokenRefreshed);
+      room.on('tokenRefreshed', this.onRoomTokenRefreshed);
+    }
+    this.roomRef = room ? new WeakRef(room) : null;
+    for (const stream of this.iterateStreams()) {
+      this.pushProcessorMetadataToStream(stream, room);
+    }
+  }
+
+  /** @internal */
+  registerAudioStream(stream: AudioStreamSource): void {
+    const ref = new WeakRef(stream);
+    this.audioStreams.add(ref);
+    this.streamFinalizationRegistry.register(stream, ref);
+    const room = this.resolveRoom();
+    if (room) {
+      this.pushProcessorMetadataToStream(stream, room);
+    }
+  }
+
+  /** @internal */
+  unregisterAudioStream(stream: AudioStreamSource): void {
+    for (const ref of this.audioStreams) {
+      if (ref.deref() === stream) {
+        this.audioStreams.delete(ref);
+        return;
+      }
+    }
+  }
+
+  private *iterateStreams(): Generator<AudioStreamSource> {
+    const dead: Array<WeakRef<AudioStreamSource>> = [];
+    for (const ref of this.audioStreams) {
+      const stream = ref.deref();
+      if (stream) {
+        yield stream;
+      } else {
+        dead.push(ref);
+      }
+    }
+    for (const ref of dead) {
+      this.audioStreams.delete(ref);
+    }
+  }
+
+  private pushProcessorMetadataToStream(stream: AudioStreamSource, room: Room | null): void {
+    const processor = stream.processor;
+    if (!processor) {
+      return;
+    }
+
+    if (!room) {
+      // Guard with optional-call: plugins built against an older @livekit/rtc-node
+      // inherit a FrameProcessor base class that doesn't define these methods,
+      // so they could be undefined on the prototype chain.
+      processor.onStreamInfoCleared?.();
+      processor.onCredentialsCleared?.();
+      return;
+    }
+
+    let identity = '';
+    let publicationSid = '';
+    const trackSid = this.sid;
+    if (trackSid) {
+      let found = false;
+      for (const participant of room.remoteParticipants.values()) {
+        const publication = participant.trackPublications.get(trackSid);
+        if (publication) {
+          identity = participant.identity;
+          publicationSid = publication.sid ?? '';
+          found = true;
+          break;
+        }
+      }
+      if (!found) {
+        const local = room.localParticipant;
+        if (local) {
+          for (const publication of local.trackPublications.values()) {
+            if (publication.sid === trackSid) {
+              identity = local.identity;
+              publicationSid = publication.sid ?? '';
+              break;
+            }
+          }
+        }
+      }
+    }
+
+    processor.onStreamInfoUpdated({
+      roomName: room.name ?? '',
+      participantIdentity: identity,
+      publicationSid,
+    });
+    if (room.token && room.serverUrl) {
+      processor.onCredentialsUpdated({ token: room.token, url: room.serverUrl });
+    }
   }
 
   get sid(): string | undefined {

package/src/version.ts

@@ -1 +1 @@
-export const SDK_VERSION = "0.13.28";
+export const SDK_VERSION = "0.13.30";