nixamp 0.24.2 → 0.25.1

package/README.md

@@ -459,6 +459,44 @@ and a page that asks for it reads what there is so far. An agent has
 `transcript_get` and `transcripts_list`, and `transcribe_audio` keeps a film
 the same way.
 
+### One address per file: nixamp.com/hash/ID
+
+Every file nixamp meets gets a page at `/hash/<sha256>`, the SHA-256 of its
+bytes, the way OpenFile (logicsrc.com/docs/openfile) names a file, so the same
+film on two machines is one page. The page, and the OpenFile descriptor beside
+it, carry the size, the type, when the file last changed, what ffprobe found
+inside, what nichedb.dev says it is, which servers have carried it and as which
+channel, and its transcripts in every language, as subtitle files. Whoever
+meets the file fills it in: `nixamp hash`, `nixamp transcribe`, and a server
+that puts the file on the air.
+
+```
+nixamp hash FILE                  the hash, the address, and what is known, kept
+nixamp hash FILE --no-keep        the hash and the address only
+nixamp hash --get ID              what nixamp.com knows, by hash or fingerprint
+```
+
+```
+GET /hash/ID                      the page; JSON when Accept says so
+GET /hash/ID.json                 the OpenFile file object with nixamp's facts under `nixamp`
+GET /hash/ID.openfile.json        the same, as a descriptor
+GET /hash/ID.srt                  the transcript as subtitles; .vtt, .txt; ?language=de
+GET /api/v1/media/ID              the record; PUT it, signed in, with what you know
+GET /.well-known/openfile.json    every file nixamp.com knows, as a publisher's listing
+```
+
+ID is the hash with or without `sha256:`, the transcript store's fingerprint,
+or a transcript id. Reading is open, since the hash of the bytes is the file;
+keeping is signed in.
+
+A file changes. The machine holding it keeps an index of what it has told
+nixamp.com and looks at each file again on a schedule set by how recently it
+changed: a quarter of the time since its last change, between a quarter of an
+hour and a month, so a file being edited is checked often and a film from 2019
+once a month. A stat is all it costs until something moved; then the file is
+hashed again, the new record says what it was and the old one what it became.
+An agent has `media_hash` and `media_get`.
+
 ### In another language
 
 Ask for a language and the lines come translated, by an open-source model on

package/dist/captions.d.ts

@@ -1,4 +1,5 @@
 import type { Listener } from "./channels.ts";
+import { type MediaToKeep } from "./transcript-client.ts";
 import { lineAt } from "./transcripts.ts";
 export interface CaptionLine {
     /** The channel's id. */
@@ -31,6 +32,15 @@ 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 {
     /** A listener on a channel, or null when there is no such channel. */
@@ -99,6 +109,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;
 }
 export declare class Captions {
     private readonly options;

package/dist/captions.js

@@ -32,7 +32,7 @@
  */
 import { spawn } from "node:child_process";
 import { RATE } from "./speech.js";
-import { fetchTranscript, keepLines, translateTexts } from "./transcript-client.js";
+import { fetchTranscript, keepLines, keepMedia, translateTexts } from "./transcript-client.js";
 import { covered, lineAt, transcriptIdOf } from "./transcripts.js";
 export const WINDOW_MS = 5000;
 /** Lines kept per channel for whoever arrives late. */
@@ -162,6 +162,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 = "";
     model = "";
     decoder = null;
     detach = null;
@@ -212,8 +214,32 @@ 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. */
+    async record() {
+        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.message}`);
+        }
+    }
     /** Ask the store what it already knows of this media in a language, once. */
     async consult(language) {
         if (!this.transcriptId || this.asked.has(language))
@@ -463,6 +489,7 @@ class Captioner {
             language: this.language,
             known: this.known.get("")?.length ?? 0,
             languages: [...this.linesBy.keys()],
+            hash: this.hash,
         };
     }
     stop() {
@@ -523,7 +550,7 @@ export class Captions {
     /** Whether a channel is being captioned, and what last went wrong if the lines are not coming. */
     status(id) {
         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() {
         for (const captioner of [...this.running.values()])

package/dist/hash.d.ts

@@ -0,0 +1,12 @@
+import { type Described } from "./media-local.ts";
+import { type Session } from "./session.ts";
+export interface HashDeps {
+    fetcher?: typeof fetch;
+    session?: Pick<Session, "site" | "token"> | null;
+    describe?: (path: string) => Promise<Described>;
+    index?: string;
+    now?: () => number;
+}
+export declare function hash(argv: string[], deps?: HashDeps): Promise<number>;
+/** A record as the terminal prints it. */
+export declare function describeRecord(record: Record<string, unknown>): string;

package/dist/hash.js

@@ -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.js";
+import { Enricher } from "./enrich.js";
+import { describeFile, keepFile } from "./media-local.js";
+import { readSession } from "./session.js";
+import { fetchMedia } from "./transcript-client.js";
+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.
+`;
+function flag(argv, name) {
+    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) {
+    return (session?.site ?? "https://nixamp.com").replace(/\/+$/, "");
+}
+export async function hash(argv, deps = {}) {
+    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 = null;
+    let enricher = null;
+    const describe = deps.describe ?? (async (path) => {
+        tools ??= detectTools();
+        enricher ??= new Enricher();
+        return describeFile(path, { tools, enricher, now: deps.now });
+    });
+    let failed = 0;
+    const records = [];
+    for (const file of files) {
+        let described;
+        try {
+            described = await describe(file);
+        }
+        catch (error) {
+            console.error(`nixamp: ${file}: ${error.message}`);
+            failed += 1;
+            continue;
+        }
+        let record = 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) {
+    const nixamp = (record["nixamp"] ?? {});
+    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"])} s`);
+    const enrichment = nixamp["enrichment"];
+    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"] ?? []);
+    for (const holder of holders)
+        lines.push(`  carried by ${holder.url}${holder.channel ? ` as ${holder.channel}` : ""} at ${holder.seenAt}`);
+    const transcripts = (nixamp["transcripts"] ?? []);
+    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");
+}

package/dist/main.js

@@ -63,6 +63,7 @@ const HELP = `nixamp — it really whips the terminal's ass.
   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 hash FILE               one address for a file: nixamp.com/hash/<sha256>, with all that is known
   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
@@ -248,9 +249,10 @@ 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,
+(transcripts_list), and text in another language (translate_text). The file
+tools: one address for a file (media_hash) and what nixamp.com knows about
+one (media_get). 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
@@ -283,6 +285,23 @@ 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\`.
+`,
+    hash: `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. The page, and /hash/<id>.openfile.json beside it, carry the
+size, the type, when the file last changed, what ffprobe found inside, what
+nichedb.dev says it is, which servers have carried it, and its transcripts
+in every language, as .srt, .vtt or text. \`nixamp transcribe\` and a server
+captioning a file keep the same record. The daemon looks at a kept file
+again on a schedule set by how recently it changed, and a changed file
+gets a new address that points back at the old one.
 `,
     translate: `nixamp translate — say it in another language.
 
@@ -559,6 +578,11 @@ export async function main() {
         process.exitCode = await translate(rest);
         return;
     }
+    if (first === "hash") {
+        const { hash } = await import("./hash.js");
+        process.exitCode = await hash(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,5 @@
 import { wavOf, type Window } from "./transcribe.ts";
+import { type Described } from "./media-local.ts";
 export declare const PROTOCOL_VERSION = "2025-06-18";
 interface Request {
     jsonrpc: "2.0";
@@ -27,6 +28,8 @@ export interface McpOptions {
     sleep?: (ms: number) => Promise<void>;
     /** How many times a translation is asked about before answering with its progress. */
     polls?: number;
+    /** How a file is described for its record; the tests hand in a fake. */
+    describe?: (path: string) => Promise<Described>;
     say?: (line: string) => void;
 }
 /** A tool answer, in the shape MCP wants: content blocks, and a flag for failure. */

package/dist/mcp.js

@@ -23,7 +23,11 @@ import { clock } from "./party.js";
 import { readSession } from "./session.js";
 import { askToHear, awaitTranscript, hearWhole, rendered, wavOf } from "./transcribe.js";
 import { readTranscript } from "./transcript.js";
-import { fetchTranscript, listTranscripts, translateTexts } from "./transcript-client.js";
+import { fetchMedia, fetchTranscript, listTranscripts, translateTexts } from "./transcript-client.js";
+import { detectTools } from "./audio.js";
+import { Enricher } from "./enrich.js";
+import { describeRecord } from "./hash.js";
+import { describeFile, keepFile } from "./media-local.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";
@@ -112,6 +116,23 @@ export const TOOLS = [
             required: ["media"],
         },
     },
+    {
+        name: "media_hash",
+        description: "One address for a file on this machine: its SHA-256 and nixamp.com/hash/<sha256>, kept there with what this machine knows (size, type, when it changed, what is inside, what nichedb says it is). The same file anywhere is the same page.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                path: { ...STRING, description: "The file's path on this machine." },
+                keep: { type: "boolean", description: "Tell nixamp.com about it (default true)." },
+            },
+            required: ["path"],
+        },
+    },
+    {
+        name: "media_get",
+        description: "What nixamp.com knows about a file, by its SHA-256 (with or without sha256:), its transcript fingerprint, or a transcript id: the OpenFile record with nixamp's facts, holders and transcripts.",
+        inputSchema: { type: "object", properties: { id: { ...STRING, description: "The hash, fingerprint or transcript id." } }, required: ["id"] },
+    },
     {
         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.",
@@ -394,6 +415,33 @@ export async function callTool(name, args, options = {}) {
             }
             return text(transcriptText(got.body, typeof args["format"] === "string" ? args["format"] : "lines"));
         }
+        if (name === "media_hash") {
+            const path = typeof args["path"] === "string" ? args["path"] : "";
+            if (!path)
+                return failed("Which file? Pass its path.");
+            let described;
+            try {
+                described = await (options.describe ?? ((file) => describeFile(file, { tools: detectTools(), enricher: new Enricher() })))(path);
+            }
+            catch (error) {
+                return failed(`${path}: ${error.message}`);
+            }
+            if (args["keep"] !== false) {
+                const refused = await keepFile({ site, token: session.token }, path, described, { fetcher: send });
+                if (refused)
+                    return failed(`hashed, but not kept: ${refused}`);
+            }
+            return text(`sha256:${described.id}\n${site}/hash/${described.id}${args["keep"] === false ? "\n(not kept)" : ""}`);
+        }
+        if (name === "media_get") {
+            const id = typeof args["id"] === "string" ? args["id"].trim() : "";
+            if (!id)
+                return failed("Which file? Pass its hash, fingerprint or transcript id.");
+            const got = await fetchMedia(site, id, send);
+            if (!got.ok)
+                return failed(got.error);
+            return text(describeRecord(got.body));
+        }
         if (name === "transcripts_list") {
             const got = await listTranscripts({ site, token: session.token }, send);
             if (!got.ok)

package/dist/media-index.d.ts

@@ -0,0 +1,67 @@
+export interface IndexedFile {
+    /** The SHA-256 hex nixamp.com knows it by. */
+    id: string;
+    fingerprint: string;
+    size: number;
+    mtimeMs: number;
+    checkedAt: number;
+    checkAfter: number;
+}
+export interface IndexFile {
+    version: 1;
+    files: Record<string, IndexedFile>;
+}
+export declare function indexPath(): string;
+export declare function readIndex(path?: string): IndexFile;
+export declare function writeIndex(index: IndexFile, path?: string): void;
+/** Note a file this machine has told nixamp.com about, with when to look at it next. */
+export declare function remember(file: string, entry: {
+    id: string;
+    fingerprint: string;
+    size: number;
+    mtimeMs: number;
+}, now?: number, path?: string): IndexedFile;
+/** The files whose turn it is. */
+export declare function due(index: IndexFile, now?: number): string[];
+export type Looked = {
+    state: "same";
+    entry: IndexedFile;
+} | {
+    state: "changed";
+    entry: IndexedFile;
+    size: number;
+    mtimeMs: number;
+} | {
+    state: "gone";
+};
+/**
+ * One look at a file: the same as it was, changed, or gone. Nothing is
+ * hashed here; the caller hashes a changed file, since that is the part
+ * that costs, and then remembers the new record.
+ */
+export declare function look(file: string, entry: IndexedFile, now?: number): Looked;
+/** How often the watcher reads the index for what is due. */
+export declare const WATCH_EVERY_MS: number;
+export interface WatchOptions {
+    path?: string;
+    now?: () => number;
+    /** Hash the changed file, tell nixamp.com, and answer the new entry; null when it could not. */
+    refresh: (file: string, before: IndexedFile, stat: {
+        size: number;
+        mtimeMs: number;
+    }) => Promise<{
+        id: string;
+        fingerprint: string;
+    } | null>;
+    onEvent?: (message: string) => void;
+}
+/**
+ * One pass over what is due. Files that are the same are pushed out to
+ * their next check; changed ones are refreshed; gone ones are forgotten.
+ * Answers how many of each, for the log.
+ */
+export declare function watchOnce(options: WatchOptions): Promise<{
+    same: number;
+    changed: number;
+    gone: number;
+}>;

package/dist/media-index.js

@@ -0,0 +1,114 @@
+/**
+ * The files this machine has told nixamp.com about, and when to look again.
+ *
+ * nixamp.com keeps the record (media.ts); the bytes stay here. So whether a
+ * file has changed is a question only this machine can answer, and it
+ * answers it on a schedule that follows the file: a quarter of the time
+ * since it last changed, never more often than every quarter of an hour
+ * and never less often than monthly (see checkInterval). Looking is one
+ * stat. Only a file whose size or modification time moved is hashed
+ * again, and a new hash is a new record on nixamp.com, with the old one
+ * told what it became.
+ *
+ * The index is a JSON file beside the daemon's other state. The CLI adds
+ * to it when it hashes or transcribes a file, the server when it captions
+ * one, and the server's watcher reads it every few minutes for what is
+ * due. Written whole and renamed into place, so two of them writing at
+ * once lose an entry at worst, never the file.
+ */
+import { mkdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { stateDir } from "./daemon.js";
+import { checkInterval } from "./media.js";
+export function indexPath() {
+    return process.env["NIXAMP_MEDIA_INDEX"] ?? join(stateDir(), "media.json");
+}
+export function readIndex(path = indexPath()) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, "utf8"));
+        if (parsed && parsed.version === 1 && parsed.files && typeof parsed.files === "object")
+            return { version: 1, files: parsed.files };
+    }
+    catch {
+        // No index yet, or one this cannot read: start again.
+    }
+    return { version: 1, files: {} };
+}
+export function writeIndex(index, path = indexPath()) {
+    mkdirSync(dirname(path), { recursive: true });
+    const temp = `${path}.${process.pid}.tmp`;
+    writeFileSync(temp, JSON.stringify(index, null, 2));
+    renameSync(temp, path);
+}
+/** Note a file this machine has told nixamp.com about, with when to look at it next. */
+export function remember(file, entry, now = Date.now(), path = indexPath()) {
+    const index = readIndex(path);
+    const kept = { ...entry, checkedAt: now, checkAfter: now + checkInterval(entry.mtimeMs, now) };
+    index.files[file] = kept;
+    writeIndex(index, path);
+    return kept;
+}
+/** The files whose turn it is. */
+export function due(index, now = Date.now()) {
+    return Object.entries(index.files).filter(([, one]) => one.checkAfter <= now).map(([file]) => file);
+}
+/**
+ * One look at a file: the same as it was, changed, or gone. Nothing is
+ * hashed here; the caller hashes a changed file, since that is the part
+ * that costs, and then remembers the new record.
+ */
+export function look(file, entry, now = Date.now()) {
+    let stat;
+    try {
+        stat = statSync(file);
+    }
+    catch {
+        return { state: "gone" };
+    }
+    if (stat.size === entry.size && Math.floor(stat.mtimeMs) === Math.floor(entry.mtimeMs)) {
+        return { state: "same", entry: { ...entry, checkedAt: now, checkAfter: now + checkInterval(entry.mtimeMs, now) } };
+    }
+    return { state: "changed", entry, size: stat.size, mtimeMs: stat.mtimeMs };
+}
+/** How often the watcher reads the index for what is due. */
+export const WATCH_EVERY_MS = 10 * 60 * 1000;
+/**
+ * One pass over what is due. Files that are the same are pushed out to
+ * their next check; changed ones are refreshed; gone ones are forgotten.
+ * Answers how many of each, for the log.
+ */
+export async function watchOnce(options) {
+    const now = options.now ?? Date.now;
+    const path = options.path ?? indexPath();
+    const index = readIndex(path);
+    const counts = { same: 0, changed: 0, gone: 0 };
+    for (const file of due(index, now())) {
+        const entry = index.files[file];
+        if (!entry)
+            continue;
+        const looked = look(file, entry, now());
+        if (looked.state === "gone") {
+            delete index.files[file];
+            counts.gone += 1;
+            continue;
+        }
+        if (looked.state === "same") {
+            index.files[file] = looked.entry;
+            counts.same += 1;
+            continue;
+        }
+        const fresh = await options.refresh(file, entry, { size: looked.size, mtimeMs: looked.mtimeMs });
+        const at = now();
+        if (fresh) {
+            index.files[file] = { ...fresh, size: looked.size, mtimeMs: looked.mtimeMs, checkedAt: at, checkAfter: at + checkInterval(looked.mtimeMs, at) };
+            counts.changed += 1;
+            options.onEvent?.(`${file} changed: now sha256:${fresh.id.slice(0, 12)} (was ${entry.id.slice(0, 12)})`);
+        }
+        else {
+            // Could not say; ask again in a quarter of an hour rather than never.
+            index.files[file] = { ...entry, checkedAt: at, checkAfter: at + 15 * 60 * 1000 };
+        }
+    }
+    writeIndex(index, path);
+    return counts;
+}

package/dist/media-local.d.ts

@@ -0,0 +1,43 @@
+import { type Tools } from "./audio.ts";
+import type { Enricher } from "./enrich.ts";
+import { type Holder } from "./media.ts";
+import { type IndexedFile } from "./media-index.ts";
+import { type MediaToKeep, type Signed } from "./transcript-client.ts";
+export interface Described {
+    id: string;
+    fingerprint: string;
+    size: number;
+    mtimeMs: number;
+    keep: MediaToKeep;
+}
+export interface DescribeDeps {
+    /** ffprobe, for what is inside. Absent: only what the filesystem says. */
+    tools?: Tools | null;
+    enricher?: Pick<Enricher, "lookup"> | null;
+    holder?: Holder | null;
+    now?: () => number;
+    /** The tests hand in fakes for the two things that cost. */
+    hash?: (path: string) => Promise<string>;
+    fingerprint?: (path: string) => string;
+}
+/** Everything this machine can say about a file, ready to keep. */
+export declare function describeFile(path: string, deps?: DescribeDeps): Promise<Described>;
+/** Keep a described file on nixamp.com and in this machine's index. Answers the store's sentence when it refused. */
+export declare function keepFile(signed: Signed, path: string, described: Described, deps?: {
+    fetcher?: typeof fetch;
+    index?: string;
+    now?: () => number;
+}): Promise<string | null>;
+/**
+ * A file that changed since it was last described: described again as a
+ * new record that says what it was, while the old record says what it
+ * became. Answers the new identity, or null when nixamp.com would not
+ * keep it.
+ */
+export declare function refreshChanged(signed: Signed, path: string, before: Pick<IndexedFile, "id">, deps?: DescribeDeps & {
+    fetcher?: typeof fetch;
+    index?: string;
+}): Promise<{
+    id: string;
+    fingerprint: string;
+} | null>;