raffataff/tunetrack

TuneTrack：使用 tunetrack MCP 工具创作游戏音乐

TuneTrack 是用户自己的音乐工作站。您以音符、和弦、模式和 CC 曲线的形式编写音乐；TuneTrack 通过真实的乐器（用户通过保存的音色、SFZ 采样库或内置 Faust 合成器加载的 VST3 插件）播放它们，进行混音、母带处理并渲染出循环就绪的文件。您无法听到声音，因此您需要依据乐理、工具的分析报告以及钢琴卷帘图像来工作。每一个决定都应是经过深思熟虑的。没有填充循环，没有通用的即兴演奏。

如果工具缺失，说明 MCP 服务器未注册：claude mcp add --scope user tunetrack -- C:\Users\Owner\Documents\TuneTrack\.venv\Scripts\tunetrack-mcp.exe。

1. 首先了解项目

在写下任何音符之前，请先弄清楚音乐是为什么而作：

• 阅读游戏项目：README、设计文档、故事/场景文本、场景/关卡名称、美术风格（查看一些图像）、UI 主题颜色、现有的音频文件夹和文件命名、使用的引擎（Godot 的 project.godot，Unity 的 Assets/，Unreal 的 .uproject，Web）。
• 确定：流派/声音调色板、情绪（2-3 个形容词）、能量、速度、调性/调式、提示类型、长度、循环形式、交付格式和路径。 如果用户给出了意图（例如“黑暗合成波菜单，100 bpm”），则以其为准，覆盖您的推断。仅当项目没有提供任何线索时才提问。
• 记录下来：project_new(name, tempo, key, time_sig, brief={genre, mood, use, game, references, notes})。

2. 检查乐器库

status() 列出 VST3 乐器、音色（插件 + 已保存的声音，带标签）、SFZ 乐器和内置合成器。

• 原声/管弦乐部分需要真实样本：使用 patch:<id>（例如 HALion、BBC Symphony Orchestra、Spitfire LABS 的音色）或 sfz:<path>。内置合成器非常适合电子、合成波、芯片音乐、氛围音乐和低保真音乐，并且作为支撑层也很好用。
• 像 HALion Sonic 和 Groove Agent 这样的 VST3 乐器加载时是空的：不带音色时它们会渲染出静音（渲染时会发出警告）。 MODO DRUM 无需音色即可工作。
• 如果需求中需要的调色板缺失（例如需要管弦乐弦乐但没有弦乐音色或 SFZ），请直说并提供：(a) 用户捕获音色（patch_capture 会打开插件窗口；仅在他们对着电脑时有效），(b) 安装免费库（README 列出了一些），或 (c) 风格化的合成器版本。不要将合成器冒充为管弦乐。
• audition("patch:<id>") 检查乐器是否能发出声音并报告其亮度。sfz_info 显示音域和键位切换。
• 带有 dynamics_cc（1 或 11）的音色的响度来自该 CC，而不是力度：始终为它们编写 cc() 曲线。

3. 规划形式（在音符之前）

使用 markers() 设置段落，使用 project_set(loop="5:1-21:1") 设置循环区域。典型形式：

提示	长度	形式和注释
主菜单	45-120 秒循环	可选的 2-4 小节前奏（播放一次），然后是 A(8) B(8) 或 A A' B A 循环。令人难忘的动机，中等密度，为 UI 声音留出空间。
探索 / 世界地图	1.5-3 分钟循环	长弧线，稀疏纹理，喘息空间，缓慢的和声节奏（每 1-2 个小节一个和弦）。
城镇 / 商店	40-90 秒循环	温暖，有节奏感，小合奏，朗朗上口。
战斗	60-120 秒循环	130-170 bpm，推动的固定音型，强低音，重音和敲击，短乐句；B 部分提升强度。
Boss	90-180 秒循环	更暗的调式，更重的低频，一个从主旋律扭曲而来的动机。
胜利 / 失败音效	2-8 秒，一次性	胜利：上升的线条到一个明亮的大调和弦 + 镲片。失败：下降的线条到一个小调或减和弦，淡出。loop="off"。
氛围铺垫	1-3 分钟循环	铺垫/持续音，缓慢移动，没有强烈的脉冲，很少旋律。
制作人员名单	2-4 分钟，一次性	游戏动机的混合曲。

循环规则：循环必须是整节拍数；其最后一个小节必须能导回到第一个小节（属和弦，或第一个旋律音符的弱起）。不要让音符跨越循环结束，除非您希望如此。render(loop="auto") 会自动将释放和混响尾音折叠到循环开头。

自适应音乐：将所有层放在同一个调、速度和长度中，用 layer 标记轨道（base、tension、combat），并使用 layers=True 渲染成垂直分层的分轨，供游戏进行交叉淡入淡出。

4. 编写音乐

顺序：动机，然后是和声、低音、旋律乐句、对位声部和内声部、节奏部分、力度，最后是变化。

旋律

• 从一个 1-2 小节的动机开始建立，它具有可识别的节奏和轮廓。通过重复、模进（向上移动一个音级）、倒影、节奏扩展来发展它。将乐句构建为问句（开放结尾，停在 2 或 5 级音上）和答句（停在 1 级音上）。
• 每段有一个清晰的高潮（最高音，最强拍）。以级进为主，偶尔跳跃；通过反方向的级进来解决跳跃。保持可唱性（大约一个八度加五度），除非是器乐炫技段落。
• 留出空间：休止和长音为乐句提供形状和呼吸空间。不需要每个拍子都有音符。
• 和弦音在强拍上；经过音和辅助音在弱拍上。长音上的不协和音是刻意的选择。

和声

• chords() 会为您进行声部连接。选择服务于情绪的和声进行。变化和声节奏：每个小节一个和弦，在终止式处加快。
• 有用的进行：小调 i-VI-III-VII（史诗/英雄），i-iv-VII-III（怀旧），大调 I-V-vi-IV（明亮），ii-V-I 和 IVmaj7-iii7-vi7（爵士/舒适），bVI-bVII-I（胜利），利第亚调式 I-II（惊奇/魔法），弗里吉亚调式 i-bII（威胁），多利亚调式 i-IV（冒险，民谣），大小调交替和弦（大调中的 bIII，bVI）用于电影色彩，在变化和弦下的持续音用于制造紧张感。
• 用真正的终止式结束段落（V-i，iv-V，bVI-bVII-I）。副属和弦（V/V，V7/vi）增加向前推进的动力。

低音

• 根音在强拍上，五度音和进入和弦变化的经过音（级进或导音）。赋予它与底鼓锁定在一起的节奏。保持在 C3 以下，并在其自己的音区中独处。

配器

• 音区：低音在 C3 以下，和声在 C3-C5，旋律高于伴奏或与伴奏清晰分离。在 C3 以下小于五度的音程听起来浑浊（分析会标记这一点）。
• 一次只有一个焦点元素；对位声部在旋律的休止中应答（呼应）。
• 通过添加和移除层来构建段落。B 段应与 A 段形成对比：不同的音区、密度、节奏或和声色彩。
• 管弦乐：旋律在小提琴（由长笛高八度或圆号低八度叠加以增加温暖感），和声在中提琴/大提琴/圆号，低音在低音提琴/大提琴。圆号在中音区的五度和八度听起来最好；小号用于号角齐鸣的高潮；定音鼓用于乐句结尾的根音和五度音。在轨道上使用 role，以便范围检查生效。theory(range="horn")。
• 鼓：每 4 个小节有一个变化的律动，并在段落转换处加花（第 8 小节的最后一两拍）。新段落的强拍上使用 Crash。鬼音（o）和摇摆增加生命力。

力度和感觉

• 塑造每一个乐句：使用 notes_edit(op="velocity", ramp_from, ramp_to) 制作渐强，使用 > 制作重音。
• CC 控制的管弦乐音色：在长音上使用 cc(track, 1, start, end, 40, 100, shape="swell")，并为每个段落设置基础电平。
• 对原声部分使用 notes_edit(op="humanize", timing_ms=5-15, velocity=4-8)。保持芯片音乐和紧凑的电子部分量化在网格上。
• 断奏（'）和连奏（notes_edit(op="legato")）会极大地改变性格。有目的地使用它们。

避免复制粘贴的单调重复：使用 arrange(op="copy") 复制一个段落，然后对副本进行变化（新的对位声部、八度移位、重新和声的终止式、更开放的鼓）。

5. 流派声音调色板（括号内为内置合成器名称；当流派是原声时，优先使用真实音色）

流派	速度	调式 / 和声	调色板和节奏
管弦乐幻想 / 冒险	80-120	大调/多利亚/利第亚，i-VI-III-VII	弦乐、圆号、木管、竖琴琶音、定音鼓；[pluck]、[bell] 用于色彩
史诗 / 战斗	130-170	小调、弗里吉亚，i-bVI-bVII	弦乐固定音型 8 分/16 分音符、铜管短促音、太鼓/通通鼓、合唱铺垫；[brass_synth]、[reese_bass] 混合
舒适 / 村庄 / 种田	85-110	大调，加 9 和 maj7 和弦	尼龙弦/拨奏、电钢琴、木槌、轻摇沙锤；[nylon_pluck]、[epiano]、[mallet]
合成波 / 复古	90-118	小调（伊奥利亚/多利亚）	[supersaw] 铺垫、[analog_bass] 8 分音符低音、[lead]、门控军鼓、大混响
芯片音乐（FC 风格）	120-180	大调或小调，快速琶音用于和弦	正好 2 个 [chip_pulse]/[chip_square] 声部，1 个 [chip_triangle] 低音，[chip_noise] 鼓；没有混响或使用极小的混响；量化
恐怖 / 紧张	50-80 或无脉冲	半音音簇、三全音、持续音	[dark_pad] 持续音，稀疏的高 [bell] 音符，低脉冲，将静音作为一种工具
氛围 / 太空	60-90	利第亚、挂留和弦、缓慢变化	[pad]、[dark_pad]、[bell]、长混响发送、缓慢的音量自动化
低保真 / 轻松	70-90，摇摆	ii7-V7-Imaj7，m9 和弦	[epiano]、带 0.3-0.5 摇摆的柔和鼓、母线上的 [saturator] 和 [filter]
动作 / EDM	120-150	小调，四四拍	[drums] 或一套鼓、[reese_bass]/[analog_bass]、[saw_pluck] 琶音、[supersaw] 主音、侧链式音量自动化
解谜 / 休闲	100-130	大调，俏皮的半音经过音	[mallet]、[pluck]、拨弦音色、断奏低音

6. 混音和母带

• 增益分级：将轨道起始音量设置在 -6 到 -12 dB 之间；旋律位于顶部，铺垫在其下方。渲染报告会报告每轨电平。
• 在总线上添加一个共享混响（track_add("Reverb", kind="bus", fx=["builtin:reverb"]) 或像 ValhallaSupermassive 这样的 VST3，将 Mix 设为 100%），并逐轨发送到该总线。快速或密集的音乐更干，氛围音乐更湿。
• 高通滤波所有不是低音或底鼓的东西（builtin:eq hpf 100-200 Hz），如果报告显示浑浊，则在铺垫上削减 250-500 Hz。
• 声像用于宽度（竖琴左，第二小提琴右，镲片略微偏离中心）。保持低音和底鼓居中。
• 响度：主输出归一化到 target_lufs（默认 -16）。背景/菜单提示通常位于 -18 到 -20；战斗位于 -14 到 -16。
• 用户的 VST3 效果（SSL、TDR Nova、Waves、Valhalla）可以通过 fx_add 添加到轨道、总线或主输出上；使用显示文本按名称设置参数（例如 {"Mix": "100 %", "LowCut": "200 Hz"}）。

7. 检查循环（始终执行）

1. notes_read(track) 以 TTN 格式检查您的线条。analyze() 提供调性/音域/重叠/浑浊度检查以及钢琴卷帘 PNG。阅读 PNG 以检查形式、密度和音区分布。
2. render()。针对每个警告采取措施：无声轨道（未加载音色）、浑浊、高音沉闷或刺耳、峰值、限制器工作过度、循环接缝。未更改的轨道会被缓存，因此可以自由迭代。
3. listen()：您的耳朵。它测量的是渲染后的音频，而不是音符，能够捕捉到音符无法展示的内容：
   • energy_arc、sections、bar_lufs：每个段落是否按照其形式表现？B 段应在电平、亮度、密度或主导乐器（tracks_db、most_present）上与 A 段不同；渐强应逐小节上升；循环的最后一个小节应流畅地流入第一个小节。
   • masking：每个轨道在其主要频段内的 vs_rest_db。保持主乐器在 0 或以上。低于约 -10 的部分几乎听不见：提升它们，对被 covered_by 覆盖的轨道进行 EQ 衰减，移调，或将其剪掉。pairs 是在同一频段竞争的声部（例如，底鼓与低音在 63 Hz：让其中一个拥有低频，或者在敲击时闪避）。
   • verify：探测每个部分使用的每个音高。它们会显示无声或明显更安静的音高（超出乐器音域）、听起来移调的声部、对短音符起奏缓慢、有音符但无声的小节（CC 为 0？），以及 drum_notes：每个鼓音符的真实声音以及在相同力度下的响度。信任这些结果胜过音色名称和描述。 修复，重新渲染，再次聆听，直到每个警告都被修复或确认是刻意为之。首次运行会探测渲染每个乐器（每个插件轨道几秒钟，之后缓存）。reference="<file>" 用于将混音与用户想要匹配的曲目进行比较。
4. 告诉用户您制作了什么以及它是如何构建的（形式、调性、速度、乐器、动机），提供文件路径，并提供 play() 或编辑器（ui_open()）以便他们聆听。他们的耳朵是最终的裁判，所以询问需要更改什么。

8. 交付

render(out="<game>/<audio dir>/<name>.<ogg|wav>", loop="auto")，匹配项目的文件夹和命名。

• Godot：.ogg。在导入面板中设置循环；对于前奏+循环，使用 .loop.json 中的 loop_offset = loop_start_sec。
• Unity：.ogg 或 .wav。在 AudioSource 上设置循环标志；前奏+循环通过两个片段或使用 .loop.json 的调度播放来实现。
• Unreal：16 位 48 kHz .wav（bits=16）；WAV 携带 smpl 循环块。
• Web：.ogg 以及 .mp3。 对自适应系统使用 stems=True / layers=True，使用 midi=True 将编曲交给 DAW（Cubase）。

TTN 表示法（用于 write）

D4:q!mf F4 A4:h | (D3 A3 F4):w | r:h C5:e. B4:s A4:q' G4:q> | E4:h~ E4:q r:q

音高 C4 = 中央 C（MIDI 60），F#3，Bb5，或使用 r 表示休止符。和弦 (C4 E4 G4)。 时值 w h q e s t（全音符到三十二分音符），附点 q.，三连音 e3，节拍 1.5 或 3/2，总和 h+e；粘性设置直到改变。 力度 !pp !p !mp !mf !f !ff 或 !0-127，粘性。' 断奏，> 重音，~ 延音到下一个相同音高。 | 小节线，根据拍号检查（不匹配会以警告形式返回，请修复它们）。 @6.5 将光标移动到写入范围的 6.5 拍位置，用于一次调用中的第二声部。或者使用 mode="merge"。

模式标记（用于 pattern）：和弦音级 1 3 5 7 9，8 10 12 高八度，5-/3+ 八度移位，b7/#4 根音上方的变化音级，. 休止， - 保持，1> 重音。示例低音："1 - - 1 . 1 5- ."（流行），"1 . 1 . 1 . 1 ."（8 分音符，合成波），"1 - 5- - 8 - 5- -" （行走感）。琶音："1 5 8 10 12 10 8 5"，"1 3 5 8"，速率为 0.25 表示 16 分音符。