> ## 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 的 Client、Native、Engine API 套件的概觀與各模式入口。

## 概觀

[revolution/laravel-voicevox](https://github.com/invokable/laravel-voicevox) 是從 Laravel 使用 VOICEVOX 的套件。

可以用相同的 Laravel 風格處理透過 HTTP 連線至官方引擎的 Client 模式,以及結合 [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php) 透過 PHP FFI 直接合成的 Native 模式。

<Info>
  若想先整理 FFI 前置知識,請參閱 [PHP FFI](/zh-TW/advanced/ffi);核心 library 本身的設定請參閱 [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php) 與 [用法](/zh-TW/packages/voicevox-core-php/usage)。
</Info>

## 功能表

| Feature                             | Supported | Description                                                                                 |
| ----------------------------------- | --------- | ------------------------------------------------------------------------------------------- |
| VOICEVOX Client                     | ✅         | 以 HTTP 存取官方 VOICEVOX 引擎 API。不需要 FFI。                                                        |
| VOICEVOX Core                       | ✅         | 透過 [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php) 使用 VOICEVOX CORE 的動態 library。 |
| Laravel style                       | ✅         | 可透過 Facade、helper、`config/voicevox.php`、`.env` 以 Laravel 風格使用。                              |
| Laravel AI SDK 整合                   | ✅         | 也可從 Laravel AI SDK 的 Audio workflow 使用。                                                     |
| VOICEVOX Engine                     | ⚠️        | 在 Laravel 應用內內建 VOICEVOX 相容 API。未支援部分會 fallback 至官方引擎。                                      |
| VOICEVOX Engine / OpenAI 相容 TTS API | ✅         | `/v1/audio/speech` voice 與 AI SDK 相同,除 style ID 外也支援「ずんだもん」等別名。                             |
| VOICEVOX Editor                     | ⚠️        | 雖然開發過 macOS 用的 song 專屬應用,但沒有在 App Store 公開發佈的計畫。若日後在 GitHub 公開程式碼,可以用 Xcode 建置使用。           |

## 需求

* PHP 8.3+
* Laravel 12+
* `ext-zip`
* 使用 Native 模式 / Engine API 時需 `ext-ffi`
* 本機 CLI 環境

<Warning>
  包含 Laravel Cloud 在內的一般 Web 伺服器環境中,FFI 大多為停用狀態,因此 Native 模式與 Engine API 請以 **本機 CLI 為前提**。
</Warning>

## 模式一覽

| 模式          | 執行方式                     | FFI | 主要用途               | 指南                                                            |
| ----------- | ------------------------ | --- | ------------------ | ------------------------------------------------------------- |
| Client Talk | 對官方引擎進行 HTTP 請求          | 不需  | 文字語音合成             | [client-talk](/zh-TW/packages/laravel-voicevox/client-talk)   |
| Client Song | 對官方引擎進行 HTTP 請求          | 不需  | 歌聲合成               | [client-song](/zh-TW/packages/laravel-voicevox/client-song)   |
| Native Talk | 以 FFI 直接呼叫 VOICEVOX CORE | 需要  | 本機文字語音合成           | [native-talk](/zh-TW/packages/laravel-voicevox/native-talk)   |
| Native Song | 以 FFI 直接呼叫 VOICEVOX CORE | 需要  | 本機歌聲合成             | [native-song](/zh-TW/packages/laravel-voicevox/native-song)   |
| Engine API  | 在 Laravel 應用內提供相容 API    | 需要  | 內建 VOICEVOX 相容 API | [installation](/zh-TW/packages/laravel-voicevox/installation) |

## `tap()` 之所以合適的原因

本套件在 `talk()` / `song()` 之後回傳 Audio Query 物件,可在 `generate()` 之前插入調整階段。

因此使用 `tap()` 可以自然地寫成 **不改變回傳值,只調整 query** 的形式。

```php theme={null}
use Revolution\Voicevox\Client\TalkAudioQuery;
use Revolution\Voicevox\Voicevox;

$response = Voicevox::talk('可以用 tap 進行調整', 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() helper 與 Tappable trait](/zh-TW/advanced/tap)。本套件是特別容易理解的實用範例。
</Info>

## 文件

<Columns cols={2}>
  <Card title="安裝" href="/zh-TW/packages/laravel-voicevox/installation" icon="download">
    確認僅 Client 的導入、使用 FFI 的導入、發佈設定檔、準備引擎資源。
  </Card>

  <Card title="Client Talk" href="/zh-TW/packages/laravel-voicevox/client-talk" icon="message-circle">
    開始使用官方 VOICEVOX 引擎進行文字語音合成。
  </Card>

  <Card title="Client Song" href="/zh-TW/packages/laravel-voicevox/client-song" icon="music">
    建立 `Score` 與 `Note` 進行歌聲合成。
  </Card>

  <Card title="Native Talk" href="/zh-TW/packages/laravel-voicevox/native-talk" icon="cpu">
    以 PHP FFI 與 VOICEVOX CORE 進行本機合成。
  </Card>

  <Card title="Native Song" href="/zh-TW/packages/laravel-voicevox/native-song" icon="music">
    透過 FFI 直接使用歌聲模型。
  </Card>

  <Card title="VOICEVOX Core for PHP" href="/zh-TW/packages/voicevox-core-php" icon="library">
    確認核心 library 的設定與 Pure PHP 端的用法。
  </Card>
</Columns>

## 參考連結

* GitHub: [invokable/laravel-voicevox](https://github.com/invokable/laravel-voicevox)
* VOICEVOX Core for PHP: [/zh-TW/packages/voicevox-core-php](/zh-TW/packages/voicevox-core-php)
* VOICEVOX Core for PHP 用法: [/zh-TW/packages/voicevox-core-php/usage](/zh-TW/packages/voicevox-core-php/usage)
* PHP FFI: [/zh-TW/advanced/ffi](/zh-TW/advanced/ffi)
* `tap()` helper: [/zh-TW/advanced/tap](/zh-TW/advanced/tap)
* 官方 VOICEVOX 引擎: [VOICEVOX/voicevox\_engine](https://github.com/VOICEVOX/voicevox_engine)


## Related topics

- [VoicevoxResponse - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/response.md)
- [入門 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/getting-started.md)
- [Laravel AI SDK 整合 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/ai-sdk.md)
- [設定參考 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/configuration.md)
- [Client 模式 - 預設集 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-presets.md)