@blockcast/mmt-container 0.3.0-main.36c5f6abe867 → 0.3.0-main.4c73d3ecc2db

package/README.md

@@ -180,12 +180,13 @@ type FecAlgorithm = "none" | "raptorq" | "reed-solomon"
 
 interface FecCatalogConfig {
   algorithm: FecAlgorithm        // §3.1
-  sourceSymbols: number          // K (REQUIRED)
+  blockProfile?: "iso-ssbg1-v1"  // REQUIRED unless algorithm is "none"; never defaulted (BLO-35597)
+  sourceSymbols: number          // K (REQUIRED): K_max, the largest SSB_length of any block
   repairSymbols: number          // P (REQUIRED)
   symbolSize: number             // T, 8-byte aligned (REQUIRED)
   interleaveDepthMs?: number     // FEC block span in MILLISECONDS, default 0 (single-group blocks)
   repairTrack: string            // §6.1 — required
-  mode?: "interleaved" | "object"
+  mode?: "interleaved" | "object"  // extension; "object" (per-frame object blocks) is retired: @blockcast/mmt-fec refuses it
   uep?: { keyRatio: number; deltaRatio: number }   // §9.1 — Unequal Error Protection
   deltaFailWindowBlocks?: number                   // D-11, base track only
   deltaProbeIntervalMs?: number                    // D-13, base track only
@@ -292,7 +293,8 @@ Codec-agnostic FEC decode service. Owns per-track decoder instances (sync WASM v
 
 ```ts
 interface FECManagerConfig {
-  k?: number
+  blockProfile?: FecBlockProfile // "iso-ssbg1-v1"; required for every FEC track, validated with parseFecBlockProfile
+  k?: number              // K_max (largest SSB_length), never a block stride
   symbolSize?: number     // T (bytes per symbol). NOT repair count.
   interleaveDepthMs?: number // FEC block span in MILLISECONDS — see MIN_INTERLEAVE_DEPTH_MS in fec-manager.ts
   fps?: number
@@ -314,6 +316,15 @@ class FECManager {
 
 `FECManager.configure()` takes `symbolSize` (bytes per symbol, T). Repair count is a distinct parameter and must never be passed in its place.
 
+FEC blocks follow one block profile, `iso-ssbg1-v1` (ISO/IEC 23008-1 Annex C ssbg_mode1, BLO-35597):
+
+- A source symbol is `u16 length || packet || 00h` padding to T.
+- A block is K' = SSB_length symbols keyed by its 32-bit SS_Start, and SS_ID increments by one per FEC source packet, wrapping at 2^32 (RFC 1982 serial arithmetic). Blocks are variable-length (SSB_length ≤ K), so K is an upper bound and never a stride: no block number is computed from an SS_ID.
+- A source symbol is placed in a block only once a repair symbol states that block's (SS_Start, SSB_length); until then it is held. Repair ESI = SSB_length + RS_ID.
+- The `sbn` in `getBlockStates()`, the block callbacks, and `RepairFetchRequest` is that SS_Start block key (the name is historical). The MoQ repair group id is the 62-bit wrap-epoch-extended SS_Start (`extSsStart` in `@blockcast/mmt-fec`), never the 32-bit key itself.
+
+`blockProfile` is never defaulted and never inferred from the wire. The retired Blockcast-private token `k-padded-v1` (zero-padded K-symbol blocks) is refused wherever a profile is read: `parseFecBlockProfile` throws for it (and for an absent token), and `FECManager` track configuration, `setupFecWorkerForTrack`, and `wireRepairFetch` all validate through it.
+
 `interleaveDepthMs` is the full FEC block span in **milliseconds** per CARP §5.1, valid range 33 ms (interactive / gaming, `MIN_INTERLEAVE_DEPTH_MS`) to 10 000 ms (broadcast ATSC 3.0). `configure()` warns if a positive value below `MIN_INTERLEAVE_DEPTH_MS` (33) is passed — that is almost certainly a raw frame count, not milliseconds — and such sub-floor values never drive the block timeout (the established timeout is preserved instead of collapsing to ~0).
 
 ### Keyframe-protected repair (`./block-policy`, `./conceal-timeline`)
@@ -325,9 +336,10 @@ Every FEC block still gets in-band FEC decode. On top of that:
   DU-header sample position) against catalog geometry (framerate,
   `interleaveDepthMs`, keyframe interval). Geometry that cannot be derived
   exactly, or any violated invariant, runs the track `all-protected` (every
-  video block `unknown`). Vanished blocks are materialised from SBN evidence.
-  A frame split across ADJACENT blocks (a K-close) is expected; only source
-  packets whose authored order and SBN order disagree (a round-robin
+  video block `unknown`). A block every symbol of which vanished is
+  materialised from the surrounding block evidence. A frame split across
+  ADJACENT blocks (a block closing at K symbols) is expected; only source
+  packets whose authored order and block order disagree (a round-robin
   interleave) trip `block-not-contiguous`. Pass the catalog track name to
   `configureTrackFec(packetId, config, catalogTrackName)` so ABR rungs that
   share a packetId each classify with their own framerate and GOP; a rung on
@@ -336,8 +348,10 @@ Every FEC block still gets in-band FEC decode. On top of that:
   and P1 (`audio`) immediately; P2 (`delta`) only while no P0/P1 is queued or
   in flight, earliest deadline first, preempted by any new P0/P1. No timers.
 - **FETCH priority (draft-ramadan-moq-fec §11.4.5).** The transport gets one
-  `RepairFetchRequest { repairTrack, sbn, packetId, signal,
-  subscriberPriority }` and puts `subscriberPriority` on the FETCH
+  `RepairFetchRequest { repairTrack, sbn, blockProfile, packetId, signal,
+  subscriberPriority }`, FETCHes the block's repair group (MoQ group id
+  `extSsStart(wrapEpoch, sbn)`, never `sbn` itself), and puts
+  `subscriberPriority` on the FETCH
   (`undefined` = omit the parameter; the publisher then uses 128,
   draft-ietf-moq-transport-16 §9.2.2.3). P0 requests carry
   `min(sourcePriority, 191)`; P1/P2 carry `max(repairPriority, 192)`. Both