@mebius-io/web 0.1.3 → 0.3.0

package/README.md

@@ -50,12 +50,17 @@ external deps. `Mebius` becomes a global.
 <script src="mebius.min.js"></script>
 <script>
   Mebius.init({ appId: "app_123", gateway: "https://gateway.mebius.io" });
-  const client = Mebius.connect({ token }); // token from your backend
+  const client = Mebius.connect({ token, deliveries }); // dari backend kamu
 </script>
 ```
 
 File + full PHP example: [`standalone/`](./standalone/). Raw download:
-`https://raw.githubusercontent.com/russimobiledroidx/mebius-web-sdk/v0.1.0/packages/web/standalone/mebius.min.js`
+`https://raw.githubusercontent.com/russimobiledroidx/mebius-web-sdk/v0.3.0/packages/web/standalone/mebius.min.js`
+
+The drop-in file is not part of the npm package — `files` ships only `dist` — so it
+is fetched from the tag, and the tag must match the version you installed. For a
+page with a build step, or one that can use an import map, prefer the ESM path:
+`https://esm.sh/@mebius-io/web@0.3.0`.
 
 ## Quick Start
 
@@ -106,7 +111,7 @@ await broadcaster.stop();
 ### d. Watch
 
 ```ts
-const player = client.createPlayer({ mode: "low-latency" }); // atau "scale"
+const player = client.createPlayer(); // mode default "auto"
 
 player.on("playing", ({ streamId }) => console.log("playing", streamId));
 player.on("buffering", () => console.log("buffering..."));
@@ -118,8 +123,44 @@ player.setVolume(0.8);
 await player.stop();
 ```
 
-Ganti mode kapan saja dengan membuat player baru: `mode: "low-latency"` untuk
-delay minimum, `mode: "scale"` untuk audiens besar.
+### Mode playback
+
+| Mode | Kapan dipakai |
+| --- | --- |
+| `"auto"` (default) | Rekomendasi. Mebius pilih rute per penonton, dan pindah sendiri kalau rute yang dipakai berhenti mengirim frame. |
+| `"low-latency"` | Interaktif dua arah (mis. co-broadcast), delay sub-detik. Browser saja. |
+| `"balanced"` | Delay rendah tapi tetap skala besar. Butuh browser dengan Media Source (bukan Safari iOS). |
+| `"scale"` | Audiens paling besar, delay paling tinggi, jalan di semua platform termasuk Safari iOS. |
+
+Ganti mode kapan saja dengan membuat player baru.
+
+### Menonton lawan bicara (`createMonitor`)
+
+Kalau kamu menonton stream yang sedang kamu **ajak interaksi** (sisi lain dari
+co-broadcast), delay satu-dua detik membuat interaksinya terasa rusak:
+
+```ts
+const monitor = client.createMonitor();
+await monitor.play(opponentStreamId, "#opponent");
+```
+
+Sama seperti player biasa, hanya budget delay-nya beda. Monitor mulai dari rute
+real-time dan **pindah sendiri** kalau rute itu tidak mengirim frame dalam 8
+detik — logika yang sebelumnya harus ditulis ulang di setiap aplikasi, dan kalau
+salah hasilnya frame hitam di depan penonton live.
+
+### `deliveries`
+
+`Mebius.connect()` menerima `deliveries` yang dikirim backend bareng token:
+
+```ts
+const { token, deliveries } = await (await fetch("/api/mebius-token")).json();
+const client = Mebius.connect({ token, deliveries });
+```
+
+Teruskan apa adanya — isinya opaque dan Mebius yang mengurutkan serta memilih.
+Opsional: tanpa itu playback tetap jalan, tapi setiap penonton dilayani dari
+origin Mebius, bukan edge terdekat.
 
 ## Integrasi per framework
 
@@ -152,7 +193,7 @@ import { useMebius, usePlayer } from "@mebius-io/react";
 
 function Watch({ token, streamId }) {
   const { client } = useMebius({ appId, gateway, token });
-  const { videoRef, play } = usePlayer(client, { mode: "low-latency" });
+  const { videoRef, play } = usePlayer(client, {});
   return <video ref={videoRef} onClick={() => play(streamId)} autoPlay />;
 }
 ```
@@ -181,7 +222,7 @@ export function useWatch(streamId: string) {
   onMounted(async () => {
     Mebius.init({ appId, gateway });
     const client = Mebius.connect({ token: await getToken() });
-    player = client.createPlayer({ mode: "low-latency" });
+    player = client.createPlayer();
     await player.play(streamId, video.value!);
   });
   onUnmounted(() => player?.stop());
@@ -191,18 +232,19 @@ export function useWatch(streamId: string) {
 
 ### Vite
 
-Tidak ada config khusus. ESM langsung jalan; engine playback untuk mode
-`"scale"` di-load lazy hanya saat mode itu dipakai, jadi tidak menambah bundle
-low-latency.
+Tidak ada config khusus. ESM langsung jalan; engine playback per mode di-load
+lazy hanya saat mode itu dipakai, jadi aplikasi yang cuma pakai `"low-latency"`
+tidak membawa bundle mode lain.
 
 ## API Reference
 
 | Class | Method | Return | Keterangan |
 |---|---|---|---|
 | `Mebius` | `init({ appId, gateway })` | `void` | Konfigurasi sekali di awal. |
-| `Mebius` | `connect({ token })` | `MebiusClient` | Buka koneksi. |
+| `Mebius` | `connect({ token, deliveries? })` | `MebiusClient` | Buka koneksi. |
 | `MebiusClient` | `createBroadcaster({ video?, audio? })` | `MebiusBroadcaster` | |
-| `MebiusClient` | `createPlayer({ mode })` | `MebiusPlayer` | `mode: "low-latency" \| "scale"` |
+| `MebiusClient` | `createPlayer({ mode? })` | `MebiusPlayer` | `mode: "auto" \| "low-latency" \| "balanced" \| "scale"`, default `"auto"` |
+| `MebiusClient` | `createMonitor()` | `MebiusPlayer` | Player untuk stream yang kamu ajak interaksi. |
 | `MebiusClient` | `disconnect(reason?)` | `void` | |
 | `MebiusBroadcaster` | `start(streamId)` | `Promise<void>` | |
 | `MebiusBroadcaster` | `stop()` | `Promise<void>` | |

package/dist/index.cjs

@@ -261,11 +261,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;
@@ -278,37 +285,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();
@@ -317,19 +323,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;
@@ -340,38 +347,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();
@@ -380,10 +384,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
     };
   }
 };
@@ -392,14 +396,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];
   }
 }
 
@@ -498,34 +518,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;
   }
@@ -534,9 +568,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);
   }
@@ -545,6 +591,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 {
@@ -568,17 +629,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.
@@ -650,9 +718,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);
@@ -680,9 +749,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) {
@@ -715,7 +799,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;
   },