> ## 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 模式:Song(歌聲語音合成)- VOICEVOX for Laravel

> 說明如何在 VOICEVOX for Laravel 的 Client 模式,以 Score 與 Note 進行歌聲語音合成。

## 在 Client 模式讓角色歌唱

Client 模式的歌聲合成使用官方 VOICEVOX 引擎的 `sing_frame_audio_query` 與 `frame_synthesis` API。

與 Talk 不同,需要先建立 `Score` 與 `Note`。

## 事前準備

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

## 建立 `Score` 與 `Note`

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

$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),
]);
```

| 參數       | 型別          | 說明               |
| -------- | ----------- | ---------------- |
| `length` | `int`       | Frame length     |
| `lyric`  | `string`    | 歌詞。空字串或省略為休止符    |
| `key`    | `int\|null` | MIDI note number |

<Tip>
  使用 `Note::len($ticks, $bpm)` 可以從 MIDI 的 ticks 與 BPM 計算 frame length。將四分音符視為 480 ticks 較好理解。
</Tip>

## 基本用法

```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(480, 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, teacher: 6000)
    ->generate(id: 3001);

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

### `teacher` 與 `id`

* `teacher`: 傳給 `sing_frame_audio_query` 的 style ID。目前只有 6000 一個,故預設為 6000。
* `generate(id:)`: 傳給 `frame_synthesis` 的 style ID

可用的歌聲 speaker 清單可透過 `singers()` 取得。

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

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

## 使用 `tap()` 調整 F0 與音量

Song 中 `tap()` 的用途特別清楚,可以先調整 `SongAudioQuery` 後再送入 `generate()`。

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

$response = Voicevox::song($score, teacher: 6000)
    ->tap(function (SongAudioQuery $song) {
        $song->sync();
    })
    ->generate(id: 3001);
```

若要分別更新 F0 與音量,請依 **F0 → 音量** 順序執行。

```php theme={null}
->tap(function (SongAudioQuery $song) {
    $song->updateF0();
    $song->updateVolume();
})
```

想在變更 Score 後重新同步,`tap()` 也很方便。

```php theme={null}
->tap(function (SongAudioQuery $song) {
    $song->score->notes[2] = Note::make(length: Note::len(480, 120), lyric: 'ファ', key: 65);
    $song->sync();
})
```

<Info>
  `tap()` 的觀念已整理於 [tap() helper 與 Tappable trait](/zh-TW/advanced/tap)。VOICEVOX for Laravel 是「不改變回傳值,只調整中間物件」的典型範例。
</Info>

## 下一步閱讀

<Columns cols={3}>
  <Card title="Score 與 Note 詳解" href="/zh-TW/packages/laravel-voicevox/song-score-note" icon="list-music">
    確認 frame length 計算與 JSON 管理模式。
  </Card>

  <Card title="Native Song" href="/zh-TW/packages/laravel-voicevox/native-song" icon="music">
    以 FFI 的 Native 模式使用相同的 `Score`。
  </Card>

  <Card title="VOICEVOX Core for PHP 用法" href="/zh-TW/packages/voicevox-core-php/usage" icon="library">
    確認核心 library 單獨的語音合成流程。
  </Card>
</Columns>


## Related topics

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