nixamp 0.1.0 → 0.3.0

package/src/accounts.ts

@@ -0,0 +1,193 @@
+/**
+ * Accounts on nixamp.com.
+ *
+ * The house auth module does the work: password and JWT, over the Postgres
+ * adapter. This is the shape nixamp needs around it, and the two things the
+ * module gets wrong from a caller's point of view:
+ *
+ * - `login()` and `register()` THROW on a bad password or a taken address
+ *   rather than resolving `{ success: false }`, so a bare `if (!result.success)`
+ *   never runs. Everything here answers a result instead.
+ * - `validateToken()` resolves to the claims directly, not to a wrapper like
+ *   the other two, so the shapes differ between calls.
+ * - `register()` without `autoVerify` creates an account that `login()` will
+ *   refuse for ever, and returns no tokens. nixamp sends no email, so there
+ *   would be nothing to click.
+ *
+ * No magic link: a link in an inbox is no use on a television or a phone that
+ * is not the one you read mail on.
+ */
+import { createAuthSystem, PostgresAdapter } from "@profullstack/auth-system";
+
+export interface Account {
+  id: string;
+  email: string;
+}
+
+export interface AuthResult {
+  ok: boolean;
+  account: Account | null;
+  token: string;
+  /** Safe to show a stranger: it never says whether an address is registered. */
+  error: string;
+}
+
+const NO_ACCOUNT: AuthResult = { ok: false, account: null, token: "", error: "" };
+
+/**
+ * The same sentence for a wrong password and an address with no account.
+ * Saying which is how an endpoint tells a stranger who has registered.
+ */
+const REFUSED = "that email and password do not match an account";
+
+export interface AccountsOptions {
+  /** postgres://user:pass@host/db */
+  connectionString: string;
+  /** Signing secret. Without one, every session dies on restart. */
+  secret: string;
+  /** Injected by the tests, which have no database. */
+  system?: AuthLike;
+}
+
+/** The slice of the auth system nixamp uses. */
+export interface AuthLike {
+  register(input: { email: string; password: string; autoVerify?: boolean }): Promise<unknown>;
+  login(input: { email: string; password: string }): Promise<unknown>;
+  validateToken(token: string): Promise<unknown>;
+}
+
+/** Pull an account and a token out of whatever shape the module returned. */
+export function readResult(value: unknown): AuthResult {
+  const record = (value ?? {}) as Record<string, unknown>;
+  const user = (record["user"] ?? {}) as Record<string, unknown>;
+  const tokens = (record["tokens"] ?? {}) as Record<string, unknown>;
+  const id = typeof user["id"] === "string" ? user["id"] : "";
+  const email = typeof user["email"] === "string" ? user["email"] : "";
+  const token = typeof tokens["accessToken"] === "string" ? tokens["accessToken"] : "";
+  if (!id || !token) return { ...NO_ACCOUNT, error: REFUSED };
+  return { ok: true, account: { id, email }, token, error: "" };
+}
+
+/** `validateToken` answers claims directly, unlike login and register. */
+export function readClaims(value: unknown): Account | null {
+  const claims = (value ?? {}) as Record<string, unknown>;
+  const id = typeof claims["userId"] === "string" ? claims["userId"] : "";
+  const email = typeof claims["email"] === "string" ? claims["email"] : "";
+  return id ? { id, email } : null;
+}
+
+/** An address that could exist, and a password long enough to be worth having. */
+export function checkCredentials(email: unknown, password: unknown): string {
+  if (typeof email !== "string" || !/^[^@\s]+@[^@\s.]+\.[^@\s]+$/.test(email)) {
+    return "that does not look like an email address";
+  }
+  if (typeof password !== "string" || password.length < 10) {
+    // Length is checked here so a hopeless password never reaches the
+    // database. The auth module then applies its own composition rules on top,
+    // and its refusals are passed through rather than swallowed.
+    return "a password needs at least 10 characters";
+  }
+  if (password.length > 200) return "that password is too long";
+  return "";
+}
+
+export class Accounts {
+  private readonly system: AuthLike;
+
+  constructor(options: AccountsOptions) {
+    this.system =
+      options.system ??
+      (createAuthSystem({
+        adapter: new PostgresAdapter({ connectionString: options.connectionString }),
+        jwtSecret: options.secret,
+      }) as AuthLike);
+  }
+
+  async signUp(email: unknown, password: unknown): Promise<AuthResult> {
+    const wrong = checkCredentials(email, password);
+    if (wrong) return { ...NO_ACCOUNT, error: wrong };
+    try {
+      // autoVerify does two things, and both are necessary here: without it
+      // the account is created unverified and login() refuses it forever --
+      // nixamp sends no email, so there is nothing to click -- and register()
+      // returns no tokens, so signing up would not sign you in.
+      return readResult(
+        await this.system.register({
+          email: email as string,
+          password: password as string,
+          autoVerify: true,
+        }),
+      );
+    } catch (error) {
+      const message = (error as Error).message ?? "";
+      // "already exists" is the one case worth naming: a sign-up form that
+      // will not say why is a sign-up form people give up on. It reveals
+      // nothing that trying to sign up does not reveal anyway.
+      if (/exist|taken|duplicate/i.test(message)) {
+        return { ...NO_ACCOUNT, error: "there is already an account with that email" };
+      }
+      // The module has its own password rules -- an uppercase letter, and so
+      // on -- and refuses with a sentence saying which. Hiding that behind
+      // "could not create that account" leaves someone retyping a password
+      // that will never be accepted.
+      const complaint = /^Invalid (?:password|email)[:\s]+(.*)$/i.exec(message);
+      if (complaint?.[1]) return { ...NO_ACCOUNT, error: complaint[1].trim().toLowerCase() };
+      return { ...NO_ACCOUNT, error: "could not create that account" };
+    }
+  }
+
+  async signIn(email: unknown, password: unknown): Promise<AuthResult> {
+    if (checkCredentials(email, password)) return { ...NO_ACCOUNT, error: REFUSED };
+    try {
+      return readResult(await this.system.login({ email: email as string, password: password as string }));
+    } catch {
+      // login() throws on bad credentials, so this is the ordinary path.
+      return { ...NO_ACCOUNT, error: REFUSED };
+    }
+  }
+
+  async whoIs(token: string): Promise<Account | null> {
+    if (!token) return null;
+    try {
+      return readClaims(await this.system.validateToken(token));
+    } catch {
+      return null;
+    }
+  }
+}
+
+/** The bearer token on a request, from the header or the session cookie. */
+export function tokenFrom(headers: Record<string, string | string[] | undefined>): string {
+  const authorization = headers["authorization"];
+  const header = Array.isArray(authorization) ? authorization[0] : authorization;
+  const bearer = /^Bearer\s+(.+)$/i.exec(header ?? "")?.[1];
+  if (bearer) return bearer.trim();
+
+  const cookie = Array.isArray(headers["cookie"]) ? headers["cookie"][0] : headers["cookie"];
+  for (const part of (cookie ?? "").split(";")) {
+    const [name, ...rest] = part.trim().split("=");
+    if (name === "nixamp_session" && rest.length > 0) return decodeURIComponent(rest.join("="));
+  }
+  return "";
+}
+
+/**
+ * The session cookie. HttpOnly because nothing in the page reads it -- the
+ * browser attaches it by itself -- and Secure only where the page was served
+ * over https, since a nixamp on your own network is plain http.
+ */
+export function sessionCookie(token: string, secure: boolean): string {
+  const parts = [
+    `nixamp_session=${encodeURIComponent(token)}`,
+    "Path=/",
+    "Max-Age=2592000",
+    "SameSite=Lax",
+    "HttpOnly",
+  ];
+  if (secure) parts.push("Secure");
+  return parts.join("; ");
+}
+
+export function clearedCookie(): string {
+  return "nixamp_session=; Path=/; Max-Age=0; SameSite=Lax; HttpOnly";
+}

package/src/admin.ts

@@ -0,0 +1,243 @@
+/**
+ * `nixamp admin` — what the daemon is doing, and who is listening to it.
+ *
+ * It talks to a running server over the same HTTP API a browser uses, so it
+ * works against the local daemon, against `nixamp serve` in another terminal,
+ * or against a nixamp on a different machine entirely.
+ */
+import { createApp, themes, type Container, type KeyEvent, type Theme } from "@profullstack/hqtui";
+import type { Color } from "@profullstack/hqtui";
+import type { Connection } from "./connections.ts";
+import { daemonUrl, readState } from "./daemon.ts";
+import { KEY_HEADER } from "./share.ts";
+
+interface Report {
+  connections: Connection[];
+  active: number;
+  startedAt: number;
+  now: number;
+}
+
+interface Snapshot {
+  tracks: { title: string; artist: string; duration: number }[];
+  index: number;
+  playing: boolean;
+  position: number;
+  root: string;
+  note: string;
+}
+
+export interface AdminOptions {
+  url: string;
+  key: string | null;
+}
+
+/** Where to point, from the flags or from the daemon that is running. */
+export function resolveTarget(argv: string[]): AdminOptions {
+  const at = argv.findIndex((a) => a === "--url" || a === "-u");
+  const keyAt = argv.findIndex((a) => a === "--key");
+  const url = at === -1 ? null : argv[at + 1];
+  const key = keyAt === -1 ? null : (argv[keyAt + 1] ?? null);
+
+  if (url) return { url: url.replace(/\/+$/, ""), key };
+
+  const state = readState();
+  if (state === null) {
+    throw new Error("nixamp: no daemon is running. Start one with `nixamp daemon start`, or pass --url.");
+  }
+  return { url: daemonUrl(state), key: key ?? state.key };
+}
+
+/** Seconds as something a person reads at a glance. */
+export function since(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m ${seconds % 60}s`;
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return `${hours}h ${minutes % 60}m`;
+  return `${Math.floor(hours / 24)}d ${hours % 24}h`;
+}
+
+export function bytes(value: number): string {
+  const units = ["B", "KiB", "MiB", "GiB"];
+  let n = value;
+  for (const unit of units) {
+    if (n < 1024 || unit === "GiB") return `${n < 10 && unit !== "B" ? n.toFixed(1) : Math.round(n)} ${unit}`;
+    n /= 1024;
+  }
+  return `${value} B`;
+}
+
+/** The colour a network deserves: the internet is the one worth noticing. */
+function networkColor(theme: Theme, network: Connection["network"]): number {
+  return network === "public"
+    ? theme.warning
+    : network === "cgnat"
+      ? theme.secondary
+      : network === "local"
+        ? theme.muted
+        : theme.success;
+}
+
+export async function admin(argv: string[]): Promise<void> {
+  const target = resolveTarget(argv);
+  const headers: Record<string, string> = target.key ? { [KEY_HEADER]: target.key } : {};
+
+  const ask = async <T,>(path: string): Promise<T | null> => {
+    try {
+      const response = await fetch(`${target.url}${path}`, { headers });
+      return response.ok ? ((await response.json()) as T) : null;
+    } catch {
+      return null;
+    }
+  };
+
+  let report: Report | null = null;
+  let snapshot: Snapshot | null = null;
+  let error = "";
+  let restreaming = "";
+  let typing = false;
+
+  const app = await createApp({ theme: themes.matrix, title: "nixamp admin", quitKeys: ["ctrl+c"] });
+
+  const refresh = async (): Promise<void> => {
+    const [next, state] = await Promise.all([ask<Report>("/api/connections"), ask<Snapshot>("/api/state")]);
+    error = next === null ? `cannot reach ${target.url}` : "";
+    if (next) report = next;
+    if (state) snapshot = state;
+    app.invalidate();
+  };
+
+  const timer = setInterval(() => void refresh(), 1000);
+  await refresh();
+
+  app.on("key", (event: KeyEvent) => {
+    const key = event.key;
+    if (typing) {
+      if (key === "escape") { typing = false; restreaming = ""; }
+      else if (key === "enter") {
+        const url = restreaming.trim();
+        typing = false;
+        restreaming = "";
+        if (url) void restream(target, headers, url).then(() => refresh());
+      } else if (key === "backspace") restreaming = restreaming.slice(0, -1);
+      // A printable key is a character; everything else is a name like "f1".
+      else if (key.length === 1) restreaming += key;
+      app.invalidate();
+      return;
+    }
+    if (key === "q") { app.quit(); return; }
+    if (key === "r") { typing = true; app.invalidate(); }
+  });
+
+  app.on("exit", () => clearInterval(timer));
+  app.render(({ ui, theme }) => draw(ui, theme, {
+    url: target.url, report, snapshot, error, typing, restreaming,
+  }));
+
+  await app.start();
+  clearInterval(timer);
+}
+
+/** Ask the server to play something else, which is what re-streaming is. */
+async function restream(target: AdminOptions, headers: Record<string, string>, url: string): Promise<void> {
+  try {
+    await fetch(`${target.url}/api/source`, {
+      method: "POST",
+      headers: { ...headers, "content-type": "application/json" },
+      body: JSON.stringify({ source: url }),
+    });
+  } catch {
+    // The next refresh reports the server being unreachable; this is not the
+    // place to make that noise.
+  }
+}
+
+export interface View {
+  url: string;
+  report: Report | null;
+  snapshot: Snapshot | null;
+  error: string;
+  typing: boolean;
+  restreaming: string;
+}
+
+export function draw(ui: Container, theme: Theme, view: View): void {
+  const { report, snapshot } = view;
+  const now = report?.now ?? Date.now();
+
+  ui.row({ size: 7, gap: 1 }, (row) => {
+    row.panel({ title: "Server" }, (p) => {
+      p.text(view.url, { fg: theme.primary });
+      p.label(snapshot?.root ?? "—");
+      p.keyValues([
+        { label: "Uptime", value: report ? since(now - report.startedAt) : "—", color: theme.accent },
+        { label: "Tracks", value: String(snapshot?.tracks.length ?? 0), color: theme.foreground },
+        { label: "Listeners", value: String(report?.active ?? 0), color: theme.success },
+      ]);
+    });
+
+    row.panel({ title: "Now playing" }, (p) => {
+      const track = snapshot ? snapshot.tracks[snapshot.index] : undefined;
+      p.text(track?.title ?? "nothing", { fg: theme.accent });
+      p.label(track?.artist || "—");
+      p.keyValues([
+        { label: "State", value: snapshot?.playing ? "playing" : "stopped", color: snapshot?.playing ? theme.success : theme.muted },
+        { label: "Position", value: snapshot ? since(snapshot.position * 1000) : "—", color: theme.foreground },
+      ]);
+    });
+  });
+
+  ui.panel({ title: `Connections (${report?.active ?? 0} live)` }, (p) => {
+    if (view.error) {
+      p.text(view.error, { fg: theme.danger });
+      return;
+    }
+    const rows = report?.connections ?? [];
+    if (rows.length === 0) {
+      p.label("Nobody is listening yet.");
+      return;
+    }
+
+    // A finished connection is drawn in muted colours rather than dropped: the
+    // most useful thing an admin view can say is "it stopped ten seconds ago".
+    const dim = (row: Connection, live: Color): Color => (row.endedAt === null ? live : theme.muted);
+
+    p.table<Connection>({
+      rows,
+      header: true,
+      headerColor: theme.muted,
+      zebra: false,
+      columns: [
+        { key: "address", title: "Where", min: 12, color: (row) => dim(row, theme.foreground) },
+        { key: "network", title: "Network", width: 9, color: (row) => dim(row, networkColor(theme, row.network)) },
+        { key: "kind", title: "Kind", width: 7, color: theme.muted },
+        { key: "agent", title: "Client", width: 12, color: theme.muted },
+        { key: "track", title: "Track", min: 16, color: (row) => dim(row, theme.primary),
+          render: (row) => row.track || "—" },
+        { key: "for", title: "For", width: 10, align: "right", color: theme.muted,
+          render: (row) => (row.endedAt === null
+            ? since(now - row.startedAt)
+            : `${since(row.endedAt - row.startedAt)} ago`) },
+        { key: "bytes", title: "Sent", width: 9, align: "right",
+          color: (row) => dim(row, theme.success), render: (row) => bytes(row.bytes) },
+      ],
+    });
+  });
+
+  if (view.typing) {
+    ui.panel({ title: "Re-stream a URL or a path", size: 4 }, (p) => {
+      p.text(`${view.restreaming}_`, { fg: theme.accent });
+      p.label("Enter plays it here. Escape forgets it.");
+    });
+  }
+
+  ui.statusBar({
+    items: [
+      { key: "r", label: "Re-stream" },
+      { key: "q", label: "Quit" },
+    ],
+    right: [{ key: "", label: report ? `${report.connections.length} seen` : "connecting" }],
+  });
+}

package/src/broadcast.ts

@@ -0,0 +1,264 @@
+/**
+ * Broadcasting out to RTMP, to as many places at once as you like.
+ *
+ * One ffmpeg, one encode, many outputs, through the `tee` muxer. Running an
+ * ffmpeg per destination is the obvious shape and it encodes the same frames
+ * four times; tee encodes once and writes the result to every URL.
+ *
+ * The encoder settings are PairUX's, which learned them the hard way against
+ * the real platforms: a one-second keyframe interval because YouTube stalls on
+ * ffmpeg's default, a forced constant frame rate because a variable-rate source
+ * makes YouTube report "not receiving enough video", and yuv420p because that
+ * is what RTMP platforms accept.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+
+export interface Destination {
+  id: string;
+  /** What to call it: "YouTube", "X", the name of a server. */
+  name: string;
+  /** rtmp://a.rtmp.youtube.com/live2 — without the key. */
+  url: string;
+  /** The stream key. It never leaves the machine: see redact(). */
+  key: string;
+  enabled: boolean;
+}
+
+export interface EncoderSettings {
+  /** kbps. */
+  videoBitrate: number;
+  audioBitrate: number;
+  framerate: number;
+  /** Seconds between keyframes. One, unless you enjoy YouTube stalling. */
+  keyframeInterval: number;
+  resolution: "720p" | "1080p";
+}
+
+export const DEFAULT_ENCODER: EncoderSettings = {
+  videoBitrate: 4500,
+  audioBitrate: 128,
+  framerate: 30,
+  keyframeInterval: 1,
+  resolution: "1080p",
+};
+
+/** The RTMP ingest URLs of the places people actually go live. */
+export const PRESETS: Record<string, string> = {
+  youtube: "rtmp://a.rtmp.youtube.com/live2",
+  x: "rtmp://ingest.x.com:1935/live",
+  facebook: "rtmps://live-api-s.facebook.com:443/rtmp",
+  tiktok: "rtmp://push.tiktokcdn.com/live",
+  twitch: "rtmp://live.twitch.tv/app",
+  kick: "rtmps://fa723fc1b171.global-contribute.live-video.net:443/app",
+};
+
+export function resolutionOf(resolution: EncoderSettings["resolution"]): { width: number; height: number } {
+  return resolution === "720p" ? { width: 1280, height: 720 } : { width: 1920, height: 1080 };
+}
+
+/** The full ingest URL. Built here so a key is never assembled by a client. */
+export function ingestUrl(destination: Destination): string {
+  return `${destination.url.replace(/\/+$/, "")}/${destination.key}`;
+}
+
+/** Somewhere to actually send RTMP. */
+export function isRtmp(url: string): boolean {
+  return /^rtmps?:\/\/[^\s/]+/i.test(url);
+}
+
+/**
+ * A destination as it may be shown to anyone. A stream key is a password: it
+ * lets a stranger broadcast as you until you rotate it.
+ */
+export function redact(destination: Destination): Omit<Destination, "key"> & { key: string } {
+  const tail = destination.key.slice(-4);
+  return { ...destination, key: destination.key ? `••••${tail}` : "" };
+}
+
+/**
+ * A tee output. `onfail=ignore` is the important part: without it one dead
+ * destination takes the whole broadcast down with it, and the one that dies is
+ * usually the one whose key expired without telling you.
+ */
+export function teeOutput(url: string, options: string[] = ["f=flv"]): string {
+  return `[${[...options, "onfail=ignore"].join(":")}]${url}`;
+}
+
+export interface BroadcastPlan {
+  source: string;
+  destinations: Destination[];
+  settings: EncoderSettings;
+  /** Also produce web-playable audio on stdout, from the same decode. */
+  webAudio: boolean;
+  /** The source has no video track, so one has to be invented for RTMP. */
+  needsVideo: boolean;
+}
+
+/**
+ * The whole ffmpeg command.
+ *
+ * RTMP platforms want a video track even when what you are sending is music,
+ * so a silent source gets a flat colour at the chosen size. It is what a radio
+ * stream looks like on YouTube either way.
+ */
+export function buildBroadcastArgs(plan: BroadcastPlan): string[] {
+  const { width, height } = resolutionOf(plan.settings.resolution);
+  const gop = plan.settings.framerate * plan.settings.keyframeInterval;
+
+  const args = ["-hide_banner", "-loglevel", "error"];
+
+  // -re only for a file: a live source already arrives in real time, and
+  // throttling it a second time drifts further behind with every track.
+  if (!/^(https?|rtmps?|pipe):/i.test(plan.source) && plan.source !== "pipe:0") args.push("-re");
+
+  if (plan.needsVideo) {
+    args.push("-f", "lavfi", "-i", `color=c=black:s=${width}x${height}:r=${plan.settings.framerate}`);
+  }
+  args.push("-i", plan.source);
+
+  // Video is always input 0: either the invented colour, or the source's own.
+  // Audio moves to input 1 when a colour was pushed in front of it.
+  args.push("-map", "0:v", "-map", plan.needsVideo ? "1:a" : "0:a");
+
+  args.push(
+    "-c:v", "libx264",
+    "-preset", "veryfast",
+    "-tune", "zerolatency",
+    "-b:v", `${plan.settings.videoBitrate}k`,
+    "-maxrate", `${Math.round(plan.settings.videoBitrate * 1.1)}k`,
+    "-bufsize", `${plan.settings.videoBitrate * 2}k`,
+    // A strict constant frame rate. A source that only produces frames when
+    // something changes reads to YouTube as a stream that is falling behind.
+    "-vf", `scale=${width}:${height},fps=${plan.settings.framerate}`,
+    "-pix_fmt", "yuv420p",
+    "-g", String(gop),
+    "-c:a", "aac",
+    "-b:a", `${plan.settings.audioBitrate}k`,
+    "-ar", "44100",
+  );
+
+  const outputs = plan.destinations
+    .filter((d) => d.enabled && isRtmp(d.url))
+    .map((d) => teeOutput(ingestUrl(d)));
+
+  // The web copy rides along on the same encode, audio only, down stdout.
+  if (plan.webAudio) outputs.push(teeOutput("pipe:1", ["select=a", "f=mp3"]));
+
+  if (outputs.length === 0) return [];
+
+  // One output does not need the tee muxer, and ffmpeg reports its errors more
+  // clearly without it.
+  if (outputs.length === 1 && !plan.webAudio) {
+    const only = plan.destinations.find((d) => d.enabled && isRtmp(d.url));
+    args.push("-f", "flv", ingestUrl(only as Destination));
+    return args;
+  }
+
+  args.push("-flags", "+global_header", "-f", "tee", outputs.join("|"));
+  return args;
+}
+
+export type BroadcastState = "idle" | "live" | "failed";
+
+export interface BroadcastStatus {
+  state: BroadcastState;
+  since: number | null;
+  /** Names only, and never a key. */
+  destinations: string[];
+  error: string;
+}
+
+/**
+ * One broadcast at a time, restarted when it dies. A live stream that stops
+ * because a platform hiccupped, and stays stopped, is worse than no feature.
+ */
+export class Broadcaster {
+  private child: ChildProcess | null = null;
+  private plan: BroadcastPlan | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  private attempts = 0;
+  private state: BroadcastState = "idle";
+  private since: number | null = null;
+  private error = "";
+
+  constructor(
+    private readonly ffmpeg: string[] = ["ffmpeg"],
+    /** Injected so a test never waits five real seconds. */
+    private readonly delay = (ms: number, run: () => void) => setTimeout(run, ms),
+  ) {}
+
+  status(): BroadcastStatus {
+    return {
+      state: this.state,
+      since: this.since,
+      destinations: (this.plan?.destinations ?? []).filter((d) => d.enabled).map((d) => d.name),
+      error: this.error,
+    };
+  }
+
+  start(plan: BroadcastPlan): { ok: boolean; error: string } {
+    const args = buildBroadcastArgs(plan);
+    if (args.length === 0) return { ok: false, error: "no enabled destination with an rtmp url" };
+
+    this.stop();
+    this.plan = plan;
+    this.attempts = 0;
+    this.error = "";
+    this.spawn(args);
+    return { ok: true, error: "" };
+  }
+
+  stop(): void {
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = null;
+    this.plan = null;
+    this.state = "idle";
+    this.since = null;
+    const child = this.child;
+    this.child = null;
+    child?.kill("SIGKILL");
+  }
+
+  private spawn(args: string[]): void {
+    const [command, ...prefix] = this.ffmpeg as [string, ...string[]];
+    const child = spawn(command, [...prefix, ...args], { stdio: ["ignore", "pipe", "pipe"] });
+    this.child = child;
+    this.state = "live";
+    this.since = Date.now();
+
+    let tail = "";
+    child.stderr?.on("data", (chunk: Buffer) => {
+      tail = (tail + chunk.toString()).slice(-2000);
+    });
+
+    child.on("error", (error) => {
+      this.error = error.message;
+      this.state = "failed";
+    });
+
+    child.on("close", (code) => {
+      if (this.child !== child) return; // stopped on purpose, or replaced
+      this.child = null;
+      if (code === 0) {
+        this.state = "idle";
+        this.since = null;
+        return;
+      }
+      this.error = tail.trim().split("\n").pop() ?? `ffmpeg exited ${code}`;
+      this.state = "failed";
+      this.retry();
+    });
+  }
+
+  /** Back off, but never give up entirely while a plan is set. */
+  private retry(): void {
+    const plan = this.plan;
+    if (plan === null) return;
+    this.attempts++;
+    const wait = Math.min(30_000, 1000 * 2 ** Math.min(5, this.attempts - 1));
+    this.timer = this.delay(wait, () => {
+      if (this.plan !== plan) return;
+      this.spawn(buildBroadcastArgs(plan));
+    }) as ReturnType<typeof setTimeout>;
+  }
+}