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

# Native 模式:Song(歌聲語音合成)- VOICEVOX for Laravel

> 說明如何在 VOICEVOX for Laravel 的 Native 模式,透過 PHP FFI 直接呼叫 VOICEVOX CORE 進行歌聲語音合成。

## 在 Native 模式讓角色歌唱

Native 模式的歌聲合成使用 PHP FFI 直接呼叫 VOICEVOX CORE。

`Score` 與 `Note` 的組合方式與 Client 模式相同。

## 事前準備

1. 已完成 [安裝與設定](/zh-TW/packages/laravel-voicevox/installation)
2. 已完成 [VOICEVOX Core for PHP](/zh-TW/packages/voicevox-core-php) 的設定
3. 已於 `.env` 設定 `VOICEVOX_CORE_PATH`

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

為使用歌聲模型,請確認 `config/voicevox.php` 的 `core.vvms` 中包含 `s0.vvm`。

## 建立 `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),
]);
```

## 基本用法

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

$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 = song($score, teacher: 6000)
    ->generate(id: 3001);

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

使用相同 `Score`,可在 Client 模式與 Native 模式共用相同譜面。

## 以 `tap()` 重新同步 F0 與音量

Native Song 中 `tap()` 一樣好用。可以調整 `SongAudioQuery` 後直接串接到 `generate()`。

```php theme={null}
use Revolution\Voicevox\Song\SongAudioQuery;
use function Revolution\Voicevox\song;

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

若要分別更新 F0 與音量,請務必依以下順序執行。

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

## 與 Client 模式的差異

| 項目               | Client Song        | Native Song |
| ---------------- | ------------------ | ----------- |
| 引擎啟動             | 需要                 | 不需要         |
| FFI              | 不需                 | 需要          |
| API 入口           | `Voicevox::song()` | `song()`    |
| `Score` / `Note` | 共用                 | 共用          |

<Info>
  FFI 機制請參閱 [PHP FFI](/zh-TW/advanced/ffi);核心 library 單獨的流程請參閱 [VOICEVOX Core for PHP 用法](/zh-TW/packages/voicevox-core-php/usage)。
</Info>

## 下一步閱讀

<Columns cols={3}>
  <Card title="Score 與 Note 詳解" href="/zh-TW/packages/laravel-voicevox/song-score-note" icon="list-music">
    確認 Song 譜面資料的實務管理方式。
  </Card>

  <Card title="Client Song" href="/zh-TW/packages/laravel-voicevox/client-song" icon="music">
    與 HTTP client 版比較差異。
  </Card>

  <Card title="VOICEVOX for Laravel 概觀" href="/zh-TW/packages/laravel-voicevox" icon="book-open">
    集中確認各模式與相關頁面。
  </Card>
</Columns>


## Related topics

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