@mebius-io/web 0.1.3 → 0.3.0

package/dist/index.js

@@ -220,11 +220,18 @@ var WhepViewTransport = class {
   }
 };
 
-// src/internal/balanced-view-transport.ts
-var FlvViewTransport = class {
-  constructor(signaling) {
+// src/internal/scale-view-transport.ts
+var HlsViewTransport = class {
+  /**
+   * deliveryPath, when given, is a gateway-relative path from the gateway's own
+   * delivery list — that is how a CDN-backed playlist gets used instead of the
+   * origin one. Without it this falls back to the origin playlist, which is
+   * still correct, just served from our own bandwidth.
+   */
+  constructor(signaling, deliveryPath) {
     this.signaling = signaling;
-    this.player = null;
+    this.deliveryPath = deliveryPath;
+    this.hls = null;
     this.video = null;
     this.endedCb = null;
     this.bufferingCb = null;
@@ -237,37 +244,36 @@ var FlvViewTransport = class {
   }
   async start(streamId, video) {
     this.video = video;
-    const url = this.signaling.balancedStreamUrl(streamId);
+    const url = this.deliveryPath ? this.signaling.deliveryUrl(this.deliveryPath) : this.signaling.scalePlaylistUrl(streamId);
     video.addEventListener("ended", () => this.endedCb?.());
     video.addEventListener("waiting", () => this.bufferingCb?.());
+    if (video.canPlayType("application/vnd.apple.mpegurl")) {
+      video.src = url;
+      await video.play().catch(() => void 0);
+      return;
+    }
     let mod;
     try {
-      const spec = "flv.js";
-      mod = await import(
-        /* @vite-ignore */
-        spec
-      );
+      mod = await import("hls.js");
     } catch (cause) {
-      throw mebiusError("CONNECTION_FAILED", "Balanced playback support failed to load.", cause);
+      throw mebiusError("CONNECTION_FAILED", "Scale playback support failed to load.", cause);
     }
-    const flvjs = mod.default;
-    if (!flvjs.isSupported()) {
-      throw mebiusError("CONNECTION_FAILED", "Balanced playback is not supported in this browser.");
+    const Hls = mod.default;
+    if (!Hls.isSupported()) {
+      throw mebiusError("CONNECTION_FAILED", "Scale playback is not supported in this browser.");
     }
-    const player = flvjs.createPlayer({ type: "flv", url, isLive: true });
-    this.player = player;
-    player.on(flvjs.Events.ERROR ?? "error", () => this.bufferingCb?.());
-    player.attachMediaElement(video);
-    player.load();
-    await Promise.resolve(player.play()).catch(() => void 0);
+    const hls = new Hls({ lowLatencyMode: true });
+    this.hls = hls;
+    hls.on(Hls.Events.ERROR, (_evt, data) => {
+      if (data.fatal) this.bufferingCb?.();
+    });
+    hls.loadSource(url);
+    hls.attachMedia(video);
+    await video.play().catch(() => void 0);
   }
   async stop() {
-    if (this.player) {
-      this.player.unload();
-      this.player.detachMediaElement();
-      this.player.destroy();
-      this.player = null;
-    }
+    this.hls?.destroy();
+    this.hls = null;
     if (this.video) {
       this.video.removeAttribute("src");
       this.video.load();
@@ -276,19 +282,20 @@ var FlvViewTransport = class {
   }
   async getStats() {
     if (!this.video) return null;
+    const level = this.hls?.levels?.[this.hls.currentLevel];
     return {
-      bitrateKbps: 0,
-      framesPerSecond: 0,
-      latencyMs: void 0
+      bitrateKbps: level ? Math.round(level.bitrate / 1e3) : 0,
+      framesPerSecond: 0
     };
   }
 };
 
-// src/internal/scale-view-transport.ts
-var HlsViewTransport = class {
-  constructor(signaling) {
+// src/internal/balanced-view-transport.ts
+var FlvViewTransport = class {
+  constructor(signaling, deliveryPath) {
     this.signaling = signaling;
-    this.hls = null;
+    this.deliveryPath = deliveryPath;
+    this.player = null;
     this.video = null;
     this.endedCb = null;
     this.bufferingCb = null;
@@ -299,38 +306,35 @@ var HlsViewTransport = class {
   onBuffering(cb) {
     this.bufferingCb = cb;
   }
-  async start(streamId, video) {
+  async start(_streamId, video) {
     this.video = video;
-    const url = this.signaling.scalePlaylistUrl(streamId);
+    const url = this.signaling.deliveryUrl(this.deliveryPath);
     video.addEventListener("ended", () => this.endedCb?.());
     video.addEventListener("waiting", () => this.bufferingCb?.());
-    if (video.canPlayType("application/vnd.apple.mpegurl")) {
-      video.src = url;
-      await video.play().catch(() => void 0);
-      return;
-    }
     let mod;
     try {
-      mod = await import("hls.js");
+      mod = await import("flv.js");
     } catch (cause) {
-      throw mebiusError("CONNECTION_FAILED", "Scale playback support failed to load.", cause);
+      throw mebiusError("CONNECTION_FAILED", "Balanced playback support failed to load.", cause);
     }
-    const Hls = mod.default;
-    if (!Hls.isSupported()) {
-      throw mebiusError("CONNECTION_FAILED", "Scale playback is not supported in this browser.");
+    const flvjs = mod.default;
+    if (!flvjs.isSupported()) {
+      throw mebiusError("CONNECTION_FAILED", "Balanced playback is not supported in this browser.");
     }
-    const hls = new Hls({ lowLatencyMode: true });
-    this.hls = hls;
-    hls.on(Hls.Events.ERROR, (_evt, data) => {
-      if (data.fatal) this.bufferingCb?.();
-    });
-    hls.loadSource(url);
-    hls.attachMedia(video);
-    await video.play().catch(() => void 0);
+    const player = flvjs.createPlayer({ type: "flv", url, isLive: true });
+    this.player = player;
+    player.on(flvjs.Events.ERROR ?? "error", () => this.bufferingCb?.());
+    player.attachMediaElement(video);
+    player.load();
+    await Promise.resolve(player.play()).catch(() => void 0);
   }
   async stop() {
-    this.hls?.destroy();
-    this.hls = null;
+    if (this.player) {
+      this.player.unload();
+      this.player.detachMediaElement();
+      this.player.destroy();
+      this.player = null;
+    }
     if (this.video) {
       this.video.removeAttribute("src");
       this.video.load();
@@ -339,10 +343,10 @@ var HlsViewTransport = class {
   }
   async getStats() {
     if (!this.video) return null;
-    const level = this.hls?.levels?.[this.hls.currentLevel];
     return {
-      bitrateKbps: level ? Math.round(level.bitrate / 1e3) : 0,
-      framesPerSecond: 0
+      bitrateKbps: 0,
+      framesPerSecond: 0,
+      latencyMs: void 0
     };
   }
 };
@@ -351,14 +355,30 @@ var HlsViewTransport = class {
 function createPublishTransport(signaling) {
   return new WhipPublishTransport(signaling);
 }
-function createViewTransport(mode, signaling) {
+var KIND_FAST = "fast";
+var KIND_WIDE = "wide";
+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);
+  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);
+  const allKinds = [KIND_FAST, KIND_WIDE, KIND_LOCAL];
   switch (mode) {
     case "low-latency":
-      return new WhepViewTransport(signaling);
+      return [new WhepViewTransport(signaling), ...fromGateway(allKinds), originFallback];
     case "balanced":
-      return new FlvViewTransport(signaling);
+      return [...fromGateway(allKinds), originFallback];
     case "scale":
-      return new HlsViewTransport(signaling);
+      return [...fromGateway([KIND_WIDE, KIND_LOCAL]), originFallback];
+    case "auto":
+      return [...fromGateway(allKinds), originFallback];
   }
 }
 
@@ -457,34 +477,48 @@ function normalize(c, fallback) {
 
 // src/player.ts
 var STATS_INTERVAL_MS2 = 2e3;
+var FIRST_FRAME_TIMEOUT_MS = 8e3;
 var MebiusPlayer = class extends TypedEmitter {
   /** @internal */
-  constructor(signaling, options) {
+  constructor(signaling, options = {}, deliveries = []) {
     super();
+    this.transport = null;
     this.video = null;
     this.statsTimer = null;
     this.playing = false;
-    this.transport = createViewTransport(options.mode, signaling);
-    this.transport.onEnded(() => {
-      this.playing = false;
-      this.stopStats();
-      this.emit("ended", void 0);
-    });
-    this.transport.onBuffering(() => this.emit("buffering", void 0));
+    this.candidates = createViewCandidates(options.mode ?? "auto", signaling, deliveries);
   }
   /** Start playing `streamId` into the given video element or selector. */
   async play(streamId, viewTarget) {
     if (this.playing) return;
-    this.video = resolveVideoElement(viewTarget);
-    await this.transport.start(streamId, this.video);
-    this.playing = true;
-    this.startStats();
-    this.emit("playing", { streamId });
+    const video = resolveVideoElement(viewTarget);
+    this.video = video;
+    let lastError = null;
+    for (const candidate of this.candidates) {
+      try {
+        this.attach(candidate);
+        await candidate.start(streamId, video);
+        if (await hasFirstFrame(video)) {
+          this.transport = candidate;
+          this.playing = true;
+          this.startStats();
+          this.emit("playing", { streamId });
+          return;
+        }
+        lastError = mebiusError("CONNECTION_FAILED", "A Mebius route delivered no video.");
+      } catch (cause) {
+        lastError = cause;
+      }
+      await candidate.stop().catch(() => void 0);
+    }
+    this.video = null;
+    throw lastError ?? mebiusError("CONNECTION_FAILED", "No Mebius route could play this stream.");
   }
   /** Stop playback and detach from the video element. */
   async stop() {
     this.stopStats();
-    await this.transport.stop();
+    await this.transport?.stop();
+    this.transport = null;
     this.video = null;
     this.playing = false;
   }
@@ -493,9 +527,21 @@ var MebiusPlayer = class extends TypedEmitter {
     const v = Math.min(1, Math.max(0, volume));
     if (this.video) this.video.volume = v;
   }
+  attach(transport) {
+    transport.onEnded(() => {
+      if (this.transport !== transport) return;
+      this.playing = false;
+      this.stopStats();
+      this.emit("ended", void 0);
+    });
+    transport.onBuffering(() => {
+      if (this.transport !== transport) return;
+      this.emit("buffering", void 0);
+    });
+  }
   startStats() {
     this.statsTimer = setInterval(async () => {
-      const stats = await this.transport.getStats();
+      const stats = await this.transport?.getStats();
       if (stats) this.emit("stats", stats);
     }, STATS_INTERVAL_MS2);
   }
@@ -504,6 +550,21 @@ var MebiusPlayer = class extends TypedEmitter {
     this.statsTimer = null;
   }
 };
+function hasFirstFrame(video) {
+  if (video.currentTime > 0 && !video.paused) return Promise.resolve(true);
+  return new Promise((resolve) => {
+    const done = (ok) => {
+      clearTimeout(timer);
+      video.removeEventListener("timeupdate", onTime);
+      resolve(ok);
+    };
+    const onTime = () => {
+      if (video.currentTime > 0) done(true);
+    };
+    const timer = setTimeout(() => done(false), FIRST_FRAME_TIMEOUT_MS);
+    video.addEventListener("timeupdate", onTime);
+  });
+}
 
 // src/internal/signaling.ts
 var SignalingClient = class {
@@ -527,17 +588,24 @@ var SignalingClient = class {
   // Build the playlist URL used by scale-mode playback (HLS path, hidden). The
   // engine serves the playlist under /live/{id}/index.m3u8 and requires the
   // token in the query; segment URIs in the playlist inherit it automatically.
+  /**
+   * Absolute, tokenized URL for a gateway-relative delivery path handed to us
+   * by the gateway (`deliveries[].path`). The gateway decides which paths exist
+   * and in what order; the SDK only resolves them against its own base and
+   * attaches the access token. Anything that is not a plain gateway-relative
+   * path is rejected rather than fetched: an absolute URL there would send the
+   * token to a host we did not choose.
+   */
+  deliveryUrl(path) {
+    if (!path.startsWith("/") || path.startsWith("//") || path.includes("://")) {
+      throw mebiusError("CONNECTION_FAILED", "The gateway returned an unusable delivery path.");
+    }
+    return this.withToken(`${this.base()}${path}`);
+  }
   /** Playlist URL for scale-mode playback. */
   scalePlaylistUrl(streamId) {
     return this.withToken(`${this.base()}/live/${encodeURIComponent(streamId)}/index.m3u8`);
   }
-  // Build the HTTP-FLV pull URL used by balanced-mode playback. Served by the
-  // CDN (CDN_PULL_FORMAT `.flv`) or an SRS/nginx-rtmp edge in front of the
-  // engine — MediaMTX itself does not vend HTTP-FLV. Hidden from the public API.
-  /** Pull URL for balanced-mode playback. */
-  balancedStreamUrl(streamId) {
-    return this.withToken(`${this.base()}/flv/${encodeURIComponent(streamId)}.flv`);
-  }
   // 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.
@@ -609,9 +677,10 @@ function readToken(token) {
 // src/client.ts
 var MebiusClient = class extends TypedEmitter {
   /** @internal */
-  constructor(config2, token) {
+  constructor(config2, token, deliveries = []) {
     super();
     this.token = token;
+    this.deliveries = deliveries;
     this.expiryTimer = null;
     this.connected = false;
     this.signaling = new SignalingClient(config2.gateway, token);
@@ -639,9 +708,24 @@ var MebiusClient = class extends TypedEmitter {
     return new MebiusBroadcaster(this.signaling, options);
   }
   /** Create a player bound to this connection. */
-  createPlayer(options) {
+  createPlayer(options = {}) {
+    this.assertConnected();
+    return new MebiusPlayer(this.signaling, options, this.deliveries);
+  }
+  /**
+   * Create a monitor: a player tuned for watching a stream you are interacting
+   * WITH rather than merely watching — the other side of a co-broadcast, where a
+   * second or two of delay makes the interaction feel broken.
+   *
+   * It is a player with the delay budget spent differently, not a different API:
+   * it starts on the real-time route and falls back on its own if that route
+   * delivers no frames. Apps used to hand-roll this (open a real-time view, run a
+   * timer, swap players when it stayed black); getting the fallback wrong showed a
+   * black frame to a live audience, so it belongs here rather than in every app.
+   */
+  createMonitor() {
     this.assertConnected();
-    return new MebiusPlayer(this.signaling, options);
+    return new MebiusPlayer(this.signaling, { mode: "low-latency" }, this.deliveries);
   }
   /** Close the connection and release resources. */
   disconnect(reason) {
@@ -674,7 +758,7 @@ var Mebius = {
       throw mebiusError("UNKNOWN", "Call Mebius.init() before Mebius.connect().");
     }
     if (!options.token) throw mebiusError("UNKNOWN", "Mebius.connect requires a token.");
-    const client = new MebiusClient(config, options.token);
+    const client = new MebiusClient(config, options.token, options.deliveries ?? []);
     client.open();
     return client;
   },