funoteka 0.1.0

package/dist/probe/ffprobe.js

@@ -0,0 +1,179 @@
+import { execFile, execFileSync } from 'node:child_process';
+import { HIDDEN } from "../util/child.js";
+function describe(err) {
+    if (err !== null && typeof err === 'object') {
+        const { stderr, message } = err;
+        const text = stderr === undefined ? '' : String(stderr).trim();
+        if (text !== '')
+            return text.split('\n')[0] ?? text;
+        if (message !== undefined)
+            return message;
+    }
+    return String(err);
+}
+function toInt(value) {
+    if (value === undefined)
+        return null;
+    const parsed = Number.parseInt(value, 10);
+    return Number.isNaN(parsed) ? null : parsed;
+}
+/**
+ * Which reading of a file a stored probe row belongs to.
+ *
+ * A row is an answer about a file *as read by a particular method*, and the two
+ * cannot be told apart once stored: this collection's `codec` column was filled
+ * by a method that wrote the *container's* name where a codec belongs (`mp4` for
+ * AAC, `id3v2` for mp3) and nothing in a row said so, so two thousand files
+ * carried a reading that was not one. Raising this number is how a change of
+ * method is announced — every row below it is no longer an answer, and the next
+ * scan takes those files again.
+ *
+ * **2 — the reader that seeds a row states more about the file than it used to.**
+ * The MPEG frame walk now reports the sample rate and the channel count beside
+ * the length (task:2910), so a row seeded by the reader carries four facts where
+ * it carried two. The stored row is not the same answer, which is precisely what
+ * this number exists to say.
+ *
+ * It has to be this number and not `TAGS_METHOD` alone, and the first attempt at
+ * this change proved it: re-reading a file is not enough, because the seed
+ * defers to a row that already succeeded — `seedProbe`'s guard is
+ * `probe_ok = 0 OR stale OR probe_method <> ?`, and a row sitting at method 1 on
+ * an unmoved file passes none of the three. Rescanning the collection with
+ * `TAGS_METHOD` bumped moved all 3350 audio files to the new reader and changed
+ * **not one** of the 728 channel counts, because the reader's answer never
+ * reached the row it was meant to correct.
+ *
+ * **3 — the MP4 reader names a codec**, which is the same kind of change as 2
+ * and lands in the same place: a seeded row now carries `aac` or `alac` where
+ * it carried null, and a row already sitting at method 2 on an unmoved file
+ * passes none of the seed's three conditions. Without this the 1425 `.m4a`
+ * would keep their empty codec and the decision path would keep spawning
+ * ffprobe for every one of them (task:2910).
+ *
+ * **4 — that reader states the channel count and the sample rate as well**, out
+ * of the same header it was already standing on. An `.m4a` row that carried a
+ * codec and nothing else now carries what `alreadyIs` needs to answer a
+ * client's `maxAudioChannels`, so the file is served rather than transcoded
+ * whole. Same reasoning as 2 and 3, and the number moves for the same reason:
+ * what the reader states has moved, and a row on an unmoved file cannot be
+ * told otherwise.
+ */
+export const PROBE_METHOD = 4;
+/**
+ * Ask ffprobe about one file.
+ *
+ * Nothing here is required to work: a duration the file's own bytes did not
+ * state, and the codec inside a container whose name does not say (a `.m4a` is
+ * AAC or ALAC and only the file knows), are the two questions asked of it. A
+ * failure is data, not an exception — the caller records `ok: false` and
+ * carries on, and the closing track of a cue split simply has no end. That is
+ * why this never throws.
+ */
+/** What the question is: the codec and the length, and nothing else. */
+function probeArgs(absPath) {
+    return [
+        '-v',
+        'error',
+        '-select_streams',
+        'a:0',
+        '-show_entries',
+        'format=duration,bit_rate:stream=codec_name,sample_rate,channels',
+        '-of',
+        'json',
+        absPath,
+    ];
+}
+/** A file ffprobe was never asked about, which is a fact like any other. */
+function unasked(err) {
+    return {
+        durationMs: null,
+        codec: null,
+        sampleRate: null,
+        channels: null,
+        bitrate: null,
+        ok: false,
+        err: describe(err),
+    };
+}
+/**
+ * The same question, asked without holding the thread that asked it.
+ *
+ * `codecOf` needs this one: it stands on the hot path of `stream`, for the files
+ * whose container tells a client nothing about what is inside — a `.m4a` is AAC
+ * or ALAC and only the file knows. Asked synchronously it cost the daemon 90 ms
+ * of answering nobody, per file, for 1422 files of this collection (measured,
+ * task:2898). The scan, which is not answering anybody, keeps the sync one.
+ *
+ * Like `probeFile` this never rejects: a failure to ask is `ok: false` and a
+ * sentence, because the callers treat it as data.
+ */
+export function probeAsync(absPath, options = {}) {
+    const bin = options.ffprobePath ?? 'ffprobe';
+    return new Promise((resolve) => {
+        execFile(bin, probeArgs(absPath), {
+            encoding: 'utf8',
+            timeout: options.timeoutMs ?? 30_000,
+            ...HIDDEN,
+        }, (err, stdout) => {
+            resolve(err === null ? parseProbe(stdout) : unasked(err));
+        });
+    });
+}
+export function probeFile(absPath, options = {}) {
+    const bin = options.ffprobePath ?? 'ffprobe';
+    let stdout;
+    try {
+        stdout = execFileSync(bin, probeArgs(absPath), {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+            timeout: options.timeoutMs ?? 30_000,
+            ...HIDDEN,
+        });
+    }
+    catch (err) {
+        return unasked(err);
+    }
+    return parseProbe(stdout);
+}
+/**
+ * What ffprobe said, as a `Probe`.
+ *
+ * Shared by both spellings of the call, so that what is known about a file does
+ * not depend on which one asked it.
+ */
+function parseProbe(stdout) {
+    /** Nothing known, with a reason: every refusal below is this plus a sentence. */
+    const nothing = (err) => ({ ...unasked(err), err });
+    let parsed;
+    try {
+        parsed = JSON.parse(stdout);
+    }
+    catch (err) {
+        return nothing(`unreadable ffprobe output: ${describe(err)}`);
+    }
+    const stream = parsed.streams?.[0];
+    if (stream === undefined) {
+        return nothing('no audio stream found');
+    }
+    const seconds = parsed.format?.duration === undefined ? null : Number(parsed.format.duration);
+    const durationMs = seconds === null || Number.isNaN(seconds) ? null : Math.round(seconds * 1000);
+    const channels = stream.channels ?? null;
+    const probed = {
+        durationMs,
+        codec: stream.codec_name ?? null,
+        sampleRate: toInt(stream.sample_rate),
+        channels,
+        bitrate: toInt(parsed.format?.bit_rate),
+        ok: false,
+        err: null,
+    };
+    // A stream being present is not enough to call the file readable. A truncated
+    // or corrupt file can make ffprobe report a codec while giving no format
+    // section at all — exit code 0, a plausible codec name, and a zero sample
+    // rate. Since the only thing we need from ffprobe is a usable duration, that
+    // is what "ok" means.
+    if (durationMs === null || durationMs <= 0 || channels === 0) {
+        return { ...probed, err: 'stream is not readable (no usable duration)' };
+    }
+    return { ...probed, ok: true };
+}

package/dist/run.js

@@ -0,0 +1,120 @@
+import { applyArtists } from "./artist/apply.js";
+import { classify } from "./classify/classify.js";
+import { numberCollidingRecords } from "./classify/collision-name.js";
+import { nameShelfRecords } from "./classify/shelf-name.js";
+import { applyCues } from "./cue/engine.js";
+import { recordStageFailure } from "./db/issue.js";
+import { scan } from "./scan/scan.js";
+import { SETTLE_MS } from "./scan/settle.js";
+import { applyPlaylists } from "./playlist/import.js";
+import { rebuildSearchIndex } from "./search/index.js";
+import { applyTags } from "./tags/apply.js";
+/**
+ * Run the chain over the given roots, and settle the run's status.
+ *
+ * The order is the one the priority depends on: the classifier names albums
+ * from the folder, tags have their say next, and the cue has the last word on
+ * what a record is called. The artist stage reads all three.
+ *
+ * The run id comes from `scan`, and later stages stamp their rows with it — so
+ * `scan` is not optional and not reorderable. Everything after it is: each
+ * stage derives its own rows from the present and clears them itself, which is
+ * what makes a rerun after a failure reach the state a clean run would.
+ */
+export function runStages(db, rootPaths, options = {}) {
+    // **The one place the half-write gate is asked for.** `scan` takes the window
+    // rather than assuming one, because waiting is a cost and only the caller
+    // knows whether it can be paid; this is production's only scan, so this is
+    // where the contract's clause becomes true of a real run. See `settle.ts`.
+    //
+    // The production window unless a caller names another, and the caller that
+    // does is a test: `settleMs` is the seam `walk` and `probe` already are, and
+    // a suite that pays the window on every fixture it has just written is a
+    // suite that measures the gate rather than the stage it asked about.
+    const scanCounters = scan(db, rootPaths, {
+        walk: options.walk,
+        full: options.full,
+        settleMs: options.settleMs ?? SETTLE_MS,
+    });
+    const runId = scanCounters.scanRunId;
+    // Which stage is running, so a throw can be recorded against its name. Held
+    // in a local rather than threaded through four wrapped calls: the stages
+    // answer with different counters, and a table of them would need a union per
+    // entry to say what it returns.
+    let stage = 'classify';
+    try {
+        const classified = classify(db);
+        stage = 'tags';
+        const tags = applyTags(db, { probe: options.probe, readBytes: options.readBytes });
+        stage = 'cues';
+        const cues = applyCues(db, { probe: options.probe, readBytes: options.readBytes });
+        // After `cues` and not before it: an imported playlist names songs, and
+        // songs are what the cue stage writes. A `.m3u` read earlier would have no
+        // tracks to point at and would import an empty list every time.
+        stage = 'playlists';
+        const playlists = applyPlaylists(db, { readBytes: options.readBytes });
+        stage = 'artists';
+        const artists = applyArtists(db);
+        // After every stage that names anything, and before the index that copies
+        // the names: a record's shelf is the last thing its name gains, because it
+        // is the only stage that can read the artist a shelf's name is measured
+        // against. See `shelf-name.ts`.
+        stage = 'shelves';
+        const shelves = nameShelfRecords(db);
+        // Last of the naming stages, and it has to be last: it numbers the records
+        // that would otherwise read identically, and a qualifier added after it would
+        // give the two names apart on its own — leaving the number describing a
+        // difference that is no longer the whole of it.
+        stage = 'collisions';
+        const collisions = numberCollidingRecords(db);
+        // Last, and it has to be: the index is a copy of what the stages above
+        // settled, so indexing before the cue had its last word on a title would
+        // publish the title it overruled.
+        stage = 'search';
+        const searchIndex = rebuildSearchIndex(db);
+        // The planner's statistics are derived from the data as plainly as any row
+        // here is, and this run is the only thing that knows the data has changed.
+        // Nothing had ever refreshed them, so `sqlite_stat1` did not exist and
+        // SQLite guessed — and on this collection it guessed that the cover route's
+        // folder lookup should scan every file in the root rather than use the
+        // index naming exactly those two columns: measured 12.6 ms against 0.02 ms
+        // per call, on a route a client calls once per artist on screen.
+        stage = 'planner';
+        db.exec('ANALYZE');
+        return {
+            scan: scanCounters,
+            classify: classified,
+            tags,
+            cues,
+            playlists,
+            artists,
+            shelves,
+            collisions,
+            search: searchIndex,
+        };
+    }
+    catch (err) {
+        try {
+            recordStageFailure(db, runId, stage, err);
+        }
+        catch {
+            // The failure is already on its way to the caller. A trace that cannot be
+            // written must not replace the reason it was being written for.
+        }
+        throw err;
+    }
+    finally {
+        // The run's own end, not the walk's.
+        //
+        // `scan` stamps `finished_at` when its walk is done, which is right for the
+        // walk and wrong for the row it is written on: the chain then spends most of
+        // the run — classify, tags, cues, artists, the index — after that stamp, so
+        // a twelve-root run recorded 0.238 s against 38.8 s of work. Nothing could
+        // measure a run's duration from these columns (task:2756).
+        //
+        // `status` is left where `scan` put it: this says when the run ended, not
+        // whether it succeeded, and the failure path above has already written what
+        // went wrong.
+        db.prepare('UPDATE scan_run SET finished_at = ? WHERE id = ?').run(new Date().toISOString(), runId);
+    }
+}

package/dist/scan/kinds.js

@@ -0,0 +1,49 @@
+import { extname } from 'node:path';
+/** Formats the collection matrix calls out: FLAC / APE / WAV / ALAC(m4a) / MP3 / TTA / AIFF. */
+const AUDIO = new Set([
+    'flac',
+    'ape',
+    'wav',
+    'm4a', // ALAC and AAC both land here
+    'mp3',
+    'tta',
+    'aiff',
+    'aif',
+    'aifc',
+    'alac',
+    // No `mp4`: it is a video container, and audio-only material uses `m4a`
+    // above. The collection keeps live clips in `.mp4`, and treating the
+    // extension as audio filed a video as a track.
+    'ogg',
+    'oga',
+    'opus',
+    'wma',
+    'wv',
+    'mpc',
+    'shn',
+    'tak',
+    'dsf',
+    'dff',
+]);
+const IMAGE = new Set(['jpg', 'jpeg', 'png', 'gif', 'bmp', 'webp', 'tif', 'tiff']);
+const PLAYLIST = new Set(['m3u', 'm3u8', 'pls']);
+export function classifyFile(name) {
+    // A leading dot marks a hidden file (`.DS_Store`), not an extension — Node's
+    // extname already reports '' for those, which falls through to 'other'.
+    const ext = extname(name).toLowerCase().slice(1);
+    if (ext === '')
+        return 'other';
+    if (AUDIO.has(ext))
+        return 'audio';
+    if (IMAGE.has(ext))
+        return 'image';
+    if (PLAYLIST.has(ext))
+        return 'playlist';
+    if (ext === 'cue')
+        return 'cue';
+    if (ext === 'nfo')
+        return 'nfo';
+    if (ext === 'log')
+        return 'log';
+    return 'other';
+}