跳转到主要内容

什么是原生模式

原生模式通过 VOICEVOX Core for PHP,用 PHP FFI 直接调用 VOICEVOX CORE。 无需启动官方引擎即可合成,但需要配置 FFI 与本地库。
原生模式不面向 Web 服务器。请在本地 CLI 中使用。FFI 的限制也在 PHP FFI 中有说明。

前置准备

  1. 已完成 安装与配置
  2. 已完成 VOICEVOX Core for PHP 的配置
  3. 已在 .env 中设置 VOICEVOX_CORE_PATH
VOICEVOX_CORE_PATH=/path/to/voicevox_core/

基本使用

原生模式使用 talk() helper。
use function Revolution\Voicevox\talk;

$response = talk('ネイティブ版なのだ', id: 1)
    ->generate(id: 1);

$response->storeAs('native', 'talk.wav');

指定 Style ID

id 请指定已加载的 .vvm 中包含的 Style ID。
use function Revolution\Voicevox\talk;

$response = talk('ずんだもんなのだ', id: 1)
    ->generate(id: 1);
只能使用 config/voicevox.phpcore.vvms 所包含的模型。

使用 tap() 调整 Audio Query

在原生模式下 tap() 的用法相同。不过 TalkAudioQuery 与客户端模式是不同的类。
use Revolution\Voicevox\Talk\TalkAudioQuery;
use function Revolution\Voicevox\talk;

$response = talk('速めに話すのだ', id: 1)
    ->tap(function (TalkAudioQuery $talk) {
        $talk->audioQuery['speedScale'] = 1.2;
        $talk->audioQuery['pitchScale'] = 0.05;
        $talk->audioQuery['intonationScale'] = 1.5;
        $talk->audioQuery['volumeScale'] = 1.0;
    })
    ->generate(id: 1);
tap() 这一模式本身整理在 tap() helper 与 Tappable trait 中。VOICEVOX for Laravel 是其实际案例。

使用 AquesTalk 风格的假名记法

原生模式没有 enable_katakana_english,因此不适合直接读取包含英语的输入。 作为替代,你可以使用直接传入 AquesTalk 风格假名记法的 kana()
use function Revolution\Voicevox\kana;

$response = kana("ネイティブ'バンナ/ノダ'", id: 1)
    ->generate(id: 1);

$response->storeAs('native', 'kana.wav');

与客户端模式的区别

项目客户端 Talk原生 Talk
引擎启动需要不需要
FFI不需要需要
英语自动片假名转换
API 入口Voicevox::talk()talk()

下一步阅读

原生 Song

通过 FFI 使用歌声模型。

VOICEVOX Core for PHP

了解纯 PHP wrapper 侧的配置与限制。
最后修改于 2026年7月13日