Laravel Voicevox Laravel Package

Getting Started

invokable/laravel-voicevox wraps VOICEVOX Core — a Japanese text-to-speech engine — behind a Laravel facade, so you can synthesize speech in-process (FFI) instead of running the VOICEVOX ENGINE HTTP server. As of 0.2.0 the bundled/expected core is v0.17.0.

Minimal path to first audio:

1. composer require invokable/laravel-voicevox
2. Publish the config (php artisan vendor:publish --tag="voicevox-config") and read config/voicevox.php first — it is where the shared library path, ONNX Runtime path, and model (.vvm) directory are declared. Almost every failure traces back to these three paths.
3. Install the native pieces out-of-band: the voicevox_core shared library, ONNX Runtime, and at least one voice model file. These are not Composer dependencies and are not shipped by the package.
4. Confirm ffi.enable=true in the relevant php.ini (CLI and FPM — they are different files).
5. Sanity-check with php artisan tinker: resolve the facade, list available speakers/styles, then synthesize a short string to a WAV.

First real use case: an Artisan command that takes a string plus a style/speaker identifier and writes a WAV to a storage disk. Keep it a command rather than a controller — model loading is slow and you do not want it on a web request the first time you test.

Implementation Patterns

Wrap the facade in your own service. Do not scatter Voicevox:: calls through controllers. A thin SpeechSynthesizer class that owns style selection, parameter presets, output formatting, and error handling gives you one place to swap engines and one place to mock in tests.

Treat synthesis as a two-stage operation. VOICEVOX conceptually works as audio query (accent phrases, pitch, speed, intonation — the JSON-ish intermediate representation) then synthesis (query + style → waveform). Use the two-stage form whenever you need to tweak speedScale, pitchScale, intonationScale, volumeScale, or pause length; the one-shot convenience call is for prototyping only.

Push generation to a queue. A job that takes (text, styleId, params, diskPath) and dispatches on a voicevox queue is the standard production shape. Long input blocks a worker for seconds; on a web request you will hit max_execution_time before you hit any package limit. Return the stored path, not raw bytes.

Cache aggressively by content hash. Key on sha256(text + styleId + serialized params + coreVersion). TTS output is fully deterministic for a given core/model version, and re-synthesizing identical UI strings is pure waste. Put the files on a disk with a public URL so the frontend can just <audio src>.

Build a small style registry. Speaker/style IDs are magic integers. Back them with an enum or config array (narration, assistant, chime) so a core upgrade that renumbers IDs is a one-file change rather than a grep across the codebase.

Use the user dictionary for domain vocabulary. Product names, acronyms, and proper nouns will be mispronounced with default accents. Registering readings once at boot (or in a seeder) beats string-hacking the input text with phonetic kana.

Batch and stream where it fits. For long articles, split on 。/！/？ and newlines, synthesize per sentence, and concatenate — this also gives you per-sentence caching and lets you stream playback while later chunks render. For HTTP delivery, respond with audio/wav and Content-Disposition; if you need seekable output, convert to MP3/AAC in a post-step (the package gives you WAV).

Integration tips: keep a php artisan voicevox:health command that verifies library load, model discovery, and a zero-length round trip — run it in CI and in your container entrypoint. In tests, bind a fake synthesizer to the container so the suite never touches FFI.

Gotchas and Tips

• FFI is a hard gate. Shared hosting, many slim Docker base images, and some hardened PHP builds ship with FFI disabled or ffi.enable=preload. Check with php -i | grep ffi in the exact SAPI that runs your app. This is the number-one reason the package "doesn't work."
• Pin the native versions together. 0.2.0 moves to core v0.17.0. The voicevox_core shared library, the ONNX Runtime build, and the .vvm model files must all be compatible with that core version. Mixing an older .so with a newer model produces opaque load errors at construction time, not at call time — so surface the exception with the resolved paths in the message.
• Model/style IDs shift across core versions. Treat every upgrade (this one included) as potentially breaking: re-list available styles and re-verify your hardcoded IDs before deploying. Models can be added or retired between cores.
• Model load is expensive; process memory is sticky. Expect multi-second cold start and hundreds of MB resident. Under Octane or a long-lived queue worker the models stay loaded (good), but under php-fpm you pay per request unless you offload. Set memory_limit accordingly and never load multiple model sets casually.
• Do not feed unbounded text. Very long input is slow and memory-hungry; chunk it yourself rather than relying on the engine. Also normalize/validate encoding — non-UTF-8 input yields garbled or empty audio rather than an exception.
• Debugging order of operations: (1) does php -i show FFI enabled, (2) does the config path resolve to an existing file (realpath), (3) does a known-good model load, (4) does a one-character string synthesize. Only then look at your own parameters.
• Extension points to prefer: the config file for paths and defaults, a container binding for your synthesizer service, and a custom Artisan command for operations. Avoid subclassing package internals — the surface is small and still pre-1.0.
• Licensing is a real production concern. VOICEVOX voice models carry per-character terms of use, typically requiring credit (e.g. "VOICEVOX:〈character name〉") wherever the audio is published. Bake the credit string into your output metadata/UI now; retrofitting it across a shipped product is painful.
• Windows and CI: native library installation is the fragile part of any CI pipeline. Run the health command as a smoke test, and mark FFI-dependent tests as skipped when the native pieces are absent so contributors without the runtime can still work.