livekit-client 2.17.3 → 2.18.1

package/src/room/data-track/packet/errors.ts

@@ -11,7 +11,7 @@ export enum DataTrackDeserializeErrorReason {
 }
 
 export class DataTrackDeserializeError<
-  Reason extends DataTrackDeserializeErrorReason,
+  Reason extends DataTrackDeserializeErrorReason = DataTrackDeserializeErrorReason,
 > extends LivekitReasonedError<DataTrackDeserializeErrorReason> {
   readonly name = 'DataTrackDeserializeError';
 
@@ -73,21 +73,13 @@ export class DataTrackDeserializeError<
   }
 }
 
-export type DataTrackDeserializeErrorAll =
-  | DataTrackDeserializeError<DataTrackDeserializeErrorReason.TooShort>
-  | DataTrackDeserializeError<DataTrackDeserializeErrorReason.HeaderOverrun>
-  | DataTrackDeserializeError<DataTrackDeserializeErrorReason.MissingExtWords>
-  | DataTrackDeserializeError<DataTrackDeserializeErrorReason.UnsupportedVersion>
-  | DataTrackDeserializeError<DataTrackDeserializeErrorReason.InvalidHandle>
-  | DataTrackDeserializeError<DataTrackDeserializeErrorReason.MalformedExt>;
-
 export enum DataTrackSerializeErrorReason {
   TooSmallForHeader = 0,
   TooSmallForPayload = 1,
 }
 
 export class DataTrackSerializeError<
-  Reason extends DataTrackSerializeErrorReason,
+  Reason extends DataTrackSerializeErrorReason = DataTrackSerializeErrorReason,
 > extends LivekitReasonedError<DataTrackSerializeErrorReason> {
   readonly name = 'DataTrackSerializeError';
 
@@ -115,7 +107,3 @@ export class DataTrackSerializeError<
     );
   }
 }
-
-export type DataTrackSerializeErrorAll =
-  | DataTrackSerializeError<DataTrackSerializeErrorReason.TooSmallForHeader>
-  | DataTrackSerializeError<DataTrackSerializeErrorReason.TooSmallForPayload>;

package/src/room/data-track/packet/extensions.ts

@@ -1,6 +1,6 @@
-import { type Throws } from '../../../utils/throws';
+import { type Throws } from '@livekit/throws-transformer/throws';
 import { coerceToDataView } from '../utils';
-import { EXT_TAG_PADDING, U8_LENGTH_BYTES, U16_LENGTH_BYTES, U64_LENGTH_BYTES } from './constants';
+import { EXT_TAG_PADDING, U8_LENGTH_BYTES, U64_LENGTH_BYTES } from './constants';
 import { DataTrackDeserializeError, DataTrackDeserializeErrorReason } from './errors';
 import Serializable from './serializable';
 
@@ -20,7 +20,7 @@ export class DataTrackUserTimestampExtension extends DataTrackExtension {
 
   static lengthBytes = 8;
 
-  private timestamp: bigint;
+  timestamp: bigint;
 
   constructor(timestamp: bigint) {
     super();
@@ -29,8 +29,8 @@ export class DataTrackUserTimestampExtension extends DataTrackExtension {
 
   toBinaryLengthBytes(): number {
     return (
-      U16_LENGTH_BYTES /* tag */ +
-      U16_LENGTH_BYTES /* length */ +
+      U8_LENGTH_BYTES /* tag */ +
+      U8_LENGTH_BYTES /* length */ +
       DataTrackUserTimestampExtension.lengthBytes
     );
   }
@@ -38,12 +38,11 @@ export class DataTrackUserTimestampExtension extends DataTrackExtension {
   toBinaryInto(dataView: DataView): Throws<number, never> {
     let byteIndex = 0;
 
-    dataView.setUint16(byteIndex, DataTrackUserTimestampExtension.tag);
-    byteIndex += U16_LENGTH_BYTES;
+    dataView.setUint8(byteIndex, DataTrackUserTimestampExtension.tag);
+    byteIndex += U8_LENGTH_BYTES;
 
-    const rtpOrientedLength = DataTrackUserTimestampExtension.lengthBytes - 1;
-    dataView.setUint16(byteIndex, rtpOrientedLength);
-    byteIndex += U16_LENGTH_BYTES;
+    dataView.setUint8(byteIndex, DataTrackUserTimestampExtension.lengthBytes);
+    byteIndex += U8_LENGTH_BYTES;
 
     dataView.setBigUint64(byteIndex, this.timestamp);
     byteIndex += U64_LENGTH_BYTES;
@@ -74,9 +73,9 @@ export class DataTrackE2eeExtension extends DataTrackExtension {
 
   static lengthBytes = 13;
 
-  private keyIndex: number;
+  keyIndex: number;
 
-  private iv: Uint8Array; /* NOTE: According to the rust implementation, this should be 12 bytes long. */
+  iv: Uint8Array; /* NOTE: According to the rust implementation, this should be 12 bytes long. */
 
   constructor(keyIndex: number, iv: Uint8Array) {
     super();
@@ -86,21 +85,18 @@ export class DataTrackE2eeExtension extends DataTrackExtension {
 
   toBinaryLengthBytes(): number {
     return (
-      U16_LENGTH_BYTES /* tag */ +
-      U16_LENGTH_BYTES /* length */ +
-      DataTrackE2eeExtension.lengthBytes
+      U8_LENGTH_BYTES /* tag */ + U8_LENGTH_BYTES /* length */ + DataTrackE2eeExtension.lengthBytes
     );
   }
 
   toBinaryInto(dataView: DataView): Throws<number, never> {
     let byteIndex = 0;
 
-    dataView.setUint16(byteIndex, DataTrackE2eeExtension.tag);
-    byteIndex += U16_LENGTH_BYTES;
+    dataView.setUint8(byteIndex, DataTrackE2eeExtension.tag);
+    byteIndex += U8_LENGTH_BYTES;
 
-    const rtpOrientedLength = DataTrackE2eeExtension.lengthBytes - 1;
-    dataView.setUint16(byteIndex, rtpOrientedLength);
-    byteIndex += U16_LENGTH_BYTES;
+    dataView.setUint8(byteIndex, DataTrackE2eeExtension.lengthBytes);
+    byteIndex += U8_LENGTH_BYTES;
 
     dataView.setUint8(byteIndex, this.keyIndex);
     byteIndex += U8_LENGTH_BYTES;
@@ -194,13 +190,12 @@ export class DataTrackExtensions extends Serializable {
     let e2ee: DataTrackE2eeExtension | undefined;
 
     let byteIndex = 0;
-    while (dataView.byteLength - byteIndex >= U16_LENGTH_BYTES + U16_LENGTH_BYTES) {
-      const tag = dataView.getUint16(byteIndex);
-      byteIndex += U16_LENGTH_BYTES;
+    while (dataView.byteLength - byteIndex >= U8_LENGTH_BYTES + U8_LENGTH_BYTES) {
+      const tag = dataView.getUint8(byteIndex);
+      byteIndex += U8_LENGTH_BYTES;
 
-      const rtpOrientedLength = dataView.getUint16(byteIndex);
-      const lengthBytes = rtpOrientedLength + 1;
-      byteIndex += U16_LENGTH_BYTES;
+      const lengthBytes = dataView.getUint8(byteIndex);
+      byteIndex += U8_LENGTH_BYTES;
 
       if (tag === EXT_TAG_PADDING) {
         // Skip padding

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/packet/index.ts

@@ -1,4 +1,4 @@
-import { type Throws } from '../../../utils/throws';
+import { type Throws } from '@livekit/throws-transformer/throws';
 import { DataTrackHandle, DataTrackHandleError, DataTrackHandleErrorReason } from '../handle';
 import {
   DataTrackTimestamp,
@@ -26,9 +26,7 @@ import {
 } from './constants';
 import {
   DataTrackDeserializeError,
-  type DataTrackDeserializeErrorAll,
   DataTrackSerializeError,
-  type DataTrackSerializeErrorAll,
   DataTrackSerializeErrorReason,
 } from './errors';
 import { DataTrackExtensions } from './extensions';
@@ -167,7 +165,7 @@ export class DataTrackPacketHeader extends Serializable {
 
   static fromBinary<Input extends DataView | ArrayBuffer | Uint8Array>(
     input: Input,
-  ): Throws<[header: DataTrackPacketHeader, byteLength: number], DataTrackDeserializeErrorAll> {
+  ): Throws<[header: DataTrackPacketHeader, byteLength: number], DataTrackDeserializeError> {
     const dataView = coerceToDataView(input);
 
     if (dataView.byteLength < BASE_HEADER_LEN) {
@@ -314,7 +312,7 @@ export class DataTrackPacket extends Serializable {
     return this.header.toBinaryLengthBytes() + this.payload.byteLength;
   }
 
-  toBinaryInto(dataView: DataView): Throws<number, DataTrackSerializeErrorAll> {
+  toBinaryInto(dataView: DataView): Throws<number, DataTrackSerializeError> {
     let byteIndex = 0;
     const headerLengthBytes = this.header.toBinaryInto(dataView);
     byteIndex += headerLengthBytes;
@@ -341,7 +339,7 @@ export class DataTrackPacket extends Serializable {
 
   static fromBinary<Input extends DataView | ArrayBuffer | Uint8Array>(
     input: Input,
-  ): Throws<[packet: DataTrackPacket, byteLength: number], DataTrackDeserializeErrorAll> {
+  ): Throws<[packet: DataTrackPacket, byteLength: number], DataTrackDeserializeError> {
     const dataView = coerceToDataView(input);
 
     const [header, headerByteLength] = DataTrackPacketHeader.fromBinary(dataView);

package/src/room/data-track/packet/serializable.ts

@@ -1,5 +1,5 @@
-import { type Throws } from '../../../utils/throws';
-import { type DataTrackSerializeErrorAll } from './errors';
+import { type Throws } from '@livekit/throws-transformer/throws';
+import { DataTrackSerializeError } from './errors';
 
 /** An abstract class implementing common behavior related to data track binary serialization. */
 export default abstract class Serializable {
@@ -7,10 +7,10 @@ export default abstract class Serializable {
   abstract toBinaryLengthBytes(): number;
 
   /** Given a DataView, serialize the instance inside and return the number of bytes written. */
-  abstract toBinaryInto(dataView: DataView): Throws<number, DataTrackSerializeErrorAll>;
+  abstract toBinaryInto(dataView: DataView): Throws<number, DataTrackSerializeError>;
 
   /** Encodes the instance as binary and returns the data as a Uint8Array. */
-  toBinary(): Throws<Uint8Array, DataTrackSerializeErrorAll> {
+  toBinary(): Throws<Uint8Array, DataTrackSerializeError> {
     const lengthBytes = this.toBinaryLengthBytes();
     const output = new ArrayBuffer(lengthBytes);
     const view = new DataView(output);

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 '../../utils/throws';
+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';
@@ -12,7 +12,7 @@ type PacketizeOptions = {
 };
 
 export class DataTrackPacketizerError<
-  Reason extends DataTrackPacketizerReason,
+  Reason extends DataTrackPacketizerReason = DataTrackPacketizerReason,
 > extends LivekitReasonedError<Reason> {
   readonly name = 'DataTrackPacketizerError';
 
@@ -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,18 +70,15 @@ 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<DataTrackPacketizerReason.MtuTooShort>
-  > {
+  ): Throws<Generator<DataTrackPacket>, DataTrackPacketizerError> {
     const frameNumber = this.frameNumber.getThenIncrement();
     const headerParams = {
       marker: FrameMarker.Inter,

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

@@ -0,0 +1,53 @@
+import type { DataTrackInfo } from './types';
+
+function isObject(subject: unknown): subject is object {
+  return subject !== null && typeof subject === 'object';
+}
+
+export const TrackSymbol: symbol = Symbol.for('lk.track');
+
+export interface ITrack {
+  readonly trackSymbol: typeof TrackSymbol;
+}
+
+function isTrack(subject: unknown): subject is ITrack {
+  return isObject(subject) && 'trackSymbol' in subject && subject.trackSymbol === TrackSymbol;
+}
+
+/** An interface representing a track (of any type) which is local and sending data to the SFU. */
+export interface ILocalTrack extends ITrack {
+  readonly isLocal: true;
+
+  isPublished(): boolean;
+}
+
+// @ts-ignore - Export this in the future when cutting over to new track interfaces more widely
+function isLocalTrack(subject: unknown): subject is ILocalTrack {
+  return isTrack(subject) && 'isLocal' in subject && subject.isLocal === true;
+}
+
+export const RemoteTrackSymbol: symbol = Symbol.for('lk.remote-track');
+
+/** An interface representing a track (of any type) which is remote and receiving data from the SFU. */
+export interface IRemoteTrack extends ITrack {
+  readonly isLocal: false;
+}
+
+// @ts-ignore - Export this in the future when cutting over to new track interfaces more widely
+function isRemoteTrack(subject: unknown): subject is IRemoteTrack {
+  return (
+    isTrack(subject) && 'localitySymbol' in subject && subject.localitySymbol === RemoteTrackSymbol
+  );
+}
+
+export const DataTrackSymbol: symbol = Symbol.for('lk.data-track');
+/** An interface representing a data track, either local or remote. */
+export interface IDataTrack extends ITrack {
+  readonly typeSymbol: typeof DataTrackSymbol;
+
+  readonly info?: DataTrackInfo;
+}
+
+export function isDataTrack(subject: unknown): subject is IDataTrack {
+  return isTrack(subject) && 'typeSymbol' in subject && subject.typeSymbol === DataTrackSymbol;
+}

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

@@ -0,0 +1,31 @@
+import { Encryption_Type, DataTrackInfo as ProtocolDataTrackInfo } from '@livekit/protocol';
+import { type DataTrackHandle } from './handle';
+
+export type DataTrackSid = string;
+
+/** Information about a published data track. */
+export type DataTrackInfo = {
+  sid: DataTrackSid;
+  pubHandle: DataTrackHandle;
+  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 {