@blockcast/mmt-container 0.1.0 → 0.3.0

package/src/cmaf-group-batcher.ts

@@ -0,0 +1,104 @@
+/**
+ * CMAF batcher for MoQ group boundaries.
+ *
+ * Collects frames via addFrame() and emits a single multi-sample moof+mdat
+ * segment on flush(). Designed to be called once per MoQ group so one
+ * appendBuffer() call per group lands in MSE.
+ *
+ * Unlike CmafBlockAssembler (FEC-SBN keyed, for multicast), this class is
+ * caller-driven — no SBN/ESI, no block timeouts. Call flush() when the
+ * group's readFrame() loop returns done.
+ *
+ * Timestamps passed to addFrame() MUST be in the same timescale the caller
+ * used to build the init segment (typically microseconds). The batcher does
+ * not scale — it rebases per-instance (first sample → 0) and passes
+ * inter-frame deltas as sample durations.
+ */
+
+import { encodeMultiSampleSegment } from './mmtp-to-cmaf.js'
+
+export interface CmafGroupBatcherConfig {
+  trackType: 'video' | 'audio'
+  /** ISO track ID. Must match the trackId used when building the init segment. */
+  trackId: number
+  /**
+   * Duration (in the same units as timestamp) for the last sample of a group
+   * with exactly one frame (no inter-frame delta to measure). Derive from
+   * catalog: video = 1_000_000 / fps; audio = 1_000_000 * 1024 / sampleRate.
+   */
+  fallbackFrameDuration: number
+}
+
+interface BufferedFrame {
+  data: Uint8Array
+  timestamp: number
+  keyframe: boolean
+}
+
+export class CmafGroupBatcher {
+  readonly trackType: 'video' | 'audio'
+  readonly #trackId: number
+  readonly #fallbackFrameDuration: number
+
+  #buffer: BufferedFrame[] = []
+  #sequence = 1
+  #baseTs = -1
+  #disposed = false
+
+  onSegment: ((segment: Uint8Array) => void) | null = null
+
+  constructor(config: CmafGroupBatcherConfig) {
+    if (!Number.isFinite(config.trackId) || config.trackId <= 0) {
+      throw new Error(`CmafGroupBatcher: trackId must be a positive finite number (got ${config.trackId})`)
+    }
+    if (!Number.isFinite(config.fallbackFrameDuration) || config.fallbackFrameDuration <= 0) {
+      throw new Error(
+        `CmafGroupBatcher: fallbackFrameDuration must be positive and finite — derive from catalog (video=1e6/fps, audio=1e6*1024/sampleRate). Got ${config.fallbackFrameDuration}`,
+      )
+    }
+    this.trackType = config.trackType
+    this.#trackId = config.trackId
+    this.#fallbackFrameDuration = config.fallbackFrameDuration
+  }
+
+  addFrame(data: Uint8Array, timestamp: number, keyframe: boolean): void {
+    if (this.#disposed) return
+    this.#buffer.push({ data, timestamp, keyframe })
+  }
+
+  flush(): void {
+    if (this.#disposed) return
+    const frames = this.#buffer
+    if (frames.length === 0) return
+    this.#buffer = []
+
+    if (this.#baseTs < 0) this.#baseTs = frames[0].timestamp
+    const relTs = frames[0].timestamp - this.#baseTs
+
+    const samples = frames.map((f, i) => {
+      let duration: number
+      if (i < frames.length - 1) {
+        duration = frames[i + 1].timestamp - f.timestamp
+      } else {
+        duration = i > 0 ? (f.timestamp - frames[i - 1].timestamp) : this.#fallbackFrameDuration
+      }
+      if (duration <= 0) duration = this.#fallbackFrameDuration
+      return { data: f.data, duration, keyframe: f.keyframe }
+    })
+
+    const segment = encodeMultiSampleSegment(samples, relTs, this.#sequence++, this.#trackId)
+    this.onSegment?.(segment)
+  }
+
+  reset(): void {
+    this.#buffer = []
+    this.#sequence = 1
+    this.#baseTs = -1
+  }
+
+  dispose(): void {
+    this.#disposed = true
+    this.#buffer = []
+    this.onSegment = null
+  }
+}

package/src/cmcd-producer.ts

@@ -0,0 +1,329 @@
+/**
+ * CmcdProducer — transport-agnostic CMCD telemetry producer.
+ *
+ * Maps FecTrackStats snapshots and TransportSnapshot state to x-bc-*
+ * CMCD vendor keys (proto tags 70-99). Fires callbacks for two delivery
+ * channels: MoQ SUBSCRIBE params and multicast HTTP POST.
+ *
+ * Does NOT call fetch() or write to QUIC directly — the player wiring
+ * layer is responsible for attaching params to SUBSCRIBE or POSTing
+ * the payload to the CDN CMCD endpoint.
+ *
+ * @see docs/superpowers/specs/2026-04-15-iwa-multicast-stack-design.md §3.3
+ * @see CDN+ Track D BLO-1044
+ */
+
+import type { FecTrackStats } from '@blockcast/fec-worker'
+import type { ManifestVerificationStats } from '@blockcast/mmt-manifest-verify'
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** Transport state snapshot, built by the player wiring layer from SocketPool. */
+export interface TransportSnapshot {
+  transport: 'native' | 'amt' | 'moq'
+  /** IPv4/IPv6 multicast group address */
+  multicastGroup?: string
+  /** SSM source address */
+  multicastSource?: string
+  /** AMT relay address (omit when undefined) */
+  amtRelay?: string
+}
+
+/** Transport transition event identifiers for x-bc-ct. */
+export type TransportTransitionEvent = 'mc-start' | 'mc-to-uc' | 'amt-start'
+
+/**
+ * Phase 14 play-mode state (D-12, x-bc-play-mode):
+ * - `full`         — base + delta both active
+ * - `base-only`    — delta fell back; base carries playback
+ * - `single-track` — stream is not a multi-track switching set (legacy)
+ */
+export type PlayMode = 'full' | 'base-only' | 'single-track'
+
+const PLAY_MODES: readonly PlayMode[] = ['full', 'base-only', 'single-track']
+
+/** CMCD vendor key map. Values are string, number, or boolean. */
+export type CmcdParams = Record<string, string | number | boolean>
+
+/** Options for CmcdProducer construction. */
+export interface CmcdProducerOptions {
+  /** Fired on each snapshot and on transport transitions. Params for MoQ SUBSCRIBE. */
+  onCmcdParams?: (params: CmcdParams) => void
+  /** Fired on each snapshot and on transport transitions. RFC 9559 query-string for HTTP POST body. */
+  onCmcdPost?: (payload: string) => void
+}
+
+/** Snapshot data passed to onSnapshot(). */
+export interface SnapshotData {
+  tracks: FecTrackStats[]
+  timestampMs: number
+}
+
+/** Transport-only telemetry for receivers that do not own FEC track stats. */
+export interface TransportOnlySnapshotData {
+  transport: TransportSnapshot
+  timestampMs: number
+  playMode?: PlayMode
+  switchMiscount?: number
+}
+
+// ---------------------------------------------------------------------------
+// Value sanitization (T-06-01: header injection mitigation)
+// ---------------------------------------------------------------------------
+
+/** Strip commas, newlines, and carriage returns from string values. */
+function sanitize(value: string): string {
+  return value.replace(/[,\r\n]/g, '')
+}
+
+// ---------------------------------------------------------------------------
+// Key building (pure functions, no side effects)
+// ---------------------------------------------------------------------------
+
+/** Build FEC vendor keys from a FecTrackStats snapshot. */
+function buildFecParams(stats: FecTrackStats): CmcdParams {
+  const params: CmcdParams = {}
+  const cfg = stats.config
+
+  params['x-bc-fec-algo'] = cfg.algorithm
+  params['x-bc-fec-k'] = cfg.k
+  // P as this receiver JOINED it: the worker is configured from
+  // TrackSessionConfig.joinedRepairCount, the sum of repairSymbols over the
+  // joined base layers. Not the catalog total, which a receiver on a clean path
+  // does not receive, and never including a keyframe overlay (separate FEC
+  // instance with its own RSB_length).
+  params['x-bc-fec-p'] = cfg.repairCount
+  params['x-bc-fec-recovery'] = parseFloat((stats.recoveryRate / 100).toFixed(4))
+
+  // ALTA keys: omit entirely when altaEnabled is false (D-09)
+  if (cfg.altaEnabled) {
+    params['x-bc-alta-verified'] = stats.altaVerified > 0
+    params['x-bc-alta-failures'] = stats.altaFailed
+  }
+
+  return params
+}
+
+/** Build transport vendor keys from a TransportSnapshot. */
+function buildTransportParams(snap: TransportSnapshot | undefined): CmcdParams {
+  if (!snap) return {}
+
+  const params: CmcdParams = {}
+  params['x-bc-transport'] = snap.transport
+
+  if (snap.multicastGroup != null) {
+    params['x-bc-multicast-group'] = snap.multicastGroup
+  }
+  if (snap.multicastSource != null) {
+    params['x-bc-multicast-source'] = snap.multicastSource
+  }
+  if (snap.amtRelay != null) {
+    params['x-bc-amt-relay'] = snap.amtRelay
+  }
+
+  return params
+}
+
+// ---------------------------------------------------------------------------
+// Query-string serialization (RFC 9559 §2)
+// ---------------------------------------------------------------------------
+
+/**
+ * Serialize CmcdParams to RFC 9559 query-string format.
+ * Keys sorted for deterministic output. String values sanitized.
+ */
+function formatQueryString(params: CmcdParams): string {
+  return Object.keys(params)
+    .sort()
+    .map(key => {
+      const v = params[key]
+      if (typeof v === 'string') return `${key}=${sanitize(v)}`
+      return `${key}=${v}`
+    })
+    .join(',')
+}
+
+// ---------------------------------------------------------------------------
+// CmcdProducer
+// ---------------------------------------------------------------------------
+
+export class CmcdProducer {
+  #onCmcdParams: ((params: CmcdParams) => void) | undefined
+  #onCmcdPost: ((payload: string) => void) | undefined
+  #transport: TransportSnapshot | undefined
+  #lastStats: FecTrackStats | undefined
+  // Phase 14 state — Plan 03 Task 2 (D-12, D-15).
+  #playMode: PlayMode | null = null
+  #deltaFailRate: number | null = null
+  #switchMiscount = 0
+  #manifestStats: ManifestVerificationStats | null = null
+
+  constructor(options: CmcdProducerOptions) {
+    this.#onCmcdParams = options.onCmcdParams
+    this.#onCmcdPost = options.onCmcdPost
+  }
+
+  /** Update the stored transport state. Called by player wiring layer. */
+  updateTransport(snapshot: TransportSnapshot): void {
+    this.#transport = snapshot
+  }
+
+  /**
+   * Set the current play-mode. Emitted as `x-bc-play-mode` on subsequent
+   * snapshots. Throws on any value outside {'full','base-only','single-track'}
+   * (CLAUDE.md: error on bad init).
+   */
+  updatePlayMode(mode: PlayMode): void {
+    if (typeof mode !== 'string' || !PLAY_MODES.includes(mode as PlayMode)) {
+      throw new Error(
+        `[CmcdProducer] invalid play-mode "${String(mode)}"; expected one of: ${PLAY_MODES.join(', ')}`,
+      )
+    }
+    this.#playMode = mode
+  }
+
+  /**
+   * Set the delta-track FEC block-failure rate (0..1 inclusive). Emitted as
+   * `x-bc-delta-fail-rate` on snapshots when play-mode is 'full' or 'base-only'.
+   * Omitted on single-track streams.
+   */
+  updateDeltaFailRate(rate: number): void {
+    if (typeof rate !== 'number' || !Number.isFinite(rate) || rate < 0 || rate > 1) {
+      throw new Error(
+        `[CmcdProducer] invalid delta-fail-rate "${String(rate)}"; expected a finite number in [0, 1]`,
+      )
+    }
+    this.#deltaFailRate = rate
+  }
+
+  /**
+   * Bump the cumulative switching-set misalignment counter. Emitted as
+   * `x-bc-switch-miscount` on snapshots when the counter is > 0.
+   */
+  incrementSwitchMiscount(): void {
+    this.#switchMiscount += 1
+  }
+
+  updateManifestVerification(stats: ManifestVerificationStats): void {
+    this.#manifestStats = stats
+  }
+
+  /**
+   * One-shot emit of `x-bc-switch-drift-us` for a single misalignment event.
+   * Does NOT mutate snapshot state — subsequent onSnapshot() calls will not
+   * include the drift key until the next emitSwitchDrift(). Mirrors the
+   * existing onTransition() pattern.
+   */
+  emitSwitchDrift(driftUs: number): void {
+    if (
+      typeof driftUs !== 'number' ||
+      !Number.isFinite(driftUs) ||
+      driftUs < 0
+    ) {
+      throw new Error(
+        `[CmcdProducer] invalid drift-us "${String(driftUs)}"; expected a non-negative finite number`,
+      )
+    }
+    const params: CmcdParams = {}
+    if (this.#lastStats) Object.assign(params, buildFecParams(this.#lastStats))
+    Object.assign(params, buildTransportParams(this.#transport))
+    if (this.#switchMiscount > 0) params['x-bc-switch-miscount'] = this.#switchMiscount
+    params['x-bc-switch-drift-us'] = driftUs
+    this.#emit(params)
+  }
+
+  /**
+   * Process a FecTrackStats snapshot. Finds the video track, builds
+   * x-bc-* vendor keys, and fires both delivery callbacks.
+   */
+  onSnapshot(data: SnapshotData): void {
+    // Find first video track; skip if none
+    const videoTrack = data.tracks.find(t => t.config.trackType === 'video')
+    if (!videoTrack) return
+
+    this.#lastStats = videoTrack
+
+    const params: CmcdParams = {
+      ...buildFecParams(videoTrack),
+      ...buildTransportParams(this.#transport),
+    }
+
+    if (this.#playMode !== null) {
+      params['x-bc-play-mode'] = this.#playMode
+    }
+
+    // Delta-fail-rate is only meaningful when a delta track exists.
+    if (
+      this.#playMode !== null &&
+      this.#playMode !== 'single-track' &&
+      this.#deltaFailRate !== null
+    ) {
+      params['x-bc-delta-fail-rate'] = parseFloat(this.#deltaFailRate.toFixed(4))
+    }
+
+    if (this.#switchMiscount > 0) {
+      params['x-bc-switch-miscount'] = this.#switchMiscount
+    }
+    if (this.#manifestStats) {
+      params['x-bc-manifest-verified'] = this.#manifestStats.verified > 0
+      params['x-bc-manifest-failures'] = Object.values(this.#manifestStats.failures)
+        .reduce((total, count) => total + count, 0)
+    }
+
+    this.#emit(params)
+  }
+
+  /**
+   * Emit transport state without inventing FEC metrics. Cadence is owned by
+   * the caller because only the transport integration knows when state changed.
+   */
+  onTransportSnapshot(data: TransportOnlySnapshotData): void {
+    if (!Number.isFinite(data.timestampMs) || data.timestampMs < 0) {
+      throw new Error('[CmcdProducer] transport snapshot timestamp must be a non-negative finite number')
+    }
+    if (data.playMode !== undefined) this.updatePlayMode(data.playMode)
+    if (
+      data.switchMiscount !== undefined &&
+      (!Number.isSafeInteger(data.switchMiscount) || data.switchMiscount < 0)
+    ) {
+      throw new Error('[CmcdProducer] transport snapshot switch-miscount must be a non-negative safe integer')
+    }
+
+    this.#transport = data.transport
+    const params = buildTransportParams(data.transport)
+    if (this.#playMode !== null) params['x-bc-play-mode'] = this.#playMode
+    const switchMiscount = data.switchMiscount ?? this.#switchMiscount
+    if (switchMiscount > 0) params['x-bc-switch-miscount'] = switchMiscount
+    this.#emit(params)
+  }
+
+  /**
+   * Signal a transport transition event. Fires an immediate out-of-band
+   * emit with x-bc-ct set. The subsequent onSnapshot() will NOT include
+   * x-bc-ct (one-shot).
+   */
+  onTransition(event: TransportTransitionEvent): void {
+    const params: CmcdParams = {}
+
+    // Include last known FEC stats if available
+    if (this.#lastStats) {
+      Object.assign(params, buildFecParams(this.#lastStats))
+    }
+
+    // Include transport state if available
+    Object.assign(params, buildTransportParams(this.#transport))
+
+    // Add the transition event key (one-shot)
+    params['x-bc-ct'] = event
+
+    this.#emit(params)
+  }
+
+  /** Fire both delivery callbacks with the given params. */
+  #emit(params: CmcdParams): void {
+    this.#onCmcdParams?.(params)
+    this.#onCmcdPost?.(formatQueryString(params))
+  }
+}