Skip to main content
使用預設集功能,可將常用的語音合成參數組合儲存於官方 VOICEVOX 引擎並重複使用。在 Client 模式下,Laravel 端不會儲存預設集,而是使用連線目標官方引擎所管理的預設集 API。

概觀

Client 模式的預設集透過 Voicevox Facade 操作。內部會對官方 VOICEVOX 引擎的 /presets/add_preset/update_preset/delete_preset/audio_query_from_preset 發送 HTTP 請求。 官方引擎的預設集以 presets.yaml 儲存於各 OS 的使用者區。VOICEVOX 應用(產品版)macOS 的 build 版通常儲存於下列位置。
若以 Docker 啟動官方引擎,也會儲存於容器內的使用者區。只要繼續使用同一個容器,即使重啟資料也會維持。但若使用 docker run --rm 之類每次建立臨時容器,容器結束時預設集會遺失。若要確實持久化預設集,請以 Docker volume 掛載容器內的使用者區。 與 Native 模式的 storage/voicevox/presets.json 為分開管理。Laravel 端的 config('voicevox.core.presets') 不會用於 Client 模式。

事前準備

啟動官方 VOICEVOX 引擎。
連線目標可透過 VOICEVOX_URL 變更。

預設集結構

Client 模式收發的預設集為對應官方引擎 API schema 的陣列。

基本用法

建立預設集

可透過 Voicevox::addPreset() 建立預設集。在官方引擎中,id 指定為 0 會分配未使用的 ID。

取得所有預設集

更新預設集

刪除預設集

使用預設集進行語音合成

talkFromPreset()

Voicevox::talkFromPreset() 會使用官方引擎的 /audio_query_from_preset,建立已套用預設集的 TalkAudioQuery

audioQueryFromPreset()

若只想取得合成前的 audio query 陣列,可使用 audioQueryFromPreset()

使用 tap() 進行額外調整

從預設集建立的 TalkAudioQuery 也可以像一般的 Voicevox::talk() 一樣,透過 tap() 調整。

與 Engine API 的對應

Voicevox Facade 的各方法對應於官方引擎的 API。

與 Native 模式的差異

實用範例

旁白用

快速對話用

參數詳解

  • 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(結尾靜音,秒)

注意事項

在 Client 模式下更新的是官方引擎端的 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 的 build 版請確認以下位置。
Docker 中會儲存於官方引擎的使用者區(容器內)。若需持久化,請將容器內的使用者區以 Docker volume 掛載。

不知道 speaker_uuid

可從 speaker 清單取得 UUID。
最後修改於 2026年8月2日