@qvac/tts-ggml 0.10.0 → 0.10.2

package/README.md

@@ -1275,9 +1275,10 @@ the demos still run and write the concatenated wav.
 ## Testing
 
 ```bash
-npm run test:unit          # mocked binding; fast
-npm run test:integration   # spins up the real engine; needs models
-npm run test               # both
+npm run test:unit               # mocked binding; fast
+npm run test:integration        # spins up the real engine; needs models
+npm run test:integration:smoke  # Supertonic suite only; the darwin-x64 CI leg runs this
+npm run test                    # both
 ```
 
 Integration tests scan a few candidate `models/` directories for the
@@ -1298,6 +1299,15 @@ files are absent.  They cover, across the engines:
   for WER against the synthesized audio (whisper-small via the
   `@qvac/asr-ggml` development dependency).
 
+On CPU the suite keeps to brief inference: single short syntheses, plus
+Supertonic's sub-second multi-sentence checks and a few capped CPU-backend
+checks (Audio8's 16-frame runs, the LavaSR denoiser composition). Tests that
+synthesize more (several runs or loads, longer text, WER) run on the GPU and
+are skipped when `NO_GPU=true`. So are the CosyVoice3, Chatterbox MTL and
+Parler f16/large tests, where one CPU synthesis already takes about a minute;
+the CPU smokes in `gpu-smoke.test.js` still run everywhere. The multi-run
+Parler tests need Metal, so off Apple they are skipped too.
+
 The MOSS integration test (`moss.test.js`) does not download its GGUFs:
 set `QVAC_TEST_MOSS_MODEL_DIR` to a directory holding them, otherwise it is
 skipped.  The C++ suite runs its MOSS synthesis cases when

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qvac/tts-ggml",
-  "version": "0.10.0",
+  "version": "0.10.2",
   "description": "Text to Speech (TTS) addon for qvac (ggml backend, wrapping the chatterbox + supertonic + parler + cosyvoice3 + audio8 + moss + Pocket engines from tts-cpp)",
   "addon": true,
   "engines": {
@@ -89,6 +89,7 @@
     "test:node": "node --test scripts/__tests__/*.test.js",
     "test": "npm run test:types && npm run test:unit && npm run test:integration",
     "test:integration": "npm run build:ts && brittle-bare test/integration/**/*.test.js",
+    "test:integration:smoke": "npm run build:ts && brittle-bare test/integration/supertonic.test.js",
     "test:benchmark:rtf": "npm run build:ts && brittle-bare test/benchmark/rtf-benchmark.test.js",
     "test:benchmark:rtf:matrix": "node scripts/run-rtf-benchmark-matrix.js",
     "test:benchmark:streaming": "npm run build:ts && brittle-bare test/benchmark/streaming-benchmark.test.js",
@@ -107,6 +108,7 @@
     "convert-models": "bash scripts/convert-models.sh",
     "setup-models": "bash scripts/setup-venv.sh && bash scripts/convert-models.sh",
     "download-models:registry": "node scripts/download-tts-ggml-models.js",
+    "download-models:smoke": "node scripts/download-tts-ggml-models.js --group supertonic",
     "example:pocket": "bare examples/pocket-tts.js",
     "test:pocket": "npm run build:ts && brittle-bare test/integration/pocket.integration.test.js"
   },
@@ -214,10 +216,10 @@
   },
   "types": "index.d.ts",
   "optionalDependencies": {
-    "@qvac/tts-ggml-linux-x64": "0.10.0",
-    "@qvac/tts-ggml-linux-arm64": "0.10.0",
-    "@qvac/tts-ggml-darwin-arm64": "0.10.0",
-    "@qvac/tts-ggml-darwin-x64": "0.10.0",
-    "@qvac/tts-ggml-win32-x64": "0.10.0"
+    "@qvac/tts-ggml-linux-x64": "0.10.2",
+    "@qvac/tts-ggml-linux-arm64": "0.10.2",
+    "@qvac/tts-ggml-darwin-arm64": "0.10.2",
+    "@qvac/tts-ggml-darwin-x64": "0.10.2",
+    "@qvac/tts-ggml-win32-x64": "0.10.2"
   }
 }

package/test/integration/addon.test.js

@@ -16,11 +16,11 @@ const { ensureChatterboxModels, ensureWhisperModel } = require('../utils/downloa
 const { loadWhisper, runWhisper } = require('../utils/runWhisper')
 const { recordTtsStats } = require('../utils/perf-helper')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
 const isDarwin = platform === 'darwin'
-const forceNoGpu = os.getEnv('NO_GPU') === 'true'
 
 const INPUT_SENTENCES = (isMobile ? 'short' : os.getEnv('INPUT_SENTENCES')) || 'short'
 const useSplit = INPUT_SENTENCES !== 'short'
@@ -42,7 +42,7 @@ function getEnglishSentences() {
 
 test(
   'Chatterbox TTS (ggml): English synthesis + optional WER verification',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const modelsDir = path.join(baseDir, 'models')
@@ -86,7 +86,8 @@ test(
     const model = await loadChatterboxTTS({
       threads: TTS_TEST_THREADS,
       modelDir: resolvedModelDir,
-      language: 'en'
+      language: 'en',
+      useGPU: GPU_ONLY_USE_GPU
     })
     t.ok(model, 'Chatterbox (ggml) model should be loaded')
 
@@ -254,7 +255,7 @@ test(
     const model = new TTSGgml({
       threads: TTS_TEST_THREADS,
       files: { modelDir: download.targetDir },
-      config: { language: 'en', ...(forceNoGpu ? { useGPU: false } : {}) },
+      config: { language: 'en', ...(NO_GPU ? { useGPU: false } : {}) },
       opts: { stats: true }
     })
 
@@ -315,7 +316,7 @@ test(
       threads: TTS_TEST_THREADS,
       files: { modelDir: download.targetDir },
       referenceAudio: resolveRefWavPath({}),
-      config: { language: 'en', outputSampleRate: 16000, ...(forceNoGpu ? { useGPU: false } : {}) },
+      config: { language: 'en', outputSampleRate: 16000, ...(NO_GPU ? { useGPU: false } : {}) },
       opts: { stats: true }
     })
     await model.load()
@@ -344,7 +345,7 @@ test(
 
 test(
   'Chatterbox TTS (ggml): native C++ chunk streaming via streamChunkTokens',
-  { timeout: 600000 },
+  { timeout: 600000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const modelsDir = path.join(baseDir, 'models')
@@ -371,7 +372,7 @@ test(
       streamChunkTokens: 25,
       streamFirstChunkTokens: 10,
       cfmSteps: 1,
-      config: { language: 'en', ...(forceNoGpu ? { useGPU: false } : {}) },
+      config: { language: 'en', useGPU: GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await model.load()

package/test/integration/chatterbox-mtl.test.js

@@ -26,13 +26,15 @@ const {
 } = require('../utils/downloadModel')
 const { recordTtsStats } = require('../utils/perf-helper')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
 
-// Language coverage test, not a GPU policy test: rely on the package
-// default (`useGPU: false`) rather than opting into GPU here.
-// Tests that *are* about GPU live in gpu-smoke.test.js.
+// Language coverage, not a GPU policy test. A single MTL synthesis already
+// takes close to a minute on the CPU-only runners, so these tests run on the
+// GPU only and are skipped there (NO_GPU=true). Tests that *are* about GPU live
+// in gpu-smoke.test.js.
 
 function getBaseDir() {
   return isMobile && global.testDir ? global.testDir : '.'
@@ -83,7 +85,7 @@ async function loadChatterboxMtlTTS(params) {
 
 test(
   'Chatterbox MTL TTS (ggml): synthesizes across es/fr/de with shared engine',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureChatterboxMtlModels({ targetDir: path.join(baseDir, 'models') })
@@ -98,7 +100,8 @@ test(
       modelDir: download.targetDir,
       t3ModelPath: path.join(download.targetDir, 'chatterbox-t3-mtl.gguf'),
       s3genModelPath: path.join(download.targetDir, 'chatterbox-s3gen-mtl.gguf'),
-      language: MTL_SENTENCES[0].lang
+      language: MTL_SENTENCES[0].lang,
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       for (let i = 0; i < MTL_SENTENCES.length; i++) {
@@ -166,7 +169,7 @@ test(
 
 test(
   'Chatterbox MTL TTS (ggml): synthesizes Japanese with MeCab dictionary',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureChatterboxMtlModels({ targetDir: path.join(baseDir, 'models') })
@@ -188,7 +191,8 @@ test(
       t3ModelPath: path.join(download.targetDir, 'chatterbox-t3-mtl.gguf'),
       s3genModelPath: path.join(download.targetDir, 'chatterbox-s3gen-mtl.gguf'),
       mecabDictDir: mecab.dir,
-      language: 'ja'
+      language: 'ja',
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const t0 = Date.now()
@@ -233,7 +237,7 @@ test(
 
 test(
   'Chatterbox MTL TTS (ggml): synthesizes Chinese with Cangjie table',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureChatterboxMtlModels({ targetDir: path.join(baseDir, 'models') })
@@ -255,7 +259,8 @@ test(
       t3ModelPath: path.join(download.targetDir, 'chatterbox-t3-mtl.gguf'),
       s3genModelPath: path.join(download.targetDir, 'chatterbox-s3gen-mtl.gguf'),
       cangjieTsvPath: cangjie.path,
-      language: 'zh'
+      language: 'zh',
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const t0 = Date.now()

package/test/integration/chatterbox-speed.test.js

@@ -12,6 +12,7 @@ const path = require('bare-path')
 const { loadChatterboxTTS, runChatterboxTTS } = require('../utils/runChatterboxTTS')
 const { ensureChatterboxModels } = require('../utils/downloadModel')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 function getBaseDir() {
   const platform = os.platform()
@@ -30,7 +31,7 @@ const EXPECTATION = {
 
 test(
   'Chatterbox TTS (ggml): speed config adjusts duration, preserves backward compat',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const modelsDir = path.join(getBaseDir(), 'models')
 
@@ -52,7 +53,8 @@ test(
         threads: TTS_TEST_THREADS,
         modelDir,
         language: 'en',
-        speed
+        speed,
+        useGPU: GPU_ONLY_USE_GPU
       })
       try {
         const r = await runChatterboxTTS(model, { text: TEXT }, EXPECTATION)

package/test/integration/cosyvoice3-clone.test.js

@@ -8,7 +8,6 @@
 const fs = require('bare-fs')
 const os = require('bare-os')
 const path = require('bare-path')
-const proc = require('bare-process')
 const test = require('brittle')
 const TTSGgml = require('@qvac/tts-ggml')
 
@@ -20,10 +19,11 @@ const {
 } = require('../utils/downloadModel')
 const { resolveRefWavPath } = require('../utils/runChatterboxTTS')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
-const useGPU = !isMobile && proc.env.NO_GPU === 'false'
+const useGPU = GPU_ONLY_USE_GPU
 
 function getBaseDir() {
   return isMobile && global.testDir ? global.testDir : '.'
@@ -99,7 +99,7 @@ async function synthOnce(t, loadParams, label) {
 
 test(
   'CosyVoice3 cloning (ggml): baked, zero-shot and cross-lingual all differ at one seed',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const modelDir = await ensureCloneReadyModelDir(t)
     if (!modelDir) return

package/test/integration/cosyvoice3-lavasr.test.js

@@ -7,7 +7,9 @@
 // CosyVoice3's ~2.4 GB model dir, while this one is listed on the dedicated
 // 'cosyvoice' row that pre-stages it (see test/mobile/test-groups.json).
 //
-// Text is kept short to bound CPU LM-decode time in CI, as in cosyvoice3.test.js.
+// As in cosyvoice3.test.js, the model-backed tests run on the GPU only and are
+// skipped on CPU-only runners (NO_GPU=true): even one short CosyVoice3 CPU
+// synthesis costs minutes there.
 //
 // Stage the enhancer GGUF via scripts/convert-lavasr-enhancer-to-gguf.py (from
 // the public LavaSRcpp ONNX release) into models/lavasr/lavasr-enhancer.gguf,
@@ -25,6 +27,7 @@ const {
   ensureCosyvoiceModel
 } = require('../utils/downloadModel')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
@@ -118,7 +121,7 @@ async function stageCosyvoice(t, baseDir) {
 
 test(
   'CosyVoice3 + LavaSR enhancer (batch) reports 48 kHz enhanced output',
-  { timeout: 900000, skip: SKIP_COSYVOICE },
+  { timeout: 900000, skip: SKIP_COSYVOICE || NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const enh = await stageEnhancer(t, baseDir)
@@ -130,7 +133,7 @@ test(
       threads: TTS_TEST_THREADS,
       engine: TTSGgml.ENGINE_COSYVOICE3,
       files: { cosyvoiceModelDir: dl.modelDir, lavasrEnhancer: enh.path },
-      config: { language: 'en', useGPU: false },
+      config: { language: 'en', useGPU: GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await model.load()
@@ -141,8 +144,8 @@ test(
       t.ok(r.stats, 'runtimeStats returned (constructed with stats:true)')
       t.is(
         r.stats.enhancerBackendDevice,
-        0,
-        'enhancer loaded and ran on CPU (enhancerBackendDevice=0, not -1 = never loaded)'
+        r.stats.backendDevice,
+        'enhancer loaded and ran on the engine device (not -1 = never loaded)'
       )
     } finally {
       try {
@@ -154,7 +157,7 @@ test(
 
 test(
   'CosyVoice3 + LavaSR enhancer + native chunk streaming emits 48 kHz chunks',
-  { timeout: 900000, skip: SKIP_COSYVOICE },
+  { timeout: 900000, skip: SKIP_COSYVOICE || NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const enh = await stageEnhancer(t, baseDir)
@@ -167,7 +170,7 @@ test(
       engine: TTSGgml.ENGINE_COSYVOICE3,
       files: { cosyvoiceModelDir: dl.modelDir, lavasrEnhancer: enh.path },
       streamChunkTokens: 25,
-      config: { language: 'en', useGPU: false },
+      config: { language: 'en', useGPU: GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await model.load()
@@ -191,7 +194,7 @@ test(
 
 test(
   'CosyVoice3 + enhancer + streaming resamples every chunk to outputSampleRate',
-  { timeout: 900000, skip: SKIP_COSYVOICE },
+  { timeout: 900000, skip: SKIP_COSYVOICE || NO_GPU },
   async (t) => {
     // A non-native rate while streaming is only legal because the enhancer's
     // overlap-reprocess window folds the resample in seam-free. Without this the
@@ -208,7 +211,7 @@ test(
       engine: TTSGgml.ENGINE_COSYVOICE3,
       files: { cosyvoiceModelDir: dl.modelDir, lavasrEnhancer: enh.path },
       streamChunkTokens: 25,
-      config: { language: 'en', useGPU: false, outputSampleRate: 16000 },
+      config: { language: 'en', useGPU: GPU_ONLY_USE_GPU, outputSampleRate: 16000 },
       opts: { stats: true }
     })
     await model.load()
@@ -228,7 +231,7 @@ test(
 
 test(
   'CosyVoice3 + LavaSR denoiser changes the emitted PCM',
-  { timeout: 900000, skip: SKIP_COSYVOICE },
+  { timeout: 900000, skip: SKIP_COSYVOICE || NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const dl = await stageCosyvoice(t, baseDir)
@@ -247,7 +250,7 @@ test(
         threads: TTS_TEST_THREADS,
         engine: TTSGgml.ENGINE_COSYVOICE3,
         files: Object.assign({ cosyvoiceModelDir: dl.modelDir }, files),
-        config: { language: 'en', useGPU: false, seed: SEED },
+        config: { language: 'en', useGPU: GPU_ONLY_USE_GPU, seed: SEED },
         opts: { stats: true }
       })
       await model.load()
@@ -294,6 +297,7 @@ test(
     if (!dl) return
 
     const badEnhancer = path.join(baseDir, 'models', 'lavasr', 'invalid-enhancer.gguf')
+    fs.mkdirSync(path.dirname(badEnhancer), { recursive: true })
     fs.writeFileSync(badEnhancer, 'not a gguf')
 
     const model = new TTSGgml({

package/test/integration/cosyvoice3.test.js

@@ -3,8 +3,10 @@
 // CosyVoice3 engine integration smoke: real synthesis in the desktop
 // `run-integration-tests` lane.  Mirrors parler.test.js (download model → build
 // TTSGgml → run → assert) but for the directory-consuming CosyVoice3 engine
-// (Qwen2 speech LM + DiT flow + CausalHiFT vocoder; native 24 kHz, CPU-only).
-// Text is kept SHORT to bound CPU LM-decode time in CI.
+// (Qwen2 speech LM + DiT flow + CausalHiFT vocoder; native 24 kHz).
+// Even one short CPU synthesis costs minutes on the CPU-only runners, so these
+// tests run on the GPU only and are skipped there (NO_GPU=true); the CPU crash
+// check is the CosyVoice3 CPU smoke in gpu-smoke.test.js.
 
 const os = require('bare-os')
 const path = require('bare-path')
@@ -13,6 +15,7 @@ const test = require('brittle')
 const { loadCosyvoiceTTS, runCosyvoiceTTS } = require('../utils/runCosyvoiceTTS')
 const { ensureCosyvoiceModel } = require('../utils/downloadModel')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
@@ -27,7 +30,7 @@ const MODEL_MISSING =
 
 test(
   'CosyVoice3 TTS (ggml): outputSampleRate=16000 resamples and reports 16 kHz',
-  { timeout: 600000 },
+  { timeout: 600000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureCosyvoiceModel({
@@ -43,7 +46,8 @@ test(
     const model = await loadCosyvoiceTTS({
       threads: TTS_TEST_THREADS,
       cosyvoiceModelDir: download.modelDir,
-      outputSampleRate: 16000
+      outputSampleRate: 16000,
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const text = 'Hello from CosyVoice.'
@@ -70,7 +74,7 @@ function samplesEqual(a, b) {
 
 test(
   'CosyVoice3 TTS (ggml): emotion changes the audio; per-call switch needs no reload',
-  { timeout: 900000 },
+  { timeout: 900000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureCosyvoiceModel({
@@ -87,7 +91,8 @@ test(
     const model = await loadCosyvoiceTTS({
       threads: TTS_TEST_THREADS,
       cosyvoiceModelDir: download.modelDir,
-      seed: 42
+      seed: 42,
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const text = 'Hello from CosyVoice.'
@@ -172,7 +177,7 @@ test(
 
 test(
   'CosyVoice3 TTS (ggml): instruct conditioning produces audio',
-  { timeout: 600000 },
+  { timeout: 600000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureCosyvoiceModel({
@@ -186,7 +191,8 @@ test(
     const model = await loadCosyvoiceTTS({
       threads: TTS_TEST_THREADS,
       cosyvoiceModelDir: download.modelDir,
-      emotion: 'happy'
+      emotion: 'happy',
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const text = 'Hello from CosyVoice.'

package/test/integration/lavasr-enhancer.test.js

@@ -33,6 +33,7 @@ const {
 } = require('../utils/downloadModel')
 const { resolveRefWavPath } = require('../utils/runChatterboxTTS')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
@@ -632,7 +633,7 @@ test(
 
 test(
   'Chatterbox + LavaSR enhancer + native chunk streaming emits 48 kHz chunks',
-  { timeout: 900000 },
+  { timeout: 900000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const enh = await ensureLavaSREnhancerGguf({
@@ -662,7 +663,7 @@ test(
       },
       referenceAudio: resolveRefWavPath({}),
       streamChunkTokens: 25, // native chunk streaming + enhancer (the path)
-      config: { language: 'en', useGPU: false },
+      config: { language: 'en', useGPU: GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await model.load()

package/test/integration/moss.test.js

@@ -11,6 +11,7 @@ const { recordTtsStats } = require('../utils/perf-helper')
 const { resolveRefWavPath } = require('../utils/runChatterboxTTS')
 const { readWavAsFloat32, createWav, resampleLinear } = require('../utils/wav-helper')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const MOSS_SAMPLE_RATE = 24000
 const MOSS_STREAM_FRAMES = 10
@@ -34,7 +35,6 @@ const GPU_DEVICE = 1
 
 const modelDir = (proc.env && proc.env[MODEL_DIR_ENV]) || ''
 const skipWithoutModels = modelDir === ''
-const noGpu = proc.env && proc.env.NO_GPU === 'true'
 
 function createMossModel(extra = {}, useGPU = false) {
   return new TTSGgml({
@@ -184,7 +184,7 @@ test(
 
 test(
   'MOSS TTS: useGPU=true synthesizes on a GPU backend',
-  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels || noGpu },
+  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels || NO_GPU },
   async (t) => {
     await withLoadedModel(
       {},
@@ -231,25 +231,29 @@ test(
 
 test(
   'MOSS TTS: durationTokens steers the length of the synthesized speech',
-  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels },
+  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels || NO_GPU },
   async (t) => {
-    await withLoadedModel({ durationTokens: SHORT_DURATION_TOKENS, seed: 7 }, async (model) => {
-      const short = await synthesize(model, SYNTHESIS_TEXT)
-      assertAudio(t, 'MOSS short target', short)
-      await model.reload({ durationTokens: LONG_DURATION_TOKENS })
-      const long = await synthesize(model, SYNTHESIS_TEXT)
-      assertAudio(t, 'MOSS long target', long)
-      t.ok(
-        long.samples.length > short.samples.length,
-        `a longer target yields longer speech (${short.samples.length} -> ${long.samples.length} samples)`
-      )
-    })
+    await withLoadedModel(
+      { durationTokens: SHORT_DURATION_TOKENS, seed: 7 },
+      async (model) => {
+        const short = await synthesize(model, SYNTHESIS_TEXT)
+        assertAudio(t, 'MOSS short target', short)
+        await model.reload({ durationTokens: LONG_DURATION_TOKENS })
+        const long = await synthesize(model, SYNTHESIS_TEXT)
+        assertAudio(t, 'MOSS long target', long)
+        t.ok(
+          long.samples.length > short.samples.length,
+          `a longer target yields longer speech (${short.samples.length} -> ${long.samples.length} samples)`
+        )
+      },
+      GPU_ONLY_USE_GPU
+    )
   }
 )
 
 test(
   'MOSS TTS: dialogue synthesis clones one reference per speaker',
-  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels },
+  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels || NO_GPU },
   async (t) => {
     if (!hasDialogueBackbone() || !hasEncoder()) {
       t.comment(`skipping: the TTSD backbone or the codec encoder is not in ${modelDir}`)
@@ -273,7 +277,8 @@ test(
           const result = await synthesize(model, DIALOGUE_TEXT)
           assertAudio(t, 'MOSS dialogue', result)
           recordMoss(t, 'moss dialogue', result, Date.now() - started)
-        }
+        },
+        GPU_ONLY_USE_GPU
       )
     } finally {
       removeFiles(references)

package/test/integration/multiple-runs.test.js

@@ -30,13 +30,15 @@ const {
 const { loadSupertonicTTS, runSupertonicTTS } = require('../utils/runSupertonicTTS')
 const { ensureChatterboxModels, ensureSupertonicModel } = require('../utils/downloadModel')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
 
-// Lifecycle / sequential-run test, not a GPU policy test: rely on the
-// package default (`useGPU: false`) rather than opting into GPU here.
-// Tests that *are* about GPU live in gpu-smoke.test.js.
+// Lifecycle / sequential-run tests, not GPU policy tests. The Chatterbox ones
+// run several syntheses, so they run on the GPU only and are skipped on CPU-only
+// runners (NO_GPU=true); the Supertonic reload keeps the package default
+// (`useGPU: false`). Tests that *are* about GPU live in gpu-smoke.test.js.
 
 function getBaseDir() {
   return isMobile && global.testDir ? global.testDir : '.'
@@ -50,7 +52,7 @@ const PHRASES = [
 
 test(
   'Chatterbox: multiple sequential runs reuse the same engine instance',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureChatterboxModels({ targetDir: path.join(baseDir, 'models') })
@@ -77,7 +79,8 @@ test(
       threads: TTS_TEST_THREADS,
       modelDir: download.targetDir,
       refWavPath,
-      language: 'en'
+      language: 'en',
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const timings = []
@@ -111,7 +114,7 @@ test(
 
 test(
   'Chatterbox: fresh instance per run (app-restart simulation)',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureChatterboxModels({ targetDir: path.join(baseDir, 'models') })
@@ -142,7 +145,8 @@ test(
         threads: TTS_TEST_THREADS,
         modelDir: download.targetDir,
         refWavPath,
-        language: 'en'
+        language: 'en',
+        useGPU: GPU_ONLY_USE_GPU
       })
       const loadMs = Date.now() - t0
       try {
@@ -175,58 +179,63 @@ test(
   }
 )
 
-test('Chatterbox: reload() between runs preserves stability', { timeout: 1800000 }, async (t) => {
-  const baseDir = getBaseDir()
-  const download = await ensureChatterboxModels({ targetDir: path.join(baseDir, 'models') })
-  if (!download.success) {
-    t.fail(
-      'Chatterbox GGUFs not available - registry fetch failed. Run `npm run download-models:registry` or stage models locally.'
-    )
-    return
-  }
+test(
+  'Chatterbox: reload() between runs preserves stability',
+  { timeout: 1800000, skip: NO_GPU },
+  async (t) => {
+    const baseDir = getBaseDir()
+    const download = await ensureChatterboxModels({ targetDir: path.join(baseDir, 'models') })
+    if (!download.success) {
+      t.fail(
+        'Chatterbox GGUFs not available - registry fetch failed. Run `npm run download-models:registry` or stage models locally.'
+      )
+      return
+    }
 
-  // Mobile-aware resolution: on iOS / Android the asset is staged into
-  // `Library/Caches/jfk.wav` via `global.assetPaths`; on desktop falls
-  // back to the in-tree `test/reference-audio/jfk.wav`. The bundled
-  // path is not readable from native code on iOS, which would trip
-  // `ModelFileNotFound` the moment `model.load()` reaches the C++
-  // `ChatterboxModel::validateConfig` check.
-  const refWavPath = resolveRefWavPath({})
-  if (!fs.existsSync(refWavPath)) {
-    t.pass('Skipped: reference audio missing')
-    return
-  }
+    // Mobile-aware resolution: on iOS / Android the asset is staged into
+    // `Library/Caches/jfk.wav` via `global.assetPaths`; on desktop falls
+    // back to the in-tree `test/reference-audio/jfk.wav`. The bundled
+    // path is not readable from native code on iOS, which would trip
+    // `ModelFileNotFound` the moment `model.load()` reaches the C++
+    // `ChatterboxModel::validateConfig` check.
+    const refWavPath = resolveRefWavPath({})
+    if (!fs.existsSync(refWavPath)) {
+      t.pass('Skipped: reference audio missing')
+      return
+    }
 
-  const model = await loadChatterboxTTS({
-    threads: TTS_TEST_THREADS,
-    modelDir: download.targetDir,
-    refWavPath,
-    language: 'en'
-  })
-  try {
-    const r1 = await runChatterboxTTS(
-      model,
-      { text: 'First run before reload.' },
-      { minSamples: 5000 }
-    )
-    t.ok(r1.passed, 'first run before reload should pass')
+    const model = await loadChatterboxTTS({
+      threads: TTS_TEST_THREADS,
+      modelDir: download.targetDir,
+      refWavPath,
+      language: 'en',
+      useGPU: GPU_ONLY_USE_GPU
+    })
+    try {
+      const r1 = await runChatterboxTTS(
+        model,
+        { text: 'First run before reload.' },
+        { minSamples: 5000 }
+      )
+      t.ok(r1.passed, 'first run before reload should pass')
 
-    await model.reload({ language: 'en' })
-    t.pass('reload() resolved')
+      await model.reload({ language: 'en' })
+      t.pass('reload() resolved')
 
-    const r2 = await runChatterboxTTS(
-      model,
-      { text: 'Second run after reload.' },
-      { minSamples: 5000 }
-    )
-    t.ok(r2.passed, 'second run after reload should pass')
-    t.ok(r2.data.sampleCount > 0, 'reloaded model produces audio')
-  } finally {
-    try {
-      await model.unload()
-    } catch (_e) {}
+      const r2 = await runChatterboxTTS(
+        model,
+        { text: 'Second run after reload.' },
+        { minSamples: 5000 }
+      )
+      t.ok(r2.passed, 'second run after reload should pass')
+      t.ok(r2.data.sampleCount > 0, 'reloaded model produces audio')
+    } finally {
+      try {
+        await model.unload()
+      } catch (_e) {}
+    }
   }
-})
+)
 
 test('Supertonic: reload() between runs preserves stability', { timeout: 1800000 }, async (t) => {
   const baseDir = getBaseDir()
@@ -272,7 +281,7 @@ test('Supertonic: reload() between runs preserves stability', { timeout: 1800000
 
 test(
   'Engine swap: chatterbox -> supertonic -> chatterbox in separate instances',
-  { timeout: 1800000 },
+  { timeout: 1800000, skip: NO_GPU },
   async (t) => {
     const baseDir = getBaseDir()
     const cb = await ensureChatterboxModels({ targetDir: path.join(baseDir, 'models') })
@@ -300,7 +309,8 @@ test(
       threads: TTS_TEST_THREADS,
       modelDir: cb.targetDir,
       refWavPath,
-      language: 'en'
+      language: 'en',
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const r = await runChatterboxTTS(c1, { text: 'Hello from chatterbox.' }, { minSamples: 5000 })
@@ -316,7 +326,7 @@ test(
       supertonicModelPath: st.path,
       voice: 'F1',
       language: 'en',
-      useGPU: false
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const r = await runSupertonicTTS(s1, { text: 'Hello from supertonic.' }, { minSamples: 5000 })
@@ -331,7 +341,8 @@ test(
       threads: TTS_TEST_THREADS,
       modelDir: cb.targetDir,
       refWavPath,
-      language: 'en'
+      language: 'en',
+      useGPU: GPU_ONLY_USE_GPU
     })
     try {
       const r = await runChatterboxTTS(

package/test/integration/output-sample-rate.test.js

@@ -13,6 +13,7 @@ const TTSGgml = require('@qvac/tts-ggml')
 
 const { ensureSupertonicModel, ensureParlerModel } = require('../utils/downloadModel')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { SKIP_PARLER_GPU_ONLY, PARLER_GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
@@ -123,7 +124,7 @@ test(
 
 test(
   'Parler: outputSampleRate=16000 resamples and reports 16 kHz',
-  { timeout: 600000 },
+  { timeout: 600000, skip: SKIP_PARLER_GPU_ONLY },
   async (t) => {
     const baseDir = getBaseDir()
     const dl = await ensureParlerModel({ targetDir: path.join(baseDir, 'models') })
@@ -140,6 +141,7 @@ test(
       files: { parlerModel: dl.path },
       voice: 'Laura',
       seed: 42,
+      config: { useGPU: PARLER_GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await native.load()
@@ -160,7 +162,7 @@ test(
       files: { parlerModel: dl.path },
       voice: 'Laura',
       seed: 42,
-      config: { outputSampleRate: 16000 },
+      config: { outputSampleRate: 16000, useGPU: PARLER_GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await resampled.load()

package/test/integration/parler-wer.test.js

@@ -7,9 +7,9 @@
 // chatterbox WER leg in addon.test.js (whisper ASR + wordErrorRate).
 //
 // macOS-desktop only (isDarwin): the whisper WER infra is desktop-only
-// across the tts-ggml suite. Runs on both the Metal GPU runner and the
-// no_gpu CPU runner (backend chosen like the quant loop). large-v1 is
-// RAM-gated; both tiers skip cleanly if their GGUF isn't staged.
+// across the tts-ggml suite. Runs on the Metal GPU runner only and is skipped
+// on CPU-only runners (NO_GPU=true). large-v1 is RAM-gated; both tiers skip
+// cleanly if their GGUF isn't staged.
 
 const os = require('bare-os')
 const path = require('bare-path')
@@ -27,10 +27,9 @@ const isApple = platform === 'darwin' || platform === 'ios'
 const NO_GPU = proc.env && proc.env.NO_GPU === 'true'
 const LARGE_MIN_RAM_BYTES = 16 * 1024 ** 3
 
-// Calibrated 2026-07-24: the CPU (no_gpu) runner is 0.0% WER at any seed; the
-// Metal/GPU runner diverges (FP reorder) — seed 42 is 0% on Apple-Silicon but
-// 22.2% on Intel-Mac Metal — so 0.35 tolerates the GPU variance while the CPU
-// leg stays effectively strict (greedy would be 50-100%, so this still asserts it).
+// Calibrated 2026-07-24: Metal diverges by FP reorder — seed 42 is 0% on
+// Apple-Silicon but 22.2% on Intel-Mac Metal — so 0.35 tolerates the GPU
+// variance while still asserting the words (greedy would be 50-100%).
 const WER_THRESHOLD = 0.35
 
 // Clear English sentences, all >= 9 words (a single ASR slip stays <= ~0.11,
@@ -51,7 +50,7 @@ function getBaseDir() {
 for (const { variant } of PARLER_WER_TIERS) {
   test(
     `Parler WER (${variant}): English synthesis transcribes within ${(WER_THRESHOLD * 100).toFixed(0)}%`,
-    { timeout: 1800000, skip: !isDarwin },
+    { timeout: 1800000, skip: !isDarwin || NO_GPU },
     async (t) => {
       if (variant === 'large' && os.totalmem() < LARGE_MIN_RAM_BYTES) {
         t.pass(

package/test/integration/parler.test.js

@@ -7,18 +7,17 @@
 
 const os = require('bare-os')
 const path = require('bare-path')
-const proc = require('bare-process')
 const test = require('brittle')
 
 const { loadParlerTTS, runParlerTTS } = require('../utils/runParlerTTS')
 const { ensureParlerModel } = require('../utils/downloadModel')
 const { recordTtsStats } = require('../utils/perf-helper')
 const { TTS_TEST_THREADS } = require('../utils/testThreads')
+const { NO_GPU, SKIP_PARLER_GPU_ONLY, PARLER_GPU_ONLY_USE_GPU } = require('../utils/gpuOnly')
 
 const platform = os.platform()
 const isMobile = platform === 'ios' || platform === 'android'
 const isApple = platform === 'darwin' || platform === 'ios'
-const NO_GPU = proc.env && proc.env.NO_GPU === 'true'
 
 function getBaseDir() {
   return isMobile && global.testDir ? global.testDir : '.'
@@ -137,7 +136,7 @@ test(
 
 test(
   'Parler TTS (ggml): description matrix — conflicts throw, per-call wins, defaults work',
-  { timeout: 600000 },
+  { timeout: 600000, skip: SKIP_PARLER_GPU_ONLY },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureParlerModel({ targetDir: path.join(baseDir, 'models') })
@@ -191,7 +190,8 @@ test(
       threads: TTS_TEST_THREADS,
       parlerModelPath: download.path,
       voice: 'Laura',
-      seed: 42
+      seed: 42,
+      useGPU: PARLER_GPU_ONLY_USE_GPU
     })
     try {
       // Per-call description conflict (same level) rejects.
@@ -234,7 +234,8 @@ test(
       threads: TTS_TEST_THREADS,
       parlerModelPath: download.path,
       description: 'A calm female voice, very clear audio.',
-      seed: 42
+      seed: 42,
+      useGPU: PARLER_GPU_ONLY_USE_GPU
     })
     try {
       await t.exception(
@@ -252,7 +253,7 @@ test(
 
 test(
   'Parler TTS (ggml): emotion flag changes the audio; per-call switch needs no reload',
-  { timeout: 600000 },
+  { timeout: 600000, skip: SKIP_PARLER_GPU_ONLY },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureParlerModel({ targetDir: path.join(baseDir, 'models') })
@@ -265,7 +266,8 @@ test(
       threads: TTS_TEST_THREADS,
       parlerModelPath: download.path,
       voice: 'Laura',
-      seed: 42
+      seed: 42,
+      useGPU: PARLER_GPU_ONLY_USE_GPU
     })
     try {
       const text = 'The weather is wonderful today.'
@@ -300,7 +302,7 @@ test(
 
 test(
   'Parler TTS (ggml): fixed seed is deterministic across runs and reload',
-  { timeout: 600000 },
+  { timeout: 600000, skip: SKIP_PARLER_GPU_ONLY },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureParlerModel({ targetDir: path.join(baseDir, 'models') })
@@ -314,7 +316,8 @@ test(
       parlerModelPath: download.path,
       voice: 'Laura',
       emotion: 'neutral',
-      seed: 42
+      seed: 42,
+      useGPU: PARLER_GPU_ONLY_USE_GPU
     })
     try {
       const text = 'Deterministic synthesis check.'
@@ -345,7 +348,7 @@ test(
 
 test(
   'Parler TTS (ggml): runStream emits per-sentence chunks with one pinned description',
-  { timeout: 600000 },
+  { timeout: 600000, skip: SKIP_PARLER_GPU_ONLY },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureParlerModel({ targetDir: path.join(baseDir, 'models') })
@@ -360,6 +363,7 @@ test(
       engine: TTSGgml.ENGINE_PARLER,
       files: { parlerModel: download.path },
       seed: 42,
+      config: { useGPU: PARLER_GPU_ONLY_USE_GPU },
       opts: { stats: true }
     })
     await model.load()
@@ -393,7 +397,7 @@ test(
 
 test(
   'Parler TTS (ggml): native streaming emits monotonic chunks equal to batch',
-  { timeout: 900000 },
+  { timeout: 900000, skip: SKIP_PARLER_GPU_ONLY },
   async (t) => {
     const baseDir = getBaseDir()
     const download = await ensureParlerModel({ targetDir: path.join(baseDir, 'models') })
@@ -526,22 +530,24 @@ test(
 
 // Desktop quant + backend coverage: q8_0 + f16 for indic/mini, q8_0 for large.
 // Runs on the platform's GPU-if-available backend (Metal on Apple GPU runners,
-// CPU otherwise). large self-gates on RAM; any tier that isn't staged skips
-// (t.pass) so a not-yet-registered tier never fails CI. Registered per PR #3372.
-// Desktop-only: the mobile Parler surface is covered by the gpu-smoke legs.
+// CPU otherwise). mini f16 and large are the slowest tiers on CPU (roughly
+// 45-80 s per synthesis), so they run on Metal only. large self-gates on RAM; any tier that isn't
+// staged skips (t.pass) so a not-yet-registered tier never fails CI. Registered
+// per PR #3372. Desktop-only: the mobile Parler surface is covered by the
+// gpu-smoke legs.
 const PARLER_QUANT_MATRIX = [
-  { variant: 'indic', quant: 'q8_0' },
-  { variant: 'indic', quant: 'f16' },
-  { variant: 'mini', quant: 'q8_0' },
-  { variant: 'mini', quant: 'f16' },
-  { variant: 'large', quant: 'q8_0' }
+  { variant: 'indic', quant: 'q8_0', gpuOnly: false },
+  { variant: 'indic', quant: 'f16', gpuOnly: false },
+  { variant: 'mini', quant: 'q8_0', gpuOnly: false },
+  { variant: 'mini', quant: 'f16', gpuOnly: true },
+  { variant: 'large', quant: 'q8_0', gpuOnly: true }
 ]
 const LARGE_MIN_RAM_BYTES = 16 * 1024 ** 3
 
-for (const { variant, quant } of PARLER_QUANT_MATRIX) {
+for (const { variant, quant, gpuOnly } of PARLER_QUANT_MATRIX) {
   test(
     `Parler TTS (ggml): ${variant} ${quant} synthesizes 44.1 kHz audio on the target backend`,
-    { timeout: 900000, skip: isMobile },
+    { timeout: 900000, skip: isMobile || (gpuOnly && SKIP_PARLER_GPU_ONLY) },
     async (t) => {
       if (variant === 'large' && os.totalmem() < LARGE_MIN_RAM_BYTES) {
         t.pass(