livekit-client 2.18.0 → 2.18.2

package/src/room/data-track/packet/index.test.ts

@@ -72,7 +72,7 @@ describe('DataTrackPacket', () => {
 
       const packet = new DataTrackPacket(header, payloadBytes);
 
-      expect(packet.toBinaryLengthBytes()).toStrictEqual(78);
+      expect(packet.toBinaryLengthBytes()).toStrictEqual(74);
       expect(packet.toBinary()).toStrictEqual(
         new Uint8Array([
           0xc, // Version 0, final, extension
@@ -88,13 +88,11 @@ describe('DataTrackPacket', () => {
           17,
           136,
           0, // Rtp oriented extension words (big endian)
-          7,
+          6,
 
           // E2ee extension
-          0, // ID 1 (big endian)
-          1,
-          0, // Length 12 (big endian)
-          12,
+          1, // ID 1
+          13, // Length 13
           0xfa, // Key index
           0x3c, // Iv array
           0x3c,
@@ -110,10 +108,8 @@ describe('DataTrackPacket', () => {
           0x3c,
 
           // User timestamp extension
-          0, // ID 2 (big endian)
-          2,
-          0, // Length 7 (big endian)
-          7,
+          2, // ID 2
+          8, // Length 8
           68, // Timestamp value (big endian)
           17,
           34,
@@ -178,7 +174,7 @@ describe('DataTrackPacket', () => {
 
       const packet = new DataTrackPacket(header, payloadBytes);
 
-      expect(packet.toBinaryLengthBytes()).toStrictEqual(66);
+      expect(packet.toBinaryLengthBytes()).toStrictEqual(62);
       expect(packet.toBinary()).toStrictEqual(
         new Uint8Array([
           0x14, // Version 0, start, extension
@@ -194,13 +190,11 @@ describe('DataTrackPacket', () => {
           0,
           104,
           0, // RTP oriented extension words (big endian)
-          4,
+          3,
 
           // E2ee extension
-          0, // ID 1 (big endian)
-          1,
-          0, // Length 12 (big endian)
-          12,
+          1, // ID 1
+          13, // Length 13
           0xfa, // Key index
           0x3c, // Iv array
           0x3c,
@@ -216,8 +210,6 @@ describe('DataTrackPacket', () => {
           0x3c,
 
           0, // Extension padding
-          0,
-          0,
 
           0xfa, // Payload
           0xfa,
@@ -431,13 +423,11 @@ describe('DataTrackPacket', () => {
         ...VALID_PACKET_BYTES,
 
         0, // RTP oriented extension words (big endian)
-        4,
+        3,
 
         // E2ee extension
-        0, // ID 1 (big endian)
-        1,
-        0, // Length 12 (big endian)
-        12,
+        1, // ID 1
+        12, // Length 12
         0xfa, // Key index
         0x3c, // Iv array
         0x3c,
@@ -453,8 +443,6 @@ describe('DataTrackPacket', () => {
         0x3c,
 
         0, // Padding
-        0,
-        0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 
@@ -476,10 +464,8 @@ describe('DataTrackPacket', () => {
         2,
 
         // User timestamp extension
-        0, // ID 2 (big endian)
-        2,
-        0, // Length 7 (big endian)
-        7,
+        2, // ID 2
+        7, // Length 7
         0x44, // Timestamp (big endian)
         0x11,
         0x22,
@@ -488,6 +474,9 @@ describe('DataTrackPacket', () => {
         0x11,
         0x88,
         0x11,
+
+        0, // Padding
+        0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 
@@ -508,19 +497,19 @@ describe('DataTrackPacket', () => {
         2,
 
         // Unknown / potential future extension
-        0, // ID 8 (big endian)
-        8,
-        0, // Length 12 (big endian)
-        6,
+        8, // ID 8
+        6, // Length 6
         0x1, // Payload
         0x2,
         0x3,
         0x4,
         0x5,
         0x6,
+        0x0,
 
         0x0, // Padding
         0x0,
+        0x0,
       ]);
       packetBytes[0] |= 1 << EXT_FLAG_SHIFT; // Extension flag
 

package/src/room/data-track/packetizer.test.ts

@@ -1,6 +1,6 @@
 /* eslint-disable @typescript-eslint/no-unused-vars */
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
-import { DataTrackFrame } from './frame';
+import { DataTrackFrameInternal } from './frame';
 import { DataTrackHandle } from './handle';
 import { FrameMarker } from './packet';
 import { DataTrackExtensions } from './packet/extensions';
@@ -90,7 +90,7 @@ describe('DataTrackPacketizer', () => {
   ])('should test packetizer edge cases', (payloadSizeBytes, mtuSizeBytes, label) => {
     const packetizer = new DataTrackPacketizer(DataTrackHandle.fromNumber(1), mtuSizeBytes);
 
-    const frame: DataTrackFrame = {
+    const frame: DataTrackFrameInternal = {
       payload: new Uint8Array(payloadSizeBytes).fill(0xab),
       extensions: new DataTrackExtensions(),
     };

package/src/room/data-track/packetizer.ts

@@ -1,6 +1,6 @@
 import type { Throws } from '@livekit/throws-transformer/throws';
 import { LivekitReasonedError } from '../errors';
-import { type DataTrackFrame } from './frame';
+import { type DataTrackFrameInternal } from './frame';
 import { DataTrackHandle } from './handle';
 import { DataTrackPacket, DataTrackPacketHeader, FrameMarker } from './packet';
 import { DataTrackClock, DataTrackTimestamp, WrapAroundUnsignedInt } from './utils';
@@ -38,7 +38,7 @@ export enum DataTrackPacketizerReason {
   MtuTooShort = 0,
 }
 
-/** A packetizer takes a {@link DataTrackFrame} as input and generates a series
+/** A packetizer takes a {@link DataTrackFrameInternal} as input and generates a series
  * of {@link DataTrackPacket}s for transmission to other clients over webrtc. */
 export default class DataTrackPacketizer {
   private handle: DataTrackHandle;
@@ -70,13 +70,13 @@ export default class DataTrackPacketizer {
     }
   }
 
-  /** Generates a series of packets for the specified {@link DataTrackPacketizerFrame}.
+  /** Generates a series of packets for the specified {@link DataTrackFrameInternal}.
    *
    * NOTE: The return value of this function is a generator, so it can be lazily ran if desired,
    * or converted to an array with {@link Array.from}.
    */
   *packetize(
-    frame: DataTrackFrame,
+    frame: DataTrackFrameInternal,
     options?: PacketizeOptions,
   ): Throws<Generator<DataTrackPacket>, DataTrackPacketizerError> {
     const frameNumber = this.frameNumber.getThenIncrement();

package/src/room/data-track/track-interfaces.ts

@@ -45,7 +45,7 @@ export const DataTrackSymbol: symbol = Symbol.for('lk.data-track');
 export interface IDataTrack extends ITrack {
   readonly typeSymbol: typeof DataTrackSymbol;
 
-  readonly info: DataTrackInfo;
+  readonly info?: DataTrackInfo;
 }
 
 export function isDataTrack(subject: unknown): subject is IDataTrack {

package/src/room/data-track/types.ts

@@ -1,3 +1,4 @@
+import { Encryption_Type, DataTrackInfo as ProtocolDataTrackInfo } from '@livekit/protocol';
 import { type DataTrackHandle } from './handle';
 
 export type DataTrackSid = string;
@@ -6,6 +7,25 @@ export type DataTrackSid = string;
 export type DataTrackInfo = {
   sid: DataTrackSid;
   pubHandle: DataTrackHandle;
-  name: String;
+  name: string;
   usesE2ee: boolean;
 };
+
+export const DataTrackInfo = {
+  from(protocolInfo: ProtocolDataTrackInfo): DataTrackInfo {
+    return {
+      sid: protocolInfo.sid,
+      pubHandle: protocolInfo.pubHandle,
+      name: protocolInfo.name,
+      usesE2ee: protocolInfo.encryption !== Encryption_Type.NONE,
+    };
+  },
+  toProtobuf(info: DataTrackInfo): ProtocolDataTrackInfo {
+    return new ProtocolDataTrackInfo({
+      sid: info.sid,
+      pubHandle: info.pubHandle,
+      name: info.name,
+      encryption: info.usesE2ee ? Encryption_Type.GCM : Encryption_Type.NONE,
+    });
+  },
+};

package/src/room/events.ts

@@ -332,7 +332,7 @@ export enum RoomEvent {
   EncryptionError = 'encryptionError',
   /**
    * Emits whenever the current buffer status of a data channel changes
-   * args: (isLow: boolean, kind: [[DataPacket_Kind]])
+   * args: (isLow: boolean, kind: [[DataChannelKind]])
    */
   DCBufferStatusChanged = 'dcBufferStatusChanged',
 
@@ -352,6 +352,26 @@ export enum RoomEvent {
    * fired when the client receives connection metrics from other participants
    */
   MetricsReceived = 'metricsReceived',
+
+  /**
+   * Emits when a new data track has been published by a downstream participant.
+   */
+  DataTrackPublished = 'dataTrackPublished',
+
+  /**
+   * Emits when a new data track has been unpublished by a downstream participant.
+   */
+  DataTrackUnpublished = 'dataTrackUnpublished',
+
+  /**
+   * Emits when a new data track has been published locally.
+   */
+  LocalDataTrackPublished = 'localDataTrackPublished',
+
+  /**
+   * Emits when a new data track has been unpublished locally.
+   */
+  LocalDataTrackUnpublished = 'localDataTrackUnpublished',
 }
 
 export enum ParticipantEvent {
@@ -606,6 +626,11 @@ export enum EngineEvent {
   SignalRequestResponse = 'signalRequestResponse',
   SignalConnected = 'signalConnected',
   RoomMoved = 'roomMoved',
+  PublishDataTrackResponse = 'publishDataTrackResponse',
+  UnPublishDataTrackResponse = 'unPublishDataTrackResponse',
+  DataTrackSubscriberHandles = 'dataTrackSubscriberHandles',
+  DataTrackPacketReceived = 'dataTrackPacketReceived',
+  Joined = 'joined',
 }
 
 export enum TrackEvent {

package/src/room/participant/LocalParticipant.ts

@@ -1,3 +1,4 @@
+import { Mutex } from '@livekit/mutex';
 import {
   AddTrackRequest,
   AudioTrackFeature,
@@ -27,8 +28,13 @@ import type { InternalRoomOptions } from '../../options';
 import TypedPromise from '../../utils/TypedPromise';
 import { PCTransportState } from '../PCTransportManager';
 import type RTCEngine from '../RTCEngine';
+import { DataChannelKind } from '../RTCEngine';
 import type OutgoingDataStreamManager from '../data-stream/outgoing/OutgoingDataStreamManager';
 import type { TextStreamWriter } from '../data-stream/outgoing/StreamWriter';
+import LocalDataTrack from '../data-track/LocalDataTrack';
+import type OutgoingDataTrackManager from '../data-track/outgoing/OutgoingDataTrackManager';
+import { DataTrackPublishError } from '../data-track/outgoing/errors';
+import type { DataTrackOptions } from '../data-track/outgoing/types';
 import { defaultVideoCodec } from '../defaults';
 import {
   DeviceUnsupportedError,
@@ -138,6 +144,8 @@ export default class LocalParticipant extends Participant {
 
   private encryptionType: Encryption_Type = Encryption_Type.NONE;
 
+  private e2eeStateMutex = new Mutex();
+
   private reconnectFuture?: Future<void, Error>;
 
   private signalConnectedFuture?: Future<void, Error>;
@@ -150,6 +158,8 @@ export default class LocalParticipant extends Participant {
 
   private roomOutgoingDataStreamManager: OutgoingDataStreamManager;
 
+  private roomOutgoingDataTrackManager: OutgoingDataTrackManager;
+
   private pendingSignalRequests: Map<
     number,
     {
@@ -179,6 +189,7 @@ export default class LocalParticipant extends Participant {
     options: InternalRoomOptions,
     roomRpcHandlers: Map<string, (data: RpcInvocationData) => Promise<string>>,
     roomOutgoingDataStreamManager: OutgoingDataStreamManager,
+    roomOutgoingDataTrackManager: OutgoingDataTrackManager,
   ) {
     super(sid, identity, undefined, undefined, undefined, {
       loggerName: options.loggerName,
@@ -198,6 +209,7 @@ export default class LocalParticipant extends Participant {
     this.pendingSignalRequests = new Map();
     this.rpcHandlers = roomRpcHandlers;
     this.roomOutgoingDataStreamManager = roomOutgoingDataStreamManager;
+    this.roomOutgoingDataTrackManager = roomOutgoingDataTrackManager;
   }
 
   get lastCameraError(): Error | undefined {
@@ -311,6 +323,35 @@ export default class LocalParticipant extends Participant {
       }
       this.pendingSignalRequests.delete(requestId);
     }
+
+    switch (response.request.case) {
+      case 'publishDataTrack': {
+        let error;
+        switch (response.reason) {
+          case RequestResponse_Reason.NOT_ALLOWED:
+            error = DataTrackPublishError.notAllowed(response.message);
+            break;
+          case RequestResponse_Reason.DUPLICATE_NAME:
+            error = DataTrackPublishError.duplicateName(response.message);
+            break;
+          case RequestResponse_Reason.INVALID_NAME:
+            error = DataTrackPublishError.invalidName(response.message);
+            break;
+          case RequestResponse_Reason.LIMIT_EXCEEDED:
+            error = DataTrackPublishError.limitReached(response.message);
+            break;
+          default:
+            error = DataTrackPublishError.unknown(response.reason, response.message);
+            return;
+        }
+
+        this.roomOutgoingDataTrackManager.receivedSfuPublishResponse(
+          response.request.value.pubHandle,
+          { type: 'error', error },
+        );
+        break;
+      }
+    }
   };
 
   private handleDataPacket = (packet: DataPacket) => {
@@ -461,8 +502,20 @@ export default class LocalParticipant extends Participant {
 
   /** @internal */
   async setE2EEEnabled(enabled: boolean) {
-    this.encryptionType = enabled ? Encryption_Type.GCM : Encryption_Type.NONE;
-    await this.republishAllTracks(undefined, false);
+    const unlock = await this.e2eeStateMutex.lock();
+    try {
+      this.encryptionType = enabled ? Encryption_Type.GCM : Encryption_Type.NONE;
+      await Promise.all(this.pendingPublishPromises.values());
+      if (
+        this.trackPublications.size === 0 ||
+        Array.from(this.trackPublications.values()).every((pub) => pub.isEncrypted === enabled)
+      ) {
+        return;
+      }
+      await this.republishAllTracks(undefined, false);
+    } finally {
+      unlock();
+    }
   }
 
   /**
@@ -1648,7 +1701,8 @@ export default class LocalParticipant extends Participant {
    * @param options optionally specify a `reliable`, `topic` and `destination`
    */
   async publishData(data: Uint8Array, options: DataPublishOptions = {}): Promise<void> {
-    const kind = options.reliable ? DataPacket_Kind.RELIABLE : DataPacket_Kind.LOSSY;
+    const kind = options.reliable ? DataChannelKind.RELIABLE : DataChannelKind.LOSSY;
+    const dataPacketKind = options.reliable ? DataPacket_Kind.RELIABLE : DataPacket_Kind.LOSSY;
     const destinationIdentities = options.destinationIdentities;
     const topic = options.topic;
 
@@ -1660,7 +1714,7 @@ export default class LocalParticipant extends Participant {
     });
 
     const packet = new DataPacket({
-      kind: kind,
+      kind: dataPacketKind,
       value: {
         case: 'user',
         value: userPacket,
@@ -1688,7 +1742,7 @@ export default class LocalParticipant extends Participant {
       },
     });
 
-    await this.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+    await this.engine.sendDataPacket(packet, DataChannelKind.RELIABLE);
   }
 
   /** @deprecated Consider migrating to {@link sendText} */
@@ -1708,7 +1762,7 @@ export default class LocalParticipant extends Participant {
         }),
       },
     });
-    await this.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+    await this.engine.sendDataPacket(packet, DataChannelKind.RELIABLE);
 
     this.emit(ParticipantEvent.ChatMessage, msg);
     return msg;
@@ -1731,7 +1785,7 @@ export default class LocalParticipant extends Participant {
         }),
       },
     });
-    await this.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+    await this.engine.sendDataPacket(packet, DataChannelKind.RELIABLE);
     this.emit(ParticipantEvent.ChatMessage, msg);
     return msg;
   }
@@ -1946,7 +2000,7 @@ export default class LocalParticipant extends Participant {
       },
     });
 
-    await this.engine.sendDataPacket(packet, DataPacket_Kind.RELIABLE);
+    await this.engine.sendDataPacket(packet, DataChannelKind.RELIABLE);
   }
 
   /** @internal */
@@ -2235,4 +2289,16 @@ export default class LocalParticipant extends Participant {
       await sleep(20);
     }
   }
+
+  /** Publishes a data track.
+   *
+   * Returns the published data track if successful. Use {@link LocalDataTrack#tryPush}
+   * to send data frames on the track.
+   */
+  async publishDataTrack(options: DataTrackOptions): Promise<LocalDataTrack> {
+    const track = new LocalDataTrack(options, this.roomOutgoingDataTrackManager);
+    await track.publish();
+
+    return track;
+  }
 }

package/src/room/participant/RemoteParticipant.ts

@@ -5,6 +5,8 @@ import type {
   UpdateTrackSettings,
 } from '@livekit/protocol';
 import type { SignalClient } from '../../api/SignalClient';
+import { DeferrableMap } from '../../utils/deferrable-map';
+import type RemoteDataTrack from '../data-track/RemoteDataTrack';
 import { ParticipantEvent, TrackEvent } from '../events';
 import RemoteAudioTrack from '../track/RemoteAudioTrack';
 import type RemoteTrack from '../track/RemoteTrack';
@@ -27,6 +29,14 @@ export default class RemoteParticipant extends Participant {
 
   trackPublications: Map<string, RemoteTrackPublication>;
 
+  /** A map of data track name to the corresponding {@link RemoteDataTrack}.
+   * @example
+   * // An already existing data track:
+   * const track = remoteParticipant.dataTracks.get("data track name");
+   * // Wait for a data track which will be published soon:
+   * const track = await remoteParticipant.dataTracks.getDeferred("data track name"); */
+  dataTracks: DeferrableMap<RemoteDataTrack['info']['name'], RemoteDataTrack>;
+
   signalClient: SignalClient;
 
   private volumeMap: Map<Track.Source, number>;
@@ -75,6 +85,7 @@ export default class RemoteParticipant extends Participant {
     this.trackPublications = new Map();
     this.audioTrackPublications = new Map();
     this.videoTrackPublications = new Map();
+    this.dataTracks = new DeferrableMap();
     this.volumeMap = new Map();
   }
 
@@ -376,6 +387,20 @@ export default class RemoteParticipant extends Participant {
     await Promise.all(promises);
   }
 
+  /** @internal */
+  addRemoteDataTrack(remoteDataTrack: RemoteDataTrack) {
+    this.dataTracks.set(remoteDataTrack.info.name, remoteDataTrack);
+  }
+
+  /** @internal */
+  removeRemoteDataTrack(remoteDataTrackSid: RemoteDataTrack['info']['sid']) {
+    for (const [name, dataTrack] of this.dataTracks.entries()) {
+      if (remoteDataTrackSid === dataTrack.info.sid) {
+        this.dataTracks.delete(name);
+      }
+    }
+  }
+
   /** @internal */
   emit<E extends keyof ParticipantEventCallbacks>(
     event: E,

package/src/room/utils.ts

@@ -775,3 +775,7 @@ export function extractMaxAgeFromRequestHeaders(headers: Headers): number | unde
   }
   return undefined;
 }
+
+export function isCompressionStreamSupported() {
+  return typeof CompressionStream !== 'undefined';
+}

package/src/utils/deferrable-map.ts

@@ -0,0 +1,109 @@
+import { type Throws } from '@livekit/throws-transformer/throws';
+import { Future } from '../room/utils';
+
+/** An error which is thrown if a {@link DeferrableMap#getDeferred} call is aborted midway
+ * through. */
+export class DeferrableMapAbortError extends DOMException {
+  reason: unknown;
+
+  constructor(message: string, reason?: unknown) {
+    super(message, 'AbortError');
+    this.reason = reason;
+  }
+}
+
+/**
+ * A Map-like container keyed by unique strings that supports the ability to wait
+ * for future keys to show up in the map.
+ *
+ * @example
+ * // An already existing key:
+ * const value = map.get("key");
+ * // Wait for a key which will be added soon:
+ * const value = await map.getDeferred("key");
+ */
+export class DeferrableMap<K, V> extends Map<K, V> {
+  private pending: Map<K, Array<Future<V, DeferrableMapAbortError>>> = new Map();
+
+  set(key: K, value: V): this {
+    super.set(key, value);
+
+    // Resolve any futures waiting on this key.
+    const futures = this.pending.get(key);
+    if (futures) {
+      for (const future of futures) {
+        if (!future.isResolved) {
+          future.resolve?.(value);
+        }
+      }
+      this.pending.delete(key);
+    }
+
+    return this;
+  }
+
+  get [Symbol.toStringTag](): string {
+    return 'WaitableMap';
+  }
+
+  /**
+   * Returns the value for `key` immediately if it exists, otherwise returns a
+   * promise that resolves once `set(key, value)` is called.
+   *
+   * If an `AbortSignal` is provided and it is aborted before the key appears,
+   * the returned promise rejects with an {@link DeferrableMapAbortError}.
+   */
+  getDeferred(key: K): Promise<V>;
+  getDeferred(key: K, signal: AbortSignal): Promise<Throws<V, DeferrableMapAbortError>>;
+  async getDeferred(key: K, signal?: AbortSignal) {
+    const existing = this.get(key);
+    if (typeof existing !== 'undefined') {
+      return existing;
+    }
+
+    // Bail out immediately if the signal is already aborted.
+    if (signal?.aborted) {
+      throw new DeferrableMapAbortError('The operation was aborted.', signal.reason);
+    }
+
+    const future = new Future<V, DeferrableMapAbortError>(undefined, () => {
+      // Clean up the pending list when the future settles.
+      const futures = this.pending.get(key);
+      if (!futures) {
+        return;
+      }
+
+      const idx = futures.indexOf(future);
+      if (idx !== -1) {
+        futures.splice(idx, 1);
+      }
+      if (futures.length === 0) {
+        this.pending.delete(key);
+      }
+    });
+
+    const existingFutures = this.pending.get(key);
+    if (existingFutures) {
+      existingFutures.push(future);
+    } else {
+      this.pending.set(key, [future]);
+    }
+
+    // If a signal was provided, listen for abort and reject the future.
+    if (signal) {
+      const onAbort = () => {
+        if (!future.isResolved) {
+          future.reject?.(new DeferrableMapAbortError('The operation was aborted.', signal.reason));
+        }
+      };
+      signal.addEventListener('abort', onAbort, { once: true });
+
+      // Clean up the listener once the future settles (resolved or rejected).
+      future.promise.finally(() => {
+        signal.removeEventListener('abort', onAbort);
+      });
+    }
+
+    return future.promise;
+  }
+}