> ## 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

> 汇总 VOICEVOX for Laravel 的基本概念、三种模式的对比、快速开始（客户端模式）与主要功能。

VOICEVOX for Laravel 是一个让你在 Laravel 中使用 VOICEVOX 语音合成功能的包。它可以从文本生成日语语音。

<Tip>
  先从客户端模式开始，配置最简单。如果你的环境支持 FFI，之后可以逐步迁移到原生模式或引擎 API 模式。
</Tip>

## 三种使用模式

| 模式        | 执行方式                          | FFI | 适用场景                       | 指南                                                                                                                  |
| --------- | ----------------------------- | --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| 客户端模式     | 通过 HTTP 连接官方 VOICEVOX 引擎      | 不需要 | 先试用、Docker 环境、无法使用 FFI 的环境 | [Client Talk](/zh/packages/laravel-voicevox/client-talk) / [Client Song](/zh/packages/laravel-voicevox/client-song) |
| 原生模式      | 通过 PHP FFI 直接调用 VOICEVOX CORE | 需要  | 加速、离线执行、CLI 工具集成           | [Native Talk](/zh/packages/laravel-voicevox/native-talk) / [Native Song](/zh/packages/laravel-voicevox/native-song) |
| 引擎 API 模式 | 由 Laravel 提供 VOICEVOX 兼容 API  | 需要  | 公开 API 服务器、多客户端联动          | [Engine Talk](/zh/packages/laravel-voicevox/engine-talk) / [Engine Song](/zh/packages/laravel-voicevox/engine-song) |

## 快速开始

以下是客户端模式的步骤。

<Steps>
  <Step title="安装包">
    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```

    详情请查看 [安装与配置](/zh/packages/laravel-voicevox/installation)。
  </Step>

  <Step title="启动官方引擎">
    ```shell theme={null}
    docker pull voicevox/voicevox_engine:cpu-latest
    docker run --rm -p '127.0.0.1:50021:50021' voicevox/voicevox_engine:cpu-latest
    ```
  </Step>

  <Step title="尝试语音合成">
    ```php theme={null}
    use Revolution\Voicevox\Voicevox;

    $response = Voicevox::talk('こんにちは、Laravel です。', id: 1)->generate(id: 1);
    $response->storeAs('output.wav');
    ```
  </Step>
</Steps>

## 主要功能

### 语音合成（Talk）

```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;
        $talk->audioQuery['pitchScale'] = 0.05;
        $talk->audioQuery['intonationScale'] = 1.5;
        $talk->audioQuery['volumeScale'] = 1.0;
    })
    ->generate(id: 1);
```

### 歌声合成（Song）

```php theme={null}
use Revolution\Voicevox\Song\Note;
use Revolution\Voicevox\Song\Score;
use Revolution\Voicevox\Voicevox;

$score = Score::make([
    Note::make(length: 15),
    Note::make(length: Note::len(ticks: 480, bpm: 120), lyric: 'ド', key: 60),
    Note::make(length: Note::len(480, 120), lyric: 'レ', key: 62),
    Note::make(length: Note::len(960, 120), lyric: 'ミ', key: 64),
    Note::make(length: 2),
]);

$response = Voicevox::song($score)->generate(id: 3001);
```

### 用户词典与预设

在客户端模式下，可通过 `Voicevox` Facade 操作官方引擎侧的用户词典和预设。

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

$uuid = Voicevox::addWord(
    surface: 'Laravel',
    pronunciation: 'ララベル',
    accentType: 3,
);

$presetId = Voicevox::addPreset([
    'id' => 0,
    'name' => 'ゆっくり丁寧',
    'speaker_uuid' => '7ffcb7ce-00ec-4bdc-82cd-45a8889e43ff',
    'style_id' => 1,
    'speedScale' => 0.8,
    'pitchScale' => 0.0,
    'intonationScale' => 1.2,
    'volumeScale' => 1.0,
    'prePhonemeLength' => 0.1,
    'postPhonemeLength' => 0.1,
]);
```

### Laravel AI SDK 集成

```php theme={null}
use Laravel\Ai\Audio;

$audio = Audio::of('こんにちは、Laravel です。')
    ->voice('ずんだもん')
    ->generate();

$audio->storeAs('output.wav');
```

## 下一步

* [安装与配置](/zh/packages/laravel-voicevox/installation)
* [配置参考](/zh/packages/laravel-voicevox/configuration)
* [Client Talk](/zh/packages/laravel-voicevox/client-talk)
* [Client Song](/zh/packages/laravel-voicevox/client-song)
* [客户端模式 - 用户词典](/zh/packages/laravel-voicevox/client-user-dict)
* [客户端模式 - 预设](/zh/packages/laravel-voicevox/client-presets)
* [Native Talk](/zh/packages/laravel-voicevox/native-talk)
* [Engine Talk](/zh/packages/laravel-voicevox/engine-talk)
* [原生模式 - 用户词典](/zh/packages/laravel-voicevox/native-user-dict)
* [原生模式 - 预设](/zh/packages/laravel-voicevox/native-presets)
* [AI SDK 集成](/zh/packages/laravel-voicevox/ai-sdk)


## Related topics

- [安装与配置 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/installation.md)
- [Blaze 包介绍](/zh/blog/blaze-introduction.md)
- [Laravel PAO — 面向 AI 智能体的输出优化工具](/zh/blog/pao-introduction.md)
- [安装](/zh/installation.md)
- [HTTP 客户端](/zh/http-client.md)