使用用户词典，你可以将专有名词和专业术语的读音注册到官方 VOICEVOX 引擎。在客户端模式下，Laravel 侧不保存词典，而是直接使用所连接的官方引擎所管理的用户词典 API。
客户端模式的用户词典通过 Voicevox Facade 操作。内部会向官方 VOICEVOX 引擎的 /user_dict、/user_dict_word、/import_user_dict 发送 HTTP 请求。
官方引擎的词典数据按 OS 保存在用户目录。VOICEVOX 应用（产品版）macOS 构建版通常保存在以下位置。
~/Library/Application Support/voicevox-engine/user_dict.json
docker run --rm 那样每次都创建临时容器，容器结束时词典会丢失。若需要可靠地持久化词典，请通过 Docker volume 挂载容器内的用户目录。
它与原生模式的 storage/voicevox/user_dict.json 是分开管理的。Laravel 侧的 config('voicevox.core.user_dict') 不会在客户端模式下使用。
前置准备
启动官方 VOICEVOX 引擎。
docker pull voicevox/voicevox_engine:cpu-latest
docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
VOICEVOX_URL 修改连接地址。
VOICEVOX_URL=http://127.0.0.1:50021
基本使用
添加词
通过 Voicevox::addWord() 注册词汇。
use Revolution\Voicevox\Voicevox;
$uuid = Voicevox::addWord(
surface: 'Laravel',
pronunciation: 'ララベル',
accentType: 0,
);
// 客户端模式下会返回带 "-" 的 UUID
// 例如："a1b2c3d4-0000-0000-0000-000000000000"
| 参数 | 类型 | 说明 |
|---|
surface | string | 表记（实际的单词字符串） |
pronunciation | string | 读音（仅片假名） |
accentType | int | 重音型（0 = 平板，1 以上 = 重音位置） |
wordType | string|null | 词类（COMMON_NOUN、PROPER_NOUN、VERB、ADJECTIVE、SUFFIX） |
priority | int|null | 优先级 |
获取所有词
可获取所有已注册的词。
use Revolution\Voicevox\Voicevox;
$words = Voicevox::userDict();
/*
[
"a1b2c3d4-0000-0000-0000-000000000000" => [
"surface" => "Laravel",
"pronunciation" => "ララベル",
"accent_type" => 0,
"word_type" => "COMMON_NOUN",
"priority" => 5,
],
...
]
*/
更新词
使用添加时返回的 UUID 进行更新。
use Revolution\Voicevox\Voicevox;
Voicevox::updateWord(
wordUuid: 'a1b2c3d4-0000-0000-0000-000000000000',
surface: 'Laravel',
pronunciation: 'ラレベル',
accentType: 1,
);
删除词
use Revolution\Voicevox\Voicevox;
Voicevox::deleteWord('a1b2c3d4-0000-0000-0000-000000000000');
导入词典
可以导入符合官方引擎用户词典格式的数组。override: false（默认）会保留现有的词，导入新增词。
use Revolution\Voicevox\Voicevox;
$words = json_decode(file_get_contents('other_user_dict.json'), true);
Voicevox::importUserDict($words, override: false);
// override: true 时会替换现有词典
Voicevox::importUserDict($words, override: true);
Voicevox::userDict() 的结果保存为 JSON。
$json = json_encode(Voicevox::userDict(), JSON_PRETTY_PRINT | JSON_UNESCAPED_UNICODE);
file_put_contents('exported_user_dict.json', $json);
注册词典后的语音合成
注册到用户词典中的词，在官方引擎进行语音合成时会自动参考。
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');
与引擎 API 的对应关系
Voicevox Facade 的各方法与官方引擎的 API 相对应。
| Laravel | 官方引擎 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 |
与原生模式的区别
| 项目 | 客户端模式 | 原生模式 |
|---|
| 使用方式 | Voicevox Facade | dict() helper |
| 保存位置 | 官方引擎的用户目录 | Laravel 的 storage/voicevox/user_dict.json |
| macOS 示例 | ~/Library/Application Support/voicevox-engine/user_dict.json | storage/voicevox/user_dict.json |
| 添加时的 UUID | 带 - | Core 返回时不带 - |
| 引擎进程 | 需要 | 不需要（需要 FFI） |
注意事项
pronunciation 请使用片假名指定。不能使用平假名或汉字。
- 客户端模式下会更新官方引擎侧的词典。不会保存到 Laravel 项目的
storage 中。
- 使用
docker run --rm 等每次创建临时容器时，容器结束时词典会丢失。
- 添加时返回的 UUID 是
a1b2c3d4-0000-0000-0000-000000000000 这样带连字符的格式。
故障排查
词未生效
- 请确认官方 VOICEVOX 引擎已启动。
- 请确认
VOICEVOX_URL 指向正确的连接地址。
- 请确认读音是否为片假名。
- 请确认没有在 Docker 中重新启动到另一个容器。
不清楚词典文件的位置
在 macOS 构建版中请确认以下位置。
~/Library/Application Support/voicevox-engine/user_dict.json
