Native mode - User Dictionary - VOICEVOX for Laravel

Register, update, and import custom readings in native mode with the VOICEVOX for Laravel user dictionary.

What the user dictionary is

The user dictionary lets you teach VOICEVOX how to read proper nouns and technical terms. Registered words are applied automatically during synthesis.

Overview

The Laravel VOICEVOX user dictionary feature is a native implementation based on VOICEVOX Core UserDict. Dictionary data is persisted as JSON at storage/voicevox/user_dict.json.

Storage is independent from the official VOICEVOX engine. Words registered from Laravel are not synced to the official engine (and vice versa).

Configuration

By default, entries are saved to storage/voicevox/user_dict.json. To use another path, update config/voicevox.php.

// config/voicevox.php

return [
    'core' => [
        'user_dict' => storage_path('voicevox/user_dict.json'),
    ],
];

Basic usage

Add a word

use function Revolution\Voicevox\dict;

$uuid = dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

// Returns UUID without hyphens
// e.g. "550e8400e29b41d4a716446655440000"

Parameters

• surface (required): written form
• pronunciation (required): reading in Katakana only
• accentType (required): accent type (0 = flat, 1+ = accent position)
• wordType (optional): part of speech (COMMON_NOUN, PROPER_NOUN, VERB, ADJECTIVE, SUFFIX)
• priority (optional): priority (default 5)

Update a word

use function Revolution\Voicevox\dict;

dict()->update(
    wordUuid: '550e8400-e29b-41d4-a716-446655440000',
    surface: 'Laravel',
    pronunciation: 'ラレベル',
    accentType: 1,
);

Delete a word

use function Revolution\Voicevox\dict;

dict()->delete('550e8400-e29b-41d4-a716-446655440000');

Get all words

use function Revolution\Voicevox\dict;

$words = dict()->all();
// or
$words = dict()->toArray();

Import dictionary data

use function Revolution\Voicevox\dict;

$json = file_get_contents('other_user_dict.json');
dict()->import($json, override: false);

dict()->import($json, override: true);

Export dictionary data

use function Revolution\Voicevox\dict;

$json = dict()->toJson();
file_put_contents('exported_dict.json', $json);

Access via Engine API

If Laravel VOICEVOX Engine API is running, you can operate the user dictionary over HTTP. It still uses the native dictionary (no fallback to official engine dictionary).

Get all words

curl http://localhost:50513/user_dict

Add a word

curl -X POST "http://localhost:50513/user_dict_word?surface=Laravel&pronunciation=ララベル&accent_type=0"

Update a word

curl -X PUT "http://localhost:50513/user_dict_word/{uuid}?surface=Laravel&pronunciation=ラレベル&accent_type=1"

Delete a word

curl -X DELETE "http://localhost:50513/user_dict_word/{uuid}"

Import dictionary data

curl -X POST "http://localhost:50513/import_user_dict?override=false" \
  -H "Content-Type: application/json" \
  -d @other_dict.json

Set override=true to remove all existing entries before importing.

Synthesize after dictionary registration

Words in the user dictionary are referenced automatically during synthesis.

use function Revolution\Voicevox\{dict, talk};

dict()->add(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 0,
);

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

Notes

Set pronunciation in Katakana only. Hiragana and Kanji are not supported.

• Laravel and official VOICEVOX engine dictionaries are managed separately.
• Add, update, and delete operations are saved to JSON immediately.
• If you are unsure about accent, try 0 (flat) first.

Troubleshooting

Word updates are not reflected

1. Check write permissions for the storage directory.
2. Confirm storage/voicevox/user_dict.json exists and is valid.
3. Verify Katakana spelling.

Check dictionary file path

$path = config('voicevox.core.user_dict');
echo $path;

Reset the dictionary

rm storage/voicevox/user_dict.json

$path = config('voicevox.core.user_dict');
if (file_exists($path)) {
    unlink($path);
}