@ailoud/providers 1.0.0-dev.1

package/dist/stt/whisperCpp.d.ts

@@ -0,0 +1,50 @@
+import type { RawSegment, TranscriptionProvider } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+/**
+ * Pulls the language out of `whisper-cli -dl` output. The line arrives on
+ * stderr amid backend chatter, so this matches rather than reads a field.
+ */
+export declare function parseDetectedLanguage(output: string): string;
+/**
+ * Pure parser for whisper-cli's "-oj" JSON output.
+ *
+ * Whisper prefixes every segment's text with a leading space, and emits
+ * silent stretches of audio as a segment with blank (or whitespace-only)
+ * text. Trimming and dropping those here keeps the quirk out of the
+ * database, where it would otherwise resurface in every export and every
+ * prompt built from stored segments.
+ */
+export declare function parseWhisperJson(raw: string): {
+    language: string;
+    segments: RawSegment[];
+};
+export interface WhisperCppOptions {
+    readonly binary: string;
+    readonly modelPath: string;
+    readonly runner?: typeof defaultRunner;
+    readonly readFile?: (path: string) => Promise<string>;
+}
+export declare class WhisperCppProvider implements TranscriptionProvider {
+    private readonly options;
+    readonly name = "whisper-cpp";
+    readonly capabilities: {
+        readonly maxBytes: null;
+        readonly supportsDiarization: false;
+        readonly supportsLanguageHint: true;
+        readonly supportsLanguageDetection: true;
+    };
+    private readonly runner;
+    private readonly readFile;
+    constructor(options: WhisperCppOptions);
+    transcribe(audioPath: string, opts: {
+        readonly language?: string;
+        readonly model?: string;
+    }): Promise<{
+        language: string;
+        model: string;
+        segments: RawSegment[];
+    }>;
+    detectLanguage(audioPath: string, opts?: {
+        readonly model?: string;
+    }): Promise<string>;
+}

package/dist/stt/whisperCpp.js

@@ -0,0 +1,116 @@
+import { readFile as readFileFromDisk } from 'node:fs/promises';
+import { basename, dirname, extname, join } from 'node:path';
+import { FailureError } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+/**
+ * Pulls the language out of `whisper-cli -dl` output. The line arrives on
+ * stderr amid backend chatter, so this matches rather than reads a field.
+ */
+export function parseDetectedLanguage(output) {
+    const match = /auto-detected language:\s*([a-z]{2,3})\b/i.exec(output);
+    if (match?.[1] === undefined) {
+        throw new FailureError('whisper did not report a detected language; the output format may have changed');
+    }
+    return match[1].toLowerCase();
+}
+/**
+ * Pure parser for whisper-cli's "-oj" JSON output.
+ *
+ * Whisper prefixes every segment's text with a leading space, and emits
+ * silent stretches of audio as a segment with blank (or whitespace-only)
+ * text. Trimming and dropping those here keeps the quirk out of the
+ * database, where it would otherwise resurface in every export and every
+ * prompt built from stored segments.
+ */
+export function parseWhisperJson(raw) {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.transcription)) {
+        throw new FailureError('whisper produced no "transcription" array; the output format changed');
+    }
+    const segments = [];
+    for (const entry of parsed.transcription) {
+        const text = (entry.text ?? '').trim();
+        if (text === '')
+            continue;
+        segments.push({
+            startMs: entry.offsets?.from ?? 0,
+            endMs: entry.offsets?.to ?? 0,
+            text,
+        });
+    }
+    return { language: parsed.result?.language ?? 'unknown', segments };
+}
+/**
+ * Builds the whisper-cli argument array for one transcription run.
+ *
+ * NOT VERIFIED AGAINST A REAL BUILD: these flags (-m model path, -f input
+ * file, -l language or "auto", -oj JSON output, -of output base path) are
+ * written against whisper.cpp's documented command-line interface. No
+ * whisper-cli binary is available in this environment to confirm them
+ * against an actual build. The end-to-end suite runs against a real binary
+ * and is where this argument list gets confirmed; if a flag turns out to
+ * differ there, fix it here in this one place.
+ */
+function buildWhisperArgs(modelPath, audioPath, language, outputBase) {
+    return ['-m', modelPath, '-f', audioPath, '-l', language ?? 'auto', '-oj', '-of', outputBase];
+}
+export class WhisperCppProvider {
+    options;
+    name = 'whisper-cpp';
+    capabilities = {
+        maxBytes: null,
+        supportsDiarization: false,
+        supportsLanguageHint: true,
+        supportsLanguageDetection: true,
+    };
+    runner;
+    readFile;
+    constructor(options) {
+        this.options = options;
+        this.runner = options.runner ?? defaultRunner;
+        this.readFile = options.readFile ?? ((path) => readFileFromDisk(path, 'utf8'));
+    }
+    async transcribe(audioPath, opts) {
+        // whisper-cli writes <outputBase>.json rather than printing to stdout.
+        // Derived from the filename component only (node:path), not a bare regex
+        // on the whole path: a regex anchored on "last dot in the string" matches
+        // a dot inside a directory name too, so an extension-less file inside a
+        // directory like "ailoud-1.2" would collapse to a sibling path outside that
+        // directory and silently collide with another recording's output.
+        // NOT VERIFIED AGAINST A REAL BUILD: that whisper-cli writes exactly
+        // "<outputBase>.json" (not, say, "<outputBase>.json.txt" or a name that
+        // depends on other flags) is likewise taken from documentation, not
+        // confirmed against a real run; see the warning on buildWhisperArgs.
+        const outputBase = join(dirname(audioPath), basename(audioPath, extname(audioPath)));
+        const modelPath = opts.model ?? this.options.modelPath;
+        const args = buildWhisperArgs(modelPath, audioPath, opts.language, outputBase);
+        // Six hours, not the run helper's half-hour default: a long recording on
+        // CPU-only whisper is genuinely slow, and the default would kill real work.
+        const result = await this.runner(this.options.binary, args, { timeoutMs: 6 * 60 * 60_000 });
+        if (result.code !== 0) {
+            throw new FailureError(`whisper failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+        }
+        const outputPath = `${outputBase}.json`;
+        let raw;
+        try {
+            raw = await this.readFile(outputPath);
+        }
+        catch (error) {
+            const reason = error instanceof Error ? error.message : String(error);
+            throw new FailureError(`whisper reported success but ${outputPath} could not be read: ${reason}`);
+        }
+        const parsed = parseWhisperJson(raw);
+        return { ...parsed, model: basename(modelPath) };
+    }
+    async detectLanguage(audioPath, opts = {}) {
+        // -dl exits after detecting, without transcribing. It costs about the
+        // same as a short transcription because almost all of it is loading the
+        // model; detection itself does not grow with clip length.
+        const modelPath = opts.model ?? this.options.modelPath;
+        const result = await this.runner(this.options.binary, ['-m', modelPath, '-f', audioPath, '-dl'], { timeoutMs: 10 * 60_000 });
+        if (result.code !== 0) {
+            throw new FailureError(`whisper could not detect a language: ${result.stderr.trim() || `exit ${result.code}`}`);
+        }
+        return parseDetectedLanguage(`${result.stdout}\n${result.stderr}`);
+    }
+}

package/dist/system/nodeFs.d.ts

@@ -0,0 +1,14 @@
+import type { Fs, TempDir, TempFile } from '@ailoud/core';
+export declare class NodeFs implements Fs {
+    exists(path: string): Promise<boolean>;
+    ensureDir(path: string): Promise<void>;
+    sha256(path: string): Promise<string>;
+    copyFile(source: string, destination: string): Promise<void>;
+    removeFile(path: string): Promise<void>;
+    listFiles(directory: string): Promise<string[]>;
+    isDirectory(path: string): Promise<boolean>;
+    tempFile(extension: string): Promise<TempFile>;
+    tempDir(): Promise<TempDir>;
+    writeTextFile(path: string, content: string): Promise<void>;
+    readTextFile(path: string): Promise<string>;
+}

package/dist/system/nodeFs.js

@@ -0,0 +1,80 @@
+import { createHash } from 'node:crypto';
+import { createReadStream } from 'node:fs';
+import { copyFile, mkdir, mkdtemp, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+/** True for the one stat failure that legitimately means "does not exist". */
+function isNotFound(error) {
+    return error.code === 'ENOENT';
+}
+export class NodeFs {
+    async exists(path) {
+        try {
+            await stat(path);
+            return true;
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return false;
+            throw error; // permission-denied and friends are real errors, not "missing"
+        }
+    }
+    async ensureDir(path) {
+        await mkdir(path, { recursive: true });
+    }
+    async sha256(path) {
+        const hash = createHash('sha256');
+        // node:fs's read stream types its chunk as `string | Buffer` because the
+        // encoding option can request strings; this stream never sets one, so
+        // the chunk is always a Buffer.
+        for await (const chunk of createReadStream(path))
+            hash.update(chunk);
+        return hash.digest('hex');
+    }
+    async copyFile(source, destination) {
+        await copyFile(source, destination);
+    }
+    async removeFile(path) {
+        // force: a file already gone is the outcome the caller asked for, and
+        // failing on it would make deletion non-idempotent for no gain.
+        await rm(path, { force: true });
+    }
+    async listFiles(directory) {
+        const entries = await readdir(directory, { withFileTypes: true });
+        return entries
+            .filter((e) => e.isFile())
+            .map((e) => join(directory, e.name))
+            .sort();
+    }
+    async isDirectory(path) {
+        try {
+            return (await stat(path)).isDirectory();
+        }
+        catch (error) {
+            if (isNotFound(error))
+                return false;
+            throw error;
+        }
+    }
+    async tempFile(extension) {
+        const dir = await mkdtemp(join(tmpdir(), 'ailoud-'));
+        const path = join(dir, `audio${extension}`);
+        return {
+            path,
+            // Removes the whole directory, not just this file: a provider (for
+            // example whisper-cli) can write other output alongside it, and that
+            // must not outlive the temp file it was derived from.
+            remove: () => rm(dir, { force: true, recursive: true }),
+        };
+    }
+    async tempDir() {
+        const dir = await mkdtemp(join(tmpdir(), 'ailoud-'));
+        return { path: dir, remove: () => rm(dir, { force: true, recursive: true }) };
+    }
+    async writeTextFile(path, content) {
+        await writeFile(path, content, 'utf8');
+    }
+    async readTextFile(path) {
+        return readFile(path, 'utf8');
+    }
+}

package/dist/system/systemClock.d.ts

@@ -0,0 +1,20 @@
+import type { Clock, Ids } from '@ailoud/core';
+export declare class SystemClock implements Clock {
+    nowIso(): string;
+}
+/**
+ * Monotonic ULID generator.
+ *
+ * `encodeUlid(Date.now(), randomBytes)` alone can invert two ids minted in
+ * the same millisecond, since they then differ only by independent random
+ * draws. This class remembers the last timestamp and random block; when
+ * `Date.now()` has not advanced past it, it reuses that millisecond and
+ * increments the previous random block as a big-endian integer instead of
+ * drawing fresh randomness, so same-millisecond ids still sort in the order
+ * they were generated.
+ */
+export declare class UlidIds implements Ids {
+    private lastTimeMs;
+    private lastRandom;
+    next(): string;
+}

package/dist/system/systemClock.js

@@ -0,0 +1,55 @@
+import { encodeUlid } from '@ailoud/core';
+export class SystemClock {
+    nowIso() {
+        return new Date().toISOString();
+    }
+}
+const RANDOM_BYTES = 10;
+/**
+ * Monotonic ULID generator.
+ *
+ * `encodeUlid(Date.now(), randomBytes)` alone can invert two ids minted in
+ * the same millisecond, since they then differ only by independent random
+ * draws. This class remembers the last timestamp and random block; when
+ * `Date.now()` has not advanced past it, it reuses that millisecond and
+ * increments the previous random block as a big-endian integer instead of
+ * drawing fresh randomness, so same-millisecond ids still sort in the order
+ * they were generated.
+ */
+export class UlidIds {
+    lastTimeMs = -1;
+    lastRandom = new Uint8Array(RANDOM_BYTES);
+    next() {
+        const now = Date.now();
+        if (now > this.lastTimeMs) {
+            this.lastTimeMs = now;
+            this.lastRandom = randomBytes();
+        }
+        else {
+            incrementBigEndian(this.lastRandom);
+        }
+        return encodeUlid(this.lastTimeMs, this.lastRandom);
+    }
+}
+// No return-type annotation: `Uint8Array` unparameterized defaults to the
+// wider `Uint8Array<ArrayBufferLike>`, whereas the type TypeScript infers
+// here from `crypto.getRandomValues(new Uint8Array(n))` is the narrower
+// `Uint8Array<ArrayBuffer>` -- annotating this would widen it right back.
+function randomBytes() {
+    return crypto.getRandomValues(new Uint8Array(RANDOM_BYTES));
+}
+function incrementBigEndian(bytes) {
+    for (let i = bytes.length - 1; i >= 0; i -= 1) {
+        const value = bytes[i];
+        if (value === undefined)
+            continue;
+        if (value === 255) {
+            bytes[i] = 0;
+            continue;
+        }
+        bytes[i] = value + 1;
+        return;
+    }
+    // All 80 bits wrapped to zero: would need 2**80 ids minted within a single
+    // millisecond, which is not reachable in practice.
+}

package/dist/vad/whisperVad.d.ts

@@ -0,0 +1,14 @@
+import type { SpeechSegmenter, SpeechSpan } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+export declare function parseVadSegments(output: string): SpeechSpan[];
+export interface WhisperVadOptions {
+    readonly binary: string;
+    readonly vadModelPath: string;
+    readonly runner?: typeof defaultRunner;
+}
+export declare class WhisperVadSegmenter implements SpeechSegmenter {
+    private readonly options;
+    private readonly runner;
+    constructor(options: WhisperVadOptions);
+    segments(audioPath: string): Promise<SpeechSpan[]>;
+}

package/dist/vad/whisperVad.js

@@ -0,0 +1,58 @@
+import { FailureError } from '@ailoud/core';
+import { run as defaultRunner } from '../process/run.js';
+// Explicit, not left to fall through to the run helper's own default, even
+// though the two currently happen to be the same 30 minutes: segmentation
+// reads the whole recording once and is comparatively fast, so it does not
+// need whisper-cli's own six-hour transcription ceiling (see whisperCpp.ts).
+// Spelling it out here means a future change to the helper's default cannot
+// silently change this call's timeout out from under it.
+const VAD_TIMEOUT_MS = 30 * 60_000;
+/**
+ * Matches one segment line from whisper-vad-speech-segments' stdout.
+ *
+ * NOT the shape the task brief assumed ("0.00 - 175.00"): a real run against
+ * fixtures/mixed-short.wav with -np produced lines shaped like
+ * "Speech segment 0: start = 0.00, end = 346.00", preceded by a
+ * "Detected N speech segments:" header. Both captures are centiseconds per
+ * the tool's own help text, so both are multiplied by ten to reach
+ * milliseconds.
+ */
+const SEGMENT_LINE = /^\s*Speech segment \d+:\s*start\s*=\s*(\d+(?:\.\d+)?)\s*,\s*end\s*=\s*(\d+(?:\.\d+)?)\s*$/;
+export function parseVadSegments(output) {
+    const spans = [];
+    for (const line of output.split('\n')) {
+        const match = SEGMENT_LINE.exec(line);
+        if (match?.[1] === undefined || match[2] === undefined)
+            continue;
+        spans.push({
+            startMs: Math.round(Number(match[1]) * 10),
+            endMs: Math.round(Number(match[2]) * 10),
+        });
+    }
+    return spans;
+}
+export class WhisperVadSegmenter {
+    options;
+    runner;
+    constructor(options) {
+        this.options = options;
+        this.runner = options.runner ?? defaultRunner;
+    }
+    async segments(audioPath) {
+        const result = await this.runner(this.options.binary, ['-f', audioPath, '-vm', this.options.vadModelPath, '-np'], { timeoutMs: VAD_TIMEOUT_MS });
+        if (result.code !== 0) {
+            throw new FailureError(`speech segmentation failed: ${result.stderr.trim() || `exit ${result.code}`}`);
+        }
+        const spans = parseVadSegments(result.stdout);
+        if (spans.length === 0) {
+            // Not `audioPath`: that names the pipeline's own scratch wav, which
+            // `Fs.tempFile`'s cleanup has already removed by the time this
+            // message reaches a user -- pointing them at a directory that no
+            // longer exists. Nothing else here identifies the source recording
+            // (see transcribe.ts's own "no speech" message for that), so this
+            // stays generic instead of naming a path at all.
+            throw new FailureError('no speech found; transcribe it without --multilingual');
+        }
+        return spans;
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@ailoud/providers",
+  "version": "1.0.0-dev.1",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@ailoud/core": "1.0.0-dev.1"
+  },
+  "description": "AILoud port implementations: ffmpeg, sqlite, whisper.cpp, and the LLM adapters",
+  "author": "Lorem Dev <contact@lorem.dev>",
+  "license": "Apache-2.0",
+  "homepage": "https://lorem-dev.github.io/ailoud/",
+  "bugs": {
+    "url": "https://github.com/lorem-dev/ailoud/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "keywords": [
+    "ailoud",
+    "whisper",
+    "ffmpeg",
+    "sqlite"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lorem-dev/ailoud.git",
+    "directory": "packages/providers"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}