@blockcast/mmt-transport 0.2.2 → 0.3.0

package/dist/moqt-priority.d.ts

@@ -0,0 +1,39 @@
+declare const subscriberPriorityBrand: unique symbol;
+declare const publisherPriorityBrand: unique symbol;
+export type MoqtSubscriberPriority = number & {
+    readonly [subscriberPriorityBrand]: true;
+};
+export type MoqtPublisherPriority = number & {
+    readonly [publisherPriorityBrand]: true;
+};
+/** Validate a protocol-native MOQT subscriber priority without transforming it. */
+export declare function moqtSubscriberPriority(value: number): MoqtSubscriberPriority;
+/** Validate a protocol-native MOQT publisher priority without transforming it. */
+export declare function moqtPublisherPriority(value: number): MoqtPublisherPriority;
+/** Shared media subscription policy on MOQT's native lower-number-wins scale. */
+export declare const MOQT_SUBSCRIBER_PRIORITY: Readonly<{
+    catalog: MoqtSubscriberPriority;
+    /**
+     * @deprecated A repair FETCH's SUBSCRIBER_PRIORITY is derived per request
+     * from the catalog source and repair priorities (draft-ramadan-moq-fec
+     * §11.4.5), not a player constant. Use the `subscriberPriority` that
+     * `@blockcast/mmt-container`'s `wireRepairFetch` puts on each
+     * `RepairFetchRequest` (`repairFetchSubscriberPriority`).
+     */
+    deadlineRepair: MoqtSubscriberPriority;
+    audio: MoqtSubscriberPriority;
+    video: MoqtSubscriberPriority;
+    /**
+     * @deprecated See `deadlineRepair`: use the request's catalog-derived
+     * `RepairFetchRequest.subscriberPriority` (draft-ramadan-moq-fec §11.4.5).
+     */
+    backgroundRepair: MoqtSubscriberPriority;
+}>;
+/** Publisher priority bands from draft-ramadan-moq-fec section 10. */
+export declare const MOQT_PUBLISHER_PRIORITY: Readonly<{
+    catalog: MoqtPublisherPriority;
+    source: MoqtPublisherPriority;
+    repair: MoqtPublisherPriority;
+}>;
+export {};
+//# sourceMappingURL=moqt-priority.d.ts.map

package/dist/moqt-priority.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"moqt-priority.d.ts","sourceRoot":"","sources":["../src/moqt-priority.ts"],"names":[],"mappings":"AAEA,OAAO,CAAC,MAAM,uBAAuB,EAAE,OAAO,MAAM,CAAC;AACrD,OAAO,CAAC,MAAM,sBAAsB,EAAE,OAAO,MAAM,CAAC;AAEpD,MAAM,MAAM,sBAAsB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,uBAAuB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AAC3F,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG;IAAE,QAAQ,CAAC,CAAC,sBAAsB,CAAC,EAAE,IAAI,CAAA;CAAE,CAAC;AASzF,mFAAmF;AACnF,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,MAAM,GAAG,sBAAsB,CAE5E;AAED,kFAAkF;AAClF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,qBAAqB,CAE1E;AAED,iFAAiF;AACjF,eAAO,MAAM,wBAAwB;;IAEpC;;;;;;OAMG;;;;IAIH;;;OAGG;;EAEF,CAAC;AAEH,sEAAsE;AACtE,eAAO,MAAM,uBAAuB;;;;EAIlC,CAAC"}

package/dist/moqt-priority.js

@@ -0,0 +1,41 @@
+const MAX_MOQT_PRIORITY = 0xff;
+function moqtPriority(value, field) {
+    if (!Number.isInteger(value) || value < 0 || value > MAX_MOQT_PRIORITY) {
+        throw new RangeError(`${field} must be an integer in [0, ${MAX_MOQT_PRIORITY}], got ${value}`);
+    }
+    return value;
+}
+/** Validate a protocol-native MOQT subscriber priority without transforming it. */
+export function moqtSubscriberPriority(value) {
+    return moqtPriority(value, "MOQT subscriber priority");
+}
+/** Validate a protocol-native MOQT publisher priority without transforming it. */
+export function moqtPublisherPriority(value) {
+    return moqtPriority(value, "MOQT publisher priority");
+}
+/** Shared media subscription policy on MOQT's native lower-number-wins scale. */
+export const MOQT_SUBSCRIBER_PRIORITY = Object.freeze({
+    catalog: moqtSubscriberPriority(0),
+    /**
+     * @deprecated A repair FETCH's SUBSCRIBER_PRIORITY is derived per request
+     * from the catalog source and repair priorities (draft-ramadan-moq-fec
+     * §11.4.5), not a player constant. Use the `subscriberPriority` that
+     * `@blockcast/mmt-container`'s `wireRepairFetch` puts on each
+     * `RepairFetchRequest` (`repairFetchSubscriberPriority`).
+     */
+    deadlineRepair: moqtSubscriberPriority(0),
+    audio: moqtSubscriberPriority(1),
+    video: moqtSubscriberPriority(2),
+    /**
+     * @deprecated See `deadlineRepair`: use the request's catalog-derived
+     * `RepairFetchRequest.subscriberPriority` (draft-ramadan-moq-fec §11.4.5).
+     */
+    backgroundRepair: moqtSubscriberPriority(3),
+});
+/** Publisher priority bands from draft-ramadan-moq-fec section 10. */
+export const MOQT_PUBLISHER_PRIORITY = Object.freeze({
+    catalog: moqtPublisherPriority(32),
+    source: moqtPublisherPriority(128),
+    repair: moqtPublisherPriority(240),
+});
+//# sourceMappingURL=moqt-priority.js.map

package/dist/moqt-priority.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"moqt-priority.js","sourceRoot":"","sources":["../src/moqt-priority.ts"],"names":[],"mappings":"AAAA,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAQ/B,SAAS,YAAY,CAAC,KAAa,EAAE,KAAa;IACjD,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,GAAG,iBAAiB,EAAE,CAAC;QACxE,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,8BAA8B,iBAAiB,UAAU,KAAK,EAAE,CAAC,CAAC;IAChG,CAAC;IACD,OAAO,KAAK,CAAC;AACd,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,sBAAsB,CAAC,KAAa;IACnD,OAAO,YAAY,CAAC,KAAK,EAAE,0BAA0B,CAA2B,CAAC;AAClF,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,YAAY,CAAC,KAAK,EAAE,yBAAyB,CAA0B,CAAC;AAChF,CAAC;AAED,iFAAiF;AACjF,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,MAAM,CAAC;IACrD,OAAO,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAClC;;;;;;OAMG;IACH,cAAc,EAAE,sBAAsB,CAAC,CAAC,CAAC;IACzC,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAChC,KAAK,EAAE,sBAAsB,CAAC,CAAC,CAAC;IAChC;;;OAGG;IACH,gBAAgB,EAAE,sBAAsB,CAAC,CAAC,CAAC;CAC3C,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,MAAM,CAAC;IACpD,OAAO,EAAE,qBAAqB,CAAC,EAAE,CAAC;IAClC,MAAM,EAAE,qBAAqB,CAAC,GAAG,CAAC;IAClC,MAAM,EAAE,qBAAqB,CAAC,GAAG,CAAC;CAClC,CAAC,CAAC"}

package/dist/multicast-catalog-policy.d.ts

@@ -0,0 +1,96 @@
+import { type MulticastSignalingEndpoint } from "./multicast-signaling-reconciler.js";
+import type { MulticastTierEndpoint } from "./multicast-tier.js";
+import type { QualityLevel } from "./types.js";
+type Catalog = Record<string, any>;
+export interface PlayerMulticastConfig {
+    group: string;
+    source: string;
+    port: number;
+    mode?: string;
+    amtRelay?: string;
+    amtRelayPort?: number;
+    amtNetworkSource?: unknown;
+    packetIds?: number[];
+}
+export interface MulticastTrackSelection {
+    containerKind?: string;
+    rendition?: string;
+}
+export declare function hasMulticastCatalogBaseline(catalog: Catalog): boolean;
+export declare function hasUnicastMediaRenditions(catalog: Catalog): boolean;
+export declare function isMulticastOnlyCatalog(catalog: Catalog): boolean;
+export declare function requiresMulticastCapability(catalog: Catalog, capabilities?: {
+    multicast?: boolean;
+}): boolean;
+export declare function isRecoverableMulticastSignalReadError(error: unknown): boolean;
+export declare function withMulticastEndpoints(catalog: Catalog, endpoints: MulticastSignalingEndpoint[], version: number): Catalog;
+export declare function selectMulticastCandidate(catalog: Catalog, endpoints?: MulticastSignalingEndpoint[], search?: string | URLSearchParams): MulticastSignalingEndpoint | null;
+export declare function selectMulticastCandidateForTracks(catalog: Catalog, endpoints?: MulticastSignalingEndpoint[], selection?: MulticastTrackSelection): MulticastSignalingEndpoint | null;
+export declare function endpointToMulticastConfig(endpoint: MulticastSignalingEndpoint | Record<string, any> | null | undefined, catalog: Catalog, selection?: MulticastTrackSelection): PlayerMulticastConfig | null;
+export declare function selectEndpointPacketIds(endpoint: MulticastSignalingEndpoint | Record<string, any> | null | undefined, catalog: Catalog, search?: string | URLSearchParams): number[] | null;
+export declare function selectEndpointPacketIdsForTracks(endpoint: MulticastSignalingEndpoint | Record<string, any> | null | undefined, catalog: Catalog, selection?: MulticastTrackSelection): number[] | null;
+/** Read the player's explicit multicast override from `mc_*` URL parameters.
+ *  Throws when an override carries a retired unprefixed alias
+ *  (`assertNoRetiredMulticastUrlParams`). */
+export declare function readPlayerMulticastConfig(search?: string | URLSearchParams): PlayerMulticastConfig | null;
+export declare function normalizeMulticastConfig(config: Partial<PlayerMulticastConfig> | null | undefined): PlayerMulticastConfig | null;
+export declare function sameMulticastConfig(a: Partial<PlayerMulticastConfig> | null | undefined, b: Partial<PlayerMulticastConfig> | null | undefined): boolean;
+/** An omitted `urlConfig` is read from `location.search` by
+ *  `readPlayerMulticastConfig`, which throws on a retired unprefixed alias
+ *  inside an override. */
+export declare function urlOverrideBlocksMulticastCandidate(candidateConfig: Partial<PlayerMulticastConfig> | null | undefined, urlConfig?: PlayerMulticastConfig | null): boolean;
+/** Preserve catalog track selection while applying explicit URL transport policy.
+ *  An omitted `urlConfig` is read from `location.search` by
+ *  `readPlayerMulticastConfig`, which throws on a retired unprefixed alias
+ *  inside an override. */
+export declare function mergeUrlMulticastPolicy(candidateConfig: Partial<PlayerMulticastConfig> | null | undefined, urlConfig?: PlayerMulticastConfig | null): PlayerMulticastConfig | null;
+/** True when an endpoint carries at least one track that is not a repair
+ *  track, i.e. it can serve media on its own. A repair-layer endpoint carries
+ *  only `fec-repair` tracks and is joined by the loss-driven layer policy, so
+ *  it must be excluded from the bandwidth ladder (`selectMulticastTier`).
+ *  An endpoint listing no tracks is treated as carrying media: that is the
+ *  pre-layer signalling shape, and a naming-era catalog with no repair tracks
+ *  declared classifies every endpoint as media.
+ *
+ *  Throws on a catalog carrying the retired `commonTrackFields` or per-track
+ *  `selectionParams`: repair membership cannot be derived from such a catalog,
+ *  and classifying it as all-media would make repair-only endpoints joinable. */
+export declare function endpointCarriesMedia(catalog: Catalog, endpoint: {
+    tracks?: {
+        name?: string;
+    }[];
+} | null | undefined): boolean;
+/** Catalog signalling endpoints as bandwidth-ladder endpoints, classified.
+ *
+ *  Every ladder caller must build its `MulticastTierEndpoint[]` through this
+ *  rather than hand-shaping them from the catalog: `carriesMedia` is optional
+ *  and an unset one is treated as carrying media, so an endpoint that was
+ *  never classified stays selectable as a tier and joining it would leave the
+ *  receiver with repair symbols and no media. Classifying at the one place
+ *  endpoints are converted is what makes that impossible to forget.
+ *
+ *  `bandwidth` is carried through only when the endpoint declares a positive
+ *  finite number and is never synthesized, so an endpoint that omits it stays
+ *  unranked exactly as before. Only the fields the ladder reads are copied;
+ *  signalling-only keys stay behind. */
+export declare function catalogTierEndpoints(catalog: Catalog, endpoints?: MulticastSignalingEndpoint[]): MulticastTierEndpoint[];
+/** The ABR ladder a catalog advertises, for `TransportManager.connect()`'s
+ *  `abrLadder`: one rung per rendition of `role` (the role's `renditions` map
+ *  and any `tracks` entry with that role), named by its catalog track name
+ *  and costed at its catalog `bitrate`. `width`, `height` and `fps` are copied
+ *  from `codedWidth`, `codedHeight` and `framerate` only when the catalog
+ *  states them as positive numbers; none is defaulted. Rungs keep catalog
+ *  order; the ABR controller walks them by ascending bitrate.
+ *
+ *  Throws `RangeError` naming the first video rendition whose `bitrate` is not
+ *  a positive finite number. ABR costs measured throughput against each
+ *  rung's bitrate, so a rung without one cannot drive it, and the coded-size
+ *  or name rank `videoRenditionRank` falls back to orders renditions without
+ *  pricing them. A catalog that omits `bitrate` therefore has no ABR ladder:
+ *  have its publisher state one per rendition, or connect with a ladder of
+ *  only the renditions the caller can price. A catalog with no video
+ *  rendition yields an empty ladder, which `connect()` refuses. Pass `"audio"`
+ *  for an audio-only stream; the default is `"video"`. */
+export declare function catalogQualityLadder(catalog: Catalog, role?: "video" | "audio"): QualityLevel[];
+export {};
+//# sourceMappingURL=multicast-catalog-policy.d.ts.map

package/dist/multicast-catalog-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"multicast-catalog-policy.d.ts","sourceRoot":"","sources":["../src/multicast-catalog-policy.ts"],"names":[],"mappings":"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"}