> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# VOICEVOX for Laravel

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

## 개요

[revolution/laravel-voicevox](https://github.com/invokable/laravel-voicevox)는 Laravel에서 VOICEVOX를 다루기 위한 패키지입니다.

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

<Info>
  FFI에 대한 사전 지식을 먼저 정리하고 싶다면 [PHP FFI](/ko/advanced/ffi)를, 코어 라이브러리 자체의 셋업은 [VOICEVOX Core for PHP](/ko/packages/voicevox-core-php)와 [사용법](/ko/packages/voicevox-core-php/usage)을 참조하세요.
</Info>

## 기능표

| Feature                             | Supported | Description                                                                                 |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
| VOICEVOX Client                     | ✅         | 공식 VOICEVOX 엔진 API에 HTTP로 접근합니다. FFI는 필요 없습니다.                                              |
| VOICEVOX Core                       | ✅         | [VOICEVOX Core for PHP](/ko/packages/voicevox-core-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 환경

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

## 모드 목록

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

## `tap()`이 잘 맞는 이유

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

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

```php theme={null}
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`로 깔끔하게 체이닝할 수 있습니다.

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

## 문서

<Columns cols={2}>
  <Card title="설치" href="/ko/packages/laravel-voicevox/installation" icon="download">
    클라이언트만의 도입, FFI를 사용하는 도입, 설정 파일 게시, 엔진 리소스 준비를 확인합니다.
  </Card>

  <Card title="클라이언트 Talk" href="/ko/packages/laravel-voicevox/client-talk" icon="message-circle">
    공식 VOICEVOX 엔진을 사용한 텍스트 음성 합성을 시작합니다.
  </Card>

  <Card title="클라이언트 Song" href="/ko/packages/laravel-voicevox/client-song" icon="music">
    `Score`와 `Note`를 조립하여 노래 합성을 실행합니다.
  </Card>

  <Card title="네이티브 Talk" href="/ko/packages/laravel-voicevox/native-talk" icon="cpu">
    PHP FFI와 VOICEVOX CORE로 로컬 합성합니다.
  </Card>

  <Card title="네이티브 Song" href="/ko/packages/laravel-voicevox/native-song" icon="music">
    FFI를 통해 노래 모델을 직접 사용합니다.
  </Card>

  <Card title="VOICEVOX Core for PHP" href="/ko/packages/voicevox-core-php" icon="library">
    코어 라이브러리의 셋업과 Pure PHP 측 사용법을 확인합니다.
  </Card>
</Columns>

## 참고 링크

* GitHub: [invokable/laravel-voicevox](https://github.com/invokable/laravel-voicevox)
* VOICEVOX Core for PHP: [/ko/packages/voicevox-core-php](/ko/packages/voicevox-core-php)
* VOICEVOX Core for PHP 사용법: [/ko/packages/voicevox-core-php/usage](/ko/packages/voicevox-core-php/usage)
* PHP FFI: [/ko/advanced/ffi](/ko/advanced/ffi)
* `tap()` 헬퍼: [/ko/advanced/tap](/ko/advanced/tap)
* 공식 VOICEVOX 엔진: [VOICEVOX/voicevox\_engine](https://github.com/VOICEVOX/voicevox_engine)


## Related topics

- [VoicevoxResponse - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/response.md)
- [설치와 설정 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/installation.md)
- [시작하기 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/getting-started.md)
- [.vvproj 파일 사양 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/vvproj.md)
- [Laravel AI SDK 연동 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/ai-sdk.md)