使用预设功能，你可以将常用的语音合成参数组合保存到官方 VOICEVOX 引擎中并复用。在客户端模式下，Laravel 侧不会保存预设，而是使用所连接的官方引擎所管理的预设 API。
客户端模式的预设通过 Voicevox Facade 操作。内部会向官方 VOICEVOX 引擎的 /presets、/add_preset、/update_preset、/delete_preset、/audio_query_from_preset 发送 HTTP 请求。
官方引擎的预设按 OS 保存在用户目录下的 presets.yaml 中。VOICEVOX 应用（产品版）macOS 构建版通常保存在以下位置。
~/Library/Application Support/voicevox-engine/presets.yaml
docker run --rm 那样每次都创建临时容器，容器结束时预设会丢失。若需要可靠地持久化预设，请使用 Docker volume 挂载容器内的用户目录。
它与原生模式的 storage/voicevox/presets.json 是分开管理的。Laravel 侧的 config('voicevox.core.presets') 不会在客户端模式下使用。
前置准备
启动官方 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
预设的结构
客户端模式下收发的预设是与官方引擎 API 结构一致的数组。
[
'id' => 1, // 预设 ID（整数）
'name' => 'ゆっくり', // 预设名称
'speaker_uuid' => 'uuid', // 说话人 UUID（字符串）
'style_id' => 1, // Style ID（整数）
'speedScale' => 0.8, // 语速
'pitchScale' => 0.0, // 音高
'intonationScale' => 1.0, // 抑扬
'volumeScale' => 1.0, // 音量
'prePhonemeLength' => 0.1, // 起始静音
'postPhonemeLength' => 0.1, // 结束静音
]
基本使用
创建预设
通过 Voicevox::addPreset() 创建预设。在官方引擎中，将 id 指定为 0 会自动分配一个未使用的 ID。
use Revolution\Voicevox\Voicevox;
$id = Voicevox::addPreset([
'id' => 0,
'name' => 'ゆっくり丁寧',
'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
'style_id' => 1,
'speedScale' => 0.8,
'pitchScale' => 0.0,
'intonationScale' => 1.2,
'volumeScale' => 1.0,
'prePhonemeLength' => 0.1,
'postPhonemeLength' => 0.1,
]);
echo $id; // 例如：1
获取所有预设
use Revolution\Voicevox\Voicevox;
$presets = Voicevox::presets();
/*
[
[
"id" => 1,
"name" => "ゆっくり丁寧",
"speaker_uuid" => "7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff",
"style_id" => 1,
"speedScale" => 0.8,
...
],
...
]
*/
更新预设
use Revolution\Voicevox\Voicevox;
$id = Voicevox::updatePreset([
'id' => 1,
'name' => 'ゆっくりはっきり',
'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
'style_id' => 1,
'speedScale' => 0.7,
'pitchScale' => 0.0,
'intonationScale' => 1.5,
'volumeScale' => 1.0,
'prePhonemeLength' => 0.1,
'postPhonemeLength' => 0.1,
]);
删除预设
use Revolution\Voicevox\Voicevox;
Voicevox::deletePreset(1);
使用预设进行语音合成
talkFromPreset()
Voicevox::talkFromPreset() 使用官方引擎的 /audio_query_from_preset，创建已应用预设的 TalkAudioQuery。
use Revolution\Voicevox\Voicevox;
$response = Voicevox::talkFromPreset('プリセットを使うのだ', presetId: 1)
->generate(id: 1);
$response->storeAs('client', 'preset-talk.wav');
audioQueryFromPreset()
如果只想获取语音合成前的 audio query 数组，可以使用 audioQueryFromPreset()。
use Revolution\Voicevox\Voicevox;
$audioQuery = Voicevox::audioQueryFromPreset(
text: 'プリセットのクエリだけ作るのだ',
presetId: 1,
);
$audioQuery['speedScale'] = 1.1;
使用 tap() 追加调整
由预设创建的 TalkAudioQuery 也可以像普通的 Voicevox::talk() 一样通过 tap() 进行调整。
use Revolution\Voicevox\Client\TalkAudioQuery;
use Revolution\Voicevox\Voicevox;
$response = Voicevox::talkFromPreset('少し速く読むのだ', presetId: 1)
->tap(function (TalkAudioQuery $talk) {
$talk->audioQuery['speedScale'] = 1.2;
})
->generate(id: 1);
与引擎 API 的对应关系
Voicevox Facade 的各方法对应官方引擎的 API。
| Laravel | 官方引擎 API |
|---|
Voicevox::presets() | GET /presets |
Voicevox::addPreset() | POST /add_preset |
Voicevox::updatePreset() | POST /update_preset |
Voicevox::deletePreset() | POST /delete_preset |
Voicevox::audioQueryFromPreset() | POST /audio_query_from_preset |
Voicevox::talkFromPreset() | POST /audio_query_from_preset + POST /synthesis |
与原生模式的区别
| 项目 | 客户端模式 | 原生模式 |
|---|
| 使用方式 | Voicevox Facade | preset() / talk() helper |
| 保存格式 | 官方引擎的 presets.yaml | Laravel 的 presets.json |
| macOS 示例 | ~/Library/Application Support/voicevox-engine/presets.yaml | storage/voicevox/presets.json |
| audio query 生成 | 官方引擎的 /audio_query_from_preset | Laravel 侧的原生实现 |
| 引擎进程 | 需要 | 不需要（需要 FFI） |
实用示例
用于旁白
use Revolution\Voicevox\Voicevox;
Voicevox::addPreset([
'id' => 0,
'name' => 'ナレーション',
'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
'style_id' => 1,
'speedScale' => 1.0,
'pitchScale' => -0.05,
'intonationScale' => 0.8,
'volumeScale' => 1.0,
'prePhonemeLength' => 0.15,
'postPhonemeLength' => 0.15,
]);
用于快速讲话
Voicevox::addPreset([
'id' => 0,
'name' => '早口',
'speaker_uuid' => '388f246b-8c41-4ac1-8e2d-5d79f3ff56d9',
'style_id' => 3,
'speedScale' => 1.5,
'pitchScale' => 0.05,
'intonationScale' => 1.3,
'volumeScale' => 1.0,
'prePhonemeLength' => 0.05,
'postPhonemeLength' => 0.05,
]);
参数详情
speedScale：0.5 ～ 2.0（语速）pitchScale：-0.15 ～ 0.15（音高）intonationScale：0.0 ～ 2.0（抑扬）volumeScale：0.0 ～ 2.0（音量）prePhonemeLength：0.0 ～ 1.5（起始静音・秒）postPhonemeLength：0.0 ～ 1.5（结束静音・秒）
注意事项
客户端模式下会更新官方引擎侧的 presets.yaml。不会保存到 Laravel 项目的 storage。
- 使用
docker run --rm 等每次创建临时容器时，容器结束时预设会丢失。
- 请同时包含
speaker_uuid 和 style_id。
- 对
talkFromPreset() 创建的 query 调用 generate(id:) 时，通常应指定与预设的 style_id 相同的 ID。
故障排查
无法获取预设
- 请确认官方 VOICEVOX 引擎已启动。
- 请确认
VOICEVOX_URL 指向正确的连接地址。
- 请确认没有在 Docker 中重新启动到另一个容器。
不清楚预设文件的位置
在 macOS 构建版中请确认以下位置。
~/Library/Application Support/voicevox-engine/presets.yaml
不清楚 speaker_uuid
可以从说话人列表中获取 UUID。
use Revolution\Voicevox\Voicevox;
$speakers = Voicevox::speakers();
foreach ($speakers as $speaker) {
echo $speaker['name'].': '.$speaker['speaker_uuid'].PHP_EOL;
}
