@mebius-io/web 0.4.8 → 0.5.0

package/dist/index.d.cts

@@ -123,6 +123,37 @@ interface PlaybackStats {
     /** Estimated end-to-end latency in milliseconds, if known. */
     latencyMs?: number;
 }
+/** Options for {@link MebiusClient.createCaptions}. */
+interface CaptionsOptions {
+    /**
+     * Which translation to read from each segment, e.g. `"id"`. Must match a
+     * `targetLangs` entry your backend passed to `captions/start` — the engine
+     * only ever sends the translations that session produced.
+     */
+    lang: string;
+}
+/**
+ * One caption segment, timed against a wall clock so it can be compared to
+ * {@link MebiusPlayer.currentEpochMs}.
+ */
+interface CaptionSegment {
+    /** Stable id for this segment. A later revision replaces it in place. */
+    segmentId: string;
+    /** Revision counter. Only the highest-`rev` copy of a `segmentId` is kept. */
+    rev: number;
+    /** `"interim"` or `"final"`. Interim only arrives if the session enabled it. */
+    state: "interim" | "final";
+    /** Unix ms the audio was actually spoken. Compare against the playhead. */
+    epochMs: number;
+    /** How long the segment should stay on screen once due, in ms. */
+    durationMs: number;
+    /** Original transcript, in the source language. */
+    text: string;
+    /** The requested {@link CaptionsOptions.lang} translation, if produced yet. */
+    translation?: string;
+    /** Always `true`. Render a machine-generated indicator — never as a direct quote. */
+    machineGenerated: true;
+}
 /** Canonical Mebius error codes surfaced to your app. */
 type MebiusErrorCode = "TOKEN_EXPIRED" | "PERMISSION_DENIED" | "CONNECTION_FAILED" | "NOT_CONNECTED" | "STREAM_NOT_FOUND" | "UNKNOWN";
 
@@ -167,6 +198,17 @@ type PlayerEventMap = {
     ended: void;
     stats: PlaybackStats;
 };
+/** Event payloads emitted by {@link MebiusCaptions}. */
+type CaptionsEventMap = {
+    /** A segment became due (its `epochMs` reached the playhead). Render it. */
+    segment: CaptionSegment;
+    /** A previously-shown segment aged out (playhead passed its window). Clear it. */
+    cleared: {
+        segmentId: string;
+    };
+    /** The SSE connection dropped. `EventSource` reconnects on its own. */
+    error: void;
+};
 type Listener<T> = (payload: T) => void;
 /**
  * A tiny strongly-typed event emitter. `EventMap` maps each event name to its
@@ -216,6 +258,12 @@ declare class SignalingClient {
     deliveryUrl(path: string): string;
     /** Playlist URL for scale-mode playback. */
     scalePlaylistUrl(streamId: string): string;
+    /**
+     * Realtime captions SSE URL. Same play token as media — the engine's
+     * `PlayVerifier` gates both, so a viewer who can watch the stream can already
+     * read its captions with zero extra credential.
+     */
+    captionsUrl(streamId: string, lang: string): string;
     private pathFor;
     /**
      * Run the session offer/answer exchange. Throws a {@link MebiusError} with a
@@ -315,11 +363,64 @@ declare class MebiusPlayer extends TypedEmitter<PlayerEventMap> {
      * drags to zero also survives a later unmute at the element level.
      */
     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}).
+     *
+     * 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.
+     */
+    currentEpochMs(): number | null;
     private attach;
     private startStats;
     private stopStats;
 }
 
+/**
+ * Realtime captions — subscribes to the engine's caption SSE feed and emits
+ * segments on the video's own timeline, not on arrival order.
+ *
+ * The engine (mebius-stream-engine, `internal/caption`) does the ASR/translate
+ * work and starts sending segments the moment a sentence finishes — which is
+ * BEFORE the viewer's player, sitting behind the live edge by however much its
+ * transport buffers, has shown the matching frame. Rendering on arrival would
+ * show the caption before the streamer says it. So every segment is buffered by
+ * `epochMs` (when the audio was actually spoken, a wall clock) and released only
+ * once {@link MebiusPlayer.currentEpochMs} reaches it. See
+ * mebius-stream-engine/docs/INTEGRATION.md §6.
+ */
+
+/**
+ * Subscribes to one stream's caption feed. Create with
+ * {@link MebiusClient.createCaptions}, `start()` it, and listen for `"segment"`
+ * / `"cleared"`.
+ *
+ * Starting the caption SESSION (`captions/start`, which spends money) is a
+ * separate, server-side call — this class only ever reads the feed a session
+ * already produces. That split is deliberate: the control endpoint needs an API
+ * key, which must never reach a browser.
+ */
+declare class MebiusCaptions extends TypedEmitter<CaptionsEventMap> {
+    private readonly signaling;
+    private readonly player;
+    private readonly opts;
+    private es;
+    private timer;
+    private readonly pending;
+    private readonly shown;
+    /** @internal */
+    constructor(signaling: SignalingClient, player: MebiusPlayer, opts: CaptionsOptions);
+    /** Open the SSE connection and begin emitting segments for `streamId`. */
+    start(streamId: string): void;
+    /** Close the connection and drop all buffered segments. */
+    stop(): void;
+    private onFrame;
+    private tick;
+}
+
 /**
  * A live connection to Mebius. Obtain one from {@link Mebius.connect}, then
  * create broadcasters and players from it.
@@ -352,6 +453,19 @@ declare class MebiusClient extends TypedEmitter<ClientEventMap> {
      * black frame to a live audience, so it belongs here rather than in every app.
      */
     createMonitor(): MebiusPlayer;
+    /**
+     * Subscribe to a stream's realtime captions.
+     *
+     * Reads the same feed a session already produces — it does NOT start the
+     * caption session itself. `captions/start` spends money and requires an API
+     * key, so it belongs to your own backend (see
+     * mebius-stream-engine/docs/API.md §5.1), called once when you want captions
+     * on for a stream. This only ever consumes what that call turned on.
+     *
+     * `player` must be the one showing `streamId`: captions are timed against its
+     * playhead, and a mismatched player would compare against the wrong clock.
+     */
+    createCaptions(player: MebiusPlayer, options: CaptionsOptions): MebiusCaptions;
     /** Close the connection and release resources. */
     disconnect(reason?: string): void;
     private assertConnected;
@@ -377,4 +491,4 @@ declare const Mebius: {
     _reset(): void;
 };
 
-export { type BroadcastStats, type BroadcasterEventMap, type BroadcasterOptions, type ClientEventMap, Mebius, MebiusBroadcaster, MebiusClient, type MebiusConnectOptions, type MebiusDelivery, MebiusError, type MebiusErrorCode, type MebiusInitOptions, MebiusPlayer, type MediaConstraint, type PlaybackMode, type PlaybackStats, type PlayerEventMap, type PlayerOptions, type ViewTarget, mebiusError };
+export { type BroadcastStats, type BroadcasterEventMap, type BroadcasterOptions, type CaptionSegment, type CaptionsEventMap, type CaptionsOptions, type ClientEventMap, Mebius, MebiusBroadcaster, MebiusCaptions, MebiusClient, type MebiusConnectOptions, type MebiusDelivery, MebiusError, type MebiusErrorCode, type MebiusInitOptions, MebiusPlayer, type MediaConstraint, type PlaybackMode, type PlaybackStats, type PlayerEventMap, type PlayerOptions, type ViewTarget, mebiusError };

package/dist/index.d.ts

@@ -123,6 +123,37 @@ interface PlaybackStats {
     /** Estimated end-to-end latency in milliseconds, if known. */
     latencyMs?: number;
 }
+/** Options for {@link MebiusClient.createCaptions}. */
+interface CaptionsOptions {
+    /**
+     * Which translation to read from each segment, e.g. `"id"`. Must match a
+     * `targetLangs` entry your backend passed to `captions/start` — the engine
+     * only ever sends the translations that session produced.
+     */
+    lang: string;
+}
+/**
+ * One caption segment, timed against a wall clock so it can be compared to
+ * {@link MebiusPlayer.currentEpochMs}.
+ */
+interface CaptionSegment {
+    /** Stable id for this segment. A later revision replaces it in place. */
+    segmentId: string;
+    /** Revision counter. Only the highest-`rev` copy of a `segmentId` is kept. */
+    rev: number;
+    /** `"interim"` or `"final"`. Interim only arrives if the session enabled it. */
+    state: "interim" | "final";
+    /** Unix ms the audio was actually spoken. Compare against the playhead. */
+    epochMs: number;
+    /** How long the segment should stay on screen once due, in ms. */
+    durationMs: number;
+    /** Original transcript, in the source language. */
+    text: string;
+    /** The requested {@link CaptionsOptions.lang} translation, if produced yet. */
+    translation?: string;
+    /** Always `true`. Render a machine-generated indicator — never as a direct quote. */
+    machineGenerated: true;
+}
 /** Canonical Mebius error codes surfaced to your app. */
 type MebiusErrorCode = "TOKEN_EXPIRED" | "PERMISSION_DENIED" | "CONNECTION_FAILED" | "NOT_CONNECTED" | "STREAM_NOT_FOUND" | "UNKNOWN";
 
@@ -167,6 +198,17 @@ type PlayerEventMap = {
     ended: void;
     stats: PlaybackStats;
 };
+/** Event payloads emitted by {@link MebiusCaptions}. */
+type CaptionsEventMap = {
+    /** A segment became due (its `epochMs` reached the playhead). Render it. */
+    segment: CaptionSegment;
+    /** A previously-shown segment aged out (playhead passed its window). Clear it. */
+    cleared: {
+        segmentId: string;
+    };
+    /** The SSE connection dropped. `EventSource` reconnects on its own. */
+    error: void;
+};
 type Listener<T> = (payload: T) => void;
 /**
  * A tiny strongly-typed event emitter. `EventMap` maps each event name to its
@@ -216,6 +258,12 @@ declare class SignalingClient {
     deliveryUrl(path: string): string;
     /** Playlist URL for scale-mode playback. */
     scalePlaylistUrl(streamId: string): string;
+    /**
+     * Realtime captions SSE URL. Same play token as media — the engine's
+     * `PlayVerifier` gates both, so a viewer who can watch the stream can already
+     * read its captions with zero extra credential.
+     */
+    captionsUrl(streamId: string, lang: string): string;
     private pathFor;
     /**
      * Run the session offer/answer exchange. Throws a {@link MebiusError} with a
@@ -315,11 +363,64 @@ declare class MebiusPlayer extends TypedEmitter<PlayerEventMap> {
      * drags to zero also survives a later unmute at the element level.
      */
     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}).
+     *
+     * 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.
+     */
+    currentEpochMs(): number | null;
     private attach;
     private startStats;
     private stopStats;
 }
 
+/**
+ * Realtime captions — subscribes to the engine's caption SSE feed and emits
+ * segments on the video's own timeline, not on arrival order.
+ *
+ * The engine (mebius-stream-engine, `internal/caption`) does the ASR/translate
+ * work and starts sending segments the moment a sentence finishes — which is
+ * BEFORE the viewer's player, sitting behind the live edge by however much its
+ * transport buffers, has shown the matching frame. Rendering on arrival would
+ * show the caption before the streamer says it. So every segment is buffered by
+ * `epochMs` (when the audio was actually spoken, a wall clock) and released only
+ * once {@link MebiusPlayer.currentEpochMs} reaches it. See
+ * mebius-stream-engine/docs/INTEGRATION.md §6.
+ */
+
+/**
+ * Subscribes to one stream's caption feed. Create with
+ * {@link MebiusClient.createCaptions}, `start()` it, and listen for `"segment"`
+ * / `"cleared"`.
+ *
+ * Starting the caption SESSION (`captions/start`, which spends money) is a
+ * separate, server-side call — this class only ever reads the feed a session
+ * already produces. That split is deliberate: the control endpoint needs an API
+ * key, which must never reach a browser.
+ */
+declare class MebiusCaptions extends TypedEmitter<CaptionsEventMap> {
+    private readonly signaling;
+    private readonly player;
+    private readonly opts;
+    private es;
+    private timer;
+    private readonly pending;
+    private readonly shown;
+    /** @internal */
+    constructor(signaling: SignalingClient, player: MebiusPlayer, opts: CaptionsOptions);
+    /** Open the SSE connection and begin emitting segments for `streamId`. */
+    start(streamId: string): void;
+    /** Close the connection and drop all buffered segments. */
+    stop(): void;
+    private onFrame;
+    private tick;
+}
+
 /**
  * A live connection to Mebius. Obtain one from {@link Mebius.connect}, then
  * create broadcasters and players from it.
@@ -352,6 +453,19 @@ declare class MebiusClient extends TypedEmitter<ClientEventMap> {
      * black frame to a live audience, so it belongs here rather than in every app.
      */
     createMonitor(): MebiusPlayer;
+    /**
+     * Subscribe to a stream's realtime captions.
+     *
+     * Reads the same feed a session already produces — it does NOT start the
+     * caption session itself. `captions/start` spends money and requires an API
+     * key, so it belongs to your own backend (see
+     * mebius-stream-engine/docs/API.md §5.1), called once when you want captions
+     * on for a stream. This only ever consumes what that call turned on.
+     *
+     * `player` must be the one showing `streamId`: captions are timed against its
+     * playhead, and a mismatched player would compare against the wrong clock.
+     */
+    createCaptions(player: MebiusPlayer, options: CaptionsOptions): MebiusCaptions;
     /** Close the connection and release resources. */
     disconnect(reason?: string): void;
     private assertConnected;
@@ -377,4 +491,4 @@ declare const Mebius: {
     _reset(): void;
 };
 
-export { type BroadcastStats, type BroadcasterEventMap, type BroadcasterOptions, type ClientEventMap, Mebius, MebiusBroadcaster, MebiusClient, type MebiusConnectOptions, type MebiusDelivery, MebiusError, type MebiusErrorCode, type MebiusInitOptions, MebiusPlayer, type MediaConstraint, type PlaybackMode, type PlaybackStats, type PlayerEventMap, type PlayerOptions, type ViewTarget, mebiusError };
+export { type BroadcastStats, type BroadcasterEventMap, type BroadcasterOptions, type CaptionSegment, type CaptionsEventMap, type CaptionsOptions, type ClientEventMap, Mebius, MebiusBroadcaster, MebiusCaptions, MebiusClient, type MebiusConnectOptions, type MebiusDelivery, MebiusError, type MebiusErrorCode, type MebiusInitOptions, MebiusPlayer, type MediaConstraint, type PlaybackMode, type PlaybackStats, type PlayerEventMap, type PlayerOptions, type ViewTarget, mebiusError };

package/dist/index.global.js

@@ -23901,19 +23901,19 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
         isInterstitial(item) {
           return !!(item != null && item.event);
         }
-        retreiveMediaSource(assetId, toSegment) {
+        retreiveMediaSource(assetId, toSegment2) {
           const player = this.getAssetPlayer(assetId);
           if (player) {
-            this.transferMediaFromPlayer(player, toSegment);
+            this.transferMediaFromPlayer(player, toSegment2);
           }
         }
-        transferMediaFromPlayer(player, toSegment) {
+        transferMediaFromPlayer(player, toSegment2) {
           const appendInPlace = player.interstitial.appendInPlace;
           const playerMedia = player.media;
           if (appendInPlace && playerMedia === this.primaryMedia) {
             this.bufferingAsset = null;
-            if (!toSegment || this.isInterstitial(toSegment) && !toSegment.event.appendInPlace) {
-              if (toSegment && playerMedia) {
+            if (!toSegment2 || this.isInterstitial(toSegment2) && !toSegment2.event.appendInPlace) {
+              if (toSegment2 && playerMedia) {
                 this.detachedData = {
                   media: playerMedia
                 };
@@ -23923,7 +23923,7 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
             const attachMediaSourceData = player.transferMedia();
             this.log(`transfer MediaSource from ${player} ${stringify(attachMediaSourceData)}`);
             this.detachedData = attachMediaSourceData;
-          } else if (toSegment && playerMedia) {
+          } else if (toSegment2 && playerMedia) {
             this.shouldPlay || (this.shouldPlay = !playerMedia.paused);
           }
         }
@@ -24942,13 +24942,13 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
           });
           return player;
         }
-        clearInterstitial(interstitial, toSegment) {
-          this.clearAssetPlayers(interstitial, toSegment);
+        clearInterstitial(interstitial, toSegment2) {
+          this.clearAssetPlayers(interstitial, toSegment2);
           interstitial.reset();
         }
-        clearAssetPlayers(interstitial, toSegment) {
+        clearAssetPlayers(interstitial, toSegment2) {
           interstitial.assetList.forEach((asset) => {
-            this.clearAssetPlayer(asset.identifier, toSegment);
+            this.clearAssetPlayer(asset.identifier, toSegment2);
           });
         }
         resetAssetPlayer(assetId) {
@@ -24960,12 +24960,12 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
             player.resetDetails();
           }
         }
-        clearAssetPlayer(assetId, toSegment) {
+        clearAssetPlayer(assetId, toSegment2) {
           const playerIndex = this.getAssetPlayerQueueIndex(assetId);
           if (playerIndex !== -1) {
             const player = this.playerQueue[playerIndex];
-            this.log(`clear ${player} toSegment: ${toSegment ? segmentToString(toSegment) : toSegment}`);
-            this.transferMediaFromPlayer(player, toSegment);
+            this.log(`clear ${player} toSegment: ${toSegment2 ? segmentToString(toSegment2) : toSegment2}`);
+            this.transferMediaFromPlayer(player, toSegment2);
             this.playerQueue.splice(playerIndex, 1);
             player.destroy();
           }
@@ -42609,6 +42609,7 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
   __export(index_exports, {
     Mebius: () => Mebius,
     MebiusBroadcaster: () => MebiusBroadcaster,
+    MebiusCaptions: () => MebiusCaptions,
     MebiusClient: () => MebiusClient,
     MebiusError: () => MebiusError,
     MebiusPlayer: () => MebiusPlayer,
@@ -42922,6 +42923,9 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
   };
 
   // src/internal/scale-view-transport.ts
+  function retryWarmupNotFound(cfg, retryCount, res, retry) {
+    return retry || retryCount < (cfg?.maxNumRetry ?? 0) && res?.code === 404;
+  }
   var HlsViewTransport = class {
     /**
      * deliveryPath, when given, is a gateway-relative path from the gateway's own
@@ -42969,7 +42973,22 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
         this.mutedByPolicy = (await playWithAutoplayFallback(video)).mutedByPolicy;
         return;
       }
-      const hls = new Hls2({ maxLiveSyncPlaybackRate: 1.1 });
+      const hls = new Hls2({
+        maxLiveSyncPlaybackRate: 1.1,
+        manifestLoadPolicy: {
+          default: {
+            maxTimeToFirstByteMs: 1e4,
+            maxLoadTimeMs: 2e4,
+            timeoutRetry: { maxNumRetry: 2, retryDelayMs: 0, maxRetryDelayMs: 0 },
+            errorRetry: {
+              maxNumRetry: 5,
+              retryDelayMs: 500,
+              maxRetryDelayMs: 2e3,
+              shouldRetry: (cfg, retryCount, _isTimeout, res, retry) => retryWarmupNotFound(cfg, retryCount, res, retry)
+            }
+          }
+        }
+      });
       this.hls = hls;
       hls.on(Hls2.Events.ERROR, (_evt, data) => {
         if (data.fatal) this.bufferingCb?.();
@@ -42997,6 +43016,22 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
         framesPerSecond: 0
       };
     }
+    /**
+     * hls.js exposes `playingDate` straight from the segment the element is
+     * currently rendering, derived from the playlist's `EXT-X-PROGRAM-DATE-TIME`
+     * (MediaMTX writes it). Safari's native player has no such property, but
+     * `getStartDate()` (the wall-clock time of the playlist's first segment) plus
+     * elapsed `currentTime` is the same clock by construction.
+     */
+    playheadEpochMs() {
+      if (this.hls) return this.hls.playingDate?.getTime() ?? null;
+      const video = this.video;
+      if (video?.getStartDate) {
+        const start = video.getStartDate().getTime();
+        if (Number.isFinite(start)) return start + video.currentTime * 1e3;
+      }
+      return null;
+    }
   };
 
   // src/internal/balanced-view-transport.ts
@@ -43368,6 +43403,82 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
     return c;
   }
 
+  // src/captions.ts
+  var TICK_MS = 100;
+  var STALE_MS = 5e3;
+  var MebiusCaptions = class extends TypedEmitter {
+    /** @internal */
+    constructor(signaling, player, opts) {
+      super();
+      this.signaling = signaling;
+      this.player = player;
+      this.opts = opts;
+      this.es = null;
+      this.timer = null;
+      this.pending = /* @__PURE__ */ new Map();
+      this.shown = /* @__PURE__ */ new Set();
+    }
+    /** Open the SSE connection and begin emitting segments for `streamId`. */
+    start(streamId) {
+      if (this.es) return;
+      const url = this.signaling.captionsUrl(streamId, this.opts.lang);
+      const es = new EventSource(url);
+      es.onmessage = (ev) => this.onFrame(ev);
+      es.onerror = () => this.emit("error", void 0);
+      this.es = es;
+      this.timer = setInterval(() => this.tick(), TICK_MS);
+    }
+    /** Close the connection and drop all buffered segments. */
+    stop() {
+      this.es?.close();
+      this.es = null;
+      if (this.timer) clearInterval(this.timer);
+      this.timer = null;
+      this.pending.clear();
+      this.shown.clear();
+    }
+    onFrame(ev) {
+      let frame;
+      try {
+        frame = JSON.parse(ev.data);
+      } catch {
+        return;
+      }
+      if (frame.type !== "caption" || !frame.segmentId) return;
+      const prev = this.pending.get(frame.segmentId);
+      if (prev && (frame.rev ?? 0) < (prev.rev ?? 0)) return;
+      this.pending.set(frame.segmentId, frame);
+    }
+    tick() {
+      const now2 = this.player.currentEpochMs();
+      if (now2 == null) return;
+      for (const [id, frame] of this.pending) {
+        const due = frame.epochMs ?? 0;
+        if (due > now2) continue;
+        if (due < now2 - STALE_MS) {
+          this.pending.delete(id);
+          if (this.shown.delete(id)) this.emit("cleared", { segmentId: id });
+          continue;
+        }
+        this.shown.add(id);
+        this.emit("segment", toSegment(id, frame, this.opts.lang));
+        if (frame.state === "final") this.pending.delete(id);
+      }
+    }
+  };
+  function toSegment(segmentId, frame, lang) {
+    return {
+      segmentId,
+      rev: frame.rev ?? 0,
+      state: frame.state === "final" ? "final" : "interim",
+      epochMs: frame.epochMs ?? 0,
+      durationMs: frame.durationMs ?? 0,
+      text: frame.text ?? "",
+      translation: frame.translations?.[lang],
+      machineGenerated: true
+    };
+  }
+
   // src/internal/freeze-clock.ts
   var FreezeClock = class {
     constructor(now2 = Date.now) {
@@ -43537,6 +43648,19 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
       this.video.volume = v;
       this.video.muted = v === 0;
     }
+    /**
+     * Wall-clock time (Unix ms) currently on screen, or `null` when the active
+     * route cannot produce one (HTTP-FLV, WHEP — 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.
+     */
+    currentEpochMs() {
+      return this.transport?.playheadEpochMs?.() ?? null;
+    }
     attach(transport) {
       transport.onEnded(() => {
         if (this.transport !== transport) return;
@@ -43631,6 +43755,16 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
     scalePlaylistUrl(streamId) {
       return this.withToken(`${this.base()}/live/${encodeURIComponent(streamId)}/index.m3u8`);
     }
+    /**
+     * Realtime captions SSE URL. Same play token as media — the engine's
+     * `PlayVerifier` gates both, so a viewer who can watch the stream can already
+     * read its captions with zero extra credential.
+     */
+    captionsUrl(streamId, lang) {
+      return this.withToken(
+        `${this.base()}/live/${encodeURIComponent(streamId)}/captions?lang=${encodeURIComponent(lang)}`
+      );
+    }
     // Maps a neutral session kind to the concrete signaling path segment. This
     // mapping (publish -> WHIP, view -> WHEP) lives ONLY in this method body, so
     // the protocol names never appear in any exported type signature.
@@ -43754,6 +43888,22 @@ Schedule: ${scheduleItems.map((seg) => segmentToString(seg))} pos: ${this.timeli
       this.assertConnected();
       return new MebiusPlayer(this.signaling, { mode: "low-latency" }, this.deliveries, this.telemetry, this.userId);
     }
+    /**
+     * Subscribe to a stream's realtime captions.
+     *
+     * Reads the same feed a session already produces — it does NOT start the
+     * caption session itself. `captions/start` spends money and requires an API
+     * key, so it belongs to your own backend (see
+     * mebius-stream-engine/docs/API.md §5.1), called once when you want captions
+     * on for a stream. This only ever consumes what that call turned on.
+     *
+     * `player` must be the one showing `streamId`: captions are timed against its
+     * playhead, and a mismatched player would compare against the wrong clock.
+     */
+    createCaptions(player, options) {
+      this.assertConnected();
+      return new MebiusCaptions(this.signaling, player, options);
+    }
     /** Close the connection and release resources. */
     disconnect(reason) {
       if (this.expiryTimer) clearTimeout(this.expiryTimer);