@voltkit-rtc/client 0.7.3 → 0.8.0

package/src/health.ts

@@ -0,0 +1,127 @@
+/**
+ * Media health warnings (docs/implementation-progress/RTC_PERF_PROGRESS.md K1).
+ *
+ * - Agora's `exception` event pairs each problem with its recovery: FRAMERATE_INPUT_TOO_LOW / _RECOVER (the camera
+ *   delivers too few frames), AUDIO_INPUT_LEVEL_TOO_LOW / _RECOVER, ...
+ * - LiveKit's `AudioSilenceDetected`: a microphone that delivers nothing but silence (a hardware mute switch, a
+ *   broken device) right after it starts.
+ * - LiveKit watches the track's `mute` event (the OS took the device: a phone call, another app) and reacts after 5 s.
+ *
+ * Each warning is reported once when it starts (`active: true`) and once when it clears (`active: false`).
+ * Pure: the decisions take samples.
+ */
+
+export type MediaWarningCode =
+  /** The microphone is on but delivers exact digital silence: a mute switch, a broken or wrongly chosen device. */
+  | 'mic-silent'
+  /** The camera delivers far fewer frames than asked: usually a dark room (the camera exposes longer), or a busy device. */
+  | 'camera-fps-low'
+  /** The system took the camera from this page for now (a phone call, another app, a locked screen). */
+  | 'camera-interrupted'
+  /** The system took the microphone (a phone call, another app). */
+  | 'mic-interrupted';
+
+export interface MediaWarning {
+  code: MediaWarningCode;
+  /** true when it starts, false when it clears. */
+  active: boolean;
+}
+
+/** How often the published camera and microphone are sampled while someone listens. */
+export const HEALTH_SAMPLE_MS = 2000;
+/** Samples of exact silence before mic-silent (6 s). */
+export const SILENT_SAMPLES = 3;
+/** Below this the level counts as exact digital silence (a real room's noise floor is well above it). */
+export const SILENCE_LEVEL = 0.0001;
+/** Fewer frames than this per second, when 24 or more were asked, is camera-fps-low. */
+export const LOW_FPS = 15;
+/** Samples below LOW_FPS before warning (6 s); samples at RECOVERED_FPS or more before clearing. */
+export const LOW_FPS_SAMPLES = 3;
+export const RECOVERED_FPS = 20;
+export const RECOVER_SAMPLES = 2;
+/** A system mute shorter than this is a glitch, not an interruption. */
+export const INTERRUPTED_AFTER_MS = 2000;
+
+/** One reading of the published devices. null: not published (or nothing measured). */
+export interface HealthSample {
+  /** The microphone's level, while it is on. */
+  micLevel: number | null;
+  /** The frames per second the camera delivers, while it is on, and what was asked. */
+  cameraFps: number | null;
+  askedFps: number;
+}
+
+/** Decides mic-silent and camera-fps-low from samples. */
+export class HealthDecisions {
+  private silent = 0;
+  private lowFps = 0;
+  private goodFps = 0;
+  private readonly activeNow = new Set<MediaWarningCode>();
+
+  constructor(private readonly report: (warning: MediaWarning) => void) {}
+
+  isActive(code: MediaWarningCode): boolean {
+    return this.activeNow.has(code);
+  }
+
+  feed(sample: HealthSample): void {
+    // mic-silent: exact silence held; any sound clears it. Off or unpublished: not a warning.
+    if (sample.micLevel === null) {
+      this.silent = 0;
+      this.set('mic-silent', false);
+    } else if (sample.micLevel <= SILENCE_LEVEL) {
+      this.silent += 1;
+      if (this.silent >= SILENT_SAMPLES) this.set('mic-silent', true);
+    } else {
+      this.silent = 0;
+      this.set('mic-silent', false);
+    }
+
+    // camera-fps-low: only when a smooth rate was asked; cleared once it holds again.
+    if (sample.cameraFps === null || sample.askedFps < 24) {
+      this.lowFps = 0;
+      this.goodFps = 0;
+      this.set('camera-fps-low', false);
+    } else if (sample.cameraFps < LOW_FPS) {
+      this.goodFps = 0;
+      this.lowFps += 1;
+      if (this.lowFps >= LOW_FPS_SAMPLES) this.set('camera-fps-low', true);
+    } else {
+      this.lowFps = 0;
+      if (sample.cameraFps >= RECOVERED_FPS) this.goodFps += 1;
+      if (this.goodFps >= RECOVER_SAMPLES) this.set('camera-fps-low', false);
+    }
+  }
+
+  /** A system interruption started or ended (decided by the caller's timer). */
+  interrupted(code: 'camera-interrupted' | 'mic-interrupted', active: boolean): void {
+    this.set(code, active);
+  }
+
+  /** Everything clears (unpublished, closed): each active warning is reported cleared. */
+  clearAll(): void {
+    for (const code of [...this.activeNow]) this.set(code, false);
+    this.silent = 0;
+    this.lowFps = 0;
+    this.goodFps = 0;
+  }
+
+  private set(code: MediaWarningCode, active: boolean): void {
+    if (this.activeNow.has(code) === active) return;
+    if (active) this.activeNow.add(code);
+    else this.activeNow.delete(code);
+    this.report({ code, active });
+  }
+}
+
+/** The microphone level and camera frame rate from a producer's statistics (media-source). */
+export function readMediaSource(report: Iterable<Record<string, unknown>>): { level: number | null; fps: number | null } {
+  let level: number | null = null;
+  let fps: number | null = null;
+  for (const s of report) {
+    if (s.type !== 'media-source') continue;
+    if (typeof s.audioLevel === 'number') level = s.audioLevel;
+    if (typeof s.framesPerSecond === 'number') fps = s.framesPerSecond;
+  }
+  return { level, fps };
+}