livekit-client 2.20.1 → 2.21.0

package/src/room/data-stream/outgoing/header-utils.ts

@@ -0,0 +1,87 @@
+import {
+  DataPacket,
+  DataStream_ByteHeader,
+  DataStream_CompressionType,
+  DataStream_Header,
+  DataStream_OperationType,
+  DataStream_TextHeader,
+} from '@livekit/protocol';
+import type { ByteStreamInfo, StreamTextOptions, TextStreamInfo } from '../../types';
+import { numberToBigInt } from '../../utils';
+
+/** The data-streams-v2 wire signals carried directly on the header: the compression flag and the
+ * inline single-packet payload. Both used to live in reserved header attributes; they are now
+ * first-class protobuf fields on `DataStream.Header`. */
+export interface StreamHeaderV2Fields {
+  /** Compression applied to the inline/chunked payload. Defaults to `NONE` when omitted. */
+  compression?: DataStream_CompressionType;
+  /** The full payload smuggled into the header for single-packet (inline) sends. */
+  inlineContent?: Uint8Array;
+}
+
+/** Builds the `DataStream_Header` for a text stream from its info and stream options. */
+export function buildTextStreamHeader(
+  info: TextStreamInfo,
+  options?: Pick<StreamTextOptions, 'version' | 'replyToStreamId' | 'type'>,
+  v2?: StreamHeaderV2Fields,
+): DataStream_Header {
+  return new DataStream_Header({
+    streamId: info.id,
+    mimeType: info.mimeType,
+    topic: info.topic,
+    timestamp: numberToBigInt(info.timestamp),
+    totalLength: numberToBigInt(info.size),
+    attributes: info.attributes,
+    compression: v2?.compression ?? DataStream_CompressionType.NONE,
+    inlineContent: v2?.inlineContent,
+    contentHeader: {
+      case: 'textHeader',
+      value: new DataStream_TextHeader({
+        version: options?.version,
+        attachedStreamIds: info.attachedStreamIds,
+        replyToStreamId: options?.replyToStreamId,
+        operationType:
+          options?.type === 'update'
+            ? DataStream_OperationType.UPDATE
+            : DataStream_OperationType.CREATE,
+      }),
+    },
+  });
+}
+
+/** Builds the `DataStream_Header` for a byte stream from its info. */
+export function buildByteStreamHeader(
+  info: ByteStreamInfo,
+  v2?: StreamHeaderV2Fields,
+): DataStream_Header {
+  return new DataStream_Header({
+    streamId: info.id,
+    mimeType: info.mimeType,
+    topic: info.topic,
+    timestamp: numberToBigInt(info.timestamp),
+    totalLength: numberToBigInt(info.size),
+    attributes: info.attributes,
+    compression: v2?.compression ?? DataStream_CompressionType.NONE,
+    inlineContent: v2?.inlineContent,
+    contentHeader: {
+      case: 'byteHeader',
+      value: new DataStream_ByteHeader({
+        name: info.name,
+      }),
+    },
+  });
+}
+
+/** Wraps a `DataStream_Header` in a `DataPacket` ready to be sent over a data channel. */
+export function createStreamHeaderPacket(
+  header: DataStream_Header,
+  destinationIdentities?: Array<string>,
+): DataPacket {
+  return new DataPacket({
+    destinationIdentities,
+    value: {
+      case: 'streamHeader',
+      value: header,
+    },
+  });
+}

package/src/room/data-track/incoming/IncomingDataTrackManager.test.ts

@@ -86,6 +86,37 @@ describe('DataTrackIncomingManager', () => {
         DataTrackHandle.fromNumber(5),
       ]);
     });
+
+    it('should not republish when a track sid is reassigned', async () => {
+      const manager = new IncomingDataTrackManager();
+      const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
+        'sfuUpdateSubscription',
+        'trackPublished',
+        'trackUnpublished',
+      ]);
+
+      const pubHandle = DataTrackHandle.fromNumber(5);
+      const oldSid = 'old sid';
+      const newSid = 'new sid';
+
+      // Simulate track published
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: oldSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+
+      const { track } = await managerEvents.waitFor('trackPublished');
+      expect(track.info.sid).toStrictEqual(oldSid);
+
+      // Simulate publisher full reconnect: same track, new SID
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: newSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+
+      // No publish/unpublish should appear
+      expect(managerEvents.areThereBufferedEvents('trackPublished')).toStrictEqual(false);
+      expect(managerEvents.areThereBufferedEvents('trackUnpublished')).toStrictEqual(false);
+      expect(track.info.sid).toStrictEqual(newSid);
+    });
   });
 
   describe('Track subscription', () => {
@@ -1064,6 +1095,278 @@ describe('DataTrackIncomingManager', () => {
       expect(onlyFrame.done).toStrictEqual(false);
       expect(onlyFrame.value?.payload).toStrictEqual(new Uint8Array([0xb1, 0xb2]));
     });
+
+    it('should resubscribe an active subscription when a track sid is reassigned', async () => {
+      const manager = new IncomingDataTrackManager();
+      const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
+        'sfuUpdateSubscription',
+        'trackPublished',
+      ]);
+
+      const pubHandle = DataTrackHandle.fromNumber(5);
+      const oldSid = 'old sid';
+      const newSid = 'new sid';
+      const oldSubHandle = DataTrackHandle.fromNumber(6);
+      const newSubHandle = DataTrackHandle.fromNumber(7);
+
+      // Simulate track published
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: oldSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+      const { track } = await managerEvents.waitFor('trackPublished');
+
+      // Subscribe to the track
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(oldSid);
+      const reader = stream.getReader();
+      await managerEvents.waitFor('sfuUpdateSubscription');
+
+      // Simulate SFU assigning subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[oldSubHandle, oldSid]]));
+
+      await sfuSubscriptionComplete;
+
+      // Simulate publisher full reconnect: same track, new SID
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: newSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+
+      // Manager should re-subscribe under the new SID
+      const event = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(event.subscribe).toStrictEqual(true);
+      expect(event.sid).toStrictEqual(newSid);
+      expect(track.info.sid).toStrictEqual(newSid);
+
+      // Simulate SFU assigning a new subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[newSubHandle, newSid]]));
+
+      // Frames received on the new handle reach the existing subscriber
+      manager.packetReceived(
+        new DataTrackPacket(
+          new DataTrackPacketHeader({
+            extensions: new DataTrackExtensions(),
+            frameNumber: WrapAroundUnsignedInt.u16(0),
+            marker: FrameMarker.Single,
+            sequence: WrapAroundUnsignedInt.u16(0),
+            timestamp: DataTrackTimestamp.fromRtpTicks(0),
+            trackHandle: newSubHandle,
+          }),
+          new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]),
+        ).toBinary(),
+      );
+
+      const { value, done } = await reader.read();
+      expect(done).toStrictEqual(false);
+      expect(value?.payload).toStrictEqual(new Uint8Array([0x01, 0x02, 0x03, 0x04, 0x05]));
+    });
+
+    it('should stop routing packets on the old handle once a new handle is assigned', async () => {
+      const manager = new IncomingDataTrackManager();
+      const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
+        'sfuUpdateSubscription',
+        'trackPublished',
+      ]);
+
+      const pubHandle = DataTrackHandle.fromNumber(5);
+      const oldSid = 'old sid';
+      const newSid = 'new sid';
+      const oldSubHandle = DataTrackHandle.fromNumber(6);
+      const newSubHandle = DataTrackHandle.fromNumber(7);
+
+      // Simulate track published
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: oldSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+      await managerEvents.waitFor('trackPublished');
+
+      // Subscribe to the track
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(oldSid);
+      const reader = stream.getReader();
+      await managerEvents.waitFor('sfuUpdateSubscription');
+
+      // Simulate SFU assigning subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[oldSubHandle, oldSid]]));
+      await sfuSubscriptionComplete;
+
+      // Simulate publisher full reconnect: same track, new SID
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: newSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+      await managerEvents.waitFor('sfuUpdateSubscription');
+
+      // Simulate SFU assigning a new subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[newSubHandle, newSid]]));
+
+      const buildPacket = (trackHandle: DataTrackHandle, frameNumber: number, payload: number[]) =>
+        new DataTrackPacket(
+          new DataTrackPacketHeader({
+            extensions: new DataTrackExtensions(),
+            frameNumber: WrapAroundUnsignedInt.u16(frameNumber),
+            marker: FrameMarker.Single,
+            sequence: WrapAroundUnsignedInt.u16(frameNumber),
+            timestamp: DataTrackTimestamp.fromRtpTicks(0),
+            trackHandle,
+          }),
+          new Uint8Array(payload),
+        ).toBinary();
+
+      // A packet received on the old handle must be dropped, not routed to the subscriber
+      await manager.packetReceived(buildPacket(oldSubHandle, 0, [0xaa, 0xbb]));
+
+      // A packet received on the new handle reaches the subscriber
+      await manager.packetReceived(buildPacket(newSubHandle, 1, [0x01, 0x02]));
+
+      const { value, done } = await reader.read();
+      expect(done).toStrictEqual(false);
+      expect(value?.payload).toStrictEqual(new Uint8Array([0x01, 0x02]));
+    });
+
+    it('should terminate the sfu subscription when the stream is cancelled after a sid reassignment', async () => {
+      const manager = new IncomingDataTrackManager();
+      const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
+        'sfuUpdateSubscription',
+        'trackPublished',
+      ]);
+
+      const pubHandle = DataTrackHandle.fromNumber(5);
+      const oldSid = 'old sid';
+      const newSid = 'new sid';
+      const oldSubHandle = DataTrackHandle.fromNumber(6);
+      const newSubHandle = DataTrackHandle.fromNumber(7);
+
+      // Simulate track published
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: oldSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+      await managerEvents.waitFor('trackPublished');
+
+      // Subscribe to the track
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(oldSid);
+      const reader = stream.getReader();
+      await managerEvents.waitFor('sfuUpdateSubscription');
+
+      // Simulate SFU assigning subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[oldSubHandle, oldSid]]));
+      await sfuSubscriptionComplete;
+
+      // Simulate publisher full reconnect: same track, new SID
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: newSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+
+      // Manager should re-subscribe under the new SID
+      const resubscribeEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(resubscribeEvent.subscribe).toStrictEqual(true);
+      expect(resubscribeEvent.sid).toStrictEqual(newSid);
+
+      // Simulate SFU assigning a new subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[newSubHandle, newSid]]));
+
+      // Cancel the stream; the SFU unsubscribe must go out under the new SID
+      await reader.cancel();
+      const endEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(endEvent.sid).toStrictEqual(newSid);
+      expect(endEvent.subscribe).toStrictEqual(false);
+    });
+
+    it('should terminate the sfu subscription when the abortsignal fires after a sid reassignment', async () => {
+      const manager = new IncomingDataTrackManager();
+      const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
+        'sfuUpdateSubscription',
+        'trackPublished',
+      ]);
+
+      const pubHandle = DataTrackHandle.fromNumber(5);
+      const oldSid = 'old sid';
+      const newSid = 'new sid';
+      const oldSubHandle = DataTrackHandle.fromNumber(6);
+      const newSubHandle = DataTrackHandle.fromNumber(7);
+
+      // Simulate track published
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: oldSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+      await managerEvents.waitFor('trackPublished');
+
+      // Subscribe to the track
+      const controller = new AbortController();
+      const [stream, sfuSubscriptionComplete] = manager.openSubscriptionStream(
+        oldSid,
+        controller.signal,
+      );
+      const reader = stream.getReader();
+      await managerEvents.waitFor('sfuUpdateSubscription');
+
+      // Simulate SFU assigning subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[oldSubHandle, oldSid]]));
+      await sfuSubscriptionComplete;
+
+      // Simulate publisher full reconnect: same track, new SID
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: newSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+
+      // Manager should re-subscribe under the new SID
+      const resubscribeEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(resubscribeEvent.subscribe).toStrictEqual(true);
+      expect(resubscribeEvent.sid).toStrictEqual(newSid);
+
+      // Simulate SFU assigning a new subscriber handle
+      manager.receivedSfuSubscriberHandles(new Map([[newSubHandle, newSid]]));
+
+      // Abort the subscription; the SFU unsubscribe must go out under the new SID
+      const inFlightReadPromise = reader.read();
+      controller.abort();
+      await expect(inFlightReadPromise).rejects.toThrowError(
+        'Subscription to data track cancelled by caller',
+      );
+      const endEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(endEvent.sid).toStrictEqual(newSid);
+      expect(endEvent.subscribe).toStrictEqual(false);
+    });
+
+    it('should cancel a pending subscription under the new sid after a sid reassignment', async () => {
+      const manager = new IncomingDataTrackManager();
+      const managerEvents = subscribeToEvents<DataTrackIncomingManagerCallbacks>(manager, [
+        'sfuUpdateSubscription',
+        'trackPublished',
+      ]);
+
+      const pubHandle = DataTrackHandle.fromNumber(5);
+      const oldSid = 'old sid';
+      const newSid = 'new sid';
+
+      // Simulate track published
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: oldSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+      await managerEvents.waitFor('trackPublished');
+
+      // Begin subscribing to the track, leaving the subscription pending
+      const controller = new AbortController();
+      const [, sfuSubscriptionComplete] = manager.openSubscriptionStream(oldSid, controller.signal);
+      const startEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(startEvent.sid).toStrictEqual(oldSid);
+      expect(startEvent.subscribe).toStrictEqual(true);
+
+      // Simulate publisher full reconnect: same track, new SID
+      await manager.receiveSfuPublicationUpdates(
+        new Map([['id', [{ sid: newSid, pubHandle, name: 'test', usesE2ee: false }]]]),
+      );
+
+      // Manager should re-subscribe under the new SID
+      const resubscribeEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(resubscribeEvent.subscribe).toStrictEqual(true);
+      expect(resubscribeEvent.sid).toStrictEqual(newSid);
+
+      // Abort the pending subscription; the SFU unsubscribe must go out under the new SID
+      controller.abort();
+      await expect(sfuSubscriptionComplete).rejects.toStrictEqual(
+        DataTrackSubscribeError.cancelled(),
+      );
+      const endEvent = await managerEvents.waitFor('sfuUpdateSubscription');
+      expect(endEvent.sid).toStrictEqual(newSid);
+      expect(endEvent.subscribe).toStrictEqual(false);
+    });
   });
 });
 

package/src/room/data-track/incoming/IncomingDataTrackManager.ts

@@ -147,6 +147,10 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
     let streamController: ReadableStreamDefaultController<DataTrackFrame> | null = null;
     const sfuSubscriptionComplete = new Future<void, DataTrackSubscribeError>();
 
+    // Hold the descriptor by reference: SID reassignment re-keys the map, so lookups
+    // with the SID captured at subscribe time would fail.
+    const descriptor = this.descriptors.get(sid);
+
     const detachSignal = () => {
       signal?.removeEventListener('abort', onAbort);
     };
@@ -158,8 +162,7 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
         log.warn(`ReadableStream subscribed to ${sid} was not started.`);
         return;
       }
-      const descriptor = this.descriptors.get(sid);
-      if (!descriptor) {
+      if (!descriptor || this.descriptors.get(descriptor.info.sid) !== descriptor) {
         log.warn(`Unknown track ${sid}, skipping cancel...`);
         return;
       }
@@ -180,9 +183,8 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
       if (!streamController) {
         return;
       }
-      const currentDescriptor = this.descriptors.get(sid);
-      if (currentDescriptor?.subscription.type === 'active') {
-        currentDescriptor.subscription.streamControllers.delete(streamController);
+      if (descriptor?.subscription.type === 'active') {
+        descriptor.subscription.streamControllers.delete(streamController);
       }
 
       streamController.error(DataTrackSubscribeError.cancelled());
@@ -198,8 +200,7 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
 
           this.subscribeRequest(sid, signal)
             .then(async () => {
-              const descriptor = this.descriptors.get(sid);
-              if (!descriptor) {
+              if (!descriptor || this.descriptors.get(descriptor.info.sid) !== descriptor) {
                 log.error(`Unknown track ${sid}`);
                 const err = DataTrackSubscribeError.disconnected();
                 controller.error(err);
@@ -330,7 +331,7 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
             descriptor.subscription = { type: 'none' };
 
             // Let the SFU know that the subscribe has been cancelled
-            this.emit('sfuUpdateSubscription', { sid, subscribe: false });
+            this.emit('sfuUpdateSubscription', { sid: descriptor.info.sid, subscribe: false });
 
             if (previousDescriptorSubscription.type === 'pending') {
               previousDescriptorSubscription.completionFuture.reject?.(
@@ -458,6 +459,9 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
         if (this.descriptors.has(info.sid)) {
           continue;
         }
+        if (this.handleSidReassigned(publisherIdentity, info)) {
+          continue;
+        }
         await this.handleTrackPublished(publisherIdentity, info);
       }
       publisherParticipantToSidsInUpdate.set(publisherIdentity, sidsInUpdate);
@@ -499,6 +503,62 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
     this.emit('trackPublished', { track });
   }
 
+  /**
+   * Detects and handles SID reassignment, which occurs when the publisher
+   * republishes its tracks after a full reconnect.
+   *
+   * Returns `true` if an SID reassignment occurred, `false` otherwise.
+   */
+  private handleSidReassigned(
+    publisherIdentity: Participant['identity'],
+    info: DataTrackInfo,
+  ): boolean {
+    // Publisher identity and pub handle are stable across republications.
+    const existingEntry = Array.from(this.descriptors.entries()).find(
+      ([_sid, descriptor]) =>
+        descriptor.publisherIdentity === publisherIdentity &&
+        descriptor.info.pubHandle === info.pubHandle,
+    );
+    if (!existingEntry) {
+      return false;
+    }
+    const [oldSid, descriptor] = existingEntry;
+
+    // Invariant: other than SID, info should not have changed.
+    // TODO: consider refactoring to move SID out of info to allow for direct comparison.
+    const { name, usesE2ee } = descriptor.info;
+    if (name !== info.name || usesE2ee !== info.usesE2ee) {
+      log.warn(`Info mismatch for ${oldSid}, treating as new publication`);
+      return false;
+    }
+
+    const newSid = info.sid;
+    log.debug(`SID reassigned: ${oldSid} -> ${newSid}`);
+
+    if (!this.descriptors.delete(oldSid)) {
+      return false;
+    }
+    descriptor.info.sid = newSid;
+
+    switch (descriptor.subscription.type) {
+      case 'none':
+        break;
+      case 'pending':
+      case 'active':
+        // The SFU does not carry subscriptions across a publisher's full
+        // reconnect; re-request the subscription under the new SID.
+        this.emit('sfuUpdateSubscription', { sid: newSid, subscribe: true });
+        break;
+    }
+    if (descriptor.subscription.type === 'active') {
+      // Keep the routing index consistent until the SFU assigns a new handle
+      // (see `registerSubscriberHandle`).
+      this.subscriptionHandles.set(descriptor.subscription.subcriptionHandle, newSid);
+    }
+    this.descriptors.set(newSid, descriptor);
+    return true;
+  }
+
   handleTrackUnpublished(sid: DataTrackSid) {
     const descriptor = this.descriptors.get(sid);
     if (!descriptor) {
@@ -540,11 +600,13 @@ export default class IncomingDataTrackManager extends (EventEmitter as new () =>
       }
       case 'active': {
         // Update handle for an active subscription. This can occur following a full reconnect.
+        this.subscriptionHandles.delete(descriptor.subscription.subcriptionHandle);
         descriptor.subscription.subcriptionHandle = assignedHandle;
         this.subscriptionHandles.set(assignedHandle, sid);
         return;
       }
       case 'pending': {
+        log.debug(`data track subscription activated`, { sid, handle: assignedHandle });
         const pipeline = new IncomingDataTrackPipeline({
           info: descriptor.info,
           publisherIdentity: descriptor.publisherIdentity,

package/src/room/data-track/outgoing/OutgoingDataTrackManager.ts

@@ -326,11 +326,13 @@ export default class OutgoingDataTrackManager extends (EventEmitter as new () =>
       case 'pending': {
         if (result.type === 'ok') {
           const info = result.data;
+          log.debug(`SFU accepted publish request for handle ${handle}`, { sid: info.sid });
           const e2eeManager = info.usesE2ee ? this.e2eeManager : null;
           this.descriptors.set(info.pubHandle, Descriptor.active(info, e2eeManager));
 
           descriptor.completionFuture.resolve?.();
         } else {
+          log.debug(`SFU rejected publish request for handle ${handle}`, { error: result.error });
           descriptor.completionFuture.reject?.(result.error);
         }
         return;

package/src/room/errors.ts

@@ -208,7 +208,7 @@ export class UnsupportedServer extends LivekitError {
   readonly name = 'UnsupportedServer';
 
   constructor(message?: string) {
-    super(10, message ?? 'unsupported server');
+    super(10, message || 'unsupported server');
   }
 }
 
@@ -216,7 +216,7 @@ export class UnexpectedConnectionState extends LivekitError {
   readonly name = 'UnexpectedConnectionState';
 
   constructor(message?: string) {
-    super(12, message ?? 'unexpected connection state');
+    super(12, message || 'unexpected connection state');
   }
 }
 
@@ -224,7 +224,7 @@ export class NegotiationError extends LivekitError {
   readonly name = 'NegotiationError';
 
   constructor(message?: string) {
-    super(13, message ?? 'unable to negotiate');
+    super(13, message || 'unable to negotiate');
   }
 }
 
@@ -232,7 +232,7 @@ export class PublishDataError extends LivekitError {
   readonly name = 'PublishDataError';
 
   constructor(message?: string) {
-    super(14, message ?? 'unable to publish data');
+    super(14, message || 'unable to publish data');
   }
 }
 
@@ -287,6 +287,12 @@ export enum DataStreamErrorReason {
 
   // Encryption type mismatch.
   EncryptionTypeMismatch = 8,
+
+  // The serialized stream header packet (driven mainly by attributes) exceeds the MTU budget.
+  HeaderTooLarge = 9,
+
+  // The stream's (decompressed) payload exceeds the maximum allowed size.
+  PayloadTooLarge = 10,
 }
 
 export class DataStreamError extends LivekitReasonedError<DataStreamErrorReason> {

package/src/room/participant/LocalParticipant.ts

@@ -82,8 +82,10 @@ import {
   sourceToKind,
 } from '../track/utils';
 import {
+  type ByteStreamInfo,
   type ChatMessage,
   type DataPublishOptions,
+  type SendBytesOptions,
   type SendFileOptions,
   type SendTextOptions,
   type StreamBytesOptions,
@@ -100,6 +102,7 @@ import {
   isLocalVideoTrack,
   isSVCCodec,
   isSafari17Based,
+  isVideoCodec,
   isVideoTrack,
   isWeb,
   sleep,
@@ -1249,12 +1252,21 @@ export default class LocalParticipant extends Participant {
               maxbr: encodings[0]?.maxBitrate ? encodings[0].maxBitrate / 1000 : 0,
             });
           }
-        } else if (track.codec && isSVCCodec(track.codec) && encodings[0]?.maxBitrate) {
-          this.engine.pcManager.publisher.setTrackCodecBitrate({
-            cid: req.cid,
-            codec: track.codec,
-            maxbr: encodings[0].maxBitrate / 1000,
-          });
+        } else if (track.codec && isVideoCodec(track.codec)) {
+          // Apply start bitrate for all video codecs to prevent initial blurriness.
+          // - SVC codecs: use first encoding's bitrate (single stream with built-in layers)
+          // - Simulcast: sum all encoding bitrates (independent streams, BWE needs total)
+          const targetBitrate = isSVCCodec(track.codec)
+            ? (encodings[0]?.maxBitrate ?? 0)
+            : encodings.reduce((sum, enc) => sum + (enc.maxBitrate ?? 0), 0);
+          if (targetBitrate > 0) {
+            this.engine.pcManager.publisher.setTrackCodecBitrate({
+              cid: req.cid,
+              codec: track.codec,
+              maxbr: targetBitrate / 1000,
+              isScreenShare: track.source === Track.Source.ScreenShare,
+            });
+          }
         }
       }
 
@@ -1841,6 +1853,17 @@ export default class LocalParticipant extends Participant {
     return this.roomOutgoingDataStreamManager.sendFile(file, options);
   }
 
+  /**
+   * Sends the given bytes to participants in the room via the data channel.
+   * For files, consider using {@link sendFile}; for longer/incremental payloads, {@link streamBytes}.
+   *
+   * @param bytes The byte payload
+   * @param options.topic Topic identifier used to route the stream to appropriate handlers.
+   */
+  async sendBytes(bytes: Uint8Array, options?: SendBytesOptions): Promise<ByteStreamInfo> {
+    return this.roomOutgoingDataStreamManager.sendBytes(bytes, options);
+  }
+
   /**
    * Stream bytes incrementally to participants in the room via the data channel.
    * For sending files, consider using {@link sendFile} instead.

package/src/room/participant/Participant.ts

@@ -371,6 +371,11 @@ export default class Participant extends (EventEmitter as new () => TypedEmitter
   }
 
   protected addTrackPublication(publication: TrackPublication) {
+    this.log.debug(`adding track publication`, {
+      trackSid: publication.trackSid,
+      source: publication.source,
+      kind: publication.kind,
+    });
     // forward publication driven events
     publication.on(TrackEvent.Muted, () => {
       this.emit(ParticipantEvent.TrackMuted, publication);