werift 0.24.4 → 0.25.0

package/lib/webrtc/src/media/rtpSender.d.ts

@@ -26,7 +26,17 @@ import type { Kind } from "../types/domain";
 import type { RTCRtpCodecParameters, RTCRtpSendParameters } from "./parameters";
 import { SenderBandwidthEstimator } from "./sender/senderBWE";
 import { type RTCStats, type RTCStatsReport } from "./stats";
-import type { MediaStream, MediaStreamTrack } from "./track";
+import { type MediaStream, type MediaStreamTrack } from "./track";
+export type PendingRtpOptions = {
+    /** Queue RTP until DTLS is connected and a codec is set. Default true when this object is passed. */
+    enabled?: boolean;
+    /** Max queued packets when enabled. Oldest packets are dropped. Default 256. */
+    maxLength?: number;
+};
+export type RTCRtpSenderOptions = {
+    /** Pending RTP cache. Disabled by default. Pass `true` or `{ maxLength }` to enable. */
+    pendingRtp?: boolean | PendingRtpOptions;
+};
 export declare class RTCRtpSender {
     trackOrKind: Kind | MediaStreamTrack;
     readonly type = "sender";
@@ -73,8 +83,16 @@ export declare class RTCRtpSender {
     private timestamp?;
     private timestampOffset;
     private seqOffset;
+    private rtpContinuityPending;
+    private pendingTimestampStep;
     private rtpCache;
+    private pendingRtp;
+    private drainingPendingRtp;
+    private readonly pendingRtpEnabled;
+    private readonly pendingRtpMaxLength;
     codec?: RTCRtpCodecParameters;
+    private negotiatedCodecs;
+    private sendPrimaryCodec?;
     dtlsTransport: RTCDtlsTransport;
     private dtlsDisposer;
     track: MediaStreamTrack | null;
@@ -82,7 +100,7 @@ export declare class RTCRtpSender {
     stopped: boolean;
     rtcpRunning: boolean;
     private rtcpCancel;
-    constructor(trackOrKind: Kind | MediaStreamTrack);
+    constructor(trackOrKind: Kind | MediaStreamTrack, options?: RTCRtpSenderOptions);
     get transport(): RTCDtlsTransport;
     get streamId(): string | undefined;
     set streamId(value: string | undefined);
@@ -90,14 +108,57 @@ export declare class RTCRtpSender {
     get redDistance(): number;
     set redDistance(n: number);
     prepareSend(params: RTCRtpSendParameters): void;
+    private canSendRtp;
+    private settlePendingRtp;
+    private discardPendingRtp;
+    private enqueuePendingRtp;
+    /**
+     * Send queued RTP once DTLS is connected and a codec is set. Used only when
+     * pending RTP is enabled: `writeRtp` / `sendRtp` may run before ICE/DTLS
+     * completes; dropping those packets would lose the start of a media source.
+     * `drainingPendingRtp` blocks re-entry while `dispatchRtp` is awaited;
+     * packets enqueued during that wait are drained by the recursive call after
+     * the flag is cleared.
+     */
+    private drainPendingRtp;
     registerTrack(track: MediaStreamTrack): void;
     setStreams(streams?: MediaStream[]): void;
     setSendEncodings(encodings?: Array<Record<string, unknown>>): void;
     replaceTrack(track: MediaStreamTrack | null): Promise<void>;
-    stop(): void;
+    /**
+     * Detach the current track without stopping the sender (`removeTrack`).
+     * The same sender can resume sending after `replaceTrack(track)`.
+     */
+    detachTrack(): void;
+    stop({ keepTrack }?: {
+        keepTrack?: boolean;
+    }): void;
     runRtcp(): Promise<void>;
-    replaceRTP({ sequenceNumber, timestamp, }: Pick<RtpHeader, "sequenceNumber" | "timestamp">, discontinuity?: boolean): void;
+    /**
+     * Send an RTP packet. Pending RTP is disabled by default: the packet is
+     * written immediately if DTLS is connected and a codec is set, otherwise
+     * dropped.
+     *
+     * When pending RTP is enabled, the packet is queued until it can be sent.
+     * The returned promise then settles for this packet only:
+     * - resolve: DTLS send completed, or the packet was dropped by `stop()`,
+     *   `replaceTrack(null)`, or pending-queue overflow
+     * - reject: DTLS send threw while writing this packet
+     *
+     * Later `sendRtp()` calls stay pending until their own packet is sent or
+     * dropped, even if a drain is already in progress.
+     */
     sendRtp(rtp: Buffer | RtpPacket): Promise<void>;
+    /**
+     * Schedule RTP continuity rewrite for the next packet that is actually sent.
+     * The header argument is kept for API compatibility and is not used to compute
+     * offsets. `discontinuity` does not change sequence or timestamp mapping.
+     * `timestampStep` (default 1) is the only way to choose the timestamp increment
+     * at the source-switch boundary.
+     */
+    replaceRTP(header: Pick<RtpHeader, "sequenceNumber" | "timestamp">, discontinuity?: boolean, timestampStep?: number): void;
+    private scheduleRtpContinuity;
+    private dispatchRtp;
     handleRtcpPacket(rtcpPacket: RtcpPacket): void;
     getParameters(): {
         encodings: {

package/lib/webrtc/src/media/rtpSender.js

@@ -27,15 +27,39 @@ const crypto_2 = require("crypto");
 const promises_1 = require("timers/promises");
 const common_1 = require("../imports/common");
 const __1 = require("..");
+const errors_1 = require("../errors");
 const rtp_1 = require("../imports/rtp");
 const utils_1 = require("../utils");
+const codecCompatibility_1 = require("./codecCompatibility");
 const senderBWE_1 = require("./sender/senderBWE");
 const stats_1 = require("./stats");
+const track_1 = require("./track");
 const log = (0, rtp_1.debug)("werift:packages/webrtc/src/media/rtpSender.ts");
 const RTP_HISTORY_SIZE = 128;
+const DEFAULT_PENDING_RTP_MAX_LENGTH = 256;
 const RTT_ALPHA = 0.85;
+function resolvePendingRtpOptions(pendingRtp) {
+    if (pendingRtp === true) {
+        return { enabled: true, maxLength: DEFAULT_PENDING_RTP_MAX_LENGTH };
+    }
+    if (pendingRtp == undefined || pendingRtp === false) {
+        return { enabled: false, maxLength: DEFAULT_PENDING_RTP_MAX_LENGTH };
+    }
+    const maxLength = typeof pendingRtp.maxLength === "number" &&
+        Number.isFinite(pendingRtp.maxLength) &&
+        pendingRtp.maxLength >= 1
+        ? Math.floor(pendingRtp.maxLength)
+        : DEFAULT_PENDING_RTP_MAX_LENGTH;
+    return { enabled: pendingRtp.enabled ?? true, maxLength };
+}
+function freezeRtpContinuityOffsets(lastOutputSeq, lastOutputTimestamp, firstInputSeq, firstInputTimestamp, timestampStep) {
+    return {
+        seqOffset: (0, common_1.uint16Add)((0, common_1.uint16Add)(lastOutputSeq, 1), -firstInputSeq),
+        timestampOffset: (0, common_1.uint32Add)((0, common_1.uint32Add)(lastOutputTimestamp, timestampStep), -firstInputTimestamp),
+    };
+}
 class RTCRtpSender {
-    constructor(trackOrKind) {
+    constructor(trackOrKind, options = {}) {
         Object.defineProperty(this, "trackOrKind", {
             enumerable: true,
             configurable: true,
@@ -308,18 +332,66 @@ class RTCRtpSender {
             writable: true,
             value: 0
         });
+        Object.defineProperty(this, "rtpContinuityPending", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "pendingTimestampStep", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: 1
+        });
         Object.defineProperty(this, "rtpCache", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: []
         });
+        Object.defineProperty(this, "pendingRtp", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "drainingPendingRtp", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: false
+        });
+        Object.defineProperty(this, "pendingRtpEnabled", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "pendingRtpMaxLength", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "codec", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "negotiatedCodecs", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: []
+        });
+        Object.defineProperty(this, "sendPrimaryCodec", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         Object.defineProperty(this, "dtlsTransport", {
             enumerable: true,
             configurable: true,
@@ -362,6 +434,9 @@ class RTCRtpSender {
             writable: true,
             value: new AbortController()
         });
+        const pendingRtp = resolvePendingRtpOptions(options.pendingRtp);
+        this.pendingRtpEnabled = pendingRtp.enabled;
+        this.pendingRtpMaxLength = pendingRtp.maxLength;
         this.kind =
             typeof this.trackOrKind === "string"
                 ? this.trackOrKind
@@ -388,6 +463,7 @@ class RTCRtpSender {
             this.dtlsTransport.onStateChange.subscribe((state) => {
                 if (state === "connected") {
                     this.onReady.execute();
+                    void this.drainPendingRtp();
                 }
             }).unSubscribe,
         ];
@@ -403,41 +479,124 @@ class RTCRtpSender {
         this.cname = params.rtcp?.cname;
         this.mid = params.muxId;
         this.headerExtensions = params.headerExtensions;
-        this.rtpStreamId = params.rtpStreamId;
+        this.rtpStreamId = params.rtpStreamId ?? this.rtpStreamId;
         this.repairedRtpStreamId = params.repairedRtpStreamId;
-        this.codec = params.codecs[0];
+        this.negotiatedCodecs = [...params.codecs];
+        this.codec =
+            params.codecs.find((codec) => codec.name.toLowerCase() !== "rtx") ??
+                params.codecs[0];
+        const redPrimaryPayloadType = this.codec?.name.toLowerCase() === "red"
+            ? Number((this.codec.parameters ?? "").split("/")[0])
+            : undefined;
+        this.sendPrimaryCodec =
+            this.codec?.name.toLowerCase() === "red"
+                ? params.codecs.find((codec) => !["red", "rtx"].includes(codec.name.toLowerCase()) &&
+                    codec.payloadType === redPrimaryPayloadType)
+                : this.codec;
         if (this.track) {
             this.track.codec = this.codec;
         }
+        this.rtxPayloadType = undefined;
+        this.redRedundantPayloadType = undefined;
         params.codecs.forEach((codec) => {
             const codecParams = (0, __1.codecParametersFromString)(codec.parameters ?? "");
             if (codec.name.toLowerCase() === "rtx" &&
-                codecParams["apt"] === this.codec?.payloadType) {
+                this.sendPrimaryCodec?.payloadType === codecParams["apt"]) {
                 this.rtxPayloadType = codec.payloadType;
             }
-            if (codec.name.toLowerCase() === "red") {
-                this.redRedundantPayloadType = Number((codec.parameters ?? "").split("/")[0]);
-            }
         });
+        if (this.codec?.name.toLowerCase() === "red" &&
+            this.sendPrimaryCodec != undefined) {
+            this.redRedundantPayloadType = this.sendPrimaryCodec.payloadType;
+        }
+        void this.drainPendingRtp();
+    }
+    canSendRtp() {
+        return (!this.stopped && this.dtlsTransport?.state === "connected" && !!this.codec);
+    }
+    settlePendingRtp(item, error) {
+        if (error == undefined) {
+            item.resolve();
+            return;
+        }
+        item.reject(error);
+    }
+    discardPendingRtp() {
+        const dropped = this.pendingRtp.splice(0);
+        for (const item of dropped) {
+            this.settlePendingRtp(item);
+        }
+    }
+    enqueuePendingRtp(rtp, resolve, reject) {
+        const packet = Buffer.isBuffer(rtp)
+            ? rtp_1.RtpPacket.deSerialize(rtp)
+            : rtp.clone();
+        this.pendingRtp.push({ packet, resolve, reject });
+        while (this.pendingRtp.length > this.pendingRtpMaxLength) {
+            const dropped = this.pendingRtp.shift();
+            if (dropped) {
+                this.settlePendingRtp(dropped);
+            }
+        }
+    }
+    /**
+     * Send queued RTP once DTLS is connected and a codec is set. Used only when
+     * pending RTP is enabled: `writeRtp` / `sendRtp` may run before ICE/DTLS
+     * completes; dropping those packets would lose the start of a media source.
+     * `drainingPendingRtp` blocks re-entry while `dispatchRtp` is awaited;
+     * packets enqueued during that wait are drained by the recursive call after
+     * the flag is cleared.
+     */
+    async drainPendingRtp() {
+        if (this.drainingPendingRtp) {
+            return;
+        }
+        this.drainingPendingRtp = true;
+        try {
+            while (this.pendingRtp.length > 0 && this.canSendRtp()) {
+                const item = this.pendingRtp.shift();
+                if (!this.canSendRtp()) {
+                    this.settlePendingRtp(item);
+                    continue;
+                }
+                try {
+                    await this.dispatchRtp(item.packet);
+                    this.settlePendingRtp(item);
+                }
+                catch (error) {
+                    this.settlePendingRtp(item, error);
+                }
+            }
+        }
+        finally {
+            this.drainingPendingRtp = false;
+        }
+        if (this.pendingRtp.length > 0 && this.canSendRtp()) {
+            await this.drainPendingRtp();
+        }
     }
     registerTrack(track) {
         if (track.stopped)
             throw new Error("track is ended");
+        (0, track_1.captureTrackSourceCodecs)(track);
         if (this.disposeTrack) {
             this.disposeTrack();
         }
         track.id = this.trackId;
-        const { unSubscribe } = track.onReceiveRtp.subscribe(async (rtp) => {
+        const { unSubscribe: unSubscribeRtp } = track.onReceiveRtp.subscribe(async (rtp) => {
             await this.sendRtp(rtp);
         });
+        const { unSubscribe: unSubscribeSourceChanged } = track.onSourceChanged.subscribe((header) => {
+            this.replaceRTP(header);
+        });
         this.track = track;
-        this.disposeTrack = unSubscribe;
+        this.disposeTrack = () => {
+            unSubscribeRtp();
+            unSubscribeSourceChanged();
+        };
         if (this.codec) {
             track.codec = this.codec;
         }
-        track.onSourceChanged.subscribe((header) => {
-            this.replaceRTP(header);
-        });
     }
     setStreams(streams = []) {
         this.streamIds = [...new Set(streams.map((stream) => stream.id))];
@@ -447,32 +606,57 @@ class RTCRtpSender {
             encodings.length > 0
                 ? encodings.map((encoding) => ({ ...encoding }))
                 : [{}];
+        const rid = this.sendEncodings.find((encoding) => typeof encoding.rid === "string")?.rid;
+        if (typeof rid === "string") {
+            this.rtpStreamId = rid;
+        }
     }
     async replaceTrack(track) {
         if (track === null) {
-            if (this.disposeTrack) {
-                this.disposeTrack();
-            }
-            this.track = null;
+            this.detachTrack();
             return;
         }
         if (track.stopped)
             throw new Error("track is ended");
+        (0, track_1.captureTrackSourceCodecs)(track);
+        const sourceCodecs = (0, track_1.getTrackSourceCodecs)(track);
+        if (this.sendPrimaryCodec != undefined &&
+            sourceCodecs != undefined &&
+            !sourceCodecs.some((source) => (0, codecCompatibility_1.isCodecCompatible)(source, this.sendPrimaryCodec))) {
+            throw (0, errors_1.createWebRtcDomException)("InvalidModificationError", `Track codec ${sourceCodecs.map((codec) => codec.mimeType).join(", ")} is incompatible with negotiated codecs ${this.negotiatedCodecs.map((codec) => codec.mimeType).join(", ")}`);
+        }
         if (this.sequenceNumber != undefined) {
-            const header = track.header || (await track.onReceiveRtp.asPromise())[0].header;
-            this.replaceRTP(header);
+            this.scheduleRtpContinuity();
         }
         this.registerTrack(track);
         log("replaceTrack", "ssrc", track.ssrc, "rid", track.rid);
     }
-    stop() {
+    /**
+     * Detach the current track without stopping the sender (`removeTrack`).
+     * The same sender can resume sending after `replaceTrack(track)`.
+     */
+    detachTrack() {
+        this.rtpContinuityPending = false;
+        this.discardPendingRtp();
+        if (this.disposeTrack) {
+            this.disposeTrack();
+            this.disposeTrack = undefined;
+        }
+        this.track = null;
+    }
+    stop({ keepTrack = false } = {}) {
         this.stopped = true;
+        this.rtpContinuityPending = false;
+        this.discardPendingRtp();
         this.rtcpRunning = false;
         this.rtcpCancel.abort();
         if (this.disposeTrack) {
             this.disposeTrack();
+            this.disposeTrack = undefined;
+        }
+        if (!keepTrack) {
+            this.track = null;
         }
-        this.track = null;
     }
     async runRtcp() {
         if (this.rtcpRunning || this.stopped)
@@ -519,30 +703,75 @@ class RTCRtpSender {
         }
         catch (error) { }
     }
-    replaceRTP({ sequenceNumber, timestamp, }, discontinuity = false) {
-        if (this.sequenceNumber != undefined) {
-            this.seqOffset = (0, common_1.uint16Add)(this.sequenceNumber, -sequenceNumber);
-            if (discontinuity) {
-                this.seqOffset = (0, common_1.uint16Add)(this.seqOffset, 2);
-            }
+    /**
+     * Send an RTP packet. Pending RTP is disabled by default: the packet is
+     * written immediately if DTLS is connected and a codec is set, otherwise
+     * dropped.
+     *
+     * When pending RTP is enabled, the packet is queued until it can be sent.
+     * The returned promise then settles for this packet only:
+     * - resolve: DTLS send completed, or the packet was dropped by `stop()`,
+     *   `replaceTrack(null)`, or pending-queue overflow
+     * - reject: DTLS send threw while writing this packet
+     *
+     * Later `sendRtp()` calls stay pending until their own packet is sent or
+     * dropped, even if a drain is already in progress.
+     */
+    async sendRtp(rtp) {
+        if (this.stopped) {
+            return;
         }
-        if (this.timestamp != undefined) {
-            this.timestampOffset = (0, common_1.uint32Add)(this.timestamp, -timestamp);
-            if (discontinuity) {
-                this.timestampOffset = (0, common_1.uint16Add)(this.timestampOffset, 1);
+        if (!this.pendingRtpEnabled) {
+            if (!this.canSendRtp()) {
+                return;
             }
+            await this.dispatchRtp(rtp);
+            return;
         }
+        await new Promise((resolve, reject) => {
+            this.enqueuePendingRtp(rtp, resolve, reject);
+            void this.drainPendingRtp();
+        });
+    }
+    /**
+     * Schedule RTP continuity rewrite for the next packet that is actually sent.
+     * The header argument is kept for API compatibility and is not used to compute
+     * offsets. `discontinuity` does not change sequence or timestamp mapping.
+     * `timestampStep` (default 1) is the only way to choose the timestamp increment
+     * at the source-switch boundary.
+     */
+    replaceRTP(header, discontinuity = false, timestampStep = 1) {
+        this.scheduleRtpContinuity(timestampStep);
+        log("replaceRTP", this.sequenceNumber, header.sequenceNumber, discontinuity, timestampStep);
+    }
+    scheduleRtpContinuity(timestampStep = 1) {
+        this.rtpContinuityPending = true;
+        this.pendingTimestampStep = timestampStep;
         this.rtpCache = [];
-        log("replaceRTP", this.sequenceNumber, sequenceNumber, this.seqOffset);
     }
-    async sendRtp(rtp) {
-        if (this.dtlsTransport.state !== "connected" || !this.codec) {
+    async dispatchRtp(rtp) {
+        if (!this.canSendRtp()) {
+            return;
+        }
+        const codec = this.codec;
+        if (!codec) {
             return;
         }
-        rtp = Buffer.isBuffer(rtp) ? rtp_1.RtpPacket.deSerialize(rtp) : rtp;
+        rtp = Buffer.isBuffer(rtp) ? rtp_1.RtpPacket.deSerialize(rtp) : rtp.clone();
         const { header, payload } = rtp;
+        const inputSequenceNumber = header.sequenceNumber;
+        const inputTimestamp = header.timestamp;
+        if (this.rtpContinuityPending) {
+            if (this.sequenceNumber != undefined && this.timestamp != undefined) {
+                const offsets = freezeRtpContinuityOffsets(this.sequenceNumber, this.timestamp, inputSequenceNumber, inputTimestamp, this.pendingTimestampStep);
+                this.seqOffset = offsets.seqOffset;
+                this.timestampOffset = offsets.timestampOffset;
+            }
+            this.rtpContinuityPending = false;
+            this.pendingTimestampStep = 1;
+        }
         header.ssrc = this.ssrc;
-        header.payloadType = this.codec.payloadType;
+        header.payloadType = codec.payloadType;
         header.timestamp = (0, common_1.uint32Add)(header.timestamp, this.timestampOffset);
         header.sequenceNumber = (0, common_1.uint16Add)(header.sequenceNumber, this.seqOffset);
         this.timestamp = header.timestamp;