@blockcast/mmt-container 0.1.0-main.149f78a4adae

package/src/catalog-fec-params.ts

@@ -0,0 +1,167 @@
+// 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";
+
+export { catalogFecInterleaveMs, type FecInterleaveCatalog };
+
+/**
+ * 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 & {
+	sourceSymbols?: number;
+	repairSymbols?: number;
+	symbolSize?: number;
+	/** Signaled jitter/reorder allowance in ms (added to the block span). */
+	reorderToleranceMs?: number;
+	repairTrack?: string;
+};
+
+type RenditionCatalog = KeyframeCadenceCatalog & {
+	fec?: FecCatalog;
+	framerate?: unknown;
+	sampleRate?: unknown;
+	samplerate?: unknown;
+};
+
+type CatalogWithRenditions = {
+	video?: { renditions?: Record<string, RenditionCatalog> };
+	audio?: { renditions?: Record<string, RenditionCatalog> };
+};
+
+export type GroupDurationCatalog = {
+	groupDurationTicks?: number;
+	groupDurationMs?: number;
+	timescale?: number;
+};
+
+export type KeyframeCadenceCatalog = GroupDurationCatalog & {
+	keyframeDurationTicks?: number;
+	keyframeDurationMs?: number;
+	keyframeIntervalTicks?: number;
+	keyframeIntervalMs?: number;
+	gopDurationTicks?: number;
+	gopDurationMs?: number;
+};
+
+export type TrackFecParams = {
+	fecK: number;
+	fecRepairCount: 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;
+	fps?: number;
+	sampleRate?: number;
+};
+
+const NO_FEC: TrackFecParams = {
+	fecK: 0,
+	fecRepairCount: 0,
+	fecSymbolSize: 0,
+	fecInterleaveMs: 0,
+};
+
+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;
+}
+
+function fecParams(
+	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 };
+	return {
+		fecK: fec.sourceSymbols ?? 0,
+		fecRepairCount: 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,
+		...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.
+ */
+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(video, catalogFps);
+	const audioParams = fecParams(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
+}