@mebius-io/web 0.2.0 → 0.4.0

package/dist/index.js

@@ -222,8 +222,15 @@ var WhepViewTransport = class {
 
 // src/internal/scale-view-transport.ts
 var HlsViewTransport = class {
-  constructor(signaling) {
+  /**
+   * 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.deliveryPath = deliveryPath;
     this.hls = null;
     this.video = null;
     this.endedCb = null;
@@ -237,7 +244,7 @@ var HlsViewTransport = class {
   }
   async start(streamId, video) {
     this.video = video;
-    const url = this.signaling.scalePlaylistUrl(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")) {
@@ -283,30 +290,195 @@ var HlsViewTransport = class {
   }
 };
 
+// src/internal/balanced-view-transport.ts
+var FlvViewTransport = class {
+  constructor(signaling, deliveryPath) {
+    this.signaling = signaling;
+    this.deliveryPath = deliveryPath;
+    this.player = null;
+    this.video = null;
+    this.endedCb = null;
+    this.bufferingCb = null;
+  }
+  onEnded(cb) {
+    this.endedCb = cb;
+  }
+  onBuffering(cb) {
+    this.bufferingCb = cb;
+  }
+  async start(_streamId, video) {
+    this.video = video;
+    const url = this.signaling.deliveryUrl(this.deliveryPath);
+    video.addEventListener("ended", () => this.endedCb?.());
+    video.addEventListener("waiting", () => this.bufferingCb?.());
+    let mod;
+    try {
+      mod = await import("flv.js");
+    } catch (cause) {
+      throw mebiusError("CONNECTION_FAILED", "Balanced 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 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() {
+    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();
+    }
+    this.video = null;
+  }
+  async getStats() {
+    if (!this.video) return null;
+    return {
+      bitrateKbps: 0,
+      framesPerSecond: 0,
+      latencyMs: void 0
+    };
+  }
+};
+
 // src/internal/transport.ts
 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 [...fromGateway(allKinds), originFallback];
     case "scale":
-      return new HlsViewTransport(signaling);
+      return [...fromGateway([KIND_WIDE, KIND_LOCAL]), originFallback];
+    case "auto":
+      return [...fromGateway(allKinds), originFallback];
   }
 }
 
+// src/internal/telemetry.ts
+var SDK_VERSION = "web/0.4.0";
+var FLUSH_INTERVAL_MS = 15e3;
+var MAX_BATCH = 64;
+function describeDevice() {
+  const nav = typeof navigator === "undefined" ? void 0 : navigator;
+  const uaData = nav?.userAgentData;
+  return { os: uaData?.platform || nav?.platform || void 0, sdk: SDK_VERSION };
+}
+function describeNetwork() {
+  const conn = typeof navigator === "undefined" ? void 0 : navigator.connection;
+  return conn?.effectiveType ? { type: conn.effectiveType } : void 0;
+}
+var QoeReporter = class {
+  constructor(target, role, streamId, userId) {
+    this.target = target;
+    this.role = role;
+    this.streamId = streamId;
+    this.userId = userId;
+    this.sessionId = randomId();
+    this.buffer = [];
+    this.timer = null;
+    this.unloadHandler = null;
+  }
+  start() {
+    if (this.timer) return;
+    this.timer = setInterval(() => void this.flush(), FLUSH_INTERVAL_MS);
+    if (typeof window !== "undefined") {
+      this.unloadHandler = () => void this.flush(true);
+      window.addEventListener("pagehide", this.unloadHandler);
+    }
+  }
+  add(sample) {
+    this.buffer.push(sample);
+    if (this.buffer.length >= MAX_BATCH) void this.flush();
+  }
+  async stop() {
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    if (this.unloadHandler && typeof window !== "undefined") {
+      window.removeEventListener("pagehide", this.unloadHandler);
+    }
+    this.unloadHandler = null;
+    await this.flush();
+  }
+  /** Send and clear the buffer. `beacon` uses sendBeacon, for page-unload flushes. */
+  async flush(beacon = false) {
+    if (!this.buffer.length) return;
+    const samples = this.buffer.splice(0, MAX_BATCH);
+    const body = JSON.stringify({
+      sessionId: this.sessionId,
+      streamId: this.streamId,
+      role: this.role,
+      userId: this.userId,
+      samples,
+      device: describeDevice(),
+      network: describeNetwork()
+    });
+    if (beacon && typeof navigator !== "undefined" && navigator.sendBeacon) {
+      const url = `${this.target.url}${this.target.url.includes("?") ? "&" : "?"}token=${encodeURIComponent(this.target.token)}`;
+      try {
+        navigator.sendBeacon(url, new Blob([body], { type: "application/json" }));
+      } catch {
+      }
+      return;
+    }
+    try {
+      await fetch(this.target.url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: `Bearer ${this.target.token}` },
+        body,
+        keepalive: true
+      });
+    } catch {
+    }
+  }
+};
+function randomId() {
+  const c = typeof crypto === "undefined" ? void 0 : crypto;
+  if (c?.randomUUID) return c.randomUUID();
+  return `s-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 10)}`;
+}
+
 // src/broadcaster.ts
 var STATS_INTERVAL_MS = 2e3;
 var MebiusBroadcaster = class extends TypedEmitter {
   /** @internal */
-  constructor(signaling, options) {
+  constructor(signaling, options, telemetry = null, userId) {
     super();
     this.options = options;
+    this.telemetry = telemetry;
+    this.userId = userId;
     this.stream = null;
     this.facingMode = "user";
     this.statsTimer = null;
     this.started = false;
+    this.reporter = null;
     this.transport = createPublishTransport(signaling);
   }
   /** Begin broadcasting under the given stream id. */
@@ -315,12 +487,18 @@ var MebiusBroadcaster = class extends TypedEmitter {
     this.stream = await this.capture();
     await this.transport.start(streamId, this.stream);
     this.started = true;
+    if (this.telemetry) {
+      this.reporter = new QoeReporter(this.telemetry, "pub", streamId, this.userId);
+      this.reporter.start();
+    }
     this.startStats();
     this.emit("started", { streamId });
   }
   /** Stop broadcasting and release the camera/microphone. */
   async stop() {
     this.stopStats();
+    await this.reporter?.stop();
+    this.reporter = null;
     await this.transport.stop();
     this.stream?.getTracks().forEach((t) => t.stop());
     this.stream = null;
@@ -376,7 +554,14 @@ var MebiusBroadcaster = class extends TypedEmitter {
   startStats() {
     this.statsTimer = setInterval(async () => {
       const stats = await this.transport.getStats();
-      if (stats) this.emit("stats", stats);
+      if (!stats) return;
+      this.emit("stats", stats);
+      this.reporter?.add({
+        ts: Math.floor(Date.now() / 1e3),
+        bitrateKbps: stats.bitrateKbps,
+        fps: stats.framesPerSecond,
+        rttMs: stats.rttMs
+      });
     }, STATS_INTERVAL_MS);
   }
   stopStats() {
@@ -391,34 +576,59 @@ 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 = [], telemetry = null, userId) {
     super();
+    this.telemetry = telemetry;
+    this.userId = userId;
+    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.reporter = null;
+    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;
+    const startedAtMs = Date.now();
+    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;
+          if (this.telemetry) {
+            this.reporter = new QoeReporter(this.telemetry, "play", streamId, this.userId);
+            this.reporter.start();
+            this.reporter.add({ ts: Math.floor(Date.now() / 1e3), firstFrameMs: Date.now() - startedAtMs });
+          }
+          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.reporter?.stop();
+    this.reporter = null;
+    await this.transport?.stop();
+    this.transport = null;
     this.video = null;
     this.playing = false;
   }
@@ -427,10 +637,30 @@ 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();
+      void this.reporter?.stop();
+      this.reporter = null;
+      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();
-      if (stats) this.emit("stats", stats);
+      const stats = await this.transport?.getStats();
+      if (!stats) return;
+      this.emit("stats", stats);
+      this.reporter?.add({
+        ts: Math.floor(Date.now() / 1e3),
+        bitrateKbps: stats.bitrateKbps,
+        fps: stats.framesPerSecond
+      });
     }, STATS_INTERVAL_MS2);
   }
   stopStats() {
@@ -438,6 +668,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 {
@@ -461,6 +706,20 @@ 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`);
@@ -536,9 +795,12 @@ function readToken(token) {
 // src/client.ts
 var MebiusClient = class extends TypedEmitter {
   /** @internal */
-  constructor(config2, token) {
+  constructor(config2, token, deliveries = [], telemetry = null, userId) {
     super();
     this.token = token;
+    this.deliveries = deliveries;
+    this.telemetry = telemetry;
+    this.userId = userId;
     this.expiryTimer = null;
     this.connected = false;
     this.signaling = new SignalingClient(config2.gateway, token);
@@ -563,12 +825,27 @@ var MebiusClient = class extends TypedEmitter {
   /** Create a broadcaster bound to this connection. */
   createBroadcaster(options = {}) {
     this.assertConnected();
-    return new MebiusBroadcaster(this.signaling, options);
+    return new MebiusBroadcaster(this.signaling, options, this.telemetry, this.userId);
   }
   /** Create a player bound to this connection. */
-  createPlayer(options) {
+  createPlayer(options = {}) {
+    this.assertConnected();
+    return new MebiusPlayer(this.signaling, options, this.deliveries, this.telemetry, this.userId);
+  }
+  /**
+   * 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, this.telemetry, this.userId);
   }
   /** Close the connection and release resources. */
   disconnect(reason) {
@@ -601,7 +878,8 @@ 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 telemetry = options.beaconToken && options.beaconUrl ? { token: options.beaconToken, url: options.beaconUrl } : null;
+    const client = new MebiusClient(config, options.token, options.deliveries ?? [], telemetry, options.userId);
     client.open();
     return client;
   },