@qvac/tts-ggml 0.11.1 → 0.13.0

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
+}

package/test/utils/testThreads.js

@@ -0,0 +1,5 @@
+'use strict'
+
+const TTS_TEST_THREADS = 4
+
+module.exports = { TTS_TEST_THREADS }

package/lib/backends.d.ts

@@ -1,10 +0,0 @@
-export declare const PREBUILT_HOSTS: string[];
-export interface BackendsDirSources {
-    localPrebuildsDir: string;
-    host: string | null;
-    directoryExists: (dir: string) => boolean;
-    resolveManifest: (specifier: string) => string | null;
-}
-export declare function hostPlatformPackage(host: string): string;
-export declare function resolveBackendsDirFrom(sources: BackendsDirSources): string;
-export declare function resolveBackendsDir(): string;

package/lib/backends.js

@@ -1,76 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.PREBUILT_HOSTS = void 0;
-exports.hostPlatformPackage = hostPlatformPackage;
-exports.resolveBackendsDirFrom = resolveBackendsDirFrom;
-exports.resolveBackendsDir = resolveBackendsDir;
-/* eslint-disable @typescript-eslint/no-require-imports -- Bare modules expose CommonJS export shapes. */
-const fs = require("bare-fs");
-const path = require("bare-path");
-/* eslint-enable @typescript-eslint/no-require-imports */
-const PACKAGE_ROOT = path.join(__dirname, "..");
-const PREBUILDS_DIR_NAME = "prebuilds";
-const PLATFORM_ADDON_DIR_NAME = "addon";
-const PLATFORM_PACKAGE_PREFIX = "@qvac/tts-ggml-";
-const PLATFORM_MANIFEST_SUBPATH = "/package";
-const IOS_PLATFORM = "ios";
-const HOST_SEPARATOR = "-";
-exports.PREBUILT_HOSTS = [
-    "linux-x64",
-    "linux-arm64",
-    "darwin-arm64",
-    "darwin-x64",
-    "win32-x64",
-    "android-arm64",
-    "ios-arm64",
-    "ios-arm64-simulator",
-    "ios-x64-simulator",
-];
-function hostPlatformPackage(host) {
-    const platform = host.split(HOST_SEPARATOR)[0];
-    const suffix = platform === IOS_PLATFORM ? IOS_PLATFORM : host;
-    return PLATFORM_PACKAGE_PREFIX + suffix;
-}
-function resolveBackendsDirFrom(sources) {
-    if (sources.directoryExists(sources.localPrebuildsDir)) {
-        return sources.localPrebuildsDir;
-    }
-    return platformPackagePrebuildsDir(sources) ?? sources.localPrebuildsDir;
-}
-function platformPackagePrebuildsDir(sources) {
-    if (!sources.host) {
-        return null;
-    }
-    const manifestPath = sources.resolveManifest(hostPlatformPackage(sources.host) + PLATFORM_MANIFEST_SUBPATH);
-    if (!manifestPath) {
-        return null;
-    }
-    return path.join(path.dirname(manifestPath), PLATFORM_ADDON_DIR_NAME, PREBUILDS_DIR_NAME);
-}
-function resolveBackendsDir() {
-    return resolveBackendsDirFrom({
-        localPrebuildsDir: path.join(PACKAGE_ROOT, PREBUILDS_DIR_NAME),
-        host: currentHost(),
-        directoryExists: safeDirectoryExists,
-        resolveManifest: safeResolveManifest,
-    });
-}
-function currentHost() {
-    return require.addon ? require.addon.host : null;
-}
-function safeDirectoryExists(dir) {
-    try {
-        return fs.existsSync(dir);
-    }
-    catch {
-        return false;
-    }
-}
-function safeResolveManifest(specifier) {
-    try {
-        return require.resolve(specifier);
-    }
-    catch {
-        return null;
-    }
-}