@voltkit-rtc/client 0.3.0 → 0.5.0

package/src/music.ts

@@ -22,7 +22,7 @@ export interface MusicOptions {
   monitor?: boolean;
 }
 
-export type TrackSource = 'mic' | 'music' | 'camera' | 'screen';
+export type TrackSource = 'mic' | 'music' | 'camera' | 'screen' | 'screen-audio';
 
 let shared: AudioContext | null = null;
 /** A media element can be wired to one audio graph, once, for its whole life. */

package/src/quality.ts

@@ -1,25 +1,22 @@
-/**
- * Video quality tiers and the simulcast layers sent for each.
- *
- * A project can publish at 720p or 480p on any plan. 1080p uses more
- * bandwidth, so the server allows it only for projects that have it enabled,
- * and during the free trial; the join result says which (`video.maxQuality`),
- * and the server caps each publisher's incoming bitrate to match.
- */
+/** All video qualities are available on every plan; per-project safety restrictions still apply. */
 
 export type VideoQuality = '1080p' | '720p' | '480p';
 
 export const VIDEO_QUALITIES: readonly VideoQuality[] = ['1080p', '720p', '480p'];
 
+/** How many simulcast layers to send at most. */
+export type LayerCount = 1 | 2 | 3;
+
 /** What the server allows this project to publish, from the join result. */
 export interface VideoPolicy {
-  maxQuality: '1080p' | '720p';
+  maxQuality: VideoQuality;
+  maxFrameRate?: 30 | 60;
   /** The server's cap on one publisher's incoming bitrate, in bits per second. */
   maxBitrate?: number;
 }
 
 /** Servers from before quality tiers send no policy; they get the default tier. */
-export const DEFAULT_VIDEO_POLICY: VideoPolicy = { maxQuality: '720p' };
+export const DEFAULT_VIDEO_POLICY: VideoPolicy = { maxQuality: '1080p', maxFrameRate: 60 };
 
 /** Each tier's 16:9 frame. */
 const TIER_SIZE: Record<VideoQuality, { width: number; height: number }> = {
@@ -32,23 +29,19 @@ const RANK: Record<VideoQuality, number> = { '480p': 0, '720p': 1, '1080p': 2 };
 
 /** The lower of what was asked for and what the project may use. */
 export function allowedQuality(requested: VideoQuality | undefined, policy: VideoPolicy = DEFAULT_VIDEO_POLICY): VideoQuality {
-  const max = policy.maxQuality === '1080p' ? '1080p' : '720p';
+  const max = policy.maxQuality in RANK ? policy.maxQuality : '1080p';
   const wanted = requested && requested in RANK ? requested : max;
   return RANK[wanted] <= RANK[max] ? wanted : max;
 }
 
-/**
- * The bitrate a layer of this many pixels gets, at up to 30 fps.
- * About 1080p 2.5 Mbps, 720p 1.8 Mbps, 540p 1.2 Mbps, 480p 750 kbps,
- * 360p 600 kbps, 240p 250 kbps, smaller 200 kbps.
- */
+/** The authoritative 30 fps bitrate for a layer of this many pixels. */
 export function layerBitrate(pixels: number): number {
-  if (pixels >= 1_800_000) return 2_500_000;
-  if (pixels >= 800_000) return 1_800_000;
-  if (pixels >= 450_000) return 1_200_000;
-  if (pixels >= 360_000) return 750_000;
-  if (pixels >= 200_000) return 600_000;
-  if (pixels >= 100_000) return 250_000;
+  if (pixels >= 1_800_000) return 6_000_000;
+  if (pixels >= 800_000) return 3_000_000;
+  if (pixels >= 450_000) return 2_000_000;
+  if (pixels >= 360_000) return 1_200_000;
+  if (pixels >= 200_000) return 800_000;
+  if (pixels >= 100_000) return 400_000;
   return 200_000;
 }
 
@@ -57,11 +50,26 @@ export interface VideoEncoding {
   scaleResolutionDownBy: number;
   maxBitrate: number;
   scalabilityMode: 'L1T3';
+  maxFramerate: number;
+}
+
+/**
+ * The size the top layer is sent at: the camera picture scaled down to the
+ * tier (never up), keeping its shape. An unknown size (some tracks don't
+ * report one) is taken to be the tier's own frame.
+ */
+export function topLayerSize(width: number, height: number, quality: VideoQuality): { width: number; height: number; scale: number } {
+  const tier = TIER_SIZE[quality] ?? TIER_SIZE['720p'];
+  const known = width > 0 && height > 0;
+  const w = known ? width : tier.width;
+  const h = known ? height : tier.height;
+  const scale = Math.max(1, Math.max(w, h) / tier.width);
+  return { width: w / scale, height: h / scale, scale };
 }
 
 /**
  * The simulcast layers for a camera picture of `width` × `height` at
- * `quality`.
+ * `quality`, sending at most `maxLayers` of them.
  *
  * The top layer is the picture scaled down to the tier (never up). The number
  * of layers follows what browsers really send for a picture that size: Chrome
@@ -69,23 +77,79 @@ export interface VideoEncoding {
  * when a picture is too small for the layers asked for it drops the TOP ones,
  * which would leave viewers with half or a quarter of the resolution. Asking
  * for exactly as many layers as will be sent keeps the full picture.
+ *
+ * Fewer layers are dropped from the bottom: two are half and full size, so the
+ * full picture is always one of them. That matters on a busy phone, where the
+ * browser shrinks the picture and then sends fewer layers: from two it keeps
+ * the full one, from three it lost it.
  */
-export function videoEncodings(width: number, height: number, quality: VideoQuality): VideoEncoding[] {
-  const tier = TIER_SIZE[quality] ?? TIER_SIZE['720p'];
-  // Size unknown (some tracks don't report it): assume the tier's own frame.
-  const w = width > 0 && height > 0 ? width : tier.width;
-  const h = width > 0 && height > 0 ? height : tier.height;
-  const scale = Math.max(1, Math.max(w, h) / tier.width);
-  const top = (w / scale) * (h / scale);
-  const layers = top >= 960 * 540 ? 3 : top >= 480 * 270 ? 2 : 1;
+export function videoEncodings(width: number, height: number, quality: VideoQuality, maxLayers: LayerCount = 3, frameRate: 30 | 60 = 30): VideoEncoding[] {
+  const { width: w, height: h, scale } = topLayerSize(width, height, quality);
+  const top = w * h;
+  const possible = top >= 960 * 540 ? 3 : top >= 480 * 270 ? 2 : 1;
+  const wanted = maxLayers === 1 || maxLayers === 2 ? maxLayers : 3;
+  const layers = Math.min(wanted, possible);
   const round = (value: number) => Math.round(value * 1000) / 1000;
   const layer = (divisor: number, rid?: string): VideoEncoding => ({
     ...(rid ? { rid } : {}),
     scaleResolutionDownBy: round(scale * divisor),
-    maxBitrate: layerBitrate(top / (divisor * divisor)),
+    maxBitrate: layerBitrate(top / (divisor * divisor)) * (divisor === 1 && frameRate === 60 ? 1.5 : 1),
+    maxFramerate: divisor === 1 ? frameRate : 30,
     scalabilityMode: 'L1T3',
   });
   if (layers === 3) return [layer(4, 'q'), layer(2, 'h'), layer(1, 'f')];
   if (layers === 2) return [layer(2, 'h'), layer(1, 'f')];
   return [layer(1)];
 }
+
+/**
+ * Whether two sets of layers are laid out alike: as many layers, each scaled
+ * the same. A track can then be swapped under the same producer without
+ * renegotiating; anything else needs a new producer.
+ */
+export function sameLayout(a: readonly VideoEncoding[], b: readonly VideoEncoding[]): boolean {
+  return a.length === b.length && a.every((encoding, i) => encoding.scaleResolutionDownBy === b[i].scaleResolutionDownBy);
+}
+
+/** Actual producer layer dimensions, smallest first; includes portrait and screen video. */
+export interface VideoLayer {
+  spatialLayer: number;
+  width: number;
+  height: number;
+}
+
+export type ReceiveQuality = 'auto' | VideoQuality;
+export type ScreenMode = 'detail' | 'motion';
+
+/** Never invent layers when an older producer does not describe them. */
+export function receiveSpatialLayer(layers: readonly VideoLayer[], quality: VideoQuality): number {
+  const valid = layers.filter((l) => Number.isInteger(l.spatialLayer) && l.spatialLayer >= 0 &&
+    Number.isFinite(l.width) && l.width > 0 && Number.isFinite(l.height) && l.height > 0)
+    .sort((a, b) => a.width * a.height - b.width * b.height);
+  if (!valid.length) throw new Error('producer has no video layer metadata');
+  const tier = TIER_SIZE[quality];
+  const fitting = valid.filter((l) => Math.max(l.width, l.height) <= tier.width + 1 && Math.min(l.width, l.height) <= tier.height + 1);
+  return (fitting.at(-1) ?? valid[0]).spatialLayer;
+}
+
+export function describeVideoLayers(width: number, height: number, encodings: readonly VideoEncoding[], quality: VideoQuality = '1080p'): VideoLayer[] {
+  const fallback = TIER_SIZE[quality];
+  const w = width > 0 ? width : fallback.width;
+  const h = height > 0 ? height : fallback.height;
+  return encodings.map((encoding, spatialLayer) => ({ spatialLayer, width: Math.round(w / encoding.scaleResolutionDownBy), height: Math.round(h / encoding.scaleResolutionDownBy) }));
+}
+
+/** Screen frames are capped to native 1080p, never enlarged, with two adaptive copies. */
+export function screenEncodings(width: number, height: number, mode: ScreenMode = 'detail'): VideoEncoding[] {
+  const nativeWidth = width > 0 ? width : 1920;
+  const nativeHeight = height > 0 ? height : 1080;
+  const scale = Math.max(1, Math.max(nativeWidth, nativeHeight) / 1920, Math.min(nativeWidth, nativeHeight) / 1080);
+  const w = nativeWidth / scale;
+  const h = nativeHeight / scale;
+  const layer = (divisor: number, rid?: string): VideoEncoding => ({
+    ...(rid ? { rid } : {}), scaleResolutionDownBy: scale * divisor,
+    maxBitrate: divisor === 1 ? (mode === 'motion' ? 6_000_000 : 2_500_000) : 600_000,
+    maxFramerate: mode === 'motion' ? 30 : 15, scalabilityMode: 'L1T3',
+  });
+  return w * h >= 480 * 270 ? [layer(2, 'h'), layer(1, 'f')] : [layer(1)];
+}

package/src/stats.ts

@@ -0,0 +1,328 @@
+/**
+ * What the camera is really sending, and what a viewer is really receiving,
+ * read from the browser's WebRTC statistics.
+ *
+ * The parsers are pure: they take the stats objects a `getStats()` report
+ * holds and a baseline of byte counts from the previous call, so they can be
+ * tested with plain objects. Bitrates are the bytes sent or received since
+ * the previous call for the same key, over the time between the two reports'
+ * timestamps: 0 on the first call.
+ */
+import type { VideoQuality } from './quality.js';
+
+/** One simulcast layer of the camera video. */
+export interface VideoLayerStats {
+  /** The layer's RTP stream id, as the browser reports it (`r0` is the smallest). */
+  rid?: string;
+  width: number;
+  height: number;
+  fps: number;
+  /** Bits per second since the previous call; 0 on the first. */
+  bitrate: number;
+  /** Switched on, and frames or bytes are going out. */
+  active: boolean;
+  /** Why the browser is sending less than asked: `cpu`, `bandwidth`, `other` or `none`. */
+  qualityLimitation?: string;
+}
+
+/** What the camera is sending. The top-level fields describe the biggest active layer. */
+export interface VideoSendStats {
+  /** `VP8` or `H264`, when the browser says. */
+  codec?: string;
+  /** The quality being published, after the project's limit. */
+  quality: VideoQuality;
+  width: number;
+  height: number;
+  fps: number;
+  bitrate: number;
+  qualityLimitation?: string;
+  /** The browser's estimate of the upload it can use, in bits per second. */
+  availableOutgoingBitrate?: number;
+  /** Every layer, smallest first. */
+  layers: VideoLayerStats[];
+}
+
+/** What this client is receiving of someone's video. */
+export interface VideoReceiveStats {
+  producerId: string;
+  codec?: string;
+  width: number;
+  height: number;
+  fps: number;
+  /** Bits per second since the previous call for this video; 0 on the first. */
+  bitrate: number;
+  /** Packets lost since this video started. */
+  packetsLost: number;
+  /** Seconds, as the browser reports it. */
+  jitter?: number;
+  /** How many times the picture froze, where the browser counts it. */
+  freezeCount?: number;
+}
+
+/** A stats object as a report holds it. Only `type` is relied on. */
+export type StatsEntry = Record<string, unknown>;
+
+/** Byte counts and their report time from the previous call, per key. The caller keeps it. */
+export type StatsBaseline = Map<string, { bytes: number; timestamp: number }>;
+
+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);
+const optStr = (value: unknown): string | undefined => (typeof value === 'string' && value !== '' ? value : undefined);
+const oneDecimal = (value: number): number => 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: StatsBaseline, key: string, bytes: number, timestamp: number): number {
+  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: StatsBaseline, keep: (key: string) => boolean): void {
+  for (const key of [...baseline.keys()]) {
+    if (!keep(key)) baseline.delete(key);
+  }
+}
+
+const isVideo = (entry: StatsEntry): boolean => entry.kind === 'video' || entry.mediaType === 'video';
+
+/** `VP8` from the codec entry an RTP stream points at. */
+function codecOf(byId: Map<string, StatsEntry>, entry: StatsEntry | undefined): string | undefined {
+  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: StatsEntry[], byId: Map<string, StatsEntry>): number | undefined {
+  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: { width: number; height: number }): number => layer.width * layer.height;
+
+/** r0, r1, r2 in order; layers without a rid by size. */
+function layerOrder(a: VideoLayerStats, b: VideoLayerStats): number {
+  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: Iterable<StatsEntry>,
+  options: { quality: VideoQuality; baseline: StatsBaseline; keyPrefix: string },
+): VideoSendStats {
+  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);
+  }
+  const outbound = entries.filter((e) => e.type === 'outbound-rtp' && isVideo(e));
+
+  const layers = outbound.map((entry): VideoLayerStats & { entry: StatsEntry } => {
+    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<(typeof layers)[number] | undefined>((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: Iterable<StatsEntry>,
+  options: { producerId: string; baseline: StatsBaseline; key: string },
+): VideoReceiveStats | null {
+  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);
+  }
+  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 } : {}),
+  };
+}
+
+// ------------------------------------------------------------ videoLimited
+
+/** What is holding the camera video back: the device, the upload, something else, or nothing. */
+export type VideoLimitReason = 'cpu' | 'bandwidth' | 'other' | 'none';
+
+export interface VideoLimitedEvent {
+  reason: VideoLimitReason;
+  /** The biggest layer going out when this was decided. */
+  width: number;
+  height: number;
+  fps: number;
+  bitrate: number;
+}
+
+/**
+ * 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: readonly VideoLayerStats[]): VideoLimitReason {
+  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 interface LimitTracker {
+  /** The last reason reported; null before the first. */
+  reported: VideoLimitReason | null;
+  /** A different reason seen lately, and for how many samples in a row. */
+  pending: VideoLimitReason | null;
+  streak: number;
+}
+
+export const initialLimitTracker = (): LimitTracker => ({ 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: LimitTracker, reason: VideoLimitReason): { tracker: LimitTracker; report: VideoLimitReason | null } {
+  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 {
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private tracker = initialLimitTracker();
+  private sampling = false;
+  private readonly baseline: StatsBaseline = new Map();
+
+  constructor(
+    private readonly sample: (baseline: StatsBaseline) => Promise<VideoSendStats | null>,
+    private readonly report: (event: VideoLimitedEvent) => void,
+    private readonly intervalMs = LIMIT_SAMPLE_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);
+    } 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(): VideoLimitedEvent | null {
+    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;
+  }
+
+  private async tick(): Promise<void> {
+    // 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;
+    }
+  }
+}