프리셋 기능을 사용하면 자주 쓰는 음성 합성 파라미터 조합을 공식 VOICEVOX 엔진에 저장해 재사용할 수 있습니다. 클라이언트 모드에서는 Laravel 측에 프리셋을 저장하지 않고, 연결 대상인 공식 엔진이 관리하는 프리셋 API를 이용합니다.
클라이언트 모드의 프리셋은 Voicevox 파사드에서 조작합니다. 내부에서는 공식 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, // 스타일 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()
음성 합성 전의 오디오 쿼리 배열만 획득하고 싶은 경우에는 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);
Engine API와의 대응
Voicevox 파사드의 각 메서드는 공식 엔진의 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 파사드 | preset() / talk() 헬퍼 |
| 저장 형식 | 공식 엔진의 presets.yaml | Laravel의 presets.json |
| macOS의 예 | ~/Library/Application Support/voicevox-engine/presets.yaml | storage/voicevox/presets.json |
| 음성 쿼리 생성 | 공식 엔진의 /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()으로 만든 쿼리를 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;
}
