> ## 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 的導入方式、依 FFI 有無的安裝、設定檔、.env、引擎資源的準備。

## 要安裝什麼

VOICEVOX for Laravel 需要的追加套件與本機設定會依想使用的模式而異。

<Tabs>
  <Tab title="僅 Client">
    若只要以 HTTP 連線至官方 VOICEVOX 引擎,只需 `revolution/laravel-voicevox` 即可開始。

    ```shell theme={null}
    composer require revolution/laravel-voicevox
    ```
  </Tab>

  <Tab title="也使用 Native / Engine API">
    在使用 FFI 的模式中,一併安裝 `revolution/voicevox-core`。

    ```shell theme={null}
    composer require revolution/laravel-voicevox revolution/voicevox-core
    ```
  </Tab>
</Tabs>

## 需求

| 項目            | 內容                        |
| ------------- | ------------------------- |
| PHP           | 8.3+                      |
| Laravel       | 12+                       |
| 必要擴充          | `ext-zip`                 |
| FFI `ext-ffi` | Native 模式 / Engine API 需要 |

<Warning>
  包含 Laravel Cloud 在內的一般 Web 伺服器上 FFI 為停用。Native 模式與 Engine API 請於 **本機 CLI** 嘗試。
</Warning>

## 設定步驟

<Steps>
  <Step title="安裝套件">
    依想使用的模式以 Composer 導入。Native 模式與 Engine API 也需要 [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php)。
  </Step>

  <Step title="發佈設定檔">
    ```shell theme={null}
    php artisan vendor:publish --tag="voicevox-config"
    ```
  </Step>

  <Step title="設定 .env">
    若只用 Client 模式,設定 `VOICEVOX_URL`;使用 FFI 時設定 `VOICEVOX_CORE_PATH`。
  </Step>

  <Step title="必要時安裝引擎資源">
    使用 `/speaker_info` 或 `/singer_info` 時需要額外資源。
  </Step>
</Steps>

## `config/voicevox.php`

所有設定項目可於 [設定參考](/zh-TW/packages/laravel-voicevox/configuration) 確認。

```php theme={null}
return [
    'client' => [
        'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50021'),
        'core_version' => env('VOICEVOX_CLIENT_CORE_VERSION'),
    ],

    'core' => [
        'path' => env('VOICEVOX_CORE_PATH'),
        'dict' => env('VOICEVOX_CORE_DICT_PATH', 'dict/open_jtalk_dic_utf_8-1.11'),
        'models' => env('VOICEVOX_CORE_MODELS_PATH', 'models/vvms'),
        'vvms' => ['0.vvm', '9.vvm', 's0.vvm'],
    ],

    'engine' => [
        'disabled' => env('VOICEVOX_ENGINE_DISABLED', false),
        'fallback_url' => env('VOICEVOX_ENGINE_FALLBACK_URL', 'http://127.0.0.1:50021'),
    ],
];
```

## 最低必要的 `.env`

### 僅 Client 模式

若以預設的 `http://127.0.0.1:50021` 啟動官方引擎則不需追加設定。

```dotenv theme={null}
VOICEVOX_URL=http://127.0.0.1:50021
```

### Native 模式 / Engine API

```dotenv theme={null}
VOICEVOX_CORE_PATH=/path/to/voicevox_core/
```

<Info>
  `VOICEVOX_CORE_PATH` 的內容需依 [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php) 的步驟準備。library 本體、OpenJTalk 字典、模型檔案的放置也請於該處確認。
</Info>

## 啟用 FFI

CLI 中通常可直接使用。

若要於本機啟動 Laravel 版引擎 API,請於 `php.ini` 啟用 FFI。

```ini theme={null}
ffi.enable=true
```

FFI 的機制與限制整理於 [PHP FFI](/zh-TW/advanced/ffi)。

## 安裝引擎資源

使用 `/speaker_info` 或 `/singer_info` 等資源相關 endpoint 時,需另外導入資源檔案。

```shell theme={null}
php artisan voicevox:install
```

Orchestra Testbench 環境使用以下指令。

```shell theme={null}
vendor/bin/testbench voicevox:install
```

## 各模式入口

<Columns cols={2}>
  <Card title="Client Talk" href="/zh-TW/packages/laravel-voicevox/client-talk" icon="message-circle">
    以 Docker 啟動官方 VOICEVOX 引擎進行文字語音合成。
  </Card>

  <Card title="Client Song" href="/zh-TW/packages/laravel-voicevox/client-song" icon="music">
    使用 `Score` 與 `Note` 進行歌聲合成。
  </Card>

  <Card title="Native Talk" href="/zh-TW/packages/laravel-voicevox/native-talk" icon="cpu">
    透過 FFI 直接呼叫 VOICEVOX CORE。
  </Card>

  <Card title="Native Song" href="/zh-TW/packages/laravel-voicevox/native-song" icon="music">
    確認歌聲模型與 `sync()` 的使用時機。
  </Card>
</Columns>

## 參考連結

* [VOICEVOX for Laravel 概觀](/zh-TW/packages/laravel-voicevox)
* [入門](/zh-TW/packages/laravel-voicevox/getting-started)
* [設定參考](/zh-TW/packages/laravel-voicevox/configuration)
* [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php)
* [VOICEVOX Core for PHP 用法](/zh-TW/packages/voicevox-core-php/usage)
* [PHP FFI](/zh-TW/advanced/ffi)


## Related topics

- [Laravel Cashier (Stripe)](/zh-TW/cashier.md)
- [入門 - VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/getting-started.md)
- [Native 模式:Talk(文字語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-talk.md)
- [Engine API 模式:Talk(文字語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/engine-talk.md)
- [Native 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-song.md)