@mebius-io/web 0.6.2 → 0.7.0

package/dist/index.cjs

@@ -264,10 +264,21 @@ function resetVideoElement(video) {
 }
 
 // src/internal/ll-view-transport.ts
+var DEFAULT_REALTIME_TARGET_MS = 300;
+function holdBuffer(receiver, targetMs) {
+  const r = receiver;
+  try {
+    if ("jitterBufferTarget" in r) r.jitterBufferTarget = targetMs;
+    if ("playoutDelayHint" in r) r.playoutDelayHint = targetMs / 1e3;
+  } catch {
+  }
+}
 var WhepViewTransport = class {
-  constructor(signaling) {
+  constructor(signaling, targetLatencyMs = DEFAULT_REALTIME_TARGET_MS) {
     this.signaling = signaling;
+    this.targetLatencyMs = targetLatencyMs;
     this.kind = "whep";
+    this.cursor = null;
     this.pc = null;
     this.resourceUrl = null;
     this.endedCb = null;
@@ -291,6 +302,7 @@ var WhepViewTransport = class {
     pc.addTransceiver("video", { direction: "recvonly" });
     pc.addTransceiver("audio", { direction: "recvonly" });
     pc.ontrack = (ev) => {
+      holdBuffer(ev.receiver, this.targetLatencyMs);
       remote.addTrack(ev.track);
       video.srcObject = remote;
       void playWithAutoplayFallback(video).then((o) => {
@@ -318,6 +330,7 @@ var WhepViewTransport = class {
     await pc.setRemoteDescription({ type: "answer", sdp: answer });
   }
   async stop() {
+    this.cursor = null;
     await this.signaling.deleteResource(this.resourceUrl);
     this.resourceUrl = null;
     this.pc?.close();
@@ -325,24 +338,59 @@ var WhepViewTransport = class {
     if (this.video) resetVideoElement(this.video);
     this.video = null;
   }
+  /**
+   * Read what the connection actually did since the last reading.
+   *
+   * This route needs to measure its own freezes, because nothing else can. A
+   * frozen real-time picture still reports a healthy connection and raises no
+   * event on the video element — so from the outside the session looks flawless
+   * while the viewer stares at a still frame. Every freeze on this route used to
+   * be recorded as zero, which is why the problem could be felt and never seen.
+   */
   async getStats() {
     if (!this.pc) return null;
     const report = await this.pc.getStats();
-    let bitrateKbps = 0;
-    let framesPerSecond = 0;
-    let latencyMs;
+    let framesPerSecond;
+    let freezeS = 0;
+    let packetsLost = 0;
+    let packetsReceived = 0;
+    let bytesReceived = 0;
+    let bufferDelayS = 0;
+    let bufferEmitted = 0;
+    let rttMs;
     report.forEach((stat) => {
-      if (stat.type === "inbound-rtp") {
-        if (typeof stat.framesPerSecond === "number") framesPerSecond = stat.framesPerSecond;
-        if (typeof stat.jitter === "number") latencyMs = Math.round(stat.jitter * 1e3);
+      if (stat.type === "inbound-rtp" && stat.kind === "video") {
+        const v = stat;
+        if (typeof v.framesPerSecond === "number") framesPerSecond = v.framesPerSecond;
+        if (typeof v.totalFreezesDuration === "number") freezeS = v.totalFreezesDuration;
+        if (typeof v.packetsLost === "number") packetsLost = v.packetsLost;
+        if (typeof v.packetsReceived === "number") packetsReceived = v.packetsReceived;
+        if (typeof v.bytesReceived === "number") bytesReceived = v.bytesReceived;
+        if (typeof v.jitterBufferDelay === "number") bufferDelayS = v.jitterBufferDelay;
+        if (typeof v.jitterBufferEmittedCount === "number") bufferEmitted = v.jitterBufferEmittedCount;
       }
       if (stat.type === "candidate-pair" && stat.state === "succeeded") {
-        if (typeof stat.availableIncomingBitrate === "number") {
-          bitrateKbps = Math.round(stat.availableIncomingBitrate / 1e3);
-        }
+        const p = stat;
+        if (typeof p.currentRoundTripTime === "number") rttMs = Math.round(p.currentRoundTripTime * 1e3);
       }
     });
-    return { bitrateKbps, framesPerSecond, latencyMs };
+    const atMs = Date.now();
+    const previous = this.cursor;
+    this.cursor = { atMs, freezeS, packetsLost, packetsReceived, bytesReceived, bufferDelayS, bufferEmitted };
+    if (!previous) return { framesPerSecond, rttMs };
+    const elapsedS = Math.max(1e-3, (atMs - previous.atMs) / 1e3);
+    const deltaLost = Math.max(0, packetsLost - previous.packetsLost);
+    const deltaReceived = Math.max(0, packetsReceived - previous.packetsReceived);
+    const deltaEmitted = bufferEmitted - previous.bufferEmitted;
+    const heldMs = deltaEmitted > 0 ? (bufferDelayS - previous.bufferDelayS) / deltaEmitted * 1e3 : void 0;
+    return {
+      bitrateKbps: Math.round((bytesReceived - previous.bytesReceived) * 8 / elapsedS / 1e3),
+      framesPerSecond,
+      latencyMs: heldMs === void 0 ? void 0 : Math.round(heldMs + (rttMs !== void 0 ? rttMs / 2 : 0)),
+      rttMs,
+      packetLossPct: deltaLost + deltaReceived > 0 ? Number((deltaLost / (deltaLost + deltaReceived) * 100).toFixed(2)) : 0,
+      freezeMs: Math.max(0, Math.round((freezeS - previous.freezeS) * 1e3))
+    };
   }
 };
 
@@ -350,6 +398,19 @@ var WhepViewTransport = class {
 function retryWarmupNotFound(cfg, retryCount, res, retry) {
   return retry || retryCount < (cfg?.maxNumRetry ?? 0) && res?.code === 404;
 }
+var TOKEN_PARAM = /([?&]token=)[^&#]*/;
+function withCurrentToken(url, token) {
+  return url.replace(TOKEN_PARAM, (_match, prefix) => prefix + encodeURIComponent(token));
+}
+function tokenRestampingLoader(Hls, currentToken) {
+  const Base = Hls.DefaultConfig.loader;
+  return class TokenRestampingLoader extends Base {
+    load(context, config2, callbacks) {
+      context.url = withCurrentToken(context.url, currentToken());
+      super.load(context, config2, callbacks);
+    }
+  };
+}
 var HlsViewTransport = class {
   /**
    * deliveryPath, when given, is a gateway-relative path from the gateway's own
@@ -357,9 +418,10 @@ var HlsViewTransport = class {
    * origin one. Without it this falls back to the origin playlist, which is
    * still correct, just served from our own bandwidth.
    */
-  constructor(signaling, deliveryPath) {
+  constructor(signaling, deliveryPath, targetS) {
     this.signaling = signaling;
     this.deliveryPath = deliveryPath;
+    this.targetS = targetS;
     this.kind = "hls";
     this.hls = null;
     this.video = null;
@@ -399,6 +461,11 @@ var HlsViewTransport = class {
     }
     const hls = new Hls({
       maxLiveSyncPlaybackRate: 1.1,
+      loader: tokenRestampingLoader(Hls, () => this.signaling.accessToken()),
+      // Only when the app actually asked. Left alone, the library follows the
+      // playlist's own HOLD-BACK, which the server measured from the segments it
+      // is producing — a number guessed here would only override a real one.
+      ...this.targetS === void 0 ? {} : { liveSyncDuration: this.targetS },
       manifestLoadPolicy: {
         default: {
           maxTimeToFirstByteMs: 1e4,
@@ -468,8 +535,12 @@ var LIVE_FLV_CONFIG = {
   autoCleanupMinBackwardDuration: 10,
   reuseRedirectedURL: true
 };
-var MAX_DRIFT_S = 2;
-var EDGE_MARGIN_S = 0.4;
+var DEFAULT_BALANCED_TARGET_S = 2;
+var CATCH_UP_RATE = 1.05;
+var BUILD_UP_RATE = 0.98;
+var SEEK_AT = 4;
+var CATCH_UP_ABOVE = 1.5;
+var BUILD_UP_BELOW = 0.9;
 var AUDIO_RETRY_MS = 2500;
 var UPSTREAM_LATENCY_MS = 800;
 function stalledWithData(video, ms) {
@@ -487,17 +558,31 @@ function stalledWithData(video, ms) {
     video.addEventListener("timeupdate", onTime);
   });
 }
-function chaseLiveEdge(video) {
+function syncLiveEdge(video, targetS = DEFAULT_BALANCED_TARGET_S) {
   const ranges = video.buffered;
   if (ranges.length === 0) return;
   const edge = ranges.end(ranges.length - 1);
-  if (edge - video.currentTime <= MAX_DRIFT_S) return;
-  video.currentTime = edge - EDGE_MARGIN_S;
+  const drift = edge - video.currentTime;
+  if (drift > targetS * SEEK_AT) {
+    video.currentTime = edge - targetS;
+    video.playbackRate = 1;
+    return;
+  }
+  if (drift > targetS * CATCH_UP_ABOVE) {
+    video.playbackRate = CATCH_UP_RATE;
+    return;
+  }
+  if (drift < targetS * BUILD_UP_BELOW) {
+    video.playbackRate = BUILD_UP_RATE;
+    return;
+  }
+  video.playbackRate = 1;
 }
 var FlvViewTransport = class {
-  constructor(signaling, deliveryPath) {
+  constructor(signaling, deliveryPath, targetS = DEFAULT_BALANCED_TARGET_S) {
     this.signaling = signaling;
     this.deliveryPath = deliveryPath;
+    this.targetS = targetS;
     this.kind = "flv_js";
     this.player = null;
     this.video = null;
@@ -523,7 +608,7 @@ var FlvViewTransport = class {
     const { signal } = this.listeners;
     video.addEventListener("ended", () => this.endedCb?.(), { signal });
     video.addEventListener("waiting", () => this.bufferingCb?.(), { signal });
-    video.addEventListener("timeupdate", () => chaseLiveEdge(video), { signal });
+    video.addEventListener("timeupdate", () => syncLiveEdge(video, this.targetS), { signal });
     let mod;
     try {
       mod = await import("flv.js");
@@ -567,6 +652,7 @@ var FlvViewTransport = class {
     this.listeners = null;
     this.teardownPlayer();
     if (this.video) {
+      this.video.playbackRate = 1;
       this.video.removeAttribute("src");
       this.video.load();
     }
@@ -632,18 +718,29 @@ var KIND_LOCAL = "local";
 function canPlayBuffered() {
   return typeof MediaSource !== "undefined";
 }
-function transportFor(kind, path, signaling) {
-  if (kind === KIND_FAST) return canPlayBuffered() ? new FlvViewTransport(signaling, path) : null;
-  if (kind === KIND_WIDE || kind === KIND_LOCAL) return new HlsViewTransport(signaling, path);
+function transportFor(kind, path, signaling, targetLatencyMs) {
+  const targetS = targetLatencyMs === void 0 ? void 0 : targetLatencyMs / 1e3;
+  if (kind === KIND_FAST)
+    return canPlayBuffered() ? new FlvViewTransport(signaling, path, targetS) : null;
+  if (kind === KIND_WIDE || kind === KIND_LOCAL)
+    return new HlsViewTransport(signaling, path, targetS);
   return null;
 }
-function createViewCandidates(mode, signaling, deliveries = []) {
-  const fromGateway = (kinds) => deliveries.filter((d) => kinds.includes(d.kind)).map((d) => transportFor(d.kind, d.path, signaling)).filter((t) => t !== null);
-  const originFallback = new HlsViewTransport(signaling);
+function createViewCandidates(mode, signaling, deliveries = [], targetLatencyMs) {
+  const fromGateway = (kinds) => deliveries.filter((d) => kinds.includes(d.kind)).map((d) => transportFor(d.kind, d.path, signaling, targetLatencyMs)).filter((t) => t !== null);
+  const originFallback = new HlsViewTransport(
+    signaling,
+    void 0,
+    targetLatencyMs === void 0 ? void 0 : targetLatencyMs / 1e3
+  );
   const allKinds = [KIND_FAST, KIND_WIDE, KIND_LOCAL];
   switch (mode) {
     case "low-latency":
-      return [new WhepViewTransport(signaling), ...fromGateway(allKinds), originFallback];
+      return [
+        new WhepViewTransport(signaling, targetLatencyMs ?? DEFAULT_REALTIME_TARGET_MS),
+        ...fromGateway(allKinds),
+        originFallback
+      ];
     case "balanced":
       return [...fromGateway(allKinds), originFallback];
     case "scale":
@@ -654,7 +751,7 @@ function createViewCandidates(mode, signaling, deliveries = []) {
 }
 
 // src/internal/telemetry.ts
-var SDK_VERSION = "web/0.4.8";
+var SDK_VERSION = true ? `web/${"0.7.0"}` : "web/dev";
 var FLUSH_INTERVAL_MS = 15e3;
 var MAX_BATCH = 64;
 function describeDevice() {
@@ -1062,7 +1159,12 @@ var MebiusPlayer = class extends TypedEmitter {
     this.freeze = new FreezeClock();
     /** Cancels element listeners bound for the lifetime of one play(). */
     this.elementListeners = null;
-    this.candidates = createViewCandidates(options.mode ?? "auto", signaling, deliveries);
+    this.candidates = createViewCandidates(
+      options.mode ?? "auto",
+      signaling,
+      deliveries,
+      options.targetLatencyMs
+    );
   }
   /** Start playing `streamId` into the given video element or selector. */
   async play(streamId, viewTarget) {
@@ -1159,13 +1261,15 @@ var MebiusPlayer = class extends TypedEmitter {
   }
   /**
    * 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() {
     return this.transport?.playheadEpochMs?.() ?? null;
@@ -1189,9 +1293,11 @@ var MebiusPlayer = class extends TypedEmitter {
   startStats() {
     this.statsTimer = setInterval(async () => {
       const stats = await this.transport?.getStats();
-      const freezeMs = this.freeze.take();
+      const elementFreezeMs = this.freeze.take();
       if (!stats) {
-        if (freezeMs > 0) this.reporter?.add({ ts: Math.floor(Date.now() / 1e3), freezeMs });
+        if (elementFreezeMs > 0) {
+          this.reporter?.add({ ts: Math.floor(Date.now() / 1e3), freezeMs: elementFreezeMs });
+        }
         return;
       }
       this.emit("stats", stats);
@@ -1199,7 +1305,9 @@ var MebiusPlayer = class extends TypedEmitter {
         ts: Math.floor(Date.now() / 1e3),
         bitrateKbps: stats.bitrateKbps,
         fps: stats.framesPerSecond,
-        freezeMs
+        rttMs: stats.rttMs,
+        packetLossPct: stats.packetLossPct,
+        freezeMs: elementFreezeMs + (stats.freezeMs ?? 0)
       });
     }, STATS_INTERVAL_MS2);
   }
@@ -1230,6 +1338,21 @@ var SignalingClient = class {
     this.gateway = gateway;
     this.token = token;
   }
+  /**
+   * 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) {
+    this.token = token;
+  }
+  /** The current access token, for transports that must re-stamp their own URLs. */
+  accessToken() {
+    return this.token;
+  }
   base() {
     return this.gateway.replace(/\/+$/, "");
   }
@@ -1350,16 +1473,21 @@ function readToken(token) {
 }
 
 // src/client.ts
+var REFRESH_MARGIN_MS = 6e4;
+var REFRESH_RETRY_BASE_MS = 2e3;
+var REFRESH_RETRY_MAX_MS = 3e4;
 var MebiusClient = class extends TypedEmitter {
   /** @internal */
-  constructor(config2, token, deliveries = [], telemetry = null, userId) {
+  constructor(config2, token, deliveries = [], telemetry = null, userId, getToken) {
     super();
     this.token = token;
     this.deliveries = deliveries;
     this.telemetry = telemetry;
     this.userId = userId;
+    this.getToken = getToken;
     this.expiryTimer = null;
     this.connected = false;
+    this.refreshFailures = 0;
     this.signaling = new SignalingClient(config2.gateway, token);
   }
   /** @internal Called by {@link Mebius.connect}. */
@@ -1371,13 +1499,82 @@ var MebiusClient = class extends TypedEmitter {
       return;
     }
     this.connected = true;
-    if (expiresAtMs !== null) {
+    this.scheduleTokenWork(expiresAtMs);
+    queueMicrotask(() => this.emit("connected", void 0));
+  }
+  /**
+   * 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.
+   */
+  scheduleTokenWork(expiresAtMs) {
+    this.clearTimer();
+    if (expiresAtMs === null) return;
+    const remaining = expiresAtMs - Date.now();
+    if (!this.getToken) {
       this.expiryTimer = setTimeout(
         () => this.emit("error", mebiusError("TOKEN_EXPIRED")),
-        Math.max(0, expiresAtMs - now)
+        Math.max(0, remaining)
       );
+      return;
     }
-    queueMicrotask(() => this.emit("connected", void 0));
+    this.expiryTimer = setTimeout(
+      () => void this.refreshToken(expiresAtMs),
+      Math.max(0, remaining - REFRESH_MARGIN_MS)
+    );
+  }
+  async refreshToken(previousExpiryMs) {
+    if (!this.connected || !this.getToken) return;
+    let next;
+    try {
+      next = await this.getToken();
+    } catch (cause) {
+      this.onRefreshFailed(previousExpiryMs, cause);
+      return;
+    }
+    if (!this.connected) return;
+    const { expiresAtMs } = readToken(next);
+    if (expiresAtMs !== null && expiresAtMs <= previousExpiryMs) {
+      this.emit(
+        "error",
+        mebiusError("TOKEN_EXPIRED", "Mebius token refresh returned a token that is not newer.")
+      );
+      return;
+    }
+    this.refreshFailures = 0;
+    this.token = next;
+    this.signaling.setToken(next);
+    this.emit("token-refreshed", void 0);
+    this.scheduleTokenWork(expiresAtMs);
+  }
+  /**
+   * 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.
+   */
+  onRefreshFailed(expiryMs, cause) {
+    const remaining = expiryMs - Date.now();
+    if (remaining <= 0) {
+      this.emit("error", mebiusError("TOKEN_EXPIRED", void 0, cause));
+      return;
+    }
+    this.refreshFailures += 1;
+    const backoff = Math.min(
+      REFRESH_RETRY_MAX_MS,
+      REFRESH_RETRY_BASE_MS * 2 ** (this.refreshFailures - 1)
+    );
+    this.clearTimer();
+    this.expiryTimer = setTimeout(
+      () => void this.refreshToken(expiryMs),
+      Math.min(backoff, remaining)
+    );
+  }
+  clearTimer() {
+    if (this.expiryTimer) clearTimeout(this.expiryTimer);
+    this.expiryTimer = null;
   }
   /** Create a broadcaster bound to this connection. */
   createBroadcaster(options = {}) {
@@ -1422,8 +1619,7 @@ var MebiusClient = class extends TypedEmitter {
   }
   /** Close the connection and release resources. */
   disconnect(reason) {
-    if (this.expiryTimer) clearTimeout(this.expiryTimer);
-    this.expiryTimer = null;
+    this.clearTimer();
     this.connected = false;
     this.emit("disconnected", { reason });
     this.removeAllListeners();
@@ -1452,7 +1648,14 @@ var Mebius = {
     }
     if (!options.token) throw mebiusError("UNKNOWN", "Mebius.connect requires a token.");
     const telemetry = options.beaconToken && options.beaconUrl ? { token: options.beaconToken, url: options.beaconUrl } : null;
-    const client = new MebiusClient(config, options.token, options.deliveries ?? [], telemetry, options.userId);
+    const client = new MebiusClient(
+      config,
+      options.token,
+      options.deliveries ?? [],
+      telemetry,
+      options.userId,
+      options.getToken
+    );
     client.open();
     return client;
   },