@voltkit-rtc/client 0.6.1 → 0.7.0

package/src/media-permissions.ts

@@ -0,0 +1,220 @@
+/**
+ * What this client may publish, from the join result: the project's media
+ * settings (`media.permissions`), the media modes the super admin has enabled
+ * (`media.profiles`) and, from older servers, the `video` policy alone.
+ *
+ * The server enforces all of it whatever a client sends; the SDK follows it so
+ * that it never sends what would be refused, and can say why it sent less.
+ * Pure: no WebRTC, so it is tested with plain objects.
+ */
+import { allowedQuality, type VideoPolicy, type VideoQuality } from './quality.js';
+
+/** Standard (mono Opus, up to 64 kbps) or HD (stereo Opus, up to 128 kbps) microphone audio. */
+export type AudioQuality = 'std' | 'hd';
+
+export const AUDIO_QUALITIES: readonly AudioQuality[] = ['std', 'hd'];
+
+/**
+ * How each audio quality is sent. Standard really stays at or under 64 kbps:
+ * the server bills HD on what it measures (above 72 kbps) or on a declared
+ * Opus maxaveragebitrate above 64,000, so a standard microphone must not
+ * drift into either. `maxBitrate` is the Opus maxaveragebitrate declared to
+ * the server and the encoder; `senderMaxBitrate` is the sender's cap, which
+ * holds the encoder there. Standard's sender is held a little under the
+ * declared 64 kbps: Opus VBR around a 64 kbps target measured up to 65 kbps
+ * in a 5 s window, and the cap keeps every window at or under 64.
+ */
+export const AUDIO_SETTINGS: Readonly<Record<AudioQuality, { stereo: boolean; maxBitrate: number; senderMaxBitrate: number }>> = {
+  std: { stereo: false, maxBitrate: 64_000, senderMaxBitrate: 60_000 },
+  hd: { stereo: true, maxBitrate: 128_000, senderMaxBitrate: 128_000 },
+};
+
+/** One media profile from the join result: the encoding contract of a mode, as the server stores it. */
+export interface MediaProfile {
+  id?: string;
+  kind?: 'audio' | 'video';
+  enabled?: boolean;
+  width?: number;
+  height?: number;
+  fps?: number;
+  maxBitrate?: number;
+  [field: string]: unknown;
+}
+
+/** The join result's `media` field (servers with wallet billing); absent from older servers. */
+export interface JoinMedia {
+  /** The enabled modes the project's settings allow, by id (`audio_std`, `video_720_60`, ...). */
+  profiles: Record<string, MediaProfile>;
+  /** The project's settings, hierarchical: a maximum allows every mode at or below it. */
+  permissions: {
+    audio: boolean;
+    video: boolean;
+    maxVideoQuality: 480 | 720 | 1080;
+    maxFrameRate: 30 | 60;
+    audioQualityMax: AudioQuality;
+  };
+  /** How many videos one participant receives at most, and how many of them above 360p. */
+  fanout: { maxHdVideoSubscriptions: number; maxVideoSubscriptions: number };
+  profilesVersion?: number;
+}
+
+/** How the session is billed: flat minutes (`legacy`) or the VoltKit wallet (`wallet`). */
+export type BillingMode = 'legacy' | 'wallet';
+
+export interface JoinBilling {
+  mode: BillingMode;
+}
+
+/** What this client may publish right now. */
+export interface MediaPermissions {
+  /** Microphone, music and screen audio. */
+  audio: boolean;
+  /** Camera and screen. */
+  video: boolean;
+  /** The largest video quality at 30 fps. */
+  maxVideoQuality: VideoQuality;
+  /** 60 when some 60 fps mode is allowed. */
+  maxFrameRate: 30 | 60;
+  /** The largest video quality at 60 fps; null when 60 fps is not allowed. */
+  maxVideoQuality60: VideoQuality | null;
+  audioQualityMax: AudioQuality;
+  /** The most videos this client receives at once; null when the server sets no limit. */
+  maxVideoSubscriptions: number | null;
+  /** Where these came from: the join result's `media`, the older `video` policy, or defaults before a join. */
+  source: 'media' | 'video-policy' | 'default';
+}
+
+/** Before a join nothing is known: everything is open, and the join result narrows it. */
+export const DEFAULT_MEDIA_PERMISSIONS: MediaPermissions = Object.freeze({
+  audio: true,
+  video: true,
+  maxVideoQuality: '1080p',
+  maxFrameRate: 60,
+  maxVideoQuality60: '1080p',
+  audioQualityMax: 'hd',
+  maxVideoSubscriptions: null,
+  source: 'default',
+});
+
+const RANK: Record<VideoQuality, number> = { '480p': 0, '720p': 1, '1080p': 2 };
+const lower = (a: VideoQuality, b: VideoQuality): VideoQuality => (RANK[a] <= RANK[b] ? a : b);
+
+/** A video height (or a profile's shorter side) as the quality that holds it. */
+function qualityOfHeight(height: unknown): VideoQuality | null {
+  if (typeof height !== 'number' || !Number.isFinite(height) || height <= 0) return null;
+  if (height >= 1080) return '1080p';
+  if (height >= 720) return '720p';
+  return '480p';
+}
+
+const PROFILE_ID = /^video_(\d+)_(\d+)$/;
+
+/** The size and frame rate of a video profile: its own fields, else its id (`video_720_60`). */
+function videoMode(id: string, p: MediaProfile): { quality: VideoQuality; fps: number } | null {
+  const fromId = PROFILE_ID.exec(id);
+  const height = typeof p.height === 'number' ? p.height : fromId ? Number(fromId[1]) : NaN;
+  const fps = typeof p.fps === 'number' ? p.fps : fromId ? Number(fromId[2]) : NaN;
+  const quality = qualityOfHeight(height);
+  return quality && Number.isFinite(fps) ? { quality, fps } : null;
+}
+
+function kindOf(id: string, p: MediaProfile): 'audio' | 'video' | null {
+  if (p.kind === 'audio' || p.kind === 'video') return p.kind;
+  if (id.startsWith('audio_')) return 'audio';
+  if (id.startsWith('video_')) return 'video';
+  return null;
+}
+
+/** The join result fields these come from. */
+export interface PermissionSource {
+  video?: VideoPolicy;
+  media?: JoinMedia;
+  billing?: JoinBilling;
+}
+
+/**
+ * Resolve what may be published. The legacy `video` policy and `media` both
+ * apply (the lower wins). The profiles narrow a **wallet** session only: they
+ * are what its tiers bill, and the media node caps to them; a session billed
+ * the flat way keeps every mode its settings allow, as it always had.
+ */
+export function resolvePermissions(join: PermissionSource | null | undefined): MediaPermissions {
+  if (!join) return DEFAULT_MEDIA_PERMISSIONS;
+  const policy = join.video;
+  const policyMax = allowedQuality(undefined, policy ?? { maxQuality: '1080p' });
+  const policyFps: 30 | 60 = policy?.maxFrameRate === 30 ? 30 : 60;
+  const media = join.media;
+  if (!media || typeof media !== 'object' || !media.permissions) {
+    return {
+      audio: true,
+      video: true,
+      maxVideoQuality: policyMax,
+      maxFrameRate: policyFps,
+      maxVideoQuality60: policyFps === 60 ? policyMax : null,
+      audioQualityMax: 'hd',
+      maxVideoSubscriptions: null,
+      source: policy ? 'video-policy' : 'default',
+    };
+  }
+
+  const perm = media.permissions;
+  let audio = perm.audio !== false;
+  let video = perm.video !== false;
+  let maxVideoQuality = lower(qualityOfHeight(perm.maxVideoQuality) ?? '1080p', policyMax);
+  let maxFrameRate: 30 | 60 = perm.maxFrameRate === 30 || policyFps === 30 ? 30 : 60;
+  let audioQualityMax: AudioQuality = perm.audioQualityMax === 'std' ? 'std' : 'hd';
+  let maxVideoQuality60: VideoQuality | null = maxFrameRate === 60 ? maxVideoQuality : null;
+  let maxVideoSubscriptions: number | null = null;
+
+  const wallet = join.billing?.mode === 'wallet';
+  const profiles = media.profiles && typeof media.profiles === 'object' ? media.profiles : {};
+  const documented = (media.profilesVersion ?? 0) > 0 || Object.keys(profiles).length > 0;
+  if (wallet && documented) {
+    // The largest enabled mode at each frame rate within the settings: what
+    // the media node caps a producer to. A size whose own mode is disabled is
+    // refused at 60 fps and capped at 30, so neither may be asked for.
+    const cap = maxVideoQuality;
+    let max30: VideoQuality | null = null;
+    let max60: VideoQuality | null = null;
+    let std = false;
+    let hd = false;
+    for (const [id, profile] of Object.entries(profiles)) {
+      if (!profile || profile.enabled === false) continue;
+      const kind = kindOf(id, profile);
+      if (kind === 'audio') {
+        if (id === 'audio_hd') hd = true;
+        else std = true;
+      } else if (kind === 'video') {
+        const mode = videoMode(id, profile);
+        if (!mode || RANK[mode.quality] > RANK[cap]) continue;
+        if (mode.fps > 30) max60 = max60 && RANK[max60] >= RANK[mode.quality] ? max60 : mode.quality;
+        else max30 = max30 && RANK[max30] >= RANK[mode.quality] ? max30 : mode.quality;
+      }
+    }
+    // No enabled mode of a kind is that kind switched off: the controller
+    // refuses it as media-disabled.
+    audio = audio && (std || hd);
+    if (!hd) audioQualityMax = 'std';
+    video = video && (max30 !== null || max60 !== null);
+    maxVideoQuality = max30 ?? max60 ?? cap;
+    maxVideoQuality60 = maxFrameRate === 60 ? max60 : null;
+    if (!maxVideoQuality60) maxFrameRate = 30;
+  }
+  if (wallet) {
+    const limit = media.fanout?.maxVideoSubscriptions;
+    maxVideoSubscriptions = typeof limit === 'number' && Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : null;
+  }
+  return { audio, video, maxVideoQuality, maxFrameRate, maxVideoQuality60, audioQualityMax, maxVideoSubscriptions, source: 'media' };
+}
+
+/** The quality to send at a frame rate: the request, capped to what that frame rate allows. */
+export function qualityAt(requested: VideoQuality | undefined, frameRate: 30 | 60, permissions: MediaPermissions): VideoQuality {
+  const max = frameRate === 60 && permissions.maxVideoQuality60 ? permissions.maxVideoQuality60 : permissions.maxVideoQuality;
+  return allowedQuality(requested, { maxQuality: max });
+}
+
+/** Whether an explicit request for this quality at 60 fps is above what 60 fps allows. */
+export function above60fpsCap(requested: VideoQuality | undefined, permissions: MediaPermissions): boolean {
+  if (!requested || !(requested in RANK) || !permissions.maxVideoQuality60) return false;
+  return RANK[lower(requested, permissions.maxVideoQuality)] > RANK[permissions.maxVideoQuality60];
+}

package/src/network.ts

@@ -0,0 +1,212 @@
+/**
+ * Network quality, from the media transports' WebRTC statistics: round-trip
+ * time, packet loss in the worse direction, and the bandwidth the browser
+ * estimates it can use. A level sums them up for a UI, with documented
+ * thresholds (docs/SDK-CONTRACT.md, "Network quality").
+ *
+ * The parsers are pure, like stats.ts: they take the stats objects of a
+ * getStats() report and the previous sample's counters.
+ */
+import type { StatsEntry } from './stats.js';
+
+export type NetworkQualityLevel = 'excellent' | 'good' | 'poor' | 'bad';
+
+export interface NetworkQuality {
+  level: NetworkQualityLevel;
+  /** Round trip to the media server, in ms; null before the browser has measured one. */
+  rttMs: number | null;
+  /** Packets lost over the last interval, in percent, the worse of sending and receiving; null when nothing moved. */
+  lossPct: number | null;
+  /** The bandwidth the browser estimates it can use, in kbps: upload while publishing, else download when reported. */
+  availableKbps: number | null;
+}
+
+/** How often the transports are sampled while someone listens for `networkQuality`. */
+export const NETWORK_QUALITY_INTERVAL_MS = 3000;
+
+/**
+ * The thresholds: the first level whose round trip and loss are both below
+ * its limits, else `bad`. An unknown value does not lower the level.
+ */
+export const NETWORK_QUALITY_LEVELS: readonly { level: Exclude<NetworkQualityLevel, 'bad'>; rttMsBelow: number; lossPctBelow: number }[] = [
+  { level: 'excellent', rttMsBelow: 150, lossPctBelow: 1 },
+  { level: 'good', rttMsBelow: 300, lossPctBelow: 3 },
+  { level: 'poor', rttMsBelow: 500, lossPctBelow: 8 },
+];
+
+export function networkLevel(rttMs: number | null, lossPct: number | null): NetworkQualityLevel {
+  for (const l of NETWORK_QUALITY_LEVELS) {
+    if ((rttMs === null || rttMs < l.rttMsBelow) && (lossPct === null || lossPct < l.lossPctBelow)) return l.level;
+  }
+  return 'bad';
+}
+
+/** One transport's counters at one moment; the next sample's deltas are taken against it. */
+export interface TransportSample {
+  /** The selected candidate pair's current round trip, in ms. */
+  rttMs: number | null;
+  /** The round trip RTCP reports from the server, in ms (a fallback). */
+  remoteRttMs: number | null;
+  /** RTP packets sent, and how many of them the server reported lost. */
+  packetsSent: number;
+  remotePacketsLost: number;
+  /** RTP packets received, and how many were lost on the way. */
+  packetsReceived: number;
+  packetsLost: number;
+  /** Bits per second the browser estimates it can send / receive. */
+  availableOutgoing: number | null;
+  availableIncoming: number | null;
+}
+
+const num = (value: unknown): number => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const optNum = (value: unknown): number | undefined => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+
+/** The counters of one transport's report. */
+export function readTransportStats(report: Iterable<StatsEntry>): TransportSample {
+  const entries = [...report].filter((e): e is StatsEntry => typeof e === 'object' && e !== null);
+  const byId = new Map<string, StatsEntry>();
+  for (const entry of entries) if (typeof entry.id === 'string') byId.set(entry.id, entry);
+
+  // The candidate pair in use: the transport's selected one, else a nominated
+  // succeeded pair (Firefox reports no transport entry).
+  let pair: StatsEntry | undefined;
+  for (const transport of entries.filter((e) => e.type === 'transport')) {
+    const selected = typeof transport.selectedCandidatePairId === 'string' ? byId.get(transport.selectedCandidatePairId) : undefined;
+    if (selected) { pair = selected; break; }
+  }
+  if (!pair) {
+    const pairs = entries.filter((e) => e.type === 'candidate-pair');
+    pair = pairs.find((p) => p.nominated === true && p.state === 'succeeded') ?? pairs.find((p) => p.selected === true);
+  }
+  const rtt = optNum(pair?.currentRoundTripTime);
+
+  let remoteRtt: number | undefined;
+  let packetsSent = 0;
+  let remotePacketsLost = 0;
+  let packetsReceived = 0;
+  let packetsLost = 0;
+  for (const e of entries) {
+    if (e.type === 'outbound-rtp') packetsSent += num(e.packetsSent);
+    else if (e.type === 'remote-inbound-rtp') {
+      remotePacketsLost += Math.max(0, num(e.packetsLost));
+      const r = optNum(e.roundTripTime);
+      if (r !== undefined) remoteRtt = Math.max(remoteRtt ?? 0, r);
+    } else if (e.type === 'inbound-rtp') {
+      packetsReceived += num(e.packetsReceived);
+      packetsLost += Math.max(0, num(e.packetsLost));
+    }
+  }
+  const out = optNum(pair?.availableOutgoingBitrate);
+  const inc = optNum(pair?.availableIncomingBitrate);
+  return {
+    rttMs: rtt === undefined ? null : Math.round(rtt * 1000),
+    remoteRttMs: remoteRtt === undefined ? null : Math.round(remoteRtt * 1000),
+    packetsSent,
+    remotePacketsLost,
+    packetsReceived,
+    packetsLost,
+    availableOutgoing: out ?? null,
+    availableIncoming: inc ?? null,
+  };
+}
+
+const pct = (lost: number, total: number): number | null => (total > 0 ? Math.round((Math.min(lost, total) / total) * 1000) / 10 : null);
+
+/**
+ * The quality now, from each transport's sample and the one before it (by
+ * key; a transport that is new, or whose counters went backwards, gives no
+ * loss for this interval). `publishing` picks the upload estimate.
+ */
+export function networkQualityOf(
+  current: ReadonlyMap<string, TransportSample>,
+  previous: ReadonlyMap<string, TransportSample>,
+  publishing: boolean,
+): NetworkQuality {
+  let rttMs: number | null = null;
+  let lossPct: number | null = null;
+  let upload: number | null = null;
+  let download: number | null = null;
+  for (const [key, now] of current) {
+    const rtt = now.rttMs ?? now.remoteRttMs;
+    if (rtt !== null) rttMs = Math.max(rttMs ?? 0, rtt);
+    if (now.availableOutgoing !== null) upload = Math.max(upload ?? 0, now.availableOutgoing);
+    if (now.availableIncoming !== null) download = Math.max(download ?? 0, now.availableIncoming);
+    const before = previous.get(key);
+    if (!before) continue;
+    const sent = now.packetsSent - before.packetsSent;
+    const remoteLost = now.remotePacketsLost - before.remotePacketsLost;
+    const received = now.packetsReceived - before.packetsReceived;
+    const lost = now.packetsLost - before.packetsLost;
+    // Counters only go forward on one transport; backwards is a new one.
+    const up = sent >= 0 && remoteLost >= 0 ? pct(remoteLost, sent) : null;
+    const down = received >= 0 && lost >= 0 ? pct(lost, received + lost) : null;
+    for (const value of [up, down]) if (value !== null) lossPct = Math.max(lossPct ?? 0, value);
+  }
+  const bandwidth = publishing ? upload ?? download : download ?? upload;
+  return {
+    level: networkLevel(rttMs, lossPct),
+    rttMs,
+    lossPct,
+    availableKbps: bandwidth === null ? null : Math.round(bandwidth / 1000),
+  };
+}
+
+/**
+ * Samples the transports on a timer while wanted and reports each interval.
+ * The first report comes as soon as a round trip is known; loss needs the
+ * previous interval's counters, so it is null until the second.
+ */
+export class NetworkQualityWatch {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private previous = new Map<string, TransportSample>();
+  private sampling = false;
+  private generation = 0;
+
+  constructor(
+    /** Each live transport's report, by a key that changes when the transport does. */
+    private readonly sample: () => Promise<Map<string, Iterable<StatsEntry>>>,
+    private readonly publishing: () => boolean,
+    private readonly report: (quality: NetworkQuality) => void,
+    private readonly intervalMs = NETWORK_QUALITY_INTERVAL_MS,
+  ) {}
+
+  get running(): boolean {
+    return this.timer !== null;
+  }
+
+  /** Start or stop sampling. Safe to call as often as anything changes. */
+  set(wanted: boolean): void {
+    if (wanted && !this.timer) {
+      this.timer = setInterval(() => void this.tick(), this.intervalMs);
+      void this.tick();
+    } else if (!wanted && this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+      this.generation += 1;
+      this.previous = new Map();
+    }
+  }
+
+  private async tick(): Promise<void> {
+    if (this.sampling) return;
+    const generation = this.generation;
+    this.sampling = true;
+    try {
+      const reports = await this.sample();
+      if (generation !== this.generation || !this.timer) return;
+      const current = new Map<string, TransportSample>();
+      for (const [key, report] of reports) current.set(key, readTransportStats(report));
+      const first = this.previous.size === 0;
+      const quality = networkQualityOf(current, this.previous, this.publishing());
+      this.previous = current;
+      // Nothing to report without a transport, or before a second sample
+      // when not even the round trip is known yet.
+      if (current.size === 0 || (first && quality.rttMs === null)) return;
+      this.report(quality);
+    } catch {
+      // Statistics are best effort; the next interval tries again.
+    } finally {
+      this.sampling = false;
+    }
+  }
+}

package/src/token.ts

@@ -0,0 +1,31 @@
+/**
+ * When a room token expires, read from the token itself. Not verified -- the
+ * server does that -- and only used to warn before the token the SDK would
+ * reconnect with lapses (`tokenExpiring`).
+ */
+
+/** How long before the token's expiry `tokenExpiring` fires. */
+export const TOKEN_EXPIRING_LEAD_MS = 60_000;
+
+/**
+ * The socket URL with the token as its `token` query parameter. Joined by
+ * hand rather than with `URL.searchParams`: React Native's `URL` is a partial
+ * polyfill (older releases had no `searchParams.set`), and a WebSocket URL has
+ * no fragment, so the string form is the same as the URL object's.
+ */
+export function socketUrl(wsUrl: string, token: string): string {
+  return `${wsUrl}${wsUrl.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}`;
+}
+
+/** The `exp` claim of a JWT, in unix milliseconds; null for a token that is not a readable JWT. */
+export function tokenExpiresAt(token: string): number | null {
+  const payload = typeof token === 'string' ? token.split('.')[1] : undefined;
+  if (!payload || typeof globalThis.atob !== 'function') return null;
+  try {
+    const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+    const json = JSON.parse(globalThis.atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4))) as { exp?: unknown };
+    return typeof json.exp === 'number' && Number.isFinite(json.exp) && json.exp > 0 ? json.exp * 1000 : null;
+  } catch {
+    return null;
+  }
+}