@qvac/tts-ggml 0.14.0 → 0.14.1

package/README.md

@@ -54,7 +54,7 @@ and registry prerequisites described under [MOSS](#moss).
 
 - Batch synthesis (`run({ input })` → single PCM buffer).
 - **Sentence-granularity streaming** — `runStreaming(asyncIterable)`:
-  yields one audio chunk per input sentence.
+  yields audio for each input sentence; Audio8 emits PCM as codec windows finish.
 - **Native per-chunk streaming** — set `streamChunkTokens` and audio
   flows out of the C++ engine chunk-by-chunk as T3 tokens produce
   S3Gen+HiFT output; sub-second first-audio-out inside a single
@@ -982,6 +982,19 @@ await model.load()
 await model.run({ input: 'Hello from a fully on-device pipeline.' })
 ```
 
+`runStream(text)`, `runStreaming(asyncIterable)` and
+`run({ input: text, streamOutput: true })` emit PCM as codec windows finish,
+before the current text chunk's complete waveform is ready. Ordinary `run()`
+retains batch synthesis. Native end markers have an empty `outputArray`. Use `response.await()`
+for completion and aggregate statistics, including for asynchronous text input. PCM window sizes are fixed by the codec, so
+`streamChunkTokens` and `streamFirstChunkTokens` remain unsupported.
+
+The native streaming API is included in the pinned `speech-cpp` dependency.
+Rebuild the addon to use it; an older published prebuild does not gain native
+streaming from a JavaScript update alone.
+Use [audio8-streaming.js](examples/audio8-streaming.js) to measure first PCM
+and completion through the wrapper, excluding model loading.
+
 Sampling is **repetition-aware**: a semantic token that repeats one from the
 recent window is re-drawn under a narrower nucleus at a higher temperature,
 which is what keeps the model out of the babble attractor that pure top-p
@@ -1005,6 +1018,15 @@ synthesis, the analysis half only to clone a voice or run a dialogue, so a
 text-only deployment can omit `files.mossCodecEncoder`.  The backbones have 8B
 parameters, so MOSS targets desktop hosts; mobile is not supported.
 
+On Metal, the backbone projects only the text-control logits needed during
+audio generation and omits text projection during the forced drain. Embedding
+tables stay on the GPU, and the model weight type is preserved.
+
+When `dialogueReferences` contains one recording, its encoded codes also serve
+as continuation, avoiding a duplicate encoder pass during engine creation.
+Multiple references retain their joined-audio continuation encoding. Prepared
+reference codes stay cached per instance for batch and streaming synthesis.
+
 ```js
 const model = new TTSGgml({
   engine: TTSGgml.ENGINE_MOSS,
@@ -1182,6 +1204,15 @@ to 30 seconds.  It is not a speech model, and it ships as one GGUF.  Select it
 with `engine: TTSGgml.ENGINE_MOSS_SFX` or by staging `moss-sfx-*.gguf` in the
 `modelDir`.
 
+Native generation reuses fixed cross-attention K/V across diffusion steps and
+uses Metal DiT FlashAttention when the GPU supports both attention shapes.
+Memory preflight includes the request cache (360 MiB for guided generation
+with the released models) alongside the scheduler's retained peak across text
+encoding, diffusion and VAE decoding, including repeated requests.
+FlashAttention can slightly change waveform samples. See the
+[native SoundEffect guide](https://github.com/tetherto/qvac-fabric-speech.cpp/blob/33174cc8693b1c8cdb44b5ff57b0f120bc89e454/engines/tts/docs/moss.md#moss-soundeffect)
+for precision details and the M1 Ultra measurements.
+
 ```js
 const sfx = new TTSGgml({
   engine: TTSGgml.ENGINE_MOSS_SFX,
@@ -1585,6 +1616,7 @@ Runnable demos under `examples/`:
 | `parler-enhanced.js` | Parler + LavaSR 48 kHz enhancement. `bare examples/parler-enhanced.js "Hello" Laura happy` |
 | `cosyvoice-tts.js` | CosyVoice3 batch synth with the cross-engine emotion option (24 kHz; CPU by default, `--gpu` opts into Metal / desktop Vulkan / Android GPU). `bare examples/cosyvoice-tts.js --gpu "Hello" happy` |
 | `cosyvoice-enhanced.js` | CosyVoice3 + LavaSR 48 kHz enhancement (add `--denoise` for the denoiser). `bare examples/cosyvoice-enhanced.js "Hello"` |
+| `audio8-streaming.js` | Measure Audio8 wrapper batch, streaming, or duplex latency: `bare examples/audio8-streaming.js ./models stream "Hello"`. Modes: `batch`, `stream`, `duplex`. |
 | `audio8-tts.js` | Audio8 batch synth, optionally cloning a reference. Set `QVAC_TTS_AUDIO8_GPU=1` for the desktop GPU backend (CUDA or Vulkan on linux, Vulkan on Windows). `bare examples/audio8-tts.js "Hello" voice.wav "What it says."` |
 | `moss-tts.js` | MOSS batch synth, optionally cloning a reference. Set `QVAC_TTS_MOSS_STREAM_FRAMES=25` for native chunk streaming, `QVAC_TTS_MOSS_DURATION=38` for a target length and `QVAC_TTS_MOSS_GPU=1` for the GPU backend. `bare examples/moss-tts.js "Hello" voice.wav` |
 | `moss-sound-effect.js` | MOSS-SoundEffect text-to-sound-effects at 48 kHz. Set `QVAC_TTS_MOSS_SFX_GPU=1` for the GPU backend and `QVAC_TTS_MOSS_SFX_STEPS` to trade quality for time. `bare examples/moss-sound-effect.js "Rain on a tin roof." 5` |

package/examples/audio8-streaming.js

@@ -0,0 +1,74 @@
+'use strict'
+
+const TTSGgml = require('..')
+const process = require('bare-process')
+
+const DEFAULT_TEXT = 'The first audio should arrive while the rest of this response is generated.'
+const MODES = ['batch', 'stream', 'duplex']
+
+async function* textSource(text) {
+  yield text
+}
+
+function start(model, mode, text) {
+  if (mode === 'batch') return model.run({ input: text })
+  if (mode === 'stream') return model.runStream(text, { maxChunkScalars: Array.from(text).length })
+  return model.runStreaming(textSource(text), { accumulateSentences: false })
+}
+
+async function measure(model, mode, text) {
+  const started = Date.now()
+  let firstAudioMs = null
+  let samples = 0
+  let sampleRate = 0
+  let chunks = 0
+  const response = await start(model, mode, text)
+  response.onUpdate((data) => {
+    if (!data.outputArray?.length) return
+    firstAudioMs ??= Date.now() - started
+    samples += data.outputArray.length
+    sampleRate = data.sampleRate
+    chunks++
+  })
+  await response.await()
+  if (firstAudioMs === null || sampleRate <= 0) throw new Error('Synthesis returned no audio')
+  console.log(
+    JSON.stringify({
+      mode,
+      firstAudioMs,
+      totalMs: Date.now() - started,
+      audioSeconds: samples / sampleRate,
+      chunks,
+      stats: response.stats
+    })
+  )
+}
+
+async function main() {
+  const [, , modelDir, mode = 'stream', text = DEFAULT_TEXT] = process.argv
+  if (!modelDir || !MODES.includes(mode)) {
+    throw new Error(
+      'Usage: bare examples/audio8-streaming.js MODEL_DIR [batch|stream|duplex] [TEXT]'
+    )
+  }
+  const model = new TTSGgml({
+    engine: TTSGgml.ENGINE_AUDIO8,
+    files: { modelDir },
+    greedy: true,
+    seed: 42,
+    threads: 4,
+    config: { useGPU: process.env.QVAC_TTS_AUDIO8_GPU === '1' },
+    opts: { stats: true }
+  })
+  try {
+    await model.load()
+    await measure(model, mode, text)
+  } finally {
+    await model.unload()
+  }
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/index.js

@@ -341,6 +341,9 @@ class TTSGgml {
     }
     async _dispatchJob(input) {
         const addon = this._requireAddon();
+        if (this._setup.engineType === engineIds_1.ENGINE_AUDIO8 && this._sentenceStream.ctx) {
+            return addon.runJob({ ...input, streamOutput: true });
+        }
         return this._pocket ? this._pocket.runJob(addon, input) : addon.runJob(input);
     }
     async cancel() {

package/lib/streamingSupport.js

@@ -31,8 +31,8 @@ function assertChunkStreamingSupport(setup) {
         (settings.streamChunkTokens != null ||
             settings.streamFirstChunkTokens != null)) {
         throw new Error("tts-ggml: streamChunkTokens / streamFirstChunkTokens are not " +
-            "supported by the audio8 engine, which synthesizes a whole " +
-            "utterance at a time. Use sentence-level streaming via " +
+            "supported by the audio8 engine, which uses fixed codec windows. " +
+            "Use incremental PCM streaming via " +
             "runStream() / runStreaming() / run({ streamOutput: true }).");
     }
     if ((engineType === engineIds_1.ENGINE_MOSS_SFX || engineType === engineIds_1.ENGINE_MOSS_SPEECH) &&

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@qvac/tts-ggml",
-  "version": "0.14.0",
+  "version": "0.14.1",
   "description": "Text to Speech (TTS) addon for qvac (ggml backend, wrapping the chatterbox + supertonic + parler + cosyvoice3 + audio8 + moss + moss-sfx + moss-speech + Pocket engines from tts-cpp)",
   "qvac": {
-    "ggml-speech": "2026-10-23"
+    "ggml-speech": "2026-10-27"
   },
   "engines": {
     "bare": ">=1.19.0"
@@ -218,16 +218,16 @@
     "bare-url": "^2.4.3"
   },
   "optionalDependencies": {
-    "@qvac/tts-ggml-linux-x64": "0.14.0",
-    "@qvac/tts-ggml-linux-arm64": "0.14.0",
-    "@qvac/tts-ggml-darwin-arm64": "0.14.0",
-    "@qvac/tts-ggml-darwin-x64": "0.14.0",
-    "@qvac/tts-ggml-win32-x64": "0.14.0"
+    "@qvac/tts-ggml-linux-x64": "0.14.1",
+    "@qvac/tts-ggml-linux-arm64": "0.14.1",
+    "@qvac/tts-ggml-darwin-arm64": "0.14.1",
+    "@qvac/tts-ggml-darwin-x64": "0.14.1",
+    "@qvac/tts-ggml-win32-x64": "0.14.1"
   },
   "types": "index.d.ts",
   "peerDependencies": {
-    "@qvac/tts-ggml-android-arm64": "0.14.0",
-    "@qvac/tts-ggml-ios": "0.14.0"
+    "@qvac/tts-ggml-android-arm64": "0.14.1",
+    "@qvac/tts-ggml-ios": "0.14.1"
   },
   "peerDependenciesMeta": {
     "@qvac/tts-ggml-android-arm64": {

package/test/integration/audio8-streaming.test.js

@@ -0,0 +1,66 @@
+'use strict'
+
+const test = require('brittle')
+const process = require('bare-process')
+const TTSGgml = require('../..')
+
+const LM = process.env.QVAC_TEST_AUDIO8_LM_GGUF
+const DECODER = process.env.QVAC_TEST_AUDIO8_DECODER_GGUF
+const FRAME_LIMIT = 48
+const TEXT = 'The listener should hear the first words before the complete response is generated.'
+const TIMEOUT_MS = 180000
+
+async function modelFiles() {
+  if (LM && DECODER) return { audio8Lm: LM, audio8CodecDecoder: DECODER }
+  const { ensureAudio8Models } = require('../utils/downloadModel')
+  const models = await ensureAudio8Models({ includeEncoder: false })
+  if (!models.success) throw new Error('Audio8 streaming tests require LM and decoder GGUFs')
+  return { audio8Lm: models.lmPath, audio8CodecDecoder: models.decoderPath }
+}
+
+async function* source() {
+  yield TEXT
+}
+
+function run(model, method) {
+  if (method === 'runStream') return model.runStream(TEXT)
+  if (method === 'runStreaming') {
+    return model.runStreaming(source(), { accumulateSentences: false })
+  }
+  return model.run({ input: TEXT, streamOutput: true })
+}
+
+for (const method of ['runStream', 'runStreaming', 'streamOutput']) {
+  test(
+    `Audio8 ${method} delivers native PCM without replay`,
+    { timeout: TIMEOUT_MS },
+    async (t) => {
+      const model = new TTSGgml({
+        engine: TTSGgml.ENGINE_AUDIO8,
+        files: await modelFiles(),
+        greedy: true,
+        threads: 4,
+        maxFrames: FRAME_LIMIT,
+        opts: { stats: true }
+      })
+      try {
+        await model.load()
+        let chunks = 0
+        let samples = 0
+        const response = await run(model, method)
+        response.onUpdate((chunk) => {
+          if (!chunk.outputArray?.length) return
+          t.is(chunk.sampleRate, 44100)
+          chunks++
+          samples += chunk.outputArray.length
+        })
+        await response.await()
+        t.ok(chunks > 1, 'multiple codec windows reached JavaScript')
+        t.is(samples, response.stats.totalSamples, 'PCM was delivered exactly once')
+        t.is(response.stats.generatedFrames, FRAME_LIMIT)
+      } finally {
+        await model.unload()
+      }
+    }
+  )
+}

package/tts.d.ts

@@ -2,6 +2,7 @@ export interface TTSConfigurationParams {
     [key: string]: string | number | boolean | string[] | undefined;
 }
 export interface TTSJobData {
+    streamOutput?: boolean;
     type: string;
     input: string;
     description?: string;