> ## 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 的基本概念、3 種模式比較、快速開始(Client 模式)與主要功能。

VOICEVOX for Laravel 是可在 Laravel 中使用 VOICEVOX 語音合成功能的套件。可從文字產生日語語音。

<Tip>
  建議先從 Client 模式開始,設定最快。若環境可用 FFI,之後可分階段轉移至 Native 模式或 Engine API 模式。
</Tip>

## 3 種使用模式

| 模式            | 執行方式                         | FFI | 適合用途                       | 指南                                                                                                                        |
| ------------- | ---------------------------- | --- | -------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Client 模式     | 對官方 VOICEVOX 引擎進行 HTTP 連線    | 不需  | 先嘗試、Docker 環境、無法使用 FFI 的環境 | [Client Talk](/zh-TW/packages/laravel-voicevox/client-talk) / [Client Song](/zh-TW/packages/laravel-voicevox/client-song) |
| Native 模式     | 以 PHP FFI 直接呼叫 VOICEVOX CORE | 需要  | 高速化、離線執行、CLI 工具整合          | [Native Talk](/zh-TW/packages/laravel-voicevox/native-talk) / [Native Song](/zh-TW/packages/laravel-voicevox/native-song) |
| Engine API 模式 | 由 Laravel 提供 VOICEVOX 相容 API | 需要  | 公開 API 伺服器、多 client 整合     | [Engine Talk](/zh-TW/packages/laravel-voicevox/engine-talk) / [Engine Song](/zh-TW/packages/laravel-voicevox/engine-song) |

## 快速開始

Client 模式的步驟。

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

    詳細請確認 [安裝與設定](/zh-TW/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);
```

### 使用者字典與預設集

Client 模式下可透過 `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-TW/packages/laravel-voicevox/installation)
* [設定參考](/zh-TW/packages/laravel-voicevox/configuration)
* [Client Talk](/zh-TW/packages/laravel-voicevox/client-talk)
* [Client Song](/zh-TW/packages/laravel-voicevox/client-song)
* [Client 模式 - 使用者字典](/zh-TW/packages/laravel-voicevox/client-user-dict)
* [Client 模式 - 預設集](/zh-TW/packages/laravel-voicevox/client-presets)
* [Native Talk](/zh-TW/packages/laravel-voicevox/native-talk)
* [Engine Talk](/zh-TW/packages/laravel-voicevox/engine-talk)
* [Native 模式 - 使用者字典](/zh-TW/packages/laravel-voicevox/native-user-dict)
* [Native 模式 - 預設集](/zh-TW/packages/laravel-voicevox/native-presets)
* [AI SDK 整合](/zh-TW/packages/laravel-voicevox/ai-sdk)


## Related topics

- [安裝與設定 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/installation.md)
- [Client 模式:Talk(文字語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-talk.md)
- [Laravel Nightwatch 入門](/zh-TW/blog/nightwatch-introduction.md)
- [VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/index.md)
- [React 入門 — 搭配 Inertia × Laravel 使用的基礎知識](/zh-TW/blog/react-introduction.md)