@mebius-io/web 0.4.9 → 0.5.1

package/dist/index.cjs

@@ -32,6 +32,7 @@ var index_exports = {};
 __export(index_exports, {
   Mebius: () => Mebius,
   MebiusBroadcaster: () => MebiusBroadcaster,
+  MebiusCaptions: () => MebiusCaptions,
   MebiusClient: () => MebiusClient,
   MebiusError: () => MebiusError,
   MebiusPlayer: () => MebiusPlayer,
@@ -439,6 +440,22 @@ var HlsViewTransport = class {
       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
@@ -810,6 +827,82 @@ function normalize(c, fallback) {
   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 now = this.player.currentEpochMs();
+    if (now == null) return;
+    for (const [id, frame] of this.pending) {
+      const due = frame.epochMs ?? 0;
+      if (due > now) continue;
+      if (due < now - 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(now = Date.now) {
@@ -979,6 +1072,19 @@ var MebiusPlayer = class extends TypedEmitter {
     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;
@@ -1073,6 +1179,23 @@ var SignalingClient = class {
   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.
+   *
+   * `/api/v1/live/...`, NOT `/live/...`: unlike {@link scalePlaylistUrl}, which
+   * hits the engine's bare `/live/*` media-edge catch-all, captions are mounted
+   * under the versioned control-API group (mebius-stream-engine
+   * internal/api/routes.go) with the play-token middleware, not the proxy.
+   * Copying the media-edge prefix here 401s every request — the catch-all
+   * doesn't recognise the path and never reaches the captions handler at all.
+   */
+  captionsUrl(streamId, lang) {
+    return this.withToken(
+      `${this.base()}/api/v1/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.
@@ -1196,6 +1319,22 @@ var MebiusClient = class extends TypedEmitter {
     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);
@@ -1241,6 +1380,7 @@ var Mebius = {
 0 && (module.exports = {
   Mebius,
   MebiusBroadcaster,
+  MebiusCaptions,
   MebiusClient,
   MebiusError,
   MebiusPlayer,