@mebius-io/web 0.2.0 → 0.4.0

package/dist/index.d.ts

@@ -15,6 +15,18 @@ interface MebiusInitOptions {
      */
     gateway: string;
 }
+/**
+ * One playback route Mebius has prepared for a stream, as returned alongside the
+ * token by your backend. Pass the list through untouched — Mebius orders it and
+ * picks from it. `kind` is a Mebius intent label, not a format: treat both fields
+ * as opaque.
+ */
+interface MebiusDelivery {
+    /** Mebius intent label, e.g. `"fast"` or `"wide"`. Opaque to your app. */
+    kind: string;
+    /** A Mebius-relative path. Opaque to your app; Mebius resolves it. */
+    path: string;
+}
 /** Options for {@link Mebius.connect}. */
 interface MebiusConnectOptions {
     /**
@@ -22,6 +34,29 @@ interface MebiusConnectOptions {
      * The app secret must never be embedded in client code.
      */
     token: string;
+    /**
+     * The `deliveries` list your backend received together with the token. Pass it
+     * through as-is and Mebius will pick the best route for each viewer's device,
+     * falling back automatically if one stops delivering frames.
+     *
+     * Optional: without it playback still works, but every viewer is served from
+     * Mebius origin rather than the nearest edge.
+     */
+    deliveries?: MebiusDelivery[];
+    /**
+     * Quality reporting credential from the same token response
+     * (`beaconToken`). Pass it through and Mebius shows this stream's publish and
+     * playback quality in your dashboard, and counts viewer minutes from it.
+     *
+     * Optional: without it the stream works exactly the same, you just see no
+     * quality data for it. Safe in the client — it can only report telemetry for
+     * this one stream.
+     */
+    beaconToken?: string;
+    /** Where to report it, from the same token response (`beaconUrl`). */
+    beaconUrl?: string;
+    /** Your own id for the person on this connection, if you want it in reports. */
+    userId?: string;
 }
 /** A media capture constraint: enable/disable, or a detailed constraint set. */
 type MediaConstraint = boolean | MediaTrackConstraints;
@@ -34,17 +69,21 @@ interface BroadcasterOptions {
 }
 /**
  * Playback mode.
+ * - `"auto"` — recommended. Mebius picks per viewer and falls back on its own.
  * - `"low-latency"` — minimal (sub-second) delay, best for interactive/real-time
  *   viewing. Web browsers only.
+ * - `"balanced"` — a low delay that still scales to a large audience. Web
+ *   browsers with Media Source support (i.e. not iOS Safari).
  * - `"scale"` — optimized for the largest audiences; higher delay. Plays on
  *   every platform, including iOS Safari.
  *
  * Mebius picks the right delivery method for each mode automatically.
  */
-type PlaybackMode = "low-latency" | "scale";
+type PlaybackMode = "auto" | "low-latency" | "balanced" | "scale";
 /** Options for {@link MebiusClient.createPlayer}. */
 interface PlayerOptions {
-    mode: PlaybackMode;
+    /** Defaults to `"auto"` — let Mebius choose per viewer. */
+    mode?: PlaybackMode;
 }
 /**
  * Where a player renders video: a `<video>` element, or a CSS selector that
@@ -151,6 +190,15 @@ declare class SignalingClient {
     private headers;
     /** Append the access token as a query param (the form the engine enforces). */
     private withToken;
+    /**
+     * 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: string): string;
     /** Playlist URL for scale-mode playback. */
     scalePlaylistUrl(streamId: string): string;
     private pathFor;
@@ -163,6 +211,13 @@ declare class SignalingClient {
     deleteResource(resourceUrl: string | null): Promise<void>;
 }
 
+interface TelemetryTarget {
+    /** Absolute beacon URL, as returned with the token. */
+    url: string;
+    /** Beacon credential, as returned with the token. */
+    token: string;
+}
+
 /**
  * Publishes the local camera/microphone to a Mebius stream.
  *
@@ -171,13 +226,16 @@ declare class SignalingClient {
  */
 declare class MebiusBroadcaster extends TypedEmitter<BroadcasterEventMap> {
     private readonly options;
+    private readonly telemetry;
+    private readonly userId?;
     private readonly transport;
     private stream;
     private facingMode;
     private statsTimer;
     private started;
+    private reporter;
     /** @internal */
-    constructor(signaling: SignalingClient, options: BroadcasterOptions);
+    constructor(signaling: SignalingClient, options: BroadcasterOptions, telemetry?: TelemetryTarget | null, userId?: string | undefined);
     /** Begin broadcasting under the given stream id. */
     start(streamId: string): Promise<void>;
     /** Stop broadcasting and release the camera/microphone. */
@@ -202,22 +260,28 @@ declare class MebiusBroadcaster extends TypedEmitter<BroadcasterEventMap> {
 /**
  * Plays a Mebius stream into a `<video>` element.
  *
- * Create one with {@link MebiusClient.createPlayer}, choosing a playback
- * {@link PlaybackMode | mode}; Mebius selects the right delivery automatically.
+ * Create one with {@link MebiusClient.createPlayer}, optionally choosing a
+ * playback {@link PlaybackMode | mode}; Mebius selects the delivery route, and
+ * moves to the next one by itself if the current one stops producing frames.
  */
 declare class MebiusPlayer extends TypedEmitter<PlayerEventMap> {
-    private readonly transport;
+    private readonly telemetry;
+    private readonly userId?;
+    private readonly candidates;
+    private transport;
     private video;
     private statsTimer;
     private playing;
+    private reporter;
     /** @internal */
-    constructor(signaling: SignalingClient, options: PlayerOptions);
+    constructor(signaling: SignalingClient, options?: PlayerOptions, deliveries?: readonly MebiusDelivery[], telemetry?: TelemetryTarget | null, userId?: string | undefined);
     /** Start playing `streamId` into the given video element or selector. */
     play(streamId: string, viewTarget: ViewTarget): Promise<void>;
     /** Stop playback and detach from the video element. */
     stop(): Promise<void>;
     /** Set output volume in the range 0..1. */
     setVolume(volume: number): void;
+    private attach;
     private startStats;
     private stopStats;
 }
@@ -228,17 +292,32 @@ declare class MebiusPlayer extends TypedEmitter<PlayerEventMap> {
  */
 declare class MebiusClient extends TypedEmitter<ClientEventMap> {
     private readonly token;
+    private readonly deliveries;
+    private readonly telemetry;
+    private readonly userId?;
     private readonly signaling;
     private expiryTimer;
     private connected;
     /** @internal */
-    constructor(config: MebiusInitOptions, token: string);
+    constructor(config: MebiusInitOptions, token: string, deliveries?: readonly MebiusDelivery[], telemetry?: TelemetryTarget | null, userId?: string | undefined);
     /** @internal Called by {@link Mebius.connect}. */
     open(): void;
     /** Create a broadcaster bound to this connection. */
     createBroadcaster(options?: BroadcasterOptions): MebiusBroadcaster;
     /** Create a player bound to this connection. */
-    createPlayer(options: PlayerOptions): MebiusPlayer;
+    createPlayer(options?: PlayerOptions): MebiusPlayer;
+    /**
+     * 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(): MebiusPlayer;
     /** Close the connection and release resources. */
     disconnect(reason?: string): void;
     private assertConnected;
@@ -264,4 +343,4 @@ declare const Mebius: {
     _reset(): void;
 };
 
-export { type BroadcastStats, type BroadcasterEventMap, type BroadcasterOptions, type ClientEventMap, Mebius, MebiusBroadcaster, MebiusClient, type MebiusConnectOptions, MebiusError, type MebiusErrorCode, type MebiusInitOptions, MebiusPlayer, type MediaConstraint, type PlaybackMode, type PlaybackStats, type PlayerEventMap, type PlayerOptions, type ViewTarget, mebiusError };
+export { type BroadcastStats, type BroadcasterEventMap, type BroadcasterOptions, type ClientEventMap, Mebius, MebiusBroadcaster, MebiusClient, type MebiusConnectOptions, type MebiusDelivery, MebiusError, type MebiusErrorCode, type MebiusInitOptions, MebiusPlayer, type MediaConstraint, type PlaybackMode, type PlaybackStats, type PlayerEventMap, type PlayerOptions, type ViewTarget, mebiusError };