> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # 클라이언트 모드 - 프리셋 - VOICEVOX for Laravel > VOICEVOX for Laravel의 클라이언트 모드에서 공식 엔진의 프리셋을 조작하고, 음성 합성 파라미터를 저장·재사용하는 방법을 설명합니다. 프리셋 기능을 사용하면 자주 쓰는 음성 합성 파라미터 조합을 공식 VOICEVOX 엔진에 저장해 재사용할 수 있습니다. 클라이언트 모드에서는 Laravel 측에 프리셋을 저장하지 않고, 연결 대상인 공식 엔진이 관리하는 프리셋 API를 이용합니다. ## 개요 클라이언트 모드의 프리셋은 `Voicevox` 파사드에서 조작합니다. 내부에서는 공식 VOICEVOX 엔진의 `/presets`, `/add_preset`, `/update_preset`, `/delete_preset`, `/audio_query_from_preset`에 HTTP 요청을 보냅니다. 공식 엔진의 프리셋은 OS별 사용자 영역에 `presets.yaml`로 저장됩니다. VOICEVOX 앱(제품판) macOS 빌드에서는 통상 다음 위치에 저장됩니다. ```text theme={null} ~/Library/Application Support/voicevox-engine/presets.yaml ``` Docker로 공식 엔진을 실행하고 있는 경우에도 컨테이너 내의 사용자 영역에 저장됩니다. 컨테이너를 재시작해도 같은 컨테이너를 계속 사용하는 동안에는 데이터가 유지됩니다. 다만 `docker run --rm`처럼 임시 컨테이너를 매번 새로 만드는 경우에는 컨테이너 종료 시에 프리셋이 사라집니다. 프리셋을 확실히 영속화하려면 Docker volume으로 컨테이너 내의 사용자 영역을 마운트하세요. 네이티브 모드의 `storage/voicevox/presets.json`과는 별도로 관리됩니다. Laravel 측의 `config('voicevox.core.presets')`는 클라이언트 모드에서는 사용되지 않습니다. ## 사전 준비 공식 VOICEVOX 엔진을 실행합니다. ```shell theme={null} docker pull voicevox/voicevox_engine:cpu-latest docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest ``` 연결 대상은 `VOICEVOX_URL`에서 변경할 수 있습니다. ```env theme={null} VOICEVOX_URL=http://127.0.0.1:50021 ``` ## 프리셋 구조 클라이언트 모드에서 송수신하는 프리셋은 공식 엔진 API의 스키마에 맞춘 배열입니다. ```php theme={null} [ '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가 할당됩니다. ```php theme={null} 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 ``` ### 전체 프리셋 조회 ```php theme={null} use Revolution\Voicevox\Voicevox; $presets = Voicevox::presets(); /* [ [ "id" => 1, "name" => "ゆっくり丁寧", "speaker_uuid" => "7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff", "style_id" => 1, "speedScale" => 0.8, ... ], ... ] */ ``` ### 프리셋 업데이트 ```php theme={null} 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, ]); ``` ### 프리셋 삭제 ```php theme={null} use Revolution\Voicevox\Voicevox; Voicevox::deletePreset(1); ``` ## 프리셋을 사용한 음성 합성 ### talkFromPreset() `Voicevox::talkFromPreset()`은 공식 엔진의 `/audio_query_from_preset`을 사용해 프리셋이 적용된 `TalkAudioQuery`를 생성합니다. ```php theme={null} use Revolution\Voicevox\Voicevox; $response = Voicevox::talkFromPreset('프리셋을 사용하는 것이다', presetId: 1) ->generate(id: 1); $response->storeAs('client', 'preset-talk.wav'); ``` ### audioQueryFromPreset() 음성 합성 전의 오디오 쿼리 배열만 획득하고 싶은 경우에는 `audioQueryFromPreset()`을 사용합니다. ```php theme={null} use Revolution\Voicevox\Voicevox; $audioQuery = Voicevox::audioQueryFromPreset( text: '프리셋의 쿼리만 만드는 것이다', presetId: 1, ); $audioQuery['speedScale'] = 1.1; ``` ### tap()으로 추가 조정 프리셋에서 생성한 `TalkAudioQuery`도 통상의 `Voicevox::talk()`과 마찬가지로 `tap()`으로 조정할 수 있습니다. ```php theme={null} 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 필요) | ## 실전 예 ### 내레이션용 ```php theme={null} 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, ]); ``` ### 빠른 말투 토크용 ```php theme={null} 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를 지정합니다. ## 트러블슈팅 ### 프리셋을 조회할 수 없음 1. 공식 VOICEVOX 엔진이 실행되고 있는지 확인하세요. 2. `VOICEVOX_URL`이 올바른 연결 대상을 가리키고 있는지 확인하세요. 3. Docker에서 다른 컨테이너를 다시 시작하고 있지 않은지 확인하세요. ### 프리셋 파일 위치를 알 수 없음 macOS 빌드판에서는 다음 위치를 확인하세요. ```text theme={null} ~/Library/Application Support/voicevox-engine/presets.yaml ``` Docker에서는 공식 엔진의 사용자 영역(컨테이너 내)에 저장됩니다. 영속화가 필요한 경우, 컨테이너 내의 사용자 영역을 Docker volume에 마운트하세요. ### speaker\_uuid를 알 수 없음 스피커 목록에서 UUID를 획득할 수 있습니다. ```php theme={null} use Revolution\Voicevox\Voicevox; $speakers = Voicevox::speakers(); foreach ($speakers as $speaker) { echo $speaker['name'].': '.$speaker['speaker_uuid'].PHP_EOL; } ``` ## Related topics - [클라이언트 모드 - 사용자 사전 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-user-dict.md) - [클라이언트 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-song.md) - [클라이언트 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-talk.md) - [엔진 API 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/engine-talk.md) - [네이티브 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-song.md)