nixamp 0.2.0 → 0.3.0

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

package/src/channels.ts

@@ -0,0 +1,281 @@
+/**
+ * Several streams at once.
+ *
+ * A channel is one live source and everybody listening to it. Two or three
+ * devices can publish at the same time -- a phone, a desktop, a second window
+ * -- and each has its own audience, so a listener picks which one to hear.
+ *
+ * The fan-out is the point. One ffmpeg decodes a publisher's bytes once, and
+ * the MP3 it produces is written to every listener attached to that channel.
+ * A decode per listener would cost a CPU core each and, for a live stream,
+ * would not even agree with itself about what "now" is.
+ *
+ * A listener joining halfway through gets the stream from that moment, which is
+ * what live means. MP3 frames are self-describing, so a player finds the next
+ * frame boundary and carries on; there is nothing to catch up on.
+ */
+import { spawn, type ChildProcess } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import type { Readable } from "node:stream";
+
+/** Somewhere for a channel's audio to go. A response, in practice. */
+export interface Listener {
+  write(chunk: Buffer): boolean;
+  end(): void;
+}
+
+export interface ChannelInfo {
+  id: string;
+  /** What the publisher called itself. */
+  name: string;
+  /** The container it is sending, e.g. webm from a browser, flv over RTMP. */
+  format: string;
+  /** How it arrived. */
+  via: "http" | "rtmp";
+  startedAt: number;
+  bytes: number;
+  listeners: number;
+}
+
+/** A name that can sit in a URL and be read back in a list. */
+export function cleanId(value: unknown, fallback = "main"): string {
+  if (typeof value !== "string") return fallback;
+  const id = value.trim().toLowerCase().replace(/[^a-z0-9_-]/g, "-").replace(/^-+|-+$/g, "");
+  return id.slice(0, 40) || fallback;
+}
+
+export interface ChannelOptions {
+  ffmpeg: string[];
+  onStart?: (info: ChannelInfo) => void;
+  onEnd?: (info: ChannelInfo) => void;
+}
+
+/**
+ * One live source, and its audience.
+ *
+ * Everything a listener is sent has been through ffmpeg, so a publisher cannot
+ * decide what bytes reach a browser by choosing what to send.
+ */
+export class Channel {
+  readonly listeners = new Set<Listener>();
+  private child: ChildProcess | null = null;
+  private closing = false;
+
+  constructor(
+    readonly info: ChannelInfo,
+    private readonly options: ChannelOptions,
+    private readonly onGone: (id: string) => void,
+  ) {}
+
+  start(format: string): void {
+    const [command, ...prefix] = this.options.ffmpeg as [string, ...string[]];
+    const child = spawn(
+      command,
+      [
+        ...prefix,
+        "-hide_banner",
+        "-loglevel", "error",
+        // Stated, because ffmpeg mis-probes a live unseekable pipe: it reads a
+        // few kilobytes, guesses, and guesses wrong.
+        "-f", format,
+        "-i", "pipe:0",
+        "-vn",
+        "-c:a", "libmp3lame",
+        "-b:a", "192k",
+        "-f", "mp3",
+        "pipe:1",
+      ],
+      { stdio: ["pipe", "pipe", "pipe"] },
+    );
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      this.info.bytes += chunk.byteLength;
+      this.send(chunk);
+    });
+    // A publisher that hangs up mid-write breaks the pipe, and an unhandled
+    // EPIPE takes the whole server with it.
+    child.stdin?.on("error", () => this.close());
+    child.stdout?.on("error", () => this.close());
+    child.on("error", () => this.close());
+    child.on("close", () => this.close());
+
+    this.child = child;
+    this.options.onStart?.(this.info);
+  }
+
+  /** Feed the source. */
+  write(chunk: Buffer): boolean {
+    return this.child?.stdin?.write(chunk) ?? false;
+  }
+
+  async pump(body: Readable): Promise<void> {
+    for await (const chunk of body) {
+      if (this.closing) return;
+      if (!this.write(chunk as Buffer)) {
+        await new Promise((done) => this.child?.stdin?.once("drain", done) ?? done(null));
+      }
+    }
+  }
+
+  /**
+   * Audio that is already in its final form, from a source we did not spawn.
+   * The bytes still only reach a listener after something decoded them; it was
+   * simply a different process that did it.
+   */
+  feed(chunk: Buffer): void {
+    this.info.bytes += chunk.byteLength;
+    this.send(chunk);
+  }
+
+  /** Write to everyone, and drop anybody whose socket has gone. */
+  private send(chunk: Buffer): void {
+    for (const listener of this.listeners) {
+      try {
+        listener.write(chunk);
+      } catch {
+        // One listener's broken socket is not the channel's problem.
+        this.listeners.delete(listener);
+      }
+    }
+    this.info.listeners = this.listeners.size;
+  }
+
+  listen(listener: Listener): () => void {
+    this.listeners.add(listener);
+    this.info.listeners = this.listeners.size;
+    return () => {
+      this.listeners.delete(listener);
+      this.info.listeners = this.listeners.size;
+    };
+  }
+
+  close(): void {
+    if (this.closing) return;
+    this.closing = true;
+    const child = this.child;
+    this.child = null;
+    try {
+      child?.stdin?.end();
+    } catch {
+      // Already broken, which is usually why we are here.
+    }
+    child?.kill("SIGKILL");
+    // Listeners are ended rather than left hanging on a stream that stopped.
+    for (const listener of this.listeners) {
+      try {
+        listener.end();
+      } catch {
+        // Gone already.
+      }
+    }
+    this.listeners.clear();
+    this.info.listeners = 0;
+    this.options.onEnd?.(this.info);
+    this.onGone(this.info.id);
+  }
+}
+
+/**
+ * Every channel currently live.
+ *
+ * A channel exists while somebody is publishing to it and disappears when they
+ * stop, so the list is what is actually on rather than what was once
+ * configured.
+ */
+export class Channels {
+  private readonly open = new Map<string, Channel>();
+
+  constructor(private readonly options: ChannelOptions) {}
+
+  list(): ChannelInfo[] {
+    return [...this.open.values()]
+      .map((channel) => channel.info)
+      .sort((a, b) => a.startedAt - b.startedAt);
+  }
+
+  get count(): number {
+    return this.open.size;
+  }
+
+  /** Total listeners across every channel. */
+  get listeners(): number {
+    let total = 0;
+    for (const channel of this.open.values()) total += channel.listeners.size;
+    return total;
+  }
+
+  has(id: string): boolean {
+    return this.open.has(id);
+  }
+
+  /**
+   * Claim a channel and start decoding into it. Null when that channel is
+   * already being published to: two publishers on one channel would be two
+   * songs at once, which is never what anybody meant. Publishing to a
+   * *different* channel is exactly what this class exists for.
+   */
+  publish(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null {
+    if (this.open.has(id)) return null;
+    const channel = new Channel(
+      {
+        id,
+        name: name || "a device",
+        format,
+        via,
+        startedAt: Date.now(),
+        bytes: 0,
+        listeners: 0,
+      },
+      this.options,
+      (gone) => this.open.delete(gone),
+    );
+    this.open.set(id, channel);
+    channel.start(format);
+    return channel;
+  }
+
+  /** Attach a listener, or null when nothing is playing on that channel. */
+  listen(id: string, listener: Listener): (() => void) | null {
+    const channel = this.open.get(id);
+    return channel ? channel.listen(listener) : null;
+  }
+
+  /** Feed a channel that already exists, for a publisher sending chunks. */
+  writeTo(id: string, chunk: Buffer): boolean {
+    return this.open.get(id)?.write(chunk) ?? false;
+  }
+
+  /**
+   * A channel fed by audio somebody else is already decoding.
+   *
+   * An RTMP listener is an ffmpeg with a publisher on one end, and it produces
+   * MP3 on its own. Spawning a second ffmpeg to decode what the first one just
+   * decoded would double the work to arrive at the same bytes.
+   */
+  attach(id: string, name: string, format: string, via: ChannelInfo["via"]): Channel | null {
+    if (this.open.has(id)) return null;
+    const channel = new Channel(
+      { id, name: name || "a device", format, via, startedAt: Date.now(), bytes: 0, listeners: 0 },
+      this.options,
+      (gone) => this.open.delete(gone),
+    );
+    this.open.set(id, channel);
+    return channel;
+  }
+
+  stop(id: string): boolean {
+    const channel = this.open.get(id);
+    if (!channel) return false;
+    channel.close();
+    return true;
+  }
+
+  stopAll(): void {
+    for (const channel of [...this.open.values()]) channel.close();
+  }
+}
+
+/** A channel id nobody chose, for a publisher that did not name one. */
+export function generatedId(): string {
+  return `s${randomBytes(3).toString("hex")}`;
+}

package/src/connections.ts

@@ -129,6 +129,19 @@ export class Connections {
     return [...live, ...done];
   }
 
+  /**
+   * Live connections that are actually hearing something. The state feed and
+   * the page are not listeners, and counting them would put a stream over the
+   * free allowance with nobody listening to it.
+   */
+  get listening(): number {
+    let count = 0;
+    for (const item of this.items.values()) {
+      if (item.endedAt === null && (item.kind === "stream" || item.kind === "media")) count++;
+    }
+    return count;
+  }
+
   get active(): number {
     let count = 0;
     for (const item of this.items.values()) if (item.endedAt === null) count++;

package/src/directory.ts

@@ -0,0 +1,135 @@
+/**
+ * The public directory.
+ *
+ * A nixamp that agrees to be listed announces itself to nixamp.com every so
+ * often and is forgotten when it stops. There is no database behind it: an
+ * entry lives for a few minutes and a heartbeat renews it, so a restart of the
+ * directory costs one heartbeat rather than a migration, and a stream that
+ * dies falls out of the list without anyone having to notice.
+ *
+ * What is published is the *listen* link. The control key never leaves the
+ * machine it was minted on.
+ */
+
+/** How long an entry survives without a heartbeat. */
+export const TTL_MS = 4 * 60 * 1000;
+/** How often a publisher renews. Comfortably inside the TTL. */
+export const HEARTBEAT_MS = 90 * 1000;
+export const DEFAULT_DIRECTORY = "https://nixamp.com";
+
+export interface Listing {
+  /** Assigned by the directory, so a publisher cannot claim someone else's. */
+  id: string;
+  name: string;
+  /** The listen link, which is what a browser opens. */
+  url: string;
+  tracks: number;
+  nowPlaying: string;
+  /** Set by the directory from the request, never by the publisher. */
+  updatedAt: number;
+}
+
+/** What a publisher sends. Everything else about a listing is ours to decide. */
+export interface Announcement {
+  id?: string;
+  name: string;
+  url: string;
+  tracks: number;
+  nowPlaying: string;
+}
+
+const MAX_NAME = 60;
+const MAX_TRACK = 120;
+
+/** Trim and flatten, so one publisher cannot draw a box in someone's terminal. */
+export function clean(value: unknown, max: number): string {
+  if (typeof value !== "string") return "";
+  // Control characters include the escape that starts an ANSI sequence, and
+  // this text is rendered in a terminal as well as a browser.
+  return value.replace(/[\u0000-\u001f\u007f]/g, " ").trim().slice(0, max);
+}
+
+/**
+ * A URL we are willing to list. It has to be somewhere a browser can go, and
+ * it must not be a loopback or link-local address: those are only reachable
+ * from the machine that published them, so listing one is an entry nobody but
+ * the publisher can ever open.
+ */
+export function publishable(raw: string): URL | null {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return null;
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") return null;
+
+  const host = url.hostname.replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host === "::1" || host.endsWith(".localhost")) return null;
+  if (/^127\./.test(host) || /^169\.254\./.test(host)) return null;
+  return url;
+}
+
+export function parseAnnouncement(input: unknown): Announcement | null {
+  if (typeof input !== "object" || input === null) return null;
+  const record = input as Record<string, unknown>;
+
+  const url = typeof record["url"] === "string" ? record["url"] : "";
+  if (publishable(url) === null) return null;
+
+  const name = clean(record["name"], MAX_NAME);
+  const tracks = Number(record["tracks"]);
+  return {
+    ...(typeof record["id"] === "string" ? { id: clean(record["id"], 40) } : {}),
+    name: name || "a nixamp",
+    url,
+    tracks: Number.isFinite(tracks) && tracks >= 0 ? Math.min(1_000_000, Math.floor(tracks)) : 0,
+    nowPlaying: clean(record["nowPlaying"], MAX_TRACK),
+  };
+}
+
+/**
+ * The registry. In memory on purpose: see the note at the top of the file.
+ * One entry per URL, so a publisher restarting does not leave a ghost of
+ * itself behind next to the entry that replaced it.
+ */
+export class Directory {
+  private readonly items = new Map<string, Listing>();
+  private sequence = 0;
+
+  constructor(
+    private readonly ttl = TTL_MS,
+    private readonly now: () => number = Date.now,
+  ) {}
+
+  announce(announcement: Announcement): Listing {
+    this.sweep();
+    const existing = [...this.items.values()].find((item) => item.url === announcement.url);
+    const id = existing?.id ?? `s${++this.sequence}${this.now().toString(36)}`;
+    const listing: Listing = {
+      id,
+      name: announcement.name,
+      url: announcement.url,
+      tracks: announcement.tracks,
+      nowPlaying: announcement.nowPlaying,
+      updatedAt: this.now(),
+    };
+    this.items.set(id, listing);
+    return listing;
+  }
+
+  withdraw(id: string): void {
+    this.items.delete(id);
+  }
+
+  list(): Listing[] {
+    this.sweep();
+    return [...this.items.values()].sort((a, b) => b.updatedAt - a.updatedAt || a.id.localeCompare(b.id));
+  }
+
+  /** Forget anything that stopped renewing. */
+  private sweep(): void {
+    const cutoff = this.now() - this.ttl;
+    for (const [id, item] of this.items) if (item.updatedAt < cutoff) this.items.delete(id);
+  }
+}