클라이언트 모드 - 프리셋 - 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 빌드에서는 통상 다음 위치에 저장됩니다.

~/Library/Application Support/voicevox-engine/presets.yaml

Docker로 공식 엔진을 실행하고 있는 경우에도 컨테이너 내의 사용자 영역에 저장됩니다. 컨테이너를 재시작해도 같은 컨테이너를 계속 사용하는 동안에는 데이터가 유지됩니다. 다만 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를 지정합니다.

​

트러블슈팅

​

프리셋을 조회할 수 없음

1. 공식 VOICEVOX 엔진이 실행되고 있는지 확인하세요.
2. VOICEVOX_URL이 올바른 연결 대상을 가리키고 있는지 확인하세요.
3. Docker에서 다른 컨테이너를 다시 시작하고 있지 않은지 확인하세요.

​

프리셋 파일 위치를 알 수 없음

macOS 빌드판에서는 다음 위치를 확인하세요.

~/Library/Application Support/voicevox-engine/presets.yaml

Docker에서는 공식 엔진의 사용자 영역(컨테이너 내)에 저장됩니다. 영속화가 필요한 경우, 컨테이너 내의 사용자 영역을 Docker volume에 마운트하세요.

​

speaker_uuid를 알 수 없음

스피커 목록에서 UUID를 획득할 수 있습니다.

use Revolution\Voicevox\Voicevox;

$speakers = Voicevox::speakers();

foreach ($speakers as $speaker) {
    echo $speaker['name'].': '.$speaker['speaker_uuid'].PHP_EOL;
}