nixamp 0.24.1 → 0.25.0

package/dist/server.js

@@ -71,6 +71,10 @@ import { LANGUAGES, Translator } from "./translate.js";
 import { StoredTranslations } from "./translate-jobs.js";
 import { Transcripts, fileFingerprint, formatOf, idFrom, languageCode, linesFrom, mediaOfLive, mediaOfUrl, toSrt, toText, toVtt, transcriptIdOf, wire, } from "./transcripts.js";
 import { handleMessage as mcpMessage } from "./mcp.js";
+import { Media, factsFromRequest, holderFrom, mediaId, openFileListing, openFileOf } from "./media.js";
+import { mediaPage } from "./media-page.js";
+import { describeFile, refreshChanged } from "./media-local.js";
+import { WATCH_EVERY_MS, remember, watchOnce } from "./media-index.js";
 import { Outro } from "./outro.js";
 import { Profiles, Voices, spokenLine, spokenVoiceFor } from "./voices.js";
 import { confirm, DEFAULT_DIRECTORY, Publisher } from "./publish.js";
@@ -2241,14 +2245,20 @@ export function createHandler(engine, options) {
          * The trollbox: the chat for one live room, keyed by the server and
          * the channel so every viewer of a stream is in the same box whichever
          * page they came from. Reading is open; a line needs a nixamp.com
-         * account and is signed with its public handle; taking one down is the
-         * author's, or the listing owner's.
+         * account and is signed with its public handle; and once sent it is
+         * public record, so there is no DELETE here for anybody.
          */
         if ((path === "/api/v1/trollbox" || path.startsWith("/api/v1/trollbox/")) && options.trollbox && options.accounts) {
             const trollbox = options.trollbox;
             const child = path.startsWith("/api/v1/trollbox/") ? path.slice("/api/v1/trollbox/".length) : "";
+            // Nothing lives under a line's id: a sent line is public record, so
+            // there is no line to address, whatever the method.
+            if (child !== "") {
+                json(response, 404, { error: "no such endpoint" });
+                return;
+            }
             try {
-                if (request.method === "GET" && child === "") {
+                if (request.method === "GET") {
                     const where = roomFor(url.searchParams.get("server"), url.searchParams.get("channel"));
                     if (!where) {
                         json(response, 400, { error: "a room is a server address and a channel" });
@@ -2259,13 +2269,11 @@ export function createHandler(engine, options) {
                     json(response, 200, {
                         room: where.room,
                         you: who ? ((await options.handles?.of(who.id)) || fallbackHandle(who.id)) : "",
-                        messages: lines.map((one) => ({
-                            id: one.id, handle: one.handle, body: one.body, createdAt: one.createdAt, mine: who !== null && one.authorId === who.id,
-                        })),
+                        messages: lines.map((one) => ({ id: one.id, handle: one.handle, body: one.body, createdAt: one.createdAt })),
                     });
                     return;
                 }
-                if (request.method === "POST" && child === "") {
+                if (request.method === "POST") {
                     const who = await options.accounts.whoIs(tokenFrom(request.headers));
                     if (who === null) {
                         json(response, 401, { error: "sign in to nixamp.com to chat" });
@@ -2287,34 +2295,10 @@ export function createHandler(engine, options) {
                     const handle = (await options.handles?.of(who.id)) || fallbackHandle(who.id);
                     const line = await trollbox.post(where, who.id, handle, body.body);
                     readOnThePhone(where, who.id, line.handle, line.body);
-                    json(response, 201, { message: { id: line.id, handle: line.handle, body: line.body, createdAt: line.createdAt, mine: true } });
-                    return;
-                }
-                if (request.method === "DELETE" && child !== "") {
-                    const who = await options.accounts.whoIs(tokenFrom(request.headers));
-                    if (who === null) {
-                        json(response, 401, { error: "sign in to nixamp.com first" });
-                        return;
-                    }
-                    const where = roomFor(url.searchParams.get("server"), url.searchParams.get("channel"));
-                    if (!where) {
-                        json(response, 400, { error: "a room is a server address and a channel" });
-                        return;
-                    }
-                    // The listing owner moderates their own server's rooms.
-                    const moderator = (options.directory?.list() ?? []).some((listing) => {
-                        try {
-                            return listing.ownerId === who.id && new URL(listing.url).origin === where.server;
-                        }
-                        catch {
-                            return false;
-                        }
-                    });
-                    const removed = await trollbox.remove(where.room, child, who.id, moderator);
-                    json(response, removed ? 200 : 404, removed ? { ok: true } : { error: "not your line, or already gone" });
+                    json(response, 201, { message: { id: line.id, handle: line.handle, body: line.body, createdAt: line.createdAt } });
                     return;
                 }
-                json(response, 405, { error: "GET, POST or DELETE" });
+                json(response, 405, { error: "GET or POST" });
             }
             catch (error) {
                 if (error instanceof TrollboxError)
@@ -2373,7 +2357,7 @@ export function createHandler(engine, options) {
                     readOnThePhone(where, who.id, line.handle, line.body);
                     json(response, 201, {
                         ...said,
-                        message: { id: line.id, handle: line.handle, body: line.body, createdAt: line.createdAt, mine: true },
+                        message: { id: line.id, handle: line.handle, body: line.body, createdAt: line.createdAt },
                     });
                     return;
                 }
@@ -2387,6 +2371,141 @@ export function createHandler(engine, options) {
             }
             return;
         }
+        /*
+         * One address per file: /hash/<sha256>, the record of the bytes (see
+         * media.ts). As a page for a person, as an OpenFile file object or plain
+         * JSON for a program, and its transcript as subtitles. Reading is open:
+         * the id is the hash of the bytes, and whoever has it has the file.
+         * Keeping (PUT on the API) is signed in, like the ear.
+         */
+        if (path === "/.well-known/openfile.json" && options.records && options.site) {
+            json(response, 200, openFileListing(await options.records.recent(), options.site));
+            return;
+        }
+        if ((path.startsWith("/hash/") || path === "/api/v1/media" || path.startsWith("/api/v1/media/")) && options.records && options.transcripts && options.site) {
+            const media = options.records;
+            const store = options.transcripts;
+            const site = options.site;
+            const viaApi = path.startsWith("/api/v1/media");
+            const tail = viaApi ? path.slice("/api/v1/media".length).replace(/^\//, "") : path.slice("/hash/".length);
+            const parts = /^([^/.]+)(?:\.(openfile\.json|json|srt|vtt|txt))?\/?$/.exec(tail);
+            if (!parts) {
+                json(response, 404, { error: "a file is /hash/<sha256>, with .json, .openfile.json, .srt, .vtt or .txt after it" });
+                return;
+            }
+            let named = "";
+            try {
+                named = decodeURIComponent(parts[1]);
+            }
+            catch {
+                json(response, 400, { error: "bad id" });
+                return;
+            }
+            const format = parts[2] ?? "";
+            try {
+                if (request.method === "PUT" && viaApi) {
+                    const who = await options.accounts?.whoIs(tokenFrom(request.headers));
+                    if (!who) {
+                        json(response, 401, { error: "sign in to nixamp.com to keep a file's record" });
+                        return;
+                    }
+                    const id = mediaId(named);
+                    if (!id) {
+                        json(response, 400, { error: "the id is the file's SHA-256, hex" });
+                        return;
+                    }
+                    let body = {};
+                    try {
+                        body = JSON.parse(await readBody(request, 256 * 1024));
+                    }
+                    catch {
+                        json(response, 400, { error: "bad JSON" });
+                        return;
+                    }
+                    const saved = await media.save({
+                        id,
+                        ...(typeof body.name === "string" ? { name: body.name.trim() } : {}),
+                        ...(typeof body.size === "number" && body.size >= 0 ? { size: Math.floor(body.size) } : {}),
+                        ...(typeof body.contentType === "string" ? { contentType: body.contentType.trim().slice(0, 100) } : {}),
+                        ...(typeof body.updated === "string" && !Number.isNaN(Date.parse(body.updated)) ? { updated: new Date(body.updated).toISOString() } : {}),
+                        facts: factsFromRequest(body.facts),
+                        holder: holderFrom(body.holder),
+                        by: who.id,
+                    });
+                    if (!saved) {
+                        json(response, 500, { error: "the record was not kept" });
+                        return;
+                    }
+                    json(response, 200, openFileOf(saved, site, saved.facts.fingerprint ? await store.languages(transcriptIdOf(saved.facts.fingerprint)) : []));
+                    return;
+                }
+                if (request.method !== "GET") {
+                    json(response, 405, { error: "GET the record, or PUT what you know" });
+                    return;
+                }
+                // By the SHA-256, by the transcript store's fingerprint, or by a transcript id.
+                let record = null;
+                const hex = mediaId(named);
+                if (hex)
+                    record = await media.get(hex);
+                if (!record && /^file:v1:[0-9a-f]{64}$/.test(named))
+                    record = await media.byFingerprint(named);
+                if (!record && hex) {
+                    const transcript = await store.get(hex);
+                    if (transcript && transcript.kind === "file")
+                        record = await media.byFingerprint(transcript.media);
+                }
+                if (!record) {
+                    json(response, 404, { error: "nixamp.com does not know that file yet. `nixamp hash FILE` tells it." });
+                    return;
+                }
+                const transcriptId = record.facts.fingerprint ? transcriptIdOf(record.facts.fingerprint) : null;
+                const languages = transcriptId ? await store.languages(transcriptId) : [];
+                if (format === "srt" || format === "vtt" || format === "txt") {
+                    const language = languageCode(url.searchParams.get("language"));
+                    if (language === null) {
+                        json(response, 400, { error: "language is a two-letter code" });
+                        return;
+                    }
+                    const transcript = transcriptId ? await store.get(transcriptId, language) : null;
+                    if (!transcript) {
+                        json(response, 404, { error: language ? `not written down in ${language}` : "not written down yet" });
+                        return;
+                    }
+                    const text = format === "srt" ? toSrt(transcript.lines) : format === "vtt" ? toVtt(transcript.lines) : toText(transcript.lines);
+                    const name = (record.name.replace(/\.[^.]+$/, "") || record.id.slice(0, 12)).replace(/[^\w.-]+/g, "_").slice(0, 60);
+                    response.writeHead(200, {
+                        ...CORS,
+                        "content-type": `${format === "vtt" ? "text/vtt" : "text/plain"}; charset=utf-8`,
+                        "content-length": Buffer.byteLength(text),
+                        "cache-control": "public, max-age=300",
+                        "content-disposition": `inline; filename="${name}${transcript.language ? `.${transcript.language}` : ""}.${format}"`,
+                    });
+                    response.end(text);
+                    return;
+                }
+                const descriptor = openFileOf(record, site, languages);
+                const accept = String(request.headers["accept"] ?? "");
+                const wantsJson = viaApi || format === "json" || format === "openfile.json" || (accept.includes("application/json") && !accept.includes("text/html"));
+                if (wantsJson) {
+                    json(response, 200, descriptor);
+                    return;
+                }
+                const original = transcriptId ? await store.get(transcriptId) : null;
+                const forPage = languages
+                    .slice()
+                    .sort((a, b) => (a.translatedFrom === null ? -1 : 0) - (b.translatedFrom === null ? -1 : 0))
+                    .map((one) => (original && one.language === original.language && one.translatedFrom === null ? { ...one, shown: original.lines } : one));
+                html(response, 200, mediaPage(record, site, forPage));
+            }
+            catch (error) {
+                if (error instanceof SpeechError)
+                    json(response, error.status, { error: error.message });
+                else
+                    throw error;
+            }
+            return;
+        }
         /*
          * Translation: texts in one language, said in another, by a model on
          * this CPU (see translate.ts). Signed in only, like the ear. GET says
@@ -5178,6 +5297,8 @@ export async function serve(argv, version = "0.1.0") {
     // What was heard, kept: where the accounts are, under the media's identity.
     const transcripts = pool ? new Transcripts(pool, (message) => console.log(message)) : undefined;
     const translations = transcripts ? new StoredTranslations(transcripts, translator, (message) => console.log(message)) : undefined;
+    // The record of every file nixamp has met, by its bytes: nixamp.com/hash/<id>.
+    const records = pool ? new Media(pool, (message) => console.log(message)) : undefined;
     // nixamp as an OAuth 2.1 authorization server, and the watch parties a
     // client site bridges through it. Both need the same three things -- a
     // database, accounts, and a site to be the issuer of -- so both appear or
@@ -5383,7 +5504,29 @@ export async function serve(argv, version = "0.1.0") {
                         return { ...base, media: mediaOfUrl(pasted), position: info.position };
                     }
                     try {
-                        return { ...base, media: fileFingerprint(info.source), position: info.position };
+                        const source = info.source;
+                        return {
+                            ...base,
+                            media: fileFingerprint(source),
+                            position: info.position,
+                            // The file itself, for nixamp.com/hash/<id>: hashed here, once,
+                            // with what ffprobe and nichedb said and where it is on the air.
+                            describe: async () => {
+                                const listen = publishable_ ? shareLink(publishable_.url, listenKey, false) : (options.publicUrl || `http://${options.host}:${options.port}`);
+                                const described = await describeFile(source, {
+                                    tools,
+                                    enricher: enricher ?? null,
+                                    holder: { kind: "gateway", url: listen, seenAt: new Date().toISOString(), channel: id, name: streamName },
+                                });
+                                try {
+                                    remember(source, { id: described.id, fingerprint: described.fingerprint, size: described.size, mtimeMs: described.mtimeMs });
+                                }
+                                catch {
+                                    // The index is a convenience.
+                                }
+                                return { id: described.id, keep: described.keep };
+                            },
+                        };
                     }
                     catch {
                         return null;
@@ -5394,6 +5537,27 @@ export async function serve(argv, version = "0.1.0") {
             },
         })
         : undefined;
+    // The files this machine has told nixamp.com about, looked at again on
+    // their own schedule (media-index.ts): a changed file is a new record.
+    if (tools.carries) {
+        const watch = async () => {
+            const signed = readSession();
+            if (!signed)
+                return;
+            const counts = await watchOnce({
+                refresh: (file, before) => refreshChanged(signed, file, before, { tools, enricher: enricher ?? null }),
+                onEvent: (message) => console.log(`  ${message}`),
+            }).catch((error) => {
+                console.log(`  the media index could not be read: ${error.message}`);
+                return null;
+            });
+            if (counts && counts.changed > 0)
+                console.log(`  ${counts.changed} file(s) changed since nixamp.com last heard of them; told it`);
+        };
+        const watching = setInterval(() => void watch(), WATCH_EVERY_MS);
+        watching.unref?.();
+        setTimeout(() => void watch(), 60_000).unref?.();
+    }
     const owner = new Owner({
         ownerId: options.owner || (session?.token ? await ownerIdOf(session) : ""),
         site: session?.site ?? DEFAULT_DIRECTORY,
@@ -5598,6 +5762,7 @@ export async function serve(argv, version = "0.1.0") {
         ...(translator ? { translator } : {}),
         ...(transcripts ? { transcripts } : {}),
         ...(translations ? { translations } : {}),
+        ...(records ? { records } : {}),
         site: nixampSite,
         // Other people's OpenProfiles, read for the voice a line is spoken in,
         // and the voices to speak in: ElevenLabs when the Telnyx account holds

package/dist/transcribe.js

@@ -24,6 +24,8 @@ 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 { Enricher } from "./enrich.js";
+import { describeFile, keepFile } from "./media-local.js";
 import { readSession } from "./session.js";
 import { MAX_SECONDS, RATE, isWav } from "./speech.js";
 import { fetchTranscript, keepLines } from "./transcript-client.js";
@@ -372,6 +374,24 @@ export async function transcribe(argv, deps = {}) {
     }
     const id = transcriptIdOf(media);
     const title = /^https?:\/\//.test(file) ? file : basename(file, extname(file));
+    // A file gets its address at nixamp.com/hash/<sha256> too, with what this
+    // machine knows about it, so the transcript has somewhere to hang.
+    if (!/^https?:\/\//.test(file) && !deps.fingerprint) {
+        void (async () => {
+            try {
+                const tools = detectTools();
+                const described = await describeFile(file, { tools, enricher: new Enricher() });
+                const refused = await keepFile(signed, file, described, { fetcher });
+                if (refused)
+                    console.error(`  The file's record was not kept: ${refused}`);
+                else
+                    console.error(`  ${site}/hash/${described.id}`);
+            }
+            catch {
+                // The transcript is the point; the record is a bonus.
+            }
+        })();
+    }
     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.");

package/dist/transcript-client.d.ts

@@ -69,6 +69,25 @@ export interface Translated {
 }
 /** 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>>;
+/** What a machine tells nixamp.com about a file it has, for the record at /hash/<id>. */
+export interface MediaToKeep {
+    name?: string;
+    size?: number;
+    contentType?: string;
+    updated?: string;
+    facts?: Record<string, unknown>;
+    holder?: {
+        kind?: string;
+        url: string;
+        seenAt?: string;
+        channel?: string;
+        name?: string;
+    };
+}
+/** Keep what is known about a file, by its SHA-256 hex. */
+export declare function keepMedia(signed: Signed, id: string, ask: MediaToKeep, fetcher?: typeof fetch): Promise<Got<Record<string, unknown>>>;
+/** The record of a file, by id, fingerprint or transcript id. Public: no token needed. */
+export declare function fetchMedia(site: string, id: string, fetcher?: typeof fetch): Promise<Got<Record<string, unknown>>>;
 /** 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;

package/dist/transcript-client.js

@@ -51,6 +51,30 @@ export async function translateTexts(signed, texts, from, to, fetcher = fetch) {
         return unreachable(signed.site, error);
     }
 }
+/** Keep what is known about a file, by its SHA-256 hex. */
+export async function keepMedia(signed, id, ask, fetcher = fetch) {
+    try {
+        const response = await fetcher(`${base(signed.site)}/api/v1/media/${encodeURIComponent(id)}`, {
+            method: "PUT",
+            headers: { authorization: `Bearer ${signed.token}`, "content-type": "application/json" },
+            body: JSON.stringify(ask),
+        });
+        return await asJson(response);
+    }
+    catch (error) {
+        return unreachable(signed.site, error);
+    }
+}
+/** The record of a file, by id, fingerprint or transcript id. Public: no token needed. */
+export async function fetchMedia(site, id, fetcher = fetch) {
+    try {
+        const response = await fetcher(`${base(site)}/api/v1/media/${encodeURIComponent(id)}`, { headers: { accept: "application/json" } });
+        return await asJson(response);
+    }
+    catch (error) {
+        return unreachable(site, error);
+    }
+}
 /** Forget some media's transcripts. Only whoever stored them may. */
 export async function forgetTranscript(signed, id, fetcher = fetch) {
     try {

package/dist/trollbox.d.ts

@@ -40,14 +40,13 @@ export declare class Trollbox {
     private readonly spoke;
     constructor(db: Queryable, now?: () => number);
     private ensure;
-    /** The room's lines, oldest first, after a moment when given. */
+    /**
+     * The room's lines, oldest first, after a moment when given. Nothing
+     * writes deleted_at any more; the filter only keeps the lines taken down
+     * before a sent line became public record out of view.
+     */
     messages(room: string, after?: string, limit?: number): Promise<TrollboxMessage[]>;
     /** Whether this account may speak now, and the bookkeeping if so. */
     private allow;
     post(where: TrollboxRoom, authorId: string, handle: string, body: unknown): Promise<TrollboxMessage>;
-    /**
-     * A line taken down: by its author, or by a moderator (whoever owns the
-     * server's listing). Anybody else's ask removes nothing and says so.
-     */
-    remove(room: string, id: string, byAccount: string, moderator: boolean): Promise<boolean>;
 }

package/package.json

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

package/src/captions.ts

@@ -33,7 +33,7 @@
 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 { fetchTranscript, keepLines, keepMedia, translateTexts, type MediaToKeep } from "./transcript-client.ts";
 import { covered, lineAt, transcriptIdOf, type TranscriptLine } from "./transcripts.ts";
 
 export interface CaptionLine {
@@ -69,6 +69,12 @@ export interface ChannelMedia {
   startedAt: number;
   /** How many seconds behind the live edge a new listener's sound starts. */
   backlog: number;
+  /**
+   * The file itself, described for the record at nixamp.com/hash/<id>:
+   * its SHA-256 and what is known about it. Absent for anything that is
+   * not a file on this machine. Asked once when the captioner starts.
+   */
+  describe?: () => Promise<{ id: string; keep: MediaToKeep } | null>;
 }
 
 export interface CaptionsOptions {
@@ -220,6 +226,8 @@ export interface CaptionStatus {
   known: number;
   /** The languages lines are being given in besides the original. */
   languages: string[];
+  /** The file's SHA-256, once it has been described for nixamp.com/hash/<id>; "" until then, or for a live. */
+  hash: string;
 }
 
 class Captioner {
@@ -232,6 +240,8 @@ class Captioner {
   error = "";
   /** What the ear says the sound is in, or the store said it was; "" until one of them has. */
   language = "";
+  /** The file's SHA-256, once described. */
+  hash = "";
   private model = "";
   private decoder: Decoder | null = null;
   private detach: (() => void) | null = null;
@@ -288,9 +298,28 @@ class Captioner {
       return false;
     }
     void this.consult("");
+    void this.record();
     return true;
   }
 
+  /** Tell nixamp.com about the file itself, once: its hash and what this server knows of it. */
+  private async record(): Promise<void> {
+    const describe = this.media?.describe;
+    if (!describe) return;
+    const session = this.options.session();
+    if (session === null) return;
+    try {
+      const described = await describe();
+      if (!described || this.stopped) return;
+      this.hash = described.id;
+      const got = await keepMedia(session, described.id, described.keep, this.options.fetcher ?? fetch);
+      if (!got.ok) this.complain(`the record was not kept: ${got.error}`);
+      else this.options.onEvent?.(`captions for "${this.id}": nixamp.com/hash/${described.id.slice(0, 12)}… knows this file`);
+    } catch (error) {
+      this.complain(`could not describe the file: ${(error as Error).message}`);
+    }
+  }
+
   /** 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;
@@ -512,6 +541,7 @@ class Captioner {
       language: this.language,
       known: this.known.get("")?.length ?? 0,
       languages: [...this.linesBy.keys()],
+      hash: this.hash,
     };
   }
 
@@ -572,7 +602,7 @@ export class Captions {
   /** Whether a channel is being captioned, and what last went wrong if the lines are not coming. */
   status(id: string): CaptionStatus {
     const captioner = this.running.get(id);
-    return captioner ? captioner.status() : { on: false, lines: 0, error: "", language: "", known: 0, languages: [] };
+    return captioner ? captioner.status() : { on: false, lines: 0, error: "", language: "", known: 0, languages: [], hash: "" };
   }
 
   stopAll(): void {

package/src/hash.ts

@@ -0,0 +1,139 @@
+/**
+ * `nixamp hash` -- one address for a file: nixamp.com/hash/<sha256>.
+ *
+ * Hashes every byte, says the address, and unless told not to tells
+ * nixamp.com what this machine knows about the file (media-local.ts) so
+ * the address answers with it: what is inside, what nichedb says it is,
+ * and, once `nixamp transcribe` or a server has been at it, the
+ * transcript in every language. The file goes into this machine's index
+ * too, so the daemon looks at it again on a schedule and a changed file
+ * gets a new address that points back at this one.
+ */
+import { detectTools } from "./audio.ts";
+import { Enricher } from "./enrich.ts";
+import { describeFile, keepFile, type Described } from "./media-local.ts";
+import { readSession, type Session } from "./session.ts";
+import { fetchMedia } from "./transcript-client.ts";
+
+const HELP = `nixamp hash — one address for a file.
+
+  nixamp hash FILE [FILE...]        sha256, and nixamp.com/hash/<sha256>, kept there with what is known
+  nixamp hash FILE --no-keep        the hash and the address only; nothing sent
+  nixamp hash FILE --json           the record as nixamp.com keeps it
+  nixamp hash --get ID              what nixamp.com knows about a file, by hash or fingerprint
+
+The address is the SHA-256 of the file's bytes, the way OpenFile
+(logicsrc.com/docs/openfile) names a file, so the same file on two
+machines is one page. What is kept: the size, the type, when the file last
+changed, what ffprobe found inside, what nichedb.dev says it is, where it
+has been carried, and its transcripts. Keeping needs a sign-in
+(\`nixamp login\`); the hash needs nothing.
+`;
+
+export interface HashDeps {
+  fetcher?: typeof fetch;
+  session?: Pick<Session, "site" | "token"> | null;
+  describe?: (path: string) => Promise<Described>;
+  index?: string;
+  now?: () => number;
+}
+
+function flag(argv: string[], name: string): string | undefined {
+  const at = argv.indexOf(name);
+  return at === -1 ? undefined : argv[at + 1];
+}
+
+/** The site an address is printed for: the session's, or nixamp.com. */
+function siteOf(session: Pick<Session, "site"> | null): string {
+  return (session?.site ?? "https://nixamp.com").replace(/\/+$/, "");
+}
+
+export async function hash(argv: string[], deps: HashDeps = {}): Promise<number> {
+  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;
+  const fetcher = deps.fetcher ?? fetch;
+  const asJson = argv.includes("--json");
+  const site = siteOf(session);
+
+  const get = flag(argv, "--get");
+  if (argv.includes("--get")) {
+    if (!get) {
+      console.error("nixamp: --get needs the file's hash, or its fingerprint.");
+      return 64;
+    }
+    const got = await fetchMedia(site, get, fetcher);
+    if (!got.ok) {
+      console.error(`nixamp: ${got.error}`);
+      return 1;
+    }
+    if (asJson) console.log(JSON.stringify(got.body, null, 2));
+    else console.log(describeRecord(got.body));
+    return 0;
+  }
+
+  const files = argv.filter((one, at) => !one.startsWith("-") && !(at > 0 && argv[at - 1] === "--get"));
+  if (files.length === 0) {
+    console.error("nixamp: which file? `nixamp hash film.mkv`.");
+    return 64;
+  }
+  const keep = !argv.includes("--no-keep");
+  if (keep && session === null) console.error("nixamp: not signed in, so nothing is kept; `nixamp login` to keep the record. The hash still is:");
+  let tools: ReturnType<typeof detectTools> | null = null;
+  let enricher: Enricher | null = null;
+  const describe = deps.describe ?? (async (path: string) => {
+    tools ??= detectTools();
+    enricher ??= new Enricher();
+    return describeFile(path, { tools, enricher, now: deps.now });
+  });
+  let failed = 0;
+  const records: unknown[] = [];
+  for (const file of files) {
+    let described: Described;
+    try {
+      described = await describe(file);
+    } catch (error) {
+      console.error(`nixamp: ${file}: ${(error as Error).message}`);
+      failed += 1;
+      continue;
+    }
+    let record: Record<string, unknown> | null = null;
+    if (keep && session) {
+      const refused = await keepFile({ site: session.site, token: session.token }, file, described, { fetcher, ...(deps.index ? { index: deps.index } : {}), ...(deps.now ? { now: deps.now } : {}) });
+      if (refused) {
+        console.error(`nixamp: ${file}: not kept: ${refused}`);
+        failed += 1;
+      } else if (asJson) {
+        const got = await fetchMedia(site, described.id, fetcher);
+        record = got.ok ? got.body : null;
+      }
+    }
+    if (asJson) {
+      records.push(record ?? { id: `sha256:${described.id}`, name: described.keep.name, url: `${site}/hash/${described.id}`, nixamp: described.keep.facts });
+    } else {
+      console.log(`sha256:${described.id}  ${described.keep.name ?? file}\n  ${site}/hash/${described.id}${keep && session ? "" : "  (not kept)"}`);
+    }
+  }
+  if (asJson) console.log(JSON.stringify(records.length === 1 ? records[0] : records, null, 2));
+  return failed > 0 ? 1 : 0;
+}
+
+/** A record as the terminal prints it. */
+export function describeRecord(record: Record<string, unknown>): string {
+  const nixamp = (record["nixamp"] ?? {}) as Record<string, unknown>;
+  const lines = [`${record["name"] ?? ""}  ${record["id"] ?? ""}`, `  ${record["url"] ?? ""}`];
+  if (typeof record["size"] === "number") lines.push(`  size: ${record["size"]} bytes${record["contentType"] ? `, ${record["contentType"]}` : ""}`);
+  if (typeof nixamp["duration"] === "number") lines.push(`  length: ${Math.round(nixamp["duration"] as number)} s`);
+  const enrichment = nixamp["enrichment"] as { title?: string; year?: number | null } | undefined;
+  if (enrichment?.title) lines.push(`  nichedb: ${enrichment.title}${enrichment.year ? ` (${enrichment.year})` : ""}`);
+  if (record["updated"]) lines.push(`  file changed: ${record["updated"]}`);
+  if (nixamp["checkAfter"]) lines.push(`  next check: ${nixamp["checkAfter"]}`);
+  const holders = (record["holders"] ?? []) as { url: string; channel?: string; seenAt: string }[];
+  for (const holder of holders) lines.push(`  carried by ${holder.url}${holder.channel ? ` as ${holder.channel}` : ""} at ${holder.seenAt}`);
+  const transcripts = (nixamp["transcripts"] ?? []) as { language: string; translatedFrom: string | null; lines: number; complete: boolean; url: string }[];
+  for (const one of transcripts) lines.push(`  transcript ${one.language || "as spoken"}${one.translatedFrom ? ` (from ${one.translatedFrom})` : ""}: ${one.lines} lines${one.complete ? "" : " so far"}  ${one.url}`);
+  if (nixamp["supersededBy"]) lines.push(`  became: ${nixamp["supersededBy"]}`);
+  return lines.join("\n");
+}