feat(rtc-node): expose RemoteTrackPublication.setVideoQuality

.changeset/feat-remote-track-set-video-quality.md

@@ -0,0 +1,5 @@
+---
+'@livekit/rtc-node': minor
+---
+
+Expose RemoteTrackPublication.setVideoQuality for requesting a simulcast subscribed quality

packages/livekit-rtc/src/index.ts

@@ -68,6 +68,7 @@ export {
   LocalTrackPublication,
   RemoteTrackPublication,
   TrackPublication,
+  VideoQuality,
 } from './track_publication.js';
 export type { Transcription, TranscriptionSegment } from './transcription.js';
 export type { ChatMessage } from './types.js';

packages/livekit-rtc/src/track_publication.test.ts

@@ -0,0 +1,49 @@
+// SPDX-FileCopyrightText: 2026 LiveKit, Inc.
+//
+// SPDX-License-Identifier: Apache-2.0
+import { SetRemoteTrackPublicationQualityRequest, VideoQuality } from '@livekit/rtc-ffi-bindings';
+import { describe, expect, it, vi } from 'vitest';
+import { FfiClient } from './ffi_client.js';
+import { RemoteTrackPublication } from './track_publication.js';
+
+// Synthetic FFI handles must not schedule a native drop (invalid handle) at GC.
+vi.mock('@livekit/rtc-ffi-bindings', async () => {
+  const actual = await vi.importActual<typeof import('@livekit/rtc-ffi-bindings')>(
+    '@livekit/rtc-ffi-bindings',
+  );
+  class FakeFfiHandle {
+    private _handle: bigint;
+    constructor(handle: bigint) {
+      this._handle = handle;
+    }
+    dispose(): void {}
+    get handle(): bigint {
+      return this._handle;
+    }
+  }
+  return { ...actual, FfiHandle: FakeFfiHandle };
+});
+
+describe('RemoteTrackPublication.setVideoQuality', () => {
+  it('dispatches SetRemoteTrackPublicationQuality with the publication handle', () => {
+    const handleId = BigInt(42);
+    const publication = new RemoteTrackPublication({
+      handle: { id: handleId },
+      info: {},
+    } as never);
+
+    const requestSpy = vi.spyOn(FfiClient.instance, 'request').mockReturnValue({} as never);
+    try {
+      publication.setVideoQuality(VideoQuality.HIGH);
+      expect(requestSpy).toHaveBeenCalledTimes(1);
+      const arg = requestSpy.mock.calls[0]![0] as {
+        message: { case: string; value: SetRemoteTrackPublicationQualityRequest };
+      };
+      expect(arg.message.case).toBe('setRemoteTrackPublicationQuality');
+      expect(arg.message.value.trackPublicationHandle).toBe(handleId);
+      expect(arg.message.value.quality).toBe(VideoQuality.HIGH);
+    } finally {
+      requestSpy.mockRestore();
+    }
+  });
+});

packages/livekit-rtc/src/track_publication.ts

@@ -2,8 +2,15 @@
 //
 // SPDX-License-Identifier: Apache-2.0
 import type { EncryptionType } from '@livekit/rtc-ffi-bindings';
-import type { SetSubscribedResponse } from '@livekit/rtc-ffi-bindings';
-import { SetSubscribedRequest } from '@livekit/rtc-ffi-bindings';
+import type {
+  SetRemoteTrackPublicationQualityResponse,
+  SetSubscribedResponse,
+} from '@livekit/rtc-ffi-bindings';
+import {
+  SetRemoteTrackPublicationQualityRequest,
+  SetSubscribedRequest,
+  VideoQuality,
+} from '@livekit/rtc-ffi-bindings';
 import type {
   OwnedTrackPublication,
   TrackKind,
@@ -121,4 +128,21 @@ export class RemoteTrackPublication extends TrackPublication {
       message: { case: 'setSubscribed', value: req },
     });
   }
+
+  /**
+   * For simulcast remote video publications, request a specific subscribed quality.
+   * Dispatches through the same FFI client path as {@link setSubscribed}.
+   */
+  setVideoQuality(quality: VideoQuality) {
+    const req = new SetRemoteTrackPublicationQualityRequest({
+      trackPublicationHandle: this.ffiHandle.handle,
+      quality,
+    });
+
+    FfiClient.instance.request<SetRemoteTrackPublicationQualityResponse>({
+      message: { case: 'setRemoteTrackPublicationQuality', value: req },
+    });
+  }
 }
+
+export { VideoQuality };