@blockcast/mmt-container 0.3.0 → 0.4.0-main.71d61b2a53f2

package/test-vectors/catalog-timing.json

@@ -0,0 +1,356 @@
+{
+  "$comment": [
+    "Canonical receiver vectors for catalog-derived FEC timing (BLO-45476).",
+    "Hand-authored; expect null = undefined, expect 'throws' = the value cannot be derived and must fail closed.",
+    "keyframeCadence, mediaUnitsPerSecond and groupDuration pin the neutral catalog rules native receiver adapters share (catalogKeyframeCadenceMs, catalogFecMediaUnitsPerSecond, catalogGroupDurationMs). They are NOT what libmmt's own receiver runs today: resolveCatalogTrackFec reads audio rate from sampleRate ?? samplerate (numeric strings admitted) with no endpoint or timescale fallback, so 'audio MP4-shaped timescale' resolves no rate there; computeBlockClassifierGeometry reads only keyframeInterval*. Converging those is a behaviour change, not part of this extraction.",
+    "deliveryWindow and trackFec run against libmmt's production paths (computeFecDeliveryWindowMs, resolveCatalogTrackFec), so an adapter that drops a catalog field (fec.reorderToleranceMs, say) fails here instead of in the field. An iso-ssbg1-v1 span that is 0 or absent keeps in-band geometry but supplies no elapsed-time deadline; local receiver retention remains bounded without inventing a catalog span.",
+    "interleaveDepth: every row names its D basis. 'access-unit' is what libmmt's receiver and the current publisher run today (D = round(span / (1000/framerate)), multicast-manager FecBlockMapper, fec-manager, block-policy); an adapter must match it to agree with them on block geometry. 'group' is draft-ramadan-moq-fec \u00a75.1/\u00a79 (D over the MoQ group duration); it is the target, not live, and moves only together with the producer contract (BLO-35597). Tick-only groupDurationTicks is authoritative for the group duration."
+  ],
+  "keyframeCadence": [
+    {
+      "name": "interval ticks win over every ms field",
+      "rendition": {
+        "timescale": 90000,
+        "keyframeIntervalTicks": 180000,
+        "keyframeIntervalMs": 1000,
+        "gopDurationMs": 500
+      },
+      "expect": 2000
+    },
+    {
+      "name": "ticks without a timescale fall through to ms",
+      "rendition": {
+        "keyframeIntervalTicks": 180000,
+        "keyframeIntervalMs": 1000
+      },
+      "expect": 1000
+    },
+    {
+      "name": "keyframe duration before GOP duration",
+      "rendition": {
+        "keyframeDurationMs": 1500,
+        "gopDurationMs": 500
+      },
+      "expect": 1500
+    },
+    {
+      "name": "GOP ticks",
+      "rendition": {
+        "timescale": 1000,
+        "gopDurationTicks": 2002
+      },
+      "expect": 2002
+    },
+    {
+      "name": "a group duration is not a keyframe cadence",
+      "rendition": {
+        "timescale": 90000,
+        "groupDurationTicks": 90000,
+        "groupDurationMs": 1000
+      },
+      "expect": null
+    },
+    {
+      "name": "non-positive values are not stated",
+      "rendition": {
+        "keyframeIntervalMs": 0,
+        "gopDurationMs": -1
+      },
+      "expect": null
+    }
+  ],
+  "mediaUnitsPerSecond": [
+    {
+      "name": "video framerate",
+      "type": "video",
+      "rendition": {
+        "framerate": 30,
+        "timescale": 90000
+      },
+      "expect": 30
+    },
+    {
+      "name": "video never reads its timescale",
+      "type": "video",
+      "rendition": {
+        "timescale": 90000
+      },
+      "expect": null
+    },
+    {
+      "name": "audio endpoint rate first",
+      "type": "audio",
+      "rendition": {
+        "sampleRate": 44100
+      },
+      "endpointSampleRate": 48000,
+      "expect": 46.875
+    },
+    {
+      "name": "audio catalog sampleRate",
+      "type": "audio",
+      "rendition": {
+        "sampleRate": 44100,
+        "timescale": 48000
+      },
+      "expect": 43.06640625
+    },
+    {
+      "name": "audio MP4-shaped timescale",
+      "type": "audio",
+      "rendition": {
+        "timescale": 48000
+      },
+      "expect": 46.875
+    },
+    {
+      "name": "a declared but unusable rate is not replaced",
+      "type": "audio",
+      "rendition": {
+        "sampleRate": 0,
+        "timescale": 48000
+      },
+      "expect": null
+    }
+  ],
+  "deliveryWindow": [
+    {
+      "name": "span plus the signaled reorder tolerance",
+      "fec": {
+        "interleaveDepthMs": 133,
+        "sourceSymbols": 32,
+        "reorderToleranceMs": 40
+      },
+      "expect": 173
+    },
+    {
+      "name": "fractional sum rounds up",
+      "fec": {
+        "interleaveDepthMs": 66.7,
+        "sourceSymbols": 8,
+        "reorderToleranceMs": 10.1
+      },
+      "expect": 77
+    },
+    {
+      "name": "a declared 0 tolerance adds nothing",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "sourceSymbols": 8,
+        "reorderToleranceMs": 0
+      },
+      "expect": 100
+    },
+    {
+      "name": "absent tolerance stays absent",
+      "fec": {
+        "interleaveDepthMs": 100.2,
+        "sourceSymbols": 8
+      },
+      "expect": 101
+    },
+    {
+      "name": "K and P never widen the span",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "sourceSymbols": 512,
+        "repairSymbols": 512,
+        "reorderToleranceMs": 20
+      },
+      "expect": 120
+    },
+    {
+      "name": "no span fails closed",
+      "fec": {
+        "sourceSymbols": 8,
+        "reorderToleranceMs": 20
+      },
+      "expect": "throws"
+    },
+    {
+      "name": "no K fails closed",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "reorderToleranceMs": 20
+      },
+      "expect": "throws"
+    },
+    {
+      "name": "negative tolerance fails closed",
+      "fec": {
+        "interleaveDepthMs": 100,
+        "sourceSymbols": 8,
+        "reorderToleranceMs": -1
+      },
+      "expect": "throws"
+    }
+  ],
+  "groupDuration": [
+    {
+      "name": "tick-only group duration is authoritative",
+      "rendition": {
+        "timescale": 90000,
+        "groupDurationTicks": 90000
+      },
+      "expect": 1000
+    },
+    {
+      "name": "ticks win over a disagreeing ms field",
+      "rendition": {
+        "timescale": 90000,
+        "groupDurationTicks": 180000,
+        "groupDurationMs": 1000
+      },
+      "expect": 2000
+    },
+    {
+      "name": "ms-only group duration",
+      "rendition": {
+        "groupDurationMs": 1001
+      },
+      "expect": 1001
+    },
+    {
+      "name": "ticks without a timescale fall through to ms",
+      "rendition": {
+        "groupDurationTicks": 90000,
+        "groupDurationMs": 1000
+      },
+      "expect": 1000
+    },
+    {
+      "name": "nothing stated",
+      "rendition": {
+        "timescale": 90000
+      },
+      "expect": null
+    }
+  ],
+  "interleaveDepth": [
+    {
+      "name": "live basis: 30 fps access units, span 4000 ms -> D=120",
+      "basis": "access-unit",
+      "interleaveDepthMs": 4000,
+      "framerate": 30,
+      "expect": 120
+    },
+    {
+      "name": "draft basis: same stream over the 1000 ms group -> D=4 (target, BLO-35597)",
+      "basis": "group",
+      "interleaveDepthMs": 4000,
+      "groupDurationMs": 1000,
+      "expect": 4
+    },
+    {
+      "name": "NTSC group is exact (4004/1001 = 4)",
+      "basis": "group",
+      "interleaveDepthMs": 4004,
+      "groupDurationMs": 1001,
+      "expect": 4
+    },
+    {
+      "name": "exact half rounds up",
+      "basis": "group",
+      "interleaveDepthMs": 4500,
+      "groupDurationMs": 1000,
+      "expect": 5
+    },
+    {
+      "name": "just below half rounds down",
+      "basis": "group",
+      "interleaveDepthMs": 4499,
+      "groupDurationMs": 1000,
+      "expect": 4
+    },
+    {
+      "name": "zero span fails closed",
+      "basis": "group",
+      "interleaveDepthMs": 0,
+      "groupDurationMs": 1000,
+      "expect": "throws"
+    }
+  ],
+  "trackFec": [
+    {
+      "name": "positive span keeps FEC",
+      "fec": {
+        "interleaveDepthMs": 4000
+      },
+      "expect": {
+        "interleaveMs": 4000,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "zero span: in-band FEC stays active without a deadline",
+      "fec": {
+        "interleaveDepthMs": 0
+      },
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "absent span: in-band FEC stays active without a default",
+      "fec": {},
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "one millisecond is a valid positive span",
+      "fec": {
+        "interleaveDepthMs": 1
+      },
+      "expect": {
+        "interleaveMs": 1,
+        "unavailable": null
+      }
+    },
+    {
+      "name": "negative span fails closed",
+      "fec": {
+        "interleaveDepthMs": -1
+      },
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": "track_fec"
+      }
+    },
+    {
+      "name": "fractional span fails closed",
+      "fec": {
+        "interleaveDepthMs": 1.5
+      },
+      "expect": {
+        "interleaveMs": 0,
+        "unavailable": "track_fec"
+      }
+    },
+    {
+      "name": "absent reorder tolerance stays absent",
+      "fec": {
+        "interleaveDepthMs": 4000
+      },
+      "expect": {
+        "interleaveMs": 4000,
+        "unavailable": null,
+        "reorderToleranceMs": null
+      }
+    },
+    {
+      "name": "explicit zero reorder tolerance is kept",
+      "fec": {
+        "interleaveDepthMs": 4000,
+        "reorderToleranceMs": 0
+      },
+      "expect": {
+        "interleaveMs": 4000,
+        "unavailable": null,
+        "reorderToleranceMs": 0
+      }
+    }
+  ]
+}

package/test-vectors/catalog-validation.json

@@ -21,7 +21,7 @@
             "groupDurationTicks": 360000,
             "fec": {
               "algorithm": "raptorq",
-              "blockProfile": "k-padded-v1",
+              "blockProfile": "iso-ssbg1-v1",
               "sourceSymbols": 32,
               "repairSymbols": 8,
               "symbolSize": 1320,
@@ -182,7 +182,7 @@
             "groupDurationMs": 4000,
             "fec": {
               "algorithm": "raptorq",
-              "blockProfile": "k-padded-v1",
+              "blockProfile": "iso-ssbg1-v1",
               "sourceSymbols": 32
             }
           }
@@ -247,7 +247,7 @@
     {
       "name": "unknown FEC block profile",
       "valid": false,
-      "error_code": "track_fec_block_profile",
+      "error_code": "track_fec_block_profile_unimplemented",
       "catalog": {
         "version": 1,
         "tracks": [
@@ -279,6 +279,41 @@
         ]
       }
     },
+    {
+      "name": "retired k-padded-v1 block profile",
+      "valid": false,
+      "error_code": "track_fec_block_profile_unimplemented",
+      "catalog": {
+        "version": 1,
+        "tracks": [
+          {
+            "name": "video",
+            "packaging": "mmtp",
+            "isLive": true,
+            "codec": "avc1.640028",
+            "mmtpMode": "mfu",
+            "timescale": 90000,
+            "groupDurationMs": 4000,
+            "groupDurationTicks": 360000,
+            "fec": {
+              "algorithm": "raptorq",
+              "blockProfile": "k-padded-v1",
+              "sourceSymbols": 32,
+              "repairSymbols": 8,
+              "symbolSize": 1320,
+              "interleaveDepthMs": 133,
+              "repairTrack": "video/repair"
+            }
+          },
+          {
+            "name": "video/repair",
+            "packaging": "fec-repair",
+            "isLive": true,
+            "priority": 240
+          }
+        ]
+      }
+    },
     {
       "name": "ISO ssbg_mode1 block profile",
       "valid": true,
@@ -316,7 +351,7 @@
     {
       "name": "disabled FEC with an unknown block profile",
       "valid": false,
-      "error_code": "track_fec_block_profile",
+      "error_code": "track_fec_block_profile_unimplemented",
       "catalog": {
         "version": 1,
         "tracks": [
@@ -435,7 +470,7 @@
             "groupDurationMs": 1000,
             "fec": {
               "algorithm": "raptorq",
-              "blockProfile": "k-padded-v1",
+              "blockProfile": "iso-ssbg1-v1",
               "sourceSymbols": 32,
               "repairSymbols": 8,
               "symbolSize": 1320,

package/test-vectors/delivery-catalog/README.md

@@ -0,0 +1,11 @@
+# Delivery-catalog vectors
+
+Hand-authored v2 delivery catalogs for `normalizeDeliveryCatalog`
+(`src/delivery-catalog.ts`). `positive/` must normalize; each `negative/` file
+is `{ "error": <regex>, "catalog": <catalog> }` and must throw a matching error.
+Do not regenerate these from the implementation under test.
+
+- `missing-block-profile` / `retired-k-padded-block-profile`: `fec.blockProfile`
+  is required, never defaulted, and must be `iso-ssbg1-v1` (BLO-35597, #518).
+- `packet-id-signaling`: `mmtp.packetId` 0 is the MMTP signaling flow, never a
+  track (`isMulticastTrackPacketId`).

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

@@ -0,0 +1,58 @@
+{
+  "error": "fec\\.blockProfile is required",
+  "catalog": {
+    "schemaVersion": 2,
+    "channelId": "live-main",
+    "multicast": {
+      "packaging": "dash",
+      "endpoints": {
+        "video-a": {
+          "source": "2001:db8::10",
+          "group": "ff3e::101",
+          "port": 5001
+        }
+      },
+      "deliveryPolicy": {
+        "bufferWindowSegments": 8,
+        "requestTimeoutMs": 1500,
+        "missPolicy": "fail"
+      },
+      "dash": {
+        "manifestUrl": "https://origin.example/live/main.mpd",
+        "routes": [
+          {
+            "id": "video-1080",
+            "contentType": "video",
+            "endpointRef": "video-a",
+            "representationId": "v1080",
+            "initUri": "https://origin.example/video-1080/init.mp4",
+            "mediaUriTemplate": "https://origin.example/video-1080/seg-$Number$.m4s",
+            "objects": {
+              "namespace": "live/video-1080",
+              "initObject": "init",
+              "mediaObjectTemplate": "seg-$Number$"
+            },
+            "fec": {
+              "K": 20,
+              "P": 4,
+              "T": 1200,
+              "interleaveDepthMs": 133
+            },
+            "mmtp": {
+              "trackName": "video-1080",
+              "packetId": 101,
+              "mode": "mfu",
+              "codec": "avc1.640028",
+              "timescale": 90000,
+              "mediaUnitDurationTicks": 3000,
+              "mediaUnitsPerObject": 30,
+              "firstMpuSequenceNumber": 1,
+              "firstObjectNumber": 1,
+              "mpuSequencesPerObject": 1
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/test-vectors/delivery-catalog/negative/packet-id-signaling.json

@@ -0,0 +1,59 @@
+{
+  "error": "mmtp\\.packetId must be an integer from 1 to 65535",
+  "catalog": {
+    "schemaVersion": 2,
+    "channelId": "live-main",
+    "multicast": {
+      "packaging": "dash",
+      "endpoints": {
+        "video-a": {
+          "source": "2001:db8::10",
+          "group": "ff3e::101",
+          "port": 5001
+        }
+      },
+      "deliveryPolicy": {
+        "bufferWindowSegments": 8,
+        "requestTimeoutMs": 1500,
+        "missPolicy": "fail"
+      },
+      "dash": {
+        "manifestUrl": "https://origin.example/live/main.mpd",
+        "routes": [
+          {
+            "id": "video-1080",
+            "contentType": "video",
+            "endpointRef": "video-a",
+            "representationId": "v1080",
+            "initUri": "https://origin.example/video-1080/init.mp4",
+            "mediaUriTemplate": "https://origin.example/video-1080/seg-$Number$.m4s",
+            "objects": {
+              "namespace": "live/video-1080",
+              "initObject": "init",
+              "mediaObjectTemplate": "seg-$Number$"
+            },
+            "fec": {
+              "K": 20,
+              "P": 4,
+              "T": 1200,
+              "interleaveDepthMs": 133,
+              "blockProfile": "iso-ssbg1-v1"
+            },
+            "mmtp": {
+              "trackName": "video-1080",
+              "packetId": 0,
+              "mode": "mfu",
+              "codec": "avc1.640028",
+              "timescale": 90000,
+              "mediaUnitDurationTicks": 3000,
+              "mediaUnitsPerObject": 30,
+              "firstMpuSequenceNumber": 1,
+              "firstObjectNumber": 1,
+              "mpuSequencesPerObject": 1
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/test-vectors/delivery-catalog/negative/retired-k-padded-block-profile.json

@@ -0,0 +1,59 @@
+{
+  "error": "fec\\.blockProfile must be \"iso-ssbg1-v1\"",
+  "catalog": {
+    "schemaVersion": 2,
+    "channelId": "live-main",
+    "multicast": {
+      "packaging": "dash",
+      "endpoints": {
+        "video-a": {
+          "source": "2001:db8::10",
+          "group": "ff3e::101",
+          "port": 5001
+        }
+      },
+      "deliveryPolicy": {
+        "bufferWindowSegments": 8,
+        "requestTimeoutMs": 1500,
+        "missPolicy": "fail"
+      },
+      "dash": {
+        "manifestUrl": "https://origin.example/live/main.mpd",
+        "routes": [
+          {
+            "id": "video-1080",
+            "contentType": "video",
+            "endpointRef": "video-a",
+            "representationId": "v1080",
+            "initUri": "https://origin.example/video-1080/init.mp4",
+            "mediaUriTemplate": "https://origin.example/video-1080/seg-$Number$.m4s",
+            "objects": {
+              "namespace": "live/video-1080",
+              "initObject": "init",
+              "mediaObjectTemplate": "seg-$Number$"
+            },
+            "fec": {
+              "K": 20,
+              "P": 4,
+              "T": 1200,
+              "interleaveDepthMs": 133,
+              "blockProfile": "k-padded-v1"
+            },
+            "mmtp": {
+              "trackName": "video-1080",
+              "packetId": 101,
+              "mode": "mfu",
+              "codec": "avc1.640028",
+              "timescale": 90000,
+              "mediaUnitDurationTicks": 3000,
+              "mediaUnitsPerObject": 30,
+              "firstMpuSequenceNumber": 1,
+              "firstObjectNumber": 1,
+              "mpuSequencesPerObject": 1
+            }
+          }
+        ]
+      }
+    }
+  }
+}

package/test-vectors/delivery-catalog/positive/dash.json

@@ -0,0 +1,56 @@
+{
+  "schemaVersion": 2,
+  "channelId": "live-main",
+  "multicast": {
+    "packaging": "dash",
+    "endpoints": {
+      "video-a": {
+        "source": "2001:db8::10",
+        "group": "ff3e::101",
+        "port": 5001
+      }
+    },
+    "deliveryPolicy": {
+      "bufferWindowSegments": 8,
+      "requestTimeoutMs": 1500,
+      "missPolicy": "fail"
+    },
+    "dash": {
+      "manifestUrl": "https://origin.example/live/main.mpd",
+      "routes": [
+        {
+          "id": "video-1080",
+          "contentType": "video",
+          "endpointRef": "video-a",
+          "representationId": "v1080",
+          "initUri": "https://origin.example/video-1080/init.mp4",
+          "mediaUriTemplate": "https://origin.example/video-1080/seg-$Number$.m4s",
+          "objects": {
+            "namespace": "live/video-1080",
+            "initObject": "init",
+            "mediaObjectTemplate": "seg-$Number$"
+          },
+          "fec": {
+            "K": 20,
+            "P": 4,
+            "T": 1200,
+            "interleaveDepthMs": 133,
+            "blockProfile": "iso-ssbg1-v1"
+          },
+          "mmtp": {
+            "trackName": "video-1080",
+            "packetId": 101,
+            "mode": "mfu",
+            "codec": "avc1.640028",
+            "timescale": 90000,
+            "mediaUnitDurationTicks": 3000,
+            "mediaUnitsPerObject": 30,
+            "firstMpuSequenceNumber": 1,
+            "firstObjectNumber": 1,
+            "mpuSequencesPerObject": 1
+          }
+        }
+      ]
+    }
+  }
+}