> ## 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](https://kawax.biz/jp/packages/voicevox-core-php.md) を組み合わせて PHP FFI から直接合成するネイティブモードを同じ Laravel スタイルで扱えます。

> [!NOTE]
>
> FFI の前提知識を先に整理したいなら [PHP FFI](https://kawax.biz/jp/advanced/ffi.md) を、コアライブラリ自体のセットアップは [VOICEVOX Core for PHP](https://kawax.biz/jp/packages/voicevox-core-php.md) と [使い方](https://kawax.biz/jp/packages/voicevox-core-php/usage.md) を参照してください。

## 機能表

| Feature | Supported | Description |
| - | - | - |
| VOICEVOX Client | ✅ | 公式 VOICEVOX エンジン API に HTTP でアクセスします。FFI は不要です。 |
| VOICEVOX Core | ✅ | [VOICEVOX Core for PHP](https://kawax.biz/jp/packages/voicevox-core-php.md) を通して VOICEVOX CORE の動的ライブラリを利用します。 |
| Laravel style | ✅ | Facade、ヘルパー、`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 を含む一般的な Web サーバー環境では FFI が無効なことが多いため、ネイティブモードとエンジン API は **ローカル CLI 前提** で考えてください。

## モード一覧

| モード | 実行方法 | FFI | 主な用途 | ガイド |
| - | - | - | - | - |
| クライアント Talk | 公式エンジンへ HTTP リクエスト | 不要 | テキスト音声合成 | [client-talk](https://kawax.biz/jp/packages/laravel-voicevox/client-talk.md) |
| クライアント Song | 公式エンジンへ HTTP リクエスト | 不要 | 歌声合成 | [client-song](https://kawax.biz/jp/packages/laravel-voicevox/client-song.md) |
| ネイティブ Talk | VOICEVOX CORE を FFI で直接呼び出し | 必要 | ローカルでのテキスト音声合成 | [native-talk](https://kawax.biz/jp/packages/laravel-voicevox/native-talk.md) |
| ネイティブ Song | VOICEVOX CORE を FFI で直接呼び出し | 必要 | ローカルでの歌声合成 | [native-song](https://kawax.biz/jp/packages/laravel-voicevox/native-song.md) |
| エンジン API | Laravel アプリ内で互換 API を提供 | 必要 | VOICEVOX 互換 API の内蔵 | [installation](https://kawax.biz/jp/packages/laravel-voicevox/installation.md) |

## `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` へきれいにチェーンできます。

> [!NOTE]
>
> `tap()` 自体の考え方は [tap() ヘルパーと Tappable トレイト](https://kawax.biz/jp/advanced/tap.md) で整理しています。このパッケージは実用例として特に分かりやすいケースです。

## ドキュメント

> [card] [インストール](https://kawax.biz/jp/packages/laravel-voicevox/installation.md)
>
> クライアントのみの導入、FFI を使う導入、設定ファイル公開、エンジンリソースの準備を確認します。

> [card] [クライアント Talk](https://kawax.biz/jp/packages/laravel-voicevox/client-talk.md)
>
> 公式 VOICEVOX エンジンを使ったテキスト音声合成を始めます。

> [card] [クライアント Song](https://kawax.biz/jp/packages/laravel-voicevox/client-song.md)
>
> `Score` と `Note` を組み立てて歌声合成を行います。

> [card] [ネイティブ Talk](https://kawax.biz/jp/packages/laravel-voicevox/native-talk.md)
>
> PHP FFI と VOICEVOX CORE でローカル合成します。

> [card] [ネイティブ Song](https://kawax.biz/jp/packages/laravel-voicevox/native-song.md)
>
> FFI 経由で歌声モデルを直接使います。

> [card] [VOICEVOX Core for PHP](https://kawax.biz/jp/packages/voicevox-core-php.md)
>
> コアライブラリのセットアップと Pure PHP 側の使い方を確認します。

## 参考リンク

* GitHub: [invokable/laravel-voicevox](https://github.com/invokable/laravel-voicevox)
* VOICEVOX Core for PHP: [/jp/packages/voicevox-core-php](https://kawax.biz/jp/packages/voicevox-core-php.md)
* VOICEVOX Core for PHP 使い方: [/jp/packages/voicevox-core-php/usage](https://kawax.biz/jp/packages/voicevox-core-php/usage.md)
* PHP FFI: [/jp/advanced/ffi](https://kawax.biz/jp/advanced/ffi.md)
* `tap()` ヘルパー: [/jp/advanced/tap](https://kawax.biz/jp/advanced/tap.md)
* 公式 VOICEVOX エンジン: [VOICEVOX/voicevox\_engine](https://github.com/VOICEVOX/voicevox_engine)


## Related topics

- [VoicevoxResponse - VOICEVOX for Laravel](https://kawax.biz/jp/packages/laravel-voicevox/response.md)
- [Laravel AI SDK連携 - VOICEVOX for Laravel](https://kawax.biz/jp/packages/laravel-voicevox/ai-sdk.md)
- [はじめに - VOICEVOX for Laravel](https://kawax.biz/jp/packages/laravel-voicevox/getting-started.md)
- [Score と Note 詳細解説 - VOICEVOX for Laravel](https://kawax.biz/jp/packages/laravel-voicevox/song-score-note.md)
- [.vvproj ファイル仕様 - VOICEVOX for Laravel](https://kawax.biz/jp/packages/laravel-voicevox/vvproj.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.