nixamp 0.23.7 → 0.24.0

package/dist/main.js

@@ -60,8 +60,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
@@ -241,31 +242,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.
 
@@ -286,13 +316,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.
 
@@ -515,6 +554,11 @@ export async function main() {
         process.exitCode = await mcp();
         return;
     }
+    if (first === "translate") {
+        const { translate } = await import("./translate-cli.js");
+        process.exitCode = await translate(rest);
+        return;
+    }
     if (first === "token" || first === "tokens") {
         const { tokens } = await import("./session.js");
         process.exitCode = await tokens(rest);

package/dist/mcp.d.ts

@@ -1,4 +1,4 @@
-import { wavOf } from "./transcribe.ts";
+import { wavOf, type Window } from "./transcribe.ts";
 export declare const PROTOCOL_VERSION = "2025-06-18";
 interface Request {
     jsonrpc: "2.0";
@@ -21,6 +21,12 @@ export interface McpOptions {
     } | null;
     /** How a recording becomes a WAV; the tests hand in a fake. */
     wavOf?: typeof wavOf;
+    /** The whole of a file as windows of sound, and a file's identity; the tests hand in fakes. */
+    windows?: (source: string) => AsyncIterable<Window>;
+    fingerprint?: (path: string) => string;
+    sleep?: (ms: number) => Promise<void>;
+    /** How many times a translation is asked about before answering with its progress. */
+    polls?: number;
     say?: (line: string) => void;
 }
 /** A tool answer, in the shape MCP wants: content blocks, and a flag for failure. */

package/dist/mcp.js

@@ -18,10 +18,13 @@
  * every diagnostic goes to stderr. That is the one rule of this file.
  */
 import { createInterface } from "node:readline";
+import { basename, extname } from "node:path";
 import { clock } from "./party.js";
 import { readSession } from "./session.js";
-import { askToHear, wavOf } from "./transcribe.js";
+import { askToHear, awaitTranscript, hearWhole, rendered, wavOf } from "./transcribe.js";
 import { readTranscript } from "./transcript.js";
+import { fetchTranscript, listTranscripts, translateTexts } from "./transcript-client.js";
+import { fileFingerprint, idFrom, languageCode, mediaOfUrl, transcriptIdOf } from "./transcripts.js";
 import { personaLines, readPersona, readVoices, writePersona } from "./profile.js";
 export const PROTOCOL_VERSION = "2025-06-18";
 const STRING = { type: "string" };
@@ -81,18 +84,53 @@ export const TOOLS = [
     },
     {
         name: "transcribe_audio",
-        description: "The words in a recording on this machine, heard by nixamp.com's own open-source ear (Whisper). Any format ffmpeg reads; up to a minute. Given a server, the words are also posted to that server's trollbox as this account.",
+        description: "The words in a recording, a film or a link on this machine, heard by nixamp.com's own open-source ear (Whisper) a minute at a time, with when each line is said, and kept on nixamp.com under the file's fingerprint so the same file is never heard twice by anybody. Any format ffmpeg reads. Given a server, the recording is a short clip and the words are posted to that server's trollbox as this account instead.",
         inputSchema: {
             type: "object",
             properties: {
-                path: { ...STRING, description: "The recording's path on this machine." },
+                path: { ...STRING, description: "The recording's path on this machine, or a URL ffmpeg can read." },
                 language: { ...STRING, description: "A two-letter language code, when Whisper should not guess." },
-                server: { ...STRING, description: "Post the words to this nixamp's trollbox: its address, as in its share link." },
+                translate: { ...STRING, description: "Also in this language: a two-letter code such as de or sv (several: de,sv). Made once on nixamp.com and kept." },
+                format: { ...STRING, description: "How to answer: lines (default, with seconds), srt, vtt or txt." },
+                fresh: { type: "boolean", description: "Hear it again even though it is kept." },
+                server: { ...STRING, description: "Post the words to this nixamp's trollbox: its address, as in its share link. A clip of a minute at most." },
                 channel: { ...STRING, description: "Which of that server's channels; its own stream (live) by default." },
             },
             required: ["path"],
         },
     },
+    {
+        name: "transcript_get",
+        description: "A kept transcript from nixamp.com: what a file, a link or a past live said, by its id or its media identity (file:v1:<hash>, url:<address>, live:<server>/<channel>@<started>). Ask for a language and it is translated once, on nixamp.com, and kept; a long one is answered with progress and is ready on a later ask.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                media: { ...STRING, description: "The transcript's id, or the media identity." },
+                language: { ...STRING, description: "A two-letter code for a translation; the original when left out." },
+                format: { ...STRING, description: "lines (default, with seconds), srt, vtt or txt." },
+            },
+            required: ["media"],
+        },
+    },
+    {
+        name: "transcripts_list",
+        description: "What this account has had written down on nixamp.com: each transcript's id, what it is, its language, how many lines, and when.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "translate_text",
+        description: "Text in another language, by an open-source model on nixamp.com's own CPU (OPUS-MT). Two-letter codes; German and Swedish among them, and anything with a model from or into English.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                text: { ...STRING, description: "The text. Or `texts`, a list." },
+                texts: { type: "array", items: STRING, description: "Several texts, answered in the same order." },
+                from: { ...STRING, description: "The language the text is in, e.g. en." },
+                to: { ...STRING, description: "The language wanted, e.g. sv." },
+            },
+            required: ["from", "to"],
+        },
+    },
     {
         name: "trollbox_say",
         description: "Say a line in a live room's trollbox, as this account and under its public handle. A room is a nixamp server's address and one of its channels (or `live`, the server's own stream).",
@@ -108,13 +146,14 @@ export const TOOLS = [
     },
     {
         name: "transcript_read",
-        description: "What a live channel is saying: the recent lines of its transcript, oldest first, each with when its sound was heard. The server carrying the channel captions it while somebody asks. Pass the server's address and share key, and the channel's id.",
+        description: "What a live channel is saying: the recent lines of its transcript, oldest first, each with when its sound was heard. The server carrying the channel captions it while somebody asks, and translates each line when a language is asked for. Pass the server's address and share key, and the channel's id.",
         inputSchema: {
             type: "object",
             properties: {
                 url: { ...STRING, description: "The nixamp server's address, e.g. https://server1.chovy.nixamp.com:4321." },
                 key: { ...STRING, description: "The share key from its link, when it has one." },
                 channel: { ...STRING, description: "The channel's id on that server (default: main)." },
+                language: { ...STRING, description: "The lines in this language (a two-letter code); as heard when left out." },
                 after: { type: "number", description: "Only lines heard after this moment (ms since the epoch)." },
             },
             required: ["url"],
@@ -159,6 +198,13 @@ export const TOOLS = [
 function said(line) {
     return `${line.createdAt}  ${line.handle}: ${line.body}`;
 }
+/** A kept transcript, as a tool answers it. */
+function transcriptText(transcript, format) {
+    const shape = format === "srt" || format === "vtt" || format === "txt" ? format : "lines";
+    const head = `${transcript.title || transcript.media} (${transcript.id.slice(0, 12)}), ${transcript.language || "language unknown"}${transcript.translatedFrom ? ` from ${transcript.translatedFrom}` : ""}, ${transcript.lines.length} lines${transcript.complete ? "" : ", so far"}`;
+    const others = transcript.languages.filter((one) => one.language !== transcript.language).map((one) => one.language || "original");
+    return `${head}${others.length > 0 ? `; also in ${others.join(", ")}` : ""}\n\n${rendered(transcript.lines, shape)}`;
+}
 function text(value) {
     return { content: [{ type: "text", text: value }] };
 }
@@ -262,25 +308,114 @@ export async function callTool(name, args, options = {}) {
             const path = typeof args["path"] === "string" ? args["path"] : "";
             if (!path)
                 return failed("Which recording? Pass its path.");
-            let wav;
+            const language = languageCode(args["language"]) || undefined;
+            if (server) {
+                let wav;
+                try {
+                    wav = (options.wavOf ?? wavOf)(path);
+                }
+                catch (error) {
+                    return failed(error.message);
+                }
+                const answer = await askToHear(session, { wav, ...(language ? { language } : {}), server, channel }, send, site);
+                if (!answer.ok)
+                    return failed(answer.error);
+                if (answer.heard.text === "")
+                    return text("Heard nothing in that recording.");
+                return text(answer.heard.message
+                    ? `${answer.heard.text}\n\nSaid in the room for ${channel} at ${server} as ${answer.heard.message.handle}.`
+                    : answer.heard.text);
+            }
+            // The whole of it, kept under what it is.
+            let media;
             try {
-                wav = (options.wavOf ?? wavOf)(path);
+                media = /^https?:\/\//.test(path) ? mediaOfUrl(path) : (options.fingerprint ?? fileFingerprint)(path);
             }
-            catch (error) {
-                return failed(error.message);
+            catch {
+                return failed(`cannot read ${path}`);
             }
-            const answer = await askToHear(session, {
-                wav,
-                ...(typeof args["language"] === "string" ? { language: args["language"] } : {}),
-                ...(server ? { server, channel } : {}),
-            }, send, site);
-            if (!answer.ok)
-                return failed(answer.error);
-            if (answer.heard.text === "")
-                return text("Heard nothing in that recording.");
-            return text(answer.heard.message
-                ? `${answer.heard.text}\n\nSaid in the room for ${channel} at ${server} as ${answer.heard.message.handle}.`
-                : answer.heard.text);
+            const id = transcriptIdOf(media);
+            const title = /^https?:\/\//.test(path) ? path : basename(path, extname(path));
+            const format = typeof args["format"] === "string" ? args["format"] : "lines";
+            const signed = { site, token: session.token };
+            let original = null;
+            if (args["fresh"] !== true) {
+                const kept = await fetchTranscript(signed, id, "", send);
+                if (kept.ok && kept.body.complete)
+                    original = kept.body;
+                else if (!kept.ok && kept.status !== 404)
+                    return failed(kept.error);
+            }
+            if (!original) {
+                const heard = await hearWhole(signed, path, media, { ...(language ? { language } : {}), title }, {
+                    fetcher: send,
+                    ...(options.windows ? { windows: options.windows } : {}),
+                    ...(options.sleep ? { sleep: options.sleep } : {}),
+                    ...(options.say ? { onProgress: options.say } : {}),
+                });
+                if (!heard.ok)
+                    return failed(heard.error);
+                if (heard.heard.lines.length === 0)
+                    return text("Heard nothing in that.");
+                const kept = await fetchTranscript(signed, id, "", send);
+                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: [],
+                };
+            }
+            const wanted = (typeof args["translate"] === "string" ? args["translate"] : "").split(",").map((one) => languageCode(one)).filter((one) => typeof one === "string" && one !== "");
+            const parts = [transcriptText(original, format)];
+            for (const to of wanted) {
+                if (to === original.language)
+                    continue;
+                const got = await awaitTranscript(signed, id, to, { fetcher: send, ...(options.sleep ? { sleep: options.sleep } : {}), ...(options.polls !== undefined ? { polls: options.polls } : {}) });
+                if (!got.ok)
+                    return failed(`could not get it in ${to}: ${got.error}`);
+                parts.push(got.body.translating
+                    ? `In ${to}: still being translated, ${got.body.translating.done} of ${got.body.translating.total} lines. Ask transcript_get for ${id} in ${to} in a moment.`
+                    : transcriptText(got.body, format));
+            }
+            return text(parts.join("\n\n"));
+        }
+        if (name === "transcript_get") {
+            const named = typeof args["media"] === "string" ? args["media"].trim() : "";
+            if (!named)
+                return failed("Which transcript? Pass its id or the media identity.");
+            const language = languageCode(args["language"]);
+            if (language === null)
+                return failed("language is a two-letter code, such as de or sv.");
+            const got = await awaitTranscript({ site, token: session.token }, idFrom(named), language, {
+                fetcher: send, ...(options.sleep ? { sleep: options.sleep } : {}), polls: options.polls ?? 1,
+            });
+            if (!got.ok)
+                return failed(got.error);
+            if (got.body.translating) {
+                return text(`Still being translated to ${language}: ${got.body.translating.done} of ${got.body.translating.total} lines. Ask again in a moment.`);
+            }
+            return text(transcriptText(got.body, typeof args["format"] === "string" ? args["format"] : "lines"));
+        }
+        if (name === "transcripts_list") {
+            const got = await listTranscripts({ site, token: session.token }, send);
+            if (!got.ok)
+                return failed(got.error);
+            if (got.body.transcripts.length === 0)
+                return text("Nothing has been written down for this account yet.");
+            return text(got.body.transcripts.map((one) => `${one.id}  ${one.language || "?"}${one.translatedFrom ? `<${one.translatedFrom}` : ""}  ${one.lines} lines${one.complete ? "" : " so far"}  ${one.title || one.media}  ${one.updatedAt}`).join("\n"));
+        }
+        if (name === "translate_text") {
+            const texts = Array.isArray(args["texts"])
+                ? args["texts"].filter((one) => typeof one === "string")
+                : typeof args["text"] === "string" ? [args["text"]] : [];
+            if (texts.length === 0)
+                return failed("Translate what? Pass text, or texts.");
+            const from = languageCode(args["from"]);
+            const to = languageCode(args["to"]);
+            if (!from || !to)
+                return failed("from and to are two-letter language codes, such as en and sv.");
+            const got = await translateTexts({ site, token: session.token }, texts, from, to, send);
+            if (!got.ok)
+                return failed(got.error);
+            return text(got.body.texts.join("\n"));
         }
         if (name === "trollbox_say") {
             if (!server)
@@ -302,7 +437,7 @@ export async function callTool(name, args, options = {}) {
             const url = typeof args["url"] === "string" ? args["url"].trim() : "";
             if (!url)
                 return failed("Which server? Pass its address.");
-            const got = await readTranscript({ url, key: typeof args["key"] === "string" && args["key"] ? args["key"] : null }, channel === "live" ? "main" : channel, typeof args["after"] === "number" ? args["after"] : 0, send);
+            const got = await readTranscript({ url, key: typeof args["key"] === "string" && args["key"] ? args["key"] : null }, channel === "live" ? "main" : channel, typeof args["after"] === "number" ? args["after"] : 0, send, languageCode(args["language"]) || "");
             if (!got.ok)
                 return failed(got.error);
             if (got.answer.recent.length === 0) {
@@ -368,8 +503,8 @@ export async function handleMessage(message, options = {}) {
         return reply({
             protocolVersion: PROTOCOL_VERSION,
             capabilities: { tools: { listChanged: false } },
-            serverInfo: { name: "nixamp", title: "nixamp: watch parties and rooms", version: "1" },
-            instructions: "Watch parties on nixamp. A party lives on the site hosting the film and is bridged here as a room every nixamp client can join. Codes are the ones that site shows; positions are seconds into the film.",
+            serverInfo: { name: "nixamp", title: "nixamp: watch parties, rooms and transcripts", version: "2" },
+            instructions: "Watch parties on nixamp: a party lives on the site hosting the film and is bridged here as a room every nixamp client can join; codes are the ones that site shows, positions are seconds into the film. Rooms: say and read trollbox lines, hear a recording. Transcripts: a file, a link or a live is written down once by nixamp.com's own ear and kept under what it is; ask for it in another language and it is translated once and kept too.",
         });
     }
     // Notifications carry no id and are answered with silence, which is what

package/dist/server.d.ts

@@ -32,6 +32,9 @@ import { Rooms } from "./rooms.ts";
 import { Trollbox } from "./trollbox.ts";
 import { Speech } from "./speech.ts";
 import { Captions } from "./captions.ts";
+import { Translator } from "./translate.ts";
+import { StoredTranslations } from "./translate-jobs.ts";
+import { Transcripts } from "./transcripts.ts";
 import { Profiles, Voices } from "./voices.ts";
 import { type Codecs } from "./audio.ts";
 import { type Tools, type Track } from "./audio.ts";
@@ -699,6 +702,14 @@ export interface HandlerOptions {
     trollbox?: Trollbox;
     /** Speech to text: a line said out loud, heard here. Needs the optional model. */
     speech?: Speech;
+    /** Translation: texts in another language, by a model here. The same optional library. */
+    translator?: Translator;
+    /** The transcript store: what was heard, kept under the media's identity. Where the accounts are. */
+    transcripts?: Transcripts;
+    /** Stored transcripts translated, as jobs. */
+    translations?: StoredTranslations;
+    /** nixamp.com's address, for the tools reached over /mcp to call. */
+    site?: string;
     /** Other people's OpenProfiles, for the voice their lines are read in. */
     profiles?: Profiles;
     /** The voices lines are read in: ElevenLabs when Telnyx holds the key, Kokoro otherwise. */