nixamp 0.21.4 → 0.22.0

package/dist/speech.js

@@ -0,0 +1,311 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+/**
+ * Speech to text: a line said into a microphone, heard by nixamp.com.
+ *
+ * The ear is Whisper, run through Transformers.js: an Apache-2.0 library
+ * carrying MIT-licensed models, on this machine's own CPU. Nothing leaves
+ * for a speech vendor, and nothing is billed. The web page, the CLI and the
+ * MCP tools all send the same thing -- a short WAV -- to the same route,
+ * and get words back; the route can also drop those words straight into a
+ * trollbox, which is what dictating a line to a room means.
+ *
+ * The library is an optional dependency on purpose. It is hundreds of
+ * megabytes with the ONNX runtime under it, native per platform, and the
+ * CLI tarball's promise is "pure JavaScript, runs anywhere a Node does".
+ * So a `nixamp serve` on a laptop answers 503 to this, and every client
+ * asks nixamp.com instead -- which is where a trollbox line has to be
+ * signed in anyway.
+ *
+ * A WAV is decoded here rather than by ffmpeg because nixamp.com has no
+ * ffmpeg (see the Dockerfile). Anything else is converted before it is
+ * sent: the browser resamples what it recorded, the CLI runs ffmpeg.
+ */
+import { join } from "node:path";
+import { stateDir } from "./daemon.js";
+/** What Whisper listens at. Everything is brought to this before it is heard. */
+export const RATE = 16_000;
+/** A trollbox line, said out loud, is seconds long; a minute is the ceiling. */
+export const MAX_SECONDS = 60;
+/** A minute of 16-bit mono at 16 kHz is under 2 MB; 48 kHz stereo is under 12. */
+export const MAX_BYTES = 12 * 1024 * 1024;
+/**
+ * How much one account may have heard in a minute, in seconds of sound.
+ * Counted in sound rather than asks because a live channel being captioned
+ * asks twelve times a minute for five seconds each, and a person dictating
+ * asks twice for thirty: the cost is the sound, not the call. Five minutes
+ * of sound a minute is four channels captioned, or a conversation, and
+ * not a firehose.
+ */
+export const SECONDS_PER_MINUTE = 300;
+/** How many may wait for the one CPU. Past this, the honest answer is "later". */
+export const QUEUE_LIMIT = 8;
+export const DEFAULT_MODEL = "onnx-community/whisper-base";
+export class SpeechError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+/** Whether these bytes are a RIFF/WAVE file, whatever the request called them. */
+export function isWav(bytes) {
+    if (bytes.length < 12)
+        return false;
+    const ascii = (at, length) => String.fromCharCode(...bytes.subarray(at, at + length));
+    return ascii(0, 4) === "RIFF" && ascii(8, 4) === "WAVE";
+}
+/**
+ * A WAV file's samples, mixed to mono. PCM of 8, 16, 24 or 32 bits, or
+ * 32-bit float; the WAVE_FORMAT_EXTENSIBLE wrapper around either. That is
+ * what every encoder that matters writes, including the one in the page.
+ */
+export function decodeWav(bytes) {
+    if (!isWav(bytes))
+        throw new SpeechError("send a WAV file", 415);
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    let at = 12;
+    let format = 0;
+    let channels = 0;
+    let rate = 0;
+    let bits = 0;
+    let dataAt = -1;
+    let dataLength = 0;
+    while (at + 8 <= bytes.length) {
+        const id = String.fromCharCode(...bytes.subarray(at, at + 4));
+        const length = view.getUint32(at + 4, true);
+        const body = at + 8;
+        if (id === "fmt " && length >= 16) {
+            format = view.getUint16(body, true);
+            channels = view.getUint16(body + 2, true);
+            rate = view.getUint32(body + 4, true);
+            bits = view.getUint16(body + 14, true);
+            // Extensible: the real format is the first two bytes of the sub-format GUID.
+            if (format === 0xfffe && length >= 26)
+                format = view.getUint16(body + 24, true);
+        }
+        else if (id === "data") {
+            dataAt = body;
+            // A streamed WAV says 0 or 0xFFFFFFFF for a length it did not know yet.
+            dataLength = length === 0 || body + length > bytes.length ? bytes.length - body : length;
+            break;
+        }
+        at = body + length + (length & 1);
+    }
+    if (dataAt < 0 || channels < 1 || rate < 8000 || rate > 192_000)
+        throw new SpeechError("that WAV has no sound in it", 415);
+    const pcm = format === 1 && (bits === 8 || bits === 16 || bits === 24 || bits === 32);
+    const float = format === 3 && bits === 32;
+    if (!pcm && !float)
+        throw new SpeechError(`WAV format ${format} at ${bits} bits is not one this reads: send 16-bit PCM`, 415);
+    const width = bits / 8;
+    const frames = Math.floor(dataLength / (width * channels));
+    const samples = new Float32Array(frames);
+    for (let frame = 0; frame < frames; frame++) {
+        let sum = 0;
+        for (let channel = 0; channel < channels; channel++) {
+            const offset = dataAt + (frame * channels + channel) * width;
+            if (float)
+                sum += view.getFloat32(offset, true);
+            else if (bits === 8)
+                sum += bytes[offset] / 128 - 1;
+            else if (bits === 16)
+                sum += view.getInt16(offset, true) / 32768;
+            else if (bits === 24)
+                sum += ((bytes[offset + 2] << 24) | (bytes[offset + 1] << 16) | (bytes[offset] << 8)) / 2147483648;
+            else
+                sum += view.getInt32(offset, true) / 2147483648;
+        }
+        samples[frame] = sum / channels;
+    }
+    return { rate, channels, samples };
+}
+/**
+ * Samples at one rate, at another. Down is an average over each output
+ * sample's span, which is a crude low-pass and enough for speech; up is a
+ * straight line between neighbours. Whisper resamples nothing itself.
+ */
+export function resample(samples, from, to) {
+    if (from === to || samples.length === 0)
+        return samples;
+    const ratio = from / to;
+    const length = Math.max(1, Math.round(samples.length / ratio));
+    const out = new Float32Array(length);
+    if (ratio > 1) {
+        for (let i = 0; i < length; i++) {
+            const start = Math.floor(i * ratio);
+            const end = Math.min(samples.length, Math.max(start + 1, Math.floor((i + 1) * ratio)));
+            let sum = 0;
+            for (let j = start; j < end; j++)
+                sum += samples[j];
+            out[i] = sum / (end - start);
+        }
+    }
+    else {
+        for (let i = 0; i < length; i++) {
+            const position = i * ratio;
+            const left = Math.floor(position);
+            const right = Math.min(samples.length - 1, left + 1);
+            const mix = position - left;
+            out[i] = samples[left] * (1 - mix) + samples[right] * mix;
+        }
+    }
+    return out;
+}
+/** 16-bit mono PCM WAV bytes from samples: what the CLI's tests, and anybody, can send. */
+export function encodeWav(samples, rate = RATE) {
+    const bytes = new Uint8Array(44 + samples.length * 2);
+    const view = new DataView(bytes.buffer);
+    const ascii = (at, text) => {
+        for (let i = 0; i < text.length; i++)
+            bytes[at + i] = text.charCodeAt(i);
+    };
+    ascii(0, "RIFF");
+    view.setUint32(4, 36 + samples.length * 2, true);
+    ascii(8, "WAVE");
+    ascii(12, "fmt ");
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, 1, true);
+    view.setUint32(24, rate, true);
+    view.setUint32(28, rate * 2, true);
+    view.setUint16(32, 2, true);
+    view.setUint16(34, 16, true);
+    ascii(36, "data");
+    view.setUint32(40, samples.length * 2, true);
+    for (let i = 0; i < samples.length; i++) {
+        const clipped = Math.max(-1, Math.min(1, samples[i]));
+        view.setInt16(44 + i * 2, clipped < 0 ? clipped * 32768 : clipped * 32767, true);
+    }
+    return bytes;
+}
+/** Whisper's own spacing and blank-audio tokens, tidied into a line. */
+export function tidy(text) {
+    return text.replace(/\[[A-Z_ ]+\]|\([A-Za-z ]+\)/g, " ").replace(/\s+/g, " ").trim();
+}
+/** A two-letter language code, or nothing: Whisper guesses when not told. */
+export function languageOf(value) {
+    if (typeof value !== "string")
+        return undefined;
+    const code = value.trim().toLowerCase();
+    return /^[a-z]{2}$/.test(code) ? code : undefined;
+}
+async function loadWhisper(model, cacheDir) {
+    // By name held in a variable: an optional dependency that is not on disk
+    // must fail here, at the first ask, and not when the file is imported.
+    const name = "@huggingface/transformers";
+    let transformers;
+    try {
+        transformers = (await import(__rewriteRelativeImportExtension(name)));
+    }
+    catch {
+        throw new SpeechError("this nixamp cannot hear: @huggingface/transformers is not installed here. nixamp.com can.", 503);
+    }
+    transformers.env.cacheDir = cacheDir;
+    const recognize = await transformers.pipeline("automatic-speech-recognition", model, { dtype: "q8" });
+    return async (pcm, { language }) => {
+        const heard = await recognize(pcm, {
+            // Whisper hears thirty seconds at a time; longer is heard in overlapping pieces.
+            chunk_length_s: 30,
+            stride_length_s: 5,
+            ...(language ? { language, task: "transcribe" } : {}),
+        });
+        return { text: Array.isArray(heard) ? heard.map((piece) => piece.text).join(" ") : heard.text };
+    };
+}
+export class Speech {
+    model;
+    cacheDir;
+    load;
+    now;
+    recognizer = null;
+    /** One at a time: the model is CPU-bound, and two at once is slower than two in turn. */
+    tail = Promise.resolve();
+    waiting = 0;
+    asked = new Map();
+    constructor(options = {}) {
+        this.model = options.model ?? process.env["NIXAMP_STT_MODEL"] ?? DEFAULT_MODEL;
+        this.cacheDir = options.cacheDir ?? process.env["NIXAMP_STT_CACHE"] ?? join(stateDir(), "models");
+        this.load = options.load ?? loadWhisper;
+        this.now = options.now ?? (() => Date.now());
+    }
+    ear() {
+        this.recognizer ??= this.load(this.model, this.cacheDir).catch((error) => {
+            // A failed load is tried again next time, not remembered forever.
+            this.recognizer = null;
+            throw error;
+        });
+        return this.recognizer;
+    }
+    /**
+     * Load the model now, so the first person to speak is not the one who
+     * waits for the download. Says whether it could; never throws.
+     */
+    async warm() {
+        try {
+            await this.ear();
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Whether this account may have this much heard now, and the bookkeeping if so. */
+    allow(accountId, seconds) {
+        const minute = Math.floor(this.now() / 60_000);
+        const record = this.asked.get(accountId) ?? { minute, seconds: 0 };
+        if (record.minute !== minute) {
+            record.minute = minute;
+            record.seconds = 0;
+        }
+        if (record.seconds + seconds > SECONDS_PER_MINUTE) {
+            throw new SpeechError(`${SECONDS_PER_MINUTE} seconds of sound a minute is plenty; try again in a moment`, 429);
+        }
+        record.seconds += seconds;
+        this.asked.set(accountId, record);
+        if (this.asked.size > 5000) {
+            for (const [id, one] of this.asked)
+                if (one.minute !== minute)
+                    this.asked.delete(id);
+        }
+    }
+    /**
+     * The words in a WAV. Refuses what is not a WAV, or is too long, or more
+     * than the account may have heard this minute, with a status.
+     */
+    async transcribe(bytes, options = {}) {
+        if (bytes.length > MAX_BYTES)
+            throw new SpeechError(`that is too much sound: ${MAX_SECONDS} seconds at most`, 413);
+        const wav = decodeWav(bytes);
+        const seconds = wav.samples.length / wav.rate;
+        if (seconds > MAX_SECONDS)
+            throw new SpeechError(`that is ${Math.round(seconds)} seconds; ${MAX_SECONDS} at most`, 413);
+        if (options.by)
+            this.allow(options.by, seconds);
+        if (wav.samples.length < wav.rate / 10)
+            return { text: "", seconds };
+        const pcm = resample(wav.samples, wav.rate, RATE);
+        if (this.waiting >= QUEUE_LIMIT)
+            throw new SpeechError("too many people are talking at once; try again in a moment", 503);
+        this.waiting += 1;
+        const turn = this.tail.then(async () => {
+            const recognize = await this.ear();
+            return recognize(pcm, options.language ? { language: options.language } : {});
+        });
+        // The queue moves on whether or not this one was heard.
+        this.tail = turn.catch(() => undefined);
+        try {
+            const heard = await turn;
+            return { text: tidy(heard.text), seconds };
+        }
+        finally {
+            this.waiting -= 1;
+        }
+    }
+}

package/dist/transcribe.d.ts

@@ -0,0 +1,43 @@
+import { type Tools } from "./audio.ts";
+import { type Session } from "./session.ts";
+/** Where the sound may be sent, as a request. */
+export interface Ask {
+    wav: Uint8Array;
+    language?: string;
+    /** A room to post the words to: the server's address, and its channel. */
+    server?: string;
+    channel?: string;
+}
+export interface Heard {
+    text: string;
+    seconds: number;
+    model?: string;
+    /** The trollbox line, when a room was named. */
+    message?: {
+        id: string;
+        handle: string;
+        body: string;
+        createdAt: string;
+    };
+}
+export type Answer = {
+    ok: true;
+    heard: Heard;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/**
+ * The file as a WAV: as it is when it already is one, through ffmpeg to
+ * 16 kHz mono otherwise. Throws a sentence when neither is possible.
+ */
+export declare function wavOf(path: string, tools?: () => Pick<Tools, "ffmpeg" | "carries">): Uint8Array;
+/** The ask, made: one POST to the site the session belongs to. */
+export declare function askToHear(session: Pick<Session, "site" | "token">, ask: Ask, fetcher?: typeof fetch, site?: string): Promise<Answer>;
+export interface TranscribeDeps {
+    fetcher?: typeof fetch;
+    wavOf?: typeof wavOf;
+    session?: Pick<Session, "site" | "token"> | null;
+}
+export declare function transcribe(argv: string[], deps?: TranscribeDeps): Promise<number>;

package/dist/transcribe.js

@@ -0,0 +1,155 @@
+/**
+ * `nixamp transcribe` -- a recording in, the words out, and into a room.
+ *
+ * The ear is nixamp.com's (see speech.ts): this machine sends a WAV and
+ * gets text back, signed in as whoever it is signed in as. Anything that
+ * is not already a WAV goes through the ffmpeg nixamp plays with, to 16 kHz
+ * mono, which is what the ear listens at and the smallest thing to send.
+ *
+ * With `--say SERVER`, the words are posted to that server's trollbox as
+ * this account, by the same rules as typing them: one line a second, and
+ * signed with the public handle. The MCP tool of the same name is this
+ * function with a different front.
+ */
+import { spawnSync } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { detectTools } from "./audio.js";
+import { readSession } from "./session.js";
+import { RATE, isWav } from "./speech.js";
+const HELP = `nixamp transcribe — say it, and have it written down.
+
+  nixamp transcribe FILE                  the words in a recording
+  nixamp transcribe FILE --say SERVER     and post them to that server's trollbox
+  nixamp transcribe FILE --say SERVER --channel ID   to one channel's room (default: live)
+  nixamp transcribe FILE --language de    when Whisper should not guess
+  nixamp transcribe FILE --json           the answer as JSON
+
+FILE is any recording ffmpeg can read; a WAV needs no ffmpeg at all. The
+hearing is done by nixamp.com with an open-source model on its own CPU, so
+this needs a sign-in (\`nixamp login\`) and nothing else. Up to a minute at
+a time.
+
+SERVER is the address of the nixamp whose room it is, as in its share link:
+https://server1.chovy.nixamp.com:4321. The room is that server's own stream
+unless --channel names one of its channels.
+`;
+/**
+ * The file as a WAV: as it is when it already is one, through ffmpeg to
+ * 16 kHz mono otherwise. Throws a sentence when neither is possible.
+ */
+export function wavOf(path, tools = detectTools) {
+    let bytes;
+    try {
+        bytes = new Uint8Array(readFileSync(path));
+    }
+    catch {
+        throw new Error(`cannot read ${path}`);
+    }
+    if (isWav(bytes))
+        return bytes;
+    const found = tools();
+    if (found.carries === false)
+        throw new Error(`${path} is not a WAV, and there is no ffmpeg here to convert it. Install ffmpeg, or record a WAV.`);
+    const [command, ...prefix] = found.ffmpeg;
+    const run = spawnSync(command, [...prefix, "-v", "error", "-i", path, "-vn", "-ac", "1", "-ar", String(RATE), "-f", "wav", "-"], {
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (run.error || run.status !== 0 || !run.stdout || run.stdout.length < 44) {
+        const why = run.stderr ? run.stderr.toString("utf8").trim().split("\n").pop() : run.error?.message;
+        throw new Error(`ffmpeg could not read ${path}${why ? `: ${why}` : ""}`);
+    }
+    return new Uint8Array(run.stdout);
+}
+/** The ask, made: one POST to the site the session belongs to. */
+export async function askToHear(session, ask, fetcher = fetch, site = session.site) {
+    const url = new URL(`${site.replace(/\/+$/, "")}/api/v1/speech/transcribe`);
+    if (ask.language)
+        url.searchParams.set("language", ask.language);
+    if (ask.server) {
+        url.searchParams.set("server", ask.server);
+        url.searchParams.set("channel", ask.channel || "live");
+    }
+    let response;
+    try {
+        response = await fetcher(url.toString(), {
+            method: "POST",
+            headers: { authorization: `Bearer ${session.token}`, "content-type": "audio/wav" },
+            body: new Blob([ask.wav.buffer.slice(ask.wav.byteOffset, ask.wav.byteOffset + ask.wav.byteLength)]),
+        });
+    }
+    catch (error) {
+        return { ok: false, status: 0, error: `could not reach ${url.origin}: ${error.message}` };
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        return { ok: false, status: response.status, error: body.error ?? `nixamp answered ${response.status}` };
+    return {
+        ok: true,
+        heard: {
+            text: body.text ?? "",
+            seconds: body.seconds ?? 0,
+            ...(body.model ? { model: body.model } : {}),
+            ...(body.message ? { message: body.message } : {}),
+        },
+    };
+}
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+export async function transcribe(argv, deps = {}) {
+    if (argv.length === 0 || argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+        console.log(HELP);
+        return argv.length === 0 ? 64 : 0;
+    }
+    const session = deps.session === undefined ? readSession() : deps.session;
+    if (session === null) {
+        console.error("nixamp: not signed in. Try `nixamp login`.");
+        return 1;
+    }
+    const withValue = new Set(["--say", "--channel", "--language", "--site"]);
+    const file = argv.find((one, at) => !one.startsWith("-") && !(at > 0 && withValue.has(argv[at - 1])));
+    if (!file) {
+        console.error("nixamp: which recording? `nixamp transcribe clip.m4a`.");
+        return 64;
+    }
+    const server = flag(argv, "--say");
+    if (argv.includes("--say") && !server) {
+        console.error("nixamp: --say needs the server's address, as in its share link.");
+        return 64;
+    }
+    let wav;
+    try {
+        wav = (deps.wavOf ?? wavOf)(file);
+    }
+    catch (error) {
+        console.error(`nixamp: ${error.message}`);
+        return 1;
+    }
+    const ask = {
+        wav,
+        ...(flag(argv, "--language") ? { language: flag(argv, "--language") } : {}),
+        ...(server ? { server, channel: flag(argv, "--channel") ?? "live" } : {}),
+    };
+    const answer = await askToHear(session, ask, deps.fetcher ?? fetch, flag(argv, "--site") ?? session.site);
+    if (!answer.ok) {
+        console.error(`nixamp: ${answer.error}`);
+        return 1;
+    }
+    if (argv.includes("--json")) {
+        console.log(JSON.stringify(answer.heard, null, 2));
+        return 0;
+    }
+    if (answer.heard.text === "") {
+        console.error("nixamp: heard nothing in that.");
+        return 1;
+    }
+    console.log(answer.heard.text);
+    if (answer.heard.message) {
+        console.error(`  Said in the room for ${ask.channel} at ${server} as ${answer.heard.message.handle}.`);
+    }
+    else if (server) {
+        console.error("  Nothing was posted: there were no words to post.");
+    }
+    return 0;
+}

package/dist/transcript.d.ts

@@ -0,0 +1,40 @@
+export interface TranscriptLine {
+    channel: string;
+    at: number;
+    until: number;
+    text: string;
+}
+export interface TranscriptAnswer {
+    channel: string;
+    backlog: number;
+    now: number;
+    on: boolean;
+    lines: number;
+    error: string;
+    /** The recent lines, oldest first. Named `lines` on the wire; renamed here so the count above keeps its name. */
+    recent: TranscriptLine[];
+}
+export type Fetched = {
+    ok: true;
+    answer: TranscriptAnswer;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** One ask for a channel's recent lines, after a moment when given. */
+export declare function readTranscript(target: {
+    url: string;
+    key: string | null;
+}, channel: string, after?: number, fetcher?: typeof fetch): Promise<Fetched>;
+/** A line as the terminal prints it: the time its sound was heard, then the words. */
+export declare function printed(line: TranscriptLine): string;
+export interface TranscriptDeps {
+    fetcher?: typeof fetch;
+    /** How long --follow waits between asks. Short in the tests. */
+    everyMs?: number;
+    /** How many asks --follow makes before it stops. Forever, except in the tests. */
+    polls?: number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export declare function transcript(argv: string[], deps?: TranscriptDeps): Promise<number>;

package/dist/transcript.js

@@ -0,0 +1,120 @@
+/**
+ * `nixamp transcript` -- what a channel is saying, in the terminal.
+ *
+ * The server carrying the channel captions it (see captions.ts) and keeps
+ * the recent lines; this asks for them, and with --follow keeps asking, a
+ * poll every few seconds with the last line's time so nothing is printed
+ * twice. A poll rather than the SSE the page uses because each ask also
+ * keeps the captioner alive, which is what a terminal that is still
+ * reading wants, and there is nothing to parse.
+ *
+ * Pointed at a server the way `nixamp admin` is: --url and --key from its
+ * share link, or the daemon on this machine when neither is given.
+ */
+import { resolveTarget } from "./admin.js";
+import { KEY_HEADER } from "./share.js";
+const HELP = `nixamp transcript — what a channel is saying, written down.
+
+  nixamp transcript --channel ID                 the recent lines from this machine's daemon
+  nixamp transcript --url URL --key K --channel ID   from another server, with its share link
+  nixamp transcript ... --follow                 and keep printing as it speaks
+  nixamp transcript ... --json                   the lines as JSON
+
+ID is the channel's id as the server names it (the address bar says it when
+you are watching one). The server captions a channel while somebody is asking
+for the transcript, with nixamp.com's ear; it needs an ffmpeg and a sign-in
+(\`nixamp login\`) on that server.
+`;
+/** One ask for a channel's recent lines, after a moment when given. */
+export async function readTranscript(target, channel, after = 0, fetcher = fetch) {
+    const url = new URL(`${target.url.replace(/\/+$/, "")}/api/channels/${encodeURIComponent(channel)}/transcript`);
+    if (after > 0)
+        url.searchParams.set("after", String(after));
+    let response;
+    try {
+        response = await fetcher(url.toString(), { headers: target.key ? { [KEY_HEADER]: target.key } : {} });
+    }
+    catch (error) {
+        return { ok: false, status: 0, error: `could not reach ${url.origin}: ${error.message}` };
+    }
+    const body = (await response.json().catch(() => ({})));
+    if (!response.ok)
+        return { ok: false, status: response.status, error: body.error ?? `the server answered ${response.status}` };
+    const recent = Array.isArray(body.lines) ? body.lines : [];
+    return {
+        ok: true,
+        answer: {
+            channel: body.channel ?? channel,
+            backlog: body.backlog ?? 0,
+            now: body.now ?? Date.now(),
+            on: body.on ?? false,
+            lines: recent.length,
+            error: body.error ?? "",
+            recent,
+        },
+    };
+}
+/** A line as the terminal prints it: the time its sound was heard, then the words. */
+export function printed(line) {
+    const at = new Date(line.at);
+    const clock = Number.isNaN(at.getTime()) ? "--:--:--" : at.toLocaleTimeString([], { hour: "2-digit", minute: "2-digit", second: "2-digit" });
+    return `${clock}  ${line.text}`;
+}
+function flag(argv, name) {
+    const at = argv.indexOf(name);
+    return at === -1 ? undefined : argv[at + 1];
+}
+export async function transcript(argv, deps = {}) {
+    if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
+        console.log(HELP);
+        return 0;
+    }
+    let target;
+    try {
+        target = resolveTarget(argv);
+    }
+    catch (error) {
+        console.error(error.message);
+        return 1;
+    }
+    const channel = flag(argv, "--channel") ?? "main";
+    const follow = argv.includes("--follow") || argv.includes("-f");
+    const asJson = argv.includes("--json");
+    const fetcher = deps.fetcher ?? fetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let after = 0;
+    let polls = 0;
+    for (;;) {
+        const got = await readTranscript(target, channel, after, fetcher);
+        if (!got.ok) {
+            console.error(`nixamp: ${got.error}`);
+            return 1;
+        }
+        if (asJson) {
+            console.log(JSON.stringify(got.answer.recent, null, 2));
+            if (!follow)
+                return 0;
+        }
+        else {
+            if (after === 0 && got.answer.recent.length === 0 && !follow) {
+                console.log(got.answer.error
+                    ? `Nothing yet: ${got.answer.error}`
+                    : "Nothing said yet. The server has just started listening; ask again in a few seconds, or --follow.");
+                return 0;
+            }
+            for (const line of got.answer.recent)
+                console.log(printed(line));
+            if (!follow)
+                return 0;
+            if (after === 0 && got.answer.error)
+                console.error(`nixamp: ${got.answer.error}`);
+        }
+        const last = got.answer.recent[got.answer.recent.length - 1];
+        if (last)
+            after = last.at;
+        polls += 1;
+        if (deps.polls !== undefined && polls >= deps.polls)
+            return 0;
+        await sleep(deps.everyMs ?? 5000);
+    }
+}