@voltkit-rtc/client 0.4.0 → 0.6.0

package/src/quality.ts

@@ -1,12 +1,4 @@
-/**
- * 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 for the first project during its 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';
 
@@ -17,13 +9,14 @@ 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 }> = {
@@ -36,27 +29,18 @@ 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 4 Mbps, 720p 2.5 Mbps, 540p 1.5 Mbps, 480p 1 Mbps,
- * 360p 700 kbps, 240p 400 kbps, smaller 200 kbps.
- *
- * Measured on a 720p camera picture: 2.5 Mbps brought VP8's quantiser down
- * from about 64 (at 1.8 Mbps) to about 55, which is finer detail, most of all
- * in motion. The server's per-project caps (4 Mbps up to 720p, 7 Mbps with
- * 1080p) carry these ladders with their audio.
- */
+/** The authoritative 30 fps bitrate for a layer of this many pixels. */
 export function layerBitrate(pixels: number): number {
-  if (pixels >= 1_800_000) return 4_000_000;
-  if (pixels >= 800_000) return 2_500_000;
-  if (pixels >= 450_000) return 1_500_000;
-  if (pixels >= 360_000) return 1_000_000;
-  if (pixels >= 200_000) return 700_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;
 }
@@ -66,6 +50,7 @@ export interface VideoEncoding {
   scaleResolutionDownBy: number;
   maxBitrate: number;
   scalabilityMode: 'L1T3';
+  maxFramerate: number;
 }
 
 /**
@@ -98,7 +83,7 @@ export function topLayerSize(width: number, height: number, quality: VideoQualit
  * 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, maxLayers: LayerCount = 3): VideoEncoding[] {
+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;
@@ -108,7 +93,8 @@ export function videoEncodings(width: number, height: number, quality: VideoQual
   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')];
@@ -124,3 +110,46 @@ export function videoEncodings(width: number, height: number, quality: VideoQual
 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/recording.ts

@@ -0,0 +1,571 @@
+/** Paid device-to-R2 recording. No storage secrets or media pass through the API. */
+export type RecordingState =
+  | "starting"
+  | "recording"
+  | "backpressure"
+  | "uploading"
+  | "ready"
+  | "stopped"
+  | "error";
+export interface RecordingEvent {
+  state: RecordingState;
+  bufferedBytes: number;
+  uploadedBytes: number;
+  recordingId?: string;
+  error?: Error;
+}
+export interface RecordingFile {
+  playbackUrl?: string;
+  retainUntil?: string;
+  durationSeconds?: number;
+  id: string;
+  state: string;
+  profileId: string;
+  width: number;
+  height: number;
+  frameRate: number;
+  videoBitrate: number;
+  audioBitrate: number;
+}
+export interface RecordingSession {
+  recording: RecordingFile;
+  token: string;
+  chunkBytes: number;
+  uploadConcurrency: number;
+  maxBufferBytes: number;
+  segmentSeconds: number;
+  expiresAt: string;
+}
+export interface RecordingOptions {
+  apiUrl: string;
+  chunkMiB?: 5 | 10;
+  onState?: (event: RecordingEvent) => void;
+  onRecordingReady?: (file: RecordingFile) => void;
+}
+export class RecordingError extends Error {
+  constructor(
+    message: string,
+    readonly status = 0,
+  ) {
+    super(message);
+    this.name = "RecordingError";
+  }
+}
+const delay = (ms: number) =>
+  new Promise<void>((resolve) => setTimeout(resolve, ms));
+export async function recordingRequest<T>(
+  base: string,
+  path: string,
+  body: unknown,
+  token?: string,
+): Promise<T> {
+  const response = await fetch(
+    `${base.replace(/\/$/, "")}/recording/upload${path}`,
+    {
+      method: "POST",
+      credentials: "omit",
+      headers: {
+        "Content-Type": "application/json",
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(path.endsWith("/complete") ? 180000 : 15000),
+    },
+  );
+  const result = (await response.json()) as {
+    success: boolean;
+    data?: T;
+    error?: { message: string };
+  };
+  if (!response.ok || !result.success || !result.data)
+    throw new RecordingError(
+      result.error?.message ?? "Recording request failed",
+      response.status,
+    );
+  return result.data;
+}
+/** Bounded uploader, also usable with an externally encoded native/file source. */
+export class RecordingUploader {
+  private queue: Blob[] = [];
+  private pendingBytes = 0;
+  private bytes = 0;
+  private uploaded = 0;
+  private number = 0;
+  private readonly active = new Set<Promise<void>>();
+  private reserve: Promise<unknown> = Promise.resolve();
+  private failure: Error | null = null;
+  private finishing = false;
+  private sealed = false;
+  private canceled = false;
+  private readonly aborter = new AbortController();
+  private constructor(
+    readonly session: RecordingSession,
+    private readonly options: RecordingOptions,
+  ) {}
+  static async create(
+    options: RecordingOptions,
+    roomToken: string,
+    mimeType: string,
+  ): Promise<RecordingUploader> {
+    const url = new URL(options.apiUrl);
+    if (
+      url.protocol !== "https:" &&
+      !["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+    )
+      throw new RecordingError("Recording API must use HTTPS");
+    const requestId = crypto.randomUUID();
+    let session: RecordingSession | undefined;
+    for (let attempt = 0; attempt < 3; attempt++) {
+      try {
+        session = await recordingRequest<RecordingSession>(
+          options.apiUrl,
+          "/sessions",
+          {
+            roomToken,
+            requestId,
+            mimeType,
+            ...(options.chunkMiB ? { chunkMiB: options.chunkMiB } : {}),
+          },
+        );
+        break;
+      } catch (error) {
+        if (
+          attempt === 2 ||
+          (error instanceof RecordingError &&
+            ![409, 429, 503].includes(error.status))
+        )
+          throw error;
+        await delay(500 * (attempt + 1));
+      }
+    }
+    if (
+      !session ||
+      ![5 * 1048576, 10 * 1048576].includes(session.chunkBytes) ||
+      session.maxBufferBytes < session.chunkBytes * 2 ||
+      session.maxBufferBytes > 100 * 1048576 ||
+      session.uploadConcurrency < 1 ||
+      session.uploadConcurrency > 4
+    )
+      throw new RecordingError("Invalid recording upload policy");
+    return new RecordingUploader(session, options);
+  }
+  get bufferedBytes(): number {
+    return this.bytes;
+  }
+  get uploadedBytes(): number {
+    return this.uploaded;
+  }
+  get hasCapacity(): boolean {
+    return (
+      !this.failure &&
+      !this.canceled &&
+      this.bytes < this.session.maxBufferBytes - this.session.chunkBytes
+    );
+  }
+  private emit(state: RecordingState, error?: Error): void {
+    try {
+      this.options.onState?.({
+        state,
+        bufferedBytes: this.bytes,
+        uploadedBytes: this.uploaded,
+        recordingId: this.session.recording.id,
+        ...(error ? { error } : {}),
+      });
+    } catch {
+      /* UI callbacks never break accounting/cleanup. */
+    }
+  }
+  append(blob: Blob): void {
+    if (this.finishing || this.canceled)
+      throw new RecordingError("Recording upload has ended");
+    if (this.failure) throw this.failure;
+    if (!blob.size) return;
+    if (blob.size > this.session.maxBufferBytes - this.bytes)
+      throw new RecordingError(
+        "Recording buffer limit reached; stop recording without stopping the live stream",
+      );
+    this.queue.push(blob);
+    this.pendingBytes += blob.size;
+    this.bytes += blob.size;
+    this.pump();
+    this.emit(this.hasCapacity ? "recording" : "backpressure");
+  }
+  private take(size: number): Blob {
+    const blobs: Blob[] = [];
+    let remaining = size;
+    while (remaining > 0) {
+      const blob = this.queue.shift()!;
+      const length = Math.min(remaining, blob.size);
+      blobs.push(blob.slice(0, length));
+      if (length < blob.size) this.queue.unshift(blob.slice(length));
+      remaining -= length;
+    }
+    this.pendingBytes -= size;
+    return new Blob(blobs);
+  }
+  private pump(): void {
+    while (
+      !this.failure &&
+      !this.canceled &&
+      this.active.size < this.session.uploadConcurrency &&
+      this.pendingBytes >= this.session.chunkBytes
+    )
+      this.upload(this.take(this.session.chunkBytes), false);
+  }
+  private upload(blob: Blob, final: boolean): void {
+    const number = ++this.number;
+    // Reserve in sequence, while PUT bodies upload concurrently.
+    const signed = this.reserve.then(() =>
+      recordingRequest<{ url: string }>(
+        this.options.apiUrl,
+        `/sessions/${this.session.recording.id}/parts`,
+        { number, bytes: blob.size, final },
+        this.session.token,
+      ),
+    );
+    this.reserve = signed;
+    let task: Promise<void>;
+    task = (async () => {
+      let url = (await signed).url;
+      for (let attempt = 0; attempt < 4; attempt++) {
+        if (this.canceled) throw new RecordingError("Recording canceled");
+        try {
+          const response = await fetch(url, {
+            method: "PUT",
+            body: blob,
+            credentials: "omit",
+            signal: AbortSignal.any([
+              this.aborter.signal,
+              AbortSignal.timeout(45000),
+            ]),
+          });
+          if (!response.ok)
+            throw new RecordingError("R2 upload failed", response.status);
+          this.bytes -= blob.size;
+          this.uploaded += blob.size;
+          return;
+        } catch (error) {
+          if (this.canceled || attempt === 3) throw error;
+          await delay(500 * 2 ** attempt);
+          url = (
+            await recordingRequest<{ url: string }>(
+              this.options.apiUrl,
+              `/sessions/${this.session.recording.id}/parts`,
+              { number, bytes: blob.size, final },
+              this.session.token,
+            )
+          ).url;
+        }
+      }
+    })()
+      .catch((error) => {
+        this.failure =
+          error instanceof Error
+            ? error
+            : new RecordingError("Recording upload failed");
+        this.emit("error", this.failure);
+      })
+      .finally(() => {
+        this.active.delete(task);
+        this.pump();
+        this.emit(
+          this.failure
+            ? "error"
+            : this.hasCapacity
+              ? "recording"
+              : "backpressure",
+        );
+      });
+    this.active.add(task);
+  }
+  async waitForCapacity(): Promise<void> {
+    while (!this.hasCapacity) {
+      if (this.failure) throw this.failure;
+      if (this.canceled) throw new RecordingError("Recording canceled");
+      await Promise.race(this.active);
+    }
+  }
+  async seal(): Promise<void> {
+    if (this.sealed) return;
+    this.finishing = true;
+    this.emit("uploading");
+    while (this.active.size) {
+      await Promise.all(this.active);
+      if (this.failure) throw this.failure;
+    }
+    if (this.pendingBytes) {
+      this.upload(this.take(this.pendingBytes), true);
+      await Promise.all(this.active);
+    }
+    if (this.failure) throw this.failure;
+    if (!this.number) {
+      await this.abort();
+      throw new RecordingError("No video was recorded");
+    }
+    this.sealed = true;
+  }
+  async complete(): Promise<RecordingFile> {
+    await this.seal();
+    const file = await recordingRequest<RecordingFile>(
+      this.options.apiUrl,
+      `/sessions/${this.session.recording.id}/complete`,
+      {},
+      this.session.token,
+    );
+    this.emit("ready");
+    return file;
+  }
+  async abort(): Promise<void> {
+    this.canceled = true;
+    this.aborter.abort();
+    await Promise.all(this.active);
+    this.queue = [];
+    this.bytes = 0;
+    this.pendingBytes = 0;
+    await recordingRequest(
+      this.options.apiUrl,
+      `/sessions/${this.session.recording.id}/abort`,
+      {},
+      this.session.token,
+    );
+    this.emit("stopped");
+  }
+}
+
+/** Encodes a downscaled COPY of local camera/mic. Never changes RTC tracks. */
+export class CameraRecording {
+  private stopped = false;
+  private stopSegment: (() => void) | null = null;
+  private done: Promise<RecordingFile[]> | null = null;
+  private readonly files = new Map<number, RecordingFile>();
+  private readonly finalizers = new Set<Promise<void>>();
+  private finalFailure: Error | null = null;
+  private segmentNumber = 0;
+  constructor(
+    private readonly getStream: () => MediaStream | null,
+    private readonly getRoomToken: () => string,
+    private readonly options: RecordingOptions,
+  ) {}
+  start(): Promise<void> {
+    const stream = this.getStream();
+    if (
+      !stream
+        ?.getVideoTracks()
+        .some((track) => track.readyState === "live" && track.enabled)
+    )
+      throw new RecordingError("Publish an enabled camera before recording");
+    if (this.done) throw new RecordingError("Recording is already started");
+    let ready!: () => void, reject!: (e: unknown) => void;
+    const started = new Promise<void>((yes, no) => {
+      ready = yes;
+      reject = no;
+    });
+    this.done = this.run(ready)
+      .then((files) => {
+        ready();
+        return files;
+      })
+      .catch((error) => {
+        reject(error);
+        this.stopped = true;
+        try {
+          this.options.onState?.({
+            state: "error",
+            bufferedBytes: 0,
+            uploadedBytes: 0,
+            error:
+              error instanceof Error
+                ? error
+                : new RecordingError("Recording failed"),
+          });
+        } catch {}
+        throw error;
+      });
+    void this.done.catch(() => undefined);
+    return started;
+  }
+  async stop(): Promise<RecordingFile[]> {
+    this.stopped = true;
+    this.stopSegment?.();
+    return this.done ?? [];
+  }
+  private async run(ready: () => void): Promise<RecordingFile[]> {
+    while (!this.stopped) {
+      const stream = this.getStream(),
+        camera = stream?.getVideoTracks()[0];
+      if (!stream || !camera || camera.readyState !== "live" || !camera.enabled)
+        break;
+      const mimeType = ["video/webm;codecs=vp8,opus", "video/mp4"].find(
+        (type) => MediaRecorder.isTypeSupported(type),
+      );
+      if (!mimeType)
+        throw new RecordingError(
+          "This browser cannot encode supported recording video",
+        );
+      const uploader = await RecordingUploader.create(
+        this.options,
+        this.getRoomToken(),
+        mimeType,
+      );
+      let video: HTMLVideoElement | null = null,
+        encoded: MediaStream | null = null,
+        timer: ReturnType<typeof setInterval> | undefined,
+        segmentTimer: ReturnType<typeof setTimeout> | undefined;
+      try {
+        if (this.stopped) {
+          await uploader.abort();
+          break;
+        }
+        const policy = uploader.session.recording;
+        video = document.createElement("video");
+        video.srcObject = stream;
+        video.muted = true;
+        video.playsInline = true;
+        await video.play();
+        if (this.stopped) {
+          await uploader.abort();
+          break;
+        }
+        const portrait =
+          (video.videoHeight || camera.getSettings().height || policy.height) >
+          (video.videoWidth || camera.getSettings().width || policy.width);
+        const canvas = document.createElement("canvas");
+        canvas.width = portrait ? policy.height : policy.width;
+        canvas.height = portrait ? policy.width : policy.height;
+        const context = canvas.getContext("2d");
+        if (!context) throw new RecordingError("Recording canvas unavailable");
+        encoded = canvas.captureStream(policy.frameRate);
+        for (const track of stream.getAudioTracks())
+          encoded.addTrack(track.clone());
+        const recorder = new MediaRecorder(encoded, {
+          mimeType,
+          videoBitsPerSecond: policy.videoBitrate,
+          audioBitsPerSecond: policy.audioBitrate,
+        });
+        let failure: Error | null = null;
+        const finished = new Promise<void>((resolve, reject) => {
+          recorder.onstop = () => (failure ? reject(failure) : resolve());
+          recorder.onerror = () => {
+            failure = new RecordingError("Recording encoder failed");
+            if (recorder.state !== "inactive") recorder.stop();
+            else reject(failure);
+          };
+        });
+        const stop = () => {
+          if (recorder.state !== "inactive") recorder.stop();
+        };
+        this.stopSegment = stop;
+        recorder.ondataavailable = (event) => {
+          try {
+            uploader.append(event.data);
+            if (!uploader.hasCapacity && recorder.state === "recording") {
+              recorder.pause();
+              void uploader
+                .waitForCapacity()
+                .then(() => {
+                  if (!this.stopped && recorder.state === "paused")
+                    recorder.resume();
+                })
+                .catch((error) => {
+                  failure = error;
+                  stop();
+                });
+            }
+          } catch (error) {
+            failure =
+              error instanceof Error
+                ? error
+                : new RecordingError("Recording buffer failed");
+            stop();
+          }
+        };
+        const draw = () => {
+          const current = this.getStream();
+          const track = current?.getVideoTracks()[0];
+          if (!track || track.readyState !== "live" || !track.enabled) {
+            this.stopped = true;
+            stop();
+            return;
+          }
+          // A camera flip gets a separate file; WebRTC is untouched.
+          if (current !== stream) {
+            stop();
+            return;
+          }
+          encoded!.getAudioTracks().forEach((audio, index) => {
+            audio.enabled = stream.getAudioTracks()[index]?.enabled ?? false;
+          });
+          context.fillStyle = "#000";
+          context.fillRect(0, 0, canvas.width, canvas.height);
+          if (video!.readyState >= 2) {
+            const scale = Math.min(
+                canvas.width / video!.videoWidth,
+                canvas.height / video!.videoHeight,
+              ),
+              w = video!.videoWidth * scale,
+              h = video!.videoHeight * scale;
+            context.drawImage(
+              video!,
+              (canvas.width - w) / 2,
+              (canvas.height - h) / 2,
+              w,
+              h,
+            );
+          }
+        };
+        recorder.start(1000);
+        draw();
+        ready();
+        timer = setInterval(draw, 1000 / policy.frameRate);
+        segmentTimer = setTimeout(stop, uploader.session.segmentSeconds * 1000);
+        await finished;
+        if (timer) clearInterval(timer);
+        if (segmentTimer) clearTimeout(segmentTimer);
+        encoded.getTracks().forEach((track) => track.stop());
+        video.pause();
+        video.srcObject = null;
+        await uploader.seal();
+        const index = this.segmentNumber++;
+        let finalize: Promise<void>;
+        finalize = uploader
+          .complete()
+          .then((file) => {
+            this.files.set(index, file);
+            try {
+              this.options.onRecordingReady?.(file);
+            } catch {}
+          })
+          .catch((error) => {
+            this.finalFailure =
+              error instanceof Error
+                ? error
+                : new RecordingError("Recording validation failed");
+            this.stopped = true;
+            this.stopSegment?.();
+          })
+          .finally(() => this.finalizers.delete(finalize));
+        this.finalizers.add(finalize);
+        // Uploaded files hold no pending media buffers; validate in the
+        // background while the next segment records. Bound pending jobs too.
+        if (this.finalizers.size >= 2) await Promise.race(this.finalizers);
+      } catch (error) {
+        await uploader.abort().catch(() => undefined);
+        throw error;
+      } finally {
+        if (timer) clearInterval(timer);
+        if (segmentTimer) clearTimeout(segmentTimer);
+        this.stopSegment = null;
+        encoded?.getTracks().forEach((track) => track.stop());
+        if (video) {
+          video.pause();
+          video.srcObject = null;
+        }
+      }
+    }
+    await Promise.all(this.finalizers);
+    if (this.finalFailure) throw this.finalFailure;
+    return [...this.files.entries()]
+      .sort((a, b) => a[0] - b[0])
+      .map(([, file]) => file);
+  }
+}