@qvac/sdk 0.9.2 → 0.10.1

package/dist/examples/transcription/parakeet-microphone-record.js

@@ -9,29 +9,12 @@
  * Requirements: FFmpeg installed, microphone access.
  */
 import { loadModel, unloadModel, transcribe, PARAKEET_TDT_ENCODER_FP32, PARAKEET_TDT_DECODER_FP32, PARAKEET_TDT_VOCAB, PARAKEET_TDT_PREPROCESSOR_FP32, } from "@qvac/sdk";
-import { spawn, spawnSync } from "child_process";
-import { platform } from "os";
+import { spawnSync } from "child_process";
+import { startMicrophone } from "../audio/mic-input";
 const SAMPLE_RATE = 16000;
 const BYTES_PER_SAMPLE = 2; // s16le
 const CHUNK_DURATION_S = 3;
 const CHUNK_SIZE = SAMPLE_RATE * BYTES_PER_SAMPLE * CHUNK_DURATION_S;
-function getAudioInputArgs() {
-    switch (platform()) {
-        case "darwin":
-            return ["-f", "avfoundation", "-i", ":0"];
-        case "win32":
-            return [
-                "-f",
-                "dshow",
-                "-i",
-                "audio=@device_cm_{33D9A762-90C8-11D0-BD43-00A0C911CE86}\\wave_{58C07110-A4FD-4FF8-BA10-5A3C14389F71}",
-            ];
-        case "linux":
-            return ["-f", "pulse", "-i", "default"];
-        default:
-            throw new Error(`Unsupported platform: ${platform()}`);
-    }
-}
 // ── Main ──
 try {
     const r = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" });
@@ -55,20 +38,10 @@ const modelId = await loadModel({
     onProgress: (p) => console.log(`Download: ${p.percentage.toFixed(1)}%`),
 });
 console.log("Model loaded.\n");
-const ffmpeg = spawn("ffmpeg", [
-    ...getAudioInputArgs(),
-    "-ar",
-    String(SAMPLE_RATE),
-    "-ac",
-    "1",
-    "-sample_fmt",
-    "s16",
-    "-f",
-    "s16le",
-    "pipe:1",
-], { stdio: ["ignore", "pipe", "ignore"] });
-if (!ffmpeg.stdout)
-    throw new Error("Failed to open microphone");
+const ffmpeg = startMicrophone({
+    sampleRate: SAMPLE_RATE,
+    format: "s16le",
+});
 let buffer = Buffer.alloc(0);
 let processing = false;
 console.log("Listening... speak and pause to see transcriptions.\n");

package/dist/examples/transcription/whispercpp-filesystem-streaming.js

@@ -51,7 +51,7 @@ try {
     });
     console.log(`Model loaded: ${modelId}\n`);
     console.log("Opening live session...");
-    const session = await transcribeStream({ modelId });
+    const session = await transcribeStream({ modelId, metadata: true });
     console.log("Session open. Streaming audio...\n");
     const ffmpeg = spawn("ffmpeg", [
         "-i", SAMPLE_FILE,
@@ -76,14 +76,16 @@ try {
         session.end();
     });
     const segments = [];
-    for await (const text of session) {
-        segments.push(text.trim());
-        console.log(`  [${segments.length}] ${text.trim()}`);
+    for await (const segment of session) {
+        segments.push(segment);
+        const start = (segment.startMs / 1000).toFixed(2);
+        const end = (segment.endMs / 1000).toFixed(2);
+        console.log(`  [${segments.length}] [${start}s → ${end}s] (id=${segment.id}, append=${segment.append}) ${segment.text.trim()}`);
     }
     console.log("\n=== Results ===");
     console.log(`Segments: ${segments.length}`);
     if (segments.length > 0) {
-        console.log(`Transcript: ${segments.join(" ")}`);
+        console.log(`Transcript: ${segments.map((s) => s.text.trim()).join(" ")}`);
     }
     else {
         console.log("WARNING: No transcription segments received!");

package/dist/examples/transcription/whispercpp-filesystem.js

@@ -53,11 +53,20 @@ try {
         },
     });
     console.log(`✅ Whisper model loaded with ID: ${modelId}`);
-    // Perform transcription
+    // Perform transcription with per-segment metadata
     console.log("🎧 Transcribing audio...");
-    const text = await transcribe({ modelId, audioChunk: audioFilePath });
+    const segments = await transcribe({
+        modelId,
+        audioChunk: audioFilePath,
+        metadata: true,
+    });
     console.log("📝 Transcription result:");
-    console.log(text);
+    for (const segment of segments) {
+        const start = (segment.startMs / 1000).toFixed(2);
+        const end = (segment.endMs / 1000).toFixed(2);
+        console.log(`  [${start}s → ${end}s] (id=${segment.id}, append=${segment.append}) ${segment.text}`);
+    }
+    console.log(`\nFull transcript: ${segments.map((s) => s.text).join("").trim()}`);
     // Unload the model when done
     console.log("🧹 Unloading Whisper model...");
     await unloadModel({ modelId });

package/dist/examples/transcription/whispercpp-microphone-record.js

@@ -9,26 +9,9 @@
  * Requirements: FFmpeg installed, microphone access.
  */
 import { loadModel, unloadModel, transcribeStream, WHISPER_TINY, VAD_SILERO_5_1_2, } from "@qvac/sdk";
-import { spawn, spawnSync } from "child_process";
-import { platform } from "os";
+import { spawnSync } from "child_process";
+import { startMicrophone } from "../audio/mic-input";
 const SAMPLE_RATE = 16000;
-function getAudioInputArgs() {
-    switch (platform()) {
-        case "darwin":
-            return ["-f", "avfoundation", "-i", ":0"];
-        case "win32":
-            return [
-                "-f",
-                "dshow",
-                "-i",
-                "audio=@device_cm_{33D9A762-90C8-11D0-BD43-00A0C911CE86}\\wave_{58C07110-A4FD-4FF8-BA10-5A3C14389F71}",
-            ];
-        case "linux":
-            return ["-f", "pulse", "-i", "default"];
-        default:
-            throw new Error(`Unsupported platform: ${platform()}`);
-    }
-}
 // ── Main ──
 try {
     const r = spawnSync("ffmpeg", ["-version"], { stdio: "ignore" });
@@ -63,16 +46,10 @@ const modelId = await loadModel({
     },
 });
 console.log("Model loaded.\n");
-const ffmpeg = spawn("ffmpeg", [
-    ...getAudioInputArgs(),
-    "-ar", String(SAMPLE_RATE),
-    "-ac", "1",
-    "-sample_fmt", "flt",
-    "-f", "f32le",
-    "pipe:1",
-], { stdio: ["ignore", "pipe", "ignore"] });
-if (!ffmpeg.stdout)
-    throw new Error("Failed to open microphone");
+const ffmpeg = startMicrophone({
+    sampleRate: SAMPLE_RATE,
+    format: "f32le",
+});
 const session = await transcribeStream({ modelId });
 ffmpeg.stdout.on("data", (chunk) => session.write(chunk));
 console.log("Listening... speak and pause to see transcriptions.\n");

package/dist/examples/translation/translation-stream.js

@@ -1,12 +1,12 @@
-import { loadModel, translate, unloadModel, MARIAN_OPUS_EN_IT_Q4_0, } from "@qvac/sdk";
+import { loadModel, translate, unloadModel, BERGAMOT_EN_ES, } from "@qvac/sdk";
 try {
     const modelId = await loadModel({
-        modelSrc: MARIAN_OPUS_EN_IT_Q4_0,
+        modelSrc: BERGAMOT_EN_ES,
         modelType: "nmt",
         modelConfig: {
-            engine: "Opus",
+            engine: "Bergamot",
             from: "en",
-            to: "it",
+            to: "es",
         },
     });
     console.log(`✅ Model loaded: ${modelId}`);
@@ -18,7 +18,7 @@ try {
         modelType: "nmt",
         stream: true,
     });
-    process.stdout.write("Translated text EN -> IT: ");
+    process.stdout.write("Translated text EN -> ES: ");
     for await (const token of streamResult.tokenStream) {
         process.stdout.write(token);
     }

package/dist/examples/tts/llm-to-tts-streaming.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Stream an LLM and forward token deltas through the duplex TTS path (`textToSpeechStream` →
+ * `runStreaming` with `accumulateSentences: true`). Text is filtered before TTS / console: any
+ * `<...>` span (including across tokens) is removed, and `*` characters are stripped.
+ *
+ * Each synthesized phrase is played as soon as PCM arrives (`playPcmInt16Chunk`). A combined WAV
+ * is written at the end for inspection.
+ *
+ * Prerequisites: Bun, QVAC worker, registry access, macOS `afplay` / Linux `aplay` (or Windows
+ * PowerShell player) for chunk playback.
+ *
+ * Usage:
+ *   bun run examples/tts/llm-to-tts-streaming.ts
+ */
+export {};
+//# sourceMappingURL=llm-to-tts-streaming.d.ts.map

package/dist/examples/tts/llm-to-tts-streaming.js

@@ -0,0 +1,143 @@
+/**
+ * Stream an LLM and forward token deltas through the duplex TTS path (`textToSpeechStream` →
+ * `runStreaming` with `accumulateSentences: true`). Text is filtered before TTS / console: any
+ * `<...>` span (including across tokens) is removed, and `*` characters are stripped.
+ *
+ * Each synthesized phrase is played as soon as PCM arrives (`playPcmInt16Chunk`). A combined WAV
+ * is written at the end for inspection.
+ *
+ * Prerequisites: Bun, QVAC worker, registry access, macOS `afplay` / Linux `aplay` (or Windows
+ * PowerShell player) for chunk playback.
+ *
+ * Usage:
+ *   bun run examples/tts/llm-to-tts-streaming.ts
+ */
+import { completion, loadModel, textToSpeechStream, unloadModel, LLAMA_3_2_1B_INST_Q4_0, TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_VOCODER_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_UNICODE_INDEXER_SUPERTONE_FP32, TTS_SUPERTONIC2_OFFICIAL_TTS_CONFIG_SUPERTONE, TTS_SUPERTONIC2_OFFICIAL_VOICE_STYLE_SUPERTONE, } from "@qvac/sdk";
+import { createWav, playPcmInt16Chunk } from "./utils.js";
+const SUPERTONIC_SAMPLE_RATE = 44100;
+/**
+ * Drop angle-bracket spans (e.g. `<think>…</think>`, `<|foo|>`) even when split across tokens,
+ * and strip `*` (markdown emphasis) from text passed to TTS and the console.
+ */
+function createAngleBracketAndStarFilter() {
+    let inAngle = false;
+    return function filterChunk(chunk) {
+        let out = "";
+        for (let i = 0; i < chunk.length; i++) {
+            const c = chunk[i];
+            if (inAngle) {
+                if (c === ">") {
+                    inAngle = false;
+                }
+                continue;
+            }
+            if (c === "<") {
+                inAngle = true;
+                continue;
+            }
+            if (c === "*") {
+                continue;
+            }
+            out += c;
+        }
+        return out;
+    };
+}
+/**
+ * Append PCM without `push(...huge)` — a spread of hundreds of thousands of
+ * arguments blows the V8 / Bare argument-count limit. Batching with
+ * `Array.prototype.push.apply` is both faster than `push(...slice)` and
+ * avoids allocating an intermediate rest array on the stack per call.
+ */
+function appendPcmSamples(target, chunk) {
+    const batch = 8192;
+    for (let i = 0; i < chunk.length; i += batch) {
+        const end = Math.min(i + batch, chunk.length);
+        Array.prototype.push.apply(target, chunk.slice(i, end));
+    }
+}
+try {
+    console.log(`Loading LLM from registry: ${LLAMA_3_2_1B_INST_Q4_0.name}`);
+    const llmModelId = await loadModel({
+        modelSrc: LLAMA_3_2_1B_INST_Q4_0.src,
+        modelType: "llm",
+        modelConfig: {
+            ctx_size: 2048,
+        },
+        onProgress: (progress) => console.log(`LLM load: ${progress.percentage.toFixed(1)}%`),
+    });
+    console.log(`LLM ready: ${llmModelId}`);
+    console.log("Loading Supertonic TTS (registry)…");
+    const ttsModelId = await loadModel({
+        modelSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
+        modelType: "tts",
+        modelConfig: {
+            ttsEngine: "supertonic",
+            language: "en",
+            ttsSpeed: 1.05,
+            ttsNumInferenceSteps: 10,
+            ttsSupertonicMultilingual: true,
+            ttsTextEncoderSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
+            ttsDurationPredictorSrc: TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32.src,
+            ttsVectorEstimatorSrc: TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32.src,
+            ttsVocoderSrc: TTS_SUPERTONIC2_OFFICIAL_VOCODER_SUPERTONE_FP32.src,
+            ttsUnicodeIndexerSrc: TTS_SUPERTONIC2_OFFICIAL_UNICODE_INDEXER_SUPERTONE_FP32.src,
+            ttsTtsConfigSrc: TTS_SUPERTONIC2_OFFICIAL_TTS_CONFIG_SUPERTONE.src,
+            ttsVoiceStyleSrc: TTS_SUPERTONIC2_OFFICIAL_VOICE_STYLE_SUPERTONE.src,
+        },
+        onProgress: (progress) => console.log(`TTS load: ${progress.percentage.toFixed(1)}%`),
+    });
+    console.log(`TTS ready: ${ttsModelId}`);
+    const prompt = "What is a constellation?";
+    console.log(`\nUser: ${prompt}\nAssistant (streaming):`);
+    const result = completion({
+        modelId: llmModelId,
+        history: [{ role: "user", content: prompt }],
+        stream: true,
+    });
+    const combinedPcm = [];
+    const ttsSession = await textToSpeechStream({
+        modelId: ttsModelId,
+        inputType: "text",
+        accumulateSentences: true,
+    });
+    let phraseIndex = 0;
+    const filterChunk = createAngleBracketAndStarFilter();
+    const drainPcm = (async () => {
+        for await (const m of ttsSession) {
+            if (m.buffer.length > 0) {
+                appendPcmSamples(combinedPcm, m.buffer);
+                phraseIndex += 1;
+                const preview = typeof m.sentenceChunk === "string"
+                    ? m.sentenceChunk.replace(/\s+/g, " ").trim().slice(0, 72)
+                    : "";
+                console.log(`\n[TTS phrase ${phraseIndex}] ${m.buffer.length} samples${preview ? ` — "${preview}${preview.length >= 72 ? "..." : ""}"` : ""}`);
+                await playPcmInt16Chunk(m.buffer, SUPERTONIC_SAMPLE_RATE);
+            }
+        }
+    })();
+    for await (const token of result.tokenStream) {
+        const cleaned = filterChunk(token);
+        if (cleaned.length > 0) {
+            process.stdout.write(cleaned);
+            ttsSession.write(cleaned);
+        }
+    }
+    ttsSession.end();
+    await drainPcm;
+    const stats = await result.stats;
+    if (stats) {
+        console.log("\nLLM stats:", stats);
+    }
+    const outWav = "llm-to-tts-streaming-output.wav";
+    console.log(`\nWriting ${combinedPcm.length} samples to ${outWav} (full utterance; phrases were already played above).`);
+    createWav(combinedPcm, SUPERTONIC_SAMPLE_RATE, outWav);
+    await unloadModel({ modelId: llmModelId, clearStorage: false });
+    await unloadModel({ modelId: ttsModelId, clearStorage: false });
+    console.log("Models unloaded.");
+    process.exit(0);
+}
+catch (error) {
+    console.error("❌ Error:", error);
+    process.exit(1);
+}

package/dist/examples/tts/supertonic-multilingual.js

@@ -10,9 +10,9 @@ try {
         modelConfig: {
             ttsEngine: "supertonic",
             language: "es",
-            speed: 1.05,
-            numInferenceSteps: 5,
-            supertonicMultilingual: true, //false for English quality.
+            ttsSpeed: 1.05,
+            ttsNumInferenceSteps: 5,
+            ttsSupertonicMultilingual: true, //false for English quality.
             ttsTextEncoderSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
             ttsDurationPredictorSrc: TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32.src,
             ttsVectorEstimatorSrc: TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32.src,

package/dist/examples/tts/supertonic.js

@@ -10,9 +10,9 @@ try {
         modelConfig: {
             ttsEngine: "supertonic",
             language: "en",
-            speed: 1.05,
-            numInferenceSteps: 5,
-            supertonicMultilingual: false, //false for English quality.
+            ttsSpeed: 1.05,
+            ttsNumInferenceSteps: 5,
+            ttsSupertonicMultilingual: false, //false for English quality.
             ttsTextEncoderSrc: TTS_SUPERTONIC2_OFFICIAL_TEXT_ENCODER_SUPERTONE_FP32.src,
             ttsDurationPredictorSrc: TTS_SUPERTONIC2_OFFICIAL_DURATION_PREDICTOR_SUPERTONE_FP32.src,
             ttsVectorEstimatorSrc: TTS_SUPERTONIC2_OFFICIAL_VECTOR_ESTIMATOR_SUPERTONE_FP32.src,

package/dist/examples/tts/utils.d.ts

@@ -11,7 +11,17 @@ export declare function int16ArrayToBuffer(samples: number[]): Buffer;
  */
 export declare function createWav(audioBuffer: number[], sampleRate: number, filename: string): void;
 /**
- * Play audio using system audio players
+ * Play a WAV buffer by streaming it into ffplay over stdin.
+ *
+ * ffplay ships with ffmpeg and is cross-platform (macOS/Linux/Windows), so
+ * we avoid the old "write to /tmp then shell out to afplay/aplay/powershell"
+ * dance — no temp files, no platform switch, no hardcoded /tmp path (which
+ * doesn't exist on Windows). Requires ffplay on PATH.
  */
+/**
+ * Play one mono s16le PCM chunk (as a minimal WAV) and wait for the player to finish.
+ * Chunks are played sequentially when awaited in order — suitable for streaming TTS output.
+ */
+export declare function playPcmInt16Chunk(samples: number[], sampleRate: number): Promise<void>;
 export declare function playAudio(audioBuffer: Buffer): void;
 //# sourceMappingURL=utils.d.ts.map

package/dist/examples/tts/utils.js

@@ -1,6 +1,7 @@
 import { writeFileSync, unlinkSync } from "fs";
-import { spawnSync } from "child_process";
-import { platform } from "os";
+import { spawn, spawnSync } from "child_process";
+import { platform, tmpdir } from "os";
+import { join } from "path";
 /**
  * Create WAV header for 16-bit PCM audio
  */
@@ -46,13 +47,30 @@ export function createWav(audioBuffer, sampleRate, filename) {
     console.log(`WAV file saved as: ${filename}`);
 }
 /**
- * Play audio using system audio players
+ * Play a WAV buffer by streaming it into ffplay over stdin.
+ *
+ * ffplay ships with ffmpeg and is cross-platform (macOS/Linux/Windows), so
+ * we avoid the old "write to /tmp then shell out to afplay/aplay/powershell"
+ * dance — no temp files, no platform switch, no hardcoded /tmp path (which
+ * doesn't exist on Windows). Requires ffplay on PATH.
  */
-export function playAudio(audioBuffer) {
+/**
+ * Play one mono s16le PCM chunk (as a minimal WAV) and wait for the player to finish.
+ * Chunks are played sequentially when awaited in order — suitable for streaming TTS output.
+ */
+export function playPcmInt16Chunk(samples, sampleRate) {
+    if (samples.length === 0) {
+        return Promise.resolve();
+    }
+    const audioData = int16ArrayToBuffer(samples);
+    const wavHeader = createWavHeader(audioData.length, sampleRate);
+    const wavFile = Buffer.concat([wavHeader, audioData]);
+    // `os.tmpdir()` resolves to the OS-specific temp directory (e.g. `%TEMP%`
+    // on Windows), so the Windows branch below no longer tries to read a
+    // POSIX-only `/tmp/...` path.
+    const tempFile = join(tmpdir(), `qvac-tts-chunk-${Date.now()}-${Math.random().toString(16).slice(2)}.wav`);
+    writeFileSync(tempFile, wavFile);
     const currentPlatform = platform();
-    const tempFile = `/tmp/audio-${Date.now()}.wav`;
-    // Write audio buffer to temporary file
-    writeFileSync(tempFile, audioBuffer);
     let audioPlayer;
     let args;
     switch (currentPlatform) {
@@ -75,19 +93,54 @@ export function playAudio(audioBuffer) {
             audioPlayer = "aplay";
             args = [tempFile];
     }
-    const result = spawnSync(audioPlayer, args, {
-        stdio: ["inherit", "inherit", "inherit"],
+    return new Promise(function (resolve, reject) {
+        const proc = spawn(audioPlayer, args, { stdio: "ignore" });
+        proc.on("error", function (err) {
+            try {
+                unlinkSync(tempFile);
+            }
+            catch {
+                // ignore
+            }
+            reject(err);
+        });
+        proc.on("close", function (code) {
+            try {
+                unlinkSync(tempFile);
+            }
+            catch {
+                // ignore
+            }
+            if (code === 0) {
+                resolve();
+            }
+            else {
+                reject(new Error(`Audio player exited with code ${code}`));
+            }
+        });
+    });
+}
+export function playAudio(audioBuffer) {
+    const result = spawnSync("ffplay", [
+        "-hide_banner",
+        "-loglevel",
+        "error",
+        "-autoexit",
+        "-nodisp",
+        "-i",
+        "pipe:0",
+    ], {
+        input: audioBuffer,
+        stdio: ["pipe", "inherit", "inherit"],
     });
-    try {
-        unlinkSync(tempFile);
-    }
-    catch {
-        // Ignore cleanup errors
-    }
     if (result.error) {
-        throw new Error(`Audio player failed: ${result.error.message}`);
+        const code = result.error.code;
+        if (code === "ENOENT") {
+            throw new Error("ffplay not found on PATH. Install ffmpeg (ffplay ships with it) and retry.");
+        }
+        throw new Error(`ffplay failed: ${result.error.message}`);
     }
     if (result.status !== 0) {
-        throw new Error(`Audio player exited with code ${result.status}`);
+        throw new Error(`ffplay exited with code ${result.status}`);
     }
 }

package/dist/examples/voice-assistant/voice-assistant.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=voice-assistant.d.ts.map