@blockcast/mmt-base 0.5.0 → 1.0.0-main.3cb7359ea316

package/dist/catalog-fec-source.js

@@ -1,154 +0,0 @@
-/**
- * Catalog FEC source rules shared by every catalog reader (BLO-40851).
- *
- * These are the dialect-level reads the container resolvers
- * (`resolveRepairLayers`, `catalogFecUnavailable`), the transport endpoint
- * selection (`selectEndpointPacketIds`) and a player's repair inventory all
- * need to agree on. They live here, in the leaf package every one of those
- * depends on, so there is one copy of each rule instead of copies pinned
- * against each other by tests.
- *
- * - `locateCatalogFecSource`: which catalog entry declares a source's `fec`
- *   block. hang `video`/`audio` rendition blocks are authoritative over an MSF
- *   `tracks[]` entry of the same name.
- * - `catalogFecAvailable`: draft-ramadan-moq-fec §5.1, whether a block's FEC
- *   is usable at all (implemented `blockProfile`, usable span).
- * - `catalogFecDeclaresUnconfigurableInstance`: a declared FEC instance whose
- *   geometry a decoder cannot configure, which is a malformed catalog rather
- *   than "no FEC".
- *
- * Every function is total: it never throws, whatever the input.
- */
-import { isFecBlockProfile } from './fec-block-profile.js';
-const ALL_ROLES = Object.freeze(['video', 'audio']);
-function recordOf(value) {
-    return value !== null && typeof value === 'object' && !Array.isArray(value)
-        ? value
-        : undefined;
-}
-/**
- * Locate the catalog entry that declares one media source's `fec` block, in
- * either catalog dialect.
- *
- * A hang `video`/`audio` rendition named `source` wins, in `roles` order, over
- * a `tracks[]` entry of the same name: when a catalog carries rendition blocks
- * beside a `tracks[]` switching-set index (the unified ABR ladder catalog),
- * the rendition blocks are authoritative, exactly as they are for hang's own
- * catalog decode. The precedence is keyed on the rendition EXISTING as an
- * object, not on it carrying `fec`: a rendition without `fec` locates with
- * `fec: undefined` and never falls through to `tracks[]`.
- *
- * Otherwise the first `tracks[]` entry named `source` locates. Returns
- * undefined when neither dialect names it, or when `catalog` is not an object.
- *
- * @param roles the hang roles to search, in order (both by default). A typed
- *   track reference passes its own role only.
- */
-export function locateCatalogFecSource(catalog, source, roles = ALL_ROLES) {
-    const root = recordOf(catalog);
-    if (root === undefined)
-        return undefined;
-    for (const role of roles) {
-        const renditions = recordOf(recordOf(root[role])?.['renditions']);
-        if (renditions === undefined || !Object.hasOwn(renditions, source))
-            continue;
-        const entry = recordOf(renditions[source]);
-        if (entry === undefined)
-            continue;
-        return Object.freeze({
-            dialect: 'hang',
-            role,
-            entry,
-            fec: entry['fec'],
-            fecPath: `$.${role}.renditions[${JSON.stringify(source)}].fec`,
-        });
-    }
-    const tracks = root['tracks'];
-    if (!Array.isArray(tracks))
-        return undefined;
-    const index = tracks.findIndex((track) => recordOf(track)?.['name'] === source);
-    if (index < 0)
-        return undefined;
-    const entry = recordOf(tracks[index]) ?? {};
-    return Object.freeze({
-        dialect: 'msf',
-        index,
-        entry,
-        fec: entry['fec'],
-        fecPath: `$.tracks[${index}].fec`,
-    });
-}
-/**
- * Whether an `iso-ssbg1-v1` block's optional `interleaveDepthMs` span is
- * usable: absent, or a non-negative safe integer. Zero or absence supplies no
- * elapsed deadline and still permits in-band FEC. True for every block that
- * names another profile (the span is not read) and for a non-object.
- */
-export function isoBlockSpanUsable(fec) {
-    const block = recordOf(fec);
-    if (block === undefined || block['blockProfile'] !== 'iso-ssbg1-v1')
-        return true;
-    const ms = block['interleaveDepthMs'];
-    return ms === undefined || (typeof ms === 'number' && Number.isSafeInteger(ms) && ms >= 0);
-}
-/**
- * Whether one catalog `fec` block leaves its FEC available
- * (draft-ramadan-moq-fec §5.1): the decision the container's
- * `catalogFecUnavailable` explains with a typed reason.
- *
- * False when the block's `algorithm` is a token this receiver does not
- * implement (`fecAlgorithmUnimplemented`); when it declares an FEC instance
- * (any `algorithm` but `"none"`) and names no implemented `blockProfile` (the retired `k-padded-v1`
- * included), or carries an `iso-ssbg1-v1` span it cannot use; and when a block
- * declaring no FEC instance carries a profile token that is not implemented.
- * True for a non-object and for every other block. It reads only the profile
- * and the span: malformed geometry (`sourceSymbols`, `symbolSize`) is
- * `catalogFecDeclaresUnconfigurableInstance`'s.
- *
- * A receiver applies no FEC to a source whose block is unavailable and joins
- * none of its repair tracks, without failing the session.
- */
-export function catalogFecAvailable(fec) {
-    const block = recordOf(fec);
-    if (block === undefined)
-        return true;
-    if (fecAlgorithmUnimplemented(block['algorithm']))
-        return false;
-    const declaresFecInstance = block['algorithm'] !== 'none';
-    const profile = block['blockProfile'];
-    const profileOk = isFecBlockProfile(profile) || (profile === undefined && !declaresFecInstance);
-    return profileOk && (!declaresFecInstance || isoBlockSpanUsable(block));
-}
-/**
- * Whether `algorithm` is a token this receiver does not implement
- * (draft-ramadan-moq-fec-01 4): any string but `none`, `raptorq` and
- * `reed-solomon`. Such a track is consumed without FEC and its repair tracks
- * are not joined; the catalog is not in error. An absent algorithm is not a
- * token (the hang dialect omits it) and stays implemented.
- */
-export function fecAlgorithmUnimplemented(algorithm) {
-    return typeof algorithm === 'string' && algorithm !== 'none' && algorithm !== 'raptorq' && algorithm !== 'reed-solomon';
-}
-function isPositiveSafeInteger(value) {
-    return typeof value === 'number' && Number.isSafeInteger(value) && value > 0;
-}
-/** Smallest `symbolSize` under `iso-ssbg1-v1` (draft-ramadan-moq-fec-01 5.1, 6.3.4 rule 13). */
-export const ISO_SSBG1_MIN_SYMBOL_SIZE = 14;
-/**
- * Whether a source's `fec` block declares an FEC instance (any `algorithm`
- * but `"none"`) whose `sourceSymbols` or `symbolSize` is not a positive
- * integer, or whose `iso-ssbg1-v1` `symbolSize` is below
- * `ISO_SSBG1_MIN_SYMBOL_SIZE` (rule 13: such a symbol carries no protected
- * MMTP packet). Geometry a decoder cannot configure is a malformed catalog, not
- * "no FEC": the container's per-track resolver throws `track_fec` for exactly
- * this block, whatever its profile or span.
- */
-export function catalogFecDeclaresUnconfigurableInstance(fec) {
-    const block = recordOf(fec);
-    if (block === undefined || block['algorithm'] === 'none' || fecAlgorithmUnimplemented(block['algorithm']))
-        return false;
-    if (!(isPositiveSafeInteger(block['sourceSymbols']) && isPositiveSafeInteger(block['symbolSize'])))
-        return true;
-    return block['blockProfile'] === 'iso-ssbg1-v1' && block['symbolSize'] < ISO_SSBG1_MIN_SYMBOL_SIZE;
-}
-//# sourceMappingURL=catalog-fec-source.js.map

package/dist/catalog-fec-source.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"catalog-fec-source.js","sourceRoot":"","sources":["../src/catalog-fec-source.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAA;AA6B1D,MAAM,SAAS,GAA8B,MAAM,CAAC,MAAM,CAAC,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC,CAAA;AAE9E,SAAS,QAAQ,CAAC,KAAc;IAC9B,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QACzE,CAAC,CAAE,KAAiC;QACpC,CAAC,CAAC,SAAS,CAAA;AACf,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,sBAAsB,CACpC,OAAgB,EAChB,MAAc,EACd,QAAmC,SAAS;IAE5C,MAAM,IAAI,GAAG,QAAQ,CAAC,OAAO,CAAC,CAAA;IAC9B,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IACxC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,UAAU,GAAG,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC,CAAA;QACjE,IAAI,UAAU,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,MAAM,CAAC;YAAE,SAAQ;QAC5E,MAAM,KAAK,GAAG,QAAQ,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,CAAA;QAC1C,IAAI,KAAK,KAAK,SAAS;YAAE,SAAQ;QACjC,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,OAAO,EAAE,MAAe;YACxB,IAAI;YACJ,KAAK;YACL,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC;YACjB,OAAO,EAAE,KAAK,IAAI,eAAe,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,OAAO;SAC/D,CAAC,CAAA;IACJ,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC7B,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,OAAO,SAAS,CAAA;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC,KAAK,MAAM,CAAC,CAAA;IAC/E,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,SAAS,CAAA;IAC/B,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,IAAI,EAAE,CAAA;IAC3C,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,OAAO,EAAE,KAAc;QACvB,KAAK;QACL,KAAK;QACL,GAAG,EAAE,KAAK,CAAC,KAAK,CAAC;QACjB,OAAO,EAAE,YAAY,KAAK,OAAO;KAClC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAY;IAC7C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,cAAc,CAAC,KAAK,cAAc;QAAE,OAAO,IAAI,CAAA;IAChF,MAAM,EAAE,GAAG,KAAK,CAAC,mBAAmB,CAAC,CAAA;IACrC,OAAO,EAAE,KAAK,SAAS,IAAI,CAAC,OAAO,EAAE,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;AAC5F,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,mBAAmB,CAAC,GAAY;IAC9C,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,IAAI,CAAA;IACpC,IAAI,yBAAyB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IAC/D,MAAM,mBAAmB,GAAG,KAAK,CAAC,WAAW,CAAC,KAAK,MAAM,CAAA;IACzD,MAAM,OAAO,GAAG,KAAK,CAAC,cAAc,CAAC,CAAA;IACrC,MAAM,SAAS,GAAG,iBAAiB,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,KAAK,SAAS,IAAI,CAAC,mBAAmB,CAAC,CAAA;IAC/F,OAAO,SAAS,IAAI,CAAC,CAAC,mBAAmB,IAAI,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAA;AACzE,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,yBAAyB,CAAC,SAAkB;IAC1D,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,KAAK,MAAM,IAAI,SAAS,KAAK,SAAS,IAAI,SAAS,KAAK,cAAc,CAAA;AACzH,CAAC;AAED,SAAS,qBAAqB,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,aAAa,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAA;AAC9E,CAAC;AAED,gGAAgG;AAChG,MAAM,CAAC,MAAM,yBAAyB,GAAG,EAAE,CAAA;AAE3C;;;;;;;;GAQG;AACH,MAAM,UAAU,wCAAwC,CAAC,GAAY;IACnE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,WAAW,CAAC,KAAK,MAAM,IAAI,yBAAyB,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;QAAE,OAAO,KAAK,CAAA;IACvH,IAAI,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,eAAe,CAAC,CAAC,IAAI,qBAAqB,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,CAAC;QAAE,OAAO,IAAI,CAAA;IAC/G,OAAO,KAAK,CAAC,cAAc,CAAC,KAAK,cAAc,IAAK,KAAK,CAAC,YAAY,CAAY,GAAG,yBAAyB,CAAA;AAChH,CAAC"}

package/src/catalog-fec-source.ts

@@ -1,183 +0,0 @@
-/**
- * Catalog FEC source rules shared by every catalog reader (BLO-40851).
- *
- * These are the dialect-level reads the container resolvers
- * (`resolveRepairLayers`, `catalogFecUnavailable`), the transport endpoint
- * selection (`selectEndpointPacketIds`) and a player's repair inventory all
- * need to agree on. They live here, in the leaf package every one of those
- * depends on, so there is one copy of each rule instead of copies pinned
- * against each other by tests.
- *
- * - `locateCatalogFecSource`: which catalog entry declares a source's `fec`
- *   block. hang `video`/`audio` rendition blocks are authoritative over an MSF
- *   `tracks[]` entry of the same name.
- * - `catalogFecAvailable`: draft-ramadan-moq-fec §5.1, whether a block's FEC
- *   is usable at all (implemented `blockProfile`, usable span).
- * - `catalogFecDeclaresUnconfigurableInstance`: a declared FEC instance whose
- *   geometry a decoder cannot configure, which is a malformed catalog rather
- *   than "no FEC".
- *
- * Every function is total: it never throws, whatever the input.
- */
-import { isFecBlockProfile } from './fec-block-profile.js'
-
-/** The catalog media roles that carry hang renditions. */
-export type CatalogFecRole = 'video' | 'audio'
-
-/** One media source's `fec` block, as `locateCatalogFecSource` found it. */
-export type CatalogFecSource =
-  | {
-      readonly dialect: 'hang'
-      readonly role: CatalogFecRole
-      /** The rendition object. */
-      readonly entry: Record<string, unknown>
-      /** The rendition's `fec` value, unvalidated (may be undefined). */
-      readonly fec: unknown
-      /** JSON path of that `fec` block. */
-      readonly fecPath: string
-    }
-  | {
-      readonly dialect: 'msf'
-      /** Index of the entry in `tracks[]`. */
-      readonly index: number
-      /** The `tracks[]` entry (an empty object when the entry is not an object). */
-      readonly entry: Record<string, unknown>
-      /** The entry's `fec` value, unvalidated (may be undefined). */
-      readonly fec: unknown
-      /** JSON path of that `fec` block. */
-      readonly fecPath: string
-    }
-
-const ALL_ROLES: readonly CatalogFecRole[] = Object.freeze(['video', 'audio'])
-
-function recordOf(value: unknown): Record<string, unknown> | undefined {
-  return value !== null && typeof value === 'object' && !Array.isArray(value)
-    ? (value as Record<string, unknown>)
-    : undefined
-}
-
-/**
- * Locate the catalog entry that declares one media source's `fec` block, in
- * either catalog dialect.
- *
- * A hang `video`/`audio` rendition named `source` wins, in `roles` order, over
- * a `tracks[]` entry of the same name: when a catalog carries rendition blocks
- * beside a `tracks[]` switching-set index (the unified ABR ladder catalog),
- * the rendition blocks are authoritative, exactly as they are for hang's own
- * catalog decode. The precedence is keyed on the rendition EXISTING as an
- * object, not on it carrying `fec`: a rendition without `fec` locates with
- * `fec: undefined` and never falls through to `tracks[]`.
- *
- * Otherwise the first `tracks[]` entry named `source` locates. Returns
- * undefined when neither dialect names it, or when `catalog` is not an object.
- *
- * @param roles the hang roles to search, in order (both by default). A typed
- *   track reference passes its own role only.
- */
-export function locateCatalogFecSource(
-  catalog: unknown,
-  source: string,
-  roles: readonly CatalogFecRole[] = ALL_ROLES,
-): CatalogFecSource | undefined {
-  const root = recordOf(catalog)
-  if (root === undefined) return undefined
-  for (const role of roles) {
-    const renditions = recordOf(recordOf(root[role])?.['renditions'])
-    if (renditions === undefined || !Object.hasOwn(renditions, source)) continue
-    const entry = recordOf(renditions[source])
-    if (entry === undefined) continue
-    return Object.freeze({
-      dialect: 'hang' as const,
-      role,
-      entry,
-      fec: entry['fec'],
-      fecPath: `$.${role}.renditions[${JSON.stringify(source)}].fec`,
-    })
-  }
-  const tracks = root['tracks']
-  if (!Array.isArray(tracks)) return undefined
-  const index = tracks.findIndex((track) => recordOf(track)?.['name'] === source)
-  if (index < 0) return undefined
-  const entry = recordOf(tracks[index]) ?? {}
-  return Object.freeze({
-    dialect: 'msf' as const,
-    index,
-    entry,
-    fec: entry['fec'],
-    fecPath: `$.tracks[${index}].fec`,
-  })
-}
-
-/**
- * Whether an `iso-ssbg1-v1` block's optional `interleaveDepthMs` span is
- * usable: absent, or a non-negative safe integer. Zero or absence supplies no
- * elapsed deadline and still permits in-band FEC. True for every block that
- * names another profile (the span is not read) and for a non-object.
- */
-export function isoBlockSpanUsable(fec: unknown): boolean {
-  const block = recordOf(fec)
-  if (block === undefined || block['blockProfile'] !== 'iso-ssbg1-v1') return true
-  const ms = block['interleaveDepthMs']
-  return ms === undefined || (typeof ms === 'number' && Number.isSafeInteger(ms) && ms >= 0)
-}
-
-/**
- * Whether one catalog `fec` block leaves its FEC available
- * (draft-ramadan-moq-fec §5.1): the decision the container's
- * `catalogFecUnavailable` explains with a typed reason.
- *
- * False when the block's `algorithm` is a token this receiver does not
- * implement (`fecAlgorithmUnimplemented`); when it declares an FEC instance
- * (any `algorithm` but `"none"`) and names no implemented `blockProfile` (the retired `k-padded-v1`
- * included), or carries an `iso-ssbg1-v1` span it cannot use; and when a block
- * declaring no FEC instance carries a profile token that is not implemented.
- * True for a non-object and for every other block. It reads only the profile
- * and the span: malformed geometry (`sourceSymbols`, `symbolSize`) is
- * `catalogFecDeclaresUnconfigurableInstance`'s.
- *
- * A receiver applies no FEC to a source whose block is unavailable and joins
- * none of its repair tracks, without failing the session.
- */
-export function catalogFecAvailable(fec: unknown): boolean {
-  const block = recordOf(fec)
-  if (block === undefined) return true
-  if (fecAlgorithmUnimplemented(block['algorithm'])) return false
-  const declaresFecInstance = block['algorithm'] !== 'none'
-  const profile = block['blockProfile']
-  const profileOk = isFecBlockProfile(profile) || (profile === undefined && !declaresFecInstance)
-  return profileOk && (!declaresFecInstance || isoBlockSpanUsable(block))
-}
-
-/**
- * Whether `algorithm` is a token this receiver does not implement
- * (draft-ramadan-moq-fec-01 4): any string but `none`, `raptorq` and
- * `reed-solomon`. Such a track is consumed without FEC and its repair tracks
- * are not joined; the catalog is not in error. An absent algorithm is not a
- * token (the hang dialect omits it) and stays implemented.
- */
-export function fecAlgorithmUnimplemented(algorithm: unknown): boolean {
-  return typeof algorithm === 'string' && algorithm !== 'none' && algorithm !== 'raptorq' && algorithm !== 'reed-solomon'
-}
-
-function isPositiveSafeInteger(value: unknown): boolean {
-  return typeof value === 'number' && Number.isSafeInteger(value) && value > 0
-}
-
-/** Smallest `symbolSize` under `iso-ssbg1-v1` (draft-ramadan-moq-fec-01 5.1, 6.3.4 rule 13). */
-export const ISO_SSBG1_MIN_SYMBOL_SIZE = 14
-
-/**
- * Whether a source's `fec` block declares an FEC instance (any `algorithm`
- * but `"none"`) whose `sourceSymbols` or `symbolSize` is not a positive
- * integer, or whose `iso-ssbg1-v1` `symbolSize` is below
- * `ISO_SSBG1_MIN_SYMBOL_SIZE` (rule 13: such a symbol carries no protected
- * MMTP packet). Geometry a decoder cannot configure is a malformed catalog, not
- * "no FEC": the container's per-track resolver throws `track_fec` for exactly
- * this block, whatever its profile or span.
- */
-export function catalogFecDeclaresUnconfigurableInstance(fec: unknown): boolean {
-  const block = recordOf(fec)
-  if (block === undefined || block['algorithm'] === 'none' || fecAlgorithmUnimplemented(block['algorithm'])) return false
-  if (!(isPositiveSafeInteger(block['sourceSymbols']) && isPositiveSafeInteger(block['symbolSize']))) return true
-  return block['blockProfile'] === 'iso-ssbg1-v1' && (block['symbolSize'] as number) < ISO_SSBG1_MIN_SYMBOL_SIZE
-}