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

package/src/signaling.ts

@@ -0,0 +1,78 @@
+/**
+ * MMTP Signaling Parser for Multicast
+ *
+ * Provides packet type detection and AL-FEC signaling message parsing.
+ * Used by the multicast pipeline to classify and route MMTP packets.
+ *
+ * Packet types (ISO/IEC 23008-1:2023 Section 9.2.2):
+ * - 0x00: MPU (Media Processing Unit) - video/audio data
+ * - 0x02: Signaling - control messages including AL-FEC config
+ * - 0x03: Repair - FEC repair symbols
+ */
+import {
+	ALFEC_MESSAGE_ID,
+	FEC_CODE_RAPTORQ,
+	FEC_CODE_XOR,
+	PACKET_TYPE_MPU,
+	PACKET_TYPE_REPAIR,
+	PACKET_TYPE_SIGNALING,
+	parseAlFecMessage,
+} from "@blockcast/mmt-base";
+
+export {
+	ALFEC_MESSAGE_ID,
+	FEC_CODE_RAPTORQ,
+	FEC_CODE_XOR,
+	PACKET_TYPE_MPU,
+	PACKET_TYPE_REPAIR,
+	PACKET_TYPE_SIGNALING,
+	parseAlFecMessage,
+};
+
+export type PacketClass = "source" | "signaling" | "repair" | "unknown";
+
+/** Get the MMTP packet type from raw multicast packet bytes.
+ *
+ * ISO/IEC 23008-1:2023 Figure 8 (V=0): byte 1 is
+ * reserved(2)|packet_type(6), so signaling is 0x02 and repair is 0x03.
+ * Pre-migration FFmpeg high-bits bytes (0x08/0x0c) are NOT accepted:
+ * writers and readers move together in the pinned smoke train.
+ */
+export function getPacketType(mmtpPacket: Uint8Array): number {
+	if (mmtpPacket.length < 2) return -1;
+	return mmtpPacket[1] & 0x3f;
+}
+
+/** Check if packet is a signaling packet (type 0x02). */
+export function isSignalingPacket(mmtpPacket: Uint8Array): boolean {
+	return getPacketType(mmtpPacket) === PACKET_TYPE_SIGNALING;
+}
+
+/** Determine if packet is a source (video/audio) packet. */
+export function isSourcePacket(mmtpPacket: Uint8Array): boolean {
+	if (mmtpPacket.length < 2) return false;
+	const packetType = mmtpPacket[1] & 0x3f;
+	const fecType = (mmtpPacket[0] >> 3) & 0x03;
+	return packetType === 0x00 && fecType <= 1;
+}
+
+/** Classify MMTP packet for multicast pipeline routing. */
+export function classifyPacket(mmtpPacket: Uint8Array): PacketClass {
+	if (mmtpPacket.length < 2) return "unknown";
+	const packetType = mmtpPacket[1] & 0x3f;
+	const fecType = (mmtpPacket[0] >> 3) & 0x03;
+	if ((mmtpPacket[0] >> 6) !== 0) return "unknown";
+	switch (packetType) {
+		case 0x00:
+			if (mmtpPacket.length < 20) return "unknown";
+			if (fecType >= 2) return "repair";
+			return "source";
+		case 0x02:
+			return "signaling";
+		case 0x03:
+			if (mmtpPacket.length < 20) return "unknown";
+			return "repair";
+		default:
+			return "unknown";
+	}
+}

package/src/source-auth.ts

@@ -0,0 +1 @@
+export * from '@blockcast/mmt-manifest-verify'

package/src/switching-set-alignment.ts

@@ -0,0 +1,109 @@
+/**
+ * SwitchingSetMonitor — subscriber-side per-group alignment check between
+ * /base and /delta tracks in a CMAF switching set.
+ *
+ * Phase 14 D-15: log-only on drift (does NOT reject stream, does NOT throw).
+ * Phase 14 D-16: tolerance = Math.floor(1_000_000 / framerate / 2) microseconds.
+ *                Hardcoded tolerance is FORBIDDEN — derives from framerate only.
+ * Phase 14 D-17: altGroup groups base+delta+repair into one switching set.
+ * Phase 14 T-14-03 mitigation: at most ONE misalignment emit per groupId pair.
+ */
+
+export interface SwitchingSetMonitorOptions {
+  /** REQUIRED — throws if missing or ≤ 0 (error on bad init, CLAUDE.md). */
+  framerate: number
+  /** Fired when base and delta timestamps for the same groupId differ by more than toleranceUs. */
+  onMisaligned?: (evt: { groupId: number; driftUs: number }) => void
+  /** Fired when base and delta are at different group numbers simultaneously (via reportGroupMismatch). */
+  onGroupNumberMismatch?: (evt: { baseGroupId: number; deltaGroupId: number }) => void
+}
+
+/** Internal state for a pending base+delta group pair. */
+type PendingGroup = { baseTs?: number; deltaTs?: number; emitted: boolean }
+
+export class SwitchingSetMonitor {
+  /**
+   * Half-frame-duration tolerance in microseconds.
+   * Derivation: Math.floor(1_000_000 / framerate / 2)
+   * D-16: no hardcoded tolerance — framerate is the only input.
+   */
+  readonly toleranceUs: number
+
+  #pending: Map<number, PendingGroup> = new Map()
+  #onMisaligned: ((evt: { groupId: number; driftUs: number }) => void) | undefined
+  #onGroupNumberMismatch: ((evt: { baseGroupId: number; deltaGroupId: number }) => void) | undefined
+  #disposed = false
+
+  constructor(opts: SwitchingSetMonitorOptions) {
+    if (
+      !opts ||
+      typeof opts.framerate !== 'number' ||
+      !Number.isFinite(opts.framerate) ||
+      opts.framerate <= 0
+    ) {
+      throw new Error('[SwitchingSetMonitor] framerate required and must be > 0')
+    }
+    // D-16: derive from framerate — no hardcoded literal tolerance.
+    this.toleranceUs = Math.floor(1_000_000 / opts.framerate / 2)
+    this.#onMisaligned = opts.onMisaligned
+    this.#onGroupNumberMismatch = opts.onGroupNumberMismatch
+  }
+
+  /**
+   * Notify the monitor that a group's first frame has arrived on a given role's track.
+   *
+   * When both base and delta have been seen for the same groupId, the timestamps are
+   * compared. If the absolute drift exceeds toleranceUs, onMisaligned fires.
+   *
+   * T-14-03: at most one emit per groupId pair (first-call-wins coalescing).
+   * D-15: no throw on misalignment — log-only semantics.
+   */
+  notifyGroup(role: 'base' | 'delta', groupId: number, firstFrameTimestampUs: number): void {
+    if (this.#disposed) return
+
+    let entry = this.#pending.get(groupId)
+    if (!entry) {
+      entry = { emitted: false }
+      this.#pending.set(groupId, entry)
+    }
+
+    if (role === 'base') {
+      entry.baseTs = firstFrameTimestampUs
+    } else {
+      entry.deltaTs = firstFrameTimestampUs
+    }
+
+    // Only evaluate when both sides have been received AND not yet emitted.
+    if (entry.baseTs !== undefined && entry.deltaTs !== undefined && !entry.emitted) {
+      const driftUs = Math.abs(entry.baseTs - entry.deltaTs)
+      if (driftUs > this.toleranceUs) {
+        entry.emitted = true  // T-14-03: coalesce — one emit per groupId pair
+        this.#onMisaligned?.({ groupId, driftUs })
+      }
+    }
+  }
+
+  /**
+   * Report a group-number mismatch observed at the caller level.
+   *
+   * Called when the caller observes that base's current group ID differs from
+   * delta's at the same wall-clock moment. This is a distinct concern from
+   * timestamp drift within a matched group — handled by a separate callback
+   * path (onGroupNumberMismatch) to keep each method single-purpose.
+   *
+   * Plan 03 wires this from player subscribe callbacks.
+   */
+  reportGroupMismatch(baseGroupId: number, deltaGroupId: number): void {
+    if (this.#disposed) return
+    this.#onGroupNumberMismatch?.({ baseGroupId, deltaGroupId })
+  }
+
+  /**
+   * Dispose the monitor and clear all buffered pending groups.
+   * After dispose(), subsequent notifyGroup/reportGroupMismatch calls are no-ops.
+   */
+  dispose(): void {
+    this.#disposed = true
+    this.#pending.clear()
+  }
+}

package/src/timestamp-codec.ts

@@ -0,0 +1,265 @@
+/**
+ * Container Timestamp Codec
+ *
+ * Encodes and decodes timestamps across container formats:
+ * - "legacy": QUIC VarInt encoded (variable length 1-8 bytes)
+ * - "raw": Fixed 8-byte BigUint64
+ * - "mmtp" / "mmtp-fec": 12-byte MMTP header with embedded timestamp
+ * - "loc": LOC extension header encoding
+ * - "fmp4": Not yet implemented
+ */
+import { extractNALUnit, extractTimestamp } from "@blockcast/mmt-base";
+
+export type ContainerFormat = "legacy" | "raw" | "mmtp" | "mmtp-fec" | "loc" | "fmp4";
+
+const DEFAULT_CONTAINER: ContainerFormat = "legacy";
+
+/** Encodes a timestamp in microseconds according to the specified container format. */
+export function encodeTimestamp(timestamp: number, container: ContainerFormat = DEFAULT_CONTAINER): Uint8Array {
+	switch (container) {
+		case "legacy":
+			return encodeVarInt(timestamp);
+		case "raw":
+			return encodeU64(timestamp);
+		case "mmtp":
+		case "mmtp-fec":
+			return encodeU64(timestamp);
+		case "loc":
+			return encodeLocTimestamp(timestamp);
+		case "fmp4":
+			throw new Error("fmp4 container not yet implemented");
+	}
+}
+
+/**
+ * Decodes a timestamp from a buffer according to the specified container format.
+ * @returns [timestamp in microseconds, remaining buffer after timestamp]
+ */
+export function decodeTimestamp(buffer: Uint8Array, container: ContainerFormat = DEFAULT_CONTAINER): [number, Uint8Array] {
+	switch (container) {
+		case "legacy": {
+			const [value, remaining] = decodeVarInt(buffer);
+			return [value, remaining];
+		}
+		case "raw": {
+			const [value, remaining] = decodeU64(buffer);
+			return [value, remaining];
+		}
+		case "mmtp":
+		case "mmtp-fec": {
+			const timestamp = extractTimestamp(buffer);
+			const payload = extractNALUnit(buffer);
+			return [Number(timestamp), payload];
+		}
+		case "loc": {
+			const [ts, payload] = decodeLocTimestamp(buffer);
+			return [ts, payload];
+		}
+		case "fmp4":
+			throw new Error("fmp4 container not yet implemented");
+	}
+}
+
+/** Gets the size in bytes of an encoded timestamp for the given container format. */
+export function getTimestampSize(container: ContainerFormat = DEFAULT_CONTAINER): number {
+	switch (container) {
+		case "legacy":
+			return 8;
+		case "raw":
+			return 8;
+		case "mmtp":
+		case "mmtp-fec":
+			return 12;
+		case "loc":
+			// [ExtID=2][ts][ExtID=4][kf]: two 1-byte IDs + a varint timestamp
+			// (<=8 bytes) + a 1-byte keyframe flag.
+			return 11;
+		case "fmp4":
+			throw new Error("fmp4 container not yet implemented");
+	}
+}
+
+// LEGACY VARINT IMPLEMENTATION
+const MAX_U6 = 2 ** 6 - 1;
+const MAX_U14 = 2 ** 14 - 1;
+const MAX_U30 = 2 ** 30 - 1;
+const MAX_U53 = Number.MAX_SAFE_INTEGER;
+
+function decodeVarInt(buf: Uint8Array): [number, Uint8Array] {
+	const size = 1 << ((buf[0] & 0xc0) >> 6);
+	const view = new DataView(buf.buffer, buf.byteOffset, size);
+	const remain = new Uint8Array(buf.buffer, buf.byteOffset + size, buf.byteLength - size);
+	let v: number;
+	if (size === 1) {
+		v = buf[0] & 0x3f;
+	} else if (size === 2) {
+		v = view.getUint16(0) & 0x3fff;
+	} else if (size === 4) {
+		v = view.getUint32(0) & 0x3fffffff;
+	} else if (size === 8) {
+		v = Number(view.getBigUint64(0) & 0x3fffffffffffffffn);
+	} else {
+		throw new Error("impossible");
+	}
+	return [v, remain];
+}
+
+function encodeVarInt(v: number): Uint8Array {
+	if (v > MAX_U53) throw new RangeError("value too large for varint");
+	let size: 1 | 2 | 4 | 8;
+	if (v <= MAX_U6) {
+		size = 1;
+	} else if (v <= MAX_U14) {
+		size = 2;
+	} else if (v <= MAX_U30) {
+		size = 4;
+	} else {
+		size = 8;
+	}
+	const arr = new Uint8Array(size);
+	const view = new DataView(arr.buffer, arr.byteOffset, size);
+	const prefixMap: Record<1 | 2 | 4 | 8, number> = { 1: 0b00, 2: 0b01, 4: 0b10, 8: 0b11 };
+	const prefix = prefixMap[size];
+	if (size === 1) {
+		view.setUint8(0, (prefix << 6) | v);
+	} else if (size === 2) {
+		view.setUint16(0, (prefix << 14) | v);
+	} else if (size === 4) {
+		view.setUint32(0, (prefix << 30) | v);
+	} else if (size === 8) {
+		view.setBigUint64(0, (BigInt(prefix) << 62n) | BigInt(v));
+	}
+	return arr;
+}
+
+// U64 IMPLEMENTATION
+function decodeU64(buf: Uint8Array): [number, Uint8Array] {
+	const view = new DataView(buf.buffer, buf.byteOffset, 8);
+	const remain = new Uint8Array(buf.buffer, buf.byteOffset + 8, buf.byteLength - 8);
+	const v = Number(view.getBigUint64(0));
+	return [v, remain];
+}
+
+function encodeU64(v: number): Uint8Array {
+	const arr = new Uint8Array(8);
+	const view = new DataView(arr.buffer, arr.byteOffset, 8);
+	view.setBigUint64(0, BigInt(v));
+	return arr;
+}
+
+// LOC TIMESTAMP IMPLEMENTATION
+//
+// The LOC wire format is defined by hang's `ContainerMode::Loc` encoder
+// (hang-mmt-fec/rs/hang/src/container/producer.rs, the `ContainerMode::Loc`
+// arm), which writes a FIXED two-pair extension header and then the payload:
+//
+//     [ExtID=2][CaptureTimestamp_us][ExtID=4][keyframe][payload]
+//
+// all four fields QUIC varints. It is exactly two pairs — no count, no length,
+// no terminator — so the reader is deterministic: consume four varints, and the
+// payload starts at the fifth. Do NOT reintroduce a payload sniff (the removed
+// `firstByte === 0x00` heuristic guessed at the boundary, which held for AVCC
+// video and destroyed AAC audio, whose first byte is ID_SCE = 0x00-0x1f).
+//
+// A LOC track advertising `packaging: "loc"` MUST be emitted through
+// `ContainerMode::Loc`. A producer that stamps the catalog but leaves the track
+// in Legacy `[VarInt ts][payload]` mode is broken on the producer side — fix it
+// there rather than making this reader guess which framing it was handed.
+
+/** Number of varints in the fixed LOC extension header (2 ID/value pairs). */
+const LOC_HEADER_VARINTS = 4;
+
+/** LOC extension IDs (draft-ietf-moq-loc). */
+const LOC_EXT_CAPTURE_TIMESTAMP = 2;
+const LOC_EXT_VIDEO_FRAME_MARKING = 4;
+
+/** Decode a LOC frame header.
+ *  Returns [timestamp in microseconds, remaining payload]. */
+export function decodeLocTimestamp(buffer: Uint8Array): [number, Uint8Array] {
+	const { timestamp, payload } = decodeLocHeader(buffer);
+	return [timestamp, payload];
+}
+
+// ── LOC Header Parsing ──────────────────────────────────────────────
+
+/** Parsed LOC extension header (CaptureTimestamp + VideoFrameMarking). */
+export interface LocHeader {
+	/** Capture timestamp in microseconds (extension ID 2). */
+	timestamp: number;
+	/** Keyframe flag (extension ID 4, bit 0). */
+	keyframe?: boolean;
+	/** Payload after the extension header (raw codec bitstream). */
+	payload: Uint8Array;
+}
+
+/**
+ * Decode the fixed LOC extension header:
+ * `[ExtID=2][timestamp_us][ExtID=4][keyframe][payload]`.
+ *
+ * Throws if the header is not the two pairs the producer emits — a truncated or
+ * mis-framed buffer is a contract break, and returning a plausible-looking
+ * payload from it just relocates the failure into the decoder.
+ */
+export function decodeLocHeader(buffer: Uint8Array): LocHeader {
+	/** Read one varint, converting an over-run into a contract-break message. */
+	const readVarInt = (buf: Uint8Array, field: string): [number, Uint8Array] => {
+		if (buf.length === 0) {
+			throw new Error(
+				`LOC header truncated at ${field}: buffer is ${buffer.byteLength} bytes, ` +
+					`expected ${LOC_HEADER_VARINTS} varints`,
+			);
+		}
+		try {
+			return decodeVarInt(buf);
+		} catch {
+			// decodeVarInt builds a DataView sized by the 2-bit prefix; a short
+			// tail throws "Invalid DataView length" and hides what actually broke.
+			throw new Error(
+				`LOC header truncated at ${field}: ${buf.length} byte(s) remain, ` +
+					`too few for the declared varint width`,
+			);
+		}
+	};
+
+	const [tsId, afterTsId] = readVarInt(buffer, "CaptureTimestamp ID");
+	// Validate each ID as soon as it is read, so a Legacy-framed buffer reports
+	// the contract break rather than an over-run further along the walk.
+	if (tsId !== LOC_EXT_CAPTURE_TIMESTAMP) {
+		throw new Error(
+			`LOC header extension IDs: expected ${LOC_EXT_CAPTURE_TIMESTAMP} ` +
+				`(CaptureTimestamp) first, got ${tsId}. The producer is advertising ` +
+				`packaging="loc" but not emitting LOC framing — see ` +
+				`hang Avc1::set_explicit_container / Aac::set_container.`,
+		);
+	}
+
+	const [timestamp, afterTs] = readVarInt(afterTsId, "CaptureTimestamp value");
+	const [kfId, afterKfId] = readVarInt(afterTs, "VideoFrameMarking ID");
+	if (kfId !== LOC_EXT_VIDEO_FRAME_MARKING) {
+		throw new Error(
+			`LOC header extension IDs: expected ${LOC_EXT_VIDEO_FRAME_MARKING} ` +
+				`(VideoFrameMarking) second, got ${kfId}.`,
+		);
+	}
+	const [kfValue, payload] = readVarInt(afterKfId, "VideoFrameMarking value");
+
+	return { timestamp, keyframe: (kfValue & 1) === 1, payload };
+}
+
+/** Encode a LOC frame header: `[ExtID=2][timestamp_us][ExtID=4][keyframe]`. */
+export function encodeLocTimestamp(timestamp: number, keyframe = false): Uint8Array {
+	const parts = [
+		encodeVarInt(LOC_EXT_CAPTURE_TIMESTAMP),
+		encodeVarInt(timestamp),
+		encodeVarInt(LOC_EXT_VIDEO_FRAME_MARKING),
+		encodeVarInt(keyframe ? 1 : 0),
+	];
+	const total = parts.reduce((n, p) => n + p.length, 0);
+	const out = new Uint8Array(total);
+	let off = 0;
+	for (const p of parts) {
+		out.set(p, off);
+		off += p.length;
+	}
+	return out;
+}

package/src/track-pipeline-setup.ts

@@ -0,0 +1,189 @@
+/**
+ * Track Pipeline Setup — shared wiring helper for both players.
+ *
+ * Provides a one-call setup that connects TrackPipeline to MediaRouter +
+ * MulticastManager, including the TrackSourceFactory that adapts multicast
+ * frames into the TrackSource interface expected by MediaRouter.setTrackSource().
+ *
+ * Usage in both moq-lib (element.ts) and moqtail (player.ts):
+ *
+ *   import { setupTrackPipeline, type TrackDescriptor } from '@blockcast/mmt-container';
+ *
+ *   const tracks: TrackDescriptor[] = catalog.getTracks().map(t => ({
+ *     name: t.name,
+ *     type: t.role as 'video' | 'audio',
+ *     packetId: t.packetId,
+ *   }));
+ *
+ *   const { pipeline, dispose } = setupTrackPipeline({
+ *     router,
+ *     multicastManager: mc,
+ *     tracks,
+ *     preferences: transportPrefs,
+ *     capabilities: caps,
+ *     onTransportChange: (track, from, to) => { ... },
+ *   });
+ */
+
+import type { MediaRouter, TrackSource, MigrationPolicy, FrameKind } from './media-router.js'
+import type { MulticastManager } from './multicast-manager.js'
+import {
+  TrackPipeline,
+  type TrackTransport,
+  type TrackTransportPreference,
+  type TransportCapabilityReport,
+} from './track-pipeline.js'
+
+export { TrackPipeline }
+
+/**
+ * Catalog-derived track descriptor. Carries the actual track type
+ * so the pipeline never guesses from track names.
+ */
+export interface TrackDescriptor {
+  /** Track name as it appears in the catalog / MoQ namespace. */
+  name: string
+  /** Actual media type from catalog role. */
+  type: FrameKind
+  /** MMTP packet ID (used for MulticastManager per-track callbacks). */
+  packetId?: number
+}
+
+export interface SetupTrackPipelineOptions {
+  /** MediaRouter instance (already wired to decoder backends). */
+  router: MediaRouter
+  /** MulticastManager instance (already joined or about to join). */
+  multicastManager: MulticastManager
+  /** Catalog-derived track descriptors. */
+  tracks: TrackDescriptor[]
+  /** Per-track transport preferences. */
+  preferences?: TrackTransportPreference[]
+  /** Initial capability snapshot (optional; call pipeline.updateCapabilities later). */
+  capabilities?: TransportCapabilityReport
+  /** Called after each per-track transport switch. */
+  onTransportChange?: (
+    trackName: string,
+    from: TrackTransport | null,
+    to: TrackTransport,
+    policy: MigrationPolicy,
+  ) => void
+}
+
+export interface SetupTrackPipelineResult {
+  pipeline: TrackPipeline
+  /** Call to tear down the pipeline and all per-track sources. */
+  dispose: () => void
+}
+
+/**
+ * Create and wire a TrackPipeline into existing MediaRouter + MulticastManager.
+ *
+ * The factory creates TrackSource adapters that:
+ * - For 'multicast': subscribe to MulticastManager's per-track frame callbacks
+ *   and forward through the TrackSource.onFrame interface.
+ * - For 'amt': same as multicast (AMT packets flow through MulticastManager.feedPacket).
+ * - For 'moq': no per-track source needed (MoQ is the default binary path).
+ */
+export function setupTrackPipeline(opts: SetupTrackPipelineOptions): SetupTrackPipelineResult {
+  const { router, multicastManager, tracks, preferences, capabilities, onTransportChange } = opts
+
+  // Build lookup: trackName → TrackDescriptor
+  const trackMap = new Map<string, TrackDescriptor>()
+  for (const t of tracks) {
+    trackMap.set(t.name, t)
+  }
+
+  const pipeline = new TrackPipeline(router)
+
+  // Register the TrackSource factory that bridges MulticastManager → TrackSource.
+  // Uses TrackDescriptor.type and .packetId — never guesses from track names.
+  pipeline.setSourceFactory((trackName: string, transport: TrackTransport): TrackSource | null => {
+    if (transport === 'moq') return null // MoQ is default binary path
+
+    const desc = trackMap.get(trackName)
+    if (!desc) {
+      console.warn(`[TrackPipeline] Unknown track "${trackName}" — no descriptor registered`)
+      return null
+    }
+
+    // Both 'multicast' and 'amt' route through MulticastManager
+    // (AMT packets arrive via feedPacket → same MmtpRouter pipeline)
+    return createMulticastTrackSource(multicastManager, desc)
+  })
+
+  if (onTransportChange) {
+    pipeline.onTransportChange(onTransportChange)
+  }
+
+  if (preferences) {
+    pipeline.setPreferences(preferences)
+  }
+
+  if (capabilities) {
+    pipeline.updateCapabilities(capabilities)
+  }
+
+  return {
+    pipeline,
+    dispose: () => pipeline.dispose(),
+  }
+}
+
+/**
+ * Create a TrackSource adapter that bridges MulticastManager frame callbacks
+ * into the TrackSource interface expected by MediaRouter.setTrackSource().
+ *
+ * Routes using the track descriptor's type and packetId — never name-based.
+ * If packetId is available, uses the specific onTrackFrame(packetId) callback
+ * for precise per-track routing. Falls back to onVideoFrame/onAudioFrame
+ * based on descriptor type.
+ */
+function createMulticastTrackSource(
+  manager: MulticastManager,
+  desc: TrackDescriptor,
+): TrackSource {
+  let frameCb: ((data: Uint8Array, meta: { timestamp: number; keyframe: boolean }) => void) | null = null
+  let errorCb: (() => void) | null = null
+  let wired = false
+
+  return {
+    name: desc.name,
+
+    onFrame(cb) {
+      frameCb = cb
+
+      if (!wired) {
+        wired = true
+
+        if (desc.packetId != null) {
+          // Precise per-packetId routing (preferred)
+          manager.onTrackFrame(desc.packetId, (data, meta) => {
+            frameCb?.(data, meta)
+          })
+        } else if (desc.type === 'video') {
+          manager.onVideoFrame((data, meta) => {
+            frameCb?.(data, meta)
+          })
+        } else if (desc.type === 'audio') {
+          manager.onAudioFrame((data, meta) => {
+            frameCb?.(data, meta)
+          })
+        }
+      }
+
+      return () => { frameCb = null }
+    },
+
+    onError(cb) {
+      errorCb = cb
+      manager.onFailback(() => { errorCb?.() })
+      return () => { errorCb = null }
+    },
+
+    dispose() {
+      frameCb = null
+      errorCb = null
+      wired = false
+    },
+  }
+}