@hyperdrive.bot/paseo-server 0.2.6

package/dist/server/server/speech/providers/local/sherpa/model-downloader.js

@@ -0,0 +1,142 @@
+import { createWriteStream } from "node:fs";
+import { mkdir, rename, rm, stat } from "node:fs/promises";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { getSherpaOnnxModelSpec } from "./model-catalog.js";
+import { spawnProcess } from "../../../../../utils/spawn.js";
+export function getSherpaOnnxModelDir(modelsDir, modelId) {
+    const spec = getSherpaOnnxModelSpec(modelId);
+    return path.join(modelsDir, spec.extractedDir);
+}
+async function hasRequiredFiles(modelDir, requiredFiles) {
+    const results = await Promise.all(requiredFiles.map(async (rel) => {
+        const abs = path.join(modelDir, rel);
+        try {
+            const s = await stat(abs);
+            if (s.isDirectory()) {
+                return true;
+            }
+            return s.isFile() && s.size > 0;
+        }
+        catch {
+            return false;
+        }
+    }));
+    return results.every((present) => present);
+}
+async function downloadToFile(options) {
+    const { url, outputPath } = options;
+    const res = await fetch(url);
+    if (!res.ok) {
+        throw new Error(`Failed to download ${url}: ${res.status} ${res.statusText}`);
+    }
+    if (!res.body) {
+        throw new Error(`Failed to download ${url}: missing response body`);
+    }
+    const tmpPath = `${outputPath}.tmp-${Date.now()}`;
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    // The fetch ReadableStream type is slightly different from what Readable.fromWeb expects
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const nodeStream = Readable.fromWeb(res.body);
+    try {
+        await pipeline(nodeStream, createWriteStream(tmpPath));
+        await rename(tmpPath, outputPath);
+    }
+    catch (error) {
+        await rm(tmpPath, { force: true }).catch(() => undefined);
+        throw error;
+    }
+}
+async function extractTarArchive(archivePath, destDir) {
+    await mkdir(destDir, { recursive: true });
+    await new Promise((resolve, reject) => {
+        const child = spawnProcess("tar", ["xf", archivePath, "-C", destDir], {
+            stdio: "inherit",
+        });
+        child.on("error", reject);
+        child.on("exit", (code) => {
+            if (code === 0)
+                resolve();
+            else
+                reject(new Error(`tar exited with code ${code}`));
+        });
+    });
+}
+async function isNonEmptyFile(filePath) {
+    try {
+        const s = await stat(filePath);
+        return s.isFile() && s.size > 0;
+    }
+    catch {
+        return false;
+    }
+}
+export async function ensureSherpaOnnxModel(options) {
+    const logger = options.logger.child({
+        module: "speech",
+        provider: "local",
+        component: "model-downloader",
+        modelId: options.modelId,
+    });
+    const spec = getSherpaOnnxModelSpec(options.modelId);
+    const modelDir = path.join(options.modelsDir, spec.extractedDir);
+    if (await hasRequiredFiles(modelDir, spec.requiredFiles)) {
+        return modelDir;
+    }
+    logger.info({ modelsDir: options.modelsDir }, "Starting model download");
+    try {
+        const downloadsDir = path.join(options.modelsDir, ".downloads");
+        const archiveFilename = path.basename(new URL(spec.archiveUrl).pathname);
+        const archivePath = path.join(downloadsDir, archiveFilename);
+        if (!(await isNonEmptyFile(archivePath))) {
+            await downloadToFile({
+                url: spec.archiveUrl,
+                outputPath: archivePath,
+            });
+        }
+        logger.info({
+            modelId: options.modelId,
+            archivePath,
+            modelDir,
+        }, "Extracting model archive");
+        await extractTarArchive(archivePath, options.modelsDir);
+        logger.info({
+            modelId: options.modelId,
+            modelDir,
+        }, "Verifying downloaded model files");
+        if (!(await hasRequiredFiles(modelDir, spec.requiredFiles))) {
+            throw new Error(`Downloaded and extracted ${archiveFilename}, but required files are still missing in ${modelDir}.`);
+        }
+        logger.info({
+            modelId: options.modelId,
+            archivePath,
+        }, "Finalizing model artifacts");
+        try {
+            await rm(archivePath, { force: true });
+        }
+        catch {
+            // ignore
+        }
+        logger.info({ modelDir }, "Model download completed");
+        return modelDir;
+    }
+    catch (error) {
+        logger.error({ err: error }, "Model download failed");
+        throw error;
+    }
+}
+export async function ensureSherpaOnnxModels(options) {
+    const uniq = Array.from(new Set(options.modelIds));
+    const entries = await Promise.all(uniq.map(async (id) => {
+        const modelPath = await ensureSherpaOnnxModel({
+            modelsDir: options.modelsDir,
+            modelId: id,
+            logger: options.logger,
+        });
+        return [id, modelPath];
+    }));
+    // oxlint-disable-next-line typescript-eslint/no-unsafe-type-assertion
+    return Object.fromEntries(entries);
+}
+//# sourceMappingURL=model-downloader.js.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-offline-recognizer.d.ts

@@ -0,0 +1,49 @@
+import type pino from "pino";
+export interface SherpaOfflineRecognizerModel {
+    kind: "nemo_transducer";
+    encoder: string;
+    decoder: string;
+    joiner: string;
+    tokens: string;
+}
+export interface SherpaOfflineRecognizerConfig {
+    model: SherpaOfflineRecognizerModel;
+    numThreads?: number;
+    provider?: "cpu";
+    debug?: 0 | 1;
+    sampleRate?: number;
+    featureDim?: number;
+    decodingMethod?: "greedy_search";
+    maxActivePaths?: number;
+}
+interface SherpaOfflineRecognizerNative {
+    config?: {
+        featConfig?: {
+            sampleRate?: number;
+        };
+    };
+    createStream: () => unknown;
+    decode: (stream: unknown) => void;
+    getResult: (stream: unknown) => {
+        text?: string;
+    } | string | undefined;
+    free?: () => void;
+}
+interface SherpaOfflineStreamNative {
+    acceptWaveform: ((arg: {
+        samples: Float32Array;
+        sampleRate: number;
+    }) => void) & ((sampleRate: number, samples: Float32Array) => void);
+    free?: () => void;
+}
+export declare class SherpaOfflineRecognizerEngine {
+    readonly recognizer: SherpaOfflineRecognizerNative;
+    readonly sampleRate: number;
+    private readonly logger;
+    constructor(config: SherpaOfflineRecognizerConfig, logger: pino.Logger);
+    createStream(): SherpaOfflineStreamNative;
+    acceptWaveform(stream: SherpaOfflineStreamNative, sampleRate: number, samples: Float32Array): void;
+    free(): void;
+}
+export {};
+//# sourceMappingURL=sherpa-offline-recognizer.d.ts.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-offline-recognizer.js

@@ -0,0 +1,73 @@
+import { existsSync } from "node:fs";
+import { loadSherpaOnnxNode } from "./sherpa-onnx-node-loader.js";
+function assertFileExists(filePath, label) {
+    if (!existsSync(filePath)) {
+        throw new Error(`Missing ${label}: ${filePath}`);
+    }
+}
+export class SherpaOfflineRecognizerEngine {
+    constructor(config, logger) {
+        this.logger = logger.child({
+            module: "speech",
+            provider: "local",
+            component: "offline-recognizer",
+        });
+        assertFileExists(config.model.encoder, "offline encoder");
+        assertFileExists(config.model.decoder, "offline decoder");
+        assertFileExists(config.model.joiner, "offline joiner");
+        assertFileExists(config.model.tokens, "tokens");
+        const sherpa = loadSherpaOnnxNode();
+        const recognizerConfig = {
+            featConfig: {
+                sampleRate: config.sampleRate ?? 16000,
+                featureDim: config.featureDim ?? 80,
+            },
+            modelConfig: {
+                transducer: {
+                    encoder: config.model.encoder,
+                    decoder: config.model.decoder,
+                    joiner: config.model.joiner,
+                },
+                tokens: config.model.tokens,
+                modelType: "nemo_transducer",
+                numThreads: config.numThreads ?? 1,
+                provider: config.provider ?? "cpu",
+                debug: config.debug ?? 0,
+            },
+            decodingMethod: config.decodingMethod ?? "greedy_search",
+            maxActivePaths: config.maxActivePaths ?? 4,
+        };
+        this.recognizer = new sherpa.OfflineRecognizer(recognizerConfig);
+        const sr = this.recognizer?.config?.featConfig?.sampleRate;
+        this.sampleRate =
+            typeof sr === "number" && Number.isFinite(sr) && sr > 0
+                ? sr
+                : recognizerConfig.featConfig.sampleRate;
+        this.logger.info({ sampleRate: this.sampleRate, numThreads: recognizerConfig.modelConfig.numThreads }, "Sherpa offline recognizer initialized");
+    }
+    createStream() {
+        return this.recognizer.createStream();
+    }
+    acceptWaveform(stream, sampleRate, samples) {
+        if (!stream || typeof stream.acceptWaveform !== "function") {
+            throw new Error("Unexpected sherpa offline stream: missing acceptWaveform()");
+        }
+        // sherpa-onnx-node expects: acceptWaveform({ samples, sampleRate })
+        // sherpa-onnx (WASM) expects: acceptWaveform(sampleRate, samples)
+        if (stream.acceptWaveform.length <= 1) {
+            stream.acceptWaveform({ samples, sampleRate });
+        }
+        else {
+            stream.acceptWaveform(sampleRate, samples);
+        }
+    }
+    free() {
+        try {
+            this.recognizer?.free?.();
+        }
+        catch (err) {
+            this.logger.warn({ err }, "Failed to free sherpa offline recognizer");
+        }
+    }
+}
+//# sourceMappingURL=sherpa-offline-recognizer.js.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-onnx-node-loader.d.ts

@@ -0,0 +1,9 @@
+export interface SherpaOnnxNodeModule {
+    OfflineRecognizer: new (config: unknown) => unknown;
+    OnlineRecognizer?: new (config: unknown) => unknown;
+    OfflineTts?: new (config: unknown) => unknown;
+    Vad?: new (config: unknown, bufferSizeInSeconds: number) => unknown;
+    CircularBuffer?: new (capacity: number) => unknown;
+}
+export declare function loadSherpaOnnxNode(): SherpaOnnxNodeModule;
+//# sourceMappingURL=sherpa-onnx-node-loader.d.ts.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-onnx-node-loader.js

@@ -0,0 +1,107 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { applySherpaLoaderEnv, resolveSherpaLoaderEnv, sherpaPlatformPackageName, } from "./sherpa-runtime-env.js";
+import { createExternalCommandProcessEnv } from "../../../../paseo-env.js";
+let cached = null;
+function appendAttempt(attempts, target, error) {
+    attempts.push({ target, error });
+}
+function formatError(error) {
+    if (!error) {
+        return "unknown error";
+    }
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+function maybePatchLinuxAddonRunpath(addonPath) {
+    if (process.platform !== "linux") {
+        return;
+    }
+    const patchelfEnv = createExternalCommandProcessEnv("patchelf", process.env);
+    const patchelfCheck = spawnSync("patchelf", ["--version"], {
+        env: patchelfEnv,
+        stdio: "ignore",
+    });
+    if (patchelfCheck.status !== 0) {
+        return;
+    }
+    const currentRpath = spawnSync("patchelf", ["--print-rpath", addonPath], {
+        encoding: "utf8",
+        env: patchelfEnv,
+    });
+    if (currentRpath.status !== 0) {
+        return;
+    }
+    const rpath = (currentRpath.stdout ?? "").trim();
+    if (rpath.includes("$ORIGIN")) {
+        return;
+    }
+    spawnSync("patchelf", ["--set-rpath", "$ORIGIN", addonPath], {
+        env: patchelfEnv,
+        stdio: "ignore",
+    });
+}
+function loadWithRequire(requireFn, target, attempts) {
+    try {
+        return requireFn(target);
+    }
+    catch (error) {
+        appendAttempt(attempts, target, error);
+        return null;
+    }
+}
+function buildFailure(attempts, pkgName) {
+    const details = attempts
+        .map((attempt) => `- ${attempt.target}: ${formatError(attempt.error)}`)
+        .join("\n");
+    const message = [
+        `Failed to load sherpa-onnx-node for ${process.platform}-${process.arch}.`,
+        `Node ${process.version} (ABI ${process.versions.modules}).`,
+        `Platform package: ${pkgName}.`,
+        "Load attempts:",
+        details || "- (no attempts made)",
+    ].join("\n");
+    return new Error(message);
+}
+export function loadSherpaOnnxNode() {
+    if (cached) {
+        return cached;
+    }
+    const require = createRequire(import.meta.url);
+    const attempts = [];
+    // Pass through upstream support matrix first.
+    const direct = loadWithRequire(require, "sherpa-onnx-node", attempts);
+    if (direct) {
+        cached = direct;
+        return cached;
+    }
+    // sherpa-onnx-node depends on a platform-specific package (e.g. sherpa-onnx-darwin-arm64)
+    // that contains the native addon and shared libraries.
+    const pkgName = sherpaPlatformPackageName();
+    const resolvedEnv = resolveSherpaLoaderEnv();
+    const platformPkgDir = resolvedEnv?.libDir ?? null;
+    if (platformPkgDir) {
+        applySherpaLoaderEnv(process.env);
+        const addonPath = path.join(platformPkgDir, "sherpa-onnx.node");
+        if (existsSync(addonPath)) {
+            const byPath = loadWithRequire(require, addonPath, attempts);
+            if (byPath) {
+                cached = byPath;
+                return cached;
+            }
+            // Linux fallback for broken prebuilt RUNPATHs.
+            maybePatchLinuxAddonRunpath(addonPath);
+            const afterPatch = loadWithRequire(require, addonPath, attempts);
+            if (afterPatch) {
+                cached = afterPatch;
+                return cached;
+            }
+        }
+    }
+    throw buildFailure(attempts, pkgName);
+}
+//# sourceMappingURL=sherpa-onnx-node-loader.js.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-parakeet-realtime-session.d.ts

@@ -0,0 +1,28 @@
+import { EventEmitter } from "node:events";
+import type { StreamingTranscriptionSession } from "../../../speech-provider.js";
+import { SherpaOfflineRecognizerEngine } from "./sherpa-offline-recognizer.js";
+export declare class SherpaParakeetRealtimeTranscriptionSession extends EventEmitter implements StreamingTranscriptionSession {
+    private readonly engine;
+    private connected;
+    readonly requiredSampleRate: number;
+    private currentSegmentId;
+    private previousSegmentId;
+    private lastPartialText;
+    private pcm16;
+    private lastDecodeAt;
+    private decoding;
+    private pendingDecode;
+    private readonly minDecodeIntervalMs;
+    constructor(params: {
+        engine: SherpaOfflineRecognizerEngine;
+        minDecodeIntervalMs?: number;
+    });
+    connect(): Promise<void>;
+    appendPcm16(chunk: Buffer): void;
+    commit(): void;
+    clear(): void;
+    close(): void;
+    private maybeDecode;
+    private decodeNow;
+}
+//# sourceMappingURL=sherpa-parakeet-realtime-session.d.ts.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-parakeet-realtime-session.js

@@ -0,0 +1,137 @@
+import { EventEmitter } from "node:events";
+import { v4 as uuidv4 } from "uuid";
+import { pcm16lePeakAbs, pcm16leToFloat32 } from "../../../audio.js";
+export class SherpaParakeetRealtimeTranscriptionSession extends EventEmitter {
+    constructor(params) {
+        super();
+        this.connected = false;
+        this.currentSegmentId = null;
+        this.previousSegmentId = null;
+        this.lastPartialText = "";
+        this.pcm16 = Buffer.alloc(0);
+        this.lastDecodeAt = 0;
+        this.decoding = false;
+        this.pendingDecode = false;
+        this.engine = params.engine;
+        this.requiredSampleRate = this.engine.sampleRate;
+        this.minDecodeIntervalMs = params.minDecodeIntervalMs ?? 350;
+    }
+    async connect() {
+        if (this.connected) {
+            return;
+        }
+        this.currentSegmentId = uuidv4();
+        this.connected = true;
+    }
+    appendPcm16(chunk) {
+        if (!this.connected || !this.currentSegmentId) {
+            this.emit("error", new Error("Parakeet realtime session not connected"));
+            return;
+        }
+        try {
+            this.pcm16 = this.pcm16.length === 0 ? chunk : Buffer.concat([this.pcm16, chunk]);
+            void this.maybeDecode(false);
+        }
+        catch (err) {
+            this.emit("error", err instanceof Error ? err : new Error(String(err)));
+        }
+    }
+    commit() {
+        if (!this.connected || !this.currentSegmentId) {
+            this.emit("error", new Error("Parakeet realtime session not connected"));
+            return;
+        }
+        void (async () => {
+            try {
+                await this.maybeDecode(true);
+                const finalText = this.lastPartialText;
+                const segmentId = this.currentSegmentId;
+                const previousSegmentId = this.previousSegmentId;
+                this.emit("committed", { segmentId, previousSegmentId });
+                this.emit("transcript", { segmentId, transcript: finalText, isFinal: true });
+                this.previousSegmentId = segmentId;
+                this.currentSegmentId = uuidv4();
+                this.lastPartialText = "";
+                this.pcm16 = Buffer.alloc(0);
+            }
+            catch (err) {
+                this.emit("error", err instanceof Error ? err : new Error(String(err)));
+            }
+        })();
+    }
+    clear() {
+        if (!this.connected) {
+            return;
+        }
+        this.pcm16 = Buffer.alloc(0);
+        this.currentSegmentId = uuidv4();
+        this.lastPartialText = "";
+    }
+    close() {
+        this.connected = false;
+        this.currentSegmentId = null;
+        this.pcm16 = Buffer.alloc(0);
+    }
+    async maybeDecode(force) {
+        if (!this.connected || !this.currentSegmentId) {
+            return;
+        }
+        const now = Date.now();
+        if (!force && now - this.lastDecodeAt < this.minDecodeIntervalMs) {
+            return;
+        }
+        if (this.decoding) {
+            this.pendingDecode = true;
+            return;
+        }
+        this.decoding = true;
+        try {
+            const text = await this.decodeNow();
+            this.lastDecodeAt = Date.now();
+            if (text !== this.lastPartialText) {
+                this.lastPartialText = text;
+                this.emit("transcript", {
+                    segmentId: this.currentSegmentId,
+                    transcript: text,
+                    isFinal: false,
+                });
+            }
+        }
+        finally {
+            this.decoding = false;
+            if (this.pendingDecode) {
+                this.pendingDecode = false;
+                await this.maybeDecode(true);
+            }
+        }
+    }
+    async decodeNow() {
+        if (this.pcm16.length === 0) {
+            return "";
+        }
+        const peak = pcm16lePeakAbs(this.pcm16);
+        const peakFloat = peak / 32768.0;
+        const targetPeak = 0.6;
+        const maxGain = 50;
+        const gain = peakFloat > 0 && peakFloat < targetPeak ? Math.min(maxGain, targetPeak / peakFloat) : 1;
+        const stream = this.engine.createStream();
+        try {
+            const floatSamples = pcm16leToFloat32(this.pcm16, gain);
+            this.engine.acceptWaveform(stream, this.engine.sampleRate, floatSamples);
+            this.engine.recognizer.decode(stream);
+            const result = this.engine.recognizer.getResult(stream);
+            return String((typeof result === "object" && result && "text" in result ? result.text : undefined) ??
+                result ??
+                "").trim();
+        }
+        finally {
+            try {
+                stream.free?.();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+}
+//# sourceMappingURL=sherpa-parakeet-realtime-session.js.map

package/dist/server/server/speech/providers/local/sherpa/sherpa-parakeet-stt.d.ts

@@ -0,0 +1,21 @@
+import type pino from "pino";
+import type { SpeechToTextProvider, StreamingTranscriptionSession, TranscriptionResult } from "../../../speech-provider.js";
+import { SherpaOfflineRecognizerEngine } from "./sherpa-offline-recognizer.js";
+export interface SherpaParakeetSttConfig {
+    engine: SherpaOfflineRecognizerEngine;
+    silencePeakThreshold?: number;
+}
+export declare class SherpaOnnxParakeetSTT implements SpeechToTextProvider {
+    private readonly engine;
+    private readonly silencePeakThreshold;
+    private readonly logger;
+    readonly id: "local";
+    constructor(config: SherpaParakeetSttConfig, logger: pino.Logger);
+    createSession(params: {
+        logger: pino.Logger;
+        language?: string;
+        prompt?: string;
+    }): StreamingTranscriptionSession;
+    transcribeAudio(audioBuffer: Buffer, format: string): Promise<TranscriptionResult>;
+}
+//# sourceMappingURL=sherpa-parakeet-stt.d.ts.map