VOICEVOX for Laravel - Knowledge of Laravel

概览

revolution/laravel-voicevox 是一个用于在 Laravel 中操作 VOICEVOX 的包。它以统一的 Laravel 风格同时支持通过 HTTP 连接官方引擎的客户端模式，以及结合 VOICEVOX Core for PHP 通过 PHP FFI 直接合成的原生模式。

若想先了解 FFI 的前置知识，请参考 PHP FFI；核心库自身的配置请参考 VOICEVOX Core for PHP 与用法。

功能表

Feature	Supported	Description
VOICEVOX Client	✅	通过 HTTP 访问官方 VOICEVOX 引擎 API。无需 FFI。
VOICEVOX Core	✅	通过 VOICEVOX Core for 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 环境

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

模式一览

模式	执行方式	FFI	主要用途	指南
客户端 Talk	向官方引擎发送 HTTP 请求	不需要	文本语音合成	client-talk
客户端 Song	向官方引擎发送 HTTP 请求	不需要	歌声合成	client-song
原生 Talk	通过 FFI 直接调用 VOICEVOX CORE	需要	本地文本语音合成	native-talk
原生 Song	通过 FFI 直接调用 VOICEVOX CORE	需要	本地歌声合成	native-song
引擎 API	由 Laravel 应用内提供兼容 API	需要	内置 VOICEVOX 兼容 API	installation

为何 `tap()` 特别契合

该包在 talk() / song() 之后立即返回 Audio Query 对象，允许你在 generate() 之前插入调整阶段。因此使用 tap() 时，不改变返回值只调整 query 的写法非常自然。

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。

关于 tap() 自身的思路，整理在 tap() helper 与 Tappable trait 中。该包是这一模式尤其易于理解的实际案例。

文档

安装

了解仅安装客户端、启用 FFI 的安装、发布配置文件、准备引擎资源等步骤。

客户端 Talk

通过官方 VOICEVOX 引擎开始进行文本语音合成。

客户端 Song

通过构建 Score 与 Note 进行歌声合成。

原生 Talk

使用 PHP FFI 与 VOICEVOX CORE 进行本地合成。

原生 Song

通过 FFI 直接使用歌声模型。

VOICEVOX Core for PHP

了解核心库的配置以及 Pure PHP 侧的用法。

参考链接

GitHub：invokable/laravel-voicevox
VOICEVOX Core for PHP：/zh/packages/voicevox-core-php
VOICEVOX Core for PHP 用法：/zh/packages/voicevox-core-php/usage
PHP FFI：/zh/advanced/ffi
tap() helper：/zh/advanced/tap
官方 VOICEVOX 引擎：VOICEVOX/voicevox_engine

​概览

​功能表

​要求

​模式一览

​为何 tap() 特别契合

​文档

安装

客户端 Talk

客户端 Song

原生 Talk

原生 Song

VOICEVOX Core for PHP

​参考链接

概览

功能表

要求

模式一览

为何 `tap()` 特别契合

文档

参考链接