@voltkit-rtc/client 0.2.0 → 0.4.0

package/dist/esm/stats.js

@@ -0,0 +1,232 @@
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const optNum = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+const optStr = (value) => (typeof value === 'string' && value !== '' ? value : undefined);
+const oneDecimal = (value) => Math.round(value * 10) / 10;
+/**
+ * Bits per second from `bytes` at `timestamp` (ms), against what `key` had
+ * last time, and remembers this reading for the next call. 0 on the first
+ * reading, and whenever the counter went backwards (a new stream).
+ */
+export function bitrateSince(baseline, key, bytes, timestamp) {
+    const previous = baseline.get(key);
+    baseline.set(key, { bytes, timestamp });
+    if (!previous)
+        return 0;
+    const seconds = (timestamp - previous.timestamp) / 1000;
+    const delta = bytes - previous.bytes;
+    if (seconds <= 0 || delta < 0)
+        return 0;
+    return Math.round((delta * 8) / seconds);
+}
+/** Forget every key `keep` turns down: the streams they counted are gone. */
+export function pruneBaseline(baseline, keep) {
+    for (const key of [...baseline.keys()]) {
+        if (!keep(key))
+            baseline.delete(key);
+    }
+}
+const isVideo = (entry) => entry.kind === 'video' || entry.mediaType === 'video';
+/** `VP8` from the codec entry an RTP stream points at. */
+function codecOf(byId, entry) {
+    const codec = entry && typeof entry.codecId === 'string' ? byId.get(entry.codecId) : undefined;
+    const mime = optStr(codec?.mimeType);
+    return mime ? mime.replace(/^video\//i, '') : undefined;
+}
+/** The upload estimate on the candidate pair in use. */
+function availableOutgoing(entries, byId) {
+    for (const transport of entries.filter((e) => e.type === 'transport')) {
+        const pair = typeof transport.selectedCandidatePairId === 'string' ? byId.get(transport.selectedCandidatePairId) : undefined;
+        const bitrate = optNum(pair?.availableOutgoingBitrate);
+        if (bitrate !== undefined)
+            return bitrate;
+    }
+    const pairs = entries.filter((e) => e.type === 'candidate-pair' && optNum(e.availableOutgoingBitrate) !== undefined);
+    const chosen = pairs.find((p) => p.nominated === true && p.state === 'succeeded') ?? pairs.find((p) => p.nominated === true) ?? pairs[0];
+    return optNum(chosen?.availableOutgoingBitrate);
+}
+const area = (layer) => layer.width * layer.height;
+/** r0, r1, r2 in order; layers without a rid by size. */
+function layerOrder(a, b) {
+    if (a.rid !== undefined && b.rid !== undefined && a.rid !== b.rid) {
+        return a.rid.localeCompare(b.rid, 'en', { numeric: true });
+    }
+    return area(a) - area(b);
+}
+/**
+ * The camera's send statistics from a sender's report. `keyPrefix` names the
+ * producer, so a new producer's counters never meet an old one's.
+ */
+export function parseSendStats(report, options) {
+    const entries = [...report].filter((e) => typeof e === 'object' && e !== null);
+    const byId = new Map();
+    for (const entry of entries) {
+        if (typeof entry.id === 'string')
+            byId.set(entry.id, entry);
+    }
+    const outbound = entries.filter((e) => e.type === 'outbound-rtp' && isVideo(e));
+    const layers = outbound.map((entry) => {
+        const rid = optStr(entry.rid);
+        const key = `${options.keyPrefix}${rid ?? String(entry.ssrc ?? entry.id ?? '')}`;
+        const bitrate = bitrateSince(options.baseline, key, num(entry.bytesSent), num(entry.timestamp));
+        const fps = oneDecimal(num(entry.framesPerSecond));
+        const reason = optStr(entry.qualityLimitationReason);
+        return {
+            ...(rid !== undefined ? { rid } : {}),
+            width: num(entry.frameWidth),
+            height: num(entry.frameHeight),
+            fps,
+            bitrate,
+            active: entry.active !== false && (fps > 0 || bitrate > 0),
+            ...(reason !== undefined ? { qualityLimitation: reason } : {}),
+            entry,
+        };
+    });
+    layers.sort(layerOrder);
+    // The biggest layer going out is what the best-connected viewer gets. With
+    // nothing going out (paused, or the very first frames), the biggest there is.
+    const pool = layers.some((l) => l.active) ? layers.filter((l) => l.active) : layers;
+    const top = pool.reduce((best, l) => (!best || area(l) > area(best) ? l : best), undefined);
+    const codec = codecOf(byId, top?.entry) ?? outbound.map((e) => codecOf(byId, e)).find(Boolean);
+    const available = availableOutgoing(entries, byId);
+    return {
+        ...(codec !== undefined ? { codec } : {}),
+        quality: options.quality,
+        width: top?.width ?? 0,
+        height: top?.height ?? 0,
+        fps: top?.fps ?? 0,
+        bitrate: top?.bitrate ?? 0,
+        ...(top?.qualityLimitation !== undefined ? { qualityLimitation: top.qualityLimitation } : {}),
+        ...(available !== undefined ? { availableOutgoingBitrate: available } : {}),
+        layers: layers.map(({ entry: _entry, ...layer }) => layer),
+    };
+}
+/** One consumed video's receive statistics from a receiver's report; null when it has none. */
+export function parseReceiveStats(report, options) {
+    const entries = [...report].filter((e) => typeof e === 'object' && e !== null);
+    const byId = new Map();
+    for (const entry of entries) {
+        if (typeof entry.id === 'string')
+            byId.set(entry.id, entry);
+    }
+    const inbound = entries
+        .filter((e) => e.type === 'inbound-rtp' && isVideo(e))
+        .sort((a, b) => num(b.bytesReceived) - num(a.bytesReceived))[0];
+    if (!inbound)
+        return null;
+    const codec = codecOf(byId, inbound);
+    const jitter = optNum(inbound.jitter);
+    const freezeCount = optNum(inbound.freezeCount);
+    return {
+        producerId: options.producerId,
+        ...(codec !== undefined ? { codec } : {}),
+        width: num(inbound.frameWidth),
+        height: num(inbound.frameHeight),
+        fps: oneDecimal(num(inbound.framesPerSecond)),
+        bitrate: bitrateSince(options.baseline, options.key, num(inbound.bytesReceived), num(inbound.timestamp)),
+        packetsLost: num(inbound.packetsLost),
+        ...(jitter !== undefined ? { jitter } : {}),
+        ...(freezeCount !== undefined ? { freezeCount } : {}),
+    };
+}
+/**
+ * The reason across the layers going out (all of them when none is): the
+ * device first, since it costs the most picture, then the upload, then
+ * anything else.
+ */
+export function limitReasonOf(layers) {
+    const pool = layers.some((l) => l.active) ? layers.filter((l) => l.active) : layers;
+    const reasons = new Set(pool.map((l) => l.qualityLimitation));
+    if (reasons.has('cpu'))
+        return 'cpu';
+    if (reasons.has('bandwidth'))
+        return 'bandwidth';
+    if (reasons.has('other'))
+        return 'other';
+    return 'none';
+}
+/** Samples a new reason must hold for before it is reported: about 4 s at one every 2 s. */
+export const LIMIT_SAMPLES_TO_REPORT = 2;
+export const initialLimitTracker = () => ({ reported: null, pending: null, streak: 0 });
+/**
+ * Feed one sample's reason. Returns the reason to report, if any: one that
+ * differs from the last reported and held for LIMIT_SAMPLES_TO_REPORT samples
+ * in a row, so a brief spike stays quiet. Before anything is reported the
+ * state counts as 'none', so 'none' is never the first event.
+ */
+export function trackLimit(tracker, reason) {
+    const current = tracker.reported ?? 'none';
+    if (reason === current)
+        return { tracker: { reported: tracker.reported, pending: null, streak: 0 }, report: null };
+    const streak = reason === tracker.pending ? tracker.streak + 1 : 1;
+    if (streak >= LIMIT_SAMPLES_TO_REPORT)
+        return { tracker: { reported: reason, pending: null, streak: 0 }, report: reason };
+    return { tracker: { reported: tracker.reported, pending: reason, streak }, report: null };
+}
+/** How often the camera is sampled while someone listens for `videoLimited`. */
+export const LIMIT_SAMPLE_MS = 2000;
+/**
+ * Samples the camera's send statistics on a timer while it is wanted and
+ * reports changes in what holds the video back. The stats it reads keep their
+ * own baseline, so its sampling never disturbs the bitrates an app reads with
+ * `getVideoStats()`.
+ */
+export class VideoLimitWatch {
+    sample;
+    report;
+    intervalMs;
+    timer = null;
+    tracker = initialLimitTracker();
+    sampling = false;
+    baseline = new Map();
+    constructor(sample, report, intervalMs = LIMIT_SAMPLE_MS) {
+        this.sample = sample;
+        this.report = report;
+        this.intervalMs = intervalMs;
+    }
+    get running() {
+        return this.timer !== null;
+    }
+    /** Start or stop sampling. Safe to call as often as anything changes. */
+    set(wanted) {
+        if (wanted && !this.timer) {
+            this.timer = setInterval(() => void this.tick(), this.intervalMs);
+        }
+        else if (!wanted && this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+        }
+    }
+    /**
+     * Stop, and start over as if nothing had been reported. Returns the event
+     * that clears a limitation still being reported, for when publishing stops.
+     */
+    reset() {
+        this.set(false);
+        const was = this.tracker.reported;
+        this.tracker = initialLimitTracker();
+        this.baseline.clear();
+        return was && was !== 'none' ? { reason: 'none', width: 0, height: 0, fps: 0, bitrate: 0 } : null;
+    }
+    async tick() {
+        // A slow getStats must not pile samples up behind it.
+        if (this.sampling)
+            return;
+        this.sampling = true;
+        try {
+            const stats = await this.sample(this.baseline);
+            if (!stats || !this.timer)
+                return;
+            const { tracker, report } = trackLimit(this.tracker, limitReasonOf(stats.layers));
+            this.tracker = tracker;
+            if (report)
+                this.report({ reason: report, width: stats.width, height: stats.height, fps: stats.fps, bitrate: stats.bitrate });
+        }
+        catch {
+            // Statistics are best effort; the next sample tries again.
+        }
+        finally {
+            this.sampling = false;
+        }
+    }
+}
+//# sourceMappingURL=stats.js.map

package/dist/esm/stats.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stats.js","sourceRoot":"","sources":["../../src/stats.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltkit-rtc/client",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Browser SDK for VoltKit RTC: realtime audio/video rooms, chat and live broadcast publishing.",
   "keywords": [
     "voltkit",
@@ -49,7 +49,8 @@
   "scripts": {
     "build": "rm -rf dist && tsc -p tsconfig.json && tsc -p tsconfig.cjs.json && node ../scripts/dual-package.mjs .",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test": "npm run build && node --test test/"
   },
   "dependencies": {
     "mediasoup-client": "^3.22.0"

package/src/chat.ts

@@ -122,6 +122,8 @@ export class ChatClient {
   private closedByUs = false;
   private reconnecting = false;
   private reconnectAttempt = 0;
+  /** Set by the first successful join. Only a session that has joined is reconnected. */
+  private joinedOnce = false;
 
   constructor(private readonly wsUrl: string, token: string) {
     this.token = token;
@@ -153,8 +155,22 @@ export class ChatClient {
   }
 
   async connect(): Promise<ChatJoinResult> {
-    await this.openSocket();
-    const result = (await this.rpc('join', { token: this.token })) as ChatJoinResult;
+    let result: ChatJoinResult;
+    try {
+      await this.openSocket();
+      result = (await this.rpc('join', { token: this.token })) as ChatJoinResult;
+    } catch (err) {
+      // Never joined: the app has the error. Left open, the socket would be
+      // closed by the server's join deadline, and that would start
+      // reconnecting a session that never began.
+      if (!this.joinedOnce) this.detachSocket();
+      throw err;
+    }
+    // Joined: the next drop gets every reconnect attempt again. Not when the
+    // socket opens, or a join refused with a code worth retrying never uses
+    // them up and is retried about twice a second, forever.
+    this.reconnectAttempt = 0;
+    this.joinedOnce = true;
     this.joinResult = result;
     this.emit('joined', result);
     return result;
@@ -170,7 +186,6 @@ export class ChatClient {
 
       const onError = () => reject(new Error('websocket failed to open'));
       ws.addEventListener('open', () => {
-        this.reconnectAttempt = 0;
         this.emit('connected');
         resolve();
       }, { once: true });
@@ -191,7 +206,9 @@ export class ChatClient {
           this.emit('closed', 'ended');
           return;
         }
-        if (!this.closedByUs) void this.scheduleReconnect();
+        // Before a first join the app is still waiting on connect(), which
+        // reports the failure; there is no session to restore.
+        if (!this.closedByUs && this.joinedOnce) void this.scheduleReconnect();
       });
     });
   }

package/src/device.ts

@@ -0,0 +1,168 @@
+/**
+ * What kind of device is publishing, and which video codec it should send.
+ *
+ * Phones and tablets get different defaults from computers: each simulcast
+ * layer is a separate encode, and a phone encoding VP8 does it in software.
+ * Under that load Chrome shrinks the picture, and with three layers asked for
+ * it then sends only two and drops the TOP one: viewers got 180×320 from a
+ * 720p phone. Two layers in hardware H.264 keep the full picture.
+ *
+ * Everything here reads the browser through small injectable parameters, so
+ * tests can stand in for any device.
+ */
+import type { types as ms } from 'mediasoup-client';
+
+type RtpCodecCapability = ms.RtpCodecCapability;
+
+/** What the SDK reads about the browser to choose its defaults. */
+export interface DeviceEnv {
+  userAgent: string;
+  /** `navigator.userAgentData.mobile`, where the browser has it (Chromium). */
+  uaMobile?: boolean;
+  maxTouchPoints: number;
+}
+
+/** The browser this runs in; an empty desktop-like one outside a browser. */
+export function currentEnv(): DeviceEnv {
+  if (typeof navigator === 'undefined') return { userAgent: '', maxTouchPoints: 0 };
+  const nav = navigator as Navigator & { userAgentData?: { mobile?: unknown } };
+  const mobile = nav.userAgentData?.mobile;
+  return {
+    userAgent: typeof nav.userAgent === 'string' ? nav.userAgent : '',
+    ...(typeof mobile === 'boolean' ? { uaMobile: mobile } : {}),
+    maxTouchPoints: typeof nav.maxTouchPoints === 'number' ? nav.maxTouchPoints : 0,
+  };
+}
+
+// iPadOS asks for desktop sites, so an iPad says "Macintosh". No Mac has a
+// touch screen, so one that reports touch points is an iPad.
+const isIPadOS = (env: DeviceEnv): boolean => /Macintosh/.test(env.userAgent) && env.maxTouchPoints > 1;
+
+/**
+ * A phone or a tablet. `userAgentData.mobile` is false on Android tablets, so
+ * the user agent is checked as well.
+ */
+export function isPhoneOrTablet(env: DeviceEnv = currentEnv()): boolean {
+  if (env.uaMobile === true) return true;
+  if (/Android|iPhone|iPad|iPod|Mobile/.test(env.userAgent)) return true;
+  return isIPadOS(env);
+}
+
+/** An iPhone, iPad or iPod: every one of them encodes H.264 in hardware. */
+export function isAppleMobile(env: DeviceEnv = currentEnv()): boolean {
+  return /iPhone|iPad|iPod/.test(env.userAgent) || isIPadOS(env);
+}
+
+/** Two layers on phones and tablets, three elsewhere. */
+export function defaultLayerCount(env: DeviceEnv = currentEnv()): 2 | 3 {
+  return isPhoneOrTablet(env) ? 2 : 3;
+}
+
+/** `navigator.mediaCapabilities.encodingInfo`, or a stand-in for tests. */
+export type EncodingInfoProbe = (configuration: MediaEncodingConfiguration) => Promise<MediaCapabilitiesEncodingInfo>;
+
+/** The browser's own probe, when it has one. */
+export function currentProbe(): EncodingInfoProbe | undefined {
+  if (typeof navigator === 'undefined') return undefined;
+  const capabilities = (navigator as Navigator & { mediaCapabilities?: MediaCapabilities }).mediaCapabilities;
+  if (!capabilities || typeof capabilities.encodingInfo !== 'function') return undefined;
+  return (configuration) => capabilities.encodingInfo(configuration);
+}
+
+/** The H.264 the media server takes: constrained baseline, packetization mode 1. */
+export const H264_CONTENT_TYPE = 'video/H264;profile-level-id=42e01f;packetization-mode=1';
+
+const PROBE_TIMEOUT_MS = 1500;
+
+/**
+ * Whether this browser encodes H.264 at this size and bitrate in hardware:
+ * true or false when it says so, null when it cannot say (no
+ * `mediaCapabilities`, no `webrtc` support in it, an error, or no answer in
+ * time). Publishing never waits on it for more than a moment.
+ */
+export async function h264HardwareEncode(
+  video: { width: number; height: number; bitrate: number },
+  probe: EncodingInfoProbe | undefined = currentProbe(),
+  timeoutMs = PROBE_TIMEOUT_MS,
+): Promise<boolean | null> {
+  if (!probe) return null;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const answer = probe({
+      type: 'webrtc',
+      video: {
+        contentType: H264_CONTENT_TYPE,
+        width: Math.round(video.width),
+        height: Math.round(video.height),
+        bitrate: video.bitrate,
+        framerate: 30,
+      },
+    });
+    const late = new Promise<null>((resolve) => {
+      timer = setTimeout(() => resolve(null), timeoutMs);
+    });
+    const info = await Promise.race([answer, late]);
+    if (!info) return null;
+    return Boolean(info.supported && info.powerEfficient);
+  } catch {
+    return null;
+  } finally {
+    if (timer !== undefined) clearTimeout(timer);
+  }
+}
+
+/** What `PublishOptions.codec` may say. */
+export type CodecPreference = 'auto' | 'vp8' | 'h264';
+
+/** 'vp8' or 'h264' in any case; anything else, including nothing, is 'auto'. */
+export function normalizeCodec(codec: unknown): CodecPreference {
+  const name = typeof codec === 'string' ? codec.toLowerCase() : '';
+  return name === 'vp8' || name === 'h264' ? name : 'auto';
+}
+
+export interface CodecChoiceInput {
+  requested: CodecPreference;
+  phoneOrTablet: boolean;
+  appleMobile: boolean;
+  /** This browser can send H.264 to this server (it is in the device's send capabilities). */
+  h264Available: boolean;
+  /** What the hardware probe said; null when it could not say. Only asked for 'auto' on phones and tablets. */
+  h264Hardware: boolean | null;
+}
+
+export interface CodecChoice {
+  codec: 'vp8' | 'h264';
+  /** Set when the codec asked for cannot be used: report it, and publish anyway. */
+  warning?: string;
+}
+
+/**
+ * The codec to publish with.
+ *
+ * 'auto' is H.264 on a phone or tablet that encodes it in hardware, and VP8
+ * everywhere else: computers encode VP8 well, and a few desktop browsers
+ * cannot decode H.264. When the probe cannot say, an Apple device is taken to
+ * have hardware H.264 (they all do) and anything else is not.
+ */
+export function chooseCodec(input: CodecChoiceInput): CodecChoice {
+  if (input.requested === 'h264') {
+    return input.h264Available
+      ? { codec: 'h264' }
+      : { codec: 'vp8', warning: 'H.264 was asked for, but this browser cannot send it to this server: publishing VP8 instead' };
+  }
+  if (input.requested === 'vp8') return { codec: 'vp8' };
+  if (!input.phoneOrTablet || !input.h264Available) return { codec: 'vp8' };
+  return { codec: (input.h264Hardware ?? input.appleMobile) ? 'h264' : 'vp8' };
+}
+
+/**
+ * The device's own capability entry for a codec, to hand to `produce()`.
+ * Only ever pass `produce()` an entry from the device's send capabilities:
+ * mediasoup-client adds the transceiver before it checks the codec, so one it
+ * cannot match leaves a transceiver behind that breaks every later produce.
+ */
+export function findCodec(codecs: readonly RtpCodecCapability[] | undefined, codec: 'vp8' | 'h264'): RtpCodecCapability | undefined {
+  if (!codecs) return undefined;
+  if (codec === 'vp8') return codecs.find((c) => c.mimeType.toLowerCase() === 'video/vp8');
+  return codecs.find((c) => c.mimeType.toLowerCase() === 'video/h264' && Number(c.parameters?.['packetization-mode'] ?? 0) === 1);
+}