> ## 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의 네이티브 모드에서 VOICEVOX CORE를 PHP FFI로 직접 호출해 노래 음성 합성하는 방법을 설명합니다.

## 네이티브 모드에서 노래 부르게 하기

네이티브 모드의 노래 합성에서는 PHP FFI로 VOICEVOX CORE를 직접 호출합니다.

`Score`와 `Note`의 조립 방식은 클라이언트 모드와 공통입니다.

## 사전 준비

1. [설치와 설정](/ko/packages/laravel-voicevox/installation)을 완료했을 것
2. [VOICEVOX Core for PHP](/ko/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`를 사용하면 클라이언트 모드와 네이티브 모드에서 공통 악보를 재사용할 수 있습니다.

## `tap()`으로 F0와 볼륨 재동기화

네이티브 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();
})
```

## 클라이언트 모드와의 차이

| 항목               | 클라이언트 Song         | 네이티브 Song |
| ---------------- | ------------------ | --------- |
| 엔진 실행            | 필요                 | 불필요       |
| FFI              | 불필요                | 필요        |
| API 진입점          | `Voicevox::song()` | `song()`  |
| `Score` / `Note` | 공통                 | 공통        |

<Info>
  FFI의 구조는 [PHP FFI](/ko/advanced/ffi), 코어 라이브러리 단독 흐름은 [VOICEVOX Core for PHP 사용법](/ko/packages/voicevox-core-php/usage)을 참조하세요.
</Info>

## 다음에 읽어볼 페이지

<Columns cols={3}>
  <Card title="Score와 Note 상세" href="/ko/packages/laravel-voicevox/song-score-note" icon="list-music">
    Song 악보 데이터의 실용적인 관리 방법을 확인합니다.
  </Card>

  <Card title="클라이언트 Song" href="/ko/packages/laravel-voicevox/client-song" icon="music">
    HTTP 클라이언트 버전과의 차이를 비교합니다.
  </Card>

  <Card title="VOICEVOX for Laravel 개요" href="/ko/packages/laravel-voicevox" icon="book-open">
    각 모드와 관련 페이지를 함께 확인합니다.
  </Card>
</Columns>


## Related topics

- [클라이언트 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/client-song.md)
- [네이티브 모드: 토크 (텍스트 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-talk.md)
- [네이티브 모드 - 프리셋 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-presets.md)
- [엔진 API 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/engine-song.md)
- [네이티브 모드 - 사용자 사전 - VOICEVOX for Laravel](/ko/packages/laravel-voicevox/native-user-dict.md)