@blockcast/mmt-container 0.1.0 → 0.3.0-main.d9354616fdf2

package/test-vectors/align.json

@@ -0,0 +1,199 @@
+{
+  "$comment": [
+    "Cross-language test vectors for group alignment and MMTP subgroup keys.",
+    "",
+    "Every sibling implementation (Go cmd/caddy/sender/group_align.go,",
+    "Rust apps/relay/src/server/abr.rs, TS packages/container/src/align.ts)",
+    "loads this file and asserts its own groupId/driftCheck output matches.",
+    "Any formula change in any language that drifts from this fixture must",
+    "fail CI.",
+    "",
+    "When adding a vector, prefer values that exercise a boundary (exact",
+    "tick, 1-off, negative, large-int near 2^53, prime divisor) rather",
+    "than arbitrary numbers."
+  ],
+  "version": 1,
+  "group_id": [
+    {
+      "name": "t=0 → 0",
+      "ticks": 0,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 0
+    },
+    {
+      "name": "90kHz, dur=4s: 3.9s before boundary → 0",
+      "ticks": 351000,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 0
+    },
+    {
+      "name": "90kHz, dur=4s: exact boundary at 4s → 1",
+      "ticks": 360000,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 1
+    },
+    {
+      "name": "90kHz, dur=4s: 4s + 1 tick → 1",
+      "ticks": 360001,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 1
+    },
+    {
+      "name": "90kHz, dur=4s: second boundary at 8s → 2",
+      "ticks": 720000,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 2
+    },
+    {
+      "name": "48kHz audio, dur=4s: aligned at 192000 ticks → 1",
+      "ticks": 192000,
+      "group_duration_ticks": 192000,
+      "expected_group_id": 1
+    },
+    {
+      "name": "negative clamps to 0 (base-clamp)",
+      "ticks": -1,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 0
+    },
+    {
+      "name": "large negative clamps to 0 (epoch skew)",
+      "ticks": -9000000,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 0
+    },
+    {
+      "name": "1kHz, dur=2s: 10s → 5",
+      "ticks": 10000,
+      "group_duration_ticks": 2000,
+      "expected_group_id": 5
+    },
+    {
+      "name": "1kHz, dur=2s: 10s + 1 tick → 5 (still in bucket 5)",
+      "ticks": 10001,
+      "group_duration_ticks": 2000,
+      "expected_group_id": 5
+    },
+    {
+      "name": "1kHz, dur=2s: 12s → 6",
+      "ticks": 12000,
+      "group_duration_ticks": 2000,
+      "expected_group_id": 6
+    },
+    {
+      "name": "prime divisor (dur=7): ticks=13 → 1",
+      "ticks": 13,
+      "group_duration_ticks": 7,
+      "expected_group_id": 1
+    },
+    {
+      "name": "prime divisor (dur=7): ticks=14 → 2 (exact boundary)",
+      "ticks": 14,
+      "group_duration_ticks": 7,
+      "expected_group_id": 2
+    },
+    {
+      "name": "prime divisor (dur=7): ticks=15 → 2",
+      "ticks": 15,
+      "group_duration_ticks": 7,
+      "expected_group_id": 2
+    },
+    {
+      "name": "large-int (24h @ 90kHz): 7_776_000_000 ticks, dur=4s → 21600",
+      "ticks": 7776000000,
+      "group_duration_ticks": 360000,
+      "expected_group_id": 21600
+    },
+    {
+      "name": "near MAX_SAFE_INTEGER (TS=2^52, dur=2): ticks=2^52 → 2^51",
+      "ticks": 4503599627370496,
+      "group_duration_ticks": 2,
+      "expected_group_id": 2251799813685248
+    }
+  ],
+  "drift": [
+    {
+      "name": "aligned",
+      "expected": 5,
+      "actual": 5,
+      "expected_kind": "aligned",
+      "expected_delta_groups": 0
+    },
+    {
+      "name": "ahead by 1",
+      "expected": 5,
+      "actual": 6,
+      "expected_kind": "drifted",
+      "expected_delta_groups": 1
+    },
+    {
+      "name": "behind by 2",
+      "expected": 5,
+      "actual": 3,
+      "expected_kind": "drifted",
+      "expected_delta_groups": -2
+    },
+    {
+      "name": "large gap",
+      "expected": 100,
+      "actual": 142,
+      "expected_kind": "drifted",
+      "expected_delta_groups": 42
+    },
+    {
+      "name": "zero-zero aligned (off-by-one hot spot)",
+      "expected": 0,
+      "actual": 0,
+      "expected_kind": "aligned",
+      "expected_delta_groups": 0
+    },
+    {
+      "name": "large negative delta",
+      "expected": 1000,
+      "actual": 5,
+      "expected_kind": "drifted",
+      "expected_delta_groups": -995
+    }
+  ],
+  "subgroup_key": [
+    {
+      "name": "MPU metadata always uses subgroup 0",
+      "kind": "mpu-metadata",
+      "expected_subgroup": 0,
+      "expected_key": "metadata:0"
+    },
+    {
+      "name": "timed MFU key keeps movie fragment and sample coordinates",
+      "kind": "timed",
+      "movie_fragment_sequence_number": 7,
+      "sample_number": 19,
+      "expected_key": "timed:7:19"
+    },
+    {
+      "name": "timed MFU key does not alias the next movie fragment",
+      "kind": "timed",
+      "movie_fragment_sequence_number": 8,
+      "sample_number": 1,
+      "expected_key": "timed:8:1"
+    },
+    {
+      "name": "timed MFU preserves maximum uint32 coordinates",
+      "kind": "timed",
+      "movie_fragment_sequence_number": 4294967295,
+      "sample_number": 4294967295,
+      "expected_key": "timed:4294967295:4294967295"
+    },
+    {
+      "name": "non-timed MFU key is Item_ID",
+      "kind": "non-timed",
+      "item_id": 42,
+      "expected_key": "non-timed:42"
+    },
+    {
+      "name": "non-timed MFU preserves maximum uint32 Item_ID",
+      "kind": "non-timed",
+      "item_id": 4294967295,
+      "expected_key": "non-timed:4294967295"
+    }
+  ]
+}

package/test-vectors/catalog/README.md

@@ -0,0 +1,106 @@
+# Golden MMTP catalog fixtures
+
+These files define the strict catalog shape emitted by new publishers. The
+catalog itself is delivered on a MoQ track whose track name is exactly
+`catalog`; aliases such as `catalog.json` and `.catalog` are not conformant.
+
+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:
+
+- `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-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"`.
+- `fec-enhancement-repair-removed.json`: `fec.enhancementRepair` does not exist;
+  repair layers are self-describing `fec-repair` tracks.
+- `fec-repair-*.json`: a repair layer or overlay declares `depends` (exactly one
+  source), `repairSymbols`, and a `priority` in 192..255; an overlay declares
+  `scope: "keyframe"` plus `sourceSymbols` and never a `repairLayer`; a repair
+  track carries no block geometry.
+- `media-track-repair-layer.json`: `repairLayer`, `repairSymbols`, `sourceSymbols`,
+  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.
+- `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.
+- `archive-unknown-field.json`: the `archive` block is closed; a second spelling
+  of the origin under another key is rejected, not ignored.
+
+`archive` is optional and `positive/flat-av.json` carries none: absence means
+"no archive advertised", never a default URL. The schema pattern catches the
+coarse shape; the canonical-form rule (one spelling per archive — no trailing
+slash, default port, uppercase, userinfo, or trailing-dot host) lives in the
+runtime validator, which JSON Schema cannot express, so those cases are
+table-driven in `src/catalog-schema.test.ts` rather than golden fixtures.
+`positive/archive-origin.json` declares `namespace` on one track and omits it
+on the other, so both arms of the `/v1/{ns}/{track}/{group}` derivation stay
+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:
+
+- `"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.
+
+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.
+
+`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
+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.
+Switching sets compare `ticks / timescale`, so equal wall-clock durations at
+different timescales are valid.
+
+`multicast-native-ssm-no-network-source.json` is the native-SSM shape: an
+endpoint's `(protocol, sourceAddress, groupAddress, port)` is complete join
+information, so a publisher reachable by native multicast has no alternate
+bearer to describe and omits `networkSource` entirely. `networkSource` describes
+how to reach a group when a direct join is not available — an AMT tunnel or an
+ATSC3 broadcast — and is absent exactly when neither applies. `validate_multicast`
+states the same rule on the Rust side: the field is optional, but a present list
+that is empty is rejected with "networkSource must not be empty when present".
+Optional plus `minItems: 1` is that contract exactly, not a libmmt house style.
+
+`endpoints` stays required (and `minItems: 1`) for the opposite reason: a
+`multicast` block with no endpoint carries no join information at all, so it
+says nothing. The Rust side typing it `Option<Vec<MulticastEndpoint>>` is a
+serde shape, not a looser contract — `validate_multicast` rejects absent and
+empty identically with "endpoints must not be empty", which is the same pair
+this schema rejects via `required` and `minItems`.
+
+`releases/moqcast-native-v16-v1/catalog.json` is copied byte-for-byte from the
+`moqcast-native-v16-v1` release in `Blockcast/hang-mmt-fec`. The adjacent
+archive checksum pins the content-addressed release asset; CI downloads that
+asset from the byte-identical `libmmt` consumer mirror, checks the archive
+digest, and compares the extracted catalog bytes to the committed fixture. The
+fixture is retained byte-identical as the record of what v1 shipped and is now
+expected to **fail** validation: its two repair tracks declare the retired
+`packaging: "condensed"`, which is not a catalog packaging value, and its two
+FEC sources predate the required `fec.blockProfile`. The condensed
+FEC repair format itself is unaffected — a catalog declares it as
+`packaging: "fec-repair"` plus `fec.repairContainer`.

package/test-vectors/catalog/negative/archive-origin-with-path.json

@@ -0,0 +1,33 @@
+{
+  "version": 1,
+  "streamingFormat": "mmtp",
+  "streamingFormatVersion": "draft-ramadan-moq-mmt-00",
+  "tracks": [
+    {
+      "name": "video",
+      "packaging": "mmtp",
+      "isLive": true,
+      "codec": "avc1.640028",
+      "framerate": 30,
+      "width": 1920,
+      "height": 1080,
+      "mmtpMode": "mfu",
+      "timescale": 90000,
+      "groupDurationMs": 1000
+    },
+    {
+      "name": "audio",
+      "packaging": "mmtp",
+      "isLive": true,
+      "codec": "mp4a.40.2",
+      "samplerate": 48000,
+      "channelConfig": "2",
+      "mmtpMode": "mfu",
+      "timescale": 48000,
+      "groupDurationMs": 1000
+    }
+  ],
+  "archive": {
+    "origin": "https://archive.example.net/v1"
+  }
+}

package/test-vectors/catalog/negative/archive-unknown-field.json

@@ -0,0 +1,34 @@
+{
+  "version": 1,
+  "streamingFormat": "mmtp",
+  "streamingFormatVersion": "draft-ramadan-moq-mmt-00",
+  "tracks": [
+    {
+      "name": "video",
+      "packaging": "mmtp",
+      "isLive": true,
+      "codec": "avc1.640028",
+      "framerate": 30,
+      "width": 1920,
+      "height": 1080,
+      "mmtpMode": "mfu",
+      "timescale": 90000,
+      "groupDurationMs": 1000
+    },
+    {
+      "name": "audio",
+      "packaging": "mmtp",
+      "isLive": true,
+      "codec": "mp4a.40.2",
+      "samplerate": 48000,
+      "channelConfig": "2",
+      "mmtpMode": "mfu",
+      "timescale": 48000,
+      "groupDurationMs": 1000
+    }
+  ],
+  "archive": {
+    "origin": "https://archive.example.net",
+    "baseUrl": "https://archive.example.net"
+  }
+}

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

@@ -0,0 +1,51 @@
+{
+  "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",
+        "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-block-profile-unknown.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": "iso-ssbg1",
+        "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

@@ -0,0 +1,28 @@
+{
+  "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": 64,
+        "repairSymbols": 8,
+        "symbolSize": 1312,
+        "repairTrack": "video/repair",
+        "enhancementRepair": [
+          { "repairTrack": "video/repair/1", "repairSymbols": 16 }
+        ]
+      }
+    },
+    { "name": "video/repair", "packaging": "fec-repair", "priority": 240 },
+    { "name": "video/repair/1", "packaging": "fec-repair", "priority": 240 }
+  ]
+}

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

@@ -0,0 +1,33 @@
+{
+  "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": 64,
+        "repairSymbols": 8,
+        "symbolSize": 1312,
+        "repairTrack": "video/repair"
+      }
+    },
+    { "name": "video/repair", "packaging": "fec-repair", "priority": 240 },
+    {
+      "name": "video/repair/1",
+      "packaging": "fec-repair",
+      "depends": ["video"],
+      "repairLayer": 1,
+      "repairSymbols": 16,
+      "priority": 244,
+      "timescale": 90000
+    }
+  ]
+}

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

@@ -0,0 +1,31 @@
+{
+  "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": 64,
+        "repairSymbols": 8,
+        "symbolSize": 1312,
+        "repairTrack": "video/repair"
+      }
+    },
+    { "name": "video/repair", "packaging": "fec-repair", "priority": 240 },
+    {
+      "name": "video/repair/1",
+      "packaging": "fec-repair",
+      "depends": ["video"],
+      "repairLayer": 1,
+      "priority": 244
+    }
+  ]
+}

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

@@ -0,0 +1,32 @@
+{
+  "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": 64,
+        "repairSymbols": 8,
+        "symbolSize": 1312,
+        "repairTrack": "video/repair"
+      }
+    },
+    { "name": "video/repair", "packaging": "fec-repair", "priority": 240 },
+    {
+      "name": "video/repair/1",
+      "packaging": "fec-repair",
+      "depends": ["video", "audio"],
+      "repairLayer": 1,
+      "repairSymbols": 16,
+      "priority": 244
+    }
+  ]
+}

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

@@ -0,0 +1,34 @@
+{
+  "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": 64,
+        "repairSymbols": 8,
+        "symbolSize": 1312,
+        "repairTrack": "video/repair"
+      }
+    },
+    { "name": "video/repair", "packaging": "fec-repair", "priority": 240 },
+    {
+      "name": "video/keyframe-repair",
+      "packaging": "fec-repair",
+      "depends": ["video"],
+      "scope": "keyframe",
+      "repairLayer": 1,
+      "sourceSymbols": 256,
+      "repairSymbols": 32,
+      "priority": 242
+    }
+  ]
+}

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

@@ -0,0 +1,24 @@
+{
+  "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": 64,
+        "repairSymbols": 8,
+        "symbolSize": 1312,
+        "repairTrack": "video/repair"
+      }
+    },
+    { "name": "video/repair", "packaging": "fec-repair", "priority": 100 }
+  ]
+}