> ## 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 模式：Song（歌声合成） - VOICEVOX for Laravel

> 介绍在 Laravel 应用内 VOICEVOX 引擎兼容 API 中使用歌声合成端点的步骤。

## 通过引擎 API 让它唱歌

引擎 API 模式也提供与官方 VOICEVOX 引擎兼容的 Song 端点。

<Info>
  关于引擎 API 的基本配置，请先查看 [引擎 API：Talk](/zh/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` 类型的 Style 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` 类型的 Style ID（例如 3001）。

## 从 Laravel 客户端使用

可以将 `Voicevox::song()` 指向 Laravel 版引擎。

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

## Song 相关端点的支持情况

| 端点                             | Laravel 版 | Fallback | 备注                 |
| ------------------------------ | --------- | -------- | ------------------ |
| `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="/zh/packages/laravel-voicevox/song-score-note" icon="list-music">
    了解 Song API 中使用的 `Score` / `Note` 详情。
  </Card>

  <Card title="引擎 API：Talk" href="/zh/packages/laravel-voicevox/engine-talk" icon="message-circle">
    了解文本语音合成端点的用法。
  </Card>

  <Card title="客户端：Song" href="/zh/packages/laravel-voicevox/client-song" icon="music">
    了解将相同乐谱直接发给官方引擎的模式。
  </Card>
</Columns>


## Related topics

- [客户端模式：Song（歌声合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/client-song.md)
- [原生模式：Song（歌声合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/native-song.md)
- [引擎 API 模式：Talk（文本语音合成） - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/engine-talk.md)
- [VOICEVOX for Laravel](/zh/packages/laravel-voicevox/index.md)
- [安装与配置 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/installation.md)