@voltkit-rtc/client 0.5.0 → 0.6.0

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);
+  }
+}