YuE2 官方可运行示例实战：从 City Lights 歌词到可编辑 ABC 谱的生成、和声改编与符号校验
【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE
examples/目录是 YuE2 仓库自带的可运行输入样例集：song.json提供了一首原创歌曲《City Lights》的歌词与风格请求，melody.abc、score.abc、score-jazz.abc则分别给出了同一段旋律的纯旋律谱、带和声谱与仅更换和弦符号的改编谱。本文以 examples/README.md 为主体，结合 examples/generate.py、skills/yue2-music/scripts/abc_tools.py 与对应测试，完整讲解如何用这些样例在本地生成歌曲、对比两次和声改编，并在无需 GPU 的情况下完成 ABC 谱的结构校验。读完本文，你将掌握 YuE2 三种 conditioning 模式（full/melody/off）的脚本化用法、原生双声部 ABC 方言的结构规范，以及"改谱必校验"的符号级不变量检查方法。
一、样例定位：可运行的输入，而非评测结果
需要首先明确的是，examples/README.md明确声明：这些文件是可运行输入（runnable inputs），不是已记录的 benchmark 或质量结果。也就是说，仓库提供它们的目的，是让你能在pip install .之后立刻跑通生成、改编、校验的完整链路，并以此为模板编写自己的请求，而不是把它当作某种得分或成品的展示。
四个样例文件的分工如下：
| 文件 | 内容 | 用途 |
|---|---|---|
| examples/song.json | 《City Lights》的歌词与风格请求 | 纯文本驱动的歌曲生成入口 |
| examples/melody.abc | 八小节原创旋律（无和弦符号） | 演示--cot melody自由伴奏模式 |
| examples/score.abc | 同一旋律 + 三和弦和声标注 | 演示--cot full带谱生成 |
| examples/score-jazz.abc | 仅更换和弦符号的改编谱 | 用于与score.abc做符号级对比 |
其中melody.abc是一个为歌词量身定制的八小节旋律：每行歌词恰好 7 个音节，每个小节恰好 7 个音符起奏（note onset），歌词与旋律一一对应。这一"每小节七音"的结构在song.json的歌词中可以直观对照——每个乐句恰好 7 个词。
二、请求文件 song.json：歌词、风格与种子
examples/song.json 是一个完整的 YuE2 歌曲请求，字段包括：
{ "id": "city_lights", "style": "English, warm piano pop, expressive female voice, acoustic piano, rounded bass and light drums, lyrical memorable melody, unhurried phrasing, 88 BPM", "lyrics": "[Verse]\nNeon fades along the lane\nFootsteps keep the time of rain\nFold the night and leave it here\nMorning has a sky to clear\n\n[Chorus]\nLet the day come into view\nEvery road begins with you\nHold a little room for light\nWe will sing beyond the night", "cot": "full", "seed": 831001 }各字段含义（与 skills/yue2-music/references/generation-and-covers.md 中的请求字段说明一致）：
id：请求唯一标识，也用作输出目录名。style：风格描述，需覆盖语言、流派、嗓音特征、乐器、速度等，例如这里同时写了"English"、"warm piano pop"、"88 BPM"。从源码 examples/generate.py 可以看到，脚本会把abc与cot字段合并进该请求后整体传给 pipeline。lyrics：带[Verse]/[Chorus]分节标签的完整歌词。cot：conditioning 模式，取值为full/melody/off。seed：固定为831001。README 特别提醒：种子有助于对比，但并不能保证跨设备、跨软件版本输出完全一致。
YuE2 的请求还接受abc、cfg_scale等字段；tags是style的别名（若同时提供两者必须一致）。请求中没有reference_audio、phonemes、bpm、negative_prompt等字段，速度和拍号应当写进 ABC 谱并在style中保持一致描述。
三、三份 ABC 谱：同一旋律的三种和声形态
三份 ABC 文件共享同一骨架——这正是它们适合做对比实验的原因。以 examples/score.abc 为例：
X:1 T: M:4/4 L:1/16 Q:1/4=88 V: Vocal clef=treble name="Vocal Melody" snm="Vocal" V: Ins clef=treble name="Ins Melody" snm="Inst." K:C % verse V: Vocal "C"E2G2A2G2E2D2C4|"G"D2E2G2E2D2C2D4|"Am"E2G2A2c2B2A2G4|"F"F2E2D2E2G2E2C4| V: Ins Z4| % chorus V: Vocal "C"G2A2c2B2A2G2E4|"F"F2A2G2E2D2E2G4|"G"A2c2B2A2G2E2D4|"C"E2G2A2G2E2D2C4| V: Ins Z4|关键结构解读：
- 头部（Header）：
M:4/4为拍号，L:1/16为默认音符长度单位（十六分音符），Q:1/4=88为四分音符 = 88 BPM。这部分是 YuE2 原生谱的固定格式。 - 双声部（Two voices）：
V: Vocal与V: Ins两个声部。Vocal 承载主旋律（和声符号也写在 Vocal 声部），Ins 声部在本例中全是整小节休止Z4|（即 4 个整小节休止的压缩写法）。 - 和弦符号：用引号包裹的小节首和弦标记，如
"C"、"G"、"Am"、"F"。
三份谱的差异仅在和声层：
- examples/melody.abc：完全没有和弦符号，Vocal 声部只有音高序列
E2G2A2G2E2D2C4|...，用于--cot melody自由伴奏。 - examples/score.abc：在每小节起始处加入三和弦，verse 为
C → G → Am → F，chorus 为C → F → G → C，是典型的流行和声进行。 - examples/score-jazz.abc：只更换和弦符号，旋律音符、节奏、小节完全不动，改为
Cmaj7 → G7 → Am7 → Fmaj7（chorus 为Cmaj7 → Fmaj7 → G7 → Cmaj7），演示了"仅改和声色彩"的改编方式。
注意：YuE2 使用的并非通用 ABC 方言，而是受限的双声部 ABC 子集。从 abc_tools.py 可以看到其约束：声部名必须是Vocal和Ins，音长单位分母必须是 2 的幂，支持的音长取值集合为{1, 2, 3, 4, 6, 8, 12, 16, 24, 32, 48}，和弦质量（quality）被白名单限定为m, dim, aug, 7, maj7, m7, dim7, m7b5, sus4, sus2, 6, m6, 7sus4, m(maj7)等，不支持连音符（triplet）、重复小节线等通用 ABC 特性——超出即报错（fail closed）。
四、用 generate.py 生成歌曲与两次和声对比
按 examples/README.md 的指引，在仓库根目录执行pip install .后即可运行。三个核心命令如下：
# 从歌词和风格创建一首歌及其谱面。 python examples/generate.py --output outputs/create # 用仓库自带的旋律做自由伴奏实现（无和弦约束）。 python examples/generate.py --abc-file examples/melody.abc \ --cot melody --output outputs/melody # 用同一旋律、歌词、风格和种子对比两种和声编配。 python examples/generate.py --abc-file examples/score.abc \ --cot full --output outputs/harmony-original python examples/generate.py --abc-file examples/score-jazz.abc \ --cot full --output outputs/harmony-edited第一条命令不传--abc-file，pipeline 将完全依赖song.json中的cot: "full"让 YuE2 的符号规划器（symbolic planner）自行规划旋律与和弦；后两条命令则把外部 ABC 谱注入请求，此时外部 ABC 会绕过符号规划器，不会再有第二个规划器去"修复"你的谱子——改了什么，就按什么生成。
4.1 参数说明（来自 generate.py 源码）
从 examples/generate.py 的 argparse 定义可以看到完整参数：
| 参数 | 默认值 | 说明 |
|---|---|---|
--request | 脚本同目录下的song.json | 请求 JSON 路径，可替换为自己的请求文件 |
--abc-file | 无 | 注入请求的 ABC 谱路径（读为文本后写入request["abc"]） |
--cot | 无（沿用请求文件中的值） | full/melody/off三选一 |
--output | 必填 | 输出目录 |
--model | m-a-p/YuE2-3B | 主模型名称或本地快照目录 |
--vae | m-a-p/YuE2-Vae | VAE 解码器名称或本地快照目录 |
--revision | 无 | 主模型版本锁定（Hub 快照时使用） |
--vae-revision | 无 | VAE 版本锁定 |
脚本内的两条硬性校验值得注意：
- 拒绝已存在的输出目录：
args.output.exists()时直接parser.error("Choose a fresh output directory...")，保证每次运行不会覆盖旧结果。 - ABC 与
cot=off互斥：如果提供了--abc-file而--cot off，会报错A supplied score requires full or melody mode.——带谱生成必须处于full（保留和声）或melody（只用旋律、自由伴奏）模式。
4.2 运行行为与退出码
脚本随后构造YuE2Pipeline并执行：
from yue2 import YuE2Pipeline with YuE2Pipeline.from_pretrained( args.model, vae=args.vae, revision=args.revision, vae_revision=args.vae_revision, device="cuda", ) as pipe: song = pipe(**request) song.save_artifacts(args.output) print(json.dumps({"audio": str(args.output / "audio.flac"), "truncated": song.truncated})) return 1 if any(song.truncated.values()) else 0- 保留全部原生产物：
save_artifacts会写出audio.flac、score.abc、语义 token、latent.npy、请求、配置、时间信息、解码器标识与哈希等。 - 截断即非零退出：
song.truncated中任何一项为真（包括 ABC 截断与语义截断），进程就返回退出码 1。README 明确指出status="complete"并不代表未截断，因此脚本用退出码强制暴露截断问题，方便在 CI 或批处理中拦截。
五、无 GPU 的符号校验：inspect 与 compare
生成音频需要 GPU，但校验谱面结构不需要。skills/yue2-music/scripts/abc_tools.py 是纯标准库实现的解析器，README 给出的无 GPU 校验命令为：
python skills/yue2-music/scripts/abc_tools.py inspect examples/score.abc python skills/yue2-music/scripts/abc_tools.py compare \ examples/score.abc examples/score-jazz.abcinspect：解析并校验谱面，输出 JSON 报告，包含 BPM、单位音长、总时长（以四分音符计）、名义时长（秒），以及每个声部的实际发音音符（onset、MIDI 音高、时值）、和弦事件、调号时间线与小节网格。compare：对两份谱做符号级对比，验证音符音高、节奏、拍号、速度是否一致，只报告差异。命令的退出码也有语义：match为 False 时返回 1，语法/结构错误返回 2。
5.1 对比的判定维度
从 abc_tools.py 的 compare 实现 可以看出，"一致"的判定基于三个不变量：
- 声部的小节拍号/时间网格（
bars）必须逐条相等； - 声部的实际发音音符序列（
notes，即 onset、音高、时值三元组）必须逐条相等； - 默认情况下四分音符速度（BPM）必须相等（可用
--allow-tempo-change放行）。
这个判定是"按实际发音事件"而非"按字符串"的：例如C32|与C16-C16|（连音线跨小节连接）在 compare 看来是同一首歌（测试test_equal_sound_different_ties），而C16z16|与z16C16|因起奏位置不同会被判定为不同（测试test_onset_changes）。换句话说，compare 回答的是"乐谱层面的音高、节奏、拍号、速度是否保留"，而不是"生成音频是否好听"。
这也是 README 最后一句提醒的核心：compare能验证score.abc与score-jazz.abc的旋律完全一致、只有和声不同，但要评估实际音响效果，仍需要聆听或音频转写（ASR/转录）作为独立证据——符号检查与音频质量是两回事。
5.2 源码与测试佐证
abc_tools.py还提供第三个子命令strip-chords（移除和弦符号并保留头部引号），用于翻唱流程中将转录谱转为纯旋律谱；compare额外支持--voices（对比单个声部）与--allow-tempo-change。这些行为由 tests/test_skill_abc_tools.py 覆盖，例如：
test_octave_accidental_propagation：变音记号按字母名跨八度传播；test_bar_accidental_reset：小节结束变音自动还原；test_crossbar_tie：跨小节连音线正确合并时值；test_bad_input_cases：包括Z1|、Z5|、C/2（连音符）、C32||（双小节线）、非法和弦"C13"、非法调K:Cmix等在内的 30 余种非法输入均被判定为AbcError。
如果你要自行改编谱面（例如把score-jazz.abc的和弦再换成 sus4 或 m7b5），建议沿用同一条校验链路：inspect确认语法与结构 →compare --voices Vocal（或both）确认旋律不变量 → 再进入生成，这样能把"谱面错误"与"生成质量问题"在归因上彻底分开。
六、注意事项与最佳实践总结
- 固定版本以便复现：使用
--revision与--vae-revision锁定模型版本，并在每次运行时记录包版本、模型 revision 与权重哈希（generation-and-covers.md亦如此要求）。 - 种子只辅助对比，不保证逐位一致：
song.json中seed: 831001固定，是为了让harmony-original与harmony-edited两次运行的差异尽可能只来自和声；不同设备、驱动或软件版本下音频仍可能有差异。 - 每次生成使用全新输出目录：
generate.py会主动拒绝已存在的目录，这是为了防止无意覆盖上一版原生产物。 - 退出码即截断信号：
return 1 if any(song.truncated.values()) else 0意味着只要发生截断，命令就以非零状态结束——批处理脚本应把它视为失败而非忽略。 - 改谱必校验、校验不替代聆听：
compare只能证明乐谱层面的不变量，实际音乐的完整性需要结合音频时长、结尾听感和转写结果共同判断。
以examples/为起点，你可以把song.json替换成自己的歌词与风格，把score.abc替换成自己编辑过的谱面，用同样的四步走完 YuE2 的完整工作流：文本生成（full/melody/off）→ 谱面导出与编辑 → 符号校验（inspect/compare）→ 有条件地再生成。这也正是仓库中 skills/yue2-music/SKILL.md 所描述的"可复现歌曲与可听对比"工作流的简化落地版。
【免费下载链接】YuEYuE2: frontier music generation with symbolic planning, zero-shot covers, and agentic music editing.项目地址: https://gitcode.com/GitHub_Trending/yue/YuE
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
