nixamp 0.23.7 → 0.24.0

package/dist/transcribe.d.ts

@@ -1,9 +1,14 @@
 import { type Tools } from "./audio.ts";
 import { type Session } from "./session.ts";
+import { type Segment } from "./speech.ts";
+import { type Got, type StoredTranscript } from "./transcript-client.ts";
+import { stamp, type TranscriptLine } from "./transcripts.ts";
 /** Where the sound may be sent, as a request. */
 export interface Ask {
     wav: Uint8Array;
     language?: string;
+    /** The pieces with their timing too. */
+    timestamps?: boolean;
     /** A room to post the words to: the server's address, and its channel. */
     server?: string;
     channel?: string;
@@ -12,6 +17,8 @@ export interface Heard {
     text: string;
     seconds: number;
     model?: string;
+    language?: string;
+    segments?: Segment[];
     /** The trollbox line, when a room was named. */
     message?: {
         id: string;
@@ -28,16 +35,79 @@ export type Answer = {
     status: number;
     error: string;
 };
+/** A minute of sound at a time: the most the ear takes in one ask. */
+export declare const WINDOW_SECONDS = 60;
+/** Heard lines go to the store this often, so a run that dies keeps most of what it heard. */
+export declare const KEEP_EVERY = 20;
 /**
  * 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;
+/** A window of sound: where it begins in the media, and 16-bit mono PCM at RATE. */
+export interface Window {
+    offset: number;
+    pcm: Buffer;
+}
+/**
+ * The whole of a file or a link as windows of PCM, through ffmpeg, as it
+ * decodes: a film is hours of sound and is never held at once.
+ */
+export declare function windowsOf(source: string, tools?: () => Pick<Tools, "ffmpeg" | "carries">, seconds?: number): AsyncGenerator<Window>;
 /** 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 WholeHeard {
+    lines: TranscriptLine[];
+    language: string;
+    model: string;
+    /** How far the sound went, seconds. */
+    seconds: number;
+}
+export interface WholeDeps {
+    fetcher?: typeof fetch;
+    windows?: (source: string) => AsyncIterable<Window>;
+    sleep?: (ms: number) => Promise<void>;
+    onProgress?: (line: string) => void;
+}
+/** m:ss, or h:mm:ss, for a progress line. */
+export declare function clock(seconds: number): string;
+/**
+ * The whole of some media, heard a window at a time and kept as it goes.
+ * The ear's throttle is so many seconds of sound a minute; a 429 is a
+ * wait, not a failure. Quiet windows are skipped without an ask.
+ */
+export declare function hearWhole(session: Pick<Session, "site" | "token">, source: string, media: string, options?: {
+    language?: string;
+    title?: string;
+}, deps?: WholeDeps): Promise<{
+    ok: true;
+    heard: WholeHeard;
+} | {
+    ok: false;
+    error: string;
+}>;
+/** A kept transcript in a language, waiting while nixamp.com translates it. */
+export declare function awaitTranscript(session: Pick<Session, "site" | "token">, id: string, language: string, deps?: {
+    fetcher?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    onProgress?: (line: string) => void;
+    polls?: number;
+}): Promise<Got<StoredTranscript>>;
+/** A line as the terminal prints it: seconds into the media, then the words. */
+export declare function printedLine(line: TranscriptLine): string;
 export interface TranscribeDeps {
     fetcher?: typeof fetch;
     wavOf?: typeof wavOf;
     session?: Pick<Session, "site" | "token"> | null;
+    /** The whole of a file as windows; the tests hand in a fake. */
+    windows?: (source: string) => AsyncIterable<Window>;
+    /** A file's identity; the tests hand in a fake. */
+    fingerprint?: (path: string) => string;
+    sleep?: (ms: number) => Promise<void>;
+    /** How many times a translation is asked about before giving up; forever, except in the tests. */
+    polls?: number;
 }
+/** A transcript's lines as one of the formats, for stdout or a file. */
+export declare function rendered(lines: TranscriptLine[], format: "srt" | "vtt" | "txt" | "lines"): string;
 export declare function transcribe(argv: string[], deps?: TranscribeDeps): Promise<number>;
+export { stamp };

package/dist/transcribe.js

@@ -1,38 +1,60 @@
 /**
- * `nixamp transcribe` -- a recording in, the words out, and into a room.
+ * `nixamp transcribe` -- a recording in, the words out, kept, 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.
+ * The ear is nixamp.com's (see speech.ts): this machine sends WAVs 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.
+ *
+ * A short clip is one ask. A whole film is the same ask a hundred times, a
+ * minute of sound each, with the pieces' timing asked for, and what comes
+ * back is kept on nixamp.com under the file's fingerprint (see
+ * transcripts.ts): the next `nixamp transcribe` of the same file, on any
+ * machine, and the next server to put it on the air, read the lines
+ * instead of hearing them. Ask for another language and nixamp.com
+ * translates the kept lines once, and keeps that too.
  *
  * 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 { spawn, spawnSync } from "node:child_process";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, extname, join } from "node:path";
 import { detectTools } from "./audio.js";
+import { isQuiet } from "./captions.js";
 import { readSession } from "./session.js";
-import { RATE, isWav } from "./speech.js";
+import { MAX_SECONDS, RATE, isWav } from "./speech.js";
+import { fetchTranscript, keepLines } from "./transcript-client.js";
+import { fileFingerprint, languageCode, mediaOfUrl, stamp, toSrt, toText, toVtt, transcriptIdOf } from "./transcripts.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                  the words in a recording, or a whole film, kept on nixamp.com
+  nixamp transcribe URL                   the same for a link ffmpeg can read
+  nixamp transcribe FILE --language sv    when Whisper should not guess
+  nixamp transcribe FILE --translate de   and in German too (de,sv for both)
+  nixamp transcribe FILE --srt | --vtt    as subtitles, on stdout
+  nixamp transcribe FILE --out DIR        subtitle files in DIR, one per language
+  nixamp transcribe FILE --fresh          hear it again even though it is kept
   nixamp transcribe FILE --json           the answer as JSON
+  nixamp transcribe CLIP --say SERVER     a short clip, posted to that server's trollbox
+  nixamp transcribe CLIP --say SERVER --channel ID   to one channel's room (default: live)
 
-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.
+FILE is any recording ffmpeg can read; a WAV under a minute 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. A film
+is heard a minute at a time and kept as it goes; the next ask for the same
+file, from anywhere, reads what was kept.
 
 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.
 `;
+/** A minute of sound at a time: the most the ear takes in one ask. */
+export const WINDOW_SECONDS = MAX_SECONDS;
+/** Heard lines go to the store this often, so a run that dies keeps most of what it heard. */
+export const KEEP_EVERY = 20;
 /**
  * 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.
@@ -60,11 +82,58 @@ export function wavOf(path, tools = detectTools) {
     }
     return new Uint8Array(run.stdout);
 }
+/**
+ * The whole of a file or a link as windows of PCM, through ffmpeg, as it
+ * decodes: a film is hours of sound and is never held at once.
+ */
+export async function* windowsOf(source, tools = detectTools, seconds = WINDOW_SECONDS) {
+    const found = tools();
+    if (found.carries === false)
+        throw new Error(`there is no ffmpeg here to read ${source}. Install ffmpeg.`);
+    const [command, ...prefix] = found.ffmpeg;
+    const child = spawn(command, [...prefix, "-v", "error", "-nostats", "-i", source, "-vn", "-ac", "1", "-ar", String(RATE), "-f", "s16le", "pipe:1"], {
+        stdio: ["ignore", "pipe", "pipe"],
+    });
+    let complaint = "";
+    child.stderr.on("data", (chunk) => {
+        complaint = `${complaint}${chunk.toString("utf8")}`.slice(-2000);
+    });
+    const size = seconds * RATE * 2;
+    let pending = [];
+    let pendingBytes = 0;
+    let offset = 0;
+    for await (const chunk of child.stdout) {
+        pending.push(chunk);
+        pendingBytes += chunk.length;
+        while (pendingBytes >= size) {
+            const all = Buffer.concat(pending);
+            yield { offset, pcm: Buffer.from(all.subarray(0, size)) };
+            offset += seconds;
+            const rest = all.subarray(size);
+            pending = rest.length > 0 ? [Buffer.from(rest)] : [];
+            pendingBytes = rest.length;
+        }
+    }
+    // The tail: anything longer than half a second is worth hearing.
+    if (pendingBytes >= RATE)
+        yield { offset, pcm: Buffer.concat(pending) };
+    const status = await new Promise((done) => {
+        if (child.exitCode !== null)
+            done(child.exitCode);
+        else
+            child.on("close", (code) => done(code));
+    });
+    if (status !== 0 && offset === 0 && pendingBytes < RATE) {
+        throw new Error(`ffmpeg could not read ${source}${complaint ? `: ${complaint.trim().split("\n").pop()}` : ""}`);
+    }
+}
 /** 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.timestamps)
+        url.searchParams.set("timestamps", "1");
     if (ask.server) {
         url.searchParams.set("server", ask.server);
         url.searchParams.set("channel", ask.channel || "live");
@@ -89,14 +158,148 @@ export async function askToHear(session, ask, fetcher = fetch, site = session.si
             text: body.text ?? "",
             seconds: body.seconds ?? 0,
             ...(body.model ? { model: body.model } : {}),
+            ...(body.language ? { language: body.language } : {}),
+            ...(body.segments ? { segments: body.segments } : {}),
             ...(body.message ? { message: body.message } : {}),
         },
     };
 }
+/** A WAV around 16-bit mono PCM at RATE, for one window. */
+function wavOfPcm(pcm) {
+    const header = Buffer.alloc(44);
+    header.write("RIFF", 0, "ascii");
+    header.writeUInt32LE(36 + pcm.length, 4);
+    header.write("WAVE", 8, "ascii");
+    header.write("fmt ", 12, "ascii");
+    header.writeUInt32LE(16, 16);
+    header.writeUInt16LE(1, 20);
+    header.writeUInt16LE(1, 22);
+    header.writeUInt32LE(RATE, 24);
+    header.writeUInt32LE(RATE * 2, 28);
+    header.writeUInt16LE(2, 32);
+    header.writeUInt16LE(16, 34);
+    header.write("data", 36, "ascii");
+    header.writeUInt32LE(pcm.length, 40);
+    return new Uint8Array(Buffer.concat([header, pcm]));
+}
+/** m:ss, or h:mm:ss, for a progress line. */
+export function clock(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    const h = Math.floor(whole / 3600);
+    const m = Math.floor((whole % 3600) / 60);
+    const s = whole % 60;
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}` : `${m}:${String(s).padStart(2, "0")}`;
+}
+/**
+ * The whole of some media, heard a window at a time and kept as it goes.
+ * The ear's throttle is so many seconds of sound a minute; a 429 is a
+ * wait, not a failure. Quiet windows are skipped without an ask.
+ */
+export async function hearWhole(session, source, media, options = {}, deps = {}) {
+    const fetcher = deps.fetcher ?? fetch;
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const windows = deps.windows ?? ((path) => windowsOf(path));
+    const id = transcriptIdOf(media);
+    const lines = [];
+    let unsaved = [];
+    let language = options.language ?? "";
+    let model = "";
+    let seconds = 0;
+    let sinceKept = 0;
+    const keep = async (complete) => {
+        const batch = complete ? lines : unsaved;
+        if (batch.length === 0 && !complete)
+            return null;
+        const got = await keepLines(session, id, {
+            media, language, ...(model ? { model } : {}), ...(options.title ? { title: options.title } : {}), lines: batch, ...(complete ? { complete: true } : {}),
+        }, fetcher);
+        unsaved = [];
+        sinceKept = 0;
+        return got.ok ? null : got.error;
+    };
+    try {
+        for await (const window of windows(source)) {
+            seconds = window.offset + window.pcm.length / (RATE * 2);
+            if (isQuiet(window.pcm))
+                continue;
+            const wav = wavOfPcm(window.pcm);
+            let answer = { ok: false, status: 0, error: "not asked" };
+            for (let attempt = 0; attempt < 40; attempt++) {
+                answer = await askToHear(session, { wav, timestamps: true, ...(language ? { language } : {}) }, fetcher);
+                if (answer.ok || answer.status !== 429)
+                    break;
+                deps.onProgress?.(`  ${clock(window.offset)}: the ear is busy; waiting`);
+                await sleep(10_000);
+            }
+            if (!answer.ok)
+                return { ok: false, error: `at ${clock(window.offset)}: ${answer.error}` };
+            if (answer.heard.language && language === "")
+                language = answer.heard.language;
+            if (answer.heard.model)
+                model = answer.heard.model;
+            const pieces = answer.heard.segments && answer.heard.segments.length > 0
+                ? answer.heard.segments
+                : answer.heard.text ? [{ start: 0, end: window.pcm.length / (RATE * 2), text: answer.heard.text }] : [];
+            for (const piece of pieces) {
+                const line = { start: round(window.offset + piece.start), end: round(window.offset + piece.end), text: piece.text };
+                lines.push(line);
+                unsaved.push(line);
+            }
+            deps.onProgress?.(`  ${clock(seconds)} heard${language ? ` (${language})` : ""}: ${lines.length} lines`);
+            sinceKept += 1;
+            if (sinceKept >= KEEP_EVERY) {
+                const failed = await keep(false);
+                if (failed)
+                    deps.onProgress?.(`  the store did not keep the lines so far: ${failed}`);
+            }
+        }
+    }
+    catch (error) {
+        return { ok: false, error: error.message };
+    }
+    const failed = await keep(true);
+    if (failed)
+        return { ok: false, error: `heard it all, but nixamp.com would not keep it: ${failed}` };
+    return { ok: true, heard: { lines, language, model, seconds } };
+}
+function round(seconds) {
+    return Math.round(seconds * 1000) / 1000;
+}
+/** A kept transcript in a language, waiting while nixamp.com translates it. */
+export async function awaitTranscript(session, id, language, deps = {}) {
+    const sleep = deps.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    let last = -1;
+    for (let poll = 0;; poll++) {
+        const got = await fetchTranscript(session, id, language, deps.fetcher ?? fetch);
+        if (!got.ok || !got.body.translating)
+            return got;
+        const { done, total } = got.body.translating;
+        if (done !== last)
+            deps.onProgress?.(`  translating to ${language}: ${done} of ${total} lines`);
+        last = done;
+        if (deps.polls !== undefined && poll + 1 >= deps.polls)
+            return got;
+        await sleep(3000);
+    }
+}
+/** A line as the terminal prints it: seconds into the media, then the words. */
+export function printedLine(line) {
+    return `${clock(line.start).padStart(7)}  ${line.text}`;
+}
 function flag(argv, name) {
     const at = argv.indexOf(name);
     return at === -1 ? undefined : argv[at + 1];
 }
+/** A transcript's lines as one of the formats, for stdout or a file. */
+export function rendered(lines, format) {
+    if (format === "srt")
+        return toSrt(lines);
+    if (format === "vtt")
+        return toVtt(lines);
+    if (format === "txt")
+        return toText(lines);
+    return lines.map(printedLine).join("\n");
+}
 export async function transcribe(argv, deps = {}) {
     if (argv.length === 0 || argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
         console.log(HELP);
@@ -107,7 +310,7 @@ export async function transcribe(argv, deps = {}) {
         console.error("nixamp: not signed in. Try `nixamp login`.");
         return 1;
     }
-    const withValue = new Set(["--say", "--channel", "--language", "--site"]);
+    const withValue = new Set(["--say", "--channel", "--language", "--site", "--translate", "--out"]);
     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`.");
@@ -118,38 +321,131 @@ export async function transcribe(argv, deps = {}) {
         console.error("nixamp: --say needs the server's address, as in its share link.");
         return 64;
     }
-    let wav;
+    const language = languageCode(flag(argv, "--language")) || undefined;
+    if (argv.includes("--language") && !language) {
+        console.error("nixamp: --language is a two-letter code, such as sv.");
+        return 64;
+    }
+    const site = flag(argv, "--site") ?? session.site;
+    const signed = { site, token: session.token };
+    const fetcher = deps.fetcher ?? fetch;
+    const asJson = argv.includes("--json");
+    const format = argv.includes("--srt") ? "srt" : argv.includes("--vtt") ? "vtt" : argv.includes("--txt") ? "txt" : "lines";
+    // A clip for a room: one ask, the words into the trollbox, as before.
+    if (server) {
+        let wav;
+        try {
+            wav = (deps.wavOf ?? wavOf)(file);
+        }
+        catch (error) {
+            console.error(`nixamp: ${error.message}`);
+            return 1;
+        }
+        const answer = await askToHear(signed, { wav, ...(language ? { language } : {}), server, channel: flag(argv, "--channel") ?? "live" }, fetcher);
+        if (!answer.ok) {
+            console.error(`nixamp: ${answer.error}`);
+            return 1;
+        }
+        if (asJson) {
+            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 ${flag(argv, "--channel") ?? "live"} at ${server} as ${answer.heard.message.handle}.`);
+        else
+            console.error("  Nothing was posted: there were no words to post.");
+        return 0;
+    }
+    // The whole thing, kept under what it is.
+    let media;
     try {
-        wav = (deps.wavOf ?? wavOf)(file);
+        media = /^https?:\/\//.test(file) ? mediaOfUrl(file) : (deps.fingerprint ?? fileFingerprint)(file);
     }
-    catch (error) {
-        console.error(`nixamp: ${error.message}`);
+    catch {
+        console.error(`nixamp: cannot read ${file}`);
         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;
+    const id = transcriptIdOf(media);
+    const title = /^https?:\/\//.test(file) ? file : basename(file, extname(file));
+    const wanted = (flag(argv, "--translate") ?? "").split(",").map((one) => languageCode(one)).filter((one) => typeof one === "string" && one !== "");
+    if (argv.includes("--translate") && wanted.length === 0) {
+        console.error("nixamp: --translate is one or more two-letter codes, such as de,sv.");
+        return 64;
     }
-    if (argv.includes("--json")) {
-        console.log(JSON.stringify(answer.heard, null, 2));
-        return 0;
+    const progress = (line) => console.error(line);
+    let original = null;
+    if (!argv.includes("--fresh")) {
+        const kept = await fetchTranscript(signed, id, "", fetcher);
+        if (kept.ok && kept.body.complete) {
+            original = kept.body;
+            progress(`  Already written down (${original.lines.length} lines${original.language ? `, ${original.language}` : ""}); --fresh hears it again.`);
+        }
+        else if (!kept.ok && kept.status !== 404) {
+            console.error(`nixamp: ${kept.error}`);
+            return 1;
+        }
     }
-    if (answer.heard.text === "") {
-        console.error("nixamp: heard nothing in that.");
-        return 1;
+    if (!original) {
+        progress(`  Hearing ${title}, a minute at a time...`);
+        const heard = await hearWhole(signed, file, media, { ...(language ? { language } : {}), title }, {
+            fetcher, onProgress: progress, ...(deps.windows ? { windows: deps.windows } : {}), ...(deps.sleep ? { sleep: deps.sleep } : {}),
+        });
+        if (!heard.ok) {
+            console.error(`nixamp: ${heard.error}`);
+            return 1;
+        }
+        if (heard.heard.lines.length === 0) {
+            console.error("nixamp: heard nothing in that.");
+            return 1;
+        }
+        const kept = await fetchTranscript(signed, id, "", fetcher);
+        original = kept.ok ? kept.body : {
+            id, media, kind: "file", language: heard.heard.language, translatedFrom: null, model: heard.heard.model, complete: true, title,
+            seconds: heard.heard.seconds, updatedAt: "", lines: heard.heard.lines, languages: [],
+        };
+        progress(`  Kept on nixamp.com as ${id.slice(0, 12)}: ${original.lines.length} lines${original.language ? ` of ${original.language}` : ""}.`);
     }
-    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}.`);
+    const versions = [original];
+    for (const to of wanted) {
+        if (to === original.language)
+            continue;
+        const got = await awaitTranscript(signed, id, to, { fetcher, onProgress: progress, ...(deps.sleep ? { sleep: deps.sleep } : {}), ...(deps.polls !== undefined ? { polls: deps.polls } : {}) });
+        if (!got.ok) {
+            console.error(`nixamp: could not get it in ${to}: ${got.error}`);
+            return 1;
+        }
+        if (got.body.translating) {
+            console.error(`nixamp: ${to} is still being translated (${got.body.translating.done} of ${got.body.translating.total}); ask again in a moment.`);
+            return 1;
+        }
+        versions.push(got.body);
     }
-    else if (server) {
-        console.error("  Nothing was posted: there were no words to post.");
+    const out = flag(argv, "--out");
+    if (out) {
+        mkdirSync(out, { recursive: true });
+        const stem = title.replace(/[^\w.-]+/g, "_").slice(0, 80) || "transcript";
+        const extension = format === "lines" ? "txt" : format;
+        for (const version of versions) {
+            const path = join(out, `${stem}${version.language ? `.${version.language}` : ""}.${asJson ? "json" : extension}`);
+            writeFileSync(path, asJson ? JSON.stringify(version, null, 2) : rendered(version.lines, format === "lines" ? "txt" : format));
+            console.log(path);
+        }
+        return 0;
     }
+    if (asJson) {
+        console.log(JSON.stringify(versions.length === 1 ? versions[0] : versions, null, 2));
+        return 0;
+    }
+    versions.forEach((version, i) => {
+        if (versions.length > 1)
+            console.error(i === 0 ? `-- ${version.language || "original"} --` : `\n-- ${version.language} --`);
+        console.log(rendered(version.lines, format));
+    });
     return 0;
 }
+export { stamp };

package/dist/transcript-client.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The transcript store and the translator, as a client sees them.
+ *
+ * Both live on nixamp.com (see transcripts.ts and translate.ts); a server
+ * captioning a channel, the CLI writing a film down, and the MCP tools all
+ * talk to them through these few calls, signed in as whoever they are.
+ * Every answer is a plain object or a sentence, never a throw, because a
+ * store that is briefly away must cost the memory and not the captions.
+ */
+import type { TranscriptLine } from "./transcripts.ts";
+export interface Signed {
+    site: string;
+    token: string;
+}
+export interface StoredTranscript {
+    id: string;
+    media: string;
+    kind: string;
+    language: string;
+    translatedFrom: string | null;
+    model: string;
+    complete: boolean;
+    title: string;
+    seconds: number;
+    updatedAt: string;
+    lines: TranscriptLine[];
+    languages: {
+        language: string;
+        translatedFrom: string | null;
+        lines: number;
+        complete: boolean;
+    }[];
+    /** A translation that is still being made: how far it has got. */
+    translating?: {
+        done: number;
+        total: number;
+    };
+}
+export type Got<T> = {
+    ok: true;
+    body: T;
+} | {
+    ok: false;
+    status: number;
+    error: string;
+};
+/** The transcript of some media in a language ("" for the original), if the store has one. */
+export declare function fetchTranscript(signed: Signed, id: string, language?: string, fetcher?: typeof fetch): Promise<Got<StoredTranscript>>;
+export interface LinesToKeep {
+    media: string;
+    language: string;
+    translatedFrom?: string | null;
+    model?: string;
+    title?: string;
+    complete?: boolean;
+    lines: TranscriptLine[];
+}
+/** Keep lines: appended to what the store has, or the whole thing when `complete`. */
+export declare function keepLines(signed: Signed, id: string, ask: LinesToKeep, fetcher?: typeof fetch): Promise<Got<{
+    saved: number;
+    seconds: number;
+    complete: boolean;
+}>>;
+export interface Translated {
+    texts: string[];
+    from: string;
+    to: string;
+    model: string;
+}
+/** Texts in another language. `from` may be "" when nixamp.com should tell. */
+export declare function translateTexts(signed: Signed, texts: string[], from: string, to: string, fetcher?: typeof fetch): Promise<Got<Translated>>;
+/** Forget some media's transcripts. Only whoever stored them may. */
+export declare function forgetTranscript(signed: Signed, id: string, fetcher?: typeof fetch): Promise<Got<{
+    ok: true;
+}>>;
+/** What this account has had written down. */
+export declare function listTranscripts(signed: Signed, fetcher?: typeof fetch): Promise<Got<{
+    transcripts: (Omit<StoredTranscript, "lines" | "languages"> & {
+        lines: number;
+    })[];
+}>>;