프리셋이란
프리셋 기능을 사용하면 자주 쓰는 음성 합성 파라미터 조합을 저장해 재사용할 수 있습니다.
말하기 속도·음높이·억양 등을 함께 관리하면, 여러 음성을 생성할 때도 일관된 품질을 유지하기 쉬워집니다.
storage/voicevox/presets.json에 영속화됩니다.
공식 VOICEVOX 엔진과는 독립된 스토리지를 사용하므로, Laravel 측에서 생성한 프리셋은 공식 엔진 측에는 반영되지 않습니다 (그 반대도 마찬가지입니다).
기본적으로 storage/voicevox/presets.json에 저장됩니다. 다른 경로를 사용하고 싶은 경우 config/voicevox.php에서 변경할 수 있습니다.
// config/voicevox.php
return [
'core' => [
'presets' => storage_path('voicevox/presets.json'),
],
];
프리셋 구조
프리셋은 다음과 같은 구조입니다.
[
'id' => 1, // 프리셋 ID (정수, 자동 채번)
'name' => 'ゆっくり', // 프리셋 이름
'speaker_uuid' => 'uuid', // 스피커 UUID (문자열)
'style_id' => 1, // 스타일 ID (정수)
'speedScale' => 0.8, // 말하기 속도 (0.5 ~ 2.0)
'pitchScale' => 0.0, // 음높이 (-0.15 ~ 0.15)
'intonationScale' => 1.0, // 억양 (0.0 ~ 2.0)
'volumeScale' => 1.0, // 볼륨 (0.0 ~ 2.0)
'prePhonemeLength' => 0.1, // 시작 무음 (0.0 ~ 1.5)
'postPhonemeLength' => 0.1, // 종료 무음 (0.0 ~ 1.5)
]
기본적인 사용법
프리셋 생성
preset() 헬퍼의 add()로 프리셋을 생성할 수 있습니다.
use function Revolution\Voicevox\preset;
$id = preset()->add([
'id' => 0, // 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,
]);
// 자동 채번된 ID가 반환됩니다
echo $id; // 예: 1
전체 프리셋 조회
use function Revolution\Voicevox\preset;
$presets = preset()->all();
프리셋 검색
use function Revolution\Voicevox\preset;
$preset = preset()->find(1);
if ($preset !== null) {
echo $preset['name']; // "ゆっくり丁寧"
}
프리셋 업데이트
use function Revolution\Voicevox\preset;
preset()->update([
'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 function Revolution\Voicevox\preset;
preset()->delete(1);
프리셋을 사용한 음성 합성
talk() 헬퍼 또는 Engine API의 /audio_query_from_preset 엔드포인트를 이용합니다.
talk() 헬퍼
talk(preset:)에 프리셋 ID를 지정합니다. 이때 일반적인 스타일 ID는 무시됩니다.
use function Revolution\Voicevox\talk;
$response = talk('프리셋을 사용하는 것이다', preset: 1)->generate(id: 1);
프리셋 적용 시에도 일반적인 음성 합성 플로우는 같습니다. 기본 AudioQuery의 값만 프리셋으로 대체됩니다.
Engine API를 통한 접근
Laravel VOICEVOX의 엔진 API를 실행하고 있는 경우, HTTP를 통해 프리셋을 조작할 수 있습니다.
전체 프리셋 조회
curl http://localhost:50513/presets
프리셋 추가
curl -X POST http://localhost:50513/add_preset \
-H "Content-Type: application/json" \
-d '{
"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
}'
프리셋 업데이트
curl -X POST http://localhost:50513/update_preset \
-H "Content-Type: application/json" \
-d '{
"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
}'
프리셋 삭제
curl -X POST http://localhost:50513/delete_preset \
-H "Content-Type: application/json" \
-d '{"id": 1}'
프리셋을 사용한 음성 쿼리 생성
curl -X POST "http://localhost:50513/audio_query_from_preset?text=こんにちは&preset_id=1"
파라미터 상세
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 (종료 무음·초)
주의 사항
Laravel판의 프리셋과 공식 VOICEVOX 엔진의 프리셋은 별도로 관리됩니다. 추가·업데이트·삭제는 즉시 JSON 파일에 저장됩니다.
- 프리셋 ID에
0을 지정하면 미사용 ID가 자동 채번됩니다.
- 프리셋에는
speaker_uuid (UUID 문자열)와 style_id (정수) 양쪽을 모두 포함하세요.
트러블슈팅
프리셋이 저장되지 않음
- 스토리지 디렉터리의 쓰기 권한을 확인하세요.
storage/voicevox/presets.json이 올바르게 생성되어 있는지 확인하세요.
프리셋 파일 위치를 알 수 없음
$path = config('voicevox.core.presets');
echo $path;
프리셋을 리셋하고 싶음
rm storage/voicevox/presets.json
$path = config('voicevox.core.presets');
if (file_exists($path)) {
unlink($path);
}
