@blockcast/mmt-container 0.1.0-main.cf0df54ddcf4 → 0.1.0-main.d0bb31684c09

package/README.md

@@ -117,7 +117,7 @@ function parseMPUHeader(buf: Uint8Array, offset: number): MPUHeader
 function extractMFUPayload(packet: Uint8Array): MFUExtraction | null
 function extractFecPayloadId(packet: Uint8Array): { ssId: number } | null
 function extractRepairFecPayloadId(packet: Uint8Array): RepairFecId | null
-function parseAlFecMessage(buf: Uint8Array): AlFecConfig
+function parseAlFecMessage(buf: Uint8Array): AlFecMessage | null   // every FEC flow (Table C.3, Amd 1:2025)
 function parseMoqRepairFrame(buf: Uint8Array): MoqRepairFrame
 ```
 
@@ -192,14 +192,21 @@ interface FecCatalogConfig {
 }
 
 interface MulticastEndpoint {
-  protocol: "ssm" | "asm" | "amt"
+  protocol: "ssm" | "asm" | "amt" | "atsc3"
   sourceAddress?: string         // REQUIRED for SSM
   groupAddress: string
   port: number
   tracks: string[]
-  relayAddress?: string          // REQUIRED for AMT
+  // relayAddress?: string — deprecated, read-only (see Breaking, below)
 }
 
+// Relay/tuning discovery is catalog-level, not per-endpoint:
+//   multicast.networkSource: [{ type: "amt", discovery: "driad" | "manual",
+//                               relay?: string, port?: number }]
+// `relay` is REQUIRED for discovery: "manual"; "driad" resolves it at runtime.
+// An endpoint-level `relayAddress` is retired — the schema and moq-rs both
+// reject it.
+
 interface TrackTimingConfig {
   groupDurationMs: number          // REQUIRED, positive integer
   groupDurationTicks?: number      // override when ms × timescale isn't integer
@@ -211,6 +218,45 @@ function resolveGroupDurationTicks(timing: TrackTimingConfig, timescale: number)
 function validateSwitchingSetTiming(...): { ok: true } | { ok: false; ... }
 ```
 
+#### Breaking: multicast emitter output (BLO-37834)
+
+`multicastFromConfig` / `multicastFromEnv` no longer emit
+`endpoints[].relayAddress` or `amtFallback`. Both are lifted into catalog-level
+`multicast.networkSource` (`{type: "amt", discovery, relay?}`), and a native
+multicast catalog omits `networkSource` entirely (BLO-37926). A reader that
+still looks for `relayAddress` or `amtFallback` reads `undefined`: read
+`networkSource` instead (`catalogAmtNetworkSource` in `./catalog-network-source`
+resolves a dialable AMT relay from it, skipping `discovery: "driad"` entries
+whose `relay` is a DNS name for a runtime lookup rather than an address), and
+keep accepting `relayAddress` from catalogs published before this change until
+every emitter is on it.
+
+Inputs are unchanged: `relayAddress` and `amtFallback` are still accepted and
+lifted. An input relay that would not survive into the emitted `networkSource`
+(two endpoints with different relays, one overridden by
+`amtFallback.relayDns` or an explicit `networkSource`, or one matched only by a
+`discovery: "driad"` entry, whose relay is a runtime discovery hint) now throws
+`conflicting_amt_relay` instead of being dropped. For that last case — wanting
+DRIAD *and* a named relay — emit both entries, `[{type: "amt", discovery:
+"manual", relay}, {type: "amt", discovery: "driad"}]`: readers join the first
+non-DRIAD AMT entry, so the manual one carries the relay while the DRIAD one
+keeps the discovery request. An `atsc3` endpoint now
+requires a `{type: "atsc3", …}` entry and throws `atsc3_requires_tuning`
+without one: that entry carries the frequency, PLP, service id and SLS URI,
+which is the only tuning information an ATSC3 receiver has, and the schema
+cannot enforce it because `networkSource` is optional there (a native join has
+none). `version`, `validUntil` and `enabled` are still emitted and still
+outside `$defs/multicast` (the BLO-3323 freshness model, tracked separately).
+
+`MulticastInputErrorKind` gains two members, `atsc3_requires_tuning` and
+`invalid_endpoints`. The union is exported, so a consumer that `switch`es on it
+exhaustively needs the two new arms to keep compiling.
+
+The package version stays `0.1.0`: consumers pin a libmmt commit (`file:` or the
+per-commit `0.1.0-main.<sha>` prerelease from `stamp-prerelease.mjs`), and a
+`0.2.0` would fall outside the `^0.1.0` range that siblings such as
+`mmt-render` declare.
+
 #### Track-role convention (Phase 14)
 
 This is **project-specific**, not in any IETF draft yet. The container's switching-set parser derives its internal role from the last `/`-segment of a track name. MMTP catalogs may also carry the publisher-owned `trackRole` dispatch tag; the canonical schema validates it as a non-empty string. `parseTrackRole` remains the name-based helper for base/delta/repair switching sets (`carp-catalog.ts:41-79`):