시작하기 - VOICEVOX for Laravel

VOICEVOX for Laravel의 기본 개념, 3가지 모드 비교, 빠른 시작(클라이언트 모드), 주요 기능을 정리합니다.

VOICEVOX for Laravel은 Laravel에서 VOICEVOX의 음성 합성 기능을 사용하기 위한 패키지입니다. 텍스트에서 일본어 음성을 생성할 수 있습니다.

우선 클라이언트 모드부터 시작하면 셋업이 최단입니다. FFI를 사용할 수 있는 환경이라면 나중에 네이티브 모드나 엔진 API 모드로 단계적으로 이전할 수 있습니다.

​

3가지 이용 모드

모드	실행 방식	FFI	적합한 용도	가이드
클라이언트 모드	공식 VOICEVOX 엔진에 HTTP 연결	불필요	우선 시도, Docker 환경, FFI를 사용할 수 없는 환경	Client Talk / Client Song
네이티브 모드	VOICEVOX CORE를 PHP FFI로 직접 호출	필요	고속화, 오프라인 실행, CLI 도구 통합	Native Talk / Native Song
엔진 API 모드	Laravel이 VOICEVOX 호환 API를 제공	필요	API 서버 공개, 여러 클라이언트 연동	Engine Talk / Engine Song

​

빠른 시작

클라이언트 모드 절차입니다.

1. 패키지 설치

   composer require revolution/laravel-voicevox
   

   자세한 내용은 설치와 설정을 확인하세요.

2. 공식 엔진 실행

   docker pull voicevox/voicevox_engine:cpu-latest
   docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
   
3. 음성 합성 시도

   use Revolution\Voicevox\Voicevox;
   
   $response = Voicevox::talk('안녕하세요, Laravel입니다.', id: 1)->generate(id: 1);
   $response->storeAs('output.wav');
   

​

주요 기능

​

음성 합성 (Talk)

use Revolution\Voicevox\Client\TalkAudioQuery;
use Revolution\Voicevox\Voicevox;

$response = Voicevox::talk('こんにちは', id: 1)
    ->tap(function (TalkAudioQuery $talk) {
        $talk->audioQuery['speedScale'] = 1.2;
        $talk->audioQuery['pitchScale'] = 0.05;
        $talk->audioQuery['intonationScale'] = 1.5;
        $talk->audioQuery['volumeScale'] = 1.0;
    })
    ->generate(id: 1);

​

노래 합성 (Song)

use Revolution\Voicevox\Song\Note;
use Revolution\Voicevox\Song\Score;
use Revolution\Voicevox\Voicevox;

$score = Score::make([
    Note::make(length: 15),
    Note::make(length: Note::len(ticks: 480, bpm: 120), lyric: 'ド', key: 60),
    Note::make(length: Note::len(480, 120), lyric: 'レ', key: 62),
    Note::make(length: Note::len(960, 120), lyric: 'ミ', key: 64),
    Note::make(length: 2),
]);

$response = Voicevox::song($score)->generate(id: 3001);

​

사용자 사전과 프리셋

클라이언트 모드에서는 Voicevox 파사드를 사용해 공식 엔진 측의 사용자 사전이나 프리셋을 조작합니다.

use Revolution\Voicevox\Voicevox;

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 3,
);

$presetId = 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,
]);

​

Laravel AI SDK 연동

use Laravel\Ai\Audio;

$audio = Audio::of('안녕하세요, Laravel입니다.')
    ->voice('ずんだもん')
    ->generate();

$audio->storeAs('output.wav');

​

다음 단계

• 설치와 설정
• 설정 레퍼런스
• Client Talk
• Client Song
• 클라이언트 모드 - 사용자 사전
• 클라이언트 모드 - 프리셋
• Native Talk
• Engine Talk
• 네이티브 모드 - 사용자 사전
• 네이티브 모드 - 프리셋
• AI SDK 연동