feat(tts): integrate LavaSR audio enhancer as opt-in post-processing

[sharmaraju352]

🎯 What problem does this PR solve?

• TTS addon outputs audio at native engine sample rates (Chatterbox 24kHz, Supertonic 44.1kHz) with no way to improve quality beyond what the engine produces
• Users have no control over output sample rate; higher-quality applications (48kHz, cleaner output) require manual post-processing outside QVAC

📝 How does it solve it?

Integrates LavaSR, a lightweight neural speech enhancement model, as an opt-in post-processing step with three independent config flags:

• enhance (bool) — runs Vocos-based neural bandwidth extension to 48kHz (2 ONNX sessions, ~55MB)
• denoise (bool) — runs UL-UNAS denoiser at 16kHz before enhancement (~1.7MB, 1 ONNX session)
• outputSampleRate (int) — sets final output rate (must be in 8000–192000 range); with enhance, upscales neurally first then resamples conventionally

Pipeline: Engine synthesize → [denoise at 16kHz] → [enhance to 48kHz] → [resample to target rate]

All flags default to off — zero performance cost and full backward compatibility.

C++ implementation:

• Pure DSP utilities (Lanczos resampler, radix-2 FFT, STFT/ISTFT, Slaney mel filterbank, spectral crossover merge) — no ML dependency, tested in isolation
• LavaSR ONNX wrappers (denoiser with chunked overlap-add, enhancer with backbone + spec head + FastLR merge)
• TTSModel::postProcess() integration after engine synthesize(), with lazy session loading for per-job toggles

JS bridge: enhance/denoise/outputSampleRate + individual model paths (backbonePath, specHeadPath, denoiserPath) flow through AddonJs.hpp → index.js → index.d.ts

Nice-to-haves included:

• sampleRate exposed in JS output callback (data.sampleRate) and runtimeStats
• Per-job enhance/denoise/outputSampleRate toggle via run() input (lazy ONNX session loading on first use)
• Benchmark tests: enhancer ~22x realtime, denoiser ~48x realtime on Apple Silicon

🧪 How was it tested?

C++ (187 total, 183 pass, 4 skip for missing Supertonic models):

• 43 new unit tests — DSP round-trip validation (FFT, STFT/ISTFT, resampler, mel filterbank, spectral merge), LavaSR wrapper lifecycle, TTSModel config parsing + resampling + per-job toggle + backward compat
• 6 new integration tests with real ONNX models — enhancer/denoiser individually, full Chatterbox→LavaSR pipeline, denoise+enhance combined, enhance+outputSampleRate
• 3 benchmark tests measuring latency at 1s/3s/5s/10s durations
• Zero regressions on all pre-existing tests

JS:

• outputSampleRate resampling test added to addon.test.js (runs in CI without LavaSR models)
• 6 LavaSR integration tests in addon.test.js (Chatterbox+enhance, denoise+enhance, outputSampleRate, enhance+downsample, Supertonic+enhance, backward compat) — all assert sampleRate via callback
• Locally verified: outputSampleRate=16000 produces 16kHz output with sampleRate correctly reported in callback

Manual verification:

• Ran comparison example producing 3 WAV files (raw 24kHz, enhanced 48kHz, denoised+enhanced 48kHz) — enhanced output is audibly clearer

🔌 API Changes

const tts = new ONNXTTS({
  files: {
    tokenizerPath: 'models/chatterbox/tokenizer.json',
    speechEncoderPath: 'models/chatterbox/speech_encoder.onnx',
    embedTokensPath: 'models/chatterbox/embed_tokens.onnx',
    conditionalDecoderPath: 'models/chatterbox/conditional_decoder.onnx',
    languageModelPath: 'models/chatterbox/language_model.onnx',
  },
  referenceAudio,
  config: {
    language: 'en',
    outputSampleRate: 22050, // optional: resample after enhancement (8000–192000)
  },
  // LavaSR enhancement (nested enhancer config)
  enhancer: {
    type: 'lavasr',
    enhance: true,
    denoise: true,
    backbonePath: 'models/lavasr/enhancer_backbone.onnx',
    specHeadPath: 'models/lavasr/enhancer_spec_head.onnx',
    denoiserPath: 'models/lavasr/denoiser_core_legacy_fixed63.onnx',
  },
})

// Per-job toggle (lazy loads ONNX sessions on first use)
await model.run({
  type: 'text',
  input: 'Hello world',
  enhancer: { type: 'lavasr', enhance: true, denoise: false },
  outputSampleRate: 22050, // per-job override
})

// Output callback now includes sampleRate
response.onUpdate(data => {
  console.log(data.outputArray)  // Int16Array
  console.log(data.sampleRate)   // 48000 (if enhanced)
})

New TypeScript interfaces:

interface LavaSREnhancerConfig {
  type: 'lavasr'
  enhance?: boolean
  denoise?: boolean
  backbonePath?: string
  specHeadPath?: string
  denoiserPath?: string
}

type EnhancerConfig = LavaSREnhancerConfig

// Added to ONNXTTSOptions:
interface ONNXTTSOptions {
  enhancer?: EnhancerConfig
  // ...existing fields
}

// Added to ONNXTTSRuntimeConfig:
interface ONNXTTSRuntimeConfig {
  outputSampleRate?: number  // 8000–192000
  // ...existing fields
}

// Per-job run input:
interface TTSRunInput {
  enhancer?: { type: 'lavasr'; enhance?: boolean; denoise?: boolean }
  outputSampleRate?: number
  // ...existing fields
}

---

🔄 CI Run

Latest full CI pipeline: https://github.com/tetherto/qvac/actions/runs/24237672067

[GustavoA1604]

• Need JS linting
• Also I think automatic on-pr run of this PR got broken, please run manually and share results