moqtail 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,5 +1,5 @@
1
1
  import { Location, MoqtObject, Setup, SetupOptions, Tuple } from "./model.cjs";
2
- import { D as FetchOptions, M as SubscribeOptions, N as SubscribeResult, O as FetchResult, j as ObjectOrdering, k as MOQtailClientOptions, t as MOQtailClient } from "./client-DUzLw_Y8.cjs";
2
+ import { D as FetchOptions, J as DataEvent, M as SubscribeOptions, N as SubscribeResult, O as FetchResult, X as DataHeaderEvent, j as ObjectOrdering, k as MOQtailClientOptions, t as MOQtailClient } from "./client-CjdF7_cL.cjs";
3
3
  import { o as Emitter } from "./logger-B8IYkljn.cjs";
4
4
  import * as v from "valibot";
5
5
  /** @public An inclusive range of MOQT Locations. */
@@ -30,7 +30,7 @@ interface MsfSource {
30
30
  locationRanges: LocationRange[];
31
31
  mediaTimeRanges: TimeRange[];
32
32
  wallclockRanges: TimeRange[];
33
- c4m?: string;
33
+ cat?: string;
34
34
  connection?: 'q' | 'wt';
35
35
  /** Every fragment parameter, last value wins. Used for catalog variable substitution (MSF 5.4). */
36
36
  variables: Record<string, string>;
@@ -96,7 +96,7 @@ type InitData = {
96
96
  };
97
97
  /** An independent catalog (MSF 5.1) whose tracks without a namespace inherit `catalogNamespace`. */
98
98
  declare const catalogSchema: (catalogNamespace: Tuple) => v.SchemaWithPipe<readonly [v.LooseObjectSchema<{
99
- readonly version: v.PicklistSchema<readonly ["draft-01"], (issue: v.PicklistIssue) => string>;
99
+ readonly version: v.PicklistSchema<readonly ["draft-01", "draft-02"], (issue: v.PicklistIssue) => string>;
100
100
  readonly generatedAt: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
101
101
  readonly isComplete: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
102
102
  readonly tracks: v.ArraySchema<v.SchemaWithPipe<readonly [v.LooseObjectSchema<{
@@ -1166,7 +1166,7 @@ declare const catalogSchema: (catalogNamespace: Tuple) => v.SchemaWithPipe<reado
1166
1166
  init: InitData;
1167
1167
  }>]>, undefined>, undefined>;
1168
1168
  }, undefined>, v.CheckAction<{
1169
- version: "draft-01";
1169
+ version: "draft-01" | "draft-02";
1170
1170
  generatedAt?: number | undefined;
1171
1171
  isComplete?: true | undefined;
1172
1172
  tracks: ({
@@ -1368,6 +1368,11 @@ interface MediaSinkElement extends EventTarget {
1368
1368
  readonly playbackRate: number;
1369
1369
  /** Where the live edge starts (media-ui-extensions proposal 0007); `NaN` on demand. */
1370
1370
  readonly liveEdgeStart: number;
1371
+ /** Live with an accessible window (MSF 5.2.46): the seconds it covers. Undefined without DVR. */
1372
+ readonly dvrRange: {
1373
+ start: number;
1374
+ end: number;
1375
+ } | undefined;
1371
1376
  setPlaybackRate(rate: number): void;
1372
1377
  play(): Promise<void>;
1373
1378
  pause(): Promise<void>;
@@ -1396,6 +1401,8 @@ interface Rendition {
1396
1401
  active: boolean;
1397
1402
  /** Considered for ABR. */
1398
1403
  selected: boolean;
1404
+ /** Track names of its fast switching GoP ladder, itself included: they all deliver this rendition. */
1405
+ ladder?: string[];
1399
1406
  }
1400
1407
  /** @public What the catalog element offers the elements it loads. Updates arrive with the player's `catalog` event. */
1401
1408
  interface CatalogReader {
@@ -1491,7 +1498,10 @@ interface ElementDefinition<E extends BaseElement = BaseElement, P extends reado
1491
1498
  readonly type: 'source' | 'transform' | 'sink';
1492
1499
  readonly name: string;
1493
1500
  readonly capabilities: CapabilityBundles;
1494
- /** Ranks the probes that accept a track: lower wins, then the earlier definition. Default 100. */
1501
+ /**
1502
+ * Ranks the probes that accept a track: lower wins, then the earlier definition. Default selection
1503
+ * also keeps only the lowest of the sets sharing an `altGroup` and `lang`. Default 100.
1504
+ */
1495
1505
  readonly priority?: number;
1496
1506
  /** The optional interfaces this element implements. */
1497
1507
  readonly provides?: P;
@@ -1589,6 +1599,8 @@ interface PadProperties {
1589
1599
  start: number;
1590
1600
  end: number;
1591
1601
  };
1602
+ /** Seconds: the catalog's `accessibleWindowTime` (MSF 5.2.46). Live only; absent means no DVR. */
1603
+ accessibleWindow?: number;
1592
1604
  }
1593
1605
  /** @public Written to a source pad, delivered in order with the packets around it. */
1594
1606
  type PadEvent = {
@@ -1795,6 +1807,10 @@ declare class MSESink extends SinkElement implements MediaSinkElement {
1795
1807
  get ended(): boolean;
1796
1808
  get playbackRate(): number;
1797
1809
  get liveEdgeStart(): number;
1810
+ get dvrRange(): {
1811
+ start: number;
1812
+ end: number;
1813
+ } | undefined;
1798
1814
  setPlaybackRate(rate: number): void;
1799
1815
  play(): Promise<void>;
1800
1816
  pause(): Promise<void>;
@@ -1996,6 +2012,22 @@ declare class MOQtailPlayer extends Emitter<PlayerEvents> {
1996
2012
  * where it exists and `MediaSource` otherwise. `player.sink(video)` adds it with `{ video }`.
1997
2013
  */
1998
2014
  declare const MSE: SinkElementDefinition<MSESink, readonly [typeof MEDIA_SINK]>;
2015
+ /** @public Index of the range containing `time`, or -1. */
2016
+ declare function rangeAt(time: number, ranges: TimeRanges): number;
2017
+ /**
2018
+ * @public
2019
+ * Runs `attach` on the player's current client and on every later one (reconnects replace it),
2020
+ * calling the cleanup `attach` returned for the one before. Returns the function that stops.
2021
+ */
2022
+ declare function eachClient(player: MOQtailPlayer, attach: (client: MOQtailClient) => () => void): () => void;
2023
+ /**
2024
+ * @public
2025
+ * Calls `listener` with each incoming data event of the player's client, across reconnects, with
2026
+ * the name of the track its stream carries and the stream's header. A stream can open before the
2027
+ * response naming its track, so `track` stays undefined until a later event of that stream.
2028
+ * Streams opened before the call are skipped. Returns the function that stops listening.
2029
+ */
2030
+ declare function followData(player: MOQtailPlayer, listener: (event: DataEvent, track: string | undefined, header: DataHeaderEvent) => void): () => void;
1999
2031
  /**
2000
2032
  * Copyright 2026 The MOQtail Authors
2001
2033
  *
@@ -2028,17 +2060,156 @@ interface LiveBufferConfig {
2028
2060
  * Priority `Infinity`, so any other active buffer plugin wins over it.
2029
2061
  */
2030
2062
  declare const liveBuffer: (config?: LiveBufferConfig | undefined) => Plugin;
2031
- /** @public The `abr()` controller. For now it keeps the current quality: it never switches. */
2032
- declare class DefaultAbrController implements AbrController {
2033
- attach(_player: MOQtailPlayer, _sink: MediaSinkElement): void;
2063
+ /**
2064
+ * Copyright 2026 The MOQtail Authors
2065
+ *
2066
+ * Licensed under the Apache License, Version 2.0 (the "License");
2067
+ * you may not use this file except in compliance with the License.
2068
+ * You may obtain a copy of the License at
2069
+ *
2070
+ * http://www.apache.org/licenses/LICENSE-2.0
2071
+ *
2072
+ * Unless required by applicable law or agreed to in writing, software
2073
+ * distributed under the License is distributed on an "AS IS" BASIS,
2074
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2075
+ * See the License for the specific language governing permissions and
2076
+ * limitations under the License.
2077
+ */
2078
+ /**
2079
+ * The observation contract between the controller and its model: what the controller reads each
2080
+ * tick, the features the model sees, and the actions it may take. A model is trained on exactly
2081
+ * these, so changing them takes a new model and a new `FEATURES_VERSION`.
2082
+ */
2083
+ /** @public What the controller reads each tick, in seconds, bytes and bits per second. */
2084
+ interface Observation {
2085
+ /** Buffered ahead of the playhead. */
2086
+ forwardBuffer: number;
2087
+ /** 0 while stalled. */
2088
+ playbackRate: number;
2089
+ /** Time stalled within the last `WINDOW`. */
2090
+ stalledTime: number;
2091
+ /** The selectable bitrates, ascending. */
2092
+ ladder: readonly number[];
2093
+ /** Index in `ladder` of the rendition last asked for. */
2094
+ requested: number;
2095
+ /** The bitrate of the rendition being received. */
2096
+ activeBitrate: number;
2097
+ /** Live video bytes received within the last `WINDOW`. */
2098
+ receivedBytes: number;
2099
+ /**
2100
+ * Live video bytes per second: the slower of the last `RECENT` seconds and its second half, from the
2101
+ * last settled switch on. Under trouble, live delivery saturates the link, so this is what it carries.
2102
+ */
2103
+ throughput: number;
2104
+ /**
2105
+ * Video objects received within the last `WINDOW` over what the frame rate delivers in it: about 1
2106
+ * while the link keeps up, whatever the scene costs, and less once it falls behind.
2107
+ */
2108
+ arrivalRate: number;
2109
+ /**
2110
+ * Link capacity recent probes saw, in bytes per second: the median of the last `CONFIRMING`, so one
2111
+ * outlier can't swing it; null before a probe, or once contradicted.
2112
+ */
2113
+ probeEstimate: number | null;
2114
+ /** Since the last probe ended with an estimate. */
2115
+ probeAge: number | null;
2116
+ /**
2117
+ * The median of the last `CONFIRMING` estimates when all of them are still evidence: each ages only
2118
+ * while the controller is free to act, and counts for `UP_EVIDENCE` seconds of that. Null otherwise.
2119
+ */
2120
+ evidence: number | null;
2121
+ probing: boolean;
2122
+ /** Probes in a row that found no room for the next rendition. */
2123
+ probeFailures: number;
2124
+ /** Since the last probe ended; null before one. */
2125
+ sinceProbe: number | null;
2126
+ sinceSwitch: number;
2127
+ /** Between group starts; null until two are seen. */
2128
+ groupInterval: number | null;
2129
+ /** Whether a recent group is known well enough to plan a probe from. */
2130
+ probeable: boolean;
2131
+ /** A switch is taking effect: the old track still streams, or the new one hasn't arrived. */
2132
+ settling: boolean;
2133
+ /** Since the last switch settled; windowed signals count from then on. */
2134
+ sinceSettled: number;
2135
+ /** Since the last stall or the last time frames fell behind. */
2136
+ sinceTrouble: number;
2137
+ }
2138
+ /** @public What the controller does with a tick. */
2139
+ declare const Action: {
2140
+ readonly Down: 0;
2141
+ readonly Stay: 1;
2142
+ readonly Up: 2;
2143
+ readonly Probe: 3;
2144
+ };
2145
+ /** @public */
2146
+ type Action = (typeof Action)[keyof typeof Action];
2147
+ /** @public A model as shipped: base64 of the packed form, and whether it is compressed. */
2148
+ interface ModelBlob {
2149
+ data: string;
2150
+ codec: 'deflate-raw' | 'raw';
2151
+ }
2152
+ interface Layer {
2153
+ inputs: number;
2154
+ outputs: number;
2155
+ /** Row-major: `outputs` rows of `inputs` weights. */
2156
+ weights: Float64Array;
2157
+ biases: Float64Array;
2158
+ }
2159
+ /** A decoded model: logits over `Action` for a feature vector. */
2160
+ declare class Policy {
2161
+ #private;
2162
+ constructor(layers: readonly Layer[]);
2163
+ /**
2164
+ * Decodes a blob.
2165
+ * @throws TypeError for a model trained on another feature list, which would read the inputs wrong.
2166
+ */
2167
+ static load(blob: ModelBlob): Promise<Policy>;
2168
+ logits(features: readonly number[]): number[];
2169
+ /**
2170
+ * Draws an allowed action by the model's odds instead of taking the likeliest: some choices, such
2171
+ * as an occasional probe on a calm link, it learned only as odds. `random` returns numbers in [0, 1).
2172
+ */
2173
+ choose(features: readonly number[], legal: readonly boolean[], random?: () => number): Action;
2174
+ }
2175
+ /** @public What the controller decided on a tick, for logging. */
2176
+ interface Decision {
2177
+ action: Action;
2178
+ observation: Observation;
2179
+ features: number[];
2180
+ /** Set on the tick a probe ended: what it measured, in bytes per second. */
2181
+ probeResult?: number;
2182
+ /** Set on a switch: the index in `observation.ladder` it asked for. */
2183
+ switchedTo?: number;
2184
+ /** Set while too little live video arrived to judge the link; the action is then `Stay`. */
2185
+ warmingUp?: true;
2186
+ }
2187
+ /**
2188
+ * @public
2189
+ * ABR for live playback: every tick a small neural network picks a switch down, a switch up, a probe
2190
+ * or nothing, among the actions `legalActions` allows.
2191
+ */
2192
+ declare class MlAbrController implements AbrController {
2193
+ #private;
2194
+ constructor(tickMs: number, policy: Promise<Policy>, onDecision?: (decision: Decision) => void);
2195
+ attach(player: MOQtailPlayer, sink: MediaSinkElement): void;
2034
2196
  detach(): void;
2035
2197
  }
2198
+ /** @public */
2199
+ interface MlAbrConfig {
2200
+ /** Milliseconds between decisions. Above 0, default 500, which the bundled model was trained at. */
2201
+ tickMs?: number;
2202
+ /** A model to use instead of the bundled one. */
2203
+ model?: ModelBlob;
2204
+ /** Called with every decision, for logging. */
2205
+ onDecision?: (decision: Decision) => void;
2206
+ }
2036
2207
  /**
2037
2208
  * @public
2038
- * An ABR controller for media sources that don't switch themselves. Priority `Infinity`, so any
2209
+ * An ABR controller driven by a small neural network, for live streams. Priority `Infinity`, so any
2039
2210
  * other active ABR plugin wins over it.
2040
2211
  */
2041
- declare const abr: () => Plugin;
2212
+ declare const abr: (config?: MlAbrConfig | undefined) => Plugin;
2042
2213
  /** @public The switching set source of the `ssts()` plugin. */
2043
2214
  declare class SstsSource extends SourceElement implements MediaSourceElement {
2044
2215
  #private;
@@ -2087,4 +2258,4 @@ interface SstsConfig {
2087
2258
  }
2088
2259
  /** @public The SSTS plugin, for `opts.plugins`. */
2089
2260
  declare const ssts: (config?: SstsConfig | undefined) => Plugin;
2090
- export { ABR as $, CONNECTION_CAPACITY as A, Capabilities as B, TimelineEvent as C, formatMsfUrl as Ct, SinkElement as D, ElementEvents as E, PadProperties as F, ElementDefinition as G, CapabilityBundles as H, PadSignal as I, SinkElementDefinition as J, Identifiers as K, ElementContext as L, PadEvent as M, PadItem as N, SourceElement as O, PadOutput as P, hasInterface as Q, ElementLoadRequest as R, CatalogElement as S, TimeRange as St, BaseElement as T, CapabilityCode as U, Capability as V, DEFAULT_PRIORITY as W, TransformElementDefinition as X, SourceElementDefinition as Y, defineElement as Z, Feature as _, PlayerError as _t, abr as a, MediaSinkElement as at, definePlugin as b, LocationRange as bt, liveBuffer as c, Rendition as ct, MOQtailPlayerOptions as d, TimelineReader as dt, CatalogReader as et, PlayerEvents as f, Catalog as ft, BufferController as g, InitData as gt, AbrController as h, MediaTimelineTemplate as ht, SstsSource as i, MEDIA_SOURCE as it, Pad as j, TransformElement as k, MSE as l, RequestHooks as lt, PlayerState as m, CatalogTrack as mt, ssts as n, InterfaceKey as nt, DefaultAbrController as o, MediaSourceElement as ot, StreamType as p, CatalogJson as pt, Provided as q, SSTS_ALGORITHMS as r, MEDIA_SINK as rt, LiveBufferConfig as s, MediaSourceOptions as st, SstsConfig as t, ElementInterfaces as tt, MOQtailPlayer as u, SwitchingSetOptions as ut, Plugin as v, PlayerErrorCategory as vt, TimelineRecord as w, parseMsfUrl as wt, MSEOptions as x, MsfSource as xt, PluginDefinition as y, PlayerErrorCode as yt, PlayerHandle as z };
2261
+ export { ElementDefinition as $, CatalogElement as A, TimeRange as At, PadEvent as B, AbrController as C, MediaTimelineTemplate as Ct, PluginDefinition as D, PlayerErrorCode as Dt, Plugin as E, PlayerErrorCategory as Et, SinkElement as F, ElementContext as G, PadOutput as H, SourceElement as I, Capabilities as J, ElementLoadRequest as K, TransformElement as L, TimelineRecord as M, parseMsfUrl as Mt, BaseElement as N, definePlugin as O, LocationRange as Ot, ElementEvents as P, DEFAULT_PRIORITY as Q, CONNECTION_CAPACITY as R, PlayerState as S, CatalogTrack as St, Feature as T, PlayerError as Tt, PadProperties as U, PadItem as V, PadSignal as W, CapabilityBundles as X, Capability as Y, CapabilityCode as Z, MSE as _, RequestHooks as _t, MlAbrConfig as a, defineElement as at, PlayerEvents as b, Catalog as bt, MlAbrController as c, CatalogReader as ct, Observation as d, MEDIA_SINK as dt, Identifiers as et, LiveBufferConfig as f, MEDIA_SOURCE as ft, rangeAt as g, Rendition as gt, followData as h, MediaSourceOptions as ht, SstsSource as i, TransformElementDefinition as it, TimelineEvent as j, formatMsfUrl as jt, MSEOptions as k, MsfSource as kt, ModelBlob as l, ElementInterfaces as lt, eachClient as m, MediaSourceElement as mt, ssts as n, SinkElementDefinition as nt, abr as o, hasInterface as ot, liveBuffer as p, MediaSinkElement as pt, PlayerHandle as q, SSTS_ALGORITHMS as r, SourceElementDefinition as rt, Decision as s, ABR as st, SstsConfig as t, Provided as tt, Action as u, InterfaceKey as ut, MOQtailPlayer as v, SwitchingSetOptions as vt, BufferController as w, InitData as wt, StreamType as x, CatalogJson as xt, MOQtailPlayerOptions as y, TimelineReader as yt, Pad as z };
@@ -1,6 +1,6 @@
1
- import { Jn as Location, Kn as Tuple, at as Setup, bn as MoqtObject, r as SetupOptions } from "./index-CNn9BgO6.mjs";
1
+ import { Jn as Location, Kn as Tuple, at as Setup, bn as MoqtObject, r as SetupOptions } from "./index-BaZgHZ8D.mjs";
2
2
  import { o as Emitter } from "./logger-B8IYkljn.mjs";
3
- import { D as FetchOptions, M as SubscribeOptions, N as SubscribeResult, O as FetchResult, j as ObjectOrdering, k as MOQtailClientOptions, t as MOQtailClient } from "./client-epHqMdHm.mjs";
3
+ import { D as FetchOptions, J as DataEvent, M as SubscribeOptions, N as SubscribeResult, O as FetchResult, X as DataHeaderEvent, j as ObjectOrdering, k as MOQtailClientOptions, t as MOQtailClient } from "./client-I8mDg-Ls.mjs";
4
4
  import * as v from "valibot";
5
5
  /** @public An inclusive range of MOQT Locations. */
6
6
  interface LocationRange {
@@ -30,7 +30,7 @@ interface MsfSource {
30
30
  locationRanges: LocationRange[];
31
31
  mediaTimeRanges: TimeRange[];
32
32
  wallclockRanges: TimeRange[];
33
- c4m?: string;
33
+ cat?: string;
34
34
  connection?: 'q' | 'wt';
35
35
  /** Every fragment parameter, last value wins. Used for catalog variable substitution (MSF 5.4). */
36
36
  variables: Record<string, string>;
@@ -96,7 +96,7 @@ type InitData = {
96
96
  };
97
97
  /** An independent catalog (MSF 5.1) whose tracks without a namespace inherit `catalogNamespace`. */
98
98
  declare const catalogSchema: (catalogNamespace: Tuple) => v.SchemaWithPipe<readonly [v.LooseObjectSchema<{
99
- readonly version: v.PicklistSchema<readonly ["draft-01"], (issue: v.PicklistIssue) => string>;
99
+ readonly version: v.PicklistSchema<readonly ["draft-01", "draft-02"], (issue: v.PicklistIssue) => string>;
100
100
  readonly generatedAt: v.OptionalSchema<v.NumberSchema<undefined>, undefined>;
101
101
  readonly isComplete: v.OptionalSchema<v.LiteralSchema<true, undefined>, undefined>;
102
102
  readonly tracks: v.ArraySchema<v.SchemaWithPipe<readonly [v.LooseObjectSchema<{
@@ -1166,7 +1166,7 @@ declare const catalogSchema: (catalogNamespace: Tuple) => v.SchemaWithPipe<reado
1166
1166
  init: InitData;
1167
1167
  }>]>, undefined>, undefined>;
1168
1168
  }, undefined>, v.CheckAction<{
1169
- version: "draft-01";
1169
+ version: "draft-01" | "draft-02";
1170
1170
  generatedAt?: number | undefined;
1171
1171
  isComplete?: true | undefined;
1172
1172
  tracks: ({
@@ -1368,6 +1368,11 @@ interface MediaSinkElement extends EventTarget {
1368
1368
  readonly playbackRate: number;
1369
1369
  /** Where the live edge starts (media-ui-extensions proposal 0007); `NaN` on demand. */
1370
1370
  readonly liveEdgeStart: number;
1371
+ /** Live with an accessible window (MSF 5.2.46): the seconds it covers. Undefined without DVR. */
1372
+ readonly dvrRange: {
1373
+ start: number;
1374
+ end: number;
1375
+ } | undefined;
1371
1376
  setPlaybackRate(rate: number): void;
1372
1377
  play(): Promise<void>;
1373
1378
  pause(): Promise<void>;
@@ -1396,6 +1401,8 @@ interface Rendition {
1396
1401
  active: boolean;
1397
1402
  /** Considered for ABR. */
1398
1403
  selected: boolean;
1404
+ /** Track names of its fast switching GoP ladder, itself included: they all deliver this rendition. */
1405
+ ladder?: string[];
1399
1406
  }
1400
1407
  /** @public What the catalog element offers the elements it loads. Updates arrive with the player's `catalog` event. */
1401
1408
  interface CatalogReader {
@@ -1491,7 +1498,10 @@ interface ElementDefinition<E extends BaseElement = BaseElement, P extends reado
1491
1498
  readonly type: 'source' | 'transform' | 'sink';
1492
1499
  readonly name: string;
1493
1500
  readonly capabilities: CapabilityBundles;
1494
- /** Ranks the probes that accept a track: lower wins, then the earlier definition. Default 100. */
1501
+ /**
1502
+ * Ranks the probes that accept a track: lower wins, then the earlier definition. Default selection
1503
+ * also keeps only the lowest of the sets sharing an `altGroup` and `lang`. Default 100.
1504
+ */
1495
1505
  readonly priority?: number;
1496
1506
  /** The optional interfaces this element implements. */
1497
1507
  readonly provides?: P;
@@ -1589,6 +1599,8 @@ interface PadProperties {
1589
1599
  start: number;
1590
1600
  end: number;
1591
1601
  };
1602
+ /** Seconds: the catalog's `accessibleWindowTime` (MSF 5.2.46). Live only; absent means no DVR. */
1603
+ accessibleWindow?: number;
1592
1604
  }
1593
1605
  /** @public Written to a source pad, delivered in order with the packets around it. */
1594
1606
  type PadEvent = {
@@ -1795,6 +1807,10 @@ declare class MSESink extends SinkElement implements MediaSinkElement {
1795
1807
  get ended(): boolean;
1796
1808
  get playbackRate(): number;
1797
1809
  get liveEdgeStart(): number;
1810
+ get dvrRange(): {
1811
+ start: number;
1812
+ end: number;
1813
+ } | undefined;
1798
1814
  setPlaybackRate(rate: number): void;
1799
1815
  play(): Promise<void>;
1800
1816
  pause(): Promise<void>;
@@ -1996,6 +2012,22 @@ declare class MOQtailPlayer extends Emitter<PlayerEvents> {
1996
2012
  * where it exists and `MediaSource` otherwise. `player.sink(video)` adds it with `{ video }`.
1997
2013
  */
1998
2014
  declare const MSE: SinkElementDefinition<MSESink, readonly [typeof MEDIA_SINK]>;
2015
+ /** @public Index of the range containing `time`, or -1. */
2016
+ declare function rangeAt(time: number, ranges: TimeRanges): number;
2017
+ /**
2018
+ * @public
2019
+ * Runs `attach` on the player's current client and on every later one (reconnects replace it),
2020
+ * calling the cleanup `attach` returned for the one before. Returns the function that stops.
2021
+ */
2022
+ declare function eachClient(player: MOQtailPlayer, attach: (client: MOQtailClient) => () => void): () => void;
2023
+ /**
2024
+ * @public
2025
+ * Calls `listener` with each incoming data event of the player's client, across reconnects, with
2026
+ * the name of the track its stream carries and the stream's header. A stream can open before the
2027
+ * response naming its track, so `track` stays undefined until a later event of that stream.
2028
+ * Streams opened before the call are skipped. Returns the function that stops listening.
2029
+ */
2030
+ declare function followData(player: MOQtailPlayer, listener: (event: DataEvent, track: string | undefined, header: DataHeaderEvent) => void): () => void;
1999
2031
  /**
2000
2032
  * Copyright 2026 The MOQtail Authors
2001
2033
  *
@@ -2028,17 +2060,156 @@ interface LiveBufferConfig {
2028
2060
  * Priority `Infinity`, so any other active buffer plugin wins over it.
2029
2061
  */
2030
2062
  declare const liveBuffer: (config?: LiveBufferConfig | undefined) => Plugin;
2031
- /** @public The `abr()` controller. For now it keeps the current quality: it never switches. */
2032
- declare class DefaultAbrController implements AbrController {
2033
- attach(_player: MOQtailPlayer, _sink: MediaSinkElement): void;
2063
+ /**
2064
+ * Copyright 2026 The MOQtail Authors
2065
+ *
2066
+ * Licensed under the Apache License, Version 2.0 (the "License");
2067
+ * you may not use this file except in compliance with the License.
2068
+ * You may obtain a copy of the License at
2069
+ *
2070
+ * http://www.apache.org/licenses/LICENSE-2.0
2071
+ *
2072
+ * Unless required by applicable law or agreed to in writing, software
2073
+ * distributed under the License is distributed on an "AS IS" BASIS,
2074
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
2075
+ * See the License for the specific language governing permissions and
2076
+ * limitations under the License.
2077
+ */
2078
+ /**
2079
+ * The observation contract between the controller and its model: what the controller reads each
2080
+ * tick, the features the model sees, and the actions it may take. A model is trained on exactly
2081
+ * these, so changing them takes a new model and a new `FEATURES_VERSION`.
2082
+ */
2083
+ /** @public What the controller reads each tick, in seconds, bytes and bits per second. */
2084
+ interface Observation {
2085
+ /** Buffered ahead of the playhead. */
2086
+ forwardBuffer: number;
2087
+ /** 0 while stalled. */
2088
+ playbackRate: number;
2089
+ /** Time stalled within the last `WINDOW`. */
2090
+ stalledTime: number;
2091
+ /** The selectable bitrates, ascending. */
2092
+ ladder: readonly number[];
2093
+ /** Index in `ladder` of the rendition last asked for. */
2094
+ requested: number;
2095
+ /** The bitrate of the rendition being received. */
2096
+ activeBitrate: number;
2097
+ /** Live video bytes received within the last `WINDOW`. */
2098
+ receivedBytes: number;
2099
+ /**
2100
+ * Live video bytes per second: the slower of the last `RECENT` seconds and its second half, from the
2101
+ * last settled switch on. Under trouble, live delivery saturates the link, so this is what it carries.
2102
+ */
2103
+ throughput: number;
2104
+ /**
2105
+ * Video objects received within the last `WINDOW` over what the frame rate delivers in it: about 1
2106
+ * while the link keeps up, whatever the scene costs, and less once it falls behind.
2107
+ */
2108
+ arrivalRate: number;
2109
+ /**
2110
+ * Link capacity recent probes saw, in bytes per second: the median of the last `CONFIRMING`, so one
2111
+ * outlier can't swing it; null before a probe, or once contradicted.
2112
+ */
2113
+ probeEstimate: number | null;
2114
+ /** Since the last probe ended with an estimate. */
2115
+ probeAge: number | null;
2116
+ /**
2117
+ * The median of the last `CONFIRMING` estimates when all of them are still evidence: each ages only
2118
+ * while the controller is free to act, and counts for `UP_EVIDENCE` seconds of that. Null otherwise.
2119
+ */
2120
+ evidence: number | null;
2121
+ probing: boolean;
2122
+ /** Probes in a row that found no room for the next rendition. */
2123
+ probeFailures: number;
2124
+ /** Since the last probe ended; null before one. */
2125
+ sinceProbe: number | null;
2126
+ sinceSwitch: number;
2127
+ /** Between group starts; null until two are seen. */
2128
+ groupInterval: number | null;
2129
+ /** Whether a recent group is known well enough to plan a probe from. */
2130
+ probeable: boolean;
2131
+ /** A switch is taking effect: the old track still streams, or the new one hasn't arrived. */
2132
+ settling: boolean;
2133
+ /** Since the last switch settled; windowed signals count from then on. */
2134
+ sinceSettled: number;
2135
+ /** Since the last stall or the last time frames fell behind. */
2136
+ sinceTrouble: number;
2137
+ }
2138
+ /** @public What the controller does with a tick. */
2139
+ declare const Action: {
2140
+ readonly Down: 0;
2141
+ readonly Stay: 1;
2142
+ readonly Up: 2;
2143
+ readonly Probe: 3;
2144
+ };
2145
+ /** @public */
2146
+ type Action = (typeof Action)[keyof typeof Action];
2147
+ /** @public A model as shipped: base64 of the packed form, and whether it is compressed. */
2148
+ interface ModelBlob {
2149
+ data: string;
2150
+ codec: 'deflate-raw' | 'raw';
2151
+ }
2152
+ interface Layer {
2153
+ inputs: number;
2154
+ outputs: number;
2155
+ /** Row-major: `outputs` rows of `inputs` weights. */
2156
+ weights: Float64Array;
2157
+ biases: Float64Array;
2158
+ }
2159
+ /** A decoded model: logits over `Action` for a feature vector. */
2160
+ declare class Policy {
2161
+ #private;
2162
+ constructor(layers: readonly Layer[]);
2163
+ /**
2164
+ * Decodes a blob.
2165
+ * @throws TypeError for a model trained on another feature list, which would read the inputs wrong.
2166
+ */
2167
+ static load(blob: ModelBlob): Promise<Policy>;
2168
+ logits(features: readonly number[]): number[];
2169
+ /**
2170
+ * Draws an allowed action by the model's odds instead of taking the likeliest: some choices, such
2171
+ * as an occasional probe on a calm link, it learned only as odds. `random` returns numbers in [0, 1).
2172
+ */
2173
+ choose(features: readonly number[], legal: readonly boolean[], random?: () => number): Action;
2174
+ }
2175
+ /** @public What the controller decided on a tick, for logging. */
2176
+ interface Decision {
2177
+ action: Action;
2178
+ observation: Observation;
2179
+ features: number[];
2180
+ /** Set on the tick a probe ended: what it measured, in bytes per second. */
2181
+ probeResult?: number;
2182
+ /** Set on a switch: the index in `observation.ladder` it asked for. */
2183
+ switchedTo?: number;
2184
+ /** Set while too little live video arrived to judge the link; the action is then `Stay`. */
2185
+ warmingUp?: true;
2186
+ }
2187
+ /**
2188
+ * @public
2189
+ * ABR for live playback: every tick a small neural network picks a switch down, a switch up, a probe
2190
+ * or nothing, among the actions `legalActions` allows.
2191
+ */
2192
+ declare class MlAbrController implements AbrController {
2193
+ #private;
2194
+ constructor(tickMs: number, policy: Promise<Policy>, onDecision?: (decision: Decision) => void);
2195
+ attach(player: MOQtailPlayer, sink: MediaSinkElement): void;
2034
2196
  detach(): void;
2035
2197
  }
2198
+ /** @public */
2199
+ interface MlAbrConfig {
2200
+ /** Milliseconds between decisions. Above 0, default 500, which the bundled model was trained at. */
2201
+ tickMs?: number;
2202
+ /** A model to use instead of the bundled one. */
2203
+ model?: ModelBlob;
2204
+ /** Called with every decision, for logging. */
2205
+ onDecision?: (decision: Decision) => void;
2206
+ }
2036
2207
  /**
2037
2208
  * @public
2038
- * An ABR controller for media sources that don't switch themselves. Priority `Infinity`, so any
2209
+ * An ABR controller driven by a small neural network, for live streams. Priority `Infinity`, so any
2039
2210
  * other active ABR plugin wins over it.
2040
2211
  */
2041
- declare const abr: () => Plugin;
2212
+ declare const abr: (config?: MlAbrConfig | undefined) => Plugin;
2042
2213
  /** @public The switching set source of the `ssts()` plugin. */
2043
2214
  declare class SstsSource extends SourceElement implements MediaSourceElement {
2044
2215
  #private;
@@ -2087,4 +2258,4 @@ interface SstsConfig {
2087
2258
  }
2088
2259
  /** @public The SSTS plugin, for `opts.plugins`. */
2089
2260
  declare const ssts: (config?: SstsConfig | undefined) => Plugin;
2090
- export { ABR as $, CONNECTION_CAPACITY as A, Capabilities as B, TimelineEvent as C, formatMsfUrl as Ct, SinkElement as D, ElementEvents as E, PadProperties as F, ElementDefinition as G, CapabilityBundles as H, PadSignal as I, SinkElementDefinition as J, Identifiers as K, ElementContext as L, PadEvent as M, PadItem as N, SourceElement as O, PadOutput as P, hasInterface as Q, ElementLoadRequest as R, CatalogElement as S, TimeRange as St, BaseElement as T, CapabilityCode as U, Capability as V, DEFAULT_PRIORITY as W, TransformElementDefinition as X, SourceElementDefinition as Y, defineElement as Z, Feature as _, PlayerError as _t, abr as a, MediaSinkElement as at, definePlugin as b, LocationRange as bt, liveBuffer as c, Rendition as ct, MOQtailPlayerOptions as d, TimelineReader as dt, CatalogReader as et, PlayerEvents as f, Catalog as ft, BufferController as g, InitData as gt, AbrController as h, MediaTimelineTemplate as ht, SstsSource as i, MEDIA_SOURCE as it, Pad as j, TransformElement as k, MSE as l, RequestHooks as lt, PlayerState as m, CatalogTrack as mt, ssts as n, InterfaceKey as nt, DefaultAbrController as o, MediaSourceElement as ot, StreamType as p, CatalogJson as pt, Provided as q, SSTS_ALGORITHMS as r, MEDIA_SINK as rt, LiveBufferConfig as s, MediaSourceOptions as st, SstsConfig as t, ElementInterfaces as tt, MOQtailPlayer as u, SwitchingSetOptions as ut, Plugin as v, PlayerErrorCategory as vt, TimelineRecord as w, parseMsfUrl as wt, MSEOptions as x, MsfSource as xt, PluginDefinition as y, PlayerErrorCode as yt, PlayerHandle as z };
2261
+ export { ElementDefinition as $, CatalogElement as A, TimeRange as At, PadEvent as B, AbrController as C, MediaTimelineTemplate as Ct, PluginDefinition as D, PlayerErrorCode as Dt, Plugin as E, PlayerErrorCategory as Et, SinkElement as F, ElementContext as G, PadOutput as H, SourceElement as I, Capabilities as J, ElementLoadRequest as K, TransformElement as L, TimelineRecord as M, parseMsfUrl as Mt, BaseElement as N, definePlugin as O, LocationRange as Ot, ElementEvents as P, DEFAULT_PRIORITY as Q, CONNECTION_CAPACITY as R, PlayerState as S, CatalogTrack as St, Feature as T, PlayerError as Tt, PadProperties as U, PadItem as V, PadSignal as W, CapabilityBundles as X, Capability as Y, CapabilityCode as Z, MSE as _, RequestHooks as _t, MlAbrConfig as a, defineElement as at, PlayerEvents as b, Catalog as bt, MlAbrController as c, CatalogReader as ct, Observation as d, MEDIA_SINK as dt, Identifiers as et, LiveBufferConfig as f, MEDIA_SOURCE as ft, rangeAt as g, Rendition as gt, followData as h, MediaSourceOptions as ht, SstsSource as i, TransformElementDefinition as it, TimelineEvent as j, formatMsfUrl as jt, MSEOptions as k, MsfSource as kt, ModelBlob as l, ElementInterfaces as lt, eachClient as m, MediaSourceElement as mt, ssts as n, SinkElementDefinition as nt, abr as o, hasInterface as ot, liveBuffer as p, MediaSinkElement as pt, PlayerHandle as q, SSTS_ALGORITHMS as r, SourceElementDefinition as rt, Decision as s, ABR as st, SstsConfig as t, Provided as tt, Action as u, InterfaceKey as ut, MOQtailPlayer as v, SwitchingSetOptions as vt, BufferController as w, InitData as wt, StreamType as x, CatalogJson as xt, MOQtailPlayerOptions as y, TimelineReader as yt, Pad as z };