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

# 엔진 API 모드: 송 (노래 음성 합성) - VOICEVOX for Laravel

> Laravel 앱 내의 VOICEVOX 엔진 호환 API에서 노래 합성 엔드포인트를 사용하는 절차를 설명합니다.

## 엔진 API로 노래 부르게 하기

엔진 API 모드는 공식 VOICEVOX 엔진 호환의 송 엔드포인트도 제공합니다.

<Info>
  엔진 API의 기본 셋업은 [엔진 API: 토크](/ko/packages/laravel-voicevox/engine-talk)를 먼저 확인하세요.
</Info>

## 사전 준비

노래 모델을 사용하기 위해 `config/voicevox.php`의 `core.vvms`에 `s0.vvm`이 포함되어 있는지 확인합니다 (기본값으로 포함됨).

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

## Laravel판 엔진 실행

```shell theme={null}
php artisan serve --port=50513
```

## 노래 음성 생성

### 1. `sing_frame_audio_query` 생성

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/sing_frame_audio_query?speaker=6000" \
  -H "Content-Type: application/json" \
  -d '{
    "notes": [
      {"id": "a", "key": null, "frame_length": 15, "lyric": ""},
      {"id": "b", "key": 60, "frame_length": 94, "lyric": "ド"},
      {"id": "c", "key": 62, "frame_length": 94, "lyric": "レ"},
      {"id": "d", "key": 64, "frame_length": 187, "lyric": "ミ"},
      {"id": "e", "key": null, "frame_length": 2, "lyric": ""}
    ]
  }' \
  > frame_audio_query.json
```

`speaker`에는 `sing` 또는 `singing_teacher` 종별의 스타일 ID (예: 6000)를 지정합니다.

### 2. `frame_synthesis`로 음성 합성

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/frame_synthesis?speaker=3001" \
  -H "Content-Type: application/json" \
  -d @frame_audio_query.json \
  > song.wav
```

`speaker`에는 `sing` 또는 `frame_decode` 종별의 스타일 ID (예: 3001)를 지정합니다.

## Laravel 클라이언트에서 사용

Laravel판 엔진을 향해 `Voicevox::song()`을 이용할 수 있습니다.

```php theme={null}
// config/voicevox.php
'client' => [
    'url' => env('VOICEVOX_URL', 'http://127.0.0.1:50513'),
],
```

```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('engine', 'song.wav');
```

## F0·볼륨 조정 엔드포인트

```shell theme={null}
curl -s -X POST "http://127.0.0.1:50513/sing_frame_f0?speaker=6000" \
  -H "Content-Type: application/json" \
  -d '{"score": {...}, "frame_audio_query": {...}}' \
  > f0.json

curl -s -X POST "http://127.0.0.1:50513/sing_frame_volume?speaker=6000" \
  -H "Content-Type: application/json" \
  -d '{"score": {...}, "frame_audio_query": {...}}' \
  > volume.json
```

<Warning>
  F0와 볼륨을 개별적으로 업데이트할 경우 반드시 **F0 → 볼륨** 순서로 실행하세요.
</Warning>

## 송 관련 대응 현황

| 엔드포인트                          | Laravel판 | 폴백 | 비고                   |
| ------------------------------ | -------- | -- | -------------------- |
| `POST /sing_frame_audio_query` | ✅        | ✅  |                      |
| `POST /frame_synthesis`        | ✅        | ✅  |                      |
| `POST /sing_frame_f0`          | ✅        | ✅  |                      |
| `POST /sing_frame_volume`      | ✅        | ✅  | f0 → volume 순으로 업데이트 |
| `GET /singers`                 | ✅        | ✅  |                      |
| `GET /singer_info`             | ✅        | ✅  | 리소스 설치 필요            |

## 다음에 읽어볼 페이지

<Columns cols={3}>
  <Card title="Score와 Note 상세" href="/ko/packages/laravel-voicevox/song-score-note" icon="list-music">
    Song API에서 사용하는 `Score` / `Note`의 상세를 확인합니다.
  </Card>

  <Card title="엔진 API: 토크" href="/ko/packages/laravel-voicevox/engine-talk" icon="message-circle">
    텍스트 음성 합성 엔드포인트의 사용법을 확인합니다.
  </Card>

  <Card title="클라이언트: 송" href="/ko/packages/laravel-voicevox/client-song" icon="music">
    같은 악보를 공식 엔진으로 직접 보내는 모드를 확인합니다.
  </Card>
</Columns>


## Related topics

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