nixamp 0.23.7 → 0.24.0

package/src/captions.ts

@@ -20,10 +20,21 @@
  * A quiet window -- the gap between songs, a picture with no talking -- is
  * never sent. Most of a music channel is that, and hearing it costs the
  * same as hearing speech.
+ *
+ * What is heard is kept (see transcripts.ts): every line goes to nixamp.com
+ * under the identity of what the channel is playing, as seconds into it.
+ * When a captioner starts it asks for what is already known, and a window
+ * whose moment the store has been through is read out of it instead of
+ * heard. A film captioned once is captioned by nobody again; a live is
+ * kept as the broadcast it was. And a viewer may ask for the lines in
+ * another language: each heard line is translated once, on nixamp.com,
+ * handed to whoever wanted that language, and kept beside the original.
  */
 import { spawn } from "node:child_process";
 import type { Listener } from "./channels.ts";
 import { RATE } from "./speech.ts";
+import { fetchTranscript, keepLines, translateTexts } from "./transcript-client.ts";
+import { covered, lineAt, transcriptIdOf, type TranscriptLine } from "./transcripts.ts";
 
 export interface CaptionLine {
   /** The channel's id. */
@@ -32,6 +43,10 @@ export interface CaptionLine {
   at: number;
   until: number;
   text: string;
+  /** The language of the words, as heard or as translated into; absent when nobody said. */
+  language?: string;
+  /** What was heard, when this line is a translation of it. */
+  original?: string;
 }
 
 /** What turns a channel's bytes into 16 kHz mono 16-bit PCM. ffmpeg, or a test's stand-in. */
@@ -40,6 +55,22 @@ export interface Decoder {
   end(): void;
 }
 
+/**
+ * What a channel is playing, for the store: its identity, and how the
+ * sound a new listener gets maps onto seconds of it.
+ */
+export interface ChannelMedia {
+  /** The media identity, as transcripts.ts spells one. */
+  media: string;
+  title: string;
+  /** Seconds into the media at this moment, for a film; absent for anything live. */
+  position?: number;
+  /** When the channel began, wall clock, ms. A live's seconds count from here. */
+  startedAt: number;
+  /** How many seconds behind the live edge a new listener's sound starts. */
+  backlog: number;
+}
+
 export interface CaptionsOptions {
   /** A listener on a channel, or null when there is no such channel. */
   listen: (id: string, listener: Listener) => (() => void) | null;
@@ -49,10 +80,14 @@ export interface CaptionsOptions {
   fetcher?: typeof fetch;
   /** How bytes become PCM. The default spawns ffmpeg; the tests hand in something quieter. */
   decoder?: (onPcm: (pcm: Buffer) => void, onEnd: () => void) => Decoder;
+  /** What a channel is playing, for the store. Null, or absent, means the lines are not kept. */
+  mediaOf?: (id: string) => ChannelMedia | null;
   now?: () => number;
   onEvent?: (message: string) => void;
   windowMs?: number;
   idleMs?: number;
+  /** How often heard lines go to the store. */
+  flushMs?: number;
 }
 
 export const WINDOW_MS = 5000;
@@ -63,6 +98,10 @@ export const IDLE_MS = 60_000;
 export const QUIET = 0.004;
 /** Windows waiting on the ear at once. Past this the sound is dropped, not queued: late words are worse than none. */
 export const IN_FLIGHT = 2;
+/** Heard lines wait this long, at most, before they are kept. */
+export const FLUSH_MS = 20_000;
+/** Or this many. */
+export const FLUSH_LINES = 12;
 
 /**
  * The ffmpeg arguments: whatever arrives on stdin, as PCM on stdout, with
@@ -148,13 +187,52 @@ export function wavAround(pcm: Buffer, rate = RATE): Buffer {
   return Buffer.concat([header, pcm]);
 }
 
+/**
+ * Seconds into the media that a window covers. A film is paced in real
+ * time from a known position, so a new listener's first byte is that
+ * position less the backlog it was handed, and every window after it is
+ * one window further on. Anything live counts from when the channel
+ * began, in wall-clock time.
+ */
+export function mediaSpan(media: ChannelMedia, windowIndex: number, windowSeconds: number, at: number, until: number): { start: number; end: number } {
+  if (typeof media.position === "number") {
+    const join = Math.max(0, media.position - media.backlog);
+    return { start: round(join + windowIndex * windowSeconds), end: round(join + (windowIndex + 1) * windowSeconds) };
+  }
+  return { start: round(Math.max(0, (at - media.startedAt) / 1000)), end: round(Math.max(0, (until - media.startedAt) / 1000)) };
+}
+
+function round(seconds: number): number {
+  return Math.round(seconds * 1000) / 1000;
+}
+
+export { lineAt };
+
 type Subscriber = (line: CaptionLine) => void;
 
+export interface CaptionStatus {
+  on: boolean;
+  lines: number;
+  error: string;
+  /** The language heard, when known. */
+  language: string;
+  /** How many lines the store already had for this media when the captioner began. */
+  known: number;
+  /** The languages lines are being given in besides the original. */
+  languages: string[];
+}
+
 class Captioner {
+  /** The lines as heard, oldest first. */
   readonly lines: CaptionLine[] = [];
-  readonly subscribers = new Set<Subscriber>();
+  /** The lines in each other language somebody asked for. */
+  readonly linesBy = new Map<string, CaptionLine[]>();
+  readonly subscribers = new Map<Subscriber, string>();
   /** The last thing that went wrong, for whoever asks why there are no lines. */
   error = "";
+  /** What the ear says the sound is in, or the store said it was; "" until one of them has. */
+  language = "";
+  private model = "";
   private decoder: Decoder | null = null;
   private detach: (() => void) | null = null;
   private idle: ReturnType<typeof setTimeout> | null = null;
@@ -163,17 +241,41 @@ class Captioner {
   private inFlight = 0;
   private stopped = false;
   private complainedAt = 0;
+  private windows = 0;
+  /** What the channel is playing, when the store is to be told. */
+  private readonly media: ChannelMedia | null;
+  private readonly transcriptId: string | null;
+  /** What the store had, by language ("" for the original), and which stored moments have been read out. */
+  private readonly known = new Map<string, TranscriptLine[]>();
+  private readonly readOut = new Set<number>();
+  private readonly asked = new Set<string>();
+  /** Lines heard or translated here and not yet kept, by language. */
+  private readonly unsaved = new Map<string, TranscriptLine[]>();
+  private flush: ReturnType<typeof setTimeout> | null = null;
+  /** Translations in order, per language: a slow one must not overtake the next. */
+  private readonly chains = new Map<string, Promise<void>>();
 
   constructor(
     readonly id: string,
     private readonly options: CaptionsOptions,
     private readonly onStop: () => void,
-  ) {}
+  ) {
+    this.media = options.mediaOf?.(id) ?? null;
+    this.transcriptId = this.media ? transcriptIdOf(this.media.media) : null;
+  }
 
   private get windowBytes(): number {
     return Math.round(((this.options.windowMs ?? WINDOW_MS) / 1000) * RATE) * 2;
   }
 
+  private get windowSeconds(): number {
+    return (this.options.windowMs ?? WINDOW_MS) / 1000;
+  }
+
+  private now(): number {
+    return (this.options.now ?? Date.now)();
+  }
+
   start(): boolean {
     const make = this.options.decoder ?? ((onPcm, onEnd) => ffmpegDecoder(this.options.ffmpeg, onPcm, onEnd));
     this.decoder = make((pcm) => this.onPcm(pcm), () => this.stop());
@@ -185,9 +287,29 @@ class Captioner {
       this.stop();
       return false;
     }
+    void this.consult("");
     return true;
   }
 
+  /** Ask the store what it already knows of this media in a language, once. */
+  private async consult(language: string): Promise<void> {
+    if (!this.transcriptId || this.asked.has(language)) return;
+    this.asked.add(language);
+    const session = this.options.session();
+    if (session === null) return;
+    const got = await fetchTranscript(session, this.transcriptId, language, this.options.fetcher ?? fetch);
+    if (this.stopped) return;
+    if (!got.ok) {
+      if (got.status !== 404) this.complain(`the store did not answer: ${got.error}`);
+      return;
+    }
+    this.known.set(language, got.body.lines);
+    if (language === "" && this.language === "" && got.body.language) this.language = got.body.language;
+    if (got.body.lines.length > 0) {
+      this.options.onEvent?.(`captions for "${this.id}": the store knows ${got.body.lines.length} lines of this${language ? ` in ${language}` : ""}`);
+    }
+  }
+
   private onPcm(pcm: Buffer): void {
     if (this.stopped) return;
     this.pending.push(pcm);
@@ -199,13 +321,29 @@ class Captioner {
       const rest = all.subarray(size);
       this.pending = rest.length > 0 ? [Buffer.from(rest)] : [];
       this.pendingBytes = rest.length;
-      const until = (this.options.now ?? Date.now)();
-      void this.hear(Buffer.from(window), until - (this.options.windowMs ?? WINDOW_MS), until);
+      const until = this.now();
+      const index = this.windows;
+      this.windows += 1;
+      void this.hear(Buffer.from(window), until - (this.options.windowMs ?? WINDOW_MS), until, index);
     }
   }
 
-  private async hear(pcm: Buffer, at: number, until: number): Promise<void> {
+  private async hear(pcm: Buffer, at: number, until: number, index: number): Promise<void> {
     if (isQuiet(pcm)) return;
+    const span = this.media ? mediaSpan(this.media, index, this.windowSeconds, at, until) : null;
+    if (span) {
+      const stored = covered(this.known.get("") ?? [], span.start, span.end);
+      if (stored.length > 0) {
+        // The store has been through this moment: read it out, and let the ear rest.
+        for (const line of stored) {
+          if (this.readOut.has(line.start)) continue;
+          this.readOut.add(line.start);
+          const lineAt = at + (line.start - span.start) * 1000;
+          this.emit({ channel: this.id, at: lineAt, until: lineAt + (line.end - line.start) * 1000, text: line.text, ...(this.language ? { language: this.language } : {}) }, line.start);
+        }
+        return;
+      }
+    }
     if (this.inFlight >= IN_FLIGHT) return;
     const session = this.options.session();
     if (session === null) {
@@ -215,12 +353,14 @@ class Captioner {
     this.inFlight += 1;
     try {
       const wav = wavAround(pcm);
-      const response = await (this.options.fetcher ?? fetch)(`${session.site.replace(/\/+$/, "")}/api/v1/speech/transcribe`, {
+      const url = new URL(`${session.site.replace(/\/+$/, "")}/api/v1/speech/transcribe`);
+      if (this.language) url.searchParams.set("language", this.language);
+      const response = await (this.options.fetcher ?? fetch)(url.toString(), {
         method: "POST",
         headers: { authorization: `Bearer ${session.token}`, "content-type": "audio/wav" },
         body: new Blob([wav.buffer.slice(wav.byteOffset, wav.byteOffset + wav.byteLength) as ArrayBuffer]),
       });
-      const body = (await response.json().catch(() => ({}))) as { text?: string; error?: string };
+      const body = (await response.json().catch(() => ({}))) as { text?: string; language?: string; model?: string; error?: string };
       if (!response.ok) {
         this.complain(body.error ?? `nixamp.com answered ${response.status}`);
         return;
@@ -228,16 +368,11 @@ class Captioner {
       const text = (body.text ?? "").trim();
       if (text === "" || this.stopped) return;
       this.error = "";
-      const line: CaptionLine = { channel: this.id, at, until, text };
-      this.lines.push(line);
-      while (this.lines.length > KEEP) this.lines.shift();
-      for (const subscriber of this.subscribers) {
-        try {
-          subscriber(line);
-        } catch {
-          // A listener that throws is not this channel's problem.
-        }
-      }
+      if (body.language && this.language === "") this.language = body.language;
+      if (body.model) this.model = body.model;
+      const line: CaptionLine = { channel: this.id, at, until, text, ...(this.language ? { language: this.language } : {}) };
+      this.emit(line, span?.start ?? null);
+      if (span) this.keep("", { start: span.start, end: span.end, text });
     } catch (error) {
       this.complain(`could not reach the ear: ${(error as Error).message}`);
     } finally {
@@ -245,17 +380,112 @@ class Captioner {
     }
   }
 
+  /** A line as heard, to whoever wants the original, and translated to whoever wants another language. */
+  private emit(line: CaptionLine, mediaStart: number | null): void {
+    this.lines.push(line);
+    while (this.lines.length > KEEP) this.lines.shift();
+    for (const [subscriber, language] of this.subscribers) {
+      if (language === "" || language === this.language) this.tell(subscriber, line);
+    }
+    for (const language of this.wanted()) this.translated(language, line, mediaStart);
+  }
+
+  private tell(subscriber: Subscriber, line: CaptionLine): void {
+    try {
+      subscriber(line);
+    } catch {
+      // A listener that throws is not this channel's problem.
+    }
+  }
+
+  /** The languages somebody wants besides the one being heard. */
+  private wanted(): Set<string> {
+    const languages = new Set<string>();
+    for (const language of this.subscribers.values()) if (language !== "" && language !== this.language) languages.add(language);
+    return languages;
+  }
+
+  /** The line in another language: from the store when it has been through this moment, from nixamp.com otherwise. */
+  private translated(language: string, line: CaptionLine, mediaStart: number | null): void {
+    const chain = (this.chains.get(language) ?? Promise.resolve()).then(async () => {
+      if (this.stopped) return;
+      let text = "";
+      const stored = mediaStart === null ? null : lineAt(this.known.get(language) ?? [], mediaStart);
+      if (stored) {
+        text = stored.text;
+      } else {
+        const session = this.options.session();
+        if (session === null) return;
+        const got = await translateTexts(session, [line.text], this.language, language, this.options.fetcher ?? fetch);
+        if (!got.ok) {
+          this.complain(`could not translate to ${language}: ${got.error}`);
+          return;
+        }
+        text = (got.body.texts[0] ?? "").trim();
+        if (text === "") return;
+        if (mediaStart !== null) this.keep(language, { start: mediaStart, end: round(mediaStart + (line.until - line.at) / 1000), text });
+      }
+      if (this.stopped) return;
+      const said: CaptionLine = { ...line, text, language, original: line.text };
+      const lines = this.linesBy.get(language) ?? [];
+      lines.push(said);
+      while (lines.length > KEEP) lines.shift();
+      this.linesBy.set(language, lines);
+      for (const [subscriber, wanted] of this.subscribers) if (wanted === language) this.tell(subscriber, said);
+    });
+    this.chains.set(language, chain.catch(() => undefined));
+  }
+
+  /** A line for the store, kept with the others of its language until the next flush. */
+  private keep(language: string, line: TranscriptLine): void {
+    if (!this.media) return;
+    const lines = this.unsaved.get(language) ?? [];
+    lines.push(line);
+    this.unsaved.set(language, lines);
+    if (lines.length >= FLUSH_LINES) {
+      void this.flushNow();
+      return;
+    }
+    if (this.flush === null) {
+      this.flush = setTimeout(() => void this.flushNow(), this.options.flushMs ?? FLUSH_MS);
+      this.flush.unref?.();
+    }
+  }
+
+  /** Everything not yet kept, to the store. Never throws; a store that is away costs nothing but the keeping. */
+  private async flushNow(): Promise<void> {
+    if (this.flush) clearTimeout(this.flush);
+    this.flush = null;
+    if (!this.media || !this.transcriptId) return;
+    const session = this.options.session();
+    if (session === null) return;
+    const batches = [...this.unsaved.entries()].filter(([, lines]) => lines.length > 0);
+    this.unsaved.clear();
+    for (const [language, lines] of batches) {
+      const got = await keepLines(session, this.transcriptId, {
+        media: this.media.media,
+        title: this.media.title,
+        language: language === "" ? this.language : language,
+        ...(language === "" ? {} : { translatedFrom: this.language }),
+        ...(this.model ? { model: this.model } : {}),
+        lines,
+      }, this.options.fetcher ?? fetch);
+      if (!got.ok) this.complain(`the store did not keep ${lines.length} lines: ${got.error}`);
+    }
+  }
+
   /** Said once a minute at most: a broken ear would otherwise say so twelve times a minute. */
   private complain(message: string): void {
     this.error = message;
-    const now = (this.options.now ?? Date.now)();
+    const now = this.now();
     if (now - this.complainedAt < 60_000) return;
     this.complainedAt = now;
     this.options.onEvent?.(`captions for "${this.id}": ${message}`);
   }
 
-  subscribe(subscriber: Subscriber): () => void {
-    this.subscribers.add(subscriber);
+  subscribe(subscriber: Subscriber, language = ""): () => void {
+    this.subscribers.set(subscriber, language);
+    if (language !== "") void this.consult(language);
     if (this.idle) clearTimeout(this.idle);
     this.idle = null;
     return () => {
@@ -269,6 +499,22 @@ class Captioner {
     };
   }
 
+  recent(after: number, language = ""): CaptionLine[] {
+    const lines = language === "" || language === this.language ? this.lines : (this.linesBy.get(language) ?? []);
+    return after > 0 ? lines.filter((line) => line.at > after) : [...lines];
+  }
+
+  status(): CaptionStatus {
+    return {
+      on: true,
+      lines: this.lines.length,
+      error: this.error,
+      language: this.language,
+      known: this.known.get("")?.length ?? 0,
+      languages: [...this.linesBy.keys()],
+    };
+  }
+
   stop(): void {
     if (this.stopped) return;
     this.stopped = true;
@@ -281,6 +527,7 @@ class Captioner {
     this.pending = [];
     this.pendingBytes = 0;
     this.subscribers.clear();
+    void this.flushNow();
     this.onStop();
   }
 }
@@ -299,9 +546,10 @@ export class Captions {
    * Lines for a channel as they are heard, starting the captioner if it is
    * not running. Null when there is no such channel. The returned function
    * is how to stop listening; the captioner itself stops a minute after the
-   * last listener does.
+   * last listener does. A language asks for the lines translated into it;
+   * "" is the original.
    */
-  subscribe(id: string, subscriber: Subscriber): (() => void) | null {
+  subscribe(id: string, subscriber: Subscriber, language = ""): (() => void) | null {
     let captioner = this.running.get(id);
     if (!captioner) {
       const made = new Captioner(id, this.options, () => {
@@ -312,20 +560,19 @@ export class Captions {
       this.options.onEvent?.(`captions for "${id}": started`);
       captioner = made;
     }
-    return captioner.subscribe(subscriber);
+    return captioner.subscribe(subscriber, language);
   }
 
-  /** The recent lines of a channel, oldest first, after a moment when given. Empty when nobody has asked for them. */
-  recent(id: string, after = 0): CaptionLine[] {
+  /** The recent lines of a channel, oldest first, after a moment when given, in a language when asked. Empty when nobody has asked for them. */
+  recent(id: string, after = 0, language = ""): CaptionLine[] {
     const captioner = this.running.get(id);
-    if (!captioner) return [];
-    return after > 0 ? captioner.lines.filter((line) => line.at > after) : [...captioner.lines];
+    return captioner ? captioner.recent(after, language) : [];
   }
 
   /** Whether a channel is being captioned, and what last went wrong if the lines are not coming. */
-  status(id: string): { on: boolean; lines: number; error: string } {
+  status(id: string): CaptionStatus {
     const captioner = this.running.get(id);
-    return captioner ? { on: true, lines: captioner.lines.length, error: captioner.error } : { on: false, lines: 0, error: "" };
+    return captioner ? captioner.status() : { on: false, lines: 0, error: "", language: "", known: 0, languages: [] };
   }
 
   stopAll(): void {

package/src/main.ts

@@ -84,8 +84,9 @@ const HELP = `nixamp — it really whips the terminal's ass.
   nixamp server list|add|remove  the machines you run, kept against your account
   nixamp party list|join|host   watch parties, here and on the sites nixamp is connected to
   nixamp mcp                     speak Model Context Protocol on stdin, for an agent
-  nixamp transcribe FILE [--say SERVER]  the words in a recording, and into a trollbox
-  nixamp transcript --channel ID [--follow]  what a channel is saying, as it says it
+  nixamp transcribe FILE [--translate sv]  a recording or a whole film written down, kept, and in other languages
+  nixamp transcript --channel ID [--follow]  what a channel is saying, as it says it; --kept for what nixamp.com keeps
+  nixamp translate --to sv TEXT  say it in another language
   nixamp profile [--handle H] [--voice V] [--profile URL]  who the rooms know you as
   nixamp voices                  the voices a line is read in on the phone
   nixamp opendir list|add|remove  folders found on the web, published for everyone
@@ -267,31 +268,60 @@ takes it away again.
   nixamp mcp    speak Model Context Protocol on stdin and stdout
 
 It offers the watch party tools: list them, read one, put one on the air,
-say where playback is, end it. And the room tools: transcribe a recording
-(transcribe_audio, which can post the words straight into a trollbox), say a
-line in a room (trollbox_say), read a room (trollbox_read), read what a
-channel is saying (transcript_read), and who you are in the rooms and how
-you sound on the phone (profile_get, profile_set, voices_list). It acts as
-whoever this machine is signed in as, so \`nixamp login\` (or NIXAMP_TOKEN)
-comes first.
-
-Point an MCP client at it as a stdio server running \`nixamp mcp\`.
+say where playback is, end it. The room tools: transcribe a recording or a
+whole film (transcribe_audio, kept on nixamp.com, translated on request, or
+posted straight into a trollbox), say a line in a room (trollbox_say), read
+a room (trollbox_read), read what a channel is saying (transcript_read, in
+any language). The transcript tools: a kept transcript by its id or its
+media (transcript_get), what this account has had written down
+(transcripts_list), and text in another language (translate_text). And who
+you are in the rooms and how you sound on the phone (profile_get,
+profile_set, voices_list). It acts as whoever this machine is signed in as,
+so \`nixamp login\` (or NIXAMP_TOKEN) comes first.
+
+Point an MCP client at it as a stdio server running \`nixamp mcp\`. The same
+tools are at https://nixamp.com/mcp over HTTP, with a nixamp token
+(\`nixamp token create\`) as the bearer, for an agent with no nixamp installed.
 `,
   transcribe: `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 (Whisper, through
-Transformers.js) on its own CPU: nothing goes to a speech vendor. It 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 (Whisper,
+through Transformers.js) on its own CPU: nothing goes to a speech vendor. It
+needs a sign-in (\`nixamp login\`) and nothing else.
+
+A film is heard a minute at a time, with when each line is said, and kept on
+nixamp.com under the file's fingerprint: 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. A translation is made once, on nixamp.com
+with an open-source model (OPUS-MT), and kept beside the original.
 
 The same ear is behind the microphone button in every nixamp.com trollbox,
 and behind the transcribe_audio tool of \`nixamp mcp\`.
+`,
+  translate: `nixamp translate — say it in another language.
+
+  nixamp translate --to sv "Hello there"      Swedish, from English
+  nixamp translate --from de --to en "Guten Tag"
+  cat lines.txt | nixamp translate --to de    each line, in order
+  nixamp translate --languages                what nixamp.com can translate between
+
+The models are open-source (OPUS-MT, through Transformers.js) and run on
+nixamp.com's own CPU; a pair with no model of its own goes through English.
+Needs a sign-in (\`nixamp login\`). The same models turn a live's captions
+into another language as they are said, and a kept transcript into one on
+request.
 `,
   profile: `nixamp profile — who the rooms know you as.
 
@@ -312,13 +342,22 @@ one picked for the account and kept. Two people in a room are two voices.
   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 ... --language sv            the lines in Swedish, translated as they are said
   nixamp transcript ... --json                   the lines as JSON
+  nixamp transcript --kept MEDIA_OR_ID [--language de] [--srt|--vtt|--txt]
+                                                 a transcript nixamp.com keeps: a file's, a link's, a past live's
+  nixamp transcript --list                       what this account has had written down
 
 A server captions a channel while somebody is asking for its transcript: its
 own ffmpeg turns the sound into five-second windows, nixamp.com's ear turns
 those into lines, each stamped with when its sound was heard. The page shows
 them as subtitles, held until its own sound gets there; this prints them.
 The server needs an ffmpeg and a sign-in (\`nixamp login\`).
+
+What it hears is kept on nixamp.com under what the channel is playing: a
+film by its bytes, a link by its address, a live as the one broadcast it
+was. A channel playing something already kept reads the lines instead of
+hearing them, and a language asked for is translated once and kept too.
 `,
   attach: `nixamp attach — the player, in front of the running daemon.
 
@@ -544,6 +583,11 @@ export async function main(): Promise<void> {
     process.exitCode = await mcp();
     return;
   }
+  if (first === "translate") {
+    const { translate } = await import("./translate-cli.ts");
+    process.exitCode = await translate(rest);
+    return;
+  }
   if (first === "token" || first === "tokens") {
     const { tokens } = await import("./session.ts");
     process.exitCode = await tokens(rest);