nixamp 0.24.2 → 0.25.1

package/dist/media-local.js

@@ -0,0 +1,88 @@
+/**
+ * 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 } from "./audio.js";
+import { checkInterval, contentHash, factsFrom, fileFacts } from "./media.js";
+import { remember } from "./media-index.js";
+import { keepMedia } from "./transcript-client.js";
+import { fileFingerprint } from "./transcripts.js";
+/** Everything this machine can say about a file, ready to keep. */
+export async function describeFile(path, deps = {}) {
+    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 = {
+        ...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,
+            ...(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, path, described, deps = {}) {
+    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, path, before, deps = {}) {
+    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 };
+}

package/dist/media-page.d.ts

@@ -0,0 +1,18 @@
+/**
+ * nixamp.com/hash/<id>, as a page: everything nixamp knows about one file,
+ * for a person with a browser. The same facts as the OpenFile descriptor
+ * beside it, laid out: what it is, how long, what is inside, who said what
+ * it was, where it has been carried, and the transcript in every language
+ * it has been written down in, with subtitle files to take away.
+ *
+ * Rendered on the server from a string, with the terminal's look, so a
+ * crawler and a link preview read it and nothing has to load first.
+ */
+import type { MediaRecord, TranscriptRef } from "./media.ts";
+import type { TranscriptLine } from "./transcripts.ts";
+export interface PageTranscript extends TranscriptRef {
+    /** The lines themselves, for the one transcript the page shows. */
+    shown?: TranscriptLine[];
+}
+/** The page, whole. `transcripts[0]` carries the lines shown; the rest are offered as files. */
+export declare function mediaPage(record: MediaRecord, site: string, transcripts?: PageTranscript[]): string;

package/dist/media-page.js

@@ -0,0 +1,146 @@
+function esc(text) {
+    return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+}
+function bytes(size) {
+    if (size >= 1024 ** 3)
+        return `${(size / 1024 ** 3).toFixed(2)} GB`;
+    if (size >= 1024 ** 2)
+        return `${(size / 1024 ** 2).toFixed(1)} MB`;
+    if (size >= 1024)
+        return `${(size / 1024).toFixed(0)} KB`;
+    return `${size} B`;
+}
+function clock(seconds) {
+    const whole = Math.max(0, Math.floor(seconds));
+    const h = Math.floor(whole / 3600);
+    const m = Math.floor((whole % 3600) / 60);
+    const s = whole % 60;
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${String(s).padStart(2, "0")}` : `${m}:${String(s).padStart(2, "0")}`;
+}
+function when(iso) {
+    return iso ? esc(iso.replace("T", " ").replace(/\.\d+Z$/, " UTC")) : "";
+}
+const STYLE = `
+  :root { color-scheme: dark; --bg:#080c09; --panel:#0c120e; --edge:#1d2c22; --green:#4af689; --dim:#227a4a; --fg:#cfe8d8; --muted:#6d8a79; --accent:#7ef0c4; }
+  * { box-sizing: border-box; }
+  body { margin:0; background:var(--bg); color:var(--fg); font:14px/1.5 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+  main { max-width: 960px; margin: 0 auto; padding: 20px 16px 48px; }
+  a { color: var(--accent); }
+  .brand { color: var(--green); font-weight: 700; letter-spacing: .14em; text-decoration: none; }
+  h1 { font-size: 20px; margin: 18px 0 4px; color: var(--green); overflow-wrap: anywhere; }
+  .id { color: var(--muted); font-size: 12px; overflow-wrap: anywhere; }
+  .panel { position: relative; border: 1px solid var(--edge); border-radius: 6px; background: var(--panel); padding: 18px 12px 12px; margin-top: 16px; }
+  .panel::before { content: attr(data-title); position: absolute; top: -9px; left: 10px; padding: 0 6px; background: var(--panel); color: var(--dim); font-size: 12px; letter-spacing: .06em; }
+  table { border-collapse: collapse; width: 100%; }
+  td { padding: 3px 8px 3px 0; vertical-align: top; overflow-wrap: anywhere; }
+  td:first-child { color: var(--muted); white-space: nowrap; width: 11em; }
+  .poster { float: right; max-width: 160px; margin: 0 0 8px 12px; border: 1px solid var(--edge); border-radius: 4px; }
+  ul { margin: 0; padding-left: 1.2em; }
+  .lines { list-style: none; padding: 0; max-height: 420px; overflow-y: auto; font-size: 13px; }
+  .lines li { display: flex; gap: 8px; padding: 2px 0; border-bottom: 1px dotted var(--edge); }
+  .lines .t { color: var(--muted); flex: 0 0 auto; }
+  .chips a { display: inline-block; margin: 0 8px 6px 0; border: 1px solid var(--edge); border-radius: 999px; padding: 1px 10px; font-size: 12px; text-decoration: none; }
+  .muted { color: var(--muted); }
+  pre { white-space: pre-wrap; overflow-wrap: anywhere; color: var(--muted); font-size: 12px; }
+`;
+/** The page, whole. `transcripts[0]` carries the lines shown; the rest are offered as files. */
+export function mediaPage(record, site, transcripts = []) {
+    const base = site.replace(/\/+$/, "");
+    const f = record.facts;
+    const title = f.enrichment?.title || f.tags?.title || record.name || record.id.slice(0, 12);
+    const picture = f.enrichment?.image ?? null;
+    const url = `${base}/hash/${record.id}`;
+    const summary = f.enrichment?.summary ?? "";
+    const description = summary || `${record.name}${f.duration ? `, ${clock(f.duration)}` : ""}${transcripts.length > 0 ? `, transcribed in ${transcripts.map((one) => one.language || "its own language").join(", ")}` : ""}`;
+    const rows = [];
+    if (record.name)
+        rows.push(["File", esc(record.name)]);
+    if (record.size)
+        rows.push(["Size", bytes(record.size)]);
+    if (record.contentType)
+        rows.push(["Type", esc(record.contentType)]);
+    if (f.duration)
+        rows.push(["Length", clock(f.duration)]);
+    if (f.width && f.height)
+        rows.push(["Picture", `${f.width}×${f.height}`]);
+    if (f.codecs)
+        rows.push(["Inside", esc([f.codecs.video, f.codecs.audio, f.codecs.container].filter(Boolean).join(" / "))]);
+    if (f.tags?.artist || f.tags?.album)
+        rows.push(["Tagged", esc([f.tags.artist, f.tags.album].filter(Boolean).join(" · "))]);
+    if (record.updated)
+        rows.push(["File changed", when(record.updated)]);
+    if (f.checkedAt)
+        rows.push(["Last checked", `${when(f.checkedAt)}${f.checkAfter ? `, next ${when(f.checkAfter)}` : ""}`]);
+    if (f.fingerprint)
+        rows.push(["Fingerprint", `<span class="id">${esc(f.fingerprint)}</span>`]);
+    if (f.supersedes)
+        rows.push(["Was", `<a href="${base}/hash/${esc(f.supersedes.replace(/^sha256:/, ""))}">${esc(f.supersedes)}</a>`]);
+    if (f.supersededBy)
+        rows.push(["Became", `<a href="${base}/hash/${esc(f.supersededBy.replace(/^sha256:/, ""))}">${esc(f.supersededBy)}</a>`]);
+    rows.push(["Kept", `${when(record.createdAt)}${record.updatedAt !== record.createdAt ? `, last added to ${when(record.updatedAt)}` : ""}`]);
+    const enrichment = f.enrichment
+        ? `<section class="panel" data-title="What nichedb says it is">
+      ${picture ? `<img class="poster" src="${esc(picture)}" alt="" />` : ""}
+      <table>
+        <tr><td>Title</td><td>${esc(f.enrichment.title ?? "")}${f.enrichment.year ? ` (${f.enrichment.year})` : ""}</td></tr>
+        ${f.enrichment.kind ? `<tr><td>Kind</td><td>${esc(f.enrichment.kind)}</td></tr>` : ""}
+        ${summary ? `<tr><td>About</td><td>${esc(summary)}</td></tr>` : ""}
+        ${f.enrichment.page ? `<tr><td>Page</td><td><a href="${esc(f.enrichment.page)}">${esc(f.enrichment.page)}</a></td></tr>` : ""}
+      </table>
+    </section>`
+        : "";
+    const holders = record.holders.length > 0
+        ? `<section class="panel" data-title="Carried by">
+      <ul>${record.holders.map((h) => `<li><a href="${esc(h.url)}">${esc(h.name || h.url)}</a>${h.channel ? ` as <code>${esc(h.channel)}</code>` : ""} <span class="muted">${when(h.seenAt)}</span></li>`).join("")}</ul>
+    </section>`
+        : "";
+    const shown = transcripts[0];
+    const transcript = transcripts.length > 0
+        ? `<section class="panel" data-title="Transcript">
+      <p class="chips">${transcripts.map((one) => {
+            const q = one.language ? `?language=${esc(one.language)}` : "";
+            return `<a href="${url}.srt${q}">${esc(one.language || "as spoken")}${one.translatedFrom ? ` (from ${esc(one.translatedFrom)})` : ""} · ${one.lines} lines${one.complete ? "" : " so far"} · SRT</a> <a href="${url}.vtt${q}">VTT</a> <a href="${url}.txt${q}">text</a>`;
+        }).join("<br />")}</p>
+      ${shown?.shown && shown.shown.length > 0
+            ? `<ul class="lines">${shown.shown.map((line) => `<li><span class="t">${clock(line.start)}</span><span>${esc(line.text)}</span></li>`).join("")}</ul>`
+            : ""}
+    </section>`
+        : `<section class="panel" data-title="Transcript"><p class="muted">Not written down yet. <code>nixamp transcribe FILE</code> keeps it here, and a server captioning it does too.</p></section>`;
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${esc(title)} · nixamp</title>
+<meta name="description" content="${esc(description.slice(0, 300))}" />
+<link rel="canonical" href="${url}" />
+<link rel="openfile" href="${url}.openfile.json" />
+<link rel="alternate" type="application/json" href="${url}.json" />
+<meta property="og:title" content="${esc(title)}" />
+<meta property="og:description" content="${esc(description.slice(0, 300))}" />
+<meta property="og:url" content="${url}" />
+<meta property="og:type" content="${record.contentType.startsWith("video/") ? "video.other" : record.contentType.startsWith("audio/") ? "music.song" : "website"}" />
+${picture ? `<meta property="og:image" content="${esc(picture)}" />` : ""}
+<style>${STYLE}</style>
+</head>
+<body>
+<main>
+  <a class="brand" href="${base}/">NIXAMP</a>
+  <h1>${esc(title)}</h1>
+  <div class="id">sha256:${esc(record.id)}</div>
+  <section class="panel" data-title="The file">
+    <table>${rows.map(([k, v]) => `<tr><td>${k}</td><td>${v}</td></tr>`).join("")}</table>
+  </section>
+  ${enrichment}
+  ${holders}
+  ${transcript}
+  <section class="panel" data-title="For a program">
+    <p class="muted">This page as <a href="${url}.openfile.json">OpenFile</a> (<a href="https://logicsrc.com/docs/openfile">the specification</a>) or <a href="${url}.json">JSON</a>. Every file nixamp.com knows: <a href="${base}/.well-known/openfile.json">/.well-known/openfile.json</a>.</p>
+    <pre>nixamp hash FILE            the same address for a file of yours
+nixamp transcribe FILE      and its transcript, kept here</pre>
+  </section>
+</main>
+</body>
+</html>
+`;
+}

package/dist/media.d.ts

@@ -0,0 +1,145 @@
+import type { Queryable } from "./follows.ts";
+import type { Codecs } from "./audio.ts";
+import type { Enriched } from "./enrich.ts";
+/** What the nixamp key of a record may carry. Every part optional: a record grows. */
+export interface MediaFacts {
+    /** The transcript store's identity for the same file. */
+    fingerprint?: string;
+    /** Seconds. */
+    duration?: number;
+    codecs?: {
+        video?: string;
+        audio?: string;
+        container?: string;
+    };
+    width?: number;
+    height?: number;
+    tags?: {
+        title?: string;
+        artist?: string;
+        album?: string;
+    };
+    /** What nichedb said it is. */
+    enrichment?: {
+        kind?: string;
+        title?: string;
+        year?: number | null;
+        image?: string | null;
+        summary?: string | null;
+        page?: string;
+    };
+    /** The record this file became when it changed on disk, as `sha256:<hex>`. */
+    supersededBy?: string;
+    /** The record this file was before it changed. */
+    supersedes?: string;
+    /** When the machine holding it last looked, and when it will next. */
+    checkedAt?: string;
+    checkAfter?: string;
+}
+/** A place that has carried the file: an OpenFile holder. A nixamp server serves it over HTTP, which makes it a gateway. */
+export interface Holder {
+    kind: "gateway" | "peer" | "seeder";
+    url: string;
+    seenAt: string;
+    /** The channel it was carried as, when it was. */
+    channel?: string;
+    name?: string;
+}
+export interface MediaRecord {
+    /** The SHA-256 of the bytes, hex. */
+    id: string;
+    name: string;
+    size: number;
+    contentType: string;
+    /** When the file last changed, ISO. */
+    updated: string;
+    facts: MediaFacts;
+    holders: Holder[];
+    by: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/** How many places a record remembers carrying it. */
+export declare const MAX_HOLDERS = 50;
+/** The listing at /.well-known/openfile.json is this long at most. */
+export declare 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 declare const CHECK_MIN_MS: number;
+export declare const CHECK_MAX_MS: number;
+/** The media type a file's name suggests, or octet-stream. */
+export declare function contentTypeOf(path: string): string;
+/** A media id as a request names one: bare hex or `sha256:` hex; the hex, or null. */
+export declare function mediaId(value: unknown): string | null;
+/** The SHA-256 of every byte of a file, as a stream so a film does not sit in memory. */
+export declare function contentHash(path: string): Promise<string>;
+/** What the filesystem says about a file: its size, when it changed, and its type. */
+export declare function fileFacts(path: string): {
+    name: string;
+    size: number;
+    updated: string;
+    contentType: string;
+    mtimeMs: number;
+};
+/**
+ * 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 declare function checkInterval(mtimeMs: number, nowMs: number): number;
+/** The facts ffprobe and nichedb give a server, as the record wants them. */
+export declare function factsFrom(codecs?: Codecs | null, enriched?: Enriched | null): MediaFacts;
+/** Facts as a request hands them in: only the keys this file names, each of the right shape. */
+export declare function factsFromRequest(value: unknown): MediaFacts;
+/** A holder as a request hands it in, or null. */
+export declare function holderFrom(value: unknown): Holder | null;
+/** Holders with one entry per address, the latest sighting kept, newest first. */
+export declare function mergeHolders(had: Holder[], added: Holder[]): Holder[];
+export interface MediaAsk {
+    id: string;
+    name?: string;
+    size?: number;
+    contentType?: string;
+    /** When the file last changed. */
+    updated?: string;
+    facts?: MediaFacts;
+    holder?: Holder | null;
+    by: string;
+}
+export declare class Media {
+    private readonly db;
+    private readonly onEvent;
+    private ready;
+    constructor(db: Queryable, onEvent?: (message: string) => void);
+    private ensure;
+    /**
+     * 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.
+     */
+    save(ask: MediaAsk): Promise<MediaRecord | null>;
+    get(id: string): Promise<MediaRecord | null>;
+    /** The record of the file a transcript fingerprint belongs to, the latest when there are several. */
+    byFingerprint(fingerprint: string): Promise<MediaRecord | null>;
+    /** The latest records, newest first, for the listing. */
+    recent(limit?: number): Promise<MediaRecord[]>;
+    /** Never throws: a store that is having a moment costs the record, not the request. */
+    quietly<T>(what: string, run: () => Promise<T>): Promise<T | null>;
+}
+/** A transcript, as the record lists it: enough to pick a language and fetch it. */
+export interface TranscriptRef {
+    language: string;
+    translatedFrom: string | null;
+    lines: number;
+    complete: boolean;
+}
+/**
+ * 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 declare function openFileOf(record: MediaRecord, site: string, transcripts?: TranscriptRef[]): Record<string, unknown>;
+/** The publisher's descriptor: nixamp.com and its latest records. */
+export declare function openFileListing(records: MediaRecord[], site: string): Record<string, unknown>;