nixamp 0.24.2 → 0.25.0

package/dist/media.js

@@ -0,0 +1,364 @@
+/**
+ * One address per file: nixamp.com/hash/<sha256>, and everything nixamp has
+ * learned about the bytes behind it.
+ *
+ * The transcript store keys a file by a quick fingerprint (see
+ * transcripts.ts), which is enough to know a file again. This is the other
+ * half: the record of the file itself, keyed by the SHA-256 of every byte,
+ * the way OpenFile (logicsrc.com/docs/openfile) names a file, so the same
+ * bytes on two machines are one record and a directory reading nixamp's
+ * listing dedupes on the same id as everybody else's.
+ *
+ * The record is an OpenFile file object. Its required keys are the id and
+ * a name; `size`, `contentType` and `updated` describe the bytes, `holders`
+ * says which nixamp servers have carried it, and everything nixamp itself
+ * found goes under a `nixamp` key, which is where the specification tells a
+ * publisher to put its own: the fingerprint, what ffprobe saw, what nichedb
+ * said it was, the transcripts and their languages, and when the file was
+ * last checked and is next due.
+ *
+ * A record is filled in by whoever meets the file: `nixamp hash`, `nixamp
+ * transcribe`, and a server captioning it. Each sends what it knows and the
+ * record keeps the union. A file that changes on disk gets a new hash and
+ * so a new record; the machine holding it notices (media-index.ts) and says
+ * which record the old one became.
+ */
+import { createHash } from "node:crypto";
+import { createReadStream, statSync } from "node:fs";
+import { basename, extname } from "node:path";
+/** How many places a record remembers carrying it. */
+export const MAX_HOLDERS = 50;
+/** The listing at /.well-known/openfile.json is this long at most. */
+export const LISTING = 100;
+/** A file changed an hour ago is looked at again in a quarter of an hour; one untouched for years, once a month. */
+export const CHECK_MIN_MS = 15 * 60 * 1000;
+export const CHECK_MAX_MS = 30 * 24 * 60 * 60 * 1000;
+const TYPES = {
+    mp4: "video/mp4", m4v: "video/mp4", mkv: "video/x-matroska", webm: "video/webm", mov: "video/quicktime", avi: "video/x-msvideo",
+    ts: "video/mp2t", m2ts: "video/mp2t", mpg: "video/mpeg", mpeg: "video/mpeg", wmv: "video/x-ms-wmv", flv: "video/x-flv",
+    mp3: "audio/mpeg", m4a: "audio/mp4", aac: "audio/aac", flac: "audio/flac", wav: "audio/wav", ogg: "audio/ogg", oga: "audio/ogg",
+    opus: "audio/opus", wma: "audio/x-ms-wma", aiff: "audio/aiff", aif: "audio/aiff", alac: "audio/mp4",
+    jpg: "image/jpeg", jpeg: "image/jpeg", png: "image/png", gif: "image/gif", webp: "image/webp",
+    pdf: "application/pdf", txt: "text/plain", md: "text/markdown", srt: "application/x-subrip", vtt: "text/vtt",
+    m3u: "audio/x-mpegurl", m3u8: "application/vnd.apple.mpegurl", pls: "audio/x-scpls", zip: "application/zip",
+};
+/** The media type a file's name suggests, or octet-stream. */
+export function contentTypeOf(path) {
+    return TYPES[extname(path).slice(1).toLowerCase()] ?? "application/octet-stream";
+}
+/** A media id as a request names one: bare hex or `sha256:` hex; the hex, or null. */
+export function mediaId(value) {
+    if (typeof value !== "string")
+        return null;
+    const hex = value.trim().toLowerCase().replace(/^sha256:/, "");
+    return /^[0-9a-f]{64}$/.test(hex) ? hex : null;
+}
+/** The SHA-256 of every byte of a file, as a stream so a film does not sit in memory. */
+export function contentHash(path) {
+    return new Promise((resolve, reject) => {
+        const hash = createHash("sha256");
+        const stream = createReadStream(path);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("error", reject);
+        stream.on("end", () => resolve(hash.digest("hex")));
+    });
+}
+/** What the filesystem says about a file: its size, when it changed, and its type. */
+export function fileFacts(path) {
+    const stat = statSync(path);
+    return { name: basename(path), size: stat.size, updated: new Date(stat.mtimeMs).toISOString(), contentType: contentTypeOf(path), mtimeMs: stat.mtimeMs };
+}
+/**
+ * How long to leave a file alone before looking at it again: a quarter of
+ * the time since it last changed, between a quarter of an hour and a
+ * month. A file being edited is looked at often; a film from 2019 is not
+ * stat'd every hour of every day for the rest of its life.
+ */
+export function checkInterval(mtimeMs, nowMs) {
+    const age = Math.max(0, nowMs - mtimeMs);
+    return Math.min(CHECK_MAX_MS, Math.max(CHECK_MIN_MS, Math.floor(age / 4)));
+}
+/** The facts ffprobe and nichedb give a server, as the record wants them. */
+export function factsFrom(codecs, enriched) {
+    const facts = {};
+    if (codecs) {
+        if (codecs.video || codecs.audio || codecs.container) {
+            facts.codecs = { ...(codecs.video ? { video: codecs.video } : {}), ...(codecs.audio ? { audio: codecs.audio } : {}), ...(codecs.container ? { container: codecs.container } : {}) };
+        }
+        if (codecs.duration)
+            facts.duration = Math.round(codecs.duration * 1000) / 1000;
+        if (codecs.width)
+            facts.width = codecs.width;
+        if (codecs.height)
+            facts.height = codecs.height;
+        if (codecs.tags && (codecs.tags.title || codecs.tags.artist || codecs.tags.album))
+            facts.tags = { ...codecs.tags };
+    }
+    if (enriched) {
+        facts.enrichment = {
+            kind: enriched.kind, title: enriched.title, year: enriched.year, image: enriched.image, summary: enriched.summary, page: enriched.page,
+        };
+    }
+    return facts;
+}
+/** Facts as a request hands them in: only the keys this file names, each of the right shape. */
+export function factsFromRequest(value) {
+    if (!value || typeof value !== "object")
+        return {};
+    const raw = value;
+    const facts = {};
+    const text = (key) => (typeof raw[key] === "string" && raw[key].trim() ? raw[key].trim().slice(0, 500) : undefined);
+    const num = (key) => (typeof raw[key] === "number" && Number.isFinite(raw[key]) && raw[key] >= 0 ? raw[key] : undefined);
+    const fp = text("fingerprint");
+    if (fp && /^file:v1:[0-9a-f]{64}$/.test(fp))
+        facts.fingerprint = fp;
+    if (num("duration") !== undefined)
+        facts.duration = num("duration");
+    if (num("width") !== undefined)
+        facts.width = num("width");
+    if (num("height") !== undefined)
+        facts.height = num("height");
+    if (raw["codecs"] && typeof raw["codecs"] === "object") {
+        const c = raw["codecs"];
+        const codecs = {};
+        for (const key of ["video", "audio", "container"])
+            if (typeof c[key] === "string" && c[key])
+                codecs[key] = c[key].slice(0, 80);
+        if (Object.keys(codecs).length > 0)
+            facts.codecs = codecs;
+    }
+    if (raw["tags"] && typeof raw["tags"] === "object") {
+        const t = raw["tags"];
+        const tags = {};
+        for (const key of ["title", "artist", "album"])
+            if (typeof t[key] === "string" && t[key])
+                tags[key] = t[key].slice(0, 300);
+        if (Object.keys(tags).length > 0)
+            facts.tags = tags;
+    }
+    if (raw["enrichment"] && typeof raw["enrichment"] === "object") {
+        const e = raw["enrichment"];
+        const enrichment = {};
+        for (const key of ["kind", "title", "image", "summary", "page"])
+            if (typeof e[key] === "string")
+                enrichment[key] = e[key].slice(0, 2000);
+        if (typeof e["year"] === "number")
+            enrichment.year = e["year"];
+        if (Object.keys(enrichment).length > 0)
+            facts.enrichment = enrichment;
+    }
+    for (const key of ["supersededBy", "supersedes"]) {
+        const id = mediaId(raw[key]);
+        if (id)
+            facts[key] = `sha256:${id}`;
+    }
+    for (const key of ["checkedAt", "checkAfter"]) {
+        const when = text(key);
+        if (when && !Number.isNaN(Date.parse(when)))
+            facts[key] = new Date(when).toISOString();
+    }
+    return facts;
+}
+/** A holder as a request hands it in, or null. */
+export function holderFrom(value) {
+    if (!value || typeof value !== "object")
+        return null;
+    const raw = value;
+    const url = typeof raw["url"] === "string" ? raw["url"].trim().slice(0, 500) : "";
+    if (!/^https?:\/\//.test(url))
+        return null;
+    const kind = raw["kind"] === "peer" || raw["kind"] === "seeder" ? raw["kind"] : "gateway";
+    return {
+        kind,
+        url,
+        seenAt: typeof raw["seenAt"] === "string" && !Number.isNaN(Date.parse(raw["seenAt"])) ? new Date(raw["seenAt"]).toISOString() : new Date().toISOString(),
+        ...(typeof raw["channel"] === "string" && raw["channel"] ? { channel: raw["channel"].slice(0, 80) } : {}),
+        ...(typeof raw["name"] === "string" && raw["name"] ? { name: raw["name"].slice(0, 200) } : {}),
+    };
+}
+/** Holders with one entry per address, the latest sighting kept, newest first. */
+export function mergeHolders(had, added) {
+    const byUrl = new Map();
+    for (const holder of [...had, ...added]) {
+        const key = holder.url.replace(/\/+$/, "");
+        const before = byUrl.get(key);
+        if (!before || Date.parse(holder.seenAt) >= Date.parse(before.seenAt))
+            byUrl.set(key, { ...before, ...holder });
+    }
+    return [...byUrl.values()].sort((a, b) => Date.parse(b.seenAt) - Date.parse(a.seenAt)).slice(0, MAX_HOLDERS);
+}
+// --- the store ---------------------------------------------------------------
+const SCHEMA = `
+  CREATE TABLE IF NOT EXISTS media (
+    id            TEXT PRIMARY KEY,
+    fingerprint   TEXT NOT NULL DEFAULT '',
+    name          TEXT NOT NULL DEFAULT '',
+    size          BIGINT NOT NULL DEFAULT 0,
+    content_type  TEXT NOT NULL DEFAULT '',
+    updated       TIMESTAMPTZ,
+    facts         JSONB NOT NULL DEFAULT '{}'::jsonb,
+    holders       JSONB NOT NULL DEFAULT '[]'::jsonb,
+    by_account    TEXT NOT NULL DEFAULT '',
+    created_at    TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at    TIMESTAMPTZ NOT NULL DEFAULT now()
+  );
+  CREATE INDEX IF NOT EXISTS media_by_fingerprint ON media (fingerprint);
+  CREATE INDEX IF NOT EXISTS media_recent ON media (updated_at DESC);
+`;
+export class Media {
+    db;
+    onEvent;
+    ready = null;
+    constructor(db, onEvent = () => { }) {
+        this.db = db;
+        this.onEvent = onEvent;
+    }
+    async ensure() {
+        this.ready ??= this.db.query(SCHEMA).then(() => undefined);
+        await this.ready;
+    }
+    /**
+     * Keep what somebody knows about a file. A new id is a new record; a known
+     * one keeps its union: facts merge key by key with the newer winning,
+     * holders merge by address, a name or a size given replaces one that was
+     * not. The account that first kept it stays its keeper.
+     */
+    async save(ask) {
+        await this.ensure();
+        const had = await this.get(ask.id);
+        const facts = { ...(had?.facts ?? {}), ...(ask.facts ?? {}) };
+        const holders = mergeHolders(had?.holders ?? [], ask.holder ? [ask.holder] : []);
+        const { rows } = await this.db.query(`INSERT INTO media (id, fingerprint, name, size, content_type, updated, facts, holders, by_account)
+       VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8::jsonb, $9)
+       ON CONFLICT (id) DO UPDATE SET
+         fingerprint = CASE WHEN EXCLUDED.fingerprint = '' THEN media.fingerprint ELSE EXCLUDED.fingerprint END,
+         name = CASE WHEN EXCLUDED.name = '' THEN media.name ELSE EXCLUDED.name END,
+         size = CASE WHEN EXCLUDED.size = 0 THEN media.size ELSE EXCLUDED.size END,
+         content_type = CASE WHEN EXCLUDED.content_type = '' THEN media.content_type ELSE EXCLUDED.content_type END,
+         updated = COALESCE(EXCLUDED.updated, media.updated),
+         facts = EXCLUDED.facts,
+         holders = EXCLUDED.holders,
+         updated_at = now()
+       RETURNING *`, [
+            ask.id,
+            facts.fingerprint ?? "",
+            (ask.name ?? "").slice(0, 300),
+            ask.size ?? 0,
+            ask.contentType ?? "",
+            ask.updated ?? null,
+            JSON.stringify(facts),
+            JSON.stringify(holders),
+            ask.by,
+        ]);
+        const row = rows[0];
+        return row ? rowToRecord(row) : null;
+    }
+    async get(id) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT * FROM media WHERE id = $1 LIMIT 1", [id]);
+        const row = rows[0];
+        return row ? rowToRecord(row) : null;
+    }
+    /** The record of the file a transcript fingerprint belongs to, the latest when there are several. */
+    async byFingerprint(fingerprint) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT * FROM media WHERE fingerprint = $1 ORDER BY updated_at DESC LIMIT 1", [fingerprint]);
+        const row = rows[0];
+        return row ? rowToRecord(row) : null;
+    }
+    /** The latest records, newest first, for the listing. */
+    async recent(limit = LISTING) {
+        await this.ensure();
+        const { rows } = await this.db.query("SELECT * FROM media ORDER BY updated_at DESC LIMIT $1", [Math.max(1, Math.min(LISTING, limit))]);
+        return rows.map(rowToRecord);
+    }
+    /** Never throws: a store that is having a moment costs the record, not the request. */
+    async quietly(what, run) {
+        try {
+            return await run();
+        }
+        catch (error) {
+            this.onEvent(`  ${what} did not persist: ${error.message}`);
+            return null;
+        }
+    }
+}
+function iso(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (typeof value === "string" && !Number.isNaN(Date.parse(value)))
+        return new Date(value).toISOString();
+    return "";
+}
+function parsed(value, fallback) {
+    if (typeof value === "string") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return value ?? fallback;
+}
+function rowToRecord(row) {
+    const facts = parsed(row["facts"], {});
+    return {
+        id: String(row["id"] ?? ""),
+        name: String(row["name"] ?? ""),
+        size: Number(row["size"] ?? 0),
+        contentType: String(row["content_type"] ?? ""),
+        updated: iso(row["updated"]),
+        facts: facts && typeof facts === "object" ? facts : {},
+        holders: (parsed(row["holders"], []) ?? []).filter((one) => one && typeof one.url === "string"),
+        by: String(row["by_account"] ?? ""),
+        createdAt: iso(row["created_at"]),
+        updatedAt: iso(row["updated_at"]),
+    };
+}
+/**
+ * The record as an OpenFile file object: the specification's keys at the
+ * top, nixamp's own under `nixamp`. `fetch` is empty on purpose: nixamp.com
+ * has no bytes to hand out, only what it knows about them; the holders are
+ * where they were last carried.
+ */
+export function openFileOf(record, site, transcripts = []) {
+    const base = site.replace(/\/+$/, "");
+    const facts = { ...record.facts };
+    return {
+        id: `sha256:${record.id}`,
+        name: record.name || record.id,
+        url: `${base}/hash/${record.id}`,
+        descriptor: `${base}/hash/${record.id}.openfile.json`,
+        ...(record.size ? { size: record.size } : {}),
+        ...(record.contentType ? { contentType: record.contentType } : {}),
+        encryption: "none",
+        fetch: [],
+        holders: record.holders.map((holder) => ({ kind: holder.kind, url: holder.url, seenAt: holder.seenAt, ...(holder.channel ? { channel: holder.channel } : {}), ...(holder.name ? { name: holder.name } : {}) })),
+        ...(record.updated ? { updated: record.updated } : {}),
+        nixamp: {
+            ...facts,
+            transcripts: transcripts.map((one) => ({
+                ...one,
+                url: `${base}/hash/${record.id}.srt${one.language ? `?language=${one.language}` : ""}`,
+            })),
+            kept: record.createdAt,
+            seen: record.updatedAt,
+        },
+    };
+}
+/** The publisher's descriptor: nixamp.com and its latest records. */
+export function openFileListing(records, site) {
+    const base = site.replace(/\/+$/, "");
+    return {
+        publisher: {
+            name: "nixamp",
+            web: base,
+            developer: {
+                cli: { name: "nixamp", install: { curl: "curl -fsSL https://nixamp.com/install.sh | sh" }, docs: "https://github.com/profullstack/nixamp#readme", repo: "https://github.com/profullstack/nixamp" },
+            },
+        },
+        updated: records[0]?.updatedAt ?? new Date(0).toISOString(),
+        files: records.map((record) => openFileOf(record, base)),
+    };
+}

package/dist/server.d.ts

@@ -35,6 +35,7 @@ import { Captions } from "./captions.ts";
 import { Translator } from "./translate.ts";
 import { StoredTranslations } from "./translate-jobs.ts";
 import { Transcripts } from "./transcripts.ts";
+import { Media } from "./media.ts";
 import { Profiles, Voices } from "./voices.ts";
 import { type Codecs } from "./audio.ts";
 import { type Tools, type Track } from "./audio.ts";
@@ -708,6 +709,8 @@ export interface HandlerOptions {
     transcripts?: Transcripts;
     /** Stored transcripts translated, as jobs. */
     translations?: StoredTranslations;
+    /** The record of every file nixamp has met, by its SHA-256: nixamp.com/hash/<id>. */
+    records?: Media;
     /** 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. */

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";
@@ -2367,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
@@ -5158,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
@@ -5363,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;
@@ -5374,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,
@@ -5578,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;