livekit-client 2.22.2 → 2.22.4

package/src/room/PCTransport.ts

@@ -34,51 +34,130 @@ const startBitrateMultiplier = 0.9;
 /** Maximum x-google-start-bitrate in kbps. 1 Mbps prevents BWE from starting too aggressively. */
 const maxStartBitrateKbps = 1000;
 
+/**
+ * Minimum target bitrate in kbps for the start bitrate hint. Below this, seeding above the
+ * real capacity costs more than the ramp it saves, so libwebrtc's default is left in place.
+ */
+const minTargetBitrateKbps = 300;
+
 const debounceInterval = 20;
 
 /**
- * Applies the configured start bitrate when this media section belongs to `cid`.
- * This SDP munging is used for a bitrate setting that cannot be applied through
- * `RTCRtpEncodingParameters`.
+ * Codec payload for `codec` in this media section, when the section carries `cid`.
  *
- * Returns `undefined` when the section does not belong to the track, `0` when
- * it does but does not offer the requested codec, and the codec payload when the
- * requested codec is present (whether the bitrate was added or already set).
+ * Returns `undefined` when the section does not belong to the track, `0` when it does but
+ * does not offer the requested codec, and the codec payload otherwise.
  *
  * @internal
  */
-export function applyVideoStartBitrate(
+export function findTrackCodecPayload(
   media: MediaDescription,
   cid: string,
   codec: string,
-  maxbr: number,
-  isScreenShare = false,
 ): number | undefined {
   if (!media.msid?.includes(cid)) {
     return undefined;
   }
+  return media.rtp.find((rtp) => rtp.codec.toUpperCase() === codec.toUpperCase())?.payload ?? 0;
+}
 
-  const codecPayload =
-    media.rtp.find((rtp) => rtp.codec.toUpperCase() === codec.toUpperCase())?.payload ?? 0;
-  if (codecPayload === 0) {
-    return 0;
+/**
+ * Start bitrate hinted for a single track, or `undefined` when its target is too low to
+ * be worth seeding.
+ *
+ * 90% of the target leaves ~10% headroom for the estimator to settle. The same multiplier
+ * is used for every codec because the target already reflects the codec's efficiency.
+ * Camera is capped at 1 Mbps so the estimator does not open too aggressively on a
+ * high-bitrate track; screen share is exempt, because its content needs the bitrate
+ * immediately to stay legible.
+ *
+ * TODO: adjust dynamically from network conditions (e.g. a previous BWE estimate) rather
+ * than a fixed cap.
+ *
+ * @internal
+ */
+export function computeTrackStartBitrate(trackbr: TrackBitrateInfo): number | undefined {
+  if (trackbr.maxbr < minTargetBitrateKbps) {
+    return undefined;
   }
+  const calculated = Math.round(trackbr.maxbr * startBitrateMultiplier);
+  return trackbr.isScreenShare ? calculated : Math.min(calculated, maxStartBitrateKbps);
+}
 
-  // Use 90% of target bitrate, capped at 1 Mbps for camera to prevent BWE
-  // from starting too aggressively. Screen share is not capped since text/UI
-  // clarity requires high bitrate from the start.
-  // TODO: dynamically adjust start bitrate based on network conditions (e.g., previous BWE estimate)
-  const calculatedStartBitrate = Math.round(maxbr * startBitrateMultiplier);
-  const startBitrate = isScreenShare
-    ? calculatedStartBitrate
-    : Math.min(calculatedStartBitrate, maxStartBitrateKbps);
+/**
+ * The single start bitrate for this peer connection: the largest hint among the video
+ * m-sections of `media` that map to a published track.
+ *
+ * libwebrtc reads `x-google-start-bitrate` per m-section but applies it to the shared
+ * `Call` (`WebRtcVideoSendChannel::ApplyChangedParams` -> `SetSdpBitrateParameters`), where
+ * `RtpBitrateConfigurator` holds one config for the whole connection. Differing per-section
+ * values are therefore last-writer-wins, decided by m-section order, so every video section
+ * gets the same number instead.
+ *
+ * Only sections that can send local media are considered. `trackBitrates` is append-only and an
+ * unpublished section keeps its `a=msid`, so matching on msid alone would still pair a stale
+ * entry with its old section — letting an uncapped screen-share target seed a connection that
+ * now carries only a camera, or consuming the one-shot hint on a section that sends nothing.
+ *
+ * The direction is the discriminator, as an exclusion rather than a match: `recvonly` and
+ * `inactive` are the only directions that cannot carry local media, and they are exactly the
+ * two a dead section lands on — unpublish sets `inactive` (explicitly in
+ * `LocalParticipant.unpublishTrack`, and via `removeTrack`'s sendonly -> inactive transition for
+ * the simulcast senders), `removeTrack` on a `sendrecv` transceiver leaves `recvonly`, and the
+ * pre-populated placeholders are `recvonly`. Everything else sends: `sendonly` from the
+ * `addTransceiver` path, `sendrecv` from the legacy `addTrack` fallback (which reuses a
+ * transceiver rather than creating a sendonly one), and a section with no direction attribute,
+ * which SDP defaults to `sendrecv`.
+ *
+ * @internal
+ */
+export function computeConnectionStartBitrate(
+  media: MediaDescription[],
+  trackBitrates: TrackBitrateInfo[],
+): number | undefined {
+  let connectionStartBitrate: number | undefined;
+  for (const m of media) {
+    if (m.type !== 'video' || m.direction === 'recvonly' || m.direction === 'inactive') {
+      continue;
+    }
+    for (const trackbr of trackBitrates) {
+      if (!trackbr.cid) {
+        continue;
+      }
+      const codecPayload = findTrackCodecPayload(m, trackbr.cid, trackbr.codec);
+      if (codecPayload === undefined) {
+        continue;
+      }
+      const startBitrate = codecPayload > 0 ? computeTrackStartBitrate(trackbr) : undefined;
+      if (
+        startBitrate !== undefined &&
+        (connectionStartBitrate === undefined || startBitrate > connectionStartBitrate)
+      ) {
+        connectionStartBitrate = startBitrate;
+      }
+      break;
+    }
+  }
+  return connectionStartBitrate;
+}
 
+/**
+ * Declares `x-google-start-bitrate` on `codecPayload`'s fmtp. This SDP munging is used for
+ * a bitrate setting that cannot be applied through `RTCRtpEncodingParameters`.
+ *
+ * Returns whether the section now carries the hint.
+ *
+ * @internal
+ */
+export function applyVideoStartBitrate(
+  media: MediaDescription,
+  codecPayload: number,
+  startBitrate: number,
+): boolean {
   const fmtp = media.fmtp.find((entry) => entry.payload === codecPayload);
   if (fmtp) {
-    // If another track's fmtp already has a start bitrate, it cannot be
-    // overridden here because the payload type is shared across the bundle.
-    // This forces every track sharing that payload to use the initial track's
-    // start bitrate.
+    // A payload type is shared across the bundle, so a value written for one section is
+    // already the connection-level one; leave it rather than rewrite it.
     if (!fmtp.config.includes('x-google-start-bitrate')) {
       fmtp.config += `;x-google-start-bitrate=${startBitrate}`;
     }
@@ -90,7 +169,7 @@ export function applyVideoStartBitrate(
     });
   }
 
-  return codecPayload;
+  return true;
 }
 
 export const PCEvents = {
@@ -127,6 +206,11 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
 
   latestOfferId: number = 0;
 
+  private answeredOfferId: number = 0;
+
+  /** offerId (0 if unnumbered) of the answer being applied right now */
+  private answerInFlight: number | undefined;
+
   latestAcknowledgedOfferId: number = 0;
 
   private offerLock: Mutex;
@@ -141,6 +225,15 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
 
   trackBitrates: TrackBitrateInfo[] = [];
 
+  /**
+   * Whether an offer carrying the connection-level `x-google-start-bitrate` has been
+   * accepted locally. The hint is written once per peer connection: libwebrtc retains
+   * `start_bitrate_bps` in `RtpBitrateConfigurator` and re-applies it on network route
+   * changes, so a later rewrite is at best a no-op and at worst restarts a converged
+   * bandwidth estimator. A new peer connection (full reconnect) seeds a new estimator.
+   */
+  private hasAppliedVideoStartBitrate = false;
+
   remoteStereoMids: string[] = [];
 
   remoteNackMids: string[] = [];
@@ -250,6 +343,36 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       });
       return false;
     }
+    if (sd.type === 'answer') {
+      if (
+        isDuplicateAnswer(
+          offerId,
+          this.answerInFlight,
+          this.answeredOfferId,
+          this._pc?.signalingState,
+          this.pendingInitialOffer !== undefined,
+        )
+      ) {
+        // a repeat of an answer already applied or being applied (e.g.
+        // duplicated by a proxy): there is no local offer left to answer
+        this.log.warn('ignoring duplicate answer', { offerId });
+        return false;
+      }
+      // claimed before any await, so a copy arriving mid-apply is caught too;
+      // released however the apply ends, so a genuine retry is still possible
+      this.answerInFlight = offerId;
+    }
+    try {
+      return await this.applyRemoteDescription(sd, offerId);
+    } finally {
+      if (sd.type === 'answer') this.answerInFlight = undefined;
+    }
+  }
+
+  private async applyRemoteDescription(
+    sd: RTCSessionDescriptionInit,
+    offerId: number,
+  ): Promise<boolean> {
     let mungedSDP: string | undefined = undefined;
     if (sd.type === 'offer') {
       let { stereoMids, nackMids } = extractStereoAndNackAudioFromOffer(sd);
@@ -331,6 +454,8 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       mungedSDP = write(sdpParsed);
     }
     await this.setMungedSDP(sd, mungedSDP, true);
+    // only a successfully applied answer makes later copies duplicates
+    if (sd.type === 'answer' && offerId > 0) this.answeredOfferId = offerId;
 
     if (this.pendingCandidates.length > 0) {
       this.iceLog.debug('flushing queued ICE candidates', {
@@ -453,6 +578,14 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
       this.log.debug('original offer', { sdp: offer.sdp });
 
       const sdpParsed = parse(offer.sdp ?? '');
+      // One value for every video m-section, written only on the first offer that carries
+      // local video: the hint is connection-level in libwebrtc, so differing per-section
+      // values would be last-writer-wins on m-section order. Offers before any video is
+      // published (data channel or audio only) find no target and leave the latch unset.
+      const connectionStartBitrate = this.hasAppliedVideoStartBitrate
+        ? undefined
+        : computeConnectionStartBitrate(sdpParsed.media, this.trackBitrates);
+      let appliedVideoStartBitrate = false;
       sdpParsed.media.forEach((media) => {
         ensureIPAddrMatchVersion(media);
         if (media.type === 'audio') {
@@ -463,19 +596,21 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
               return false;
             }
 
-            const codecPayload = applyVideoStartBitrate(
-              media,
-              trackbr.cid,
-              trackbr.codec,
-              trackbr.maxbr,
-              trackbr.isScreenShare,
-            );
+            const codecPayload = findTrackCodecPayload(media, trackbr.cid, trackbr.codec);
             if (codecPayload === undefined) {
               return false;
             }
 
-            if (codecPayload > 0 && isSVCCodec(trackbr.codec) && !isSafari()) {
-              this.ddExtID = ensureVideoDDExtension(media, sdpParsed, this.ddExtID);
+            if (codecPayload > 0) {
+              if (connectionStartBitrate !== undefined) {
+                appliedVideoStartBitrate =
+                  applyVideoStartBitrate(media, codecPayload, connectionStartBitrate) ||
+                  appliedVideoStartBitrate;
+              }
+
+              if (isSVCCodec(trackbr.codec) && !isSafari()) {
+                this.ddExtID = ensureVideoDDExtension(media, sdpParsed, this.ddExtID);
+              }
             }
 
             return true;
@@ -500,7 +635,13 @@ export default class PCTransport extends (EventEmitter as new () => TypedEmitter
         });
         return;
       }
-      await this.setMungedSDP(offer, write(sdpParsed));
+      const mungedSdp = write(sdpParsed);
+      await this.setMungedSDP(offer, mungedSdp);
+      // setMungedSDP falls back to the unmunged SDP on rejection. Only consume the
+      // one-shot hint once the SDP carrying it has been accepted locally.
+      if (appliedVideoStartBitrate && offer.sdp === mungedSdp) {
+        this.hasAppliedVideoStartBitrate = true;
+      }
       this.onOffer(offer, this.latestOfferId);
     } finally {
       unlock();
@@ -952,6 +1093,26 @@ export function conformBundledCodecFmtp(
 }
 
 /** @internal */
+/**
+ * Whether an incoming answer repeats one already applied or being applied.
+ * Any answer for the offer whose answer is in flight is a duplicate, numbered
+ * or not. With an offerId (current servers) an answer is also a duplicate if
+ * that offer's answer was already applied. Without one, fall back to the
+ * signaling state: in `stable` no local offer is pending, unless the initial
+ * offer is still deferred (it is set locally only once its answer arrives).
+ */
+export function isDuplicateAnswer(
+  offerId: number,
+  answerInFlight: number | undefined,
+  answeredOfferId: number,
+  signalingState: RTCSignalingState | undefined,
+  hasPendingInitialOffer: boolean,
+): boolean {
+  if (answerInFlight === offerId) return true;
+  if (offerId > 0) return offerId === answeredOfferId;
+  return signalingState === 'stable' && !hasPendingInitialOffer;
+}
+
 export function extractStereoAndNackAudioFromOffer(offer: RTCSessionDescriptionInit): {
   stereoMids: string[];
   nackMids: string[];

package/src/room/PCTransportManager.ts

@@ -229,7 +229,9 @@ export class PCTransportManager {
         this.publisher.getConnectionState() !== 'connecting'
       ) {
         this.log.debug('negotiation required, start negotiating');
-        this.publisher.negotiate();
+        this.publisher.negotiate().catch((err) => {
+          this.log.error(err);
+        });
       }
       await Promise.all(
         this.requiredTransports?.map((transport) =>

package/src/room/RTCEngine.test.ts

@@ -10,6 +10,7 @@ import { PCTransportState } from './PCTransportManager';
 import RTCEngine, { DataChannelKind } from './RTCEngine';
 import { roomOptionDefaults } from './defaults';
 import { PublishDataError, UnexpectedConnectionState } from './errors';
+import { EngineEvent } from './events';
 
 describe('RTCEngine', () => {
   const originalRTCRtpSender = window.RTCRtpSender;
@@ -919,4 +920,87 @@ describe('RTCEngine', () => {
       expect(handleDisconnect).not.toHaveBeenCalled();
     });
   });
+
+  describe('negotiate', () => {
+    /**
+     * An engine whose `pcManager` parks in `negotiate()` until its abort controller fires, so
+     * several negotiations can be held in flight at once. The controllers are captured so tests
+     * can check the abort actually reached each in-flight call.
+     */
+    function stubNegotiableEngine(engine: RTCEngine) {
+      const controllers: AbortController[] = [];
+      const negotiate = vi.fn((abortController: AbortController) => {
+        controllers.push(abortController);
+        return new Promise<void>((_resolve, reject) => {
+          abortController.signal.addEventListener(
+            'abort',
+            () => reject(new Error('negotiation aborted')),
+            { once: true },
+          );
+        });
+      });
+      Object.assign(engine as unknown as Record<string, unknown>, {
+        _isClosed: false,
+        pcManager: {
+          requirePublisher: vi.fn(),
+          // a non-empty transceiver list keeps negotiate() off the createDataChannels path
+          publisher: { getTransceivers: () => [{}], off: vi.fn(), once: vi.fn() },
+          negotiate,
+        },
+        handleDisconnect: vi.fn(),
+      });
+      return { negotiate, controllers };
+    }
+
+    const pendingAborts = (engine: RTCEngine) =>
+      (engine as unknown as { pendingNegotiationAborts: Set<() => void> }).pendingNegotiationAborts;
+
+    it('does not add a Closing/Restarting listener per in-flight negotiate call', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const { negotiate, controllers } = stubNegotiableEngine(engine);
+
+      // A burst of server-initiated renegotiations used to stack a listener pair per call, which
+      // trips the emitter's max-listener warning at 11.
+      const closingBaseline = engine.listenerCount(EngineEvent.Closing);
+      const restartingBaseline = engine.listenerCount(EngineEvent.Restarting);
+
+      const pending = Array.from({ length: 20 }, () => engine.negotiate());
+      await tick();
+
+      expect(negotiate).toHaveBeenCalledTimes(20);
+      expect(engine.listenerCount(EngineEvent.Closing)).toBe(closingBaseline);
+      expect(engine.listenerCount(EngineEvent.Restarting)).toBe(restartingBaseline);
+
+      // The single central listener still has to reach every one of them.
+      engine.emit(EngineEvent.Closing);
+      await expect(Promise.all(pending)).resolves.toHaveLength(20);
+      expect(controllers).toHaveLength(20);
+      expect(controllers.every((c) => c.signal.aborted)).toBe(true);
+      expect(pendingAborts(engine).size).toBe(0);
+    });
+
+    it('aborts in-flight negotiations on restart without disarming later ones', async () => {
+      const engine = new RTCEngine(roomOptionDefaults);
+      const { controllers } = stubNegotiableEngine(engine);
+
+      const firstBatch = [engine.negotiate(), engine.negotiate()];
+      await tick();
+      engine.emit(EngineEvent.Restarting);
+      await expect(Promise.all(firstBatch)).resolves.toHaveLength(2);
+      expect(controllers.every((c) => c.signal.aborted)).toBe(true);
+
+      // Restarting fires on every reconnect attempt, so the fan-out point has to re-arm: a
+      // negotiation started after a restart must not be aborted on arrival.
+      const afterRestart = engine.negotiate();
+      await tick();
+      expect(controllers).toHaveLength(3);
+      expect(controllers[2].signal.aborted).toBe(false);
+      expect(pendingAborts(engine).size).toBe(1);
+
+      engine.emit(EngineEvent.Restarting);
+      await expect(afterRestart).resolves.toBeUndefined();
+      expect(controllers[2].signal.aborted).toBe(true);
+      expect(pendingAborts(engine).size).toBe(0);
+    });
+  });
 });

package/src/room/RTCEngine.ts

@@ -173,6 +173,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     return !!this.reconnectTimeout;
   }
 
+  get serverVersion(): string | undefined {
+    return (
+      this.latestJoinResponse?.serverInfo?.version ||
+      this.latestJoinResponse?.serverVersion ||
+      undefined
+    );
+  }
+
   /**
    * Owns the data channels: the three flow-controlled publisher wrappers (engine-lifetime; the
    * RTCDataChannel handles underneath are attached/detached as peer connections come and go, with
@@ -260,6 +268,14 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
   /** timestamp (ms) the primary transport entered `CONNECTING`, used to bound how long we tolerate it */
   private transportConnectingSince?: number;
 
+  /**
+   * Abort handlers for the in-flight `negotiate()` calls, which a single central
+   * Closing/Restarting listener pair fans out to. Registering a listener pair per call instead
+   * accumulates them on the engine emitter and trips its max-listener warning under
+   * renegotiation bursts.
+   */
+  private pendingNegotiationAborts = new Set<() => void>();
+
   constructor(private options: InternalRoomOptions) {
     super();
     this.log = getLogger(options.loggerName ?? LoggerNames.Engine, () => this.logContext);
@@ -300,6 +316,15 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
     this.client.onParticipantUpdate = (updates) =>
       this.emit(EngineEvent.ParticipantUpdate, updates);
     this.client.onJoined = (joinResponse) => this.emit(EngineEvent.Joined, joinResponse);
+
+    const abortPendingNegotiations = () => {
+      // Iterate a copy: each handler removes itself from the set as its negotiation settles.
+      for (const abort of Array.from(this.pendingNegotiationAborts)) {
+        abort();
+      }
+    };
+    this.on(EngineEvent.Closing, abortPendingNegotiations);
+    this.on(EngineEvent.Restarting, abortPendingNegotiations);
   }
 
   /** @internal */
@@ -655,8 +680,13 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
         sdp: sd.sdp,
         midToTrackId,
       });
-      this.midToTrackId = midToTrackId;
+      // in dual PC mode the publisher answer carries no mapping (the server's publisher
+      // transport has no sending tracks) and must not clobber the subscriber offer mapping
+      if (this.pcManager.mode === 'publisher-only') {
+        this.midToTrackId = midToTrackId;
+      }
       await this.pcManager.setPublisherAnswer(sd, offerId);
+      this.emit(EngineEvent.RequestSubscribedCodecRefresh);
     };
 
     // add candidate on trickle
@@ -726,7 +756,9 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
 
     this.client.onMediaSectionsRequirement = (requirement: MediaSectionsRequirement) => {
       this.addMediaSections(requirement.numAudios, requirement.numVideos);
-      this.negotiate();
+      this.negotiate().catch((err) => {
+        this.log.error(err);
+      });
     };
 
     this.client.onPublishDataTrackResponse = (event: PublishDataTrackResponse) => {
@@ -918,12 +950,21 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
           this.log.error('Received encrypted packet but E2EE not set up');
           return;
         }
-        const decryptedData = await this.e2eeManager?.handleEncryptedData(
-          dp.value.value.encryptedValue as NonSharedUint8Array,
-          dp.value.value.iv as NonSharedUint8Array,
-          dp.participantIdentity,
-          dp.value.value.keyIndex,
-        );
+        let decryptedData;
+        try {
+          decryptedData = await this.e2eeManager.handleEncryptedData(
+            dp.value.value.encryptedValue as NonSharedUint8Array,
+            dp.value.value.iv as NonSharedUint8Array,
+            dp.participantIdentity,
+            dp.value.value.keyIndex,
+          );
+        } catch (err) {
+          this.log.debug('failed to decrypt data packet', {
+            error: err,
+            participantIdentity: dp.participantIdentity,
+          });
+          return;
+        }
         const decryptedPacket = EncryptedPacketPayload.fromBinary(decryptedData.payload);
         const newDp = new DataPacket({
           value: decryptedPacket.value,
@@ -1786,8 +1827,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
       if (this.isClosed) {
         reject(new NegotiationError('cannot negotiate on closed engine'));
       }
-      this.on(EngineEvent.Closing, handleClosed);
-      this.on(EngineEvent.Restarting, handleClosed);
+      this.pendingNegotiationAborts.add(handleClosed);
       this.pcManager.publisher.off(PCEvents.RTPVideoPayloadTypes, this.onRtpMapAvailable);
       this.pcManager.publisher.once(PCEvents.RTPVideoPayloadTypes, this.onRtpMapAvailable);
 
@@ -1811,8 +1851,7 @@ export default class RTCEngine extends (EventEmitter as new () => TypedEventEmit
           reject(new Error(String(e)));
         }
       } finally {
-        this.off(EngineEvent.Closing, handleClosed);
-        this.off(EngineEvent.Restarting, handleClosed);
+        this.pendingNegotiationAborts.delete(handleClosed);
       }
     });
   }
@@ -2074,6 +2113,7 @@ export type EngineEventCallbacks = {
   joined: (joinResponse: JoinResponse) => void;
   tokenRefreshed: (token: string) => void;
   serverRegionsReported: (regions: RegionSettings) => void;
+  requestSubscribedCodecRefresh: () => void;
 };
 
 export interface RegionStrategy {

package/src/room/Room.test.ts

@@ -10,6 +10,7 @@ import {
 } from '@livekit/protocol';
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import MockMediaStreamTrack from '../test/MockMediaStreamTrack';
+import { stubMissingDeflateRawSupport } from '../test/compressionStreamStubs';
 import Room, { ConnectionState } from './Room';
 import { roomConnectOptionDefaults, roomOptionDefaults } from './defaults';
 import { EngineEvent, ParticipantEvent, RoomEvent } from './events';
@@ -46,8 +47,8 @@ describe('Active device switch', () => {
 });
 
 describe('Room signaling options', () => {
-  it('advertises packet trailer capability when E2EE can handle trailers', async () => {
-    const room = new Room();
+  /** Drives `connectSignal` with E2EE enabled against a stub engine, returning the `join` mock. */
+  async function connectSignalWithE2EE(room: Room) {
     const join = vi.fn().mockResolvedValue({
       joinResponse: new JoinResponse({
         room: { name: 'test-room', sid: 'room-sid' },
@@ -91,19 +92,44 @@ describe('Room signaling options', () => {
       new AbortController(),
     );
 
+    return join;
+  }
+
+  function expectCapabilities(
+    join: ReturnType<typeof vi.fn>,
+    clientInfoCapabilities: Array<ClientInfo_Capability>,
+  ) {
     expect(join).toHaveBeenCalledWith(
       'wss://test.livekit.io',
       'test-token',
       expect.objectContaining({
-        clientInfoCapabilities: [
-          ClientInfo_Capability.CAP_PACKET_TRAILER,
-          ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW,
-        ],
+        clientInfoCapabilities,
         e2eeEnabled: true,
       }),
       expect.any(AbortSignal),
       false,
     );
+  }
+
+  it('advertises packet trailer capability when E2EE can handle trailers', async () => {
+    const join = await connectSignalWithE2EE(new Room());
+
+    expectCapabilities(join, [
+      ClientInfo_Capability.CAP_PACKET_TRAILER,
+      ClientInfo_Capability.CAP_COMPRESSION_DEFLATE_RAW,
+    ]);
+  });
+
+  it('does not advertise deflate-raw compression when the runtime cannot decompress it', async () => {
+    const restoreCompressionStreams = stubMissingDeflateRawSupport();
+    try {
+      const join = await connectSignalWithE2EE(new Room());
+
+      // Otherwise peers would compress what they send us and we'd have to drop it.
+      expectCapabilities(join, [ClientInfo_Capability.CAP_PACKET_TRAILER]);
+    } finally {
+      restoreCompressionStreams();
+    }
   });
 });