跳转到主要内容
使用预设功能,你可以将常用的语音合成参数组合保存到官方 VOICEVOX 引擎中并复用。在客户端模式下,Laravel 侧不会保存预设,而是使用所连接的官方引擎所管理的预设 API。

概览

客户端模式的预设通过 Voicevox Facade 操作。内部会向官方 VOICEVOX 引擎的 /presets/add_preset/update_preset/delete_preset/audio_query_from_preset 发送 HTTP 请求。 官方引擎的预设按 OS 保存在用户目录下的 presets.yaml 中。VOICEVOX 应用(产品版)macOS 构建版通常保存在以下位置。
通过 Docker 启动官方引擎时,也保存在容器内的用户目录中。只要一直使用同一个容器,即使重启数据也会保留。但如果像 docker run --rm 那样每次都创建临时容器,容器结束时预设会丢失。若需要可靠地持久化预设,请使用 Docker volume 挂载容器内的用户目录。 它与原生模式的 storage/voicevox/presets.json 是分开管理的。Laravel 侧的 config('voicevox.core.presets') 不会在客户端模式下使用。

前置准备

启动官方 VOICEVOX 引擎。
可通过 VOICEVOX_URL 修改连接地址。

预设的结构

客户端模式下收发的预设是与官方引擎 API 结构一致的数组。

基本使用

创建预设

通过 Voicevox::addPreset() 创建预设。在官方引擎中,将 id 指定为 0 会自动分配一个未使用的 ID。

获取所有预设

更新预设

删除预设

使用预设进行语音合成

talkFromPreset()

Voicevox::talkFromPreset() 使用官方引擎的 /audio_query_from_preset,创建已应用预设的 TalkAudioQuery

audioQueryFromPreset()

如果只想获取语音合成前的 audio query 数组,可以使用 audioQueryFromPreset()

使用 tap() 追加调整

由预设创建的 TalkAudioQuery 也可以像普通的 Voicevox::talk() 一样通过 tap() 进行调整。

与引擎 API 的对应关系

Voicevox Facade 的各方法对应官方引擎的 API。

与原生模式的区别

实用示例

用于旁白

用于快速讲话

参数详情

  • 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_uuidstyle_id
  • talkFromPreset() 创建的 query 调用 generate(id:) 时,通常应指定与预设的 style_id 相同的 ID。

故障排查

无法获取预设

  1. 请确认官方 VOICEVOX 引擎已启动。
  2. 请确认 VOICEVOX_URL 指向正确的连接地址。
  3. 请确认没有在 Docker 中重新启动到另一个容器。

不清楚预设文件的位置

在 macOS 构建版中请确认以下位置。
在 Docker 中会保存在官方引擎的用户目录(容器内)。如果需要持久化,请通过 Docker volume 挂载容器内的用户目录。

不清楚 speaker_uuid

可以从说话人列表中获取 UUID。
最后修改于 2026年7月18日