> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# Client 模式:Talk(文字語音合成)- VOICEVOX for Laravel

> 說明如何在 VOICEVOX for Laravel 的 Client 模式連線至官方 VOICEVOX 引擎進行文字語音合成。

## 什麼是 Client 模式

Client 模式會向官方 VOICEVOX 引擎發送 HTTP 請求以產生語音。

不需要 FFI,是最容易入門嘗試的模式。

<Info>
  若尚未導入,請先確認 [安裝與設定](/zh-TW/packages/laravel-voicevox/installation)。
</Info>

## 事前準備

<Steps>
  <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="必要時設定連線 URL">
    ```dotenv theme={null}
    VOICEVOX_URL=http://127.0.0.1:50021
    ```
  </Step>
</Steps>

在有 GPU 的環境也可使用 GPU 映像。

## 基本用法

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

$response = Voicevox::talk('我喜歡 Laravel', id: 1)
    ->generate(id: 1);

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

## Style ID 指定

`talk()` 與 `generate()` 都可以傳入 style ID。

* `talk(id:)`: 建立 `audio_query` 時的 style
* `generate(id:)`: 進行語音合成時的 style

一般會指定相同的值。

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

$response = Voicevox::talk('ずんだもんなのだ', id: 1)
    ->generate(id: 1);
```

可用的 speaker 清單可透過 `speakers()` 取得。

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

$speakers = Voicevox::speakers();
```

## 使用 `tap()` 調整 Audio Query

本套件在 `generate()` 之前會傳回 `TalkAudioQuery`,因此以 `tap()` 只植入副作用的寫法能自然對應。

```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);
```

<Tip>
  `tap()` 只進行 query 的微調,回傳值可直接傳給下一個 `generate()`。思路詳細整理於 [tap() helper 與 Tappable trait](/zh-TW/advanced/tap)。
</Tip>

## 英文自動片假名轉換

Client 模式下 `enable_katakana_english` 為啟用,含英文的文字會自動修正為偏片假名的讀音。

```php theme={null}
$response = Voicevox::talk('I love Laravel', id: 1)
    ->generate(id: 1);
```

若要停用,可在第 3 個參數傳入 `false`。

```php theme={null}
$response = Voicevox::talk('I love Laravel', id: 1, enableKatakanaEnglish: false)
    ->generate(id: 1);
```

## 儲存回應

```php theme={null}
$response = Voicevox::talk('測試', id: 1)->generate(id: 1);

$wav = $response->content();
$path = $response->storeAs('client', 'talk.wav');
$path = $response->storeAs('client', 'talk.wav', disk: 's3');
```

## 下一步閱讀

<Columns cols={2}>
  <Card title="Client Song" href="/zh-TW/packages/laravel-voicevox/client-song" icon="music">
    以歌聲合成建立 `Score` 與 `Note`。
  </Card>

  <Card title="VOICEVOX Core for PHP" href="/zh-TW/packages/voicevox-core-php/usage" icon="library">
    若要使用 FFI,可一併確認核心 library 端的用法。
  </Card>
</Columns>


## Related topics

- [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)
- [Engine API 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/engine-song.md)
- [Client 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/client-song.md)
- [Native 模式:Song(歌聲語音合成)- VOICEVOX for Laravel](/zh-TW/packages/laravel-voicevox/native-song.md)