Skip to main content
The user dictionary lets you register custom readings for proper nouns and technical terms with the official VOICEVOX engine. In client mode, the dictionary is managed entirely by the connected official engine — Laravel does not store dictionary data locally.

​
Overview

The client mode user dictionary is operated through the Voicevox facade. Internally it sends HTTP requests to the official VOICEVOX engine endpoints /user_dict, /user_dict_word, and /import_user_dict. The official engine stores dictionary data in the OS user area. On macOS (VOICEVOX app product build), the default path is: 
~/Library/Application Support/voicevox-engine/user_dict.json
When running the official engine via Docker, data is stored inside the container’s user area. Data persists across container restarts as long as you reuse the same container. However, when creating a temporary container each time with docker run --rm, the dictionary is lost when the container stops. Use a Docker volume to mount the container’s user area if you need persistence. This is separate from the native mode storage/voicevox/user_dict.json. The Laravel config('voicevox.core.user_dict') setting is not used in client mode.

​
Prerequisites

Start the official VOICEVOX engine. 
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
The connection URL can be changed with VOICEVOX_URL. 
VOICEVOX_URL=http://127.0.0.1:50021

​
Basic usage

​
Add a word

Use Voicevox::addWord() to register a word. 
use Revolution\Voicevox\Voicevox;

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// In client mode, a UUID with hyphens is returned
// e.g. "a1b2c3d4-0000-0000-0000-000000000000"

​
Parameters

ParameterTypeDescription
surfacestringWritten form of the word
pronunciationstringReading in Katakana only
accentTypeintAccent type (0 = flat, 1+ = accent position)
wordTypestring|nullPart of speech (COMMON_NOUN, PROPER_NOUN, VERB, ADJECTIVE, SUFFIX)
priorityint|nullPriority

​
Get all words

use Revolution\Voicevox\Voicevox;

$words = Voicevox::userDict();

/*
[
    "a1b2c3d4-0000-0000-0000-000000000000" => [
        "surface" => "Laravel",
        "pronunciation" => "ララベル",
        "accent_type" => 0,
        "word_type" => "COMMON_NOUN",
        "priority" => 5,
    ],
    ...
]
*/

​
Update a word

Specify the UUID returned when the word was added. 
use Revolution\Voicevox\Voicevox;

Voicevox::updateWord(
    wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);

​
Delete a word

use Revolution\Voicevox\Voicevox;

Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000');

​
Import dictionary data

Import an array in the official engine user dictionary format. With override: false (default), existing words are kept and imported words are added. 
use Revolution\Voicevox\Voicevox;

$words = json_decode(file_get_contents('other_user_dict.json'), true);

Voicevox::importUserDict($words, override: false);

// override: true replaces the existing dictionary
Voicevox::importUserDict($words, override: true);
To export the dictionary, save the result of Voicevox::userDict() as JSON. 
$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);

file_put_contents('exported_user_dict.json', $json);

​
Synthesize after dictionary registration

Words registered in the user dictionary are referenced automatically during synthesis. 
use Revolution\Voicevox\Voicevox;

Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

$response = Voicevox::talk('Laravelで開発するのは楽しいです', id: 1)->generate(id: 1);

$response->storeAs('client', 'laravel.wav');

​
Engine API mapping

Each Voicevox facade method maps to an official engine API endpoint.
LaravelOfficial engine API
Voicevox::userDict()GET /user_dict
Voicevox::addWord()POST /user_dict_word
Voicevox::updateWord()PUT /user_dict_word/{word_uuid}
Voicevox::deleteWord()DELETE /user_dict_word/{word_uuid}
Voicevox::importUserDict()POST /import_user_dict

​
Differences from native mode

ItemClient modeNative mode
APIVoicevox facadedict() helper
StorageOfficial engine user areaLaravel storage/voicevox/user_dict.json
macOS example~/Library/Application Support/voicevox-engine/user_dict.jsonstorage/voicevox/user_dict.json
UUID format on addWith hyphensWithout hyphens (from Core)
Engine processRequiredNot required (FFI required)

​
Notes

Set pronunciation in Katakana only. Hiragana and Kanji are not supported.
  • In client mode, the official engine dictionary is updated. Nothing is stored in your Laravel project’s storage.
  • With docker run --rm, the dictionary is lost when the container exits.
  • The UUID returned on add uses the hyphenated format: a1b2c3d4-0000-0000-0000-000000000000.

​
Troubleshooting

​
Word updates are not reflected

  1. Confirm the official VOICEVOX engine is running.
  2. Check that VOICEVOX_URL points to the correct engine.
  3. Verify that the reading is in Katakana.
  4. Check whether a different Docker container was started.

​
Check dictionary file path

On the macOS product build, check: 
~/Library/Application Support/voicevox-engine/user_dict.json
In Docker, the dictionary is inside the container’s user area. Mount that path as a Docker volume if persistence is required.
Last modified on May 26, 2026