@qvac/sdk 0.19.1 → 0.20.1

package/dist/examples/asr/parakeet-nemotron-filesystem.js

@@ -0,0 +1,170 @@
+/**
+ * Parakeet Nemotron transcription from an audio file.
+ *
+ * Usage:
+ *   bun run examples/asr/parakeet-nemotron-filesystem.ts \
+ *     <audio-file> [locale] [nemotron-gguf] [--streaming]
+ *   bun run examples/asr/parakeet-nemotron-filesystem.ts \
+ *     <audio-file> [nemotron-gguf] [--streaming]
+ *
+ * Uses `PARAKEET_NEMOTRON_0_6B_Q4_0` when the model is omitted and `auto` when
+ * the locale is omitted. Pass `--streaming` to stream decoded 16 kHz mono PCM;
+ * otherwise, the input is transcribed in batch mode.
+ */
+import { loadModel, PARAKEET_NEMOTRON_0_6B_Q4_0, transcribe, transcribeStream, unloadModel } from '@qvac/sdk';
+import { spawn } from 'child_process';
+const SAMPLE_RATE = 16000;
+const BYTES_PER_S16_SAMPLE = 2;
+const INPUT_CHUNK_MS = 160;
+const MILLISECONDS_PER_SECOND = 1000;
+const BYTES_PER_MEGABYTE = 1e6;
+const DEFAULT_LOCALE = 'auto';
+const FFMPEG_PROTOCOLS = 'file,pipe';
+const STREAMING_FLAG = '--streaming';
+const EARLY_OUTPUT_END_MESSAGE = 'The transcription stream ended before the decoder input completed';
+const USAGE = 'Usage: bun run examples/asr/parakeet-nemotron-filesystem.ts ' +
+    '<audio-file> [locale] [nemotron-gguf] [--streaming]';
+function parseArguments(args) {
+    const streaming = args.includes(STREAMING_FLAG);
+    const positional = args.filter((argument) => argument !== STREAMING_FLAG);
+    const [audioFilePath, second, third] = positional;
+    const secondIsModel = second !== undefined &&
+        (second.endsWith('.gguf') || second.includes('/') || second.includes('\\'));
+    const locale = secondIsModel ? DEFAULT_LOCALE : (second ?? DEFAULT_LOCALE);
+    const modelSource = secondIsModel ? second : third;
+    return { audioFilePath, locale, modelSource, streaming };
+}
+function requireAudioFilePath(audioFilePath) {
+    if (audioFilePath)
+        return audioFilePath;
+    throw new Error(USAGE);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function calculateChunkBytes() {
+    const samplesPerChunk = Math.floor((INPUT_CHUNK_MS / MILLISECONDS_PER_SECOND) * SAMPLE_RATE);
+    return samplesPerChunk * BYTES_PER_S16_SAMPLE;
+}
+function createDecoder(inputPath) {
+    return spawn('ffmpeg', [
+        '-protocol_whitelist',
+        FFMPEG_PROTOCOLS,
+        '-i',
+        inputPath,
+        '-ar',
+        String(SAMPLE_RATE),
+        '-ac',
+        '1',
+        '-f',
+        's16le',
+        'pipe:1'
+    ], { stdio: ['ignore', 'pipe', 'inherit'] });
+}
+function waitForDecoder(decoder) {
+    return new Promise((resolve) => {
+        decoder.once('error', resolve);
+        decoder.once('close', (code) => {
+            if (code === 0)
+                resolve(null);
+            else
+                resolve(new Error(`ffmpeg exited with code ${code}`));
+        });
+    });
+}
+function stopDecoder(decoder) {
+    if (decoder?.exitCode === null && !decoder.killed)
+        decoder.kill();
+}
+async function printTranscription(session) {
+    for await (const event of session) {
+        if (event.type === 'text' && event.text)
+            process.stdout.write(event.text);
+    }
+}
+async function rejectWhenOutputEnds(output) {
+    await output;
+    throw new Error(EARLY_OUTPUT_END_MESSAGE);
+}
+async function writeAvailableChunks(session, pcm, chunkBytes) {
+    let offset = 0;
+    while (pcm.length - offset >= chunkBytes) {
+        session.write(pcm.subarray(offset, offset + chunkBytes));
+        offset += chunkBytes;
+        await delay(INPUT_CHUNK_MS);
+    }
+    return pcm.subarray(offset);
+}
+async function feedDecoderOutput(session, decoder, chunkBytes) {
+    let incomplete = Buffer.alloc(0);
+    for await (const decoded of decoder.stdout) {
+        const pcm = incomplete.length === 0 ? Buffer.from(decoded) : Buffer.concat([incomplete, decoded]);
+        incomplete = await writeAvailableChunks(session, pcm, chunkBytes);
+    }
+    return incomplete;
+}
+async function runStreaming(modelId, inputPath) {
+    const session = await transcribeStream({ modelId, parakeetStreamingConfig: {} });
+    const output = printTranscription(session);
+    let decoder;
+    let exited;
+    let feeding;
+    try {
+        decoder = createDecoder(inputPath);
+        exited = waitForDecoder(decoder);
+        feeding = feedDecoderOutput(session, decoder, calculateChunkBytes());
+        const incomplete = await Promise.race([feeding, rejectWhenOutputEnds(output)]);
+        const decoderError = await exited;
+        if (decoderError)
+            throw decoderError;
+        if (incomplete.length > 0)
+            session.write(incomplete);
+        session.end();
+        await output;
+        process.stdout.write('\n');
+    }
+    finally {
+        stopDecoder(decoder);
+        session.destroy();
+        await Promise.allSettled([exited, feeding, output]);
+    }
+}
+function printDownloadProgress(progress) {
+    const downloaded = (progress.downloaded / BYTES_PER_MEGABYTE).toFixed(1);
+    const total = (progress.total / BYTES_PER_MEGABYTE).toFixed(1);
+    const percentage = progress.percentage.toFixed(0);
+    const line = `Downloading ${percentage}% (${downloaded}/${total} MB)`;
+    process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+    if (progress.percentage >= 100)
+        process.stderr.write('\n');
+}
+async function run() {
+    const { audioFilePath, locale, modelSource, streaming } = parseArguments(process.argv.slice(2));
+    const inputPath = requireAudioFilePath(audioFilePath);
+    let modelId = null;
+    try {
+        console.log(`Loading Nemotron with locale ${locale}...`);
+        modelId = await loadModel({
+            modelSrc: modelSource ?? PARAKEET_NEMOTRON_0_6B_Q4_0,
+            modelType: 'parakeet-transcription',
+            modelConfig: { language: locale, streaming },
+            onProgress: printDownloadProgress
+        });
+        if (streaming) {
+            console.log('Streaming with the Nemotron native 320 ms operating point...');
+            await runStreaming(modelId, inputPath);
+        }
+        else {
+            console.log('Transcribing in batch mode...');
+            console.log(await transcribe({ modelId, audioChunk: inputPath }));
+        }
+    }
+    finally {
+        if (modelId)
+            await unloadModel({ modelId });
+    }
+}
+run().catch((error) => {
+    console.error(error);
+    process.exitCode = 1;
+});

package/dist/examples/audiogen/edit-music.d.ts

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

package/dist/examples/audiogen/edit-music.js

@@ -0,0 +1,121 @@
+import { writeFileSync } from 'node:fs';
+import { AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0, AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M, AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0, AUDIOGEN_VAE_BF16, audioEdit, loadModel, unloadModel } from '@qvac/sdk';
+// Edit an existing recording with ACE-Step: a Flow-Edit that re-conditions the
+// whole clip from a source prompt to a target prompt, then a Repaint that
+// regenerates one time range against a new prompt. Operations run in order.
+//
+// Usage:
+//   bun examples/audiogen/edit-music.ts <source.wav|mp3|...> "original pop song" "guitar pop-rock" [output.wav]
+//
+// The source must run at least REPAINT_END seconds: the Repaint below asks for
+// a fixed window, and a range past the end of the source is rejected with
+// `repaint.start must be within the source duration`.
+//
+// The source is a file path: the SDK decodes it (any FFmpeg-decodable format)
+// to the 48 kHz stereo float PCM the engine expects. Pass raw interleaved
+// stereo 48 kHz Float32 LE PCM in [-1, 1] as a Buffer instead when the audio
+// is already in memory — for example the `pcm` of an earlier `audioGen()` run,
+// converted from Int16 to Float32.
+// Repaint window, in seconds from the start of the source.
+const REPAINT_START = 10;
+const REPAINT_END = 20;
+const sourcePath = process.argv[2];
+const fromCaption = process.argv[3] ?? 'Original pop song';
+const toCaption = process.argv[4] ?? 'Guitar pop-rock';
+const outputPath = process.argv[5] ?? 'audiogen-edit.wav';
+if (!sourcePath) {
+    console.error('Usage: bun examples/audiogen/edit-music.ts <source-audio> "<from caption>" "<to caption>" [output.wav]');
+    process.exit(1);
+}
+let modelId;
+try {
+    console.log('▸ Loading ACE-Step AudioGen models...');
+    modelId = await loadModel({
+        modelType: 'audiogen',
+        modelConfig: {
+            textEncModelSrc: AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0,
+            lmModelSrc: AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0,
+            // Flow-Edit needs a turbo DiT variant; Repaint works on every variant.
+            ditModelSrc: AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M,
+            vaeModelSrc: AUDIOGEN_VAE_BF16,
+            useGPU: true
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Editing ${sourcePath}: "${fromCaption}" -> "${toCaption}"`);
+    const run = audioEdit({
+        modelId,
+        sourceAudio: sourcePath,
+        operations: [
+            {
+                type: 'flow-edit',
+                from: { caption: fromCaption },
+                to: { caption: toCaption }
+            },
+            {
+                // Regenerate the repaint window as a synth solo; the rest is kept.
+                type: 'repaint',
+                caption: 'analog synth solo',
+                lyrics: '[Instrumental]',
+                start: REPAINT_START,
+                end: REPAINT_END,
+                mode: 'balanced',
+                strength: 0.5
+            }
+        ],
+        // Seeds the first operation; each following operation uses seed + index.
+        seed: 22883
+    });
+    console.log(`▸ requestId: ${run.requestId}`);
+    for await (const progress of run.progressStream) {
+        const value = progress.total > 0 ? `${progress.step}/${progress.total}` : `${progress.step} (indeterminate)`;
+        console.log(`▸ ${progress.stage}: ${value}`);
+    }
+    const [audio, stats] = await Promise.all([run.audio, run.stats]);
+    writeFileSync(outputPath, createWav(audio.pcm, audio.sampleRate, audio.channels, audio.bitsPerSample));
+    if (stats)
+        console.log(`▸ Stats: ${JSON.stringify(stats)}`);
+    console.log(`▸ Saved ${outputPath}`);
+    await unloadModel({ modelId });
+    modelId = undefined;
+    process.exit(0);
+}
+catch (error) {
+    if (modelId !== undefined) {
+        try {
+            await unloadModel({ modelId });
+        }
+        catch {
+            // Preserve the edit error as the primary failure.
+        }
+    }
+    console.error('✖', error);
+    process.exit(1);
+}
+function createWav(pcm, sampleRate, channels, bitsPerSample) {
+    const header = new ArrayBuffer(44);
+    const view = new DataView(header);
+    const blockAlign = channels * (bitsPerSample / 8);
+    writeAscii(view, 0, 'RIFF');
+    view.setUint32(4, 36 + pcm.byteLength, true);
+    writeAscii(view, 8, 'WAVE');
+    writeAscii(view, 12, 'fmt ');
+    view.setUint32(16, 16, true);
+    view.setUint16(20, 1, true);
+    view.setUint16(22, channels, true);
+    view.setUint32(24, sampleRate, true);
+    view.setUint32(28, sampleRate * blockAlign, true);
+    view.setUint16(32, blockAlign, true);
+    view.setUint16(34, bitsPerSample, true);
+    writeAscii(view, 36, 'data');
+    view.setUint32(40, pcm.byteLength, true);
+    const wav = new Uint8Array(44 + pcm.byteLength);
+    wav.set(new Uint8Array(header));
+    wav.set(pcm, 44);
+    return wav;
+}
+function writeAscii(view, offset, value) {
+    for (let index = 0; index < value.length; index++) {
+        view.setUint8(offset + index, value.charCodeAt(index));
+    }
+}

package/dist/examples/audiogen/understand-music.d.ts

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

package/dist/examples/audiogen/understand-music.js

@@ -0,0 +1,73 @@
+import { AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0, AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M, AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0, AUDIOGEN_VAE_BF16, audioUnderstand, loadModel, unloadModel } from '@qvac/sdk';
+// Describe an existing recording with ACE-Step's reverse pipeline: the engine
+// encodes the audio, recovers its FSQ semantic codes, and the LM reports a
+// caption and the clip's musical metadata.
+//
+// Usage:
+//   bun examples/audiogen/understand-music.ts <source.wav|mp3|...> [language hint]
+//
+// The source is a file path: the SDK decodes it (any FFmpeg-decodable format)
+// to the 48 kHz stereo float PCM the engine expects. Pass raw interleaved
+// stereo 48 kHz Float32 LE PCM in [-1, 1] as a Buffer instead when the audio
+// is already in memory.
+const sourcePath = process.argv[2];
+const vocalLanguage = process.argv[3];
+if (!sourcePath) {
+    console.error('Usage: bun examples/audiogen/understand-music.ts <source-audio> [language]');
+    process.exit(1);
+}
+let modelId;
+try {
+    console.log('▸ Loading ACE-Step AudioGen models...');
+    modelId = await loadModel({
+        modelType: 'audiogen',
+        modelConfig: {
+            textEncModelSrc: AUDIOGEN_QWEN3_EMBEDDING_0_6B_Q8_0,
+            lmModelSrc: AUDIOGEN_ACESTEP_5HZ_LM_0_6B_Q8_0,
+            ditModelSrc: AUDIOGEN_ACESTEP_V15_TURBO_Q4_K_M,
+            vaeModelSrc: AUDIOGEN_VAE_BF16,
+            useGPU: true
+        }
+    });
+    console.log(`▸ Model loaded: ${modelId}`);
+    console.log(`▸ Analysing ${sourcePath}`);
+    const run = audioUnderstand({
+        modelId,
+        sourceAudio: sourcePath,
+        // Forced into the result instead of the LM's guess; omit to let it decide.
+        ...(vocalLanguage !== undefined && { vocalLanguage }),
+        seed: 11
+    });
+    console.log(`▸ requestId: ${run.requestId}`);
+    for await (const progress of run.progressStream) {
+        const value = progress.total > 0 ? `${progress.step}/${progress.total}` : `${progress.step} (indeterminate)`;
+        console.log(`▸ ${progress.stage}: ${value}`);
+    }
+    const [description, stats] = await Promise.all([run.description, run.stats]);
+    console.log(`▸ Caption: ${description.caption}`);
+    console.log(`▸ ${description.bpm} BPM, ${description.keyscale}, ${description.timesignature}`);
+    console.log(`▸ Vocal language: ${description.vocalLanguage}`);
+    // The LM's duration is an estimate; the recovered codes fix the true length.
+    console.log(`▸ Estimated duration: ${description.duration.toFixed(1)} s`);
+    console.log(`▸ Recovered ${description.audioCodes.length} semantic codes`);
+    if (stats)
+        console.log(`▸ Stats: ${JSON.stringify({ ...stats, understand: undefined })}`);
+    // `audioCodes` feeds straight back into audioGen() to re-synthesize the piece
+    // without re-running the LM:
+    //   audioGen({ modelId, caption: description.caption, audioCodes: description.audioCodes })
+    await unloadModel({ modelId });
+    modelId = undefined;
+    process.exit(0);
+}
+catch (error) {
+    if (modelId !== undefined) {
+        try {
+            await unloadModel({ modelId });
+        }
+        catch {
+            // Preserve the understand error as the primary failure.
+        }
+    }
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/diffusion-ic-lora-ltx.js

@@ -1,4 +1,4 @@
-import { GEMMA_3_12B_Q4_K_XL, loadModel, LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS, LTX_2_3_22B_Q5_K_M, LTX_2_3_VAE, LTX_2_3_VAE_1, unloadModel, video } from '@qvac/sdk';
+import { GEMMA_3_12B_Q4_K_XL, loadModel, LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS, LTX_2_3_22B_Q5_K_M, LTX_2_3_AUDIO_VAE, LTX_2_3_VIDEO_VAE, unloadModel, video } from '@qvac/sdk';
 import fs from 'fs';
 import path from 'path';
 const loraPath = process.argv[2];
@@ -24,8 +24,8 @@ try {
             device: 'gpu',
             threads: 4,
             llmModelSrc: GEMMA_3_12B_Q4_K_XL,
-            vaeModelSrc: LTX_2_3_VAE_1,
-            audioVaeModelSrc: LTX_2_3_VAE,
+            vaeModelSrc: LTX_2_3_VIDEO_VAE,
+            audioVaeModelSrc: LTX_2_3_AUDIO_VAE,
             embeddingsConnectorsModelSrc: LTX_2_3_22B_DISTILLED_EMBEDDINGS_CONNECTORS,
             diffusion_fa: true,
             offload_to_cpu: true,

package/dist/examples/diffusion-img2vid.js

@@ -33,7 +33,7 @@ try {
             clipVisionModelSrc,
             diffusion_fa: true,
             offload_to_cpu: true,
-            vae_on_cpu: true,
+            params_backend: 'vae=cpu',
             vae_tiling: true
         },
         onProgress: (p) => {

package/dist/examples/diffusion-txt2vid-minimax-h3.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=diffusion-txt2vid-minimax-h3.d.ts.map

package/dist/examples/diffusion-txt2vid-minimax-h3.js

@@ -0,0 +1,64 @@
+import { loadModel, unloadModel, video } from '@qvac/sdk';
+import fs from 'fs';
+import path from 'path';
+// Pass a directory containing the four MiniMax-H3 files, followed by an output path.
+const modelsDir = process.argv[2];
+if (!modelsDir) {
+    throw new Error('Usage: diffusion-txt2vid-minimax-h3.ts <models-directory> [output.avi]');
+}
+const outputPath = process.argv[3] || 'minimax-h3.avi';
+const modelSrc = path.resolve(modelsDir, process.env['H3_MODEL'] || 'minimax_h3_fl2va_pruned-Q4_K.gguf');
+const llmModelSrc = path.resolve(modelsDir, process.env['H3_LLM'] || 'qwen3vl_32b_minimax_h3-Q4_K_M.gguf');
+const vaeModelSrc = path.resolve(modelsDir, 'vae/minimax_h3_video_vae_fp16.safetensors');
+const audioVaeModelSrc = path.resolve(modelsDir, 'vae/minimax_h3_audio_vae_fp32.safetensors');
+for (const file of [modelSrc, llmModelSrc, vaeModelSrc, audioVaeModelSrc])
+    fs.accessSync(file);
+let modelId;
+try {
+    modelId = await loadModel({
+        modelType: 'sdcpp-generation',
+        modelSrc,
+        modelConfig: {
+            mode: 'video',
+            llmModelSrc,
+            vaeModelSrc,
+            audioVaeModelSrc,
+            device: 'gpu',
+            diffusion_fa: true,
+            offload_to_cpu: process.env['H3_OFFLOAD_TO_CPU'] !== '0',
+            stream_layers: process.env['H3_STREAM_LAYERS'] === '1',
+            ...(process.env['H3_BACKEND'] && { backend: process.env['H3_BACKEND'] }),
+            ...(process.env['H3_PARAMS_BACKEND'] && { params_backend: process.env['H3_PARAMS_BACKEND'] }),
+            ...(process.env['H3_MAX_VRAM'] && { max_vram: process.env['H3_MAX_VRAM'] })
+        }
+    });
+    const { progressStream, outputs, stats } = video({
+        modelId,
+        mode: 'txt2vid',
+        prompt: process.env['PROMPT'] ||
+            'Premium cinematic coffee commercial. A confident adult sits at a small café table at sunrise, slowly lifts one matte black coffee cup, takes a relaxed sip, and smiles. Warm golden rim light, drifting steam, realistic skin, natural hands, shallow depth of field, subtle slow camera push-in, restrained natural motion, polished live-action advertising, no dialogue, no text overlay.',
+        negative_prompt: 'extra people, duplicate cup, malformed hands, cup fused to hand, text, subtitles, watermark, cartoon, CGI, blur, flicker, jitter, camera shake',
+        width: 960,
+        height: 544,
+        // H3 uses 17*k+5 frames; 124 frames at 24 FPS is approximately 5.17 seconds.
+        video_frames: Number(process.env['FRAMES'] || 124),
+        fps: 24,
+        steps: 8,
+        cfg_scale: 1,
+        seed: 11
+    });
+    const progress = (async () => {
+        for await (const tick of progressStream)
+            console.log(`Step ${tick.step}/${tick.totalSteps}`);
+    })();
+    const [buffers, runtimeStats] = await Promise.all([outputs, stats, progress]);
+    if (!buffers[0])
+        throw new Error('Generation finished without an AVI result');
+    fs.writeFileSync(outputPath, buffers[0]);
+    console.log(`Saved ${outputPath}`, runtimeStats);
+}
+finally {
+    if (modelId)
+        await unloadModel({ modelId, clearStorage: false });
+}
+process.exit(0);

package/dist/examples/diffusion-txt2vid.js

@@ -26,7 +26,7 @@ try {
             vaeModelSrc,
             diffusion_fa: true,
             offload_to_cpu: true,
-            vae_on_cpu: true,
+            params_backend: 'vae=cpu',
             vae_tiling: true
         },
         onProgress: (p) => {

package/dist/examples/rag/rag-turbovec.d.ts

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

package/dist/examples/rag/rag-turbovec.js

@@ -0,0 +1,58 @@
+import { createVectorIndex, embed, loadModel, loadVectorIndex, unloadModel, GTE_LARGE_FP16, VectorIndexStorage } from '@qvac/sdk';
+// Retrieval over documents kept in your own store. The SDK holds only the
+// vectors, in a TurboVec index inside the worker; the documents stay in this
+// Map (or any database you choose) and result ids map back to them.
+try {
+    const query = process.argv[2] || 'Which moon has methane rain and lakes?';
+    console.log(`▸ Query: "${query}"`);
+    const documents = new Map([
+        ['1', 'Saturn moon Titan has lakes, clouds, and rain made of liquid methane.'],
+        ['2', 'Solar panels convert sunlight into electricity using photovoltaic cells.'],
+        ['3', 'Honeybees communicate the location of flowers through a waggle dance.'],
+        ['4', 'The Pacific Ocean is the largest and deepest ocean on Earth.']
+    ]);
+    const modelId = await loadModel({
+        modelSrc: GTE_LARGE_FP16,
+        onProgress: (p) => {
+            const mb = (n) => (n / 1e6).toFixed(1);
+            const line = `▸ Downloading ${p.percentage.toFixed(0)}% (${mb(p.downloaded)}/${mb(p.total)} MB)`;
+            process.stderr.write(process.stderr.isTTY ? `\r${line}` : `${line}\n`);
+            if (p.percentage >= 100)
+                process.stderr.write('\n');
+        }
+    });
+    console.log('▸ Embedding documents...');
+    const { embedding: vectors } = await embed({ modelId, text: [...documents.values()] });
+    console.log('▸ Building the vector index...');
+    const index = await createVectorIndex({
+        dim: vectors[0].length,
+        storage: VectorIndexStorage.TURBOVEC_Q4
+    });
+    await index.add({ ids: [...documents.keys()], vectors });
+    console.log(`▸ Indexed ${index.length} vectors of dimension ${index.dim}`);
+    console.log('▸ Searching...');
+    const { embedding: queryVector } = await embed({ modelId, text: query });
+    const hits = await index.search({ query: queryVector, k: 2 });
+    console.log('▸ Top matches:');
+    for (const hit of hits) {
+        console.log(`  score=${hit.score.toFixed(4)} id=${hit.id}: ${documents.get(hit.id)}`);
+    }
+    // Snapshots persist the vectors only. A relative path resolves under the
+    // QVAC data directory; pass an absolute path to store it elsewhere.
+    const snapshotPath = 'examples/rag-turbovec.qvi';
+    const { path: writtenPath } = await index.write({ path: snapshotPath });
+    await index.dispose();
+    console.log(`▸ Snapshot written to ${writtenPath}`);
+    const reloaded = await loadVectorIndex({ path: snapshotPath });
+    const [reloadedBest] = await reloaded.search({ query: queryVector, k: 1 });
+    await reloaded.dispose();
+    if (!reloadedBest || reloadedBest.id !== hits[0]?.id) {
+        throw new Error(`Reloaded index returned id=${reloadedBest?.id} but the original returned id=${hits[0]?.id}`);
+    }
+    console.log(`▸ Reloaded index agrees: best match id=${reloadedBest.id}`);
+    await unloadModel({ modelId });
+}
+catch (error) {
+    console.error('✖', error);
+    process.exit(1);
+}

package/dist/examples/tts/audio8.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // primary modelSrc is the LM GGUF; the codec decoder loads via modelConfig.
 // For zero-shot voice cloning also pass audio8CodecEncoderModelSrc plus
 // referenceAudioSrc/referenceText (a recording and its exact transcript).
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const AUDIO8_SAMPLE_RATE = 44100;
 try {
     const modelId = await loadModel({
@@ -32,16 +34,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? AUDIO8_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, AUDIO8_SAMPLE_RATE, 'audio8-output.wav');
+    createWav(audioBuffer, sampleRate, 'audio8-output.wav');
     console.log('▸ Audio saved to audio8-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, AUDIO8_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/chatterbox-enhanced.js

@@ -5,6 +5,7 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // enhancement — there is no on/off flag — and it forces the output to 48 kHz.
 // Usage: node chatterbox-enhanced.ts [referenceAudioSrc]
 const [referenceAudioSrc] = process.argv.slice(2);
+// Only a fallback; the engine reports the rate it actually produced.
 const ENHANCED_SAMPLE_RATE = 48000;
 try {
     const modelId = await loadModel({
@@ -33,16 +34,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? ENHANCED_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, ENHANCED_SAMPLE_RATE, 'chatterbox-enhanced-output.wav');
+    createWav(audioBuffer, sampleRate, 'chatterbox-enhanced-output.wav');
     console.log('▸ Audio saved to chatterbox-enhanced-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, ENHANCED_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

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

@@ -2,6 +2,8 @@ import { loadModel, textToSpeech, unloadModel, TTS_T3_MULTILINGUAL_CHATTERBOX_Q4
 import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './utils.js';
 // Chatterbox multilingual TTS (GGML): Japanese synthesis with MeCab/IPAdic.
 // Uses registry model constants — downloads automatically from QVAC Registry.
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const CHATTERBOX_SAMPLE_RATE = 24000;
 const OUTPUT_FILE = 'chatterbox-multilingual-output.wav';
 try {
@@ -32,16 +34,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? CHATTERBOX_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total samples: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, CHATTERBOX_SAMPLE_RATE, OUTPUT_FILE);
+    createWav(audioBuffer, sampleRate, OUTPUT_FILE);
     console.log(`▸ Audio saved to ${OUTPUT_FILE}`);
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, CHATTERBOX_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });

package/dist/examples/tts/chatterbox.js

@@ -4,6 +4,8 @@ import { createWav, playAudio, int16ArrayToBuffer, createWavHeader } from './uti
 // Uses registry model constants — downloads automatically from QVAC Registry.
 // Usage: node chatterbox.ts [referenceAudioSrc]
 const [referenceAudioSrc] = process.argv.slice(2);
+// Only a fallback: the engine reports the rate it actually produced, and
+// `outputSampleRate` (plus the LavaSR enhancer) can move it off this default.
 const CHATTERBOX_SAMPLE_RATE = 24000;
 try {
     const modelId = await loadModel({
@@ -35,16 +37,14 @@ try {
         stream: false
     });
     const audioBuffer = await result.buffer;
+    const sampleRate = (await result.sampleRate) ?? CHATTERBOX_SAMPLE_RATE;
     console.log(`▸ TTS complete. Total bytes: ${audioBuffer.length}`);
     console.log('▸ Saving audio to file...');
-    createWav(audioBuffer, CHATTERBOX_SAMPLE_RATE, 'tts-output.wav');
+    createWav(audioBuffer, sampleRate, 'tts-output.wav');
     console.log('▸ Audio saved to tts-output.wav');
     console.log('▸ Playing audio...');
     const audioData = int16ArrayToBuffer(audioBuffer);
-    const wavBuffer = Buffer.concat([
-        createWavHeader(audioData.length, CHATTERBOX_SAMPLE_RATE),
-        audioData
-    ]);
+    const wavBuffer = Buffer.concat([createWavHeader(audioData.length, sampleRate), audioData]);
     playAudio(wavBuffer);
     console.log('▸ Audio playback complete');
     await unloadModel({ modelId });