@mebius-io/web 0.3.0 → 0.4.1

package/README.md

@@ -55,12 +55,12 @@ external deps. `Mebius` becomes a global.
 ```
 
 File + full PHP example: [`standalone/`](./standalone/). Raw download:
-`https://raw.githubusercontent.com/russimobiledroidx/mebius-web-sdk/v0.3.0/packages/web/standalone/mebius.min.js`
+`https://raw.githubusercontent.com/russimobiledroidx/mebius-web-sdk/v0.4.1/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`.
+`https://esm.sh/@mebius-io/web@0.4.1`.
 
 ## Quick Start
 
@@ -162,6 +162,29 @@ 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.
 
+### `beaconToken` / `beaconUrl` — quality di dashboard
+
+Response token juga membawa dua field opsional. Teruskan keduanya dan SDK
+melaporkan kualitas stream ini (bitrate, fps, rtt, jeda first-frame) tiap ~15
+detik:
+
+```ts
+const { token, deliveries, beaconToken, beaconUrl } = await (await fetch("/api/mebius-token")).json();
+const client = Mebius.connect({ token, deliveries, beaconToken, beaconUrl });
+```
+
+Itu yang mengisi **Quality → Publish / Play** di dashboard Mebius, dan yang jadi
+dasar hitung **viewer minutes** — laporan sisi penonton adalah satu-satunya sumber
+data itu, karena cuma client yang bisa melihat pengalaman penonton sebenarnya.
+
+Aman di browser: kredensialnya terikat klaim bertanda tangan ke **satu** stream dan
+**satu** project, jadi tak bisa dipakai menulis telemetri milik stream lain. SDK
+tidak pernah tahu tenant-mu — informasi itu ada di dalam klaim, bukan di kode client.
+
+Tanpa dua field itu stream tetap jalan normal; kamu hanya tidak melihat data
+kualitasnya. Tambahkan `userId` di `connect()` kalau ingin laporan itu ikut membawa
+id pengguna versimu.
+
 ## Integrasi per framework
 
 ### Vanilla JS

package/dist/index.cjs

@@ -188,6 +188,28 @@ var WhipPublishTransport = class {
   }
 };
 
+// src/internal/autoplay.ts
+function isAutoplayBlocked(e) {
+  return typeof e === "object" && e !== null && e.name === "NotAllowedError";
+}
+async function playWithAutoplayFallback(video) {
+  video.playsInline = true;
+  try {
+    await video.play();
+    return { mutedByPolicy: false };
+  } catch (e) {
+    if (!isAutoplayBlocked(e) || video.muted) throw e;
+    video.muted = true;
+    await video.play();
+    return { mutedByPolicy: true };
+  }
+}
+function resetVideoElement(video) {
+  video.srcObject = null;
+  video.removeAttribute("src");
+  video.load();
+}
+
 // src/internal/ll-view-transport.ts
 var WhepViewTransport = class {
   constructor(signaling) {
@@ -196,6 +218,10 @@ var WhepViewTransport = class {
     this.resourceUrl = null;
     this.endedCb = null;
     this.bufferingCb = null;
+    /** Element this route attached a MediaStream to, so stop() can release it. */
+    this.video = null;
+    /** True when playback only started because the element had to be muted. */
+    this.mutedByPolicy = false;
   }
   onEnded(cb) {
     this.endedCb = cb;
@@ -204,6 +230,7 @@ var WhepViewTransport = class {
     this.bufferingCb = cb;
   }
   async start(streamId, video) {
+    this.video = video;
     const pc = new RTCPeerConnection(DEFAULT_RTC_CONFIG);
     this.pc = pc;
     const remote = new MediaStream();
@@ -212,7 +239,9 @@ var WhepViewTransport = class {
     pc.ontrack = (ev) => {
       remote.addTrack(ev.track);
       video.srcObject = remote;
-      void video.play().catch(() => {
+      void playWithAutoplayFallback(video).then((o) => {
+        this.mutedByPolicy = o.mutedByPolicy;
+      }).catch(() => {
       });
     };
     pc.onconnectionstatechange = () => {
@@ -239,6 +268,8 @@ var WhepViewTransport = class {
     this.resourceUrl = null;
     this.pc?.close();
     this.pc = null;
+    if (this.video) resetVideoElement(this.video);
+    this.video = null;
   }
   async getStats() {
     if (!this.pc) return null;
@@ -276,6 +307,8 @@ var HlsViewTransport = class {
     this.video = null;
     this.endedCb = null;
     this.bufferingCb = null;
+    /** True when playback only started because the element had to be muted. */
+    this.mutedByPolicy = false;
   }
   onEnded(cb) {
     this.endedCb = cb;
@@ -290,7 +323,7 @@ var HlsViewTransport = class {
     video.addEventListener("waiting", () => this.bufferingCb?.());
     if (video.canPlayType("application/vnd.apple.mpegurl")) {
       video.src = url;
-      await video.play().catch(() => void 0);
+      this.mutedByPolicy = (await playWithAutoplayFallback(video)).mutedByPolicy;
       return;
     }
     let mod;
@@ -303,14 +336,14 @@ var HlsViewTransport = class {
     if (!Hls.isSupported()) {
       throw mebiusError("CONNECTION_FAILED", "Scale playback is not supported in this browser.");
     }
-    const hls = new Hls({ lowLatencyMode: true });
+    const hls = new Hls();
     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);
+    this.mutedByPolicy = (await playWithAutoplayFallback(video)).mutedByPolicy;
   }
   async stop() {
     this.hls?.destroy();
@@ -340,6 +373,8 @@ var FlvViewTransport = class {
     this.video = null;
     this.endedCb = null;
     this.bufferingCb = null;
+    /** True when playback only started because the element had to be muted. */
+    this.mutedByPolicy = false;
   }
   onEnded(cb) {
     this.endedCb = cb;
@@ -367,7 +402,7 @@ var FlvViewTransport = class {
     player.on(flvjs.Events.ERROR ?? "error", () => this.bufferingCb?.());
     player.attachMediaElement(video);
     player.load();
-    await Promise.resolve(player.play()).catch(() => void 0);
+    this.mutedByPolicy = (await playWithAutoplayFallback(video)).mutedByPolicy;
   }
   async stop() {
     if (this.player) {
@@ -423,17 +458,103 @@ function createViewCandidates(mode, signaling, deliveries = []) {
   }
 }
 
+// src/internal/telemetry.ts
+var SDK_VERSION = "web/0.4.1";
+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. */
@@ -442,12 +563,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;
@@ -503,7 +630,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() {
@@ -521,12 +655,15 @@ var STATS_INTERVAL_MS2 = 2e3;
 var FIRST_FRAME_TIMEOUT_MS = 8e3;
 var MebiusPlayer = class extends TypedEmitter {
   /** @internal */
-  constructor(signaling, options = {}, deliveries = []) {
+  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.reporter = null;
     this.candidates = createViewCandidates(options.mode ?? "auto", signaling, deliveries);
   }
   /** Start playing `streamId` into the given video element or selector. */
@@ -534,14 +671,21 @@ var MebiusPlayer = class extends TypedEmitter {
     if (this.playing) return;
     const video = resolveVideoElement(viewTarget);
     this.video = video;
+    const startedAtMs = Date.now();
     let lastError = null;
     for (const candidate of this.candidates) {
       try {
+        resetVideoElement(video);
         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;
@@ -558,6 +702,8 @@ var MebiusPlayer = class extends TypedEmitter {
   /** Stop playback and detach from the video element. */
   async stop() {
     this.stopStats();
+    await this.reporter?.stop();
+    this.reporter = null;
     await this.transport?.stop();
     this.transport = null;
     this.video = null;
@@ -573,6 +719,8 @@ var MebiusPlayer = class extends TypedEmitter {
       if (this.transport !== transport) return;
       this.playing = false;
       this.stopStats();
+      void this.reporter?.stop();
+      this.reporter = null;
       this.emit("ended", void 0);
     });
     transport.onBuffering(() => {
@@ -583,7 +731,13 @@ var MebiusPlayer = 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
+      });
     }, STATS_INTERVAL_MS2);
   }
   stopStats() {
@@ -718,10 +872,12 @@ function readToken(token) {
 // src/client.ts
 var MebiusClient = class extends TypedEmitter {
   /** @internal */
-  constructor(config2, token, deliveries = []) {
+  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);
@@ -746,12 +902,12 @@ 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 = {}) {
     this.assertConnected();
-    return new MebiusPlayer(this.signaling, options, this.deliveries);
+    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
@@ -766,7 +922,7 @@ var MebiusClient = class extends TypedEmitter {
    */
   createMonitor() {
     this.assertConnected();
-    return new MebiusPlayer(this.signaling, { mode: "low-latency" }, this.deliveries);
+    return new MebiusPlayer(this.signaling, { mode: "low-latency" }, this.deliveries, this.telemetry, this.userId);
   }
   /** Close the connection and release resources. */
   disconnect(reason) {
@@ -799,7 +955,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, options.deliveries ?? []);
+    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;
   },