nixamp 0.24.2 → 0.25.1

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nixamp",
-  "version": "0.24.2",
+  "version": "0.25.1",
   "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");
+}

package/src/main.ts

@@ -87,6 +87,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
@@ -274,9 +275,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
@@ -309,6 +311,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.
 
@@ -588,6 +607,11 @@ export async function main(): Promise<void> {
     process.exitCode = await translate(rest);
     return;
   }
+  if (first === "hash") {
+    const { hash } = await import("./hash.ts");
+    process.exitCode = await hash(rest);
+    return;
+  }
   if (first === "token" || first === "tokens") {
     const { tokens } = await import("./session.ts");
     process.exitCode = await tokens(rest);

package/src/mcp.ts

@@ -23,7 +23,11 @@ import { clock, type PartyRow } from "./party.ts";
 import { readSession } from "./session.ts";
 import { askToHear, awaitTranscript, hearWhole, rendered, wavOf, type Window } from "./transcribe.ts";
 import { readTranscript } from "./transcript.ts";
-import { fetchTranscript, listTranscripts, translateTexts, type StoredTranscript } from "./transcript-client.ts";
+import { fetchMedia, fetchTranscript, listTranscripts, translateTexts, type StoredTranscript } from "./transcript-client.ts";
+import { detectTools } from "./audio.ts";
+import { Enricher } from "./enrich.ts";
+import { describeRecord } from "./hash.ts";
+import { describeFile, keepFile, type Described } from "./media-local.ts";
 import { fileFingerprint, idFrom, languageCode, mediaOfUrl, transcriptIdOf } from "./transcripts.ts";
 import { personaLines, readPersona, readVoices, writePersona } from "./profile.ts";
 
@@ -134,6 +138,24 @@ export const TOOLS: ToolDefinition[] = [
       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.",
@@ -245,6 +267,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;
 }
 
@@ -439,6 +463,30 @@ export async function callTool(name: string, args: Record<string, unknown>, opti
       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: Described;
+      try {
+        described = await (options.describe ?? ((file: string) => describeFile(file, { tools: detectTools(), enricher: new Enricher() })))(path);
+      } catch (error) {
+        return failed(`${path}: ${(error as 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) return failed(got.error);

package/src/media-index.ts

@@ -0,0 +1,145 @@
+/**
+ * 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.ts";
+import { checkInterval } from "./media.ts";
+
+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 function indexPath(): string {
+  return process.env["NIXAMP_MEDIA_INDEX"] ?? join(stateDir(), "media.json");
+}
+
+export function readIndex(path = indexPath()): IndexFile {
+  try {
+    const parsed = JSON.parse(readFileSync(path, "utf8")) as Partial<IndexFile>;
+    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: IndexFile, path = indexPath()): void {
+  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: string, entry: { id: string; fingerprint: string; size: number; mtimeMs: number }, now = Date.now(), path = indexPath()): IndexedFile {
+  const index = readIndex(path);
+  const kept: IndexedFile = { ...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: IndexFile, now = Date.now()): string[] {
+  return Object.entries(index.files).filter(([, one]) => one.checkAfter <= now).map(([file]) => file);
+}
+
+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 function look(file: string, entry: IndexedFile, now = Date.now()): Looked {
+  let stat: { size: number; mtimeMs: number };
+  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;
+
+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 async function watchOnce(options: WatchOptions): Promise<{ same: number; changed: number; gone: number }> {
+  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/src/media-local.ts

@@ -0,0 +1,117 @@
+/**
+ * A file on this machine, described for nixamp.com's record of it.
+ *
+ * The same few steps whoever meets the file: hash every byte (the OpenFile
+ * id), take the quick fingerprint (the transcript key), ask ffprobe what is
+ * inside, ask nichedb what it is, note where it is being carried, and say
+ * when this machine will look at it again. `nixamp hash` does it for a
+ * file you name, `nixamp transcribe` for the one it is writing down, and a
+ * server for a file it puts on the air. A file that changed since the
+ * machine last looked is described again as a new record, and the two
+ * records point at each other.
+ */
+import { basename, extname } from "node:path";
+import { codecsOf, type Tools } from "./audio.ts";
+import type { Enricher } from "./enrich.ts";
+import { checkInterval, contentHash, factsFrom, fileFacts, type Holder, type MediaFacts } from "./media.ts";
+import { remember, type IndexedFile } from "./media-index.ts";
+import { keepMedia, type MediaToKeep, type Signed } from "./transcript-client.ts";
+import { fileFingerprint } from "./transcripts.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 async function describeFile(path: string, deps: DescribeDeps = {}): Promise<Described> {
+  const now = deps.now ?? Date.now;
+  const file = fileFacts(path);
+  const id = await (deps.hash ?? contentHash)(path);
+  const fingerprint = (deps.fingerprint ?? fileFingerprint)(path);
+  const codecs = deps.tools && deps.tools.carries !== false ? await codecsOf(deps.tools, path) : null;
+  const name = codecs?.tags?.title || basename(path, extname(path));
+  let enriched = null;
+  try {
+    enriched = deps.enricher ? await deps.enricher.lookup(name) : null;
+  } catch {
+    enriched = null;
+  }
+  const at = now();
+  const facts: MediaFacts = {
+    ...factsFrom(codecs, enriched),
+    fingerprint,
+    checkedAt: new Date(at).toISOString(),
+    checkAfter: new Date(at + checkInterval(file.mtimeMs, at)).toISOString(),
+  };
+  return {
+    id,
+    fingerprint,
+    size: file.size,
+    mtimeMs: file.mtimeMs,
+    keep: {
+      name: file.name,
+      size: file.size,
+      contentType: file.contentType,
+      updated: file.updated,
+      facts: facts as Record<string, unknown>,
+      ...(deps.holder ? { holder: deps.holder } : {}),
+    },
+  };
+}
+
+/** Keep a described file on nixamp.com and in this machine's index. Answers the store's sentence when it refused. */
+export async function keepFile(
+  signed: Signed,
+  path: string,
+  described: Described,
+  deps: { fetcher?: typeof fetch; index?: string; now?: () => number } = {},
+): Promise<string | null> {
+  const got = await keepMedia(signed, described.id, described.keep, deps.fetcher ?? fetch);
+  if (!got.ok) return got.error;
+  try {
+    remember(path, { id: described.id, fingerprint: described.fingerprint, size: described.size, mtimeMs: described.mtimeMs }, (deps.now ?? Date.now)(), deps.index);
+  } catch {
+    // The index is a convenience; the record is what matters.
+  }
+  return 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 async function refreshChanged(
+  signed: Signed,
+  path: string,
+  before: Pick<IndexedFile, "id">,
+  deps: DescribeDeps & { fetcher?: typeof fetch; index?: string } = {},
+): Promise<{ id: string; fingerprint: string } | null> {
+  const described = await describeFile(path, deps);
+  if (described.id === before.id) {
+    // Touched but not changed: the same bytes, a new modification time.
+    const failed = await keepFile(signed, path, described, deps);
+    return failed ? null : { id: described.id, fingerprint: described.fingerprint };
+  }
+  described.keep.facts = { ...(described.keep.facts ?? {}), supersedes: `sha256:${before.id}` };
+  const failed = await keepFile(signed, path, described, deps);
+  if (failed) return null;
+  await keepMedia(signed, before.id, { facts: { supersededBy: `sha256:${described.id}` } }, deps.fetcher ?? fetch);
+  return { id: described.id, fingerprint: described.fingerprint };
+}