@tribe-nest/media-protocol 1.0.0

package/build/codecs.js

@@ -0,0 +1,138 @@
+"use strict";
+/**
+ * THE codec list. Every Router in the fleet is created from this array and no
+ * other, and every server-side participant derives what it can receive FROM it.
+ *
+ * ## Why it is pinned rather than left to mediasoup's defaults
+ *
+ * Two Routers that disagree about codecs cannot be piped. `pipeToRouter` and
+ * the hand-rolled equivalent in the node's `pipe.ts` both require the receiving
+ * Router to be able to consume the producer, and "able" is decided by this
+ * list. A node booted from a different build with one extra codec still pipes
+ * fine until the day a client happens to negotiate that codec, and then exactly
+ * one leg of one room goes silent, which reads as a network fault.
+ *
+ * So the list lives in one place and every Router in the fleet is created from
+ * it. A change here is a fleet-wide change and a deploy that mixes versions is
+ * a deploy that mixes codec sets, which is why `DEPLOYMENT.md` says drain
+ * before upgrade rather than rolling.
+ *
+ * ## Why it lives in the PROTOCOL package
+ *
+ * The node is not the only party that has to agree. A room agent, the SIP
+ * gateway and the RTMP ingress are participants, not nodes: each one has to
+ * declare RTP capabilities on `consume`, each one runs in its own app, and none
+ * of them may import `apps/media-server`. Every phase that needed this list
+ * from outside the node had exactly one alternative, which is to write a second
+ * copy - and a second copy is the failure the pinning exists to prevent. The
+ * earlier agent plan proved it: its contract test compared two hand-written
+ * lists to EACH OTHER and never to this one, so both could drift together and
+ * stay green.
+ *
+ * Codec agreement is a wire contract between parties that cannot import each
+ * other, which is the same reason the frames and the claims are here.
+ *
+ * ## Zero mediasoup, deliberately
+ *
+ * The types below are declared structurally rather than imported from
+ * mediasoup, because this package is isomorphic and a browser must be able to
+ * import a frame type without pulling in a C++ addon. `apps/media-server`
+ * re-exports these values through explicitly mediasoup-typed bindings, so if
+ * the two shapes ever diverge the node fails to COMPILE rather than failing to
+ * pipe at three in the morning.
+ *
+ * ## What is in it, and what is deliberately not
+ *
+ * Opus for audio, because it is the only audio codec every browser publishes
+ * and the only one worth transcoding to for SIP and for agents.
+ *
+ * VP8 and H.264 for video. VP8 is universal and simple; H.264 is what Safari
+ * and every hardware encoder produce, and its absence is not a quality loss but
+ * a "video does not work on iPhone" bug. Both are listed with the RTCP feedback
+ * mediasoup needs for keyframes and bandwidth estimation: `nack`, `pli` and
+ * `transport-cc`. Drop `pli` and a keyframe request has no wire representation,
+ * so every active-speaker switch shows macroblocks until the encoder happens to
+ * send an IDR on its own schedule.
+ *
+ * VP9 and AV1 are deliberately absent. Both are real wins and both are a
+ * separate decision with a measurement behind it: SVC changes what
+ * `setPreferredLayers` means, and adding a codec that only some clients
+ * negotiate widens the "one leg is silent" surface above.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MEDIA_CODECS = void 0;
+exports.audioOnlyCapabilities = audioOnlyCapabilities;
+exports.MEDIA_CODECS = [
+    {
+        kind: "audio",
+        mimeType: "audio/opus",
+        clockRate: 48000,
+        channels: 2,
+        parameters: {
+            // In-band FEC costs a little bandwidth and buys intelligibility across
+            // exactly the packet loss a consultation is likely to hit.
+            useinbandfec: 1,
+        },
+    },
+    {
+        kind: "video",
+        mimeType: "video/VP8",
+        clockRate: 90000,
+        parameters: {},
+        rtcpFeedback: [
+            { type: "nack" },
+            { type: "nack", parameter: "pli" },
+            { type: "ccm", parameter: "fir" },
+            { type: "goog-remb" },
+            { type: "transport-cc" },
+        ],
+    },
+    {
+        kind: "video",
+        mimeType: "video/H264",
+        clockRate: 90000,
+        parameters: {
+            // Constrained baseline, level 3.1. `packetization-mode: 1` is what every
+            // browser actually offers; mode 0 exists and nothing sends it.
+            "packetization-mode": 1,
+            "profile-level-id": "42e01f",
+            // Without this Chrome offers H.264 and then never sends a parameter set
+            // out of band, so a late joiner sees nothing until the next IDR.
+            "level-asymmetry-allowed": 1,
+        },
+        rtcpFeedback: [
+            { type: "nack" },
+            { type: "nack", parameter: "pli" },
+            { type: "ccm", parameter: "fir" },
+            { type: "goog-remb" },
+            { type: "transport-cc" },
+        ],
+    },
+];
+/**
+ * The audio half, for a participant that has no video at all.
+ *
+ * DERIVED, never written beside the list above. A hand-written copy for agents
+ * and SIP was compared against another hand-written copy in an earlier plan and
+ * never against this list, which is precisely the drift the pinning exists to
+ * prevent: both copies agree with each other and neither agrees with the fleet.
+ */
+function audioOnlyCapabilities(codecs = exports.MEDIA_CODECS) {
+    return {
+        codecs: codecs
+            .filter((c) => c.kind === "audio")
+            .map((c, index) => ({
+            kind: "audio",
+            mimeType: c.mimeType,
+            clockRate: c.clockRate,
+            ...(c.channels ? { channels: c.channels } : {}),
+            ...(c.parameters ? { parameters: c.parameters } : {}),
+            ...(c.rtcpFeedback ? { rtcpFeedback: c.rtcpFeedback } : {}),
+            // Dynamic range. mediasoup assigns the real value per Router; this is
+            // only what a server-side participant claims it can receive.
+            preferredPayloadType: c.preferredPayloadType ?? 100 + index,
+        })),
+        headerExtensions: [],
+    };
+}
+//# sourceMappingURL=codecs.js.map

package/build/codecs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.js","sourceRoot":"","sources":["../src/codecs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2DG;;;AAwFH,sDAiBC;AAzEY,QAAA,YAAY,GAA2B;IAClD;QACE,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,YAAY;QACtB,SAAS,EAAE,KAAK;QAChB,QAAQ,EAAE,CAAC;QACX,UAAU,EAAE;YACV,uEAAuE;YACvE,2DAA2D;YAC3D,YAAY,EAAE,CAAC;SAChB;KACF;IACD;QACE,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,WAAW;QACrB,SAAS,EAAE,KAAK;QAChB,UAAU,EAAE,EAAE;QACd,YAAY,EAAE;YACZ,EAAE,IAAI,EAAE,MAAM,EAAE;YAChB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE;YAClC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE;YACjC,EAAE,IAAI,EAAE,WAAW,EAAE;YACrB,EAAE,IAAI,EAAE,cAAc,EAAE;SACzB;KACF;IACD;QACE,IAAI,EAAE,OAAO;QACb,QAAQ,EAAE,YAAY;QACtB,SAAS,EAAE,KAAK;QAChB,UAAU,EAAE;YACV,yEAAyE;YACzE,+DAA+D;YAC/D,oBAAoB,EAAE,CAAC;YACvB,kBAAkB,EAAE,QAAQ;YAC5B,wEAAwE;YACxE,iEAAiE;YACjE,yBAAyB,EAAE,CAAC;SAC7B;QACD,YAAY,EAAE;YACZ,EAAE,IAAI,EAAE,MAAM,EAAE;YAChB,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE;YAClC,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE;YACjC,EAAE,IAAI,EAAE,WAAW,EAAE;YACrB,EAAE,IAAI,EAAE,cAAc,EAAE;SACzB;KACF;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,SAAgB,qBAAqB,CAAC,SAAiC,oBAAY;IACjF,OAAO;QACL,MAAM,EAAE,MAAM;aACX,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,OAAO,CAAC;aACjC,GAAG,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,CAAC;YAClB,IAAI,EAAE,OAAgB;YACtB,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,SAAS,EAAE,CAAC,CAAC,SAAS;YACtB,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/C,GAAG,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YACrD,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,sEAAsE;YACtE,6DAA6D;YAC7D,oBAAoB,EAAE,CAAC,CAAC,oBAAoB,IAAI,GAAG,GAAG,KAAK;SAC5D,CAAC,CAAC;QACL,gBAAgB,EAAE,EAAE;KACrB,CAAC;AACJ,CAAC"}

package/build/errorSchema.d.ts

@@ -0,0 +1,8 @@
+import { z } from "zod";
+/**
+ * Separate from `errors.ts` so that file stays a plain union with no zod
+ * import, and so `frames.ts` can validate a code without a circular import
+ * through the error class.
+ */
+export declare const mediaErrorCodeSchema: z.ZodEnum<["unauthorized", "replayed", "protocol_version", "forbidden_transport", "forbidden", "not_subscribable", "subscription_limit", "room_closed", "no_such_room", "no_such_producer", "no_such_transport", "duplicate_identity", "node_draining", "capacity", "bad_request", "internal"]>;
+//# sourceMappingURL=errorSchema.d.ts.map

package/build/errorSchema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorSchema.d.ts","sourceRoot":"","sources":["../src/errorSchema.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,iSAA4B,CAAC"}

package/build/errorSchema.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaErrorCodeSchema = void 0;
+const zod_1 = require("zod");
+const errors_1 = require("./errors");
+/**
+ * Separate from `errors.ts` so that file stays a plain union with no zod
+ * import, and so `frames.ts` can validate a code without a circular import
+ * through the error class.
+ */
+exports.mediaErrorCodeSchema = zod_1.z.enum(errors_1.MEDIA_ERROR_CODES);
+//# sourceMappingURL=errorSchema.js.map

package/build/errorSchema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errorSchema.js","sourceRoot":"","sources":["../src/errorSchema.ts"],"names":[],"mappings":";;;AAAA,6BAAwB;AACxB,qCAA6C;AAE7C;;;;GAIG;AACU,QAAA,oBAAoB,GAAG,OAAC,CAAC,IAAI,CAAC,0BAAiB,CAAC,CAAC"}

package/build/errors.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Every way the media plane refuses, named once.
+ *
+ * A closed union rather than free-text messages, because three surfaces (the
+ * SDK, the harness, the egress client) branch on these, and a string compare
+ * against prose drifts the moment someone improves the wording.
+ */
+export declare const MEDIA_ERROR_CODES: readonly ["unauthorized", "replayed", "protocol_version", "forbidden_transport", "forbidden", "not_subscribable", "subscription_limit", "room_closed", "no_such_room", "no_such_producer", "no_such_transport", "duplicate_identity", "node_draining", "capacity", "bad_request", "internal"];
+export type MediaErrorCode = (typeof MEDIA_ERROR_CODES)[number];
+export declare class MediaError extends Error {
+    readonly code: MediaErrorCode;
+    /** Safe to show a user? Most of these are not. */
+    readonly retryable: boolean;
+    constructor(code: MediaErrorCode, message?: string, 
+    /** Safe to show a user? Most of these are not. */
+    retryable?: boolean);
+}
+//# sourceMappingURL=errors.d.ts.map

package/build/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,+RAsBpB,CAAC;AAEX,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEhE,qBAAa,UAAW,SAAQ,KAAK;aAEjB,IAAI,EAAE,cAAc;IAEpC,kDAAkD;aAClC,SAAS;gBAHT,IAAI,EAAE,cAAc,EACpC,OAAO,CAAC,EAAE,MAAM;IAChB,kDAAkD;IAClC,SAAS,UAAQ;CAKpC"}

package/build/errors.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaError = exports.MEDIA_ERROR_CODES = void 0;
+/**
+ * Every way the media plane refuses, named once.
+ *
+ * A closed union rather than free-text messages, because three surfaces (the
+ * SDK, the harness, the egress client) branch on these, and a string compare
+ * against prose drifts the moment someone improves the wording.
+ */
+exports.MEDIA_ERROR_CODES = [
+    // token / session
+    "unauthorized", // token missing, malformed, or rejected
+    "replayed", // jti already consumed (a session concern, not a verifier one)
+    "protocol_version", // client and node disagree on MEDIA_PROTOCOL_VERSION
+    "forbidden_transport", // token's `transport` claim does not permit this transport kind
+    // authorization
+    "forbidden", // grants do not permit this operation
+    "not_subscribable", // maySubscribe said no - an information barrier, not an error
+    "subscription_limit", // maxSubscriptions or the active-set ceiling
+    // state
+    "room_closed",
+    "no_such_room",
+    "no_such_producer",
+    "no_such_transport",
+    "duplicate_identity", // that identity is already connected to this room
+    // capacity / lifecycle
+    "node_draining", // reconnect via the URL; the LB or a redirect will place you
+    "capacity",
+    // catch-alls
+    "bad_request",
+    "internal",
+];
+class MediaError extends Error {
+    code;
+    retryable;
+    constructor(code, message, 
+    /** Safe to show a user? Most of these are not. */
+    retryable = false) {
+        super(message ?? code);
+        this.code = code;
+        this.retryable = retryable;
+        this.name = "MediaError";
+    }
+}
+exports.MediaError = MediaError;
+//# sourceMappingURL=errors.js.map

package/build/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":";;;AAAA;;;;;;GAMG;AACU,QAAA,iBAAiB,GAAG;IAC/B,kBAAkB;IAClB,cAAc,EAAW,wCAAwC;IACjE,UAAU,EAAe,+DAA+D;IACxF,kBAAkB,EAAO,qDAAqD;IAC9E,qBAAqB,EAAI,gEAAgE;IACzF,gBAAgB;IAChB,WAAW,EAAc,sCAAsC;IAC/D,kBAAkB,EAAO,8DAA8D;IACvF,oBAAoB,EAAK,6CAA6C;IACtE,QAAQ;IACR,aAAa;IACb,cAAc;IACd,kBAAkB;IAClB,mBAAmB;IACnB,oBAAoB,EAAK,kDAAkD;IAC3E,uBAAuB;IACvB,eAAe,EAAU,6DAA6D;IACtF,UAAU;IACV,aAAa;IACb,aAAa;IACb,UAAU;CACF,CAAC;AAIX,MAAa,UAAW,SAAQ,KAAK;IAEjB;IAGA;IAJlB,YACkB,IAAoB,EACpC,OAAgB;IAChB,kDAAkD;IAClC,YAAY,KAAK;QAEjC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAC;QALP,SAAI,GAAJ,IAAI,CAAgB;QAGpB,cAAS,GAAT,SAAS,CAAQ;QAGjC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;IAC3B,CAAC;CACF;AAVD,gCAUC"}