feuerwerk/src/core/recording/recording.ts

/**
 * Recording the game view (#405): what `Start recording` asks for, and the rules a recording is made
 * by – its size, its name, which H.264 it is, when a frame is taken and where the picture lands.
 * The browser's side, encoders and canvas, is `viewport/GameRecorder.ts`.
 */

export type RecordingResolution = 'view' | '720p' | '1080p';

export interface RecordingSettings {
  /** Empty: named after the moment it starts (`recordingName`). */
  name: string;
  resolution: RecordingResolution;
  fps: 30 | 60;
}

export const RECORDING_RESOLUTIONS: readonly { value: RecordingResolution; label: string }[] = [
  { value: 'view', label: 'Game view' },
  { value: '720p', label: '720p' },
  { value: '1080p', label: '1080p' },
];

export const RECORDING_FPS = [
  { value: '60', label: '60' },
  { value: '30', label: '30' },
];

/** What a run hands its graphs to record with; each answer is a line for the log, '' for none. */
export interface RecordingSink {
  start(settings: RecordingSettings): string;
  stop(): string;
}

/** The upload takes 2 GB (`MAX_VIDEO_BYTES`); a recording stops a little before, its head still to come. */
export const RECORDING_MOST_BYTES = 2048 * 1024 * 1024 - 16 * 1024 * 1024;

/** What `Game view` records at most: a 4K picture, larger ones are scaled down to it. */
const MOST_WIDTH = 3840;
const MOST_HEIGHT = 2160;
/** Bits per pixel of a frame: 10 Mbit/s at 1080p60. Flat game graphics need less than film. */
const BITS_PER_PIXEL = 0.08;
const KEY_FRAME_SECONDS = 2;

export function recordingSettingsOf(
  name: string,
  resolution: string,
  fps: string | number,
): RecordingSettings {
  const known = RECORDING_RESOLUTIONS.find((r) => r.value === resolution);
  return { name: name.trim(), resolution: known?.value ?? 'view', fps: Number(fps) === 30 ? 30 : 60 };
}

/** The name a recording is saved under: the one asked for, else `Recording 2026-10-11 16:42:05`. */
export function recordingName(asked: string, at: Date): string {
  if (asked.trim()) return asked.trim();
  const two = (n: number) => String(n).padStart(2, '0');
  const day = `${at.getFullYear()}-${two(at.getMonth() + 1)}-${two(at.getDate())}`;
  return `Recording ${day} ${two(at.getHours())}:${two(at.getMinutes())}:${two(at.getSeconds())}`;
}

/**
 * The size of the frames, even on both sides as the encoders want it. `shown` is the camera's
 * picture as it lies on screen and `whole` all of it, both in device pixels: they differ only while
 * a fixed scale cuts the picture to the view. `Game view` records what is shown at its size; 720p
 * and 1080p hold the height and take the width from the camera.
 */
export function recordingSize(
  resolution: RecordingResolution,
  shown: { w: number; h: number },
  whole: { w: number; h: number },
): { w: number; h: number } {
  if (resolution === 'view') {
    const fit = Math.min(1, MOST_WIDTH / shown.w, MOST_HEIGHT / shown.h);
    return { w: even(shown.w * fit), h: even(shown.h * fit) };
  }
  const h = resolution === '720p' ? 720 : 1080;
  return { w: even((h * whole.w) / whole.h), h };
}

function even(value: number): number {
  return Math.max(2, Math.round(value / 2) * 2);
}

/**
 * The size of an editor recording of a canvas in device pixels: all of it, an odd row or column
 * cut off, since the encoders want both sides even.
 */
export function editorRecordingSize(canvas: { w: number; h: number }): { w: number; h: number } {
  const cut = (value: number) => Math.max(2, Math.floor(value / 2) * 2);
  return { w: cut(canvas.w), h: cut(canvas.h) };
}

/** How long a recording runs, as the editor shows it: `0:07`, `12:45`, `1:02:03`. */
export function elapsedText(ms: number): string {
  const seconds = Math.max(0, Math.floor(ms / 1000));
  const two = (n: number) => String(n).padStart(2, '0');
  const h = Math.floor(seconds / 3600);
  const m = Math.floor(seconds / 60) % 60;
  const s = seconds % 60;
  return h > 0 ? `${h}:${two(m)}:${two(s)}` : `${m}:${two(s)}`;
}

/**
 * Where the canvas lands in a frame of `frame` size. As it is at the start, it lands where it is,
 * cut by the odd pixel. A window resized during the recording is fitted in whole and centred, the
 * rest of the frame left dark.
 */
export function fitPicture(
  canvas: { w: number; h: number },
  frame: { w: number; h: number },
): { x: number; y: number; w: number; h: number } {
  const cutW = canvas.w - frame.w;
  const cutH = canvas.h - frame.h;
  if (cutW >= 0 && cutW <= 1 && cutH >= 0 && cutH <= 1) return { x: 0, y: 0, w: canvas.w, h: canvas.h };
  const scale = Math.min(frame.w / canvas.w, frame.h / canvas.h);
  const w = Math.round(canvas.w * scale);
  const h = Math.round(canvas.h * scale);
  return { x: Math.round((frame.w - w) / 2), y: Math.round((frame.h - h) / 2), w, h };
}

/** H.264 levels by the frame size and macroblocks a second they allow (ITU-T H.264, table A-1). */
const AVC_LEVELS: readonly { level: number; frame: number; rate: number }[] = [
  { level: 0x1f, frame: 3600, rate: 108_000 },
  { level: 0x20, frame: 5120, rate: 216_000 },
  { level: 0x28, frame: 8192, rate: 245_760 },
  { level: 0x2a, frame: 8704, rate: 522_240 },
  { level: 0x32, frame: 22_080, rate: 589_824 },
  { level: 0x33, frame: 36_864, rate: 983_040 },
  { level: 0x34, frame: 36_864, rate: 2_073_600 },
  { level: 0x3c, frame: 139_264, rate: 4_177_920 },
];

/** The codec string of H.264 High at the lowest level that takes these frames. */
export function avcCodec(w: number, h: number, fps: number): string {
  const frame = Math.ceil(w / 16) * Math.ceil(h / 16);
  const found = AVC_LEVELS.find((l) => frame <= l.frame && frame * fps <= l.rate) ?? AVC_LEVELS.at(-1)!;
  return `avc1.6400${found.level.toString(16).padStart(2, '0')}`;
}

/** VP9 profile 0 at 8 bits; level 4.1 takes 1080p60, 5.1 4K60. */
export function vp9Codec(w: number, h: number): string {
  return w * h <= 2_228_224 ? 'vp09.00.41.08' : 'vp09.00.51.08';
}

export function videoBitrate(w: number, h: number, fps: number): number {
  return Math.round(w * h * fps * BITS_PER_PIXEL);
}

/** Whether the `index`th frame taken (from 0) starts a group, so a player can seek to it. */
export function isKeyFrame(index: number, fps: number): boolean {
  return index % (fps * KEY_FRAME_SECONDS) === 0;
}

/**
 * The time of a recording in milliseconds, from its first frame: real time, minus what the editor
 * held it paused. A game that pauses itself is still seen, so that is not taken out.
 */
export class RecordingClock {
  private origin: number | null = null;
  private pausedAt: number | null = null;
  private paused = 0;

  get started(): boolean {
    return this.origin !== null;
  }

  /** A pause before the first frame is no part of the recording's time. */
  start(now: number): void {
    this.origin = now;
    this.paused = 0;
  }

  pause(now: number): void {
    this.pausedAt ??= now;
  }

  resume(now: number): void {
    if (this.pausedAt === null) return;
    this.paused += now - this.pausedAt;
    this.pausedAt = null;
  }

  at(now: number): number {
    if (this.origin === null) return 0;
    return Math.max(0, (this.pausedAt ?? now) - this.origin - this.paused);
  }
}

/**
 * Which drawn frames a recording takes: about `fps` a second whatever the screen draws. A frame a
 * little early still counts, so 60 at 60 Hz takes every one however unevenly they come.
 */
export class FrameGate {
  private next = 0;

  constructor(private readonly fps: number) {}

  take(ms: number): boolean {
    const period = 1000 / this.fps;
    if (ms < this.next - period / 4) return false;
    this.next = Math.max(this.next + period, ms + period / 2);
    return true;
  }
}

/**
 * Where the view's local CSS pixels land when `area` of it (a centre and a size) fills a frame of
 * `size` pixels: the recording draws into a texture of that size, whatever the window's.
 */
export function pictureTransform(
  area: { x: number; y: number; w: number; h: number },
  size: { w: number; h: number },
): { a: number; d: number; tx: number; ty: number } {
  const sx = size.w / area.w;
  const sy = size.h / area.h;
  return { a: sx, d: sy, tx: size.w / 2 - area.x * sx, ty: size.h / 2 - area.y * sy };
}