livekit-client 2.17.3 → 2.18.1

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

@@ -1,7 +1,7 @@
+import { type Throws } from '@livekit/throws-transformer/throws';
 import { LoggerNames, getLogger } from '../../logger';
-import { type Throws } from '../../utils/throws';
 import { LivekitReasonedError } from '../errors';
-import { type DataTrackFrame } from './frame';
+import { type DataTrackFrameInternal } from './frame';
 import { DataTrackPacket, FrameMarker } from './packet';
 import { DataTrackExtensions } from './packet/extensions';
 import { U16_MAX_SIZE, WrapAroundUnsignedInt } from './utils';
@@ -21,7 +21,7 @@ type PartialFrame = {
 
 /** An error indicating a frame was dropped. */
 export class DataTrackDepacketizerDropError<
-  Reason extends DataTrackDepacketizerDropReason,
+  Reason extends DataTrackDepacketizerDropReason = DataTrackDepacketizerDropReason,
 > extends LivekitReasonedError<Reason> {
   readonly name = 'DataTrackDepacketizerDropError';
 
@@ -38,9 +38,9 @@ export class DataTrackDepacketizerDropError<
     this.frameNumber = frameNumber;
   }
 
-  static interrupted(frameNumber: number) {
+  static interrupted(frameNumber: number, newFrameNumber: number) {
     return new DataTrackDepacketizerDropError(
-      'Interrupted by the start of a new frame',
+      `Interrupted by the start of a new frame ${newFrameNumber}`,
       DataTrackDepacketizerDropReason.Interrupted,
       frameNumber,
     );
@@ -94,18 +94,12 @@ export default class DataTrackDepacketizer {
   /** Should be repeatedly called with received {@link DataTrackPacket}s - intermediate calls
    * aggregate the packet's state internally, and return null.
    *
-   * Once this method is called with the final packet to form a frame, a new {@link DataTrackFrame}
+   * Once this method is called with the final packet to form a frame, a new {@link DataTrackFrameInternal}
    * is returned.*/
   push(
     packet: DataTrackPacket,
     options?: PushOptions,
-  ): Throws<
-    DataTrackFrame | null,
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Interrupted>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.BufferFull>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.UnknownFrame>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Incomplete>
-  > {
+  ): Throws<DataTrackFrameInternal | null, DataTrackDepacketizerDropError> {
     switch (packet.header.marker) {
       case FrameMarker.Single:
         return this.frameFromSingle(packet, options);
@@ -125,7 +119,7 @@ export default class DataTrackDepacketizer {
     packet: DataTrackPacket,
     options?: PushOptions,
   ): Throws<
-    DataTrackFrame | null,
+    DataTrackFrameInternal | null,
     DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Interrupted>
   > {
     if (packet.header.marker !== FrameMarker.Single) {
@@ -139,7 +133,10 @@ export default class DataTrackDepacketizer {
       if (options?.errorOnPartialFrames) {
         const frameNumber = this.partial.frameNumber;
         this.reset();
-        throw DataTrackDepacketizerDropError.interrupted(frameNumber);
+        throw DataTrackDepacketizerDropError.interrupted(
+          frameNumber,
+          packet.header.frameNumber.value,
+        );
       } else {
         log.warn(
           `Data track frame ${this.partial.frameNumber} was interrupted by the start of a new frame, dropping.`,
@@ -167,10 +164,13 @@ export default class DataTrackDepacketizer {
       if (options?.errorOnPartialFrames) {
         const frameNumber = this.partial.frameNumber;
         this.reset();
-        throw DataTrackDepacketizerDropError.interrupted(frameNumber);
+        throw DataTrackDepacketizerDropError.interrupted(
+          frameNumber,
+          packet.header.frameNumber.value,
+        );
       } else {
         log.warn(
-          `Data track frame ${this.partial.frameNumber} was interrupted by the start of a new frame, dropping.`,
+          `Data track frame ${this.partial.frameNumber} was interrupted by the start of a new frame ${packet.header.frameNumber.value}, dropping.`,
         );
       }
     }
@@ -191,13 +191,7 @@ export default class DataTrackDepacketizer {
   /** Push to the existing partial frame. */
   private pushToPartial(
     packet: DataTrackPacket,
-  ): Throws<
-    DataTrackFrame | null,
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Interrupted>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.UnknownFrame>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.BufferFull>
-    | DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Incomplete>
-  > {
+  ): Throws<DataTrackFrameInternal | null, DataTrackDepacketizerDropError> {
     if (packet.header.marker !== FrameMarker.Inter && packet.header.marker !== FrameMarker.Final) {
       // @throws-transformer ignore - this should be treated as a "panic" and not be caught
       throw new Error(
@@ -213,7 +207,10 @@ export default class DataTrackDepacketizer {
     if (packet.header.frameNumber.value !== this.partial.frameNumber) {
       const frameNumber = this.partial.frameNumber;
       this.reset();
-      throw DataTrackDepacketizerDropError.interrupted(frameNumber);
+      throw DataTrackDepacketizerDropError.interrupted(
+        frameNumber,
+        packet.header.frameNumber.value,
+      );
     }
 
     // NOTE: this check will block reprocessing packets with duplicate sequence values if the
@@ -246,7 +243,7 @@ export default class DataTrackDepacketizer {
     partial: PartialFrame,
     endSequence: number,
   ): Throws<
-    DataTrackFrame,
+    DataTrackFrameInternal,
     DataTrackDepacketizerDropError<DataTrackDepacketizerDropReason.Incomplete>
   > {
     const received = partial.payloads.size;

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

@@ -1,8 +1,34 @@
-import { DataTrackExtensions } from './packet/extensions';
-import DataTrackPacketizer from './packetizer';
+import { DataTrackExtensions, DataTrackUserTimestampExtension } from './packet/extensions';
 
 /** A pair of payload bytes and packet extensions which can be fed into a {@link DataTrackPacketizer}. */
 export type DataTrackFrame = {
+  payload: Uint8Array;
+  userTimestamp?: bigint;
+};
+
+/** An internal representation o data track frame which contains all SFU metadata. */
+export type DataTrackFrameInternal = {
   payload: Uint8Array;
   extensions: DataTrackExtensions;
 };
+
+export const DataTrackFrameInternal = {
+  from(frame: DataTrackFrame) {
+    return {
+      payload: frame.payload,
+      extensions: new DataTrackExtensions({
+        userTimestamp: frame.userTimestamp
+          ? new DataTrackUserTimestampExtension(frame.userTimestamp)
+          : undefined,
+      }),
+    };
+  },
+  /** Converts from a DataTrackFrameInternal -> DataTrackFrame. Some internal information is
+   * discarded like e2ee encrption extension data. */
+  lossyIntoFrame(frame: DataTrackFrameInternal): DataTrackFrame {
+    return {
+      payload: frame.payload,
+      userTimestamp: frame.extensions.userTimestamp?.timestamp,
+    };
+  },
+};

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

@@ -1,4 +1,4 @@
-import { type Throws } from '../../utils/throws';
+import { type Throws } from '@livekit/throws-transformer/throws';
 import { LivekitReasonedError } from '../errors';
 import { U16_MAX_SIZE } from './utils';
 
@@ -43,13 +43,7 @@ export class DataTrackHandleError<
 
 export type DataTrackHandle = number;
 export const DataTrackHandle = {
-  fromNumber(
-    raw: number,
-  ): Throws<
-    DataTrackHandle,
-    | DataTrackHandleError<DataTrackHandleErrorReason.TooLarge>
-    | DataTrackHandleError<DataTrackHandleErrorReason.Reserved>
-  > {
+  fromNumber(raw: number): Throws<DataTrackHandle, DataTrackHandleError> {
     if (raw === 0) {
       throw DataTrackHandleError.reserved(raw);
     }