@blockcast/mmt-container 2.2.0-main.7a01a10f6629 → 2.2.0-main.986a21fc9782

package/README.md

@@ -74,7 +74,7 @@ The package exposes a wide subpath surface so consumers can tree-shake aggressiv
 | `./multicast-unwrap` | Container-aware MMTP dispatch (LOC vs raw MMTP) |
 | `./signaling` | Packet-type classifier (`isSignalingPacket`, `isSourcePacket`, `classifyPacket`) |
 | `./mmtp-container-parser` | `MmtpContainerParser` (the unified, transport-agnostic parser) |
-| `./cmcd-producer` | `CmcdProducer` — RFC 9559 CMCD with `x-bc-*` vendor keys |
+| `./cmcd-producer` | `CmcdProducer` — CMCD v2 Event-mode reports (CTA-5004-B) with `com.blockcast-*` custom keys |
 | `./cmaf-block-assembler` | `CmafBlockAssembler` — assembles one CMAF segment per FEC source block |
 | `./cmaf-group-batcher` | `CmafGroupBatcher` — MoQ group → CMAF segment batcher |
 | `./carp-catalog` | CARP / CMSF catalog types, track-role parser, switching-set validator, track-timing |
@@ -425,36 +425,47 @@ Per-track timestamp rebase (`#videoBaseTs` / `#audioBaseTs` at `mmtp-to-cmaf.ts:
 
 ### CMCD producer (`./cmcd-producer`)
 
-Transport-agnostic CMCD (Common Media Client Data) telemetry per **RFC 9559**. Maps `FecTrackStats` snapshots and `TransportSnapshot` state to `x-bc-*` vendor keys (proto tags 70-99). Does NOT call `fetch()` or write to QUIC — emits via two callbacks (`onCmcdParams` for MoQ SUBSCRIBE params; `onCmcdPost` for HTTP POST query strings).
+CMCD v2 Event-mode reports (**CTA-5004-B** §2.2) for a player. Maps `FecTrackStats` snapshots, repair lifecycle events and `TransportSnapshot` state to newline-separated `application/cmcd` records (§3.3). Each record is an RFC 8941 dictionary with keys in alphabetical order and carries `v=2`, `ts`, `e`, `sn` and `sid`. Does NOT call `fetch()`: the player POSTs the body handed to `onCmcdPost` with `Content-Type: application/cmcd`.
 
 ```ts
 class CmcdProducer {
-  constructor(opts: CmcdProducerOptions)
+  constructor(opts: { onCmcdPost?: (body: string) => void; intervalMs?: number; sessionId?: string; now?: () => number })
   updateTransport(snapshot: TransportSnapshot): void
   updatePlayMode(mode: "full" | "base-only" | "single-track"): void
   updateDeltaFailRate(rate: number): void
+  updateFecFailClosed(reason: FecFailClosedReason): void
+  updateManifestVerification(stats: ManifestVerificationStats): void
   incrementSwitchMiscount(): void
+  onRepairLifecycle(event: RepairLifecycleEvent): void
   emitSwitchDrift(driftUs: number): void
   onSnapshot(data: SnapshotData): void
+  onTransportSnapshot(data: TransportOnlySnapshotData): void
   onTransition(event: TransportTransitionEvent): void
 }
 ```
 
-Vendor keys emitted (BLO-1044):
+Reports:
 
-| Key | Source | Notes |
+| `e` | When | Carries |
+|-----|------|---------|
+| `t` | heartbeat, every `intervalMs` (default 30 s), driven by snapshots | Table 1 keys only |
+| `ce`, `cen="com.blockcast-fec"` | with each `t` | the `com.blockcast-*` counters below |
+| `e` | FEC fails closed (fec-01 6.3.9), once per reason | `ec` = reason code |
+| `ce`, `cen="com.blockcast-ct"` | transport transition | `-ct` (`mc-start` / `mc-to-uc` / `amt-start`), transport keys |
+| `ce`, `cen="com.blockcast-switch-drift"` | `emitSwitchDrift()` | `-sdu` |
+
+Custom keys ride only `e=ce` (§2.2 admits only Table 1 keys on Event reports; the Table 1 `cen` row admits a custom key-value pair). Values are STRING or TOKEN of at most 64 characters (§4.1); numbers go out as strings, and a longer value is omitted. A value that is unknown is omitted, never sent as zero (§3). Counters are absolute since session start.
+
+| Key (`com.blockcast-`) | Source | Value |
 |-----|--------|-------|
-| `x-bc-fec-algo` | FEC config | `none` / `raptorq` / `reed-solomon` |
-| `x-bc-fec-k`, `x-bc-fec-p` | FEC config | source / repair counts |
-| `x-bc-fec-recovery` | `recoveryRate` | Block-level recovery, 4 decimal places |
-| `x-bc-transport` | `TransportSnapshot.transport` | `native` / `amt` / `moq` |
-| `x-bc-multicast-group`, `x-bc-multicast-source`, `x-bc-amt-relay` | endpoint | Omitted when null |
-| `x-bc-play-mode` | Phase 14 D-12 | `full` / `base-only` / `single-track` |
-| `x-bc-delta-fail-rate` | Phase 14 D-15 | 0..1, omitted on single-track |
-| `x-bc-switch-miscount`, `x-bc-switch-drift-us` | switching-set drift | One-shot for drift |
-| `x-bc-ct` | transport transition | `mc-start` / `mc-to-uc` / `amt-start` |
-
-All string values pass through `sanitize()` (T-06-01) — commas, `\r`, `\n` are stripped to prevent header injection.
+| `fa`, `fk`, `fp` | FEC config | algorithm; K; P as joined |
+| `pr`, `pl`, `pu` | `FecTrackStats` | source packets received; missing before FEC; still missing after FEC |
+| `fbf` | `FecTrackStats.blocksFailed` | failed blocks |
+| `fbr`, `fbq`, `fbfk` | repair lifecycle (video blocks) | recovered in band; recovered by repair FETCH; failed keyframe-class. Absent until `onRepairLifecycle` is fed |
+| `tr`, `sg`, `ar` | `TransportSnapshot` | `ssm` / `amt` / `moq`; `"<group>@<source>"`; AMT relay |
+| `pm`, `dfr` | play mode | `full` / `base-only` / `single-track`; delta fail rate, 3 decimals |
+| `ffc`, `ffl` | FEC fail-closed | reason code; held layer |
+| `sm`, `mv`, `mf` | switching set, source auth | miscount; manifests verified; verification failures |
 
 ### Multicast transport (`./multicast-transport`)
 
@@ -527,7 +538,8 @@ Roles are required by:
 - **draft-ramadan-moq-mmt-01** — MMT-over-MoQ wire format (§4.4.2 group-duration signaling, §4 MoQ object mapping, §5 MFU mode)
 - **draft-ramadan-moq-fec** — AL-FEC over MoQ (§5.3 FEC Source Info object extension 0x11: SS_ID(32), fixed 4 bytes)
 - **RFC 6330** — RaptorQ Forward Error Correction (strict OTI codec in `@blockcast/mmt-fec`)
-- **RFC 9559** — CMCD (used by `CmcdProducer`)
+- **CTA-5004-B** — CMCD v2 (used by `CmcdProducer`, Event mode)
+- **RFC 8941** — Structured Field Values (CMCD record encoding)
 - **ATSC A/331:2026-02 (informative for draft-fec-01 / draft-mmt-01; 7.2 SLS/MP table, 8.1.2.1 MMTP session, 8.1.2.5 AL-FEC) and A/331:2026-04 (normative for draft-multicast-01)** — Signaling, Delivery, Synchronization, Error Protection
 
 ## Related packages