poddrill 0.0.0-stage → 0.1.0

package/dist/disk.js

@@ -0,0 +1,47 @@
+/**
+ * Filesystem error codes and JSON files, read at the disk boundary.
+ */
+import { readFile, stat } from "node:fs/promises";
+export function errorCode(error) {
+    if (error instanceof Error && "code" in error && typeof error.code === "string") {
+        return error.code;
+    }
+    return undefined;
+}
+export async function pathExists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return false;
+        }
+        throw error;
+    }
+}
+/** `undefined` when the file is missing or is not JSON. */
+export async function readJsonFile(path) {
+    let text;
+    try {
+        text = await readFile(path, "utf8");
+    }
+    catch (error) {
+        if (errorCode(error) === "ENOENT") {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(value));
+}

package/dist/embed.js

@@ -0,0 +1,127 @@
+/**
+ * The local ECAPA embedding host. One python3 process per fleet slot, never shared with Whistle.
+ * Ready frame: { "kind": "ready" }. Result: 192 numbers for one stretch wav.
+ * Frontend: float samples times 32768, Kaldi fbank with 80 bins, hamming, 25 ms window, 10 ms shift,
+ * dither 0, then CMN, then the ONNX session on CPU.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { pathExists } from "./disk.js";
+import { openFleet } from "./fleet.js";
+import { PYTHON_FRAMES, spawnFramedWorker } from "./worker.js";
+export const EMBEDDING_SIZE = 192;
+/** `PODDRILL_EMBED_WEIGHTS`, else `~/.cache/poddrill/ecapa/voxceleb_ECAPA512.onnx`. */
+export function embedWeightsPath(env) {
+    const configured = env["PODDRILL_EMBED_WEIGHTS"];
+    if (configured !== undefined && configured !== "") {
+        return configured;
+    }
+    return join(homedir(), ".cache", "poddrill", "ecapa", "voxceleb_ECAPA512.onnx");
+}
+/** Spawns nothing until the first stretch. A missing weights file fails each call without spawning. */
+export function openEmbedHost(embeddingLimit, weightsPath) {
+    if (!Number.isInteger(embeddingLimit) || embeddingLimit < 1) {
+        throw new Error(`embedding limit must be a positive integer, got ${embeddingLimit}`);
+    }
+    const pool = openFleet({
+        limit: embeddingLimit,
+        spawn: spawnEmbedWorker(weightsPath),
+        closedMessage: "embedding host is closed",
+    });
+    const requireWeights = async () => {
+        if (!(await pathExists(weightsPath))) {
+            throw new Error(`ECAPA weights are missing at ${weightsPath}. Put the file there or set PODDRILL_EMBED_WEIGHTS.`);
+        }
+    };
+    return {
+        prepare: requireWeights,
+        async embedStretch(wavPath) {
+            await requireWeights();
+            return pool.run(wavPath);
+        },
+        close: () => pool.close(),
+        release: () => pool.release(),
+    };
+}
+function spawnEmbedWorker(weightsPath) {
+    return (events) => {
+        const link = spawnFramedWorker({
+            label: "ecapa",
+            args: ["-c", WORKER_SCRIPT, weightsPath],
+            checkReady: async () => undefined,
+            parseResult: parseEmbedding,
+        }, events);
+        return {
+            request: (wavPath) => link.request({ wavPath }),
+            close: () => link.close(),
+        };
+    };
+}
+function parseEmbedding(value) {
+    if (!Array.isArray(value)) {
+        throw new Error("ecapa result must be an array");
+    }
+    const vector = [];
+    for (const item of value) {
+        if (typeof item !== "number" || !Number.isFinite(item)) {
+            throw new Error("ecapa result must hold finite numbers");
+        }
+        vector.push(item);
+    }
+    if (vector.length !== EMBEDDING_SIZE) {
+        throw new Error(`ecapa result has ${vector.length} values, not ${EMBEDDING_SIZE}`);
+    }
+    return vector;
+}
+/** Mirrors torchaudio's `compliance.kaldi.fbank`, including DC removal and 0.97 preemphasis. */
+const WORKER_SCRIPT = [
+    PYTHON_FRAMES,
+    "import wave",
+    "import numpy as np",
+    "import onnxruntime as ort",
+    "session = ort.InferenceSession(sys.argv[1], providers=[\"CPUExecutionProvider\"])",
+    "feed = session.get_inputs()[0].name",
+    "RATE = 16000",
+    "FRAME = 400",
+    "SHIFT = 160",
+    "FFT = 512",
+    "BINS = 80",
+    "EPS = float(np.finfo(np.float32).eps)",
+    "def mel(freq):",
+    "    return 1127.0 * np.log(1.0 + freq / 700.0)",
+    "def mel_banks():",
+    "    low = mel(20.0)",
+    "    delta = (mel(RATE / 2.0) - low) / (BINS + 1)",
+    "    bins = mel(np.arange(FFT // 2) * (RATE / FFT))[None, :]",
+    "    left = low + np.arange(BINS)[:, None] * delta",
+    "    center = left + delta",
+    "    right = center + delta",
+    "    banks = np.maximum(0.0, np.minimum((bins - left) / delta, (right - bins) / delta))",
+    "    return np.pad(banks, ((0, 0), (0, 1)))",
+    "BANKS = mel_banks()",
+    "WINDOW = 0.54 - 0.46 * np.cos(2.0 * np.pi * np.arange(FRAME) / (FRAME - 1))",
+    "def fbank(samples):",
+    "    if len(samples) < FRAME:",
+    "        raise ValueError(\"stretch is shorter than one 25 ms frame\")",
+    "    count = 1 + (len(samples) - FRAME) // SHIFT",
+    "    index = np.arange(FRAME)[None, :] + SHIFT * np.arange(count)[:, None]",
+    "    frames = samples[index].astype(np.float64)",
+    "    frames = frames - frames.mean(axis=1, keepdims=True)",
+    "    frames = frames - 0.97 * np.concatenate([frames[:, :1], frames[:, :-1]], axis=1)",
+    "    power = np.abs(np.fft.rfft(frames * WINDOW, n=FFT)) ** 2",
+    "    return np.log(np.maximum(power @ BANKS.T, EPS))",
+    "def read_wav(path):",
+    "    with wave.open(path, \"rb\") as reader:",
+    "        if reader.getnchannels() != 1 or reader.getsampwidth() != 2 or reader.getframerate() != RATE:",
+    "            raise ValueError(path + \" is not 16-bit mono 16 kHz wav\")",
+    "        pcm = reader.readframes(reader.getnframes())",
+    "    return np.frombuffer(pcm, dtype=\"<i2\").astype(np.float64) / 32768.0",
+    "def embed(message):",
+    "    wav_path = message[\"wavPath\"]",
+    "    feats = fbank(read_wav(wav_path) * 32768.0)",
+    "    feats = feats - feats.mean(axis=0, keepdims=True)",
+    "    output = session.run(None, {feed: feats[None, :, :].astype(np.float32)})[0]",
+    "    return [float(value) for value in np.asarray(output).reshape(-1)]",
+    "send({\"kind\": \"ready\"})",
+    "serve(embed)",
+].join("\n");

package/dist/episode.js

@@ -0,0 +1,259 @@
+/**
+ * Episode clock, slice plan, and WebVTT projection.
+ * Cue times are built only by adding a slice start to a Whistle word time.
+ */
+/** Milliseconds. Constructed only by `shift`. */
+export class EpisodeTime {
+    milliseconds;
+    constructor(milliseconds) {
+        this.milliseconds = milliseconds;
+    }
+    /**
+     * The only way to build an episode time.
+     * `sliceStartMs` is the slice offset. `wordSeconds` is Whistle's slice-relative clock.
+     */
+    static shift(sliceStartMs, wordSeconds) {
+        if (!Number.isInteger(sliceStartMs) || sliceStartMs < 0) {
+            throw new Error("slice start must be a non-negative integer millisecond");
+        }
+        if (!Number.isFinite(wordSeconds) || wordSeconds < 0) {
+            throw new Error("word time must be a non-negative finite second");
+        }
+        return new EpisodeTime(sliceStartMs + Math.round(wordSeconds * 1000));
+    }
+}
+/** 28 seconds, under Whistle's 30 second limit. */
+export const SLICE_MS = 28000;
+/** Overlap so a hard cut can drop the repeated word from the later slice. */
+export const OVERLAP_MS = 1000;
+/** A cue longer than this closes even when Whistle omitted punctuation. */
+export const MAX_CUE_MS = 12000;
+const STEP_MS = SLICE_MS - OVERLAP_MS;
+/** Fixed grid. No silence detector. */
+export function planSlices(durationMs) {
+    if (!Number.isInteger(durationMs) || durationMs < 0) {
+        throw new Error("duration must be a non-negative integer millisecond");
+    }
+    if (durationMs === 0) {
+        return [];
+    }
+    const slices = [];
+    let index = 0;
+    for (let start = 0; start < durationMs; start += STEP_MS) {
+        const end = Math.min(start + SLICE_MS, durationMs);
+        const keepEnd = end === durationMs ? durationMs : start + STEP_MS;
+        slices.push({
+            index,
+            startMs: start,
+            endMs: end,
+            keepStartMs: start,
+            keepEndMs: keepEnd,
+        });
+        index += 1;
+        if (end === durationMs) {
+            break;
+        }
+    }
+    return slices;
+}
+/**
+ * Rebuild cues and WebVTT from slice records.
+ * A rerun with the same records returns the same text.
+ */
+export function projectSlices(records) {
+    const kept = [];
+    const segments = [];
+    for (const record of records) {
+        const fates = [];
+        if (record.whistle.kind === "speech") {
+            record.whistle.words.forEach((word, wordIndex) => {
+                const start = EpisodeTime.shift(record.plan.startMs, word.start);
+                let end = EpisodeTime.shift(record.plan.startMs, word.end);
+                if (end.milliseconds <= start.milliseconds) {
+                    end = EpisodeTime.shift(record.plan.startMs, word.start + 0.001);
+                }
+                const inWindow = start.milliseconds >= record.plan.keepStartMs &&
+                    start.milliseconds < record.plan.keepEndMs;
+                if (inWindow) {
+                    kept.push({
+                        sliceIndex: record.plan.index,
+                        wordIndex,
+                        text: word.word,
+                        start,
+                        end,
+                    });
+                }
+                fates.push({
+                    wordIndex,
+                    word: word.word,
+                    episodeStart: start,
+                    episodeEnd: end,
+                    kept: inWindow,
+                    cueId: undefined,
+                });
+            });
+        }
+        segments.push({
+            sliceIndex: record.plan.index,
+            slicePath: record.slicePath,
+            startMs: record.plan.startMs,
+            endMs: record.plan.endMs,
+            whistle: record.whistle,
+            words: fates,
+        });
+    }
+    const cues = groupCues(kept);
+    const withCueIds = assignCueIds(segments, cues);
+    return {
+        vtt: renderVtt(cues),
+        cues,
+        segments: withCueIds,
+    };
+}
+function groupCues(words) {
+    const cues = [];
+    let bucket = [];
+    const close = () => {
+        if (bucket.length === 0) {
+            return;
+        }
+        const first = bucket[0];
+        const last = bucket[bucket.length - 1];
+        if (first === undefined || last === undefined) {
+            return;
+        }
+        cues.push({
+            id: cueId(cues.length),
+            start: first.start,
+            end: last.end,
+            text: bucket.map((word) => word.text).join(" "),
+            pieces: bucket.map((word) => ({
+                sliceIndex: word.sliceIndex,
+                wordIndex: word.wordIndex,
+            })),
+        });
+        bucket = [];
+    };
+    for (const word of words) {
+        const first = bucket[0];
+        if (first !== undefined &&
+            word.start.milliseconds - first.start.milliseconds >= MAX_CUE_MS) {
+            close();
+        }
+        bucket.push(word);
+        // CJK lines end on 。！？. The ASCII class never sees them, so the cue would run on.
+        if (/[.!?。！？]$/.test(word.text)) {
+            close();
+        }
+    }
+    close();
+    return cues;
+}
+function cueId(index) {
+    return `c${String(index + 1).padStart(4, "0")}`;
+}
+function assignCueIds(segments, cues) {
+    const cueByPiece = new Map();
+    for (const cue of cues) {
+        for (const piece of cue.pieces) {
+            cueByPiece.set(`${piece.sliceIndex}:${piece.wordIndex}`, cue.id);
+        }
+    }
+    return segments.map((segment) => ({
+        ...segment,
+        words: segment.words.map((word) => ({
+            ...word,
+            cueId: cueByPiece.get(`${segment.sliceIndex}:${word.wordIndex}`),
+        })),
+    }));
+}
+function renderVtt(cues) {
+    const blocks = cues.map((cue) => {
+        return [
+            cue.id,
+            `${stamp(cue.start.milliseconds)} --> ${stamp(cue.end.milliseconds)}`,
+            escapeCue(cue.text),
+        ].join("\n");
+    });
+    return ["WEBVTT", ...blocks].join("\n\n").concat("\n");
+}
+function stamp(ms) {
+    const hours = Math.floor(ms / 3_600_000);
+    const minutes = Math.floor((ms % 3_600_000) / 60_000);
+    const seconds = Math.floor((ms % 60_000) / 1_000);
+    const millis = ms % 1_000;
+    return `${pad(hours)}:${pad(minutes)}:${pad(seconds)}.${String(millis).padStart(3, "0")}`;
+}
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+function escapeCue(text) {
+    return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+}
+function asRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return undefined;
+    }
+    return Object.fromEntries(Object.entries(value));
+}
+function readString(record, key) {
+    const value = record[key];
+    if (typeof value !== "string") {
+        throw new Error(`Whistle field ${key} must be a string`);
+    }
+    return value;
+}
+function readNumber(record, key) {
+    const value = record[key];
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        throw new Error(`Whistle field ${key} must be a finite number`);
+    }
+    return value;
+}
+/** Parse one Whistle JSON object at the boundary. */
+export function parseWhistle(value) {
+    const record = asRecord(value);
+    if (record === undefined) {
+        throw new Error("Whistle result must be an object");
+    }
+    const text = readString(record, "text");
+    const language = readString(record, "language");
+    const ttftMs = readNumber(record, "ttft_ms");
+    const decodeTps = readNumber(record, "decode_tps");
+    const wordsValue = record["words"];
+    if (text === "" && language === "" && !Array.isArray(wordsValue)) {
+        return { kind: "silence", text: "", language: "", ttftMs, decodeTps };
+    }
+    if (!Array.isArray(wordsValue)) {
+        throw new Error("Whistle speech result must include words");
+    }
+    const words = wordsValue.map((item) => {
+        const word = asRecord(item);
+        if (word === undefined) {
+            throw new Error("Whistle word must be an object");
+        }
+        return {
+            word: readString(word, "word"),
+            start: readNumber(word, "start"),
+            end: readNumber(word, "end"),
+            probability: readNumber(word, "probability"),
+        };
+    });
+    return { kind: "speech", text, language, ttftMs, decodeTps, words };
+}
+/** Inverse of `parseWhistle`. Writes Whistle's wire field names. */
+export function serializeWhistle(result) {
+    const wire = {
+        text: result.text,
+        language: result.language,
+        ttft_ms: result.ttftMs,
+        decode_tps: result.decodeTps,
+    };
+    if (result.kind === "silence") {
+        return JSON.stringify(wire);
+    }
+    return JSON.stringify({
+        ...wire,
+        words: result.words.map(({ word, start, end, probability }) => ({ word, start, end, probability })),
+    });
+}

package/dist/fleet.js

@@ -0,0 +1,176 @@
+/**
+ * A warm, demand-grown fleet of single-request workers behind one `run`.
+ * Policy (high-water hold):
+ * - Nothing spawns at open.
+ * - Grow by one when a request is waiting and every live worker is busy, while live < limit.
+ *   A booting worker is live and not busy, so at most one worker boots at a time.
+ * - Idle workers stay until `release` or `close`.
+ * - A dead worker is removed. It is replaced only by the grow rule above.
+ * Dead is represented by absence from `slots`, so the live count is `slots.size`.
+ */
+/** Hosts pass their process spawner. Tests pass in-memory links. */
+export function openFleet(options) {
+    return new Fleet(options.limit, options.spawn, options.closedMessage);
+}
+/** Insertion order of `slots` is spawn order, so dispatch prefers the oldest idle worker. */
+function nextMove(slots, waiting, limit) {
+    if (waiting === 0) {
+        return { kind: "hold" };
+    }
+    let booting = false;
+    for (const [workerId, slot] of slots) {
+        switch (slot.state) {
+            case "idle":
+                return { kind: "dispatch", workerId, link: slot.link };
+            case "booting":
+                booting = true;
+                break;
+            case "busy":
+                break;
+            default: {
+                const leftover = slot.state;
+                throw new Error(`unexpected worker state ${String(leftover)}`);
+            }
+        }
+    }
+    if (booting || slots.size >= limit) {
+        return { kind: "hold" };
+    }
+    return { kind: "grow" };
+}
+class Fleet {
+    limit;
+    spawn;
+    closedMessage;
+    /** Live workers only: booting, idle, or busy. */
+    slots = new Map();
+    /** FIFO. With one lane upstream this keeps today's request order. */
+    waiting = [];
+    nextId = 0;
+    closed = false;
+    constructor(limit, spawn, closedMessage) {
+        this.limit = limit;
+        this.spawn = spawn;
+        this.closedMessage = closedMessage;
+    }
+    run(query) {
+        if (this.closed) {
+            return Promise.reject(new Error(this.closedMessage));
+        }
+        return new Promise((resolve, reject) => {
+            this.waiting.push({ query, resolve, reject });
+            this.pump();
+        });
+    }
+    async close() {
+        if (this.closed) {
+            return;
+        }
+        this.closed = true;
+        for (const waiter of this.waiting.splice(0)) {
+            waiter.reject(new Error(this.closedMessage));
+        }
+        for (const slot of this.slots.values()) {
+            slot.link.close();
+        }
+        this.slots.clear();
+    }
+    release() {
+        if (this.closed || this.waiting.length > 0) {
+            return false;
+        }
+        for (const slot of this.slots.values()) {
+            switch (slot.state) {
+                case "idle":
+                    break;
+                case "booting":
+                case "busy":
+                    return false;
+                default: {
+                    const leftover = slot.state;
+                    throw new Error(`unexpected worker state ${String(leftover)}`);
+                }
+            }
+        }
+        for (const slot of this.slots.values()) {
+            slot.link.close();
+        }
+        this.slots.clear();
+        return true;
+    }
+    pump() {
+        while (!this.closed) {
+            const move = nextMove(this.slots, this.waiting.length, this.limit);
+            switch (move.kind) {
+                case "hold":
+                    return;
+                case "grow": {
+                    const id = this.nextId;
+                    this.nextId += 1;
+                    const link = this.spawn({
+                        ready: () => {
+                            this.onReady(id);
+                        },
+                        exit: (reason) => {
+                            this.onExit(id, reason);
+                        },
+                    });
+                    this.slots.set(id, { state: "booting", link });
+                    break;
+                }
+                case "dispatch": {
+                    const waiter = this.waiting.shift();
+                    if (waiter === undefined) {
+                        return;
+                    }
+                    this.slots.set(move.workerId, { state: "busy", link: move.link });
+                    // The worker goes idle before the caller sees the result, so an immediate next call reuses it.
+                    void move.link.request(waiter.query).then((result) => {
+                        this.onSettled(move.workerId);
+                        waiter.resolve(result);
+                    }, (error) => {
+                        this.onSettled(move.workerId);
+                        waiter.reject(error);
+                    });
+                    break;
+                }
+                default: {
+                    const leftover = move;
+                    throw new Error(`unexpected fleet move ${JSON.stringify(leftover)}`);
+                }
+            }
+        }
+    }
+    onSettled(id) {
+        const slot = this.slots.get(id);
+        if (slot?.state === "busy") {
+            this.slots.set(id, { state: "idle", link: slot.link });
+        }
+        this.pump();
+    }
+    onReady(id) {
+        const slot = this.slots.get(id);
+        if (slot?.state !== "booting") {
+            return;
+        }
+        this.slots.set(id, { state: "idle", link: slot.link });
+        this.pump();
+    }
+    /**
+     * A worker that died booting fails the oldest waiting request with its reason.
+     * Load failures are deterministic (no python3, a missing module, weights that do not load),
+     * and failing one request per failed boot bounds the respawn loop by the upstream window.
+     * A worker that died busy fails only its own request, which the link rejects.
+     */
+    onExit(id, reason) {
+        const slot = this.slots.get(id);
+        if (slot === undefined) {
+            return;
+        }
+        this.slots.delete(id);
+        if (slot.state === "booting") {
+            this.waiting.shift()?.reject(new Error(reason));
+        }
+        this.pump();
+    }
+}