네이티브 모드 - 프리셋 - VOICEVOX for Laravel

VOICEVOX for Laravel의 네이티브 모드에서 프리셋 기능을 사용해 음성 합성 파라미터를 저장·재사용하는 방법을 설명합니다.

​

프리셋이란

프리셋 기능을 사용하면 자주 쓰는 음성 합성 파라미터 조합을 저장해 재사용할 수 있습니다.

말하기 속도·음높이·억양 등을 함께 관리하면, 여러 음성을 생성할 때도 일관된 품질을 유지하기 쉬워집니다.

​

개요

Laravel VOICEVOX의 프리셋 기능은 VOICEVOX Core를 이용한 네이티브 구현입니다. 프리셋 데이터는 JSON 형식으로 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 (정수) 양쪽을 모두 포함하세요.

​

트러블슈팅

​

프리셋이 저장되지 않음

1. 스토리지 디렉터리의 쓰기 권한을 확인하세요.
2. 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);
}