nixamp 0.6.0 → 0.6.4

package/dist/admin.d.ts

@@ -46,6 +46,19 @@ export interface AdminOptions {
 export declare function resolveTarget(argv: string[]): AdminOptions;
 /** Seconds as something a person reads at a glance. */
 export declare function since(ms: number): string;
+/**
+ * What a keypress contributes to a field being typed into.
+ *
+ * A paste is one event carrying the whole string, not a burst of single
+ * characters, so a handler that only accepted `key.length === 1` accepted
+ * nothing at all from a paste -- which is how you find you cannot put a URL in
+ * the box by any means except typing it out.
+ *
+ * The ambiguity is real and unavoidable: a pasted word of bare letters is
+ * indistinguishable from a key name, and loses. A URL or a path never is,
+ * because neither is spelled with letters alone.
+ */
+export declare function typed(key: string): string;
 export declare function bytes(value: number): string;
 export declare function admin(argv: string[]): Promise<void>;
 export interface View {

package/dist/admin.js

@@ -44,6 +44,31 @@ export function since(ms) {
         return `${hours}h ${minutes % 60}m`;
     return `${Math.floor(hours / 24)}d ${hours % 24}h`;
 }
+/**
+ * A key name rather than something somebody typed: "up", "f7", "ctrl+c".
+ * Letters and digits only, so anything with a colon or a slash in it is text.
+ */
+const NAMED_KEY = /^(?:[a-z]+\d*|(?:ctrl|alt|shift|meta)\+.+)$/;
+/**
+ * What a keypress contributes to a field being typed into.
+ *
+ * A paste is one event carrying the whole string, not a burst of single
+ * characters, so a handler that only accepted `key.length === 1` accepted
+ * nothing at all from a paste -- which is how you find you cannot put a URL in
+ * the box by any means except typing it out.
+ *
+ * The ambiguity is real and unavoidable: a pasted word of bare letters is
+ * indistinguishable from a key name, and loses. A URL or a path never is,
+ * because neither is spelled with letters alone.
+ */
+export function typed(key) {
+    if (key.length === 1)
+        return key >= " " && key !== "\u007f" ? key : "";
+    if (NAMED_KEY.test(key))
+        return "";
+    // A paste. Control characters and newlines are not part of an address.
+    return key.replace(/[\u0000-\u001f\u007f]/g, "");
+}
 export function bytes(value) {
     const units = ["B", "KiB", "MiB", "GiB"];
     let n = value;
@@ -109,9 +134,8 @@ export async function admin(argv) {
             }
             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;
+            else
+                restreaming += typed(key);
             app.invalidate();
             return;
         }

package/dist/audio.d.ts

@@ -58,6 +58,20 @@ export declare function peaks(pcm: Float32Array): [number, number];
 /** Interleaved stereo down to mono, for the analyser. */
 export declare function toMono(pcm: Float32Array): Float32Array;
 export declare function formatTime(seconds: number): string;
+/**
+ * The same tags, read without blocking anything.
+ *
+ * `probe` is spawnSync, and 0.5.5 tried to fix the tagging pass by yielding
+ * between files. That is not enough: each individual call still stops the
+ * process for as long as one ffprobe takes, and on a large file over a slow
+ * disk that is hundreds of milliseconds. Yield, block, yield, block, and a
+ * server delivers a stream in slivers -- measured at 357 KB/s on a machine
+ * whose disk reads at 6.5 MB/s and whose link runs at 1.4 Gbps.
+ *
+ * ffprobe still costs what it costs. It just costs it in a child process now,
+ * which is where that work belongs.
+ */
+export declare function probeAsync(tools: Tools, path: string): Promise<Track>;
 /** What is actually inside a container, as opposed to what the name suggests. */
 export interface Codecs {
     /** e.g. "h264", "hevc", "vp9". Empty when there is no video stream. */
@@ -82,4 +96,13 @@ export declare function codecsOf(tools: Tools, path: string): Promise<Codecs>;
  * would cost a core per viewer and look worse. So the streams decide, one part
  * at a time -- a film can have its video copied and only its DTS re-encoded.
  */
-export declare function videoArgs(codecs: Codecs): string[];
+export declare function videoArgs(codecs: Codecs, capKbps?: number): string[];
+/**
+ * The width that suits a bitrate.
+ *
+ * 1080p squeezed into a megabit is worse than 360p at the same megabit: the
+ * encoder spends everything it has on detail it cannot afford and the result
+ * smears on every motion. Dropping the resolution with the bitrate is what
+ * makes a small stream watchable rather than merely small.
+ */
+export declare function widthFor(kbps: number): number;

package/dist/audio.js

@@ -204,6 +204,77 @@ export function formatTime(seconds) {
     const s = total % 60;
     return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
 }
+/**
+ * The same tags, read without blocking anything.
+ *
+ * `probe` is spawnSync, and 0.5.5 tried to fix the tagging pass by yielding
+ * between files. That is not enough: each individual call still stops the
+ * process for as long as one ffprobe takes, and on a large file over a slow
+ * disk that is hundreds of milliseconds. Yield, block, yield, block, and a
+ * server delivers a stream in slivers -- measured at 357 KB/s on a machine
+ * whose disk reads at 6.5 MB/s and whose link runs at 1.4 Gbps.
+ *
+ * ffprobe still costs what it costs. It just costs it in a child process now,
+ * which is where that work belongs.
+ */
+export async function probeAsync(tools, path) {
+    const [cmd, ...rest] = tools.ffprobe;
+    const fallback = {
+        path,
+        title: path.split("/").pop() ?? path,
+        artist: "",
+        album: "",
+        duration: 0,
+    };
+    if (!cmd)
+        return fallback;
+    return new Promise((done) => {
+        const child = spawn(cmd, [
+            ...rest,
+            "-v", "quiet", "-print_format", "json",
+            "-show_format", "-show_entries", "format_tags=title,artist,album",
+            path,
+        ], { stdio: ["ignore", "pipe", "ignore"] });
+        let out = "";
+        // A file that will not answer must not hold a place in the queue for ever.
+        const giveUp = setTimeout(() => child.kill("SIGKILL"), 20_000);
+        giveUp.unref?.();
+        child.stdout.on("data", (chunk) => {
+            if (out.length < 4 * 1024 * 1024)
+                out += chunk.toString("utf8");
+        });
+        child.on("error", () => {
+            clearTimeout(giveUp);
+            done(fallback);
+        });
+        child.on("close", (code) => {
+            clearTimeout(giveUp);
+            if (code !== 0)
+                return done(fallback);
+            done(readTags(out, fallback));
+        });
+    });
+}
+/** The tags out of ffprobe's JSON, or the filename when it said nothing useful. */
+function readTags(stdout, fallback) {
+    try {
+        const parsed = JSON.parse(stdout);
+        const tags = parsed.format?.tags ?? {};
+        const lower = {};
+        for (const [k, v] of Object.entries(tags))
+            lower[k.toLowerCase()] = v;
+        return {
+            path: fallback.path,
+            title: lower.title || fallback.title,
+            artist: lower.artist ?? "",
+            album: lower.album ?? "",
+            duration: Number(parsed.format?.duration ?? 0) || 0,
+        };
+    }
+    catch {
+        return fallback;
+    }
+}
 /**
  * Ask ffprobe what the streams are, without holding the event loop.
  *
@@ -253,7 +324,11 @@ export async function codecsOf(tools, path) {
  * would cost a core per viewer and look worse. So the streams decide, one part
  * at a time -- a film can have its video copied and only its DTS re-encoded.
  */
-export function videoArgs(codecs) {
+export function videoArgs(codecs, capKbps = 0) {
+    // A ceiling means re-encoding whatever is there, because you cannot cap the
+    // bitrate of a stream you are copying: copying is what "unchanged" means.
+    if (capKbps > 0)
+        return cappedArgs(capKbps);
     // What a browser can play inside MP4 without help.
     const keepVideo = codecs.video === "h264";
     const keepAudio = codecs.audio === "aac" || codecs.audio === "mp3";
@@ -269,3 +344,43 @@ export function videoArgs(codecs) {
         "-movflags", "frag_keyframe+empty_moov+default_base_moof",
     ];
 }
+/**
+ * The width that suits a bitrate.
+ *
+ * 1080p squeezed into a megabit is worse than 360p at the same megabit: the
+ * encoder spends everything it has on detail it cannot afford and the result
+ * smears on every motion. Dropping the resolution with the bitrate is what
+ * makes a small stream watchable rather than merely small.
+ */
+export function widthFor(kbps) {
+    if (kbps <= 800)
+        return 640;
+    if (kbps <= 1800)
+        return 854;
+    if (kbps <= 4000)
+        return 1280;
+    return 1920;
+}
+/** Arguments for a stream that has to fit through a link of a known size. */
+function cappedArgs(kbps) {
+    const audioKbps = kbps <= 800 ? 96 : 128;
+    const videoKbps = Math.max(200, kbps - audioKbps);
+    return [
+        "-c:v", "libx264",
+        "-preset", "veryfast",
+        "-pix_fmt", "yuv420p",
+        // -2 keeps the aspect ratio and an even height, which H.264 requires.
+        // The min() never enlarges: a 480p source asked for 720p stays 480p.
+        "-vf", `scale='min(${widthFor(kbps)},iw)':-2`,
+        "-b:v", `${videoKbps}k`,
+        // A ceiling rather than an average, because an average that spikes is a
+        // stall on a link this size. The buffer is one second of it.
+        "-maxrate", `${videoKbps}k`,
+        "-bufsize", `${videoKbps}k`,
+        "-c:a", "aac",
+        "-b:a", `${audioKbps}k`,
+        "-ac", "2",
+        "-f", "mp4",
+        "-movflags", "frag_keyframe+empty_moov+default_base_moof",
+    ];
+}

package/dist/invite.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Asking somebody to watch, when that somebody is not technical.
+ *
+ * A share link is a URL with a key in it, which is fine for the person who
+ * runs the server and useless as a thing to text your mother. An invite is the
+ * three ways in, written as a sentence: a link that opens a player, a phone
+ * number, and the code to key once it answers.
+ *
+ * The sender is signed in, because sending is an action with a cost: a text
+ * message is money and somebody's phone. The recipient signs in too, but only
+ * once and only at the far end of a single click, because a stream can ask to
+ * be paid for -- x402 starts charging past five listeners -- and there is
+ * nobody to charge without an account. The dial-in path is the exception and
+ * stays open to anybody, since a phone call cannot sign in to anything.
+ */
+/** Where the phone line answers, and what to key when it does. */
+export interface Invite {
+    /** What the stream is called, as the recipient will see it. */
+    name: string;
+    /** A link that opens a player on this stream, listen only. */
+    link: string;
+    /** The phone number, when this stream is one the line knows about. */
+    phone: string;
+    /** The six digits that reach this stream, when it has been published. */
+    code: string;
+}
+/** Looks like a phone number rather than an address. */
+export declare function isPhone(value: string): boolean;
+/** Looks like somewhere an email could arrive. */
+export declare function isEmail(value: string): boolean;
+/**
+ * The message itself.
+ *
+ * Short, because it is going into a text message, and ordered by how likely
+ * each way in is to work for the person reading it. The link first: most
+ * people have a browser in their hand. The phone last, because it is the one
+ * that needs no browser at all and is therefore the fallback that never fails.
+ */
+export declare function inviteText(invite: Invite): string;
+/** The same thing as a subject line, for the surface that wants one. */
+export declare function inviteSubject(invite: Invite): string;
+/**
+ * A link that opens a player on this stream.
+ *
+ * Sent through nixamp.com when the stream is https, because that page is a
+ * player anybody can already open and reaches this stream with `?url=`. An
+ * http stream is sent as its own address instead: a browser refuses every
+ * request from an https page to an http one, so routing it through nixamp.com
+ * would produce a link that cannot work, which is worse than a plainer one
+ * that does.
+ */
+export declare function watchLink(streamUrl: string, site: string): string;

package/dist/invite.js

@@ -0,0 +1,58 @@
+/**
+ * Asking somebody to watch, when that somebody is not technical.
+ *
+ * A share link is a URL with a key in it, which is fine for the person who
+ * runs the server and useless as a thing to text your mother. An invite is the
+ * three ways in, written as a sentence: a link that opens a player, a phone
+ * number, and the code to key once it answers.
+ *
+ * The sender is signed in, because sending is an action with a cost: a text
+ * message is money and somebody's phone. The recipient signs in too, but only
+ * once and only at the far end of a single click, because a stream can ask to
+ * be paid for -- x402 starts charging past five listeners -- and there is
+ * nobody to charge without an account. The dial-in path is the exception and
+ * stays open to anybody, since a phone call cannot sign in to anything.
+ */
+/** Looks like a phone number rather than an address. */
+export function isPhone(value) {
+    return /^\+?[\d\s().-]{7,20}$/.test(value.trim()) && /\d{7}/.test(value.replace(/\D/g, ""));
+}
+/** Looks like somewhere an email could arrive. */
+export function isEmail(value) {
+    return /^[^@\s]+@[^@\s.]+\.[^@\s]+$/.test(value.trim());
+}
+/**
+ * The message itself.
+ *
+ * Short, because it is going into a text message, and ordered by how likely
+ * each way in is to work for the person reading it. The link first: most
+ * people have a browser in their hand. The phone last, because it is the one
+ * that needs no browser at all and is therefore the fallback that never fails.
+ */
+export function inviteText(invite) {
+    const lines = [`${invite.name} is streaming.`, "", `Watch: ${invite.link}`];
+    if (invite.phone && invite.code) {
+        lines.push("", `Or call ${invite.phone} and key ${invite.code} to listen.`);
+    }
+    return lines.join("\n");
+}
+/** The same thing as a subject line, for the surface that wants one. */
+export function inviteSubject(invite) {
+    return `${invite.name} is streaming`;
+}
+/**
+ * A link that opens a player on this stream.
+ *
+ * Sent through nixamp.com when the stream is https, because that page is a
+ * player anybody can already open and reaches this stream with `?url=`. An
+ * http stream is sent as its own address instead: a browser refuses every
+ * request from an https page to an http one, so routing it through nixamp.com
+ * would produce a link that cannot work, which is worse than a plainer one
+ * that does.
+ */
+export function watchLink(streamUrl, site) {
+    const bare = streamUrl.replace(/\/+$/, "");
+    if (!bare.startsWith("https://"))
+        return bare;
+    return `${site.replace(/\/+$/, "")}/?url=${encodeURIComponent(bare)}`;
+}

package/dist/playlist.d.ts

@@ -38,5 +38,7 @@ export declare function loadPlaylist(tools: Tools, root: string, probeTags?: boo
  * ffprobe rather than for the whole library, and the tagging still finishes in
  * about the time it did.
  */
-export declare function loadTagged(tools: Tools, source: string): Promise<Track[]>;
+export declare function loadTagged(tools: Tools, source: string, 
+/** Injected by the test, which must not depend on ffprobe being installed. */
+probeOne?: (tools: Tools, path: string) => Promise<Track>): Promise<Track[]>;
 export declare function displayName(track: Track): string;

package/dist/playlist.js

@@ -1,7 +1,7 @@
 /** The playlist: audio found on disk or named by a playlist, in a stable order. */
 import { readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-import { probe } from "./audio.js";
+import { probe, probeAsync } from "./audio.js";
 import { isHls, isPlaylistFile, isRemote, nameOf, parseM3u, parsePls, } from "./sources.js";
 export const AUDIO_EXTENSIONS = new Set([
     ".mp3", ".flac", ".ogg", ".oga", ".opus", ".m4a", ".aac",
@@ -135,15 +135,20 @@ export function loadPlaylist(tools, root, probeTags = true) {
  * ffprobe rather than for the whole library, and the tagging still finishes in
  * about the time it did.
  */
-export async function loadTagged(tools, source) {
+export async function loadTagged(tools, source, 
+/** Injected by the test, which must not depend on ffprobe being installed. */
+probeOne = probeAsync) {
     // A URL is one thing and is never probed; a playlist carries its own titles.
     if (isRemote(source) || isPlaylistFile(source))
         return loadSource(tools, source, true);
     const paths = findAudio(source);
     const tracks = [];
     for (const path of paths) {
-        tracks.push(probe(tools, path));
-        await new Promise((done) => setImmediate(done));
+        // Awaiting a child process, not blocking on one. Yielding between files
+        // was not enough: each spawnSync still stopped everything for as long as
+        // one ffprobe took, which on a large file is long enough to strangle a
+        // stream being served at the same time.
+        tracks.push(await probeOne(tools, path));
     }
     return tracks;
 }

package/dist/server.d.ts

@@ -239,6 +239,12 @@ export interface HandlerOptions {
      * imported so the handler stays a plain function of a request.
      */
     load: (source: string) => Promise<Track[]>;
+    /**
+     * The same source, with its tags, read without holding the event loop. Called
+     * after `load` and never awaited: the titles arrive into a player that is
+     * already playing.
+     */
+    tag?: (source: string) => Promise<Track[]>;
     /**
      * The public directory, on the instance that hosts one. Only nixamp.com
      * passes this; a nixamp on your laptop is a publisher, not a registry.

package/dist/server.js

@@ -1623,6 +1623,15 @@ export function createHandler(engine, options) {
                     return;
                 }
                 engine.replace(tracks, source);
+                // Names now, tags later, here as much as at startup: re-streaming a
+                // directory of five thousand files used to read every tag before it
+                // answered, with the event loop held the whole time.
+                if (options.tag) {
+                    void options
+                        .tag(source)
+                        .then((tagged) => engine.retag(tagged, source))
+                        .catch(() => { });
+                }
                 json(response, 200, engine.snapshot());
             }
             catch (error) {
@@ -1646,7 +1655,12 @@ export function createHandler(engine, options) {
             // to it raw is bytes it cannot play. Seeking is what this route is for
             // and transcoding gives it up, but an unseekable film beats a silent
             // one -- and the seekable formats are untouched.
-            if (playsInBrowser(file)) {
+            // A ceiling the caller asked for, because only the caller knows what its
+            // link can carry. Capped at both ends: nothing below 200k is watchable,
+            // and above 20 megabits the original was always the better answer.
+            const asked = Number(url.searchParams.get("kbps") ?? "");
+            const capKbps = Number.isFinite(asked) && asked > 0 ? Math.min(20_000, Math.max(200, asked)) : 0;
+            if (playsInBrowser(file) && capKbps === 0) {
                 sendFile(request, response, file);
             }
             else if (hasPicture(file)) {
@@ -1654,7 +1668,7 @@ export function createHandler(engine, options) {
                 // soundtrack over a blank panel; what ffprobe finds inside decides how
                 // little work it takes to keep the picture.
                 const codecs = await codecsOf({ ffmpeg: [], ffprobe: options.ffprobe ?? ["ffprobe"], play: null }, file);
-                pipeFfmpeg(request, response, file, options.ffmpeg ?? ["ffmpeg"], videoArgs(codecs), "video/mp4");
+                pipeFfmpeg(request, response, file, options.ffmpeg ?? ["ffmpeg"], videoArgs(codecs, capKbps), "video/mp4");
             }
             else {
                 transcode(request, response, file, options.ffmpeg ?? ["ffmpeg"]);
@@ -2234,7 +2248,10 @@ export async function serve(argv, version = "0.1.0") {
         ffmpeg: tools.ffmpeg,
         ffprobe: tools.ffprobe,
         ...(tls ? { tls } : {}),
-        load: (next) => loadSource(tools, next),
+        // Untagged, so a directory of five thousand files answers at once; the
+        // tags follow through `tag` below.
+        load: (next) => loadSource(tools, next, false),
+        tag: (next) => loadTagged(tools, next),
         ...(directory ? { directory } : {}),
         ...(follows ? { follows, vapidPublicKey } : {}),
         ...(partyLine ? { partyLine } : {}),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.6.0",
+  "version": "0.6.4",
   "description": "It really whips the terminal's ass. A Winamp-shaped audio player for your terminal.",
   "license": "MIT",
   "type": "module",

package/src/admin.ts

@@ -79,6 +79,31 @@ export function since(ms: number): string {
   return `${Math.floor(hours / 24)}d ${hours % 24}h`;
 }
 
+/**
+ * A key name rather than something somebody typed: "up", "f7", "ctrl+c".
+ * Letters and digits only, so anything with a colon or a slash in it is text.
+ */
+const NAMED_KEY = /^(?:[a-z]+\d*|(?:ctrl|alt|shift|meta)\+.+)$/;
+
+/**
+ * What a keypress contributes to a field being typed into.
+ *
+ * A paste is one event carrying the whole string, not a burst of single
+ * characters, so a handler that only accepted `key.length === 1` accepted
+ * nothing at all from a paste -- which is how you find you cannot put a URL in
+ * the box by any means except typing it out.
+ *
+ * The ambiguity is real and unavoidable: a pasted word of bare letters is
+ * indistinguishable from a key name, and loses. A URL or a path never is,
+ * because neither is spelled with letters alone.
+ */
+export function typed(key: string): string {
+  if (key.length === 1) return key >= " " && key !== "\u007f" ? key : "";
+  if (NAMED_KEY.test(key)) return "";
+  // A paste. Control characters and newlines are not part of an address.
+  return key.replace(/[\u0000-\u001f\u007f]/g, "");
+}
+
 export function bytes(value: number): string {
   const units = ["B", "KiB", "MiB", "GiB"];
   let n = value;
@@ -142,8 +167,7 @@ export async function admin(argv: string[]): Promise<void> {
         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;
+      else restreaming += typed(key);
       app.invalidate();
       return;
     }

package/src/audio.ts

@@ -232,6 +232,82 @@ export function formatTime(seconds: number): string {
   return `${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}`;
 }
 
+/**
+ * The same tags, read without blocking anything.
+ *
+ * `probe` is spawnSync, and 0.5.5 tried to fix the tagging pass by yielding
+ * between files. That is not enough: each individual call still stops the
+ * process for as long as one ffprobe takes, and on a large file over a slow
+ * disk that is hundreds of milliseconds. Yield, block, yield, block, and a
+ * server delivers a stream in slivers -- measured at 357 KB/s on a machine
+ * whose disk reads at 6.5 MB/s and whose link runs at 1.4 Gbps.
+ *
+ * ffprobe still costs what it costs. It just costs it in a child process now,
+ * which is where that work belongs.
+ */
+export async function probeAsync(tools: Tools, path: string): Promise<Track> {
+  const [cmd, ...rest] = tools.ffprobe;
+  const fallback: Track = {
+    path,
+    title: path.split("/").pop() ?? path,
+    artist: "",
+    album: "",
+    duration: 0,
+  };
+  if (!cmd) return fallback;
+
+  return new Promise<Track>((done) => {
+    const child = spawn(
+      cmd,
+      [
+        ...rest,
+        "-v", "quiet", "-print_format", "json",
+        "-show_format", "-show_entries", "format_tags=title,artist,album",
+        path,
+      ],
+      { stdio: ["ignore", "pipe", "ignore"] },
+    );
+    let out = "";
+    // A file that will not answer must not hold a place in the queue for ever.
+    const giveUp = setTimeout(() => child.kill("SIGKILL"), 20_000);
+    giveUp.unref?.();
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      if (out.length < 4 * 1024 * 1024) out += chunk.toString("utf8");
+    });
+    child.on("error", () => {
+      clearTimeout(giveUp);
+      done(fallback);
+    });
+    child.on("close", (code) => {
+      clearTimeout(giveUp);
+      if (code !== 0) return done(fallback);
+      done(readTags(out, fallback));
+    });
+  });
+}
+
+/** The tags out of ffprobe's JSON, or the filename when it said nothing useful. */
+function readTags(stdout: string, fallback: Track): Track {
+  try {
+    const parsed = JSON.parse(stdout) as {
+      format?: { duration?: string; tags?: Record<string, string> };
+    };
+    const tags = parsed.format?.tags ?? {};
+    const lower: Record<string, string> = {};
+    for (const [k, v] of Object.entries(tags)) lower[k.toLowerCase()] = v;
+    return {
+      path: fallback.path,
+      title: lower.title || fallback.title,
+      artist: lower.artist ?? "",
+      album: lower.album ?? "",
+      duration: Number(parsed.format?.duration ?? 0) || 0,
+    };
+  } catch {
+    return fallback;
+  }
+}
+
 /** What is actually inside a container, as opposed to what the name suggests. */
 export interface Codecs {
   /** e.g. "h264", "hevc", "vp9". Empty when there is no video stream. */
@@ -293,7 +369,11 @@ export async function codecsOf(tools: Tools, path: string): Promise<Codecs> {
  * would cost a core per viewer and look worse. So the streams decide, one part
  * at a time -- a film can have its video copied and only its DTS re-encoded.
  */
-export function videoArgs(codecs: Codecs): string[] {
+export function videoArgs(codecs: Codecs, capKbps = 0): string[] {
+  // A ceiling means re-encoding whatever is there, because you cannot cap the
+  // bitrate of a stream you are copying: copying is what "unchanged" means.
+  if (capKbps > 0) return cappedArgs(capKbps);
+
   // What a browser can play inside MP4 without help.
   const keepVideo = codecs.video === "h264";
   const keepAudio = codecs.audio === "aac" || codecs.audio === "mp3";
@@ -309,3 +389,42 @@ export function videoArgs(codecs: Codecs): string[] {
     "-movflags", "frag_keyframe+empty_moov+default_base_moof",
   ];
 }
+
+/**
+ * The width that suits a bitrate.
+ *
+ * 1080p squeezed into a megabit is worse than 360p at the same megabit: the
+ * encoder spends everything it has on detail it cannot afford and the result
+ * smears on every motion. Dropping the resolution with the bitrate is what
+ * makes a small stream watchable rather than merely small.
+ */
+export function widthFor(kbps: number): number {
+  if (kbps <= 800) return 640;
+  if (kbps <= 1800) return 854;
+  if (kbps <= 4000) return 1280;
+  return 1920;
+}
+
+/** Arguments for a stream that has to fit through a link of a known size. */
+function cappedArgs(kbps: number): string[] {
+  const audioKbps = kbps <= 800 ? 96 : 128;
+  const videoKbps = Math.max(200, kbps - audioKbps);
+  return [
+    "-c:v", "libx264",
+    "-preset", "veryfast",
+    "-pix_fmt", "yuv420p",
+    // -2 keeps the aspect ratio and an even height, which H.264 requires.
+    // The min() never enlarges: a 480p source asked for 720p stays 480p.
+    "-vf", `scale='min(${widthFor(kbps)},iw)':-2`,
+    "-b:v", `${videoKbps}k`,
+    // A ceiling rather than an average, because an average that spikes is a
+    // stall on a link this size. The buffer is one second of it.
+    "-maxrate", `${videoKbps}k`,
+    "-bufsize", `${videoKbps}k`,
+    "-c:a", "aac",
+    "-b:a", `${audioKbps}k`,
+    "-ac", "2",
+    "-f", "mp4",
+    "-movflags", "frag_keyframe+empty_moov+default_base_moof",
+  ];
+}