程序化芯片配乐
把作曲信息和音色引擎分开：参考音频 → 按需真实分轨 → 转谱候选与校订 → 编曲事件谱 → 波形合成 → 试听／循环母版。支持无参考的原创音乐；这时跳过扒谱。
先确定音乐目标
优先沿用用户已确定的参考、时长、风格和已认可音轨。缺少非关键细节时选择合理初稿，不重复询问已回答的偏好。保存新版到独立曲目目录，保留已认可原稿。创作本身不代表授权接入网站、游戏或发布 npm。
参考改编先读取 参考分析与取舍。需要保留混音中的主线／回应细节时，再读 真实分轨与转谱，使用 Demucs + Basic Pitch ONNX／pYIN；基础 NumPy 模式不自动拉这些重依赖。使用 Yakui Studio 工作台校订和导入时，读取同级安装的 Yakui Studio。若只是了解方法来源，读取 Yakui 案例；案例中的速度、和弦和段落长度不是新曲默认规则。
参考音频分析
拿到实际可解码的音频再报告分析结果。用户文本中的 BPM 或音符表需要核对；网页描述、曲名和在线视频链接本身不是听过音频的证据。只有 URL 时使用当前可用的正常媒体获取途径；获取受阻则说明缺少什么，不编造扒谱结果。参考录音不自动混入音轨或源代码包。
基础工具：
python scripts/analyze_reference.py reference.wav --start 0 --seconds 30 --out analysis-intro.json
路径相对本 skill；可使用其绝对路径。依赖 Python 3.10+、NumPy，参考解码和 MP3 导出还需 FFmpeg（PATH 或 FFMPEG）。
- 至少比较开头和主要段落的节拍候选，注意半速／倍速；确认后才传
--bpm对齐音符候选。 half_beat_candidates是混音中的谐波显著度，不是自动识别的独立旋律。最大的峰可能属于贝斯泛音、鼓或另一个声部。- 标注观测、低置信度候选和编曲选择；高音回应无法可靠提取时保留歧义，原创回应明确标记。
- 细节优先的改编先真实分轨，模型标签按实际
sources保存；再用复调转谱保留同时音符，用单声部 F0 对照明确旋律段。主旋律／回应属于音乐角色，不能把频段筛选或 Demucs 的other自动改称独立角色声轨。 - 原始秒时刻、音高弯曲、置信度/激活值和校订理由留在分析文件；量化只增加派生字段。用谱面和有代表性的实际乐句核对八度、短装饰音、重复同音与同时奏响，不把模型输出直接称为原曲准确乐谱。
建立可编辑曲目
python scripts/init_track.py /absolute/new-track --title "Track title" --bpm 95 --bars 24
它复制独立的编曲模板、合成器与构建入口，不覆盖已有目录。输出包括 track.json、arrange.py、render_score.py、build.py、依赖清单。模板动机只是原创示例，须按本次音乐目标修改；不要把每首曲子都渲染成模板换 BPM。
在曲目目录执行：
python -m pip install -r requirements.txt
python build.py --mp3 --three-pass
先做有代表性的乐句／段落，再扩展到目标长度；用户已批准详细编排时直接按编排制作，不另设审批门槛。
- 四分音符拍为事件时间单位，时长由 BPM、小节数与拍号计算；接近指定秒数时说明节拍约束，不通过加快整条音频硬凑长度。
- 主旋律、回应、贝斯、和声、琶音和鼓分别编排。高潮增强音域、节奏和和声密度，给主旋律留出声像与电平空间。
- 合成器沿用已验证的 PolyBLEP 脉冲波、有限谐波三角波、LFSR 噪声鼓、短包络和节拍延迟。按曲目调音色；扩展芯片声部不等于严格模拟 FC/NES 通道限制。
- 参考分析与转谱可服务其他风格；用户指定后摇等风格时保留已核对的旋律，另选实际合适的乐器／渲染器。芯片模板不会自动变成真实吉他或后摇音色，不用模板换标签冒充新风格。
8-bit默认指音色／编曲；输出保留 44.1 kHz、16-bit 立体声质量，除非用户明确要求位深降质。
需要直接编辑谱或调音色时读 事件谱格式。render_score.py score.json --out audio --mp3 --three-pass 可跳过编曲器，渲染任意兼容谱。
试听与交付
audio/ 输出 preview.wav、loop.wav、可选 MP3、高潮片段与 render-report.json。预览可淡出；循环母版不加整曲淡出，延迟尾音环绕到开头。--three-pass 生成三轮接缝试听。
核对时长、有限数值、削波、段落电平及循环附近的突变；数字检查不能替代听感。实际听音能力不可用时交付可播放文件让用户试听，不声称自己已经听过。重点听主题、回应、高潮密度、主奏清晰度与循环接缝；不因为音乐文件存在就宣称风格匹配。
用绝对路径音频嵌入提供完整试听和有代表性的高潮片段；附编曲／合成源码、乐谱和简短段落说明。用户要求轻量终端播放时，再按相同事件谱和音色参数移植本机合成器，避免把整段 PCM 内嵌或要求用户安装 Python；不要为了制作试听自动改观看器或发布流程。