> ## 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 的包。

它以统一的 Laravel 风格同时支持通过 HTTP 连接官方引擎的客户端模式，以及结合 [VOICEVOX Core for PHP](/zh/packages/voicevox-core-php) 通过 PHP FFI 直接合成的原生模式。

<Info>
  若想先了解 FFI 的前置知识，请参考 [PHP FFI](/zh/advanced/ffi)；核心库自身的配置请参考 [VOICEVOX Core for PHP](/zh/packages/voicevox-core-php) 与 [用法](/zh/packages/voicevox-core-php/usage)。
</Info>

## 功能表

| Feature                             | Supported | Description                                                                       |
| ----------------------------------- | --------- | --------------------------------------------------------------------------------- |
| VOICEVOX Client                     | ✅         | 通过 HTTP 访问官方 VOICEVOX 引擎 API。无需 FFI。                                              |
| VOICEVOX Core                       | ✅         | 通过 [VOICEVOX Core for PHP](/zh/packages/voicevox-core-php) 使用 VOICEVOX CORE 的动态库。 |
| Laravel style                       | ✅         | 通过 Facade、helper、`config/voicevox.php`、`.env` 以 Laravel 风格使用。                     |
| Laravel AI SDK 集成                   | ✅         | 也可以从 Laravel AI SDK 的 Audio 工作流中使用。                                               |
| VOICEVOX Engine                     | ⚠️        | 在 Laravel 应用内内置 VOICEVOX 兼容 API。未支持的部分会 fallback 到官方引擎。                           |
| VOICEVOX Engine / OpenAI 兼容 TTS API | ✅         | `/v1/audio/speech` 的 voice 与 AI SDK 一样，除 Style ID 之外也支持"ずんだもん"等别名。                |
| VOICEVOX Editor                     | ⚠️        | 开发了 macOS 用的 Song 专用应用，但没有在应用商店发布/发行的计划。如果日后在 GitHub 公开代码，你可以在 Xcode 中构建后使用。      |

## 要求

* PHP 8.3+
* Laravel 12+
* `ext-zip`
* 若使用原生模式 / 引擎 API，需要 `ext-ffi`
* 本地 CLI 环境

<Warning>
  在包括 Laravel Cloud 在内的常见 Web 服务器环境中，FFI 往往是禁用的，因此请将原生模式与引擎 API **默认视为本地 CLI 环境使用**。
</Warning>

## 模式一览

| 模式       | 执行方式                      | FFI | 主要用途               | 指南                                                         |
| -------- | ------------------------- | --- | ------------------ | ---------------------------------------------------------- |
| 客户端 Talk | 向官方引擎发送 HTTP 请求           | 不需要 | 文本语音合成             | [client-talk](/zh/packages/laravel-voicevox/client-talk)   |
| 客户端 Song | 向官方引擎发送 HTTP 请求           | 不需要 | 歌声合成               | [client-song](/zh/packages/laravel-voicevox/client-song)   |
| 原生 Talk  | 通过 FFI 直接调用 VOICEVOX CORE | 需要  | 本地文本语音合成           | [native-talk](/zh/packages/laravel-voicevox/native-talk)   |
| 原生 Song  | 通过 FFI 直接调用 VOICEVOX CORE | 需要  | 本地歌声合成             | [native-song](/zh/packages/laravel-voicevox/native-song)   |
| 引擎 API   | 由 Laravel 应用内提供兼容 API     | 需要  | 内置 VOICEVOX 兼容 API | [installation](/zh/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('タップで調整できるのだ', 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/advanced/tap) 中。该包是这一模式尤其易于理解的实际案例。
</Info>

## 文档

<Columns cols={2}>
  <Card title="安装" href="/zh/packages/laravel-voicevox/installation" icon="download">
    了解仅安装客户端、启用 FFI 的安装、发布配置文件、准备引擎资源等步骤。
  </Card>

  <Card title="客户端 Talk" href="/zh/packages/laravel-voicevox/client-talk" icon="message-circle">
    通过官方 VOICEVOX 引擎开始进行文本语音合成。
  </Card>

  <Card title="客户端 Song" href="/zh/packages/laravel-voicevox/client-song" icon="music">
    通过构建 `Score` 与 `Note` 进行歌声合成。
  </Card>

  <Card title="原生 Talk" href="/zh/packages/laravel-voicevox/native-talk" icon="cpu">
    使用 PHP FFI 与 VOICEVOX CORE 进行本地合成。
  </Card>

  <Card title="原生 Song" href="/zh/packages/laravel-voicevox/native-song" icon="music">
    通过 FFI 直接使用歌声模型。
  </Card>

  <Card title="VOICEVOX Core for PHP" href="/zh/packages/voicevox-core-php" icon="library">
    了解核心库的配置以及 Pure PHP 侧的用法。
  </Card>
</Columns>

## 参考链接

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


## Related topics

- [VOICEVOX for Laravel](/it/packages/laravel-voicevox/index.md)