@blockcast/mmt-base 0.5.0 → 1.0.0-main.3cb7359ea316

package/src/fec-bindings.ts

@@ -0,0 +1,281 @@
+/**
+ * Runtime FEC bindings (BLO-50171): what each source track's FEC resolves to
+ * for this library's receiver, read from `validateFecCatalog`'s per-instance
+ * result and never re-derived.
+ *
+ * Every runtime reader (the container's `resolveCatalogTrackFec`,
+ * `resolveRepairLayers`, `MulticastManager.configureMultiTrack`, transport's
+ * `catalogRepairTracks`) goes through `resolveFecBindings`, so they cannot
+ * disagree with the validator or with each other about which tracks have FEC
+ * and which repair tracks belong to them.
+ *
+ * The draft-ramadan-moq-fec-catalog-00 array is the only shape. Both catalog
+ * dialects bind through it: an MSF `tracks[]` entry directly, and a hang
+ * `video`/`audio` rendition (`fec` the same array) with its `repair.renditions`
+ * entries (`source` + `instanceId`), mapped onto a `tracks[]` view so the same
+ * validator runs. A hang rendition is authoritative over a `tracks[]` entry of
+ * the same name.
+ *
+ * Fail closed per instance: a source whose base instance is not `ok` resolves
+ * to `unavailable` with the validator's code and path, and costs no other
+ * track anything. A draft-01 object `fec` is `fec_member` at that track's
+ * `fec`: the track plays without FEC.
+ */
+import { validateFecCatalog, type FecCatalogCode, type FecCatalogReceiver } from './fec-catalog.js'
+
+/** The receiver this runtime is: it decodes `iso-ssbg1-v1` only. */
+export const RUNTIME_FEC_RECEIVER: FecCatalogReceiver = Object.freeze({
+  schemes: Object.freeze(['raptorq', 'reed-solomon']),
+  blockProfiles: Object.freeze(['iso-ssbg1-v1']),
+  overlays: true,
+})
+
+/** Repair track priority when the track states none (MoQT scale, 192..255). */
+export const DEFAULT_FEC_REPAIR_PRIORITY = 240
+
+/** One `ok` instance's geometry. */
+export interface FecInstanceGeometry {
+  readonly instanceId: number
+  readonly scheme: 'raptorq' | 'reed-solomon'
+  /** `iso-ssbg1-v1` under `RUNTIME_FEC_RECEIVER`. */
+  readonly blockProfile: string
+  /** K. */
+  readonly sourceSymbols: number
+  /** P_0 for a base instance; the overlay's own P for an overlay. */
+  readonly repairSymbols: number
+  /** T. */
+  readonly symbolSize: number
+  readonly interleaveDepthMs?: number
+  readonly reorderToleranceMs?: number
+  readonly repairTrack: string
+  readonly symbolTrack?: string
+}
+
+export interface FecLayerBinding {
+  readonly layer: number
+  readonly repairTrackName: string
+  readonly repairSymbols: number
+  /** O_i = sum(P_j, j < i). */
+  readonly rsIdOffset: number
+  readonly priority: number
+}
+
+export interface FecOverlayBinding {
+  readonly repairTrackName: string
+  readonly scope: 'keyframe'
+  readonly sourceSymbols: number
+  readonly repairSymbols: number
+  readonly priority: number
+  readonly geometry: FecInstanceGeometry
+}
+
+export interface FecBindingUnavailable {
+  /** The validator's code, or `fec_base_instances` for a track with no base
+   *  instance or more than one `ok` one (the MMTP wire carries one base Source FEC Payload
+   *  ID, mmt-02 7.4.1). */
+  readonly code: FecCatalogCode | 'fec_base_instances'
+  /** JSON Pointer into the catalog (a hang path starts `/video` or `/audio`). */
+  readonly path: string
+  readonly outcome: 'unavailable' | 'violation'
+}
+
+export type FecSourceBinding =
+  | {
+      readonly status: 'ok'
+      readonly track: string
+      /** JSON Pointer of the source track (`/tracks/<i>`, `/video/renditions/<name>`). */
+      readonly pointer: string
+      readonly base: FecInstanceGeometry
+      /** Base layers in order, layer 0 first. */
+      readonly layers: readonly FecLayerBinding[]
+      /** Sum of P over the base layers: the wire RSB_length. */
+      readonly totalBaseRepairSymbols: number
+      readonly overlay?: FecOverlayBinding
+      /** Why a declared overlay is not used, when one is not. */
+      readonly overlayUnavailable?: FecBindingUnavailable
+    }
+  | {
+      readonly status: 'unavailable'
+      readonly track: string
+      readonly pointer: string
+      readonly reason: FecBindingUnavailable
+    }
+
+type Obj = Record<string, unknown>
+const recordOf = (v: unknown): Obj | undefined =>
+  typeof v === 'object' && v !== null && !Array.isArray(v) ? (v as Obj) : undefined
+const escape = (s: string) => s.replace(/~/g, '~0').replace(/\//g, '~1')
+
+/**
+ * The `tracks[]` view of a catalog in either dialect, with each view track's
+ * JSON Pointer in the original catalog.
+ */
+export function fecCatalogTracks(catalog: unknown): { tracks: unknown[]; pointers: string[] } {
+  const root = recordOf(catalog) ?? {}
+  const tracks: unknown[] = []
+  const pointers: string[] = []
+  const hangNames = new Set<string>()
+  for (const role of ['video', 'audio'] as const) {
+    for (const [name, r] of Object.entries(recordOf(recordOf(root[role])?.['renditions']) ?? {})) {
+      const entry = recordOf(r)
+      if (!entry) continue
+      hangNames.add(name)
+      const kind = recordOf(entry['container'])?.['kind']
+      // A hang rendition carries no `packaging`; its container kind is it.
+      // `mmtp-fec` is hang's kind for MMTP that carries FEC (the FFmpeg
+      // publisher's `moq_publish_set_video_packaging`): MMTP packaging.
+      const view: Obj = { name, packaging: kind === undefined || kind === 'mmtp-fec' ? 'mmtp' : kind }
+      if (entry['fec'] !== undefined) view['fec'] = entry['fec']
+      tracks.push(view)
+      pointers.push(`/${role}/renditions/${escape(name)}`)
+    }
+  }
+  const hangRenditions = tracks.length
+  for (const [name, r] of Object.entries(recordOf(recordOf(root['repair'])?.['renditions']) ?? {})) {
+    hangNames.add(name)
+    tracks.push({ packaging: 'fec-repair', ...recordOf(r), name })
+    pointers.push(`/repair/renditions/${escape(name)}`)
+  }
+  const raw = Array.isArray(root['tracks']) ? root['tracks'] : []
+  const named = new Set(hangNames)
+  raw.forEach((t, i) => {
+    const name = recordOf(t)?.['name']
+    if (typeof name === 'string') named.add(name)
+    if (typeof name === 'string' && hangNames.has(name)) return
+    tracks.push(t)
+    pointers.push(`/tracks/${i}`)
+  })
+  // hang layer 0 needs no `repair.renditions` entry: the rendition's instance
+  // names it, and a hang Root (hang's toHang) carries no repair block. Such a
+  // name stands for a repair track of that instance.
+  tracks.slice(0, hangRenditions).forEach((t, ti) => {
+    const view = t as Obj
+    if (!Array.isArray(view['fec'])) return
+    view['fec'].forEach((o, ii) => {
+      const repairTrack = recordOf(o)?.['repairTrack']
+      if (typeof repairTrack !== 'string' || named.has(repairTrack)) return
+      named.add(repairTrack)
+      const instanceId = recordOf(o)?.['instanceId']
+      tracks.push({ name: repairTrack, packaging: 'fec-repair', source: view['name'], ...(instanceId === undefined ? {} : { instanceId }) })
+      pointers.push(`${pointers[ti]}/fec/${ii}/repairTrack`)
+    })
+  })
+  return { tracks, pointers }
+}
+
+/**
+ * Every source track's runtime FEC binding, by track name. A track with no
+ * `fec`, or an empty `fec` array, declares no FEC and has no entry.
+ */
+export function resolveFecBindings(
+  catalog: unknown,
+  receiver: FecCatalogReceiver = RUNTIME_FEC_RECEIVER,
+): ReadonlyMap<string, FecSourceBinding> {
+  const { tracks, pointers } = fecCatalogTracks(catalog)
+  const report = validateFecCatalog({ tracks }, receiver)
+  const at = (path: string) => {
+    const m = /^\/tracks\/(\d+)(.*)$/.exec(path)
+    return m ? pointers[Number(m[1])] + m[2] : path
+  }
+  const trackAt = (i: number) => recordOf(tracks[i]) ?? {}
+  const nameAt = (i: number | null) => (i === null ? undefined : (trackAt(i)['name'] as string))
+  const why = (i: { outcome: string; issues: readonly { code: FecCatalogCode; path: string }[]; path: string }) =>
+    Object.freeze({
+      code: i.issues[0]?.code ?? 'fec_member',
+      path: at(i.issues[0]?.path ?? i.path),
+      outcome: i.outcome === 'unavailable' ? ('unavailable' as const) : ('violation' as const),
+    })
+
+  const out = new Map<string, FecSourceBinding>()
+  tracks.forEach((t, ti) => {
+    const track = recordOf(t)
+    const name = track?.['name']
+    if (!track || typeof name !== 'string' || out.has(name)) return
+    if (track['packaging'] === 'fec-repair' || track['packaging'] === 'fec-source') return
+    const fec = track['fec']
+    if (fec === undefined) return
+    if (!Array.isArray(fec)) {
+      const reason = { code: 'fec_member' as const, path: at(`/tracks/${ti}/fec`), outcome: 'violation' as const }
+      out.set(name, Object.freeze({ status: 'unavailable', track: name, pointer: pointers[ti]!, reason: Object.freeze(reason) }))
+      return
+    }
+    if (fec.length === 0) return
+    const insts = report.instances.filter((i) => i.trackIndex === ti)
+    const isOverlay = (i: (typeof insts)[number]) => Object.hasOwn(recordOf(fec[Number(i.path.split('/').pop())]) ?? {}, 'scope')
+    const bases = insts.filter((i) => !isOverlay(i))
+    const okBases = bases.filter((i) => i.outcome === 'ok')
+    if (okBases.length !== 1) {
+      const reason =
+        // No base instance at all (overlay-only `fec`) is a count of 0, not
+        // the overlay's own issue.
+        okBases.length > 1 || bases.length === 0
+          ? Object.freeze({ code: 'fec_base_instances' as const, path: at(`/tracks/${ti}/fec`), outcome: 'violation' as const })
+          : why(bases[0] ?? insts[0]!)
+      out.set(name, Object.freeze({ status: 'unavailable', track: name, pointer: pointers[ti]!, reason }))
+      return
+    }
+    const b = okBases[0]!
+    const base = geometry(recordOf(fec[Number(b.path.split('/').pop())])!, b.instanceId!, nameAt(b.symbolTrack))
+    const priorityOf = (i: number | null) => {
+      const p = i === null ? undefined : trackAt(i)['priority']
+      return typeof p === 'number' ? p : DEFAULT_FEC_REPAIR_PRIORITY
+    }
+    const layers: FecLayerBinding[] = [
+      { layer: 0, repairTrackName: base.repairTrack, repairSymbols: base.repairSymbols, rsIdOffset: 0, priority: priorityOf(b.repairTrack) },
+    ]
+    const more = b.boundRepairTracks
+      .map((tj) => ({ tj, layer: trackAt(tj)['repairLayer'] as number }))
+      .sort((x, y) => x.layer - y.layer)
+    let offset = base.repairSymbols
+    for (const { tj, layer } of more) {
+      const repairSymbols = trackAt(tj)['repairSymbols'] as number
+      layers.push({ layer, repairTrackName: nameAt(tj)!, repairSymbols, rsIdOffset: offset, priority: priorityOf(tj) })
+      offset += repairSymbols
+    }
+    let overlay: FecOverlayBinding | undefined
+    let overlayUnavailable: FecBindingUnavailable | undefined
+    const ov = insts.find(isOverlay)
+    if (ov?.outcome === 'ok') {
+      const g = geometry(recordOf(fec[Number(ov.path.split('/').pop())])!, ov.instanceId!, nameAt(ov.symbolTrack))
+      overlay = Object.freeze({
+        repairTrackName: g.repairTrack,
+        scope: 'keyframe' as const,
+        sourceSymbols: g.sourceSymbols,
+        repairSymbols: g.repairSymbols,
+        priority: priorityOf(ov.repairTrack),
+        geometry: g,
+      })
+    } else if (ov) overlayUnavailable = why(ov)
+    out.set(
+      name,
+      Object.freeze({
+        status: 'ok' as const,
+        track: name,
+        pointer: pointers[ti]!,
+        base,
+        layers: Object.freeze(layers.map((l) => Object.freeze(l))),
+        totalBaseRepairSymbols: offset,
+        ...(overlay ? { overlay } : {}),
+        ...(overlayUnavailable ? { overlayUnavailable } : {}),
+      }),
+    )
+  })
+  return out
+}
+
+// The validator passed this instance for this receiver, so every member read
+// here is present and in range.
+function geometry(o: Obj, instanceId: number, symbolTrack: string | undefined): FecInstanceGeometry {
+  return Object.freeze({
+    instanceId,
+    scheme: o['scheme'] as 'raptorq' | 'reed-solomon',
+    blockProfile: o['blockProfile'] as string,
+    sourceSymbols: o['sourceSymbols'] as number,
+    repairSymbols: o['repairSymbols'] as number,
+    symbolSize: o['symbolSize'] as number,
+    ...(typeof o['interleaveDepthMs'] === 'number' ? { interleaveDepthMs: o['interleaveDepthMs'] } : {}),
+    ...(typeof o['reorderToleranceMs'] === 'number' ? { reorderToleranceMs: o['reorderToleranceMs'] } : {}),
+    repairTrack: o['repairTrack'] as string,
+    ...(symbolTrack !== undefined ? { symbolTrack } : {}),
+  })
+}