viet-asr 0.1.0-dev.3

package/README.md

@@ -0,0 +1,106 @@
+# vietasr — Node.js binding
+
+Offline Vietnamese Speech AI SDK for Node.js. Pure FFI over the same C/C++ core that powers every other vietasr binding.
+
+## Install
+
+```bash
+npm install vietasr
+```
+
+The package bundles a prebuilt `libvietasr.{so,dylib,dll}` + `libonnxruntime.{so,dylib,dll}` for your platform under `_native/`. No system dependencies.
+
+## Quickstart
+
+```js
+const vietasr = require("vietasr");
+
+const pipe = vietasr.Pipeline.preset("transcribe");
+const result = pipe.transcribe("audio.wav");
+console.log(result.text);
+pipe.close();
+```
+
+## Streaming
+
+```js
+const vietasr = require("vietasr");
+
+const pipe = vietasr.Pipeline.preset("transcribe");
+const session = pipe.stream(16000);
+
+for (const chunk of micChunks()) {
+    session.accept(chunk);          // Int16Array, Float32Array, or Buffer
+    process.stdout.write(`\r${session.partial().text}`);
+}
+console.log(`\n${session.final().text}`);
+session.close();
+pipe.close();
+```
+
+## Custom pipeline
+
+```js
+const vietasr = require("vietasr");
+
+const pipe = vietasr.Pipeline.new()
+    .add("vad")
+    .add("vietasr")
+    .add("punctuation")
+    .add("gender")
+    .add("emotion")
+    .build();
+
+const result = pipe.transcribe("call.wav");
+console.log(result.text);
+console.log(result.field("gender"));
+console.log(result.field("emotion"));
+pipe.close();
+```
+
+## CLI
+
+The package installs a `vietasr` binary:
+
+```bash
+vietasr audio.wav
+vietasr --preset analytics call.wav --pretty
+vietasr --module vad --module vietasr --module gender audio.wav
+```
+
+## API
+
+| Object | Method | Returns |
+|---|---|---|
+| `Pipeline` | `.preset(name)` | `Pipeline` |
+| `Pipeline` | `.new()` | `Pipeline` |
+| `Pipeline` | `.add(module, config?)` | `Pipeline` |
+| `Pipeline` | `.setBackend("auto" \| "onnx" \| "coreml")` | `Pipeline` |
+| `Pipeline` | `.setModelDir(path)` | `Pipeline` |
+| `Pipeline` | `.build()` | `Pipeline` |
+| `Pipeline` | `.transcribe(filePathOrInt16Array, sampleRate?)` | `Result` |
+| `Pipeline` | `.stream(sampleRate)` | `Session` |
+| `Pipeline` | `.close()` | void |
+| `Session` | `.accept(Int16Array \| Float32Array \| Buffer)` | bool (true = endpoint reached) |
+| `Session` | `.partial()` / `.result()` / `.final()` | `Result` |
+| `Session` | `.reset()` / `.close()` | void |
+| `Result` | `.text`, `.partial`, `.isFinal`, `.segments`, `.speakers` | typed |
+| `Result` | `.field(key)` | any (extra JSON keys) |
+| `Result` | `.toJson()` | string |
+| module-level | `vietasr.listModules()`, `listPresets()`, `version()`, `setLogLevel(level)` | — |
+
+## Thread safety
+
+- One `Pipeline` can serve many concurrent `Session`s — each Session has its own state.
+- For pure parallelism, prefer multiple Sessions on a shared Pipeline (engine loaded once).
+- See [docs/thread-safety.md](../../docs/thread-safety.md) for the full guide.
+
+## Audio format
+
+The SDK accepts any sample rate and either mono or stereo (auto-converted internally). For best accuracy, feed 16 kHz mono 16-bit PCM directly.
+
+## Models
+
+The vietasr model is **bundled inside the SDK** — no download, no network. `model.onnx`
+is committed to the repo as <50 MB chunks and baked into the native `libvietasr` that
+ships with this package.

package/bin/vietasr.js

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+const vietasr = require("..");
+
+function main() {
+    const argv = process.argv.slice(2);
+    let preset = "transcribe";
+    let pretty = false;
+    let wavPath = null;
+    const modules = [];
+
+    for (let i = 0; i < argv.length; ++i) {
+        const arg = argv[i];
+        if (arg === "--preset" && i + 1 < argv.length) {
+            preset = argv[++i];
+        } else if (arg === "--module" && i + 1 < argv.length) {
+            modules.push(argv[++i]);
+        } else if (arg === "--pretty") {
+            pretty = true;
+        } else if (arg === "-h" || arg === "--help") {
+            console.log(`Usage: vietasr [--preset NAME] [--module NAME]... [--pretty] <wav-file>`);
+            console.log(`\nAvailable presets: ${JSON.stringify(vietasr.listPresets())}`);
+            console.log(`Available modules: ${JSON.stringify(vietasr.listModules())}`);
+            process.exit(0);
+        } else if (!arg.startsWith("-")) {
+            wavPath = arg;
+        }
+    }
+
+    if (!wavPath) {
+        console.error("missing WAV path; pass --help for usage");
+        process.exit(1);
+    }
+
+    let pipe;
+    if (modules.length) {
+        pipe = vietasr.Pipeline.new();
+        for (const m of modules) pipe.add(m);
+        pipe.build();
+    } else {
+        pipe = vietasr.Pipeline.preset(preset);
+    }
+
+    try {
+        const result = pipe.transcribe(wavPath);
+        if (pretty) {
+            console.log(JSON.stringify(result.payload, null, 2));
+        } else {
+            console.log(result.toJson());
+        }
+    } finally {
+        pipe.close();
+    }
+}
+
+main();

package/index.js

@@ -0,0 +1,12 @@
+const { Pipeline, PipelineError, Session, Result } = require("./lib/pipeline");
+
+module.exports = {
+    Pipeline,
+    PipelineError,
+    Session,
+    Result,
+    version: () => Pipeline.version(),
+    listModules: () => Pipeline.listModules(),
+    listPresets: () => Pipeline.listPresets(),
+    setLogLevel: (level) => Pipeline.setLogLevel(level),
+};

package/lib/native-download.js

@@ -0,0 +1,77 @@
+"use strict";
+
+// Resolves the libvietasr native library. The npm package ships small; the
+// platform-specific native (~67 MB, ONNX model embedded) is downloaded from the
+// matching GitHub Release into a per-user cache on install / first use.
+
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const { execFileSync } = require("child_process");
+
+const REPO = "dangvansam/viet-asr";
+
+function platformKey() {
+    if (process.platform === "win32") return "win-x64";
+    if (process.platform === "darwin") return "darwin-universal2";
+    if (process.platform === "linux") {
+        if (process.arch === "x64") return "linux-x64";
+        if (process.arch === "arm64") return "linux-arm64";
+    }
+    throw new Error(
+        `viet-asr: unsupported platform ${process.platform}/${process.arch}`
+    );
+}
+
+function libFileName() {
+    if (process.platform === "win32") return "vietasr.dll";
+    if (process.platform === "darwin") return "libvietasr.dylib";
+    return "libvietasr.so";
+}
+
+function cacheDir(version) {
+    const base =
+        process.env.XDG_CACHE_HOME || path.join(os.homedir(), ".cache");
+    return path.join(base, "viet-asr", version);
+}
+
+// Downloads + extracts the native bundle into the per-user cache. Synchronous
+// (shells out to curl + tar, present on every supported OS) so it works both
+// from the postinstall hook and as a lazy fallback inside require().
+function ensureNative(version) {
+    const dir = cacheDir(version);
+    const lib = path.join(dir, libFileName());
+    if (fs.existsSync(lib)) return dir;
+
+    const asset = `viet-asr-native-${platformKey()}.tar.gz`;
+    fs.mkdirSync(dir, { recursive: true });
+    const tarball = path.join(dir, asset);
+    const urls = [
+        `https://github.com/${REPO}/releases/download/v${version}/${asset}`,
+        `https://github.com/${REPO}/releases/latest/download/${asset}`,
+    ];
+
+    let lastErr;
+    for (const url of urls) {
+        try {
+            execFileSync("curl", ["-fSL", "--retry", "3", "-o", tarball, url], {
+                stdio: "inherit",
+            });
+            execFileSync("tar", ["-xzf", tarball, "-C", dir], {
+                stdio: "inherit",
+            });
+            fs.rmSync(tarball, { force: true });
+            if (fs.existsSync(lib)) return dir;
+        } catch (err) {
+            lastErr = err;
+        }
+    }
+    fs.rmSync(tarball, { force: true });
+    throw new Error(
+        `viet-asr: could not download the native library for ${platformKey()}. ` +
+            `Set VIETASR_NATIVE_DIR to a directory containing ${libFileName()}. ` +
+            `Cause: ${lastErr && lastErr.message}`
+    );
+}
+
+module.exports = { platformKey, libFileName, cacheDir, ensureNative };

package/lib/native.js

@@ -0,0 +1,115 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+
+class NativeLibrary {
+    constructor() {
+        const koffi = require("koffi");
+        const nativeDir = NativeLibrary.findNativeDirectory();
+        NativeLibrary.preloadSiblings(koffi, nativeDir);
+        const libraryPath = NativeLibrary.libraryName(nativeDir);
+        this.koffi = koffi;
+        this.lib = koffi.load(libraryPath);
+        this.declare();
+    }
+
+    static findNativeDirectory() {
+        const override = process.env.VIETASR_NATIVE_DIR;
+        if (override && fs.existsSync(override)) {
+            return override;
+        }
+        const candidates = [
+            path.resolve(__dirname, "..", "_native"),
+            path.resolve(__dirname, "..", "..", "..", "build-core"),
+            path.resolve(__dirname, "..", "..", "..", "build-core", "_deps", "onnxruntime-src", "lib"),
+        ];
+        for (const dir of candidates) {
+            if (fs.existsSync(path.join(dir, NativeLibrary.libraryFilename()))) {
+                return dir;
+            }
+        }
+        // Not bundled and not a source checkout: download into the per-user
+        // cache (also covers `npm install --ignore-scripts`).
+        const { ensureNative } = require("./native-download");
+        const { version } = require("../package.json");
+        return ensureNative(version);
+    }
+
+    static libraryFilename() {
+        if (process.platform === "win32") return "vietasr.dll";
+        if (process.platform === "darwin") return "libvietasr.dylib";
+        return "libvietasr.so";
+    }
+
+    static libraryName(nativeDir) {
+        return path.join(nativeDir, NativeLibrary.libraryFilename());
+    }
+
+    static preloadSiblings(koffi, dir) {
+        if (!fs.existsSync(dir)) return;
+        const patterns = process.platform === "win32"
+            ? [/^onnxruntime.*\.dll$/]
+            : process.platform === "darwin"
+                ? [/^libonnxruntime.*\.dylib$/]
+                : [/^libonnxruntime\.so(\..*)?$/];
+        for (const entry of fs.readdirSync(dir)) {
+            for (const re of patterns) {
+                if (re.test(entry)) {
+                    try {
+                        koffi.load(path.join(dir, entry), { global: true });
+                    } catch (_) {
+                    }
+                }
+            }
+        }
+    }
+
+    declare() {
+        const koffi = this.koffi;
+        this.VietasrPipeline = koffi.opaque("VietasrPipeline");
+        this.VietasrSession = koffi.opaque("VietasrSession");
+        const Pipeline = koffi.pointer(this.VietasrPipeline);
+        const Session = koffi.pointer(this.VietasrSession);
+
+        this.fn = {
+            vietasr_pipeline_preset: this.lib.func("vietasr_pipeline_preset", Pipeline, ["str"]),
+            vietasr_pipeline_new: this.lib.func("vietasr_pipeline_new", Pipeline, []),
+            vietasr_pipeline_add_module: this.lib.func("vietasr_pipeline_add_module", "int",
+                [Pipeline, "str", "str"]),
+            vietasr_pipeline_set_backend: this.lib.func("vietasr_pipeline_set_backend", "int",
+                [Pipeline, "int"]),
+            vietasr_pipeline_set_model_dir: this.lib.func("vietasr_pipeline_set_model_dir", "int",
+                [Pipeline, "str"]),
+            vietasr_pipeline_build: this.lib.func("vietasr_pipeline_build", "int", [Pipeline]),
+            vietasr_pipeline_free: this.lib.func("vietasr_pipeline_free", "void", [Pipeline]),
+
+            vietasr_list_modules: this.lib.func("vietasr_list_modules", "str", []),
+            vietasr_list_presets: this.lib.func("vietasr_list_presets", "str", []),
+
+            vietasr_session_new: this.lib.func("vietasr_session_new", Session, [Pipeline, "float"]),
+            vietasr_session_free: this.lib.func("vietasr_session_free", "void", [Session]),
+            vietasr_session_reset: this.lib.func("vietasr_session_reset", "void", [Session]),
+
+            vietasr_accept_waveform_s16: this.lib.func("vietasr_accept_waveform_s16", "int",
+                [Session, koffi.pointer("int16_t"), "int"]),
+            vietasr_accept_waveform_f32: this.lib.func("vietasr_accept_waveform_f32", "int",
+                [Session, koffi.pointer("float"), "int"]),
+
+            vietasr_partial_result: this.lib.func("vietasr_partial_result", "str", [Session]),
+            vietasr_result: this.lib.func("vietasr_result", "str", [Session]),
+            vietasr_final_result: this.lib.func("vietasr_final_result", "str", [Session]),
+
+            vietasr_transcribe_file: this.lib.func("vietasr_transcribe_file", "str",
+                [Pipeline, "str"]),
+            vietasr_transcribe_buffer: this.lib.func("vietasr_transcribe_buffer", "str",
+                [Pipeline, koffi.pointer("int16_t"), "int", "float"]),
+
+            vietasr_default_cache_dir: this.lib.func("vietasr_default_cache_dir", "str", []),
+            vietasr_set_log_level: this.lib.func("vietasr_set_log_level", "void", ["int"]),
+            vietasr_version: this.lib.func("vietasr_version", "str", []),
+            vietasr_last_error: this.lib.func("vietasr_last_error", "str", []),
+        };
+    }
+}
+
+module.exports = new NativeLibrary();

package/lib/pipeline.js

@@ -0,0 +1,122 @@
+const native = require("./native");
+const { Result } = require("./result");
+const { Session } = require("./session");
+
+const BACKEND = { auto: 0, onnx: 1, coreml: 2 };
+
+class PipelineError extends Error {}
+
+class Pipeline {
+    constructor(handle) {
+        this.handle = handle;
+    }
+
+    static preset(name) {
+        const handle = native.fn.vietasr_pipeline_preset(name);
+        if (!handle) {
+            throw new PipelineError(Pipeline.lastError() || `unknown preset: ${name}`);
+        }
+        return new Pipeline(handle);
+    }
+
+    static new() {
+        const handle = native.fn.vietasr_pipeline_new();
+        return new Pipeline(handle);
+    }
+
+    add(moduleName, config) {
+        const json = JSON.stringify(config || {});
+        const status = native.fn.vietasr_pipeline_add_module(this.handle, moduleName, json);
+        if (status !== 0) {
+            throw new PipelineError(Pipeline.lastError() || `add(${moduleName}) failed: ${status}`);
+        }
+        return this;
+    }
+
+    setBackend(backend) {
+        if (!(backend in BACKEND)) {
+            throw new PipelineError(`unknown backend: ${backend}`);
+        }
+        const status = native.fn.vietasr_pipeline_set_backend(this.handle, BACKEND[backend]);
+        if (status !== 0) {
+            throw new PipelineError(Pipeline.lastError() || `setBackend(${backend}) failed`);
+        }
+        return this;
+    }
+
+    setModelDir(dir) {
+        const status = native.fn.vietasr_pipeline_set_model_dir(this.handle, dir);
+        if (status !== 0) {
+            throw new PipelineError(Pipeline.lastError() || "setModelDir failed");
+        }
+        return this;
+    }
+
+    build() {
+        const status = native.fn.vietasr_pipeline_build(this.handle);
+        if (status !== 0) {
+            throw new PipelineError(Pipeline.lastError() || "build failed");
+        }
+        return this;
+    }
+
+    transcribe(source, sampleRate) {
+        if (typeof source === "string") {
+            const raw = native.fn.vietasr_transcribe_file(this.handle, source);
+            if (!raw) {
+                throw new PipelineError(Pipeline.lastError() || "transcribe_file failed");
+            }
+            return Result.fromJson(raw);
+        }
+        if (source instanceof Int16Array) {
+            const sr = sampleRate || 16000;
+            const raw = native.fn.vietasr_transcribe_buffer(
+                this.handle, source, source.length, sr);
+            if (!raw) {
+                throw new PipelineError(Pipeline.lastError() || "transcribe_buffer failed");
+            }
+            return Result.fromJson(raw);
+        }
+        throw new TypeError("transcribe() expects a file path or Int16Array");
+    }
+
+    stream(sampleRate) {
+        const sr = sampleRate || 16000;
+        const handle = native.fn.vietasr_session_new(this.handle, sr);
+        if (!handle) {
+            throw new PipelineError(Pipeline.lastError() || "session creation failed");
+        }
+        return new Session(handle);
+    }
+
+    static listModules() {
+        return JSON.parse(native.fn.vietasr_list_modules() || "[]");
+    }
+
+    static listPresets() {
+        return JSON.parse(native.fn.vietasr_list_presets() || "[]");
+    }
+
+    static lastError() {
+        return native.fn.vietasr_last_error() || "";
+    }
+
+    static version() {
+        return native.fn.vietasr_version() || "";
+    }
+
+    static setLogLevel(level) {
+        const levels = { trace: 0, debug: 1, info: 2, warn: 3, error: 4, off: 5 };
+        const value = typeof level === "string" ? levels[level] : level;
+        native.fn.vietasr_set_log_level(value);
+    }
+
+    close() {
+        if (this.handle) {
+            native.fn.vietasr_pipeline_free(this.handle);
+            this.handle = null;
+        }
+    }
+}
+
+module.exports = { Pipeline, PipelineError, Session, Result };

package/lib/result.js

@@ -0,0 +1,44 @@
+class Result {
+    constructor(payload) {
+        this.payload = payload;
+    }
+
+    static fromJson(raw) {
+        if (!raw) return new Result({});
+        try {
+            return new Result(JSON.parse(raw));
+        } catch (_) {
+            return new Result({});
+        }
+    }
+
+    get text() {
+        return this.payload.text || "";
+    }
+
+    get partial() {
+        return this.payload.partial || "";
+    }
+
+    get isFinal() {
+        return Boolean(this.payload.is_final);
+    }
+
+    get segments() {
+        return this.payload.segments || [];
+    }
+
+    get speakers() {
+        return this.payload.speakers || [];
+    }
+
+    field(key) {
+        return this.payload[key];
+    }
+
+    toJson() {
+        return JSON.stringify(this.payload);
+    }
+}
+
+module.exports = { Result };

package/lib/session.js

@@ -0,0 +1,55 @@
+const native = require("./native");
+const { Result } = require("./result");
+
+class Session {
+    constructor(handle) {
+        this.handle = handle;
+    }
+
+    reset() {
+        native.fn.vietasr_session_reset(this.handle);
+    }
+
+    accept(pcm) {
+        if (!this.handle) {
+            throw new Error("Session is closed");
+        }
+        if (pcm instanceof Int16Array) {
+            return native.fn.vietasr_accept_waveform_s16(
+                this.handle, pcm, pcm.length) === 1;
+        }
+        if (pcm instanceof Float32Array) {
+            return native.fn.vietasr_accept_waveform_f32(
+                this.handle, pcm, pcm.length) === 1;
+        }
+        if (Buffer.isBuffer(pcm)) {
+            const view = new Int16Array(pcm.buffer, pcm.byteOffset,
+                pcm.byteLength / 2);
+            return native.fn.vietasr_accept_waveform_s16(
+                this.handle, view, view.length) === 1;
+        }
+        throw new TypeError(
+            "accept() expects Int16Array, Float32Array, or Buffer (16-bit PCM)");
+    }
+
+    partial() {
+        return Result.fromJson(native.fn.vietasr_partial_result(this.handle));
+    }
+
+    result() {
+        return Result.fromJson(native.fn.vietasr_result(this.handle));
+    }
+
+    final() {
+        return Result.fromJson(native.fn.vietasr_final_result(this.handle));
+    }
+
+    close() {
+        if (this.handle) {
+            native.fn.vietasr_session_free(this.handle);
+            this.handle = null;
+        }
+    }
+}
+
+module.exports = { Session };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "viet-asr",
+  "version": "0.1.0-dev.3",
+  "description": "Universal Vietnamese Speech AI SDK",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js"
+  },
+  "bin": {
+    "vietasr": "./bin/vietasr.js"
+  },
+  "files": [
+    "index.js",
+    "lib/",
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "keywords": [
+    "asr",
+    "speech-recognition",
+    "vietnamese",
+    "vietasr",
+    "offline",
+    "onnx"
+  ],
+  "license": "Apache-2.0",
+  "homepage": "https://github.com/dangvansam/viet-asr",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dangvansam/viet-asr.git",
+    "directory": "bindings/nodejs"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "dependencies": {
+    "koffi": "^2.10.0"
+  },
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "node test/smoke.js",
+    "example": "node examples/quickstart.js"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,15 @@
+"use strict";
+
+// postinstall hook — pre-fetch the native library so the first require() is
+// instant. Failure here is non-fatal: lib/native.js retries lazily at runtime
+// (covers offline installs and `npm install --ignore-scripts`).
+
+const { ensureNative } = require("../lib/native-download");
+const { version } = require("../package.json");
+
+try {
+    ensureNative(version);
+    console.log(`viet-asr: native library ready (v${version})`);
+} catch (err) {
+    console.warn(`viet-asr: native prefetch skipped — ${err.message}`);
+}