메인 콘텐츠로 건너뛰기

네이티브 모드란

네이티브 모드는 VOICEVOX Core for PHP를 통해 VOICEVOX CORE를 PHP FFI로 직접 호출합니다. 공식 엔진을 실행하지 않아도 합성할 수 있지만, FFI와 로컬 라이브러리 셋업이 필요합니다.
네이티브 모드는 웹 서버용이 아닙니다. 로컬 CLI에서 이용하세요. FFI의 제약은 PHP FFI에서도 설명하고 있습니다.

사전 준비

  1. 설치와 설정을 완료했을 것
  2. VOICEVOX Core for PHP의 셋업을 완료했을 것
  3. .envVOICEVOX_CORE_PATH를 설정했을 것
VOICEVOX_CORE_PATH=/path/to/voicevox_core/

기본적인 사용법

네이티브 모드에서는 talk() 헬퍼를 사용합니다.
use function Revolution\Voicevox\talk;

$response = talk('네이티브판인 것이다', id: 1)
    ->generate(id: 1);

$response->storeAs('native', 'talk.wav');

스타일 ID 지정

id에는 로드된 .vvm에 포함된 스타일 ID를 지정합니다.
use function Revolution\Voicevox\talk;

$response = talk('ずんだもんなのだ', id: 1)
    ->generate(id: 1);
config/voicevox.phpcore.vvms에 포함된 모델만 사용할 수 있습니다.

tap()으로 Audio Query 조정

네이티브 모드에서도 tap()의 사용법은 같습니다. 단, TalkAudioQuery는 클라이언트 모드와는 다른 클래스입니다.
use Revolution\Voicevox\Talk\TalkAudioQuery;
use function Revolution\Voicevox\talk;

$response = 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);
tap() 패턴 자체는 tap() 헬퍼와 Tappable 트레이트에 정리되어 있습니다. VOICEVOX for Laravel은 그 실전 예시입니다.

AquesTalk 풍 표기의 카나 사용

네이티브 모드에는 enable_katakana_english가 없기 때문에, 영어가 섞인 입력을 그대로 읽는 용도에는 적합하지 않습니다. 대신 AquesTalk 풍 표기의 카나를 직접 전달하는 kana()를 사용할 수 있습니다.
use function Revolution\Voicevox\kana;

$response = kana("ネイティブ'バンナ/ノダ'", id: 1)
    ->generate(id: 1);

$response->storeAs('native', 'kana.wav');

클라이언트 모드와의 차이

항목클라이언트 Talk네이티브 Talk
엔진 실행필요불필요
FFI불필요필요
영어 자동 카타카나 변환있음없음
API 진입점Voicevox::talk()talk()

다음에 읽어볼 페이지

네이티브 Song

노래 모델을 FFI를 통해 다룹니다.

VOICEVOX Core for PHP

순수한 PHP 래퍼 측의 셋업과 제약을 확인합니다.
마지막 수정일 2026년 7월 13일