VOICEVOX for Laravel

Laravel에서 VOICEVOX의 클라이언트·네이티브·엔진 API를 다루는 패키지의 개요와 각 모드의 진입점을 정리합니다.

​

개요

revolution/laravel-voicevox는 Laravel에서 VOICEVOX를 다루기 위한 패키지입니다.

HTTP를 통해 공식 엔진에 연결하는 클라이언트 모드와, VOICEVOX Core for PHP를 조합해 PHP FFI에서 직접 합성하는 네이티브 모드를 같은 Laravel 스타일로 다룰 수 있습니다.

FFI에 대한 사전 지식을 먼저 정리하고 싶다면 PHP FFI를, 코어 라이브러리 자체의 셋업은 VOICEVOX Core for PHP와 사용법을 참조하세요.

​

기능표

Feature	Supported	Description
VOICEVOX Client	✅	공식 VOICEVOX 엔진 API에 HTTP로 접근합니다. FFI는 필요 없습니다.
VOICEVOX Core	✅	VOICEVOX Core for PHP를 통해 VOICEVOX CORE의 동적 라이브러리를 이용합니다.
Laravel style	✅	파사드, 헬퍼, config/voicevox.php, .env로 Laravel답게 다룰 수 있습니다.
Laravel AI SDK 통합	✅	Laravel AI SDK의 Audio 워크플로에서도 이용할 수 있습니다.
VOICEVOX Engine	⚠️	Laravel 앱 내에 VOICEVOX 호환 API를 내장합니다. 미대응 부분은 공식 엔진으로 폴백합니다.
VOICEVOX Engine / OpenAI 호환 TTS API	✅	/v1/audio/speech의 voice는 AI SDK와 마찬가지로 스타일 ID 외에 “ずんだもん” 등의 별칭에 대응하고 있습니다.
VOICEVOX Editor	⚠️	macOS용 송 특화 앱을 개발했지만 앱스토어에서 공개·배포할 예정은 없습니다. 언젠가 GitHub에서 코드가 공개되면 Xcode에서 빌드해 사용할 수 있습니다.

​

요구 사항

• PHP 8.3+
• Laravel 12+
• ext-zip
• 네이티브 모드 / 엔진 API를 사용하는 경우 ext-ffi
• 로컬 CLI 환경

Laravel Cloud를 포함해 일반적인 웹 서버 환경에서는 FFI가 무효화된 경우가 많으므로, 네이티브 모드와 엔진 API는 로컬 CLI 전제로 생각하세요.

​

모드 목록

모드	실행 방법	FFI	주요 용도	가이드
클라이언트 Talk	공식 엔진에 HTTP 요청	불필요	텍스트 음성 합성	client-talk
클라이언트 Song	공식 엔진에 HTTP 요청	불필요	노래 합성	client-song
네이티브 Talk	VOICEVOX CORE를 FFI로 직접 호출	필요	로컬에서의 텍스트 음성 합성	native-talk
네이티브 Song	VOICEVOX CORE를 FFI로 직접 호출	필요	로컬에서의 노래 합성	native-song
엔진 API	Laravel 앱 내에서 호환 API를 제공	필요	VOICEVOX 호환 API의 내장	installation

​

tap()이 잘 맞는 이유

이 패키지는 talk() / song() 직후에 Audio Query 오브젝트를 반환하며, generate() 이전에 조정 단계를 끼워 넣을 수 있습니다.

그래서 tap()을 사용하면 반환값을 바꾸지 않고 쿼리만 조정하는 작성 방식이 자연스럽습니다.

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

$response = Voicevox::talk('탭으로 조정할 수 있는 것이다', id: 1)
    ->tap(function (TalkAudioQuery $talk) {
        $talk->audioQuery['speedScale'] = 1.2;
    })
    ->generate(id: 1);

• Talk에서는 speedScale이나 pitchScale 등을 조정할 수 있습니다.
• Song에서는 sync()로 F0와 볼륨을 재계산할 수 있습니다.
• generate()가 반환하는 VoicevoxResponse로 깔끔하게 체이닝할 수 있습니다.

tap() 자체의 사고방식은 tap() 헬퍼와 Tappable 트레이트에서 정리하고 있습니다. 이 패키지는 실용 예시로서 특히 이해하기 쉬운 케이스입니다.

​

문서

설치

클라이언트만의 도입, FFI를 사용하는 도입, 설정 파일 게시, 엔진 리소스 준비를 확인합니다.

클라이언트 Talk

공식 VOICEVOX 엔진을 사용한 텍스트 음성 합성을 시작합니다.

클라이언트 Song

Score와 Note를 조립하여 노래 합성을 실행합니다.

네이티브 Talk

PHP FFI와 VOICEVOX CORE로 로컬 합성합니다.

네이티브 Song

FFI를 통해 노래 모델을 직접 사용합니다.

VOICEVOX Core for PHP

코어 라이브러리의 셋업과 Pure PHP 측 사용법을 확인합니다.

​

참고 링크

• GitHub: invokable/laravel-voicevox
• VOICEVOX Core for PHP: /ko/packages/voicevox-core-php
• VOICEVOX Core for PHP 사용법: /ko/packages/voicevox-core-php/usage
• PHP FFI: /ko/advanced/ffi
• tap() 헬퍼: /ko/advanced/tap
• 공식 VOICEVOX 엔진: VOICEVOX/voicevox_engine