nixamp 0.10.3 → 0.11.1

package/dist/enrich.d.ts

@@ -0,0 +1,108 @@
+/** Where the answers come from, unless a deployment says otherwise. */
+export declare const DEFAULT_SITE = "https://nichedb.dev";
+/** How long a hit is believed. Titles and channels change on the order of months. */
+export declare const HIT_TTL_MS: number;
+/** How long a miss is believed: nichedb's catalogue is still filling in. */
+export declare const MISS_TTL_MS: number;
+/** A fixture's score is stale in a minute. */
+export declare const FIXTURE_TTL_MS: number;
+/**
+ * Below this the best match is a guess, and a wrong poster is worse than none.
+ * Measured: "Severance" against a channel called "Sever" scored 0.45, and
+ * "Lakers at Celtics" against "Rangers at Celtic" 0.44. Half is above both.
+ */
+export declare const MIN_SCORE = 0.5;
+/** A weaker score is still taken when one name plainly begins with the other. */
+export declare const PREFIX_SCORE = 0.42;
+/** How many answers the cache keeps before the oldest go. */
+export declare const MAX_ENTRIES = 5000;
+export type EnrichKind = "auto" | "title" | "channel" | "fixture";
+export interface Enriched {
+    /** What nichedb says it is. */
+    kind: "title" | "channel" | "fixture";
+    title: string;
+    /** For a title, its year; for a fixture, when it starts. */
+    year: number | null;
+    /** A poster, a logo, or nothing. */
+    image: string | null;
+    summary: string | null;
+    /** nichedb's page for it, for a link. */
+    page: string;
+    score: number;
+    /** The rest, as the collection shapes it: rating, genres, country, scores… */
+    data: Record<string, unknown>;
+    tags: string[];
+}
+interface Cached {
+    at: number;
+    hit: Enriched | null;
+}
+/** nichedb's answer to /api/v1/match, as much of it as is read here. */
+interface MatchAnswer {
+    parsed?: {
+        name?: string;
+        year?: number | null;
+        kind?: string;
+        season?: number | null;
+        episode?: number | null;
+    };
+    items?: {
+        kind?: string;
+        title?: string;
+        summary?: string | null;
+        image_url?: string | null;
+        published_at?: string | null;
+        page?: string;
+        score?: number;
+        data?: Record<string, unknown>;
+        tags?: string[];
+    }[];
+}
+/** The collection and kind a name is asked about, from what the caller knows. */
+export declare function whereToAsk(kind: EnrichKind, parsedKind?: string): {
+    collection: string;
+    kind: string;
+} | null;
+/** The key one name is remembered under: case and spacing do not make it a different name. */
+export declare function cacheKey(name: string, kind: EnrichKind, year: number | null): string;
+/** Whether a stored answer is still worth believing. */
+export declare function fresh(entry: Cached, now: number): boolean;
+/** The best of nichedb's answers, or nothing when the best is a guess. */
+export declare function pickBest(answer: MatchAnswer, asked: string): Enriched | null;
+export interface EnricherOptions {
+    site?: string;
+    fetch?: typeof globalThis.fetch;
+    /** Where answers are kept between runs; none means memory only. */
+    cacheFile?: string;
+    now?: () => number;
+    onEvent?: (message: string) => void;
+}
+export declare class Enricher {
+    private readonly options;
+    private readonly site;
+    private readonly fetcher;
+    private readonly now;
+    private readonly cache;
+    private readonly inflight;
+    private saveTimer;
+    private dirty;
+    constructor(options?: EnricherOptions);
+    /** How many names are remembered. */
+    get size(): number;
+    /**
+     * What a name is, from the cache or from nichedb.
+     *
+     * `kind` narrows the question when the caller knows: a live channel is a
+     * channel however its name reads. `auto` lets nichedb's parser decide from
+     * the name itself, which is right for a file.
+     */
+    lookup(name: string, kind?: EnrichKind, year?: number | null): Promise<Enriched | null>;
+    private ask;
+    private get;
+    private remember;
+    private load;
+    private scheduleSave;
+    /** Write the cache now. Called on a timer, and by whoever is shutting down. */
+    save(): void;
+}
+export {};

package/dist/enrich.js

@@ -0,0 +1,253 @@
+/**
+ * What is this, really?
+ *
+ * A file called "Top.Gun.Maverick.2022.1080p.WEB-DL.mkv" is a film with a
+ * poster, a year and a rating; a playlist entry called "US: ESPN2 HD" is a
+ * channel with a logo, a country and a category; "Lakers at Celtics" is a
+ * fixture with a score. nixamp knows none of that on its own -- ffprobe reads
+ * tags, and a torrent's tags are its file name -- so it asks nichedb.dev,
+ * which keeps the titles, channels and fixtures every profullstack site is
+ * built on, and answers a name with the best match and a score.
+ *
+ * Asked once per name and remembered: a library of five thousand files must
+ * not become five thousand requests a day, and a channel that was ESPN2
+ * yesterday is ESPN2 today. Misses are remembered too, for less long, so a
+ * file nichedb has never heard of is not asked about every time it plays.
+ */
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+/** Where the answers come from, unless a deployment says otherwise. */
+export const DEFAULT_SITE = "https://nichedb.dev";
+/** How long a hit is believed. Titles and channels change on the order of months. */
+export const HIT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** How long a miss is believed: nichedb's catalogue is still filling in. */
+export const MISS_TTL_MS = 6 * 60 * 60 * 1000;
+/** A fixture's score is stale in a minute. */
+export const FIXTURE_TTL_MS = 60 * 1000;
+/**
+ * Below this the best match is a guess, and a wrong poster is worse than none.
+ * Measured: "Severance" against a channel called "Sever" scored 0.45, and
+ * "Lakers at Celtics" against "Rangers at Celtic" 0.44. Half is above both.
+ */
+export const MIN_SCORE = 0.5;
+/** A weaker score is still taken when one name plainly begins with the other. */
+export const PREFIX_SCORE = 0.42;
+/** How many answers the cache keeps before the oldest go. */
+export const MAX_ENTRIES = 5000;
+/** The collection and kind a name is asked about, from what the caller knows. */
+export function whereToAsk(kind, parsedKind) {
+    const k = kind === "auto" ? parsedKind ?? "" : kind;
+    switch (k) {
+        case "channel":
+            return { collection: "channels", kind: "channel" };
+        case "fixture":
+            return { collection: "sports", kind: "fixture" };
+        case "title":
+        case "movie":
+        case "series":
+            return { collection: "screen", kind: "title" };
+        default:
+            // Music and the rest: nichedb has no answer worth a poster yet.
+            return null;
+    }
+}
+/** The key one name is remembered under: case and spacing do not make it a different name. */
+export function cacheKey(name, kind, year) {
+    return `${kind}|${year ?? ""}|${name.trim().toLowerCase().replace(/\s+/g, " ")}`;
+}
+/** Whether a stored answer is still worth believing. */
+export function fresh(entry, now) {
+    const ttl = entry.hit === null ? MISS_TTL_MS : entry.hit.kind === "fixture" ? FIXTURE_TTL_MS : HIT_TTL_MS;
+    return now - entry.at < ttl;
+}
+/** The best of nichedb's answers, or nothing when the best is a guess. */
+export function pickBest(answer, asked) {
+    const items = answer.items ?? [];
+    const wanted = asked.trim().toLowerCase();
+    let best;
+    const isExact = (item) => item !== undefined && String(item.title ?? "").toLowerCase() === wanted;
+    const plain = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    const askedPlain = plain(wanted);
+    for (const item of items) {
+        const exact = isExact(item);
+        const score = Number(item.score ?? 0);
+        const titlePlain = plain(String(item.title ?? ""));
+        // Whole words: "Top Gun Maverick Extended" begins with "Top Gun Maverick",
+        // but "Severance" does not begin with a channel called "Sever".
+        const prefix = titlePlain.length >= 4 &&
+            askedPlain.length >= 4 &&
+            (askedPlain.startsWith(`${titlePlain} `) || titlePlain.startsWith(`${askedPlain} `));
+        if (!exact && score < (prefix ? PREFIX_SCORE : MIN_SCORE))
+            continue;
+        // An exact title beats any score; among exact titles the one with a
+        // picture wins, since nichedb keeps both the IMDb row and the TMDB row of
+        // a film and only one has the poster; among the rest, the score decides.
+        if (!best)
+            best = item;
+        else if (exact && !isExact(best))
+            best = item;
+        else if (exact && isExact(best) && !best.image_url && item.image_url)
+            best = item;
+        else if (!isExact(best) && score > Number(best.score ?? 0))
+            best = item;
+    }
+    if (!best)
+        return null;
+    const kind = best.kind === "channel" || best.kind === "fixture" ? best.kind : "title";
+    const year = typeof best.data?.["year"] === "number"
+        ? best.data["year"]
+        : best.published_at
+            ? new Date(best.published_at).getUTCFullYear() || null
+            : null;
+    return {
+        kind,
+        title: String(best.title ?? ""),
+        year: Number.isFinite(year) ? year : null,
+        image: best.image_url ?? null,
+        summary: best.summary ?? null,
+        page: String(best.page ?? ""),
+        score: Number(best.score ?? 0),
+        data: best.data ?? {},
+        tags: best.tags ?? [],
+    };
+}
+export class Enricher {
+    options;
+    site;
+    fetcher;
+    now;
+    cache = new Map();
+    inflight = new Map();
+    saveTimer = null;
+    dirty = false;
+    constructor(options = {}) {
+        this.options = options;
+        this.site = (options.site ?? DEFAULT_SITE).replace(/\/+$/, "");
+        this.fetcher = options.fetch ?? globalThis.fetch;
+        this.now = options.now ?? Date.now;
+        this.load();
+    }
+    /** How many names are remembered. */
+    get size() {
+        return this.cache.size;
+    }
+    /**
+     * What a name is, from the cache or from nichedb.
+     *
+     * `kind` narrows the question when the caller knows: a live channel is a
+     * channel however its name reads. `auto` lets nichedb's parser decide from
+     * the name itself, which is right for a file.
+     */
+    async lookup(name, kind = "auto", year = null) {
+        const asked = String(name ?? "").trim();
+        if (asked === "")
+            return null;
+        const key = cacheKey(asked, kind, year);
+        const had = this.cache.get(key);
+        if (had && fresh(had, this.now()))
+            return had.hit;
+        const running = this.inflight.get(key);
+        if (running)
+            return running;
+        const work = this.ask(asked, kind, year)
+            .then((hit) => {
+            this.remember(key, hit);
+            return hit;
+        })
+            .catch((error) => {
+            this.options.onEvent?.(`  nichedb did not answer for "${asked}": ${error.message}`);
+            // Not remembered: a network fault is not a miss.
+            return had?.hit ?? null;
+        })
+            .finally(() => this.inflight.delete(key));
+        this.inflight.set(key, work);
+        return work;
+    }
+    async ask(name, kind, year) {
+        // Two round trips at most: nichedb parses the name; when the caller did
+        // not say what it is, the first answer's reading says where to look.
+        const first = new URLSearchParams({ q: name, limit: "3" });
+        if (year !== null)
+            first.set("year", String(year));
+        const where = whereToAsk(kind);
+        if (where) {
+            first.set("collection", where.collection);
+            first.set("kind", where.kind);
+        }
+        const answer = await this.get(`/api/v1/match?${first}`);
+        if (where)
+            return pickBest(answer, answer.parsed?.name ?? name);
+        const guessed = whereToAsk("auto", answer.parsed?.kind);
+        if (!guessed)
+            return null;
+        const second = new URLSearchParams(first);
+        second.set("collection", guessed.collection);
+        second.set("kind", guessed.kind);
+        // The year the name carried narrows the second question.
+        if (year === null && answer.parsed?.year)
+            second.set("year", String(answer.parsed.year));
+        return pickBest(await this.get(`/api/v1/match?${second}`), answer.parsed?.name ?? name);
+    }
+    async get(path) {
+        const response = await this.fetcher(`${this.site}${path}`, {
+            headers: { accept: "application/json", "user-agent": "nixamp (+https://nixamp.com)" },
+            signal: AbortSignal.timeout(15_000),
+        });
+        if (!response.ok)
+            throw new Error(`nichedb answered ${response.status}`);
+        return (await response.json());
+    }
+    remember(key, hit) {
+        this.cache.set(key, { at: this.now(), hit });
+        if (this.cache.size > MAX_ENTRIES) {
+            // Oldest first: a Map remembers insertion order.
+            const drop = this.cache.size - MAX_ENTRIES;
+            let n = 0;
+            for (const k of this.cache.keys()) {
+                if (n++ >= drop)
+                    break;
+                this.cache.delete(k);
+            }
+        }
+        this.dirty = true;
+        this.scheduleSave();
+    }
+    load() {
+        if (!this.options.cacheFile)
+            return;
+        try {
+            const parsed = JSON.parse(readFileSync(this.options.cacheFile, "utf8"));
+            for (const [k, v] of Object.entries(parsed)) {
+                if (v && typeof v.at === "number")
+                    this.cache.set(k, v);
+            }
+        }
+        catch {
+            // No cache yet, or one that is not JSON: start empty.
+        }
+    }
+    scheduleSave() {
+        if (!this.options.cacheFile || this.saveTimer)
+            return;
+        this.saveTimer = setTimeout(() => {
+            this.saveTimer = null;
+            this.save();
+        }, 2000);
+        this.saveTimer.unref?.();
+    }
+    /** Write the cache now. Called on a timer, and by whoever is shutting down. */
+    save() {
+        if (!this.options.cacheFile || !this.dirty)
+            return;
+        try {
+            mkdirSync(dirname(this.options.cacheFile), { recursive: true });
+            const tmp = `${this.options.cacheFile}.tmp`;
+            writeFileSync(tmp, JSON.stringify(Object.fromEntries(this.cache)));
+            renameSync(tmp, this.options.cacheFile);
+            this.dirty = false;
+        }
+        catch (error) {
+            this.options.onEvent?.(`  could not save the enrichment cache: ${error.message}`);
+        }
+    }
+}

package/dist/server.d.ts

@@ -12,6 +12,7 @@ import { Owner } from "./owner.ts";
 import { Directory } from "./directory.ts";
 import { PartyLine } from "./partyline.ts";
 import { HlsPackagers } from "./hls.ts";
+import { Enricher } from "./enrich.ts";
 import { Follows } from "./follows.ts";
 import { Favorites } from "./favorites.ts";
 import { Catalogs } from "./catalogs.ts";
@@ -425,6 +426,8 @@ export interface HandlerOptions {
     ytdlp?: string[] | null;
     /** Channels as HLS, for Safari on a phone, which plays a live stream no other way. */
     hls?: HlsPackagers;
+    /** What a name is -- a film, a channel, a fixture -- asked of nichedb.dev and remembered. */
+    enricher?: Enricher;
     /** A Netscape cookies file for sites that want a signed-in browser, when there is one. */
     cookies?: string;
     /** Who is listening, for the admin view. */

package/dist/server.js

@@ -35,6 +35,7 @@ import { readSession } from "./session.js";
 import { Directory, ENDED_TTL_MS, parseAnnouncement } from "./directory.js";
 import { PartyLine, telnyxSms } from "./partyline.js";
 import { HlsPackagers, withKey } from "./hls.js";
+import { DEFAULT_SITE as NICHEDB, Enricher } from "./enrich.js";
 import { contentTypeFor, downloadArgs, fileNameFor, inputArgsFor, linkChannelId, playableLink, resolveLink, saveFormat, } from "./links.js";
 import { CALL_IN_NUMBER, OPT_IN_PATH, optInPage } from "./optin.js";
 import pg from "pg";
@@ -2317,6 +2318,35 @@ export function createHandler(engine, options) {
         // own, the way a catalog entry is played: started for whoever asked,
         // stopped a minute after the last viewer leaves. Open to anyone holding
         // the link, like picking something from a catalog.
+        // --- what is this? ------------------------------------------------------
+        //
+        // A file name, a playlist entry, a channel: the poster, the logo, the
+        // year, the rating, from nichedb.dev, remembered here so a library is
+        // asked about once. Open to whoever holds the link, like the playlist.
+        if (path === "/api/enrich" && request.method === "GET") {
+            const name = (url.searchParams.get("name") ?? "").trim().slice(0, 300);
+            if (name === "") {
+                json(response, 400, { error: "name is required" });
+                return;
+            }
+            if (!options.enricher) {
+                json(response, 200, { match: null });
+                return;
+            }
+            const kinds = ["auto", "title", "channel", "fixture"];
+            const asked = url.searchParams.get("kind") ?? "auto";
+            const kind = kinds.includes(asked) ? asked : "auto";
+            const year = Number(url.searchParams.get("year")) || null;
+            const match = await options.enricher.lookup(name, kind, year);
+            response.writeHead(200, {
+                ...CORS,
+                "content-type": "application/json; charset=utf-8",
+                // A miss is worth asking again in a few hours; a hit lasts the day.
+                "cache-control": match ? "public, max-age=3600" : "public, max-age=600",
+            });
+            response.end(JSON.stringify({ match }));
+            return;
+        }
         if (path === "/api/links/play" && request.method === "POST") {
             let body = {};
             try {
@@ -3521,6 +3551,13 @@ export async function serve(argv, version = "0.1.0") {
     });
     // Channels as HLS, on demand, for Safari on a phone: one ffmpeg copying a
     // channel's fragments into short files while somebody is asking for them.
+    // What things are, from nichedb.dev, remembered beside the keys so a
+    // library is asked about once across restarts.
+    const enricher = new Enricher({
+        site: process.env["NIXAMP_NICHEDB"] || NICHEDB,
+        cacheFile: join(stateDir(), "enrich.json"),
+        onEvent: (message) => console.log(message),
+    });
     const hls = new HlsPackagers({
         ffmpeg: tools.ffmpeg,
         listen: (id, listener) => channels.listen(id, listener),
@@ -3878,6 +3915,7 @@ export async function serve(argv, version = "0.1.0") {
         ytdlp: tools.ytdlp ?? null,
         cookies: cookiesFile(),
         hls,
+        enricher,
         ...(tls ? { tls } : {}),
         // Untagged, so a directory of five thousand files answers at once; the
         // tags follow through `tag` below.
@@ -4297,6 +4335,7 @@ export async function serve(argv, version = "0.1.0") {
     });
     const shutdown = () => {
         rtmp?.stop();
+        enricher.save();
         hls.stopAll();
         channels.stopAll();
         ingest?.stopRtmp();

package/package.json

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