@blockcast/mmt-container 0.3.0 → 0.4.0-main.1e94b11199ea

package/src/track-session.ts

@@ -172,24 +172,32 @@ export interface FecDeliveryWindowConfig {
 export function computeFecDeliveryWindowMs(
   config: FecDeliveryWindowConfig,
 ): number {
-  const fecInterleaveMs = config.interleaveDepthMs
   const fecK = config.sourceSymbols
-  if (!Number.isFinite(fecInterleaveMs) || fecInterleaveMs <= 0) {
-    throw new Error(
-      `[TrackSession] fecInterleaveMs=${fecInterleaveMs}. ` +
-      `Derive a positive FEC interleave window from the stream catalog.`
-    )
-  }
   if (!Number.isFinite(fecK) || fecK <= 0) {
     throw new Error(
       `[TrackSession] fecK=${fecK}. ` +
       `Derive a positive FEC source-symbol count from the stream catalog.`
     )
   }
+  return fecSpanDeliveryWindowMs(config.interleaveDepthMs, config.jitterBufferMs)
+}
 
+/**
+ * The delivery window of a §5.1 span alone. Every window is this; K only
+ * validates a track's geometry in computeFecDeliveryWindowMs, so a caller
+ * with a span and no K (FECManager's stream-global envelope) uses this
+ * rather than invent one.
+ */
+export function fecSpanDeliveryWindowMs(interleaveDepthMs: number, jitterBufferMs?: number): number {
+  if (!Number.isFinite(interleaveDepthMs) || interleaveDepthMs <= 0) {
+    throw new Error(
+      `[TrackSession] fecInterleaveMs=${interleaveDepthMs}. ` +
+      `Derive a positive FEC interleave window from the stream catalog.`
+    )
+  }
   // Absence stays absent; it does not authorize a synthesized reorder budget.
-  if (config.jitterBufferMs === undefined) return Math.ceil(fecInterleaveMs)
-  return fecBlockBudgetMs(fecInterleaveMs, config.jitterBufferMs)
+  if (jitterBufferMs === undefined) return Math.ceil(interleaveDepthMs)
+  return fecBlockBudgetMs(interleaveDepthMs, jitterBufferMs)
 }
 
 /** Convert the shared FEC delivery deadline into an integer media timescale. */
@@ -377,6 +385,17 @@ export class TrackSession {
   /** multicast/amt → failing: loss detected, start hysteresis timer (Claim 9f). */
   lossDetected(): void {
     if (this.#state !== 'multicast' && this.#state !== 'amt') return
+
+    // A zero/absent catalog span carries no elapsed FEC deadline. The stall
+    // detector that calls this method already supplied the generic loss
+    // evidence, so there is no FEC hysteresis window to derive here. Follow
+    // the existing transport-failure edge immediately instead of inventing a
+    // local timeout for a catalog value that explicitly supplied none.
+    if (this.config.fecInterleaveMs === 0 || this.config.fecInterleaveMs === undefined) {
+      this.transportFailed()
+      return
+    }
+
     this.#previousPrimary = this.#state as SubscriptionMode
     this.#transition('failing')
 

package/test-vectors/catalog/README.md

@@ -8,13 +8,22 @@ Positive fixtures MUST validate against `schemas/catalog.schema.json`.
 `releases/` is a third category — a frozen record of what a shipped release
 actually emitted, which validates or fails depending on what that release
 predates; it is never edited to make it pass.
-Negative fixtures are the migration worklist and MUST fail:
+Negative fixtures are the migration worklist and MUST fail.
+`section-codes.json` lists every negative once: the code and path the
+TypeScript runtime validator and the Rust catalog section (`mmt_fec::catalog`)
+both reject it with, or `outOfSection` when the section does not own the field.
+The Rust section owns only the track MMTP/FEC/repair/timing fields.
+
+The negatives:
 
 - `legacy-selection-params.json`: rendition fields must be flat.
 - `missing-mmtp-fields.json`: MMTP tracks require mode, timescale, and duration.
 - `multicast-packet-id-signaling.json`: an endpoint track's `packetId` is
   1..65535; `packetId` 0 is the MMTP signaling flow and is never a track's.
 - `network-source-object.json`: `networkSource` is always an array.
+- `multicast-endpoint-relay-address.json`: the AMT relay is catalog-level
+  `networkSource[{type:"amt",relay}]`; an endpoint `relayAddress` is retired
+  and rejected (`multicast_relay_address`), not ignored.
 - `multicast-network-source-empty.json`: `networkSource` is optional, but an
   empty array is not a way to say "absent" — omit the key instead.
 - `repair-track-legacy-shape.json`: repair tracks use `packaging: "fec-repair"`.
@@ -28,9 +37,13 @@ Negative fixtures are the migration worklist and MUST fail:
   and `scope` are `fec-repair` track fields only.
 - `raptorq-source-symbols-over-max.json`: RaptorQ K is at most 56403 (RFC 6330).
 - `fec-block-profile-missing.json`: an FEC instance must name its block
-  profile; there is no default.
-- `fec-block-profile-unknown.json`: `fec.blockProfile` is one of the two known
-  tokens; a near-miss such as `"iso-ssbg1"` is rejected, not normalized.
+  profile; there is no default (`track_fec_block_profile`).
+- `fec-block-profile-unknown.json`: `fec.blockProfile` is `"iso-ssbg1-v1"`; a
+  near-miss such as `"iso-ssbg1"` is rejected, not normalized
+  (`track_fec_block_profile_unimplemented`).
+- `fec-block-profile-retired.json`: the retired Blockcast-private
+  `"k-padded-v1"` is not a block profile
+  (`track_fec_block_profile_unimplemented`).
 - `archive-origin-with-path.json`: `archive.origin` is scheme and authority
   only. A path would make the derived object URL ambiguous above a codec that
   refuses percent-encoding precisely so each identity has one URL path.
@@ -49,21 +62,33 @@ exercised: `{ns}` is the track's own `namespace`, or the MoQ subscription's
 Track Namespace tuple when the track declares none.
 
 Every `fec` object that declares an FEC instance (any `algorithm` other than
-`"none"`) carries `fec.blockProfile` (BLO-35597, ISO/IEC 23008-1 Annex C), the
-one per-stream discriminator between the two block profiles. It is never
-defaulted and never inferred from the wire, because both profiles carry
-identical wire tuples whose repair math differs:
+`"none"`) carries `fec.blockProfile` (BLO-35597, ISO/IEC 23008-1 Annex C).
+draft-ramadan-moq-fec §5.1 defines exactly one value, `"iso-ssbg1-v1"`
+(ssbg_mode1, `K' = SSB_length`, consecutive SS_IDs), and it is never defaulted
+and never inferred from the wire. Any other token, the retired
+Blockcast-private `"k-padded-v1"` included, fails validation with
+`track_fec_block_profile_unimplemented`; an absent token on an FEC instance
+fails with `track_fec_block_profile`. A receiver consumes such a track without
+FEC and joins none of its repair tracks, without failing the session or any
+other track's FEC.
 
-- `"k-padded-v1"` (legacy): zero-padded K-symbol blocks, `SS_Start = SBN*K`.
-  Every fixture that predates the token carries this value, which is the wire
-  it always described.
-- `"iso-ssbg1-v1"`: ssbg_mode1, `K' = SSB_length`, consecutive SS_IDs.
-  `fec-iso-ssbg1.json` is `fec-multicast.json` under this profile.
+`"iso-ssbg1-v1"` bounds a block's location by its span, so a receiver applies
+FEC only when `fec.interleaveDepthMs` is at least 33 ms; without it the track
+resolves to no FEC (`track_fec_block_span` on `interleaveDepthMs`; a declared
+span below the floor is `track_fec`). The schema and the
+CMSF validator do not require the field. Every fixture that carried
+`"k-padded-v1"` now names `"iso-ssbg1-v1"`. The FEC-carrying positives that
+omitted the span (`fec-multicast.json`,
+`multicast-native-ssm-no-network-source.json`) now declare the one-group span
+their omitted field used to mean (`interleaveDepthMs` equal to
+`groupDurationMs`, 1000). `fec-iso-ssbg1.json` is `fec-multicast.json` without
+that span: a valid catalog whose FEC a receiver cannot apply.
 
 On `algorithm: "none"` the field is optional, but a present token must still be
-known. Repair tracks carry no `fec`, so they carry no profile; a repair layer or
-overlay inherits its source's. Every negative fixture with an FEC source names
-`"k-padded-v1"`, so each still fails for exactly the reason listed above.
+implemented. Repair tracks carry no `fec`, so they carry no profile; a repair
+layer or overlay inherits its source's. Every negative fixture with an FEC
+source names `"iso-ssbg1-v1"` unless the profile is what it tests, so each still
+fails for exactly the reason listed above.
 
 `fec-layered-repair.json` carries base layers 0..2 and a keyframe overlay for one
 source (draft-ramadan-moq-fec 6.3): layer 0 is `fec.repairTrack`, every further
@@ -71,8 +96,9 @@ repair track names its source in `depends`, and the second endpoint carries only
 repair tracks. Priority is on the MoQT scale (lower first); `audio-repair`
 declares none and so is layer 0 at the default 240.
 
-An omitted `fec.interleaveDepthMs` means one group (`D=1`); it does not disable
-FEC. When present, `groupDurationTicks` overrides the integer millisecond field.
+An omitted `fec.interleaveDepthMs` is valid catalog shape, but under
+`"iso-ssbg1-v1"` it leaves the track without FEC at a receiver (see above).
+When present, `groupDurationTicks` overrides the integer millisecond field.
 Switching sets compare `ticks / timescale`, so equal wall-clock durations at
 different timescales are valid.
 

package/test-vectors/catalog/negative/fec-block-profile-retired.json

@@ -0,0 +1,52 @@
+{
+  "version": 1,
+  "streamingFormat": "mmtp",
+  "streamingFormatVersion": "draft-ramadan-moq-mmt-00",
+  "tracks": [
+    {
+      "name": "video",
+      "packaging": "mmtp",
+      "codec": "avc1.640028",
+      "mmtpMode": "mfu",
+      "timescale": 90000,
+      "groupDurationMs": 1000,
+      "fec": {
+        "algorithm": "raptorq",
+        "blockProfile": "k-padded-v1",
+        "sourceSymbols": 768,
+        "repairSymbols": 384,
+        "symbolSize": 1312,
+        "repairTrack": "video-repair",
+        "mode": "interleaved"
+      }
+    },
+    {
+      "name": "video-repair",
+      "packaging": "fec-repair",
+      "priority": 240
+    }
+  ],
+  "multicast": {
+    "endpoints": [
+      {
+        "sourceAddress": "192.0.2.10",
+        "groupAddress": "232.1.1.1",
+        "port": 5000,
+        "tracks": [
+          { "name": "video", "packetId": 1 },
+          { "name": "video-repair", "packetId": 2 }
+        ]
+      }
+    ],
+    "networkSource": [
+      { "type": "amt", "discovery": "driad" },
+      {
+        "type": "atsc3",
+        "frequency": 587000000,
+        "plpId": 0,
+        "serviceId": 101,
+        "slsUri": "https://example.test/atsc3/service/101/sls.xml"
+      }
+    ]
+  }
+}

package/test-vectors/catalog/negative/fec-enhancement-repair-removed.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/fec-repair-layer-geometry.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/fec-repair-layer-missing-symbols.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/fec-repair-multiple-depends.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/fec-repair-overlay-with-layer.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/fec-repair-priority-out-of-band.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/fec-repair-source-symbols-without-scope.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/multicast-endpoint-relay-address.json

@@ -0,0 +1,39 @@
+{
+  "version": 1,
+  "streamingFormat": "mmtp",
+  "streamingFormatVersion": "draft-ramadan-moq-mmt-00",
+  "tracks": [
+    {
+      "name": "video",
+      "packaging": "mmtp",
+      "codec": "avc1.640028",
+      "mmtpMode": "mfu",
+      "timescale": 90000,
+      "groupDurationMs": 1000
+    }
+  ],
+  "multicast": {
+    "endpoints": [
+      {
+        "protocol": "amt",
+        "sourceAddress": "192.0.2.10",
+        "groupAddress": "232.1.1.1",
+        "port": 5000,
+        "relayAddress": "amt-relay.example.test",
+        "tracks": [
+          {
+            "name": "video",
+            "packetId": 1
+          }
+        ]
+      }
+    ],
+    "networkSource": [
+      {
+        "type": "amt",
+        "discovery": "manual",
+        "relay": "amt-relay.example.test"
+      }
+    ]
+  }
+}

package/test-vectors/catalog/negative/multicast-network-source-empty.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 768,
         "repairSymbols": 384,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/raptorq-source-symbols-over-max.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 56404,
         "repairSymbols": 8,
         "symbolSize": 1312,

package/test-vectors/catalog/negative/raptorq-unaligned-symbol.json

@@ -6,12 +6,13 @@
     {
       "name": "video",
       "packaging": "mmtp",
+      "codec": "avc1.640028",
       "mmtpMode": "mfu",
       "timescale": 90000,
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 32,
         "repairSymbols": 8,
         "symbolSize": 1310,

package/test-vectors/catalog/positive/fec-layered-repair.json

@@ -12,7 +12,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 64,
         "repairSymbols": 8,
         "symbolSize": 1312,
@@ -62,7 +62,7 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 47,
         "repairSymbols": 4,
         "symbolSize": 1312,

package/test-vectors/catalog/positive/fec-multicast.json

@@ -12,10 +12,11 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 768,
         "repairSymbols": 384,
         "symbolSize": 1312,
+        "interleaveDepthMs": 1000,
         "repairTrack": "video-repair",
         "mode": "interleaved"
       }

package/test-vectors/catalog/positive/multicast-amt-manual-relay.json

@@ -0,0 +1,38 @@
+{
+  "version": 1,
+  "streamingFormat": "mmtp",
+  "streamingFormatVersion": "draft-ramadan-moq-mmt-00",
+  "tracks": [
+    {
+      "name": "video",
+      "packaging": "mmtp",
+      "codec": "avc1.640028",
+      "mmtpMode": "mfu",
+      "timescale": 90000,
+      "groupDurationMs": 1000
+    }
+  ],
+  "multicast": {
+    "endpoints": [
+      {
+        "protocol": "amt",
+        "sourceAddress": "192.0.2.10",
+        "groupAddress": "232.1.1.1",
+        "port": 5000,
+        "tracks": [
+          {
+            "name": "video",
+            "packetId": 1
+          }
+        ]
+      }
+    ],
+    "networkSource": [
+      {
+        "type": "amt",
+        "discovery": "manual",
+        "relay": "amt-relay.example.test"
+      }
+    ]
+  }
+}

package/test-vectors/catalog/positive/multicast-native-ssm-no-network-source.json

@@ -12,10 +12,11 @@
       "groupDurationMs": 1000,
       "fec": {
         "algorithm": "raptorq",
-        "blockProfile": "k-padded-v1",
+        "blockProfile": "iso-ssbg1-v1",
         "sourceSymbols": 768,
         "repairSymbols": 384,
         "symbolSize": 1312,
+        "interleaveDepthMs": 1000,
         "repairTrack": "video-repair",
         "mode": "interleaved"
       }

package/test-vectors/catalog/section-codes.json

@@ -0,0 +1,33 @@
+{
+  "description": "What the MMTP/FEC/repair/timing catalog section rejects each negative fixture with. Read by packages/container/src/catalog-schema.test.ts (against validateCmsfMmtpCatalog) and mmt-fec/tests/catalog_section_vectors.rs (against mmt_fec::catalog::validate_tracks): both engines must report the same code at the same JSON path. Every negative fixture is listed exactly once; outOfSection names fields the section does not own, which the embedding catalog validates.",
+  "negative": {
+    "archive-origin-with-path.json": { "outOfSection": "archive" },
+    "archive-unknown-field.json": { "outOfSection": "archive" },
+    "fec-block-profile-missing.json": { "code": "track_fec_block_profile", "path": "$.tracks[0].fec.blockProfile" },
+    "fec-block-profile-retired.json": { "code": "track_fec_block_profile_unimplemented", "path": "$.tracks[0].fec.blockProfile" },
+    "fec-block-profile-unknown.json": { "code": "track_fec_block_profile_unimplemented", "path": "$.tracks[0].fec.blockProfile" },
+    "fec-enhancement-repair-removed.json": { "code": "track_fec", "path": "$.tracks[0].fec.enhancementRepair" },
+    "fec-repair-layer-geometry.json": { "code": "track_repair_geometry", "path": "$.tracks[2].timescale" },
+    "fec-repair-layer-missing-symbols.json": { "code": "track_repair_layer", "path": "$.tracks[2].repairSymbols" },
+    "fec-repair-multiple-depends.json": { "code": "track_repair_depends", "path": "$.tracks[2].depends" },
+    "fec-repair-overlay-with-layer.json": { "code": "track_repair_overlay", "path": "$.tracks[2].repairLayer" },
+    "fec-repair-priority-out-of-band.json": { "code": "track_repair_priority", "path": "$.tracks[1].priority" },
+    "fec-repair-source-symbols-without-scope.json": { "code": "track_repair_overlay", "path": "$.tracks[2].sourceSymbols" },
+    "legacy-selection-params.json": { "outOfSection": "common track field selectionParams" },
+    "media-track-repair-layer.json": { "code": "track_repair_layer", "path": "$.tracks[0].repairLayer" },
+    "missing-mmtp-fields.json": { "code": "track_mmtp_mode", "path": "$.tracks[0].mmtpMode" },
+    "multicast-auth-padded-key.json": { "outOfSection": "multicast.auth" },
+    "multicast-auth-reused-track-format.json": { "outOfSection": "multicast.auth" },
+    "multicast-auth-trailing-pad-bits.json": { "outOfSection": "multicast.auth" },
+    "multicast-endpoint-missing-protocol-and-source.json": { "outOfSection": "multicast" },
+    "multicast-endpoint-relay-address.json": { "outOfSection": "multicast" },
+    "multicast-network-source-empty.json": { "outOfSection": "multicast" },
+    "multicast-packet-id-signaling.json": { "outOfSection": "multicast" },
+    "network-source-object.json": { "outOfSection": "multicast" },
+    "raptorq-source-symbols-over-max.json": { "code": "track_fec_bounds", "path": "$.tracks[0].fec.sourceSymbols" },
+    "raptorq-unaligned-symbol.json": { "code": "track_fec", "path": "$.tracks[0].fec.symbolSize" },
+    "repair-track-legacy-shape.json": { "outOfSection": "the packaging value set (common track field)" },
+    "track-role-empty.json": { "outOfSection": "common track field trackRole" },
+    "track-role-non-string.json": { "outOfSection": "common track field trackRole" }
+  }
+}