> ## Documentation Index > Fetch the complete documentation index at: https://kawax.biz/llms.txt > Use this file to discover all available pages before exploring further. # .vvproj 文件规范 - VOICEVOX for Laravel > 整理直接使用 VOICEVOX 编辑器的 .vvproj JSON，从 Laravel 生成 Talk / Song 的实用规范。 ## 目的 直接利用 VOICEVOX 编辑器的 `.vvproj`，让 Laravel 能重新生成 Talk / Song。 ## 顶层结构 `.vvproj` 是 UTF-8 JSON。Talk 与 Song 保存在同一个文件中。 ```json theme={null} { "appVersion": "0.25.2", "talk": { "audioKeys": [], "audioItems": {} }, "song": { "tpqn": 480, "tempos": [], "timeSignatures": [], "tracks": {}, "trackOrder": [] } } ``` | Key | 内容 | | ------------ | ------------------------------------ | | `appVersion` | 保存时的编辑器版本 | | `talk` | Talk 用数据（`audioKeys` + `audioItems`） | | `song` | Song 用数据（速度、拍号、轨道群） | ## `talk` 部分 `talk.audioKeys` 是有序数组，`talk.audioItems` 是以 ID 为键的 Record。 ```json theme={null} { "audioKeys": ["audio-item-uuid"], "audioItems": { "audio-item-uuid": { "text": "ずんだもんなのだ", "voice": { "engineId": "engine-uuid", "speakerId": "speaker-uuid", "styleId": 3 }, "query": { "accentPhrases": [], "speedScale": 1, "pitchScale": 0 }, "presetKey": "preset-uuid" } } } ``` ### TalkAudioItem | Key | 内容 | | ----------------- | ---------------------------------------------------------------------------- | | `text` | 输入文本 | | `voice.engineId` | 引擎 ID（对应 `/engine_manifest`） | | `voice.speakerId` | 说话人 UUID | | `voice.styleId` | Style ID。可直接传给 `/synthesis?speaker={styleId}` | | `query` | 等同于 `AudioQuery` | | `presetKey` | 编辑器的预设 ID。Laravel 侧的预设请参见 [预设](/zh/packages/laravel-voicevox/native-presets) | 如果 `.vvproj` 已保存有 `query`，则可以不再执行 `/audio_query`，直接进入合成。 ### `accentPhrases` | Key | 内容 | | ----------------- | ----------------------------- | | `moras` | mora 数组（`consonant` 类字段可能被省略） | | `accent` | 重音位置（从 1 开始） | | `pauseMora` | 在标点等处插入静音时可能会存在 | | `isInterrogative` | 疑问句标志 | ## `song` 部分 ```json theme={null} { "tpqn": 480, "tempos": [{ "position": 0, "bpm": 120 }], "timeSignatures": [{ "measureNumber": 1, "beats": 4, "beatType": 4 }], "tracks": { "track-uuid": { "name": "無名トラック", "singer": { "engineId": "engine-uuid", "styleId": 3003 }, "notes": [] } }, "trackOrder": ["track-uuid"] } ``` | Key | 内容 | | ---------------- | ------------------------------ | | `tpqn` | Ticks Per Quarter Note。标准为 480 | | `tempos` | 速度表（`position` 为 tick） | | `timeSignatures` | 拍号表（`measureNumber` 从 1 开始） | | `tracks` | 以 Track ID 为键的 Record | | `trackOrder` | 显示/播放顺序。需与 `tracks` 的键集合一致 | ### Track | Key | 内容 | | ---------------------------------- | ---------------------------------------------- | | `singer.styleId` | 最终传给 `/frame_synthesis?speaker={styleId}` 的 ID | | `notes` | 音符数组 | | `keyRangeAdjustment` | 以半音为单位的调号调整 | | `volumeRangeAdjustment` | 音量调整 | | `pitchEditData` / `volumeEditData` | 按帧的编辑数据 | | `phonemeTimingEditData` | 每个 Note ID 的音素时长编辑 | | `solo` / `mute` | 用于判定播放对象轨道 | ### Note | Key | 内容 | | ------------ | --------- | | `id` | 音符 ID（唯一） | | `position` | 音符开始 tick | | `duration` | 音符长度 tick | | `noteNumber` | MIDI 音符编号 | | `lyric` | 歌词 | ## tick、秒、帧的转换 在单一速度下按以下方式换算。 ```text theme={null} seconds = ticks / tpqn * 60 / bpm frames = round(seconds * frameRate) ``` 在存在速度变化时，将 `tempos` 按 `position` 升序累加各区间。 ```php theme={null} function ticksToSeconds(int $targetTick, int $tpqn, array $tempos): float { $seconds = 0.0; $currentTick = 0; foreach ($tempos as $index => $tempo) { $nextTick = $tempos[$index + 1]['position'] ?? $targetTick; $segmentEnd = min($targetTick, $nextTick); if ($segmentEnd <= $currentTick) { break; } $bpm = $tempo['bpm']; $seconds += (($segmentEnd - $currentTick) / $tpqn) * (60 / $bpm); $currentTick = $segmentEnd; } return $seconds; } ``` 使用 `Note::len()` helper 将 tick 转换为帧长的实现请参考 [Score 与 Note 详解](/zh/packages/laravel-voicevox/song-score-note)。 ## Song 音频生成流程 ```mermaid theme={null} flowchart TD A["1. 按 trackOrder 顺序取出 tracks"] --> B["2. 通过 solo/mute 决定生成对象"] B --> C["3. 将 notes 按 position 升序排列"] C --> D["4. 在首尾追加休止符并构建 Score"] D --> E["5. tick→秒→frame 得到 frame_length"] E --> F["6. sing_frame_audio_query→sing_frame_f0→sing_frame_volume"] F --> G["7. 通过 frame_synthesis 生成 WAV"] ``` ## 直接编辑时的注意事项 * 必须使 `tracks` 的键集合与 `trackOrder` 一致 * `talk.audioKeys` 与 `talk.audioItems` 同样需要保持同步 * 保持 `position >= 0`、`duration >= 1`、`noteNumber` 处于 `0..127` * `tempos[0].position` 通常为 `0`，`timeSignatures[0].measureNumber` 通常为 `1` * 未知的 key 尽可能保留并重新保存，以避免破坏与未来版本的兼容性 ## Laravel 代码示例 以下是读取 `.vvproj` 并生成 Talk 与 Song 的最小示例。 ```php theme={null} use Illuminate\Support\Facades\Storage; use Revolution\Voicevox\Client\TalkAudioQuery; use Revolution\Voicevox\Song\Note; use Revolution\Voicevox\Song\Score; use Revolution\Voicevox\Voicevox; $project = json_decode( Storage::disk('local')->get('voicevox/sample.vvproj'), true, flags: JSON_THROW_ON_ERROR, ); // Talk：直接使用已保存的 query 进行合成 foreach ($project['talk']['audioKeys'] as $audioKey) { $item = $project['talk']['audioItems'][$audioKey]; Voicevox::talk($item['text'], id: $item['voice']['styleId']) ->tap(fn (TalkAudioQuery $talk) => $talk->audioQuery = array_replace($talk->audioQuery, $item['query'])) ->generate(id: $item['voice']['styleId']) ->storeAs('vvproj/talk', "{$audioKey}.wav"); } // Song：这里将第一条轨道的 duration 转为 frame_length 后生成 $trackId = $project['song']['trackOrder'][0]; $track = $project['song']['tracks'][$trackId]; $bpm = $project['song']['tempos'][0]['bpm'] ?? 120; $score = Score::make([ Note::make(length: 15, lyric: '', key: null), ...collect($track['notes'])->map( fn (array $note) => Note::make( length: Note::len(ticks: $note['duration'], bpm: $bpm), lyric: $note['lyric'] ?? 'ら', key: $note['noteNumber'], id: $note['id'] ?? null, ), )->all(), Note::make(length: 2, lyric: '', key: null), ]); Voicevox::song($score, teacher: 6000) ->generate(id: $track['singer']['styleId']) ->storeAs('vvproj/song', "{$trackId}.wav"); ``` ## Related topics - [引擎 API 集成应用开发指南 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/app-guide.md) - [用 Laravel 构建 MCP 服务器](/zh/advanced/mcp-server.md) - [Score 与 Note 详解 - VOICEVOX for Laravel](/zh/packages/laravel-voicevox/song-score-note.md) - [Laravel MCP](/zh/mcp.md) - [Laravel Boost](/zh/boost.md)