@mebius-io/web 0.6.2 → 0.7.0

package/dist/index.d.cts

@@ -34,6 +34,21 @@ interface MebiusConnectOptions {
      * The app secret must never be embedded in client code.
      */
     token: string;
+    /**
+     * Called when the current token is about to expire, to mint the next one.
+     * Return a fresh token from the same backend endpoint that produced `token`.
+     *
+     * WITHOUT this, a connection lives exactly as long as its token: Mebius emits
+     * `TOKEN_EXPIRED` at that moment and playback stops. That is fine for a short
+     * watch and wrong for anything unattended — a stream left running overnight,
+     * a lobby screen, a 24/7 broadcast — where nobody is there to reconnect.
+     *
+     * WITH it, Mebius refreshes ahead of expiry and keeps the session going
+     * indefinitely; a `"token-refreshed"` event is emitted each time. If the call
+     * fails it is retried with backoff until the old token genuinely expires, so a
+     * brief backend blip costs nothing.
+     */
+    getToken?: () => string | Promise<string>;
     /**
      * The `deliveries` list your backend received together with the token. Pass it
      * through as-is and Mebius will pick the best route for each viewer's device,
@@ -84,6 +99,28 @@ type PlaybackMode = "auto" | "low-latency" | "balanced" | "scale";
 interface PlayerOptions {
     /** Defaults to `"auto"` — let Mebius choose per viewer. */
     mode?: PlaybackMode;
+    /**
+     * How much delay to trade for smoothness, in milliseconds. Higher is steadier.
+     *
+     * Mebius holds roughly this much video ahead of the picture. That buffer is
+     * what absorbs an unsteady network: when a piece of video arrives late or has
+     * to be re-sent, it still lands before its turn to be shown, and the viewer
+     * sees nothing. With too small a buffer the same event freezes the picture —
+     * and a freeze is not brief, because video can only resume at the next
+     * complete frame, typically a second or two later. Small buffers therefore do
+     * not produce small glitches; they produce multi-second stalls.
+     *
+     * Pick from the viewing experience, not the number:
+     *   - `~300` (default on the real-time route) — conversational: co-hosts, PK
+     *     battles, anything where people talk back and delay is felt.
+     *   - `1500`-`3000` — watching: screen shares, presentations, long unattended
+     *     broadcasts. Costs a couple of seconds nobody notices and removes the
+     *     stalls everybody notices.
+     *
+     * Applies to whichever route serves the viewer, so the trade you choose holds
+     * even when Mebius falls back to another one.
+     */
+    targetLatencyMs?: number;
 }
 /**
  * Where a player renders video: a `<video>` element, or a CSS selector that
@@ -120,8 +157,25 @@ interface PlaybackStats {
     bitrateKbps?: number;
     /** Frames per second currently being rendered, when known. */
     framesPerSecond?: number;
-    /** Estimated end-to-end latency in milliseconds, if known. */
+    /**
+     * How far behind the source the picture is running, in milliseconds, when the
+     * route can measure it. This is the delay the viewer actually experiences.
+     */
     latencyMs?: number;
+    /** Round-trip time to the serving edge in milliseconds, if known. */
+    rttMs?: number;
+    /** Percentage of video that had to be re-sent or was lost, if known. */
+    packetLossPct?: number;
+    /**
+     * Milliseconds the picture was frozen since the previous reading, when the
+     * route measures this itself.
+     *
+     * Some routes must: a real-time connection can sit frozen for seconds while
+     * the connection reports perfect health and the video element raises no
+     * event, so a freeze there is invisible from the outside. A route that leaves
+     * this absent is one whose stalls are already visible to the player.
+     */
+    freezeMs?: number;
 }
 /** Options for {@link MebiusClient.createCaptions}. */
 interface CaptionsOptions {
@@ -187,6 +241,13 @@ type ClientEventMap = {
         reason?: string;
     };
     error: MebiusError;
+    /**
+     * A fresh access token was fetched and is now in use. Purely informational —
+     * playback and publishing continue uninterrupted; nothing needs to be done in
+     * response. Useful for logging that an unattended long-running session is
+     * still renewing itself.
+     */
+    "token-refreshed": void;
 };
 /** Event payloads emitted by a broadcaster. */
 type BroadcasterEventMap = {
@@ -248,8 +309,19 @@ interface SessionResult {
 }
 declare class SignalingClient {
     private readonly gateway;
-    private readonly token;
+    private token;
     constructor(gateway: string, token: string);
+    /**
+     * Swap in a freshly-minted access token.
+     *
+     * Every URL this class builds is built at call time, so a session that starts
+     * a new request after this point uses the new token with no further wiring.
+     * What it does NOT reach is a request already in flight or a media URL another
+     * library has memorised — see the scale route's loader for that half.
+     */
+    setToken(token: string): void;
+    /** The current access token, for transports that must re-stamp their own URLs. */
+    accessToken(): string;
     private base;
     private headers;
     /** Append the access token as a query param (the form the engine enforces). */
@@ -379,13 +451,15 @@ declare class MebiusPlayer extends TypedEmitter<PlayerEventMap> {
     setVolume(volume: number): void;
     /**
      * Wall-clock time (Unix ms) currently on screen, or `null` when the active
-     * route cannot produce one (HTTP-FLV, WHEP — see {@link ViewTransport}).
+     * route cannot produce one. A real-time route carries no wall clock at all,
+     * and a segmented route has none until its first timestamped segment arrives
+     * (see {@link ViewTransport}).
      *
      * This is what {@link MebiusClient.createCaptions} compares against a
      * segment's `epochMs` to know when it is due. Delegating to the transport
      * rather than reading the element directly is what keeps this correct across
-     * a route failover: the player may switch from HLS to FLV mid-session, and
-     * the clock source has to follow.
+     * a route failover: the player may change route mid-session, and the clock
+     * source has to follow.
      */
     currentEpochMs(): number | null;
     private attach;
@@ -464,17 +538,36 @@ declare class MebiusCaptions extends TypedEmitter<CaptionsEventMap> {
  * create broadcasters and players from it.
  */
 declare class MebiusClient extends TypedEmitter<ClientEventMap> {
-    private readonly token;
+    private token;
     private readonly deliveries;
     private readonly telemetry;
     private readonly userId?;
+    private readonly getToken?;
     private readonly signaling;
     private expiryTimer;
     private connected;
+    private refreshFailures;
     /** @internal */
-    constructor(config: MebiusInitOptions, token: string, deliveries?: readonly MebiusDelivery[], telemetry?: TelemetryTarget | null, userId?: string | undefined);
+    constructor(config: MebiusInitOptions, token: string, deliveries?: readonly MebiusDelivery[], telemetry?: TelemetryTarget | null, userId?: string | undefined, getToken?: (() => string | Promise<string>) | undefined);
     /** @internal Called by {@link Mebius.connect}. */
     open(): void;
+    /**
+     * Arm whatever has to happen as this token approaches its expiry: renew it if
+     * the app gave us a way to, otherwise report that the session is over.
+     *
+     * Renewing is what makes an unattended session possible at all. The gateway
+     * checks the token on every media request, so without a fresh one playback
+     * stops the moment it expires — no matter how healthy the stream is.
+     */
+    private scheduleTokenWork;
+    private refreshToken;
+    /**
+     * A failed refresh is not a dead session: the current token is still valid
+     * until `expiryMs`, and the viewer is still watching. Retry inside that window
+     * and only report expiry once it has actually run out.
+     */
+    private onRefreshFailed;
+    private clearTimer;
     /** Create a broadcaster bound to this connection. */
     createBroadcaster(options?: BroadcasterOptions): MebiusBroadcaster;
     /** Create a player bound to this connection. */

package/dist/index.d.ts

@@ -34,6 +34,21 @@ interface MebiusConnectOptions {
      * The app secret must never be embedded in client code.
      */
     token: string;
+    /**
+     * Called when the current token is about to expire, to mint the next one.
+     * Return a fresh token from the same backend endpoint that produced `token`.
+     *
+     * WITHOUT this, a connection lives exactly as long as its token: Mebius emits
+     * `TOKEN_EXPIRED` at that moment and playback stops. That is fine for a short
+     * watch and wrong for anything unattended — a stream left running overnight,
+     * a lobby screen, a 24/7 broadcast — where nobody is there to reconnect.
+     *
+     * WITH it, Mebius refreshes ahead of expiry and keeps the session going
+     * indefinitely; a `"token-refreshed"` event is emitted each time. If the call
+     * fails it is retried with backoff until the old token genuinely expires, so a
+     * brief backend blip costs nothing.
+     */
+    getToken?: () => string | Promise<string>;
     /**
      * The `deliveries` list your backend received together with the token. Pass it
      * through as-is and Mebius will pick the best route for each viewer's device,
@@ -84,6 +99,28 @@ type PlaybackMode = "auto" | "low-latency" | "balanced" | "scale";
 interface PlayerOptions {
     /** Defaults to `"auto"` — let Mebius choose per viewer. */
     mode?: PlaybackMode;
+    /**
+     * How much delay to trade for smoothness, in milliseconds. Higher is steadier.
+     *
+     * Mebius holds roughly this much video ahead of the picture. That buffer is
+     * what absorbs an unsteady network: when a piece of video arrives late or has
+     * to be re-sent, it still lands before its turn to be shown, and the viewer
+     * sees nothing. With too small a buffer the same event freezes the picture —
+     * and a freeze is not brief, because video can only resume at the next
+     * complete frame, typically a second or two later. Small buffers therefore do
+     * not produce small glitches; they produce multi-second stalls.
+     *
+     * Pick from the viewing experience, not the number:
+     *   - `~300` (default on the real-time route) — conversational: co-hosts, PK
+     *     battles, anything where people talk back and delay is felt.
+     *   - `1500`-`3000` — watching: screen shares, presentations, long unattended
+     *     broadcasts. Costs a couple of seconds nobody notices and removes the
+     *     stalls everybody notices.
+     *
+     * Applies to whichever route serves the viewer, so the trade you choose holds
+     * even when Mebius falls back to another one.
+     */
+    targetLatencyMs?: number;
 }
 /**
  * Where a player renders video: a `<video>` element, or a CSS selector that
@@ -120,8 +157,25 @@ interface PlaybackStats {
     bitrateKbps?: number;
     /** Frames per second currently being rendered, when known. */
     framesPerSecond?: number;
-    /** Estimated end-to-end latency in milliseconds, if known. */
+    /**
+     * How far behind the source the picture is running, in milliseconds, when the
+     * route can measure it. This is the delay the viewer actually experiences.
+     */
     latencyMs?: number;
+    /** Round-trip time to the serving edge in milliseconds, if known. */
+    rttMs?: number;
+    /** Percentage of video that had to be re-sent or was lost, if known. */
+    packetLossPct?: number;
+    /**
+     * Milliseconds the picture was frozen since the previous reading, when the
+     * route measures this itself.
+     *
+     * Some routes must: a real-time connection can sit frozen for seconds while
+     * the connection reports perfect health and the video element raises no
+     * event, so a freeze there is invisible from the outside. A route that leaves
+     * this absent is one whose stalls are already visible to the player.
+     */
+    freezeMs?: number;
 }
 /** Options for {@link MebiusClient.createCaptions}. */
 interface CaptionsOptions {
@@ -187,6 +241,13 @@ type ClientEventMap = {
         reason?: string;
     };
     error: MebiusError;
+    /**
+     * A fresh access token was fetched and is now in use. Purely informational —
+     * playback and publishing continue uninterrupted; nothing needs to be done in
+     * response. Useful for logging that an unattended long-running session is
+     * still renewing itself.
+     */
+    "token-refreshed": void;
 };
 /** Event payloads emitted by a broadcaster. */
 type BroadcasterEventMap = {
@@ -248,8 +309,19 @@ interface SessionResult {
 }
 declare class SignalingClient {
     private readonly gateway;
-    private readonly token;
+    private token;
     constructor(gateway: string, token: string);
+    /**
+     * Swap in a freshly-minted access token.
+     *
+     * Every URL this class builds is built at call time, so a session that starts
+     * a new request after this point uses the new token with no further wiring.
+     * What it does NOT reach is a request already in flight or a media URL another
+     * library has memorised — see the scale route's loader for that half.
+     */
+    setToken(token: string): void;
+    /** The current access token, for transports that must re-stamp their own URLs. */
+    accessToken(): string;
     private base;
     private headers;
     /** Append the access token as a query param (the form the engine enforces). */
@@ -379,13 +451,15 @@ declare class MebiusPlayer extends TypedEmitter<PlayerEventMap> {
     setVolume(volume: number): void;
     /**
      * Wall-clock time (Unix ms) currently on screen, or `null` when the active
-     * route cannot produce one (HTTP-FLV, WHEP — see {@link ViewTransport}).
+     * route cannot produce one. A real-time route carries no wall clock at all,
+     * and a segmented route has none until its first timestamped segment arrives
+     * (see {@link ViewTransport}).
      *
      * This is what {@link MebiusClient.createCaptions} compares against a
      * segment's `epochMs` to know when it is due. Delegating to the transport
      * rather than reading the element directly is what keeps this correct across
-     * a route failover: the player may switch from HLS to FLV mid-session, and
-     * the clock source has to follow.
+     * a route failover: the player may change route mid-session, and the clock
+     * source has to follow.
      */
     currentEpochMs(): number | null;
     private attach;
@@ -464,17 +538,36 @@ declare class MebiusCaptions extends TypedEmitter<CaptionsEventMap> {
  * create broadcasters and players from it.
  */
 declare class MebiusClient extends TypedEmitter<ClientEventMap> {
-    private readonly token;
+    private token;
     private readonly deliveries;
     private readonly telemetry;
     private readonly userId?;
+    private readonly getToken?;
     private readonly signaling;
     private expiryTimer;
     private connected;
+    private refreshFailures;
     /** @internal */
-    constructor(config: MebiusInitOptions, token: string, deliveries?: readonly MebiusDelivery[], telemetry?: TelemetryTarget | null, userId?: string | undefined);
+    constructor(config: MebiusInitOptions, token: string, deliveries?: readonly MebiusDelivery[], telemetry?: TelemetryTarget | null, userId?: string | undefined, getToken?: (() => string | Promise<string>) | undefined);
     /** @internal Called by {@link Mebius.connect}. */
     open(): void;
+    /**
+     * Arm whatever has to happen as this token approaches its expiry: renew it if
+     * the app gave us a way to, otherwise report that the session is over.
+     *
+     * Renewing is what makes an unattended session possible at all. The gateway
+     * checks the token on every media request, so without a fresh one playback
+     * stops the moment it expires — no matter how healthy the stream is.
+     */
+    private scheduleTokenWork;
+    private refreshToken;
+    /**
+     * A failed refresh is not a dead session: the current token is still valid
+     * until `expiryMs`, and the viewer is still watching. Retry inside that window
+     * and only report expiry once it has actually run out.
+     */
+    private onRefreshFailed;
+    private clearTimer;
     /** Create a broadcaster bound to this connection. */
     createBroadcaster(options?: BroadcasterOptions): MebiusBroadcaster;
     /** Create a player bound to this connection. */