@qvac/tts-ggml 0.12.0 → 0.13.0

package/test/integration/moss.test.js

@@ -12,6 +12,12 @@ 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 { assertMossBackend } = require('../utils/mossBackend')
+const {
+  createMossGpuValidation,
+  ENCODER_RE,
+  DIALOGUE_BACKBONE_RE
+} = require('../utils/mossGpuValidation')
 
 const MOSS_SAMPLE_RATE = 24000
 const MOSS_STREAM_FRAMES = 10
@@ -19,8 +25,6 @@ const MOSS_SAMPLES_PER_FRAME = 1920
 const TEST_TIMEOUT_MS = 1800000
 const SYNTHESIS_TEXT = 'The MOSS integration test checks this generated voice.'
 const MODEL_DIR_ENV = 'QVAC_TEST_MOSS_MODEL_DIR'
-const ENCODER_RE = /^moss-codec-encoder(-[a-z0-9_]+)?\.gguf$/i
-const DIALOGUE_BACKBONE_RE = /^moss-ttsd(-[a-z0-9_]+)?\.gguf$/i
 const DIALOGUE_TEXT =
   '[S1] And so, my fellow Americans, [S2] ask what you can do for your country. ' +
   '[S1] Did the build finish this morning? [S2] Yes, every single test passed.'
@@ -29,12 +33,12 @@ const SPEAKER_TWO_SECONDS = [7.6, 10.6]
 const SHORT_DURATION_TOKENS = 25
 const LONG_DURATION_TOKENS = 100
 const INT16_FULL_SCALE = 32767
-const CPU_DEVICE = 0
-const CPU_BACKEND = 0
-const GPU_DEVICE = 1
+const PINNED_GPU_BACKEND = (proc.env && proc.env.TTS_CPP_GPU_BACKEND) || ''
 
 const modelDir = (proc.env && proc.env[MODEL_DIR_ENV]) || ''
 const skipWithoutModels = modelDir === ''
+const sourceAudio = resolveRefWavPath({})
+const validation = createMossGpuValidation(proc.env || {}, sourceAudio, GPU_ONLY_USE_GPU)
 
 function createMossModel(extra = {}, useGPU = false) {
   return new TTSGgml({
@@ -133,9 +137,8 @@ function recordMoss(t, label, result, wallMs) {
   )
 }
 
-function assertCpuBackend(t, label, stats) {
-  t.is(stats.backendDevice, CPU_DEVICE, `${label} reports a CPU device`)
-  t.is(stats.backendId, CPU_BACKEND, `${label} reports the CPU backend`)
+function assertBackend(t, label, stats, useGPU = false) {
+  assertMossBackend(t, label, stats, useGPU, PINNED_GPU_BACKEND)
 }
 
 async function withLoadedModel(extra, body, useGPU = false) {
@@ -156,31 +159,40 @@ test(
       const started = Date.now()
       const result = await synthesize(model, SYNTHESIS_TEXT)
       assertAudio(t, 'MOSS batch', result)
-      assertCpuBackend(t, 'MOSS batch', result.stats)
+      assertBackend(t, 'MOSS batch', result.stats)
       t.is(nonEmptyChunks(result).length, 1, 'batch synthesis emits one buffer')
       recordMoss(t, 'moss batch', result, Date.now() - started)
     })
+    validation.completed('CPU batch')
   }
 )
 
-test(
-  'MOSS TTS: native chunk streaming emits frame-sized chunks',
-  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels },
-  async (t) => {
-    await withLoadedModel({ streamChunkTokens: MOSS_STREAM_FRAMES }, async (model) => {
-      const started = Date.now()
-      const result = await synthesize(model, SYNTHESIS_TEXT)
-      assertAudio(t, 'MOSS stream', result)
-      const chunks = nonEmptyChunks(result)
-      t.ok(chunks.length > 1, `streaming emits several chunks (got ${chunks.length})`)
-      t.ok(
-        chunks.every((length) => length <= MOSS_STREAM_FRAMES * MOSS_SAMPLES_PER_FRAME),
-        'no chunk exceeds the configured frame count'
+for (const useGPU of [false, true]) {
+  test(
+    `MOSS TTS: native chunk streaming emits frame-sized chunks (${useGPU ? 'GPU' : 'CPU'})`,
+    { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels || (useGPU && NO_GPU) },
+    async (t) => {
+      await withLoadedModel(
+        { streamChunkTokens: MOSS_STREAM_FRAMES },
+        async (model) => {
+          const started = Date.now()
+          const result = await synthesize(model, SYNTHESIS_TEXT)
+          assertAudio(t, 'MOSS stream', result)
+          assertBackend(t, 'MOSS stream', result.stats, useGPU)
+          const chunks = nonEmptyChunks(result)
+          t.ok(chunks.length > 1, `streaming emits several chunks (got ${chunks.length})`)
+          t.ok(
+            chunks.every((length) => length <= MOSS_STREAM_FRAMES * MOSS_SAMPLES_PER_FRAME),
+            'no chunk exceeds the configured frame count'
+          )
+          recordMoss(t, 'moss stream', result, Date.now() - started)
+        },
+        useGPU
       )
-      recordMoss(t, 'moss stream', result, Date.now() - started)
-    })
-  }
-)
+      validation.completed(`${useGPU ? 'GPU' : 'CPU'} streaming`)
+    }
+  )
+}
 
 test(
   'MOSS TTS: useGPU=true synthesizes on a GPU backend',
@@ -192,42 +204,48 @@ test(
         const started = Date.now()
         const result = await synthesize(model, SYNTHESIS_TEXT)
         assertAudio(t, 'MOSS GPU', result)
-        t.is(result.stats.backendDevice, GPU_DEVICE, 'MOSS GPU reports a GPU device')
-        t.not(result.stats.backendId, CPU_BACKEND, 'MOSS GPU does not report the CPU backend')
-        t.is(result.stats.gpuUnsupported, 0, 'MOSS GPU does not report a GPU fallback')
+        assertBackend(t, 'MOSS GPU', result.stats, true)
         recordMoss(t, 'moss gpu', result, Date.now() - started)
       },
       true
     )
+    validation.completed('GPU batch')
   }
 )
 
-test(
-  'MOSS TTS: voice cloning synthesizes from a reference recording',
-  { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels },
-  async (t) => {
-    const sourceAudio = resolveRefWavPath({})
-    if (!hasEncoder()) {
-      t.comment(`skipping: no moss-codec-encoder GGUF in ${modelDir}`)
-      return
-    }
-    if (!fs.existsSync(sourceAudio)) {
-      t.fail(`MOSS reference audio is missing: ${sourceAudio}`)
-      return
-    }
-    const referenceAudio = writeReferenceAtMossRate(sourceAudio)
-    try {
-      await withLoadedModel({ referenceAudio, seed: 7 }, async (model) => {
-        const started = Date.now()
-        const result = await synthesize(model, SYNTHESIS_TEXT)
-        assertAudio(t, 'MOSS clone', result)
-        recordMoss(t, 'moss clone', result, Date.now() - started)
-      })
-    } finally {
-      fs.unlinkSync(referenceAudio)
+for (const useGPU of [false, true]) {
+  test(
+    `MOSS TTS: voice cloning synthesizes from a reference recording (${useGPU ? 'GPU' : 'CPU'})`,
+    { timeout: TEST_TIMEOUT_MS, skip: skipWithoutModels || (useGPU && NO_GPU) },
+    async (t) => {
+      if (!hasEncoder()) {
+        t.comment(`skipping: no moss-codec-encoder GGUF in ${modelDir}`)
+        return
+      }
+      if (!fs.existsSync(sourceAudio)) {
+        t.fail(`MOSS reference audio is missing: ${sourceAudio}`)
+        return
+      }
+      const referenceAudio = writeReferenceAtMossRate(sourceAudio)
+      try {
+        await withLoadedModel(
+          { referenceAudio, seed: 7 },
+          async (model) => {
+            const started = Date.now()
+            const result = await synthesize(model, SYNTHESIS_TEXT)
+            assertAudio(t, 'MOSS clone', result)
+            assertBackend(t, 'MOSS clone', result.stats, useGPU)
+            recordMoss(t, 'moss clone', result, Date.now() - started)
+          },
+          useGPU
+        )
+      } finally {
+        fs.unlinkSync(referenceAudio)
+      }
+      validation.completed(`${useGPU ? 'GPU' : 'CPU'} cloning`)
     }
-  }
-)
+  )
+}
 
 test(
   'MOSS TTS: durationTokens steers the length of the synthesized speech',
@@ -238,9 +256,11 @@ test(
       async (model) => {
         const short = await synthesize(model, SYNTHESIS_TEXT)
         assertAudio(t, 'MOSS short target', short)
+        assertBackend(t, 'MOSS short target', short.stats, GPU_ONLY_USE_GPU)
         await model.reload({ durationTokens: LONG_DURATION_TOKENS })
         const long = await synthesize(model, SYNTHESIS_TEXT)
         assertAudio(t, 'MOSS long target', long)
+        assertBackend(t, 'MOSS long target', long.stats, GPU_ONLY_USE_GPU)
         t.ok(
           long.samples.length > short.samples.length,
           `a longer target yields longer speech (${short.samples.length} -> ${long.samples.length} samples)`
@@ -248,6 +268,7 @@ test(
       },
       GPU_ONLY_USE_GPU
     )
+    validation.completed('GPU duration/reload')
   }
 )
 
@@ -259,7 +280,6 @@ test(
       t.comment(`skipping: the TTSD backbone or the codec encoder is not in ${modelDir}`)
       return
     }
-    const sourceAudio = resolveRefWavPath({})
     if (!fs.existsSync(sourceAudio)) {
       t.fail(`MOSS reference audio is missing: ${sourceAudio}`)
       return
@@ -276,6 +296,7 @@ test(
           const started = Date.now()
           const result = await synthesize(model, DIALOGUE_TEXT)
           assertAudio(t, 'MOSS dialogue', result)
+          assertBackend(t, 'MOSS dialogue', result.stats, GPU_ONLY_USE_GPU)
           recordMoss(t, 'moss dialogue', result, Date.now() - started)
         },
         GPU_ONLY_USE_GPU
@@ -283,5 +304,21 @@ test(
     } finally {
       removeFiles(references)
     }
+    validation.completed('GPU TTSD dialogue')
   }
 )
+
+if (validation.enabled) {
+  test('MOSS TTS: full GPU validation completed every required case', (t) => {
+    validation.assertComplete(t, [
+      'CPU batch',
+      'CPU streaming',
+      'GPU streaming',
+      'GPU batch',
+      'CPU cloning',
+      'GPU cloning',
+      'GPU duration/reload',
+      'GPU TTSD dialogue'
+    ])
+  })
+}

package/test/mobile/integration.auto.cjs

@@ -50,6 +50,14 @@ async function runLavasrEnhancerTest (options = {}) { // eslint-disable-line no-
   return runIntegrationModule('../integration/lavasr-enhancer.test.js', options)
 }
 
+async function runMossFitTest (options = {}) { // eslint-disable-line no-unused-vars
+  return runIntegrationModule('../integration/moss-fit.test.js', options)
+}
+
+async function runMossSfxFitTest (options = {}) { // eslint-disable-line no-unused-vars
+  return runIntegrationModule('../integration/moss-sfx-fit.test.js', options)
+}
+
 async function runMossSfxTest (options = {}) { // eslint-disable-line no-unused-vars
   return runIntegrationModule('../integration/moss-sfx.test.js', options)
 }
@@ -118,6 +126,8 @@ module.exports = {
   runFitTest,
   runGpuSmokeTest,
   runLavasrEnhancerTest,
+  runMossFitTest,
+  runMossSfxFitTest,
   runMossSfxTest,
   runMossSpeechTest,
   runMossTest,

package/test/mobile/test-groups.json

@@ -33,7 +33,9 @@
       "runMultipleRunsTest",
       "runGpuSmokeTest",
       "runOutputSampleRateTest",
-      "runVoiceControlsTest"
+      "runVoiceControlsTest",
+      "runMossFitTest",
+      "runMossSfxFitTest"
     ]
   },
   "android": {
@@ -69,7 +71,9 @@
       "runMultipleRunsTest",
       "runGpuSmokeTest",
       "runOutputSampleRateTest",
-      "runVoiceControlsTest"
+      "runVoiceControlsTest",
+      "runMossFitTest",
+      "runMossSfxFitTest"
     ]
   }
 }

package/test/utils/gpuOnly.js

@@ -0,0 +1,15 @@
+'use strict'
+
+const os = require('bare-os')
+const proc = require('bare-process')
+
+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'
+const GPU_ONLY_USE_GPU = !isMobile
+const SKIP_PARLER_GPU_ONLY = NO_GPU || (!isMobile && !isApple)
+const PARLER_GPU_ONLY_USE_GPU = isApple && !isMobile
+
+module.exports = { NO_GPU, GPU_ONLY_USE_GPU, SKIP_PARLER_GPU_ONLY, PARLER_GPU_ONLY_USE_GPU }

package/test/utils/mossBackend.js

@@ -0,0 +1,34 @@
+'use strict'
+
+const GPU_BACKEND_IDS = { metal: 1, cuda: 2, vulkan: 3, opencl: 4 }
+
+// The native engine reads TTS_CPP_GPU_BACKEND. Check its reported backend as
+// well: a different GPU must not make a CUDA/Vulkan validation lane pass.
+function assertMossBackend(t, label, stats, useGPU, pinnedBackend = '') {
+  if (!stats) {
+    t.fail(`${label}: missing runtime stats; cannot verify the backend`)
+    return
+  }
+  t.is(stats.backendDevice, useGPU ? 1 : 0, `${label}: requested compute device`)
+  if (!useGPU) {
+    t.is(stats.backendId, 0, `${label}: CPU requested explicitly`)
+    return
+  }
+  t.is(stats.gpuUnsupported, 0, `${label}: no GPU fallback`)
+  pinnedBackend = pinnedBackend.toLowerCase()
+  if (pinnedBackend) {
+    if (!Object.prototype.hasOwnProperty.call(GPU_BACKEND_IDS, pinnedBackend)) {
+      t.fail(`${label}: unknown TTS_CPP_GPU_BACKEND=${pinnedBackend}`)
+      return
+    }
+    t.is(
+      stats.backendId,
+      GPU_BACKEND_IDS[pinnedBackend],
+      `${label}: TTS_CPP_GPU_BACKEND=${pinnedBackend}`
+    )
+  } else {
+    t.ok(Object.values(GPU_BACKEND_IDS).includes(stats.backendId), `${label}: known GPU backend`)
+  }
+}
+
+module.exports = { assertMossBackend }

package/test/utils/mossGpuValidation.js

@@ -0,0 +1,70 @@
+'use strict'
+
+const fs = require('bare-fs')
+const path = require('bare-path')
+
+const ENCODER_RE = /^moss-codec-encoder(-[a-z0-9_]+)?\.gguf$/i
+const DIALOGUE_BACKBONE_RE = /^moss-ttsd(-[a-z0-9_]+)?\.gguf$/i
+const REQUIRED_MODELS = {
+  QVAC_TEST_MOSS_MODEL_DIR: [
+    ['TTS backbone', /^moss-tts-delay(-[a-z0-9_]+)?\.gguf$/i],
+    ['TTSD backbone', DIALOGUE_BACKBONE_RE],
+    ['codec decoder', /^moss-codec-decoder(-[a-z0-9_]+)?\.gguf$/i],
+    ['codec encoder', ENCODER_RE]
+  ],
+  QVAC_TEST_MOSS_SPEECH_MODEL_DIR: [
+    ['Speech backbone', /^moss-speech(-(?!codec)[a-z0-9_]+)?\.gguf$/i],
+    ['Speech codec', /^moss-speech-codec(-[a-z0-9_]+)?\.gguf$/i]
+  ]
+}
+
+function requireValidation(condition, message) {
+  if (!condition) throw new Error(`MOSS full GPU validation: ${message}`)
+}
+
+function isFile(file) {
+  return fs.existsSync(file) && fs.statSync(file).isFile()
+}
+
+// Called before either suite registers tests. Reuse each suite's reference WAV
+// resolver so preflight and inference cannot silently select different audio.
+function createMossGpuValidation(env, referenceAudio, gpuOnlyUseGPU = true) {
+  const enabled = env.QVAC_TEST_MOSS_FULL_GPU === 'true'
+  const completed = new Set()
+  if (enabled) {
+    requireValidation(env.NO_GPU !== 'true', 'NO_GPU=true conflicts with full GPU validation')
+    requireValidation(gpuOnlyUseGPU, 'full GPU validation requires the desktop GPU cases')
+    requireValidation(
+      ['cuda', 'vulkan', 'metal', 'opencl'].includes((env.TTS_CPP_GPU_BACKEND || '').toLowerCase()),
+      'set TTS_CPP_GPU_BACKEND to cuda, vulkan, metal or opencl'
+    )
+    for (const [variable, requirements] of Object.entries(REQUIRED_MODELS)) {
+      const directory = env[variable]
+      requireValidation(
+        directory && fs.existsSync(directory) && fs.statSync(directory).isDirectory(),
+        `${variable} must name an existing model directory`
+      )
+      const files = fs.readdirSync(directory).filter((entry) => isFile(path.join(directory, entry)))
+      for (const [label, pattern] of requirements) {
+        requireValidation(
+          files.some((file) => pattern.test(file)),
+          `${variable}: missing ${label}`
+        )
+      }
+    }
+    requireValidation(isFile(referenceAudio), `reference WAV is missing: ${referenceAudio}`)
+  }
+  return {
+    enabled,
+    completed(caseName) {
+      completed.add(caseName)
+    },
+    assertComplete(t, expected) {
+      for (const caseName of expected) {
+        t.ok(completed.has(caseName), `full GPU validation executed ${caseName}`)
+      }
+    }
+  }
+}
+
+module.exports = { createMossGpuValidation, ENCODER_RE, DIALOGUE_BACKBONE_RE }

package/test/utils/perf-helper.js

@@ -0,0 +1,275 @@
+'use strict'
+// Performance-recording helper shared by the tts-ggml integration tests
+// (Chatterbox English/MTL, Supertonic, Supertonic MTL, GPU smoke). Holds the
+// singleton perf-reporter, the mobile-safe inline fallback, and
+// `recordTtsStats()` which turns an addon `response.stats` payload into a perf
+// row.
+//
+// Lives in test/utils/ (not test/integration/) so it sits next to the other
+// shared runners (runChatterboxTTS.js, runSupertonicTTS.js, ...) and is never
+// picked up by the mobile test generator or the brittle test runner, which
+// only discover test/integration/*.test.js.
+//
+// Mirrors the structure of the Parakeet/LLM helpers: on desktop we require the
+// shared scripts/test-utils/performance-reporter directly; on mobile that path
+// lives outside the addon package and bare-pack can't bundle it, so we fall
+// back to an inline lightweight reporter that emits [PERF_REPORT_START]/
+// [PERF_CHUNK] markers extract-from-log.js already understands.
+
+const fs = require('bare-fs')
+const path = require('bare-path')
+const os = require('bare-os')
+const process = require('bare-process')
+
+const platform = os.platform()
+const arch = os.arch()
+const platformLabel = `${platform}-${arch}`
+const isMobile = platform === 'ios' || platform === 'android'
+
+// Inject bare-subprocess so performance-reporter.js's _detectGpu() can shell
+// out to nvidia-smi / vulkaninfo / system_profiler on desktop runners.
+// Resolving from this caller file works (it lives next to the addon's
+// node_modules); resolving from inside scripts/test-utils/ does not because
+// require('child_process') throws under Bare. Without this, device.gpu stays
+// null and the perf report shows "N/A" for the GPU. Mirrors the LLM addon's
+// _perf-helper.js. Mobile doesn't need it — the inline fallback below leaves
+// gpu null on Device Farm where the probes wouldn't work anyway.
+let _subprocess = null
+try {
+  _subprocess = require('bare-subprocess')
+} catch (_) {}
+
+let createPerformanceReporter
+const _scriptBase = path.join('..', '..', '..', '..', 'scripts', 'test-utils')
+try {
+  const perfReporterMod = require(path.join(_scriptBase, 'performance-reporter'))
+  perfReporterMod.configure({ fs, path, process, os, subprocess: _subprocess })
+  createPerformanceReporter = perfReporterMod.createPerformanceReporter
+} catch (_) {
+  createPerformanceReporter = function (opts) {
+    const _results = []
+    const _startedAt = new Date().toISOString()
+    const _addon = (opts && opts.addon) || 'tts-ggml'
+    const _addonType = (opts && opts.addonType) || 'tts'
+    const _device = {
+      name: platform,
+      platform,
+      os_version: '',
+      arch: os.arch ? os.arch() : '',
+      // GPU label only filled in for desktop runners by
+      // performance-reporter.js's _detectGpu(). On Device Farm we leave it
+      // null and let the aggregator fall back to the device name.
+      gpu: null,
+      runner: 'device-farm'
+    }
+
+    return {
+      record(testName, metrics, extra) {
+        const entry = {
+          test: testName,
+          execution_provider: (extra && extra.execution_provider) || null,
+          model: (extra && extra.model) || null,
+          metrics: Object.assign(
+            {
+              total_time_ms: null,
+              tps: null,
+              real_time_factor: null,
+              sample_count: null,
+              audio_duration_ms: null
+            },
+            metrics
+          ),
+          input: (extra && extra.input) || null,
+          output: (extra && extra.output) || null
+        }
+        _results.push(entry)
+      },
+      toJSON() {
+        return {
+          schema_version: '1.0',
+          addon: _addon,
+          addon_type: _addonType,
+          timestamp: _startedAt,
+          device: _device,
+          results: _results
+        }
+      },
+      writeReport() {
+        const json = JSON.stringify(this.toJSON())
+        const dirs = []
+        if (global.testDir) dirs.push(global.testDir)
+        if (platform === 'android') {
+          dirs.push('/sdcard/Android/data/io.tether.test.qvac/files')
+          dirs.push('/storage/emulated/0/Android/data/io.tether.test.qvac/files')
+          dirs.push('/data/local/tmp')
+        }
+        dirs.push('/tmp')
+        for (let di = 0; di < dirs.length; di++) {
+          try {
+            try {
+              fs.mkdirSync(dirs[di], { recursive: true })
+            } catch (_) {}
+            const p = path.join(dirs[di], 'perf-report.json')
+            fs.writeFileSync(p, json)
+            console.log('[PERF_REPORT_PATH]' + p)
+          } catch (e) {
+            console.log('[perf-reporter] write to ' + dirs[di] + ' failed: ' + e.message)
+          }
+        }
+      },
+      writeStepSummary() {},
+      writeToConsole() {
+        try {
+          const json = JSON.stringify(this.toJSON())
+          const CHUNK = 800
+          if (json.length <= CHUNK) {
+            console.log('[PERF_REPORT_START]' + json + '[PERF_REPORT_END]')
+          } else {
+            const id = Date.now().toString(36)
+            const n = Math.ceil(json.length / CHUNK)
+            for (let i = 0; i < n; i++) {
+              console.log(
+                '[PERF_CHUNK:' +
+                  id +
+                  ':' +
+                  i +
+                  ':' +
+                  n +
+                  ']' +
+                  json.substring(i * CHUNK, (i + 1) * CHUNK)
+              )
+            }
+          }
+        } catch (err) {
+          console.log('[perf-reporter] mobile console write failed: ' + err.message)
+        }
+      },
+      get length() {
+        return _results.length
+      }
+    }
+  }
+}
+
+const _perfReporter = createPerformanceReporter({
+  addon: 'tts-ggml',
+  addonType: 'tts'
+})
+
+const _reportPath = path.resolve('.', 'test/results/performance-report.json')
+let _reportScheduled = false
+
+function _flushPerfReport() {
+  if (_perfReporter.length === 0) return
+  try {
+    _perfReporter.writeReport(_reportPath)
+  } catch (_) {}
+  try {
+    _perfReporter.writeStepSummary()
+  } catch (_) {}
+  try {
+    _perfReporter.writeToConsole()
+  } catch (_) {}
+}
+
+function _scheduleReportWrite() {
+  if (_reportScheduled) return
+  _reportScheduled = true
+  process.on('exit', _flushPerfReport)
+}
+
+function _num(v) {
+  return typeof v === 'number' && Number.isFinite(v) ? v : null
+}
+
+/**
+ * Record a Chatterbox (ggml) synthesis stats row through the shared perf
+ * reporter.
+ *
+ * @param {string} label - Test label, e.g. 'chatterbox english 1'. A leading
+ *                         [CPU]/[GPU] is optional and only used as a fallback
+ *                         hint — the row is tagged from the resolved backend
+ *                         (stats.backendDevice) when available, and the prefix
+ *                         is normalized to match.
+ * @param {Object} stats - response.stats from the addon:
+ *                         { realTimeFactor, audioDurationMs, totalSamples,
+ *                           backendDevice, ... }
+ * @param {Object} [extra] - Optional overrides:
+ *                         { wallMs, sampleCount, model, output,
+ *                           executionProvider }.
+ */
+function recordTtsStats(label, stats, extra) {
+  const s = stats || {}
+  const resolvedEp = s.backendDevice === 1 ? 'gpu' : s.backendDevice === 0 ? 'cpu' : null
+  const epOverride = extra && extra.executionProvider
+  const labelEp = /\[gpu\]/i.test(label) ? 'gpu' : /\[cpu\]/i.test(label) ? 'cpu' : null
+  const ep = resolvedEp || epOverride || labelEp
+
+  const baseLabel = label.replace(/^\s*\[(?:cpu|gpu)\]\s*/i, '')
+  const finalLabel = ep ? `[${ep.toUpperCase()}] ${baseLabel}` : baseLabel
+
+  const rtf = _num(s.realTimeFactor)
+  const sampleCount =
+    (extra && _num(extra.sampleCount)) != null ? _num(extra.sampleCount) : _num(s.totalSamples)
+  const audioMs = _num(s.audioDurationMs) != null ? Math.round(_num(s.audioDurationMs)) : null
+  const wallMs = extra && _num(extra.wallMs) != null ? Math.round(_num(extra.wallMs)) : null
+  const tps = _num(s.tokensPerSecond)
+
+  // When the addon doesn't report a positive realTimeFactor (e.g. Supertonic /
+  // some GPU paths), derive it from the measured wall time and audio duration
+  // — the same fallback the RTF benchmark uses — so the row still carries an
+  // RTF instead of n/a. Callers that already pass a derived realTimeFactor
+  // (addon.test.js) keep it untouched.
+  //
+  // The two bases aren't comparable (compute-RTF excludes JS/marshalling
+  // overhead that wall-RTF includes), so record rtf_source per row: anyone
+  // comparing numbers across rows in a single report can see which is which.
+  const usingComputeRtf = rtf != null && rtf > 0
+  const effRtf = usingComputeRtf ? rtf : wallMs != null && audioMs ? wallMs / audioMs : null
+  const rtfSource = usingComputeRtf ? 'compute' : effRtf != null ? 'wall' : null
+
+  _perfReporter.record(
+    finalLabel,
+    {
+      total_time_ms: wallMs,
+      tps,
+      real_time_factor: effRtf,
+      rtf_source: rtfSource,
+      sample_count: sampleCount,
+      audio_duration_ms: audioMs
+    },
+    {
+      execution_provider: ep,
+      model: (extra && extra.model) || null,
+      output: extra && extra.output ? String(extra.output) : null
+    }
+  )
+  _scheduleReportWrite()
+
+  if (isMobile) {
+    try {
+      _perfReporter.writeReport()
+    } catch (_) {}
+    try {
+      _perfReporter.writeToConsole()
+    } catch (_) {}
+  }
+
+  const lines = [
+    `${finalLabel} Performance Metrics (platform=${platformLabel}):`,
+    `    - Wall time: ${wallMs !== null ? wallMs + 'ms' : 'n/a'}`,
+    `    - RTF: ${effRtf !== null ? effRtf.toFixed(4) + ' (' + rtfSource + ')' : 'n/a'}`,
+    `    - Samples: ${sampleCount !== null ? sampleCount : 'n/a'}`,
+    `    - Audio: ${audioMs !== null ? audioMs + 'ms' : 'n/a'}`
+  ]
+  return lines.join('\n')
+}
+
+module.exports = {
+  platform,
+  arch,
+  platformLabel,
+  isMobile,
+  recordTtsStats,
+  flushTtsPerfReport: _flushPerfReport
+}