Vocalizer: Local Text-to-Speech for PHP

Vocalizer is a native PHP extension by Akram Zerarka that runs text-to-speech synthesis locally, with no API calls and no runtime dependencies. It embeds two inference backends — sherpa-onnx (ONNX Runtime) and audio.cpp (ggml) — and ships as a prebuilt .so binary, so there's nothing to compile.

Here's what the extension gives you:

• Eight model families, one API — Chatterbox, Supertonic, Piper/VITS, Pocket, Kokoro, Kitten, Matcha, and ZipVoice, auto-detected from the model directory
• Voice cloning — Chatterbox clones any voice from a 3–10 second reference WAV across 23 languages
• Anti-hallucination guard — Chatterbox output is checked for skipped text, loops, and silence, and re-synthesized with a fresh seed when it looks suspicious
• Crash isolation — models run in fork mode by default, so an engine crash is retried and reloaded instead of taking down the PHP worker
• Model cache — models load once per PHP worker (LRU eviction, vocalizer.max_models) and stay warm for subsequent requests
• Async synthesis — speakAsync() returns a job you can wait() on, with per-call timeouts
• WAV or raw PCM output — save to a file, get the WAV as a string, or grab float32 PCM

#One API Across Eight Model Families

Engine::load() points at a model directory and figures out the backend from its contents. Synthesis is a single speak() call:

use Vocalizer\Engine;
 
$engine = Engine::load('/opt/voices/sherpa-onnx-supertonic-3-tts-int8-2026-05-11');
 
$res = $engine->speak('Votre commande est prête.', [
    'lang'       => 'fr',   // required for Supertonic
    'voice'      => 0,      // 0–9 preset voices
    'speed'      => 1.0,
    'timeout_ms' => 30_000,
]);
 
$res->save('/var/www/audio/notice.wav');
echo $res->seconds, " s in ", $res->generationMs, " ms\n";

Which model to load depends on what you're after:

#Voice Cloning with Chatterbox

Chatterbox covers 23 languages with a single ~7.5 GB model and clones a voice from a short reference WAV in the target language:

$engine = Engine::load('/opt/voices/chatterbox', [
    'threads' => 4,
    'opts'    => ['weight_type' => 'f16'],   // default: q8_0
]);
 
$res = $engine->speak('Bonjour, votre commande est prête.', [
    'lang'       => 'fr',
    'reference'  => '/opt/voices/refs/fr.wav',
    'opts'       => [
        'temperature'        => 0.6,
        'repetition_penalty' => 1.2,
        'seed'               => 42,
    ],
    'timeout_ms' => 600_000,
]);
 
echo $res->qualityRetries;   // guard re-syntheses (0 = first output accepted)
$res->save('/tmp/out.wav');

Autoregressive TTS models can skip text, loop, or produce silence, which is where the anti-hallucination guard comes in. Vocalizer checks every Chatterbox output against the text length and signal energy, and re-synthesizes suspicious audio with a new seed — two extra attempts by default, configurable via verify_retries. If every attempt fails, it throws a Vocalizer\Exception rather than returning corrupt audio, which makes a fallback to a faster model straightforward:

try {
    $res = $engine->speak($text, ['lang' => 'fr', 'reference' => $ref]);
} catch (\Vocalizer\Exception $e) {
    $res = Engine::load('/opt/voices/sherpa-onnx-supertonic-3-tts-int8-2026-05-11')
        ->speak($text, ['lang' => 'fr']);
}

#Crash Isolation and Async

Native inference engines can crash, and a segfault inside a PHP extension normally kills the FPM worker with it. Vocalizer's default fork isolation mode runs synthesis in a forked child process, so a crash is caught, retried (up to vocalizer.max_retries), and the model reloaded — surfacing as a Vocalizer\CrashException only when recovery fails. Chatterbox is the exception: its ggml thread pool is not fork-safe, so it always runs in direct mode.

For longer texts, speakAsync() moves synthesis off the request path:

$job = $engine->speakAsync($paragraph);
$res = $job->wait(30_000) ?? throw new RuntimeException('still running');

Behavior is tuned through php.ini directives: vocalizer.isolation (fork vs. direct), vocalizer.timeout_ms, vocalizer.max_models for the per-worker model cache, and vocalizer.max_concurrency for the async pool. One production note from the README worth repeating: model RAM is per FPM worker, and Chatterbox alone needs several GB.

#Installation

Vocalizer requires Linux x86-64 (glibc ≥ 2.28) and PHP 8.4 or 8.5 NTS — Alpine/musl, ARM, and ZTS builds are not supported. The install script downloads the prebuilt extension (~44 MB) and verifies it via SHA256:

curl -fsSL https://raw.githubusercontent.com/akramzerarka/vocalizer/main/install.sh | bash

Models are downloaded separately with the bundled script:

./scripts/download-model.sh chatterbox                                    # ~7.5 GB
./scripts/download-model.sh sherpa-onnx-supertonic-3-tts-int8-2026-05-11  # ~120 MB
./scripts/download-model.sh vits-piper-en_US-amy-low                      # ~65 MB

The extension is MIT-licensed and statically links its dependencies, including sherpa-onnx (Apache-2.0), audio.cpp/ggml (MIT), ONNX Runtime (MIT), and espeak-ng (GPL-3.0 phonemization data).

You can find the full API reference, configuration details, and model catalog on GitHub.