메인 콘텐츠로 건너뛰기

​
무엇을 설치하는가

VOICEVOX for Laravel은 사용하려는 모드에 따라 추가 패키지와 로컬 셋업이 달라집니다.
공식 VOICEVOX 엔진에 HTTP로 연결하기만 할 경우, revolution/laravel-voicevox만으로 시작할 수 있습니다.
composer require revolution/laravel-voicevox

​
요구 사항

항목내용
PHP8.3+
Laravel12+
필수 확장ext-zip
FFI ext-ffi네이티브 모드 / 엔진 API에서 필요
Laravel Cloud를 포함해 일반적인 웹 서버에서는 FFI가 무효화되어 있습니다. 네이티브 모드와 엔진 API는 로컬 CLI에서 시도하세요.

​
셋업 절차

1

패키지 설치

사용하려는 모드에 따라 Composer로 도입합니다. 네이티브 모드와 엔진 API에서는 VOICEVOX Core for PHP도 필요합니다.
2

설정 파일 게시

php artisan vendor:publish --tag="voicevox-config"
3

.env 설정

클라이언트 모드만이라면 VOICEVOX_URL, FFI를 사용한다면 VOICEVOX_CORE_PATH를 설정합니다.
4

필요하면 엔진 리소스 설치

/speaker_info나 /singer_info를 사용할 경우, 추가 리소스가 필요합니다.

​
config/voicevox.php

모든 설정 항목은 설정 레퍼런스에서 확인할 수 있습니다. 
return [
    'client' => [
        'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
        'core_version' => env('VOICEVOX_CLIENT_CORE_VERSION'),
    ],

    'core' => [
        'path' => env('VOICEVOX_CORE_PATH'),
        'dict' => env('VOICEVOX_CORE_DICT_PATH', 'dict/open_jtalk_dic_utf_8-1.11'),
        'models' => env('VOICEVOX_CORE_MODELS_PATH', 'models/vvms'),
        'vvms' => ['0.vvm', '9.vvm', 's0.vvm'],
    ],

    'engine' => [
        'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
        'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
    ],
];

​
최소한으로 필요한 .env

​
클라이언트 모드만

기본값 http://127.0.0.1:50021에서 공식 엔진을 실행한다면 추가 설정은 불필요합니다. 
VOICEVOX_URL=http://127.0.0.1:50021

​
네이티브 모드 / 엔진 API

VOICEVOX_CORE_PATH=/path/to/voicevox_core/
VOICEVOX_CORE_PATH의 내용은 VOICEVOX Core for PHP의 절차로 준비합니다. 라이브러리 본체, OpenJTalk 사전, 모델 파일의 배치도 그쪽에서 확인하세요.

​
FFI 활성화

CLI에서는 통상 그대로 사용할 수 있습니다. 로컬에서 Laravel판 엔진 API를 실행하는 경우에는 php.ini에서 FFI를 활성화합니다. 
ffi.enable=true
FFI의 구조와 제약은 PHP FFI에 정리되어 있습니다.

​
엔진 리소스 설치

/speaker_info나 /singer_info 등 리소스 계열 엔드포인트를 사용할 경우에는 별도로 리소스 파일을 도입합니다. 
php artisan voicevox:install
Orchestra Testbench 환경에서는 다음 명령입니다. 
vendor/bin/testbench voicevox:install

​
모드별 진입점

클라이언트 Talk

공식 VOICEVOX 엔진을 Docker로 실행해 텍스트 음성 합성합니다.

클라이언트 Song

Score와 Note를 사용해 노래 합성합니다.

네이티브 Talk

FFI로 VOICEVOX CORE를 직접 호출합니다.

네이티브 Song

노래 모델과 sync()의 활용처를 확인합니다.

​
참고 링크

마지막 수정일 2026년 7월 13일

관련 항목

Laravel Cashier (Stripe)Laravel에서 MCP 서버 만들기설정 레퍼런스 - VOICEVOX for Laravel시작하기 - VOICEVOX for Laravel네이티브 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel