@furious.luke/argus-js 0.5.0 → 0.5.2

package/dist/index.d.cts

@@ -14,11 +14,23 @@ type TrackType = "camera" | "screen" | "audio";
  */
 type VideoTrackType = "camera" | "screen";
 /**
- * Declares the logical type of a single published track, keyed by the browser
- * `MediaStreamTrack.id`. The media server reads this to label the track
- * explicitly rather than guessing from the SDP msid.
+ * Declares the logical type and identity of a single published track.
+ *
+ * `mid` is the negotiated media-section id — the ROUTING key the server matches a
+ * track to its type by. It is used rather than the browser `MediaStreamTrack.id`
+ * because it is the only track identifier both peers agree on: Firefox mints an
+ * SDP msid track id unrelated to the `MediaStreamTrack.id`, so routing keyed on
+ * the latter cannot be matched server-side.
+ *
+ * `id` is the browser `MediaStreamTrack.id` — the GENERATION identity. The mid is
+ * stable across renegotiation and is reused when a track of the same type is
+ * republished on the same m-line, so it cannot distinguish a delayed end of a
+ * removed track from a failure of its replacement; the id changes with each new
+ * capture and can. The server echoes it in `media_track_ended`, and the publisher
+ * correlates that against the id it intentionally removed.
  */
 interface TrackLabel {
+    mid: string;
     id: string;
     type: TrackType;
 }
@@ -177,6 +189,16 @@ interface PublisherOptions {
     gatewayHandshakeTimeoutMs?: number;
     /** Deadline after the initial offer for WebRTC to reach connected. Defaults to 30 seconds. */
     peerConnectionTimeoutMs?: number;
+    /**
+     * Preferred video codecs, most-preferred first, as RTP MIME types (e.g.
+     * `"video/VP9"`, `"video/VP8"`, `"video/H264"`). Each published video track's
+     * transceiver offers these codecs ahead of the rest, so the browser sends the
+     * first one the media server also accepts. Codecs the browser supports but that
+     * are not listed keep their default order behind the preferred ones, so
+     * negotiation still falls back cleanly. Defaults to `["video/VP9"]`. Pass an
+     * empty array to leave the browser's native codec order untouched.
+     */
+    preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
     /** Callbacks for lifecycle events. */
@@ -435,6 +457,20 @@ declare class Publisher {
      * the server's outbound speech sender on the dedicated speech transceiver.
      */
     private addMicrophoneTrack;
+    /**
+     * Reorders the codecs a video sender offers so the browser prefers the
+     * configured codecs (VP9 by default). This is what actually controls the wire
+     * format: the browser is the offerer and sends its own top-of-offer codec, and
+     * the media server (Pion) answers by mirroring the offer's codec order — so the
+     * server's own registration order has no say. Floating VP9 to the front of the
+     * offer is therefore the lever. Codecs not in the preference keep their native
+     * order behind it, so anything VP9 can't satisfy still negotiates.
+     *
+     * Best-effort: browsers lacking `getCapabilities`/`setCodecPreferences` (older
+     * Safari) keep their default order, and any failure is swallowed — codec
+     * preference is an optimization, never a requirement for publishing.
+     */
+    private preferVideoCodecs;
     /** Registers one physical video track under its logical type and source stream. */
     private registerTrack;
     /** The live video tracks currently published under the given type. */
@@ -442,6 +478,13 @@ declare class Publisher {
     /** Builds the id → type label array declared to the server on every offer. */
     private buildTrackLabels;
     private labelsReplacingType;
+    /**
+     * The negotiated mid of the transceiver currently sending `track`, or null if
+     * none is found or it has not been negotiated yet. The mid is the identifier
+     * both peers agree on; it is assigned once setLocalDescription runs, which the
+     * publisher always does before sending an offer's labels.
+     */
+    private midForTrack;
     private stagePublish;
     private stageUnpublish;
     /** Stops every published local track and clears the published map. */

package/dist/index.d.ts

@@ -14,11 +14,23 @@ type TrackType = "camera" | "screen" | "audio";
  */
 type VideoTrackType = "camera" | "screen";
 /**
- * Declares the logical type of a single published track, keyed by the browser
- * `MediaStreamTrack.id`. The media server reads this to label the track
- * explicitly rather than guessing from the SDP msid.
+ * Declares the logical type and identity of a single published track.
+ *
+ * `mid` is the negotiated media-section id — the ROUTING key the server matches a
+ * track to its type by. It is used rather than the browser `MediaStreamTrack.id`
+ * because it is the only track identifier both peers agree on: Firefox mints an
+ * SDP msid track id unrelated to the `MediaStreamTrack.id`, so routing keyed on
+ * the latter cannot be matched server-side.
+ *
+ * `id` is the browser `MediaStreamTrack.id` — the GENERATION identity. The mid is
+ * stable across renegotiation and is reused when a track of the same type is
+ * republished on the same m-line, so it cannot distinguish a delayed end of a
+ * removed track from a failure of its replacement; the id changes with each new
+ * capture and can. The server echoes it in `media_track_ended`, and the publisher
+ * correlates that against the id it intentionally removed.
  */
 interface TrackLabel {
+    mid: string;
     id: string;
     type: TrackType;
 }
@@ -177,6 +189,16 @@ interface PublisherOptions {
     gatewayHandshakeTimeoutMs?: number;
     /** Deadline after the initial offer for WebRTC to reach connected. Defaults to 30 seconds. */
     peerConnectionTimeoutMs?: number;
+    /**
+     * Preferred video codecs, most-preferred first, as RTP MIME types (e.g.
+     * `"video/VP9"`, `"video/VP8"`, `"video/H264"`). Each published video track's
+     * transceiver offers these codecs ahead of the rest, so the browser sends the
+     * first one the media server also accepts. Codecs the browser supports but that
+     * are not listed keep their default order behind the preferred ones, so
+     * negotiation still falls back cleanly. Defaults to `["video/VP9"]`. Pass an
+     * empty array to leave the browser's native codec order untouched.
+     */
+    preferredVideoCodecs?: string[];
     /** How long to retry a dropped signaling connection to the selected gateway. Defaults to 20 seconds. */
     signalingReconnectTimeoutMs?: number;
     /** Callbacks for lifecycle events. */
@@ -435,6 +457,20 @@ declare class Publisher {
      * the server's outbound speech sender on the dedicated speech transceiver.
      */
     private addMicrophoneTrack;
+    /**
+     * Reorders the codecs a video sender offers so the browser prefers the
+     * configured codecs (VP9 by default). This is what actually controls the wire
+     * format: the browser is the offerer and sends its own top-of-offer codec, and
+     * the media server (Pion) answers by mirroring the offer's codec order — so the
+     * server's own registration order has no say. Floating VP9 to the front of the
+     * offer is therefore the lever. Codecs not in the preference keep their native
+     * order behind it, so anything VP9 can't satisfy still negotiates.
+     *
+     * Best-effort: browsers lacking `getCapabilities`/`setCodecPreferences` (older
+     * Safari) keep their default order, and any failure is swallowed — codec
+     * preference is an optimization, never a requirement for publishing.
+     */
+    private preferVideoCodecs;
     /** Registers one physical video track under its logical type and source stream. */
     private registerTrack;
     /** The live video tracks currently published under the given type. */
@@ -442,6 +478,13 @@ declare class Publisher {
     /** Builds the id → type label array declared to the server on every offer. */
     private buildTrackLabels;
     private labelsReplacingType;
+    /**
+     * The negotiated mid of the transceiver currently sending `track`, or null if
+     * none is found or it has not been negotiated yet. The mid is the identifier
+     * both peers agree on; it is assigned once setLocalDescription runs, which the
+     * publisher always does before sending an offer's labels.
+     */
+    private midForTrack;
     private stagePublish;
     private stageUnpublish;
     /** Stops every published local track and clears the published map. */

package/dist/index.js

@@ -151,10 +151,11 @@ var Publisher = class {
   // may later reuse any compatible inactive transceiver, not necessarily the one
   // that previously carried the same logical type.
   typeSenders = /* @__PURE__ */ new Map();
-  // intentionalTrackEnds holds physical track ids removed by publish/unpublish
-  // whose server-side `media_track_ended` has not yet arrived. Correlating by id
-  // keeps a delayed end for an old screen track from being mistaken for failure
-  // of a newly-published screen track.
+  // intentionalTrackEnds holds the browser track ids removed by publish/unpublish
+  // whose server-side `media_track_ended` has not yet arrived. Correlating by the
+  // track id (the generation identity the server echoes in track_id) keeps a
+  // delayed end for an old screen track from being mistaken for failure of a
+  // newly-published screen track.
   intentionalTrackEnds = /* @__PURE__ */ new Map();
   // negotiationChain serializes every offer/answer exchange, including recovery.
   // User operations do not resolve until their answer is applied, so no caller
@@ -340,6 +341,7 @@ var Publisher = class {
       };
       if (initialTrack) {
         const sender = initialTrack.type === "audio" ? this.addMicrophoneTrack(pc, initialTrack.track, initialTrack.stream) : pc.addTrack(initialTrack.track, initialTrack.stream);
+        if (initialTrack.type !== "audio") this.preferVideoCodecs(pc, sender);
         this.typeSenders.set(
           initialTrack.type,
           sender
@@ -1095,7 +1097,7 @@ var Publisher = class {
         sdp: local.sdp,
         sdp_type: "offer",
         negotiation_id: id,
-        tracks: change?.labels ?? this.buildTrackLabels(),
+        tracks: change?.labels?.() ?? this.buildTrackLabels(),
         speech_enabled: this.speechEnabled || this.speechPending || void 0
       });
       this.releaseLocalCandidateBatch();
@@ -1504,7 +1506,7 @@ var Publisher = class {
       this.typeSenders.set(type, addedSender);
     }
     return {
-      labels: this.labelsReplacingType(type, track),
+      labels: () => this.labelsReplacingType(type, track),
       commit: () => {
         for (const { track: oldTrack } of previous) {
           this.unwatchTrack(oldTrack);
@@ -1550,6 +1552,39 @@ var Publisher = class {
     this.microphoneTransceiver = transceiver;
     return transceiver.sender;
   }
+  /**
+   * Reorders the codecs a video sender offers so the browser prefers the
+   * configured codecs (VP9 by default). This is what actually controls the wire
+   * format: the browser is the offerer and sends its own top-of-offer codec, and
+   * the media server (Pion) answers by mirroring the offer's codec order — so the
+   * server's own registration order has no say. Floating VP9 to the front of the
+   * offer is therefore the lever. Codecs not in the preference keep their native
+   * order behind it, so anything VP9 can't satisfy still negotiates.
+   *
+   * Best-effort: browsers lacking `getCapabilities`/`setCodecPreferences` (older
+   * Safari) keep their default order, and any failure is swallowed — codec
+   * preference is an optimization, never a requirement for publishing.
+   */
+  preferVideoCodecs(pc, sender) {
+    const preferred = this.opts.preferredVideoCodecs ?? ["video/VP9"];
+    if (preferred.length === 0) return;
+    if (sender.track && sender.track.kind !== "video") return;
+    if (typeof RTCRtpSender === "undefined" || typeof RTCRtpSender.getCapabilities !== "function") return;
+    if (typeof pc.getTransceivers !== "function") return;
+    const caps = RTCRtpSender.getCapabilities("video");
+    if (!caps?.codecs) return;
+    const transceiver = pc.getTransceivers().find((t) => t.sender === sender);
+    if (!transceiver || typeof transceiver.setCodecPreferences !== "function") return;
+    const rank = (mimeType) => {
+      const idx = preferred.findIndex((p) => p.toLowerCase() === mimeType.toLowerCase());
+      return idx === -1 ? preferred.length : idx;
+    };
+    const ordered = caps.codecs.map((codec, index) => ({ codec, index })).sort((a, b) => rank(a.codec.mimeType) - rank(b.codec.mimeType) || a.index - b.index).map((entry) => entry.codec);
+    try {
+      transceiver.setCodecPreferences(ordered);
+    } catch {
+    }
+  }
   /** Registers one physical video track under its logical type and source stream. */
   registerTrack(track, stream, type) {
     this.published.set(track, type);
@@ -1568,18 +1603,34 @@ var Publisher = class {
   buildTrackLabels() {
     const labels = [];
     for (const [track, type] of this.published) {
-      labels.push({ id: track.id, type });
+      const mid = this.midForTrack(track);
+      if (mid !== null) labels.push({ mid, id: track.id, type });
     }
     return labels;
   }
   labelsReplacingType(type, replacement) {
     const labels = [];
     for (const [track, publishedType] of this.published) {
-      if (publishedType !== type) labels.push({ id: track.id, type: publishedType });
+      if (publishedType === type) continue;
+      const mid = this.midForTrack(track);
+      if (mid !== null) labels.push({ mid, id: track.id, type: publishedType });
+    }
+    if (replacement) {
+      const mid = this.midForTrack(replacement);
+      if (mid !== null) labels.push({ mid, id: replacement.id, type });
     }
-    if (replacement) labels.push({ id: replacement.id, type });
     return labels;
   }
+  /**
+   * The negotiated mid of the transceiver currently sending `track`, or null if
+   * none is found or it has not been negotiated yet. The mid is the identifier
+   * both peers agree on; it is assigned once setLocalDescription runs, which the
+   * publisher always does before sending an offer's labels.
+   */
+  midForTrack(track) {
+    const transceiver = this.pc?.getTransceivers().find((candidate) => candidate.sender.track === track);
+    return transceiver?.mid ?? null;
+  }
   async stagePublish(track, stream, type) {
     const pc = this.pc;
     if (!pc) throw new Error("publisher not started");
@@ -1607,10 +1658,11 @@ var Publisher = class {
         throw new SenderRestoreError(`inactive ${type} sender still has a track`);
       }
       addedSender = pc.addTrack(track, stream);
+      this.preferVideoCodecs(pc, addedSender);
       this.typeSenders.set(type, addedSender);
     }
     return {
-      labels: this.labelsReplacingType(type, track),
+      labels: () => this.labelsReplacingType(type, track),
       commit: () => {
         this.cancelMediaRecovery(type);
         this.recoveryState(type).required = false;
@@ -1658,7 +1710,7 @@ var Publisher = class {
     for (const { track } of previous) this.expectIntentionalTrackEnd(track.id, type);
     pc.removeTrack(typeSender);
     return {
-      labels: this.labelsReplacingType(type),
+      labels: () => this.labelsReplacingType(type),
       commit: () => {
         this.cancelMediaRecovery(type);
         this.recoveryState(type).required = false;