VOICEVOX Engine: Local HTTP Speech Synthesis with Docker

VOICEVOX Engine's HTTP Service and Intended Users

VOICEVOX Engine solves the server-side part of the VOICEVOX speech system. It is not primarily a desktop application or command-line voice player. The engine runs as an HTTP service, receives Japanese text and synthesis parameters, and returns generated audio. That boundary makes it suitable for an editor, a script, or another application that needs programmatic access to speech output.

The intended users divide into three groups named by the README. People who want speech can download a compatible engine release and use the HTTP API. Contributors work on the engine itself. Developers can incorporate or run its code, subject to the repository's licensing terms. The README separates the VOICEVOX editor from VOICEVOX ENGINE and VOICEVOX CORE, so choosing the wrong component is an easy first mistake. The editor is the user interface; this repository provides the synthesis service behind it.

The API is local by default in the documented examples, with requests sent to `127.0.0.1:50021`. Its Swagger-style interface is available at `/docs` while the engine or editor is running. This design is practical for desktop software and local automation, where an application can start or contact a speech service without depending on a remote SaaS account. The repository does not describe authentication, tenancy, or multi-user isolation for that HTTP interface, so an internet-facing deployment would require a separate security and access-control review.

From Text to Audio Through Two HTTP Stages

The normal synthesis flow has two stages. First, a client posts text to `/audio_query` with a `speaker`. The engine analyzes the text and returns a JSON query containing voice-control data. The client can save and inspect that JSON before synthesis. Second, it posts the query to `/synthesis`, again with a `speaker`, and receives an audio file. Separating query creation from audio generation is the engine's most useful architectural choice for application developers because it exposes an editable intermediate representation.

The `speaker` value is not a display name. According to the README, it must be an `id` returned in style information from the `/speakers` endpoint. The name remains `speaker` for compatibility. A hard-coded value such as `1` in the examples therefore should not be treated as a permanent universal identifier.

The query contains more than text. The README shows editing `speedScale` to change the speaking rate and replacing the `accent_phrases` array derived from `/accent_phrases`. The `audio_query` response also contains a `kana` field in AquesTalk-style notation. Correcting that pronunciation and accent data before sending the final query gives callers direct control over reading rather than forcing them to accept automatic analysis.

For continuous delivery, `/streaming_synthesis` returns portions of the audio while synthesis continues. `segment_length` sets the approximate amount synthesized at once. This can start playback before the complete file exists, but the README warns that too small a value may interrupt playback and that joining audio from separate requests can create an unnatural seam. It also exposes `start_offset`, allowing synthesis to begin at a chosen point. For a complete artifact with natural continuity, the README advises making one synthesis request.

Install and Run the CPU Container

The fastest documented starting point is the CPU image. This path suits a developer who wants to call the API locally and does not want to set up a source environment. The README publishes two maintained image tags: `voicevox/voicevox_engine:cpu-latest` for CPU execution and `voicevox/voicevox_engine:nvidia-latest` for NVIDIA GPU execution.

For the first synthesis, use the CPU commands exactly as documented:

docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest

The container should keep running after the pull. Its HTTP service is then available on port `50021` at `127.0.0.1`. The host binding is limited to the local interface by the quoted address, so this example does not request access from other machines.

With the engine available, create a UTF-8 text file, obtain an audio query, and synthesize a WAV file:

echo -n "こんにちは、音声合成の世界へようこそ" >text.txt

curl -s \
    -X POST \
    "127.0.0.1:50021/audio_query?speaker=1"\
    --get --data-urlencode [email protected] \
    > query.json

curl -s \
    -H "Content-Type: application/json" \
    -X POST \
    -d @query.json \
    "127.0.0.1:50021/synthesis?speaker=1" \
    > audio.wav

The first request should produce `query.json`, and the second should produce `audio.wav`. The documentation states that generated audio uses a sampling rate of 24000 Hz. Some media players may reject that rate, so failure to play the file does not necessarily mean synthesis failed. Validate the file in software that supports 24000 Hz before troubleshooting the HTTP request.

Streaming, Pronunciation, and User Dictionary Controls

Streaming changes when audio reaches the caller rather than the basic analysis flow. The client still creates `query.json` through `/audio_query`, then sends it to `/streaming_synthesis`:

curl -s \
    -H "Content-Type: application/json" \
    -X POST \
    -d @query.json \
    "127.0.0.1:50021/streaming_synthesis?speaker=1&segment_length=0.3" \
    > audio_stream.wav

Here, `segment_length=0.3` requests synthesis in roughly 0.3-second portions. The tradeoff is latency versus continuity. The README says to increase `segment_length` if streamed playback cuts out. Applications that must start at an offset can send `start_offset`, but synthesizing several fragments separately may introduce audible joins.

Pronunciation control works through the query. `/audio_query` returns the engine's selected reading in `kana`, and `/accent_phrases?speaker=1&is_kana=true` returns phrase and accent data for corrected AquesTalk-style input. The client can replace the query's `accent_phrases` content and then submit the modified JSON to `/synthesis`. This is useful for technical terms and names whose automatic reading is wrong. It also places responsibility on the caller: the caller must preserve valid JSON and understand accent notation before submitting changes.

The user dictionary provides a separate persistent customization layer. The API can list dictionary entries with `GET /user_dict`, add words with `POST /user_dict_word`, and update an existing UUID with `PUT /user_dict_word/{word_uuid}`. New entries require a surface form, katakana pronunciation, and integer accent position. The README says creation returns the assigned UUID as a string, while a successful update returns `204 No Content`. Applications should treat UUIDs as server-assigned values and query `/user_dict` when an entry must be modified later.

Source Installation, Dependencies, and Upgrade Boundaries

A direct source installation is a different choice from running a release image. The repository's `pyproject.toml` pins Python to exactly `==3.14.6` and specifies FastAPI, Uvicorn, Pydantic, audio processing libraries, and a Git revision for `pyopenjtalk`. It also contains `uv.lock`, and the `[tool.uv]` section sets `python-preference = "only-managed"`. The README excerpt does not provide a complete source installation tutorial, so it would be misleading to invent a package-manager sequence.

That exact Python requirement is a significant adoption constraint. A developer cannot assume any Python 3 release will satisfy the project. The dependency set also includes platform-specific considerations. `pyhwloc` is declared for Linux and Windows, with a comment that it is not used on macOS because the wheel is unavailable. This helps explain why source setup is not interchangeable across operating systems.

The repository is not archived, and its last push was on 2026-10-02. Recent release names include development and preview identifiers, including `0.26.0-dev`, `0.26.0-preview.1`, and `0.0.0-preview.20260824`. These names indicate multiple release channels, but they do not by themselves establish compatibility with one another. The project version in `pyproject.toml` is still shown as `0.24.0`, with a TODO about automatic version management. An adopter should therefore compare the release artifact, container tag, API behavior, and model resources as a set.

Maintenance cost comes mainly from this environment coupling. Upgrading Python, FastAPI, Pydantic, audio dependencies, or VOICEVOX CORE resources can change more than the Python package itself. The presence of tests, Ruff, mypy, and a locked dependency file indicates engineering support for changes, but upgrade acceptance should still include synthesis and playback checks.

Docker, Release Artifacts, and the Editor Boundary

VOICEVOX Engine has two documented deployment choices. A downloaded release artifact is the route offered to users who simply want a compatible engine, while Docker packages the service as `cpu-latest` or `nvidia-latest`. The choice affects runtime setup. Docker supplies a declared image and a consistent port mapping, whereas the download route expects the user to select an artifact compatible with their platform and run it outside the container workflow.

CPU and NVIDIA images are not interchangeable. The GPU command asks Docker to provide all host GPUs:

docker pull voicevox/voicevox_engine:nvidia-latest
docker run --rm --gpus all -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:nvidia-latest

The README says some GPU environments require adding `--runtime=nvidia` to `docker run`. It describes this as a possible fix for environment-dependent errors, not a universal requirement. Operators should therefore check their NVIDIA container configuration before changing the command.

Compared with VOICEVOX, the editor is the practical alternative for people who want a graphical speech interface rather than an API integration. VOICEVOX can start or work with the engine and provide an editing experience. It does not replace the need to understand the service boundary when software needs custom pronunciations, streamed responses, or dictionary operations. Conversely, this engine does not replace the editor for users who want an interface for selecting and listening to speech.

Licensing also requires direct review. GitHub classifies the repository's licence as custom, while the repository contains both `LICENSE` and `LGPL_LICENSE`. The available text does not explain how those files apply to every distribution or integration scenario. No legal interpretation should be inferred from the file names. Review the applicable `LICENSE` terms before redistributing an engine, container-derived artifact, or bundled application.

Editorial conclusion

VOICEVOX Engine is appropriate for developers building a local or self-controlled Japanese speech service, especially when they need query editing, streaming, or user dictionaries. It is a poor fit for users who only want an editor interface or operators who cannot manage a Python service, GPU runtime, model resources, and custom licence terms. Before adoption, verify the exact release artifact, inspect LICENSE, confirm the target CPU or NVIDIA environment, and test the 24000 Hz output with the playback stack that will consume it.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. VOICEVOX/voicevox_engine on GitHub