@blockcast/mmt-container 0.1.0-main.0399efef1f07

package/src/catalog-fec-params.ts

@@ -0,0 +1,535 @@
+// Catalog → per-track FEC geometry resolution.
+//
+// Moved from hang-mmt-fec's js/watch/src/track-fec-params.ts so every player
+// (moq-lib/hang, moqtail, shaka MSF) resolves catalog FEC semantics through
+// one shared implementation — players keep only wiring, not MMT/catalog
+// interpretation. Structural track shape ({ name, type }) keeps this module
+// player-agnostic.
+
+import { catalogFecInterleaveMs, type FecInterleaveCatalog } from "@blockcast/mmt-fec";
+import { resolveGroupDurationMs } from "./carp-catalog.js";
+import {
+	assembleRepairLayers,
+	assertRepairTrackReachable,
+	describeRepairTrack,
+	rejectRepairFieldsOnMediaTrack,
+	rejectRepairTrackGeometry,
+	repairReachability,
+	dependsTarget,
+	type RepairLayerParams,
+	type RepairLayersResolution,
+	type RepairOverlayParams,
+	type RepairSourceGeometry,
+	type RepairTrackDescriptor,
+	throwRepairContractError,
+	validateRepairTrackFields,
+} from "./repair-layers.js";
+
+export { catalogFecInterleaveMs, type FecInterleaveCatalog };
+export {
+	assembleRepairLayers,
+	assertRepairTrackReachable,
+	repairReachability,
+	type AssembleRepairLayersOptions,
+	type RepairReachability,
+	dependsTarget,
+	describeRepairTrack,
+	rejectRepairFieldsOnMediaTrack,
+	rejectRepairTrackGeometry,
+	REPAIR_TRACK_GEOMETRY_KEYS,
+	REPAIR_TRACK_ONLY_KEYS,
+	validateRepairTrackFields,
+	DEFAULT_REPAIR_PRIORITY,
+	MAX_ENCODING_SYMBOL_ID,
+	MAX_RAPTORQ_SOURCE_SYMBOLS,
+	MAX_REPAIR_SYMBOLS,
+	REPAIR_PRIORITY_MAX,
+	REPAIR_PRIORITY_MIN,
+	RepairContractError,
+	type RepairContractCode,
+	type RepairContractFail,
+	type RepairLayerParams,
+	type RepairLayersResolution,
+	type RepairOverlayParams,
+	type RepairSourceGeometry,
+	type RepairTrackDescriptor,
+} from "./repair-layers.js";
+
+/**
+ * Minimal structural shape of a resolved endpoint track. Callers may carry
+ * extra fields (e.g. hang's ResolvedEndpointTrack adds `pid`) — the resolver
+ * only reads `name` and `type`.
+ */
+export type CatalogTrackRef = {
+	name: string;
+	type: "video" | "audio" | (string & {});
+};
+
+type FecCatalog = FecInterleaveCatalog & {
+	algorithm?: unknown;
+	sourceSymbols?: number;
+	repairSymbols?: number;
+	symbolSize?: number;
+	/** Signaled jitter/reorder allowance in ms (added to the block span). */
+	reorderToleranceMs?: number;
+	/** Layer 0 repair track. Further layers and overlays describe themselves
+	 *  (draft-ramadan-moq-fec §6.3): MSF `tracks[]` entries with
+	 *  `packaging: "fec-repair"`, or hang `repair.renditions` entries, that
+	 *  `depend` on this rendition. */
+	repairTrack?: string;
+};
+
+/** One self-describing repair rendition of the hang catalog's `repair` block
+ *  (draft-ramadan-moq-fec §6.3). Mirrors the MSF fec-repair track fields. */
+export type RepairRenditionCatalog = {
+	depends?: unknown;
+	repairLayer?: unknown;
+	repairSymbols?: unknown;
+	priority?: unknown;
+	scope?: unknown;
+	sourceSymbols?: unknown;
+};
+
+/** The container fields the FEC and group-duration readers consult. */
+type ContainerCatalog = { kind?: unknown; timescale?: unknown };
+
+type RenditionCatalog = KeyframeCadenceCatalog & {
+	container?: ContainerCatalog;
+	fec?: FecCatalog;
+	framerate?: unknown;
+	sampleRate?: unknown;
+	samplerate?: unknown;
+};
+
+type CatalogWithRenditions = {
+	video?: { renditions?: Record<string, RenditionCatalog> };
+	audio?: { renditions?: Record<string, RenditionCatalog> };
+	/** hang-native repair renditions: every repair track beyond layer 0. */
+	repair?: { renditions?: Record<string, RepairRenditionCatalog> };
+};
+
+/** An MSF/CMSF catalog: `tracks[]` entries, optionally with `commonTrackFields`. */
+type CatalogWithTracks = {
+	tracks?: unknown;
+	commonTrackFields?: unknown;
+};
+
+/** Either catalog dialect `resolveRepairLayers` reads. */
+export type RepairLayerCatalog = CatalogWithRenditions | CatalogWithTracks;
+
+export type GroupDurationCatalog = {
+	groupDurationTicks?: number;
+	groupDurationMs?: number;
+	timescale?: number;
+};
+
+/** Rendition fields the group-duration reader consumes. */
+export type GroupDurationRendition = GroupDurationCatalog & {
+	container?: ContainerCatalog;
+};
+
+/**
+ * Largest tick count per Hz of timescale whose millisecond duration
+ * `resolveGroupDurationMs` still accepts: `(ticks / timescale) * 1000` must not
+ * exceed `Number.MAX_SAFE_INTEGER`, so `ticks <= timescale * (MAX_SAFE / 1000)`
+ * (Hz times seconds is ticks).
+ */
+const MAX_SAFE_TICKS_PER_HZ = Number.MAX_SAFE_INTEGER / 1000;
+
+/** A positive safe-integer Hz timescale, or undefined. */
+function timescaleHz(value: unknown): number | undefined {
+	return typeof value === "number" && Number.isSafeInteger(value) && value > 0 ? value : undefined;
+}
+
+/**
+ * A rendition's publisher group duration in ms, or undefined when the catalog
+ * carries none.
+ *
+ * `groupDurationTicks` over a timescale wins when both are present, through
+ * `resolveGroupDurationMs` (draft-ramadan-moq-mmt-00 §4.4.4). The timescale is
+ * the MMTP container's when the rendition declares one, else the rendition's
+ * own `timescale`. Only the ticks are forwarded: a catalog `groupDurationMs`
+ * is often a rounded fraction (21.33 for 1024/48000), which the ticks path
+ * never reads but `resolveGroupDurationMs` would reject as a non-integral ms.
+ * Ticks with no usable timescale, and ticks that `resolveGroupDurationMs`
+ * would reject, fall back to `groupDurationMs` rather than guessing a clock.
+ * That rejection is on the product, not the operand: the count must be a safe
+ * integer and `(ticks / timescale) * 1000` must stay within
+ * `Number.MAX_SAFE_INTEGER`, which a safe-integer count can still exceed when
+ * `timescale < 1000`, so the guard below bounds the count by
+ * `timescale * (Number.MAX_SAFE_INTEGER / 1000)` and the reader never throws.
+ * The production catalog signals both fields on every rendition and no
+ * rendition-level timescale, so the `groupDurationMs` fallback is the path it
+ * takes.
+ */
+export function catalogGroupDurationMs(rendition: GroupDurationRendition | undefined): number | undefined {
+	if (!rendition) return undefined;
+	const ticks = numericField(rendition.groupDurationTicks);
+	const ms = numericField(rendition.groupDurationMs);
+	const timescale =
+		timescaleHz(rendition.container?.kind === "mmtp" ? rendition.container.timescale : undefined) ??
+		timescaleHz(rendition.timescale);
+	if (
+		ticks !== undefined &&
+		timescale !== undefined &&
+		Number.isSafeInteger(ticks) &&
+		ticks <= timescale * MAX_SAFE_TICKS_PER_HZ
+	) {
+		return resolveGroupDurationMs({ groupDurationTicks: ticks }, timescale);
+	}
+	return ms;
+}
+
+/**
+ * The group duration of the catalog rendition an endpoint track was resolved
+ * from, by type and name (the same lookup `resolveCatalogTrackFec` performs
+ * for FEC geometry). Undefined when the rendition is missing or carries no
+ * group duration, so a caller that needs one can fail closed by name.
+ */
+export function resolveCatalogTrackGroupDurationMs(
+	catalog: CatalogWithRenditions | undefined,
+	track: CatalogTrackRef,
+): number | undefined {
+	const renditions = track.type === "audio" ? catalog?.audio?.renditions : catalog?.video?.renditions;
+	return catalogGroupDurationMs(renditions?.[track.name]);
+}
+
+export type KeyframeCadenceCatalog = GroupDurationCatalog & {
+	keyframeDurationTicks?: number;
+	keyframeDurationMs?: number;
+	keyframeIntervalTicks?: number;
+	keyframeIntervalMs?: number;
+	gopDurationTicks?: number;
+	gopDurationMs?: number;
+};
+
+export type TrackFecParams = {
+	fecK: number;
+	/** P_0: repair symbols per block on layer 0 (the track-level repairSymbols). */
+	fecRepairCount: number;
+	/** Total repair symbols per block across the BASE layers: the wire
+	 *  RSB_length on every base layer packet. Equals fecRepairCount on a
+	 *  single-layer track. A keyframe overlay is a separate FEC instance with
+	 *  its own RSB_length and is not included. */
+	fecTotalRepairCount: number;
+	fecSymbolSize: number;
+	fecInterleaveMs: number;
+	/** Catalog fec.reorderToleranceMs — signaled jitter/reorder allowance, ADDED
+	 *  to the block span to form a deadline. Deliberately `number | undefined`
+	 *  and NOT floored to 0: a declared 0 ("this path needs no slack") and an
+	 *  absent value ("the encoder never said") must stay distinguishable, or a
+	 *  consumer that wants to fail loud on absence silently reads a default
+	 *  instead — which is exactly how the magic 3.0 survived. */
+	fecReorderToleranceMs?: number;
+	repairTrackName?: string;
+	/** Every base repair layer in order, layer 0 first, with derived RS_ID
+	 *  offsets. Present whenever repairTrackName is. */
+	repairLayers?: readonly RepairLayerParams[];
+	/** Keyframe overlay instances declared for this track. Present (possibly
+	 *  empty) whenever repairLayers is. */
+	repairOverlays?: readonly RepairOverlayParams[];
+	fps?: number;
+	sampleRate?: number;
+};
+
+const NO_FEC: TrackFecParams = {
+	fecK: 0,
+	fecRepairCount: 0,
+	fecTotalRepairCount: 0,
+	fecSymbolSize: 0,
+	fecInterleaveMs: 0,
+};
+
+/**
+ * Repair symbols per block a receiver has actually joined: the sum of
+ * `repairSymbols` over the BASE layers whose repair track it joined
+ * (draft-ramadan-moq-fec 6.3). This is a symbol count, not a count of layers.
+ *
+ * A keyframe overlay is a separate FEC instance with its own K, its own
+ * RSB_length and its own RS_ID space, so it is never added here however it was
+ * joined. Counting it would overstate the base instance's P and misreport
+ * CMCD `x-bc-fec-p`.
+ *
+ * Falls back to P_0 when the track declares no layers, which is the
+ * single-layer identity rather than a default: with one layer, P_0 is the
+ * total.
+ */
+export function joinedRepairSymbolCount(
+	params: Pick<TrackFecParams, "fecRepairCount" | "repairLayers">,
+	joinedRepairTrackNames: Iterable<string>,
+): number {
+	const layers = params.repairLayers;
+	if (layers === undefined || layers.length === 0) return params.fecRepairCount;
+	const joined = new Set(joinedRepairTrackNames);
+	let total = 0;
+	for (const layer of layers) {
+		if (joined.has(layer.repairTrackName)) total += layer.repairSymbols;
+	}
+	return total;
+}
+
+function recordOf(value: unknown): Record<string, unknown> | undefined {
+	return typeof value === "object" && value !== null && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined;
+}
+
+/** The MSF `tracks[]` view of a catalog, or undefined for the hang dialect. */
+function msfTracks(catalog: RepairLayerCatalog): { tracks: Record<string, unknown>[]; common: Record<string, unknown> } | undefined {
+	const raw = (catalog as CatalogWithTracks).tracks;
+	if (!Array.isArray(raw)) return undefined;
+	const common = recordOf((catalog as CatalogWithTracks).commonTrackFields) ?? {};
+	return { tracks: raw.map((t) => recordOf(t) ?? {}), common };
+}
+
+/**
+ * Resolve every repair track of one source track: base layers with derived
+ * RS_ID offsets and keyframe overlays (draft-ramadan-moq-fec §6.3), from either
+ * catalog dialect.
+ *
+ * - MSF `tracks[]`: the source is the entry named `source`; repair tracks are
+ *   `packaging: "fec-repair"` entries. Layer 0 is the source's
+ *   `fec.repairTrack`; layers 1..n and overlays `depend` on the source.
+ * - hang: the source is a `video`/`audio` rendition; repair tracks beyond
+ *   layer 0 are `repair.renditions` entries that `depend` on it.
+ *
+ * Returns undefined when the source carries no FEC repair track and nothing
+ * depends on it. Throws `RepairContractError` (code + JSON path) on any
+ * violation, including a repair rendition whose `depends` names a rendition
+ * without FEC, so a player fails closed before joining any repair track.
+ */
+export function resolveRepairLayers(
+	catalog: RepairLayerCatalog | undefined,
+	source: string | CatalogTrackRef,
+): RepairLayersResolution | undefined {
+	if (!catalog) return undefined;
+	const sourceName = typeof source === "string" ? source : source.name;
+
+	// hang dialect first. When a catalog carries hang-native rendition blocks
+	// beside a tracks[] switching-set index (the unified ABR ladder catalog),
+	// the rendition blocks are authoritative, exactly as they are for hang's own
+	// catalog decode. A typed ref resolves only within its own role.
+	const hang = catalog as CatalogWithRenditions;
+	const roles: Array<"video" | "audio"> =
+		typeof source === "string"
+			? ["video", "audio"]
+			: source.type === "audio"
+				? ["audio"]
+				: source.type === "video"
+					? ["video"]
+					: ["video", "audio"];
+	const role = roles.find((r) => recordOf(hang[r]?.renditions?.[sourceName]) !== undefined);
+	if (role !== undefined) {
+		const renditionPath = `$.${role}.renditions[${JSON.stringify(sourceName)}]`;
+		const rendition = recordOf(hang[role]!.renditions![sourceName])!;
+		rejectRepairFieldsOnMediaTrack(renditionPath, rendition, throwRepairContractError);
+		const repairRenditions = recordOf(hang.repair?.renditions) ?? {};
+		const descriptors: RepairTrackDescriptor[] = Object.entries(repairRenditions).map(([name, entry]) => {
+			const path = `$.repair.renditions[${JSON.stringify(name)}]`;
+			const fields = recordOf(entry);
+			if (fields === undefined) {
+				throwRepairContractError("track_repair_layer", path, "a repair rendition must be an object");
+			}
+			rejectRepairTrackGeometry(path, fields, throwRepairContractError);
+			return describeRepairTrack(name, path, fields);
+		});
+		const fecOfRendition = (entry: unknown): Record<string, unknown> | undefined => {
+			const fec = recordOf(recordOf(entry)?.["fec"]);
+			return fec !== undefined && fec["algorithm"] !== "none" ? fec : undefined;
+		};
+		const mediaRenditions = [
+			...Object.values(recordOf(hang.video?.renditions) ?? {}),
+			...Object.values(recordOf(hang.audio?.renditions) ?? {}),
+		];
+		const reachability = repairReachability(mediaRenditions.map((entry) => recordOf(entry)?.["fec"]));
+		for (const d of descriptors) {
+			validateRepairTrackFields(d, throwRepairContractError);
+			assertRepairTrackReachable(d, reachability, throwRepairContractError);
+			const target = dependsTarget(d);
+			if (target === undefined) continue;
+			const targetFec =
+				fecOfRendition(hang.video?.renditions?.[target]) ?? fecOfRendition(hang.audio?.renditions?.[target]);
+			if (targetFec === undefined) {
+				throwRepairContractError(
+					"track_repair_depends",
+					`${d.path}.depends`,
+					`${JSON.stringify(target)} is not a video or audio rendition with FEC`,
+				);
+			}
+		}
+		return assembleRepairLayers(
+			geometryOf(sourceName, `${renditionPath}.fec`, recordOf(rendition["fec"])),
+			descriptors,
+			throwRepairContractError,
+		);
+	}
+
+	const msf = msfTracks(catalog);
+	const msfIndex = msf ? msf.tracks.findIndex((t) => t["name"] === sourceName) : -1;
+	if (!msf || msfIndex < 0) return undefined;
+	const track = msf.tracks[msfIndex]!;
+	const fec = recordOf(track["fec"]);
+	const packagingOf = (t: Record<string, unknown>): unknown => t["packaging"] ?? msf.common["packaging"];
+	const fecOfTrack = (t: Record<string, unknown> | undefined): Record<string, unknown> | undefined => {
+		const trackFec = recordOf(t?.["fec"]);
+		return trackFec !== undefined && trackFec["algorithm"] !== "none" ? trackFec : undefined;
+	};
+	// Rule 8 on the resolver path too: a repair track carries no block geometry
+	// and a media track carries no repair-track fields. Without this a repair
+	// track with its own `fec` would count as a FEC source below and name
+	// itself as layer 0, so rule 9 would never see it.
+	const descriptors: RepairTrackDescriptor[] = [];
+	const mediaTracks: Record<string, unknown>[] = [];
+	msf.tracks.forEach((t, i) => {
+		const path = `$.tracks[${i}]`;
+		if (packagingOf(t) === "fec-repair") {
+			rejectRepairTrackGeometry(path, t, throwRepairContractError);
+			if (typeof t["name"] === "string") descriptors.push(describeRepairTrack(t["name"], path, t));
+			return;
+		}
+		rejectRepairFieldsOnMediaTrack(path, t, throwRepairContractError);
+		mediaTracks.push(t);
+	});
+	const reachability = repairReachability(mediaTracks.map((t) => t["fec"]));
+	for (const d of descriptors) {
+		validateRepairTrackFields(d, throwRepairContractError);
+		assertRepairTrackReachable(d, reachability, throwRepairContractError);
+		const target = dependsTarget(d);
+		if (target === undefined) continue;
+		const targetTrack = msf.tracks.find((t) => t["name"] === target);
+		if (targetTrack === undefined || packagingOf(targetTrack) !== "mmtp" || fecOfTrack(targetTrack) === undefined) {
+			throwRepairContractError(
+				"track_repair_depends",
+				`${d.path}.depends`,
+				`${JSON.stringify(target)} is not an mmtp track with FEC`,
+			);
+		}
+	}
+	return assembleRepairLayers(geometryOf(sourceName, `$.tracks[${msfIndex}].fec`, fec), descriptors, throwRepairContractError, {
+		layerZeroMustBeDeclared: true,
+	});
+}
+
+function geometryOf(name: string, path: string, fec: Record<string, unknown> | undefined): RepairSourceGeometry {
+	return {
+		name,
+		path,
+		algorithm: fec?.["algorithm"],
+		sourceSymbols: fec?.["sourceSymbols"],
+		repairSymbols: fec?.["repairSymbols"],
+		repairTrack: fec?.["repairTrack"],
+	};
+}
+
+function numericField(value: unknown): number | undefined {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** Like `numericField` but admits an explicit 0, and still rejects absent,
+ *  negative and non-finite input. Absence returns undefined so callers can
+ *  tell "declared none" from "never declared". */
+function nonNegativeField(value: unknown): number | undefined {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+
+/**
+ * Per-track FEC geometry, or `NO_FEC` when the rendition declares none.
+ *
+ * @throws RepairContractError from `resolveRepairLayers` when the rendition
+ * has FEC and the catalog's repair contract is malformed; see
+ * `resolveCatalogTrackFec`.
+ */
+function fecParams(
+	catalog: CatalogWithRenditions | undefined,
+	track: CatalogTrackRef | undefined,
+	rendition: RenditionCatalog | undefined,
+	fps?: number,
+	sampleRate?: number,
+): TrackFecParams {
+	const mediaRate = sampleRate === undefined ? { fps } : { fps, sampleRate };
+	const fec = rendition?.fec;
+	if (!fec) return { ...NO_FEC, ...mediaRate };
+	const repair = track ? resolveRepairLayers(catalog, track) : undefined;
+	return {
+		fecK: fec.sourceSymbols ?? 0,
+		fecRepairCount: fec.repairSymbols ?? 0,
+		// The wire RSB_length: every base layer's packets carry the base total (§7.1).
+		fecTotalRepairCount: repair?.totalBaseRepairSymbols ?? fec.repairSymbols ?? 0,
+		fecSymbolSize: fec.symbolSize ?? 0,
+		// interleaveDepthMs is the FEC block span in MILLISECONDS (§5.1) — the
+		// only interleave key the catalog carries post-BLO-14526. Receivers
+		// derive D by positive round-half-up of span / GOP duration where needed.
+		fecInterleaveMs: catalogFecInterleaveMs(fec) ?? 0,
+		// Additive, never a multiplier on the span: jitter belongs to the network
+		// path and the span belongs to the encoder, so scaling one by the other
+		// hands one network different slack per track. `numericField` rejects 0,
+		// so it cannot be reused here — a declared 0 is a legitimate value.
+		fecReorderToleranceMs: nonNegativeField(fec.reorderToleranceMs),
+		repairTrackName: fec.repairTrack,
+		repairLayers: repair?.baseLayers,
+		repairOverlays: repair?.overlays,
+		...mediaRate,
+	};
+}
+
+/**
+ * Resolves per-track FEC geometry from the catalog for the active endpoint tracks.
+ *
+ * Invariant: expects at most one video track and one audio track. `forTrack`
+ * dispatches purely on `track.type`, so a second video track (e.g. a simulcast
+ * variant) would silently receive the first video rendition's geometry. Revisit
+ * the `track.type` dispatch before relaxing that one-per-type assumption.
+ *
+ * @throws RepairContractError when a rendition with FEC carries a repair
+ * contract that violates draft-ramadan-moq-fec 6.3 (a gap or duplicate in the
+ * layer chain, a bad `depends` target, an unreachable repair track, a bound
+ * violation). Because the hang dialect validates every `repair.renditions`
+ * entry of the catalog, resolving the video track fails on a malformed audio
+ * repair rendition too. This is deliberate: a player must fail closed before it
+ * joins any repair track. Callers that used to treat this function as total
+ * must catch it and surface the catalog error.
+ */
+export function resolveCatalogTrackFec(
+	catalog: CatalogWithRenditions | undefined,
+	tracks: readonly CatalogTrackRef[],
+): {
+	videoTrackName?: string;
+	audioTrackName?: string;
+	missingVideoRendition?: string;
+	missingAudioRendition?: string;
+	videoForKeyframeRepair?: KeyframeCadenceCatalog;
+	catalogFps?: number;
+	video: TrackFecParams;
+	audio: TrackFecParams;
+	forTrack(track: CatalogTrackRef): TrackFecParams;
+} {
+	const videoTrackName = tracks.find((t) => t.type === "video")?.name;
+	const audioTrackName = tracks.find((t) => t.type === "audio")?.name;
+	const videoRenditions = catalog?.video?.renditions;
+	const audioRenditions = catalog?.audio?.renditions;
+	const video = videoTrackName ? videoRenditions?.[videoTrackName] : undefined;
+	const audio = audioTrackName ? audioRenditions?.[audioTrackName] : undefined;
+	const catalogFps = numericField(video?.framerate);
+	const sampleRate = numericField(audio?.sampleRate ?? audio?.samplerate);
+	const audioFps = sampleRate ? sampleRate / 1024 : undefined;
+	const videoParams = fecParams(catalog, videoTrackName ? { name: videoTrackName, type: "video" } : undefined, video, catalogFps);
+	const audioParams = fecParams(
+		catalog,
+		audioTrackName ? { name: audioTrackName, type: "audio" } : undefined,
+		audio,
+		audioFps,
+		sampleRate,
+	);
+
+	return {
+		videoTrackName,
+		audioTrackName,
+		missingVideoRendition: videoTrackName && videoRenditions && !video ? videoTrackName : undefined,
+		missingAudioRendition: audioTrackName && audioRenditions && !audio ? audioTrackName : undefined,
+		videoForKeyframeRepair: video,
+		catalogFps,
+		video: videoParams,
+		audio: audioParams,
+		forTrack: (track) => (track.type === "audio" ? audioParams : videoParams),
+	};
+}

package/src/catalog-network-source.ts

@@ -0,0 +1,49 @@
+// Catalog → AMT relay discovery (multicast.networkSource).
+//
+// Shared by every player (moq-lib/hang, moqtail, shaka MSF) so networkSource
+// interpretation lives in one place — players keep only wiring, not
+// MMT/catalog semantics.
+//
+// draft-ramadan-moq-multicast §4.1 carries relay discovery as
+// `multicast.networkSource`. Publishers emit the canonical ARRAY form
+// (hang-rs `Option<Vec<NetworkSource>>`; cast's bridge + ladder catalogs), but
+// hang's zod RootSchema also accepts a bare object and older hand-authored
+// catalogs used it — consume both.
+
+/** One `networkSource[]` entry as published (`{type, relay, port?}`). */
+export type CatalogNetworkSource = {
+	type?: string;
+	relay?: string;
+	port?: number;
+};
+
+/** Resolved AMT relay a player can hand to its multicast join/subscribe. */
+export type AmtNetworkSource = {
+	relay: string;
+	port?: number;
+};
+
+function normalizePort(value: unknown): number | undefined {
+	const n = typeof value === "number" ? value : typeof value === "string" ? Number(value) : Number.NaN;
+	return Number.isInteger(n) && n > 0 && n <= 65535 ? n : undefined;
+}
+
+/**
+ * Resolve the AMT relay from a catalog `multicast` block's `networkSource`
+ * (array or bare-object form). Returns the first entry with `type: "amt"`
+ * and a non-blank relay, or `undefined` when the catalog advertises none —
+ * callers fall back to native multicast (or their own explicit relay config).
+ */
+export function catalogAmtNetworkSource(networkSource: unknown): AmtNetworkSource | undefined {
+	const entries = Array.isArray(networkSource) ? networkSource : networkSource ? [networkSource] : [];
+	for (const raw of entries) {
+		if (!raw || typeof raw !== "object") continue;
+		const ns = raw as CatalogNetworkSource;
+		if (ns.type !== "amt") continue;
+		const relay = typeof ns.relay === "string" ? ns.relay.trim() : "";
+		if (!relay) continue;
+		const port = normalizePort(ns.port);
+		return port !== undefined ? { relay, port } : { relay };
+	}
+	return undefined;
+}

package/src/catalog-validator.ts

@@ -0,0 +1,34 @@
+import Ajv2020 from 'ajv/dist/2020.js'
+import addFormats from 'ajv-formats'
+import { hasUniqueMulticastAuthTrackBindings } from './multicast-auth-catalog.js'
+
+export interface CatalogSchemaValidationError {
+  instancePath: string
+  schemaPath: string
+  keyword: string
+  params: Record<string, unknown>
+  message?: string
+}
+
+export interface CatalogSchemaValidator {
+  (catalog: unknown): boolean
+  errors: CatalogSchemaValidationError[] | null
+}
+
+/**
+ * Compile the published catalog schema with every package-defined semantic
+ * keyword installed. Consumers must use this entry point instead of compiling
+ * `catalog.schema.json` with a bare JSON Schema validator.
+ */
+export function createCatalogSchemaValidator(schema: object): CatalogSchemaValidator {
+  const ajv = new Ajv2020({ allErrors: true, strict: true })
+  addFormats(ajv)
+  ajv.addKeyword({
+    keyword: 'uniqueMulticastAuthTrackBindings',
+    type: 'array',
+    schemaType: 'boolean',
+    validate: (enabled: boolean, tracks: unknown[]) =>
+      !enabled || hasUniqueMulticastAuthTrackBindings(tracks),
+  })
+  return ajv.compile(schema) as CatalogSchemaValidator
+}