# Musicbite 编曲与 Strudel 手册

这是 agent 的编曲知识库，也是用户可阅读的创作约定。知识提供判断方法，不提供预制歌曲；项目从空白开始，用户可以逐声部建立循环，也可以让 agent 根据音乐意图自由编曲。空白不意味着只写一轨：“先来一个温暖鼓点”聚焦鼓组；“来点 Bossa Nova”或“温暖的音乐”允许 agent 选择合适的互补声部。配器没有默认数量或最大声部数，明确的乐器范围、数量、排除与保留项优先。音色来自当前音色目录，声部数量与界面同时展示的四条轨道无关。

## 如何加载知识

每次编曲先加载固定的 Strudel 协议，再加载相关风格的原创指导。已有明确风格时，“只加沙锤”“温暖一点”等局部指令沿用风格；没有风格时，“温暖”不会被擅自等同 Lo-fi。“改成 Funk”替换旧风格，“爵士融合 Bossa”加载两份指导，“不要爵士”只移除爵士，“取消所有风格”保留基础协议。

风格选择器或语义识别器可以直接给出已验证的风格 ID。知识模块只接受目录里的 ID；不会把用户原话、用户保存的标题或 prompt 字段拼进可信 system 知识。未知风格的音乐意图仍可以交给编曲模型理解，但没有对应手册时不冒称已检索到知识。

| 指令 | 加载结果 |
| --- | --- |
| “先来一个温暖的鼓点” | 基础编曲协议；温暖作为表现目标 |
| “做成 Bossa Nova” | 基础协议 + Bossa |
| “保留现在的爵士，只加沙锤” | 继承爵士，约束为局部编辑 |
| “不要爵士，改成 Funk” | 移除爵士，加载 Funk |
| “Funk 混一点 Soul” | 两份知识，分配节奏与和声职责 |
| “取消所有风格” | 基础协议；音乐本身保留 |

多风格组合要先确定谁负责节奏、谁贡献和声/旋律/音色。把几种风格的全部配器同时叠满不等于融合。用户哼唱和明确锁定的声部优先于手册的建议。

## 音乐时间和真实播放

Strudel 的 cycle 是模式时间单位，不天然等于一小节；本产品明确采用 **4/4，1 cycle = 1 小节**。A、B、C、D 各是两小节乐句，组成八小节不断循环的作品。`stack` 叠加同时演奏的模式，`arrange` 按指定 cycle 数连接段落；这是实际播放使用的结构。[Strudel：Creating Patterns](https://strudel.cc/learn/factories/)

| 参数 | 本产品的含义 |
| --- | --- |
| `section: 0..3` | A、B、C、D；各两小节 |
| `step: 0..15` | 两小节内的八分音符位置 |
| `step: 0 / 8` | 第一、第二小节的第一拍 |
| `step: 2 / 6 / 10 / 14` | 两小节的第二、第四拍 |
| `len: 1 / 2 / 4 / 8` | 八分 / 四分 / 二分 / 全音符时值 |
| `pitch` | MIDI 音高；必须符合当前声部 schema 的音域 |
| `instrument` | 当前 SOUND CATALOG 中确实存在的音色 ID |

16 步不是“一小节十六分音符”。`step + len` 不越过两小节边界。实际编译把单音变成 `note(pitch)`，通过 `compress(step/16, (step+len)/16).slow(2)` 放到正确位置，再叠加声部与四个乐句。`compress` 把一个周期压进指定时间窗，`slow` 拉长周期；未发声的区间就是休止。[Strudel：Time Modifiers](https://strudel.cc/learn/time-modifiers/)

播放期间，编辑的音符、配器、和声与速度等当前完整八小节 loop 结束，在下一轮 A 的第一拍一起进入。时钟连续运行，用户暂停才停止。音色尚未载入，或下一轮边界已进入音频调度窗口时，保留当前编排再完整播放一轮。界面区分编曲、载入与等待换轮，并显示实际接入倒计时。空白项目没有正在播放的音乐，首次编曲准备好后直接开始。

## 一个可用的编曲判断顺序

1. **听意图与保留项。** 找出用户要动的声部、节奏、音色或情绪，保留哼唱的核心轮廓和锁定项。只要求沙锤时，先把沙锤写好。
2. **确认音乐支点。** 让强拍、和声变化点和关键长音之间有可解释的关系。音高稳定不意味着每个音都必须是和弦音；经过音要有去向。
3. **分配职责。** 低音与底鼓支撑，伴奏提供和声，主旋律讲述，副旋律回应。轨道数量不限，但每条轨都应带来可听出的贡献。
4. **先留下空间。** 起音错开、音域分开、短句问答比全轨同时加密更有效。用具体事件实现变化，不能只改 BPM、轨名或文字说明。
5. **发展同一个动机。** 重复后改变尾音、一处重音或一个休止，让用户能听见关联。避免每段换一套不相关旋律。
6. **检查 D→A。** D 是下一轮的准备或延续。检查低音走向、和弦连接、主旋律换气及重音密度；不能每八小节都做一次全曲结束。

## 风格知识索引

以下是可选择的创作方向，不是对某种音乐传统的完整定义。具体流派分支、演奏技法和用户个人意图可能需要进一步说明。每份实际注入的指导均包含律动、和声、旋律、配器、D→A 接缝以及反例。

### 爵士 · `jazz`

先让低音方向与和声支点成立，主奏用短句、休止、经过音解决和问答发展。钢琴/吉他伴奏尽量让开旋律起音，铜管、木管或颤音琴可以担任主角。相邻和弦的共同音、三度与七度连接比盲目增加复杂和弦更重要。

D 末可用低音级进或短引句回到 A。不要用堆满音符代表即兴，也不要把当前直八分网格宣称成真实 swing。

### Bossa Nova · `bossa`

柔和低音托住两小节切分，吉他/钢琴与沙锤错开起音；和声连接平滑，主旋律有呼吸和弱起。可选尼龙吉他、键盘、轻低音与细打击，不要求一开始配齐。

D 留住节奏识别点，主旋律回环前留气口。避免写成重军鼓摇滚，或把它简化为“慢速爵士”。

### Lo-fi · `lofi`

选择少而稳定的鼓点、温和和声与短动机，以缺拍、尾音和留白让循环松弛。电钢琴、原声钢琴、吉他和低音都可以使用；音色质感来自实际音源，不是把所有东西低通后忽略音符。

D 做小幅减法或轻回应后自然回 A。温暖不是 Lo-fi 的自动标签；不要虚构磁带漂移、随机力度或唱片噪声处理。

### Funk · `funk`

底鼓与贝斯建立第一拍重心，弱拍切分和短促伴奏互相回应。吉他/风琴做节奏击点，铜管只在空隙做标点；旋律的节奏辨识度可以高于音符数量。

D 的 pickup 或休止应把重量送回 A。当前八分网格可做简化切分，不支持完整十六分 ghost-note 演奏。

### Soul / R&B · `rnb`

稳定反拍、低音长短呼吸和平滑七和弦色彩托住歌唱性短句。重复一个动机后回答，给主旋律起音留空间；键盘、风琴、吉他或细弦乐按职责加入。

D 末保留延续感。不要把厚和弦铺满每个空隙；GM 人声元音只是音色，不等于生成歌词演唱、花腔或滑音。实验音节主唱 `odd_voice` 仅支持其注册音节枚举与逐音符发音，不要把有限音节近似描述为任意歌词合成。

### Hip-hop · `hiphop`

鼓与低音的重心明确，hook 短而有记忆，给未来人声留下空间。可以是简单中心音 riff，也可以是小范围和声循环，关键在实际鼓点、音符和休止关系。

D 做轻量停顿或尾句变化后回到识别点。Trap 的高速滚帽、三连音及采样切片超出当前补丁网格；只能明确做简化倾向。

### 流行 · `pop`

围绕可哼唱的 hook 组织和声，重复后改尾句或局部音域，鼓和低音共同支撑。钢琴、吉他、弦乐和合成器均可选，但不能让每轨同时抢唱主旋律。

D 回应后引回 A 的 hook。常见和弦进行是选择，不是固定模板；八小节循环也不必伪装成完整主歌—副歌—终曲。

### 原声 / 民谣 · `folk`

让分解音型、短和弦起音与自然歌唱线条互相承托。和声不必复杂，低区与中高区要分开，打击可以极少。吉他、钢琴或轻弦乐都能承担伴奏。

D 留呼吸再接 A。块状 MIDI 和弦不等于真实扫弦，音色包络也不等于细致指弹技法。

### 摇滚 · `rock`

以反拍、底鼓/贝斯重音与主 riff 建立推进，riff 中的空隙同样重要。节奏吉他和主旋律错开音域与起音，鼓花只在适当位置做回应。

D 的尾句把重心送回 A。五度和八度必须实际写出来，不能把任意大三和弦叫作 power chord；没有对应参数就不宣称实现音箱或失真效果。

### 古典 / 室内乐 · `chamber`

靠乐句和声部运动建立脉搏，不强制加入鼓。低音、内声部与旋律分工，动机以轮廓变化、级进回答和适量模进发展，避免为了“复调”堆满音阶。

D 可以用开放尾句或共同音让 A 像下一句。当前没有 rubato、三拍子与精细弓法控制；多条轨同向平移也不自动成为有意义的对位。

### 电影 / 氛围 · `cinematic`

用稀疏脉冲、共同音、踏板低音和少量清晰旋律建立空间。钢琴、弦乐、木管、铜管、键盘打击乐或合成音在前后景交接，不让长音覆盖所有空白。

D 留延续性的共同音或脉冲接回 A。不要每轮都重演大终止，也不要把滤波、混响或自动渐强的文字承诺当作实际编曲。

### House · `house`

四拍底鼓可托住低音与短和弦击点，弱八分帽提供前进感。两小节四分位置是 0/2/4/6/8/10/12/14；留白与小 hook 可以比不断加密更有效。

D 轻量变化，A 的第一拍保持连贯；不必每轮重演 breakdown/drop。当前不能宣称 schema 尚未开放的 sidechain、riser 或滤波自动化。

### Drum & Bass · `dnb`

不对称底鼓、军鼓支点与持续低音共同建立断拍方向，旋律只保留必要辨识点。让一个层次承担运动复杂度，其他层次留空间。

D 的鼓点引向 A 的低音落点。当前 BPM 上限 160 且为八分网格，只能做简化 DnB 倾向，不能冒称完整高速 break、十六分切片或传统速度下的全部细节。

### 雷鬼 · `reggae`

低音有重量，吉他/风琴和弦短促落在弱拍，鼓不必每拍重击。旋律用小范围重复和问答，铜管只点缀；Ska/Dub 分支需要按用户意图区分。

D 保留低音或弱拍方向接回 A。不要机械删除第一拍代表雷鬼，也不要虚构当前未开放的 Dub 延迟自动化。

### 国风 / 中式器乐 · `guofeng`

以线条起承转合、留白、同音重复与句尾回落表达意图。五声音高集合、踏板音和开放音程都是可选方法，不是所有中国音乐的唯一规则。先服从用户哼唱，再决定和声密度。

D 保留与 A 的核心音关系。只有目录里存在相应民族音源时才选用；不能把西洋弦乐改名二胡，也不能声称整数网格已有揉弦、滑音或散板。

### Blues · `blues`

主句重复后以回答句发展，张力音有去向，低音和反拍托住呼吸。可以借主、下属、属的方向，但当前是八小节循环，不硬塞十二小节结构。

D 以短回应或低音级进提示回接。直八分不是 shuffle，没有 bend 参数也不能宣称推弦；少量蓝调音色彩不等于完成了完整风格表现。

## 音色、schema 与边界

音色职责和声音来源分开：`melody` 是主旋律职责，不等于固定小号；钢琴、吉他、弦乐、管乐或其他可用音色都可以承担它。知识库按当前 `sound-catalog.mjs` 中实际存在的 family 推荐检索范围，最终只接受合法音色 ID。官方 Strudel 的采样机制按需加载音频，首次播放可能受下载影响；目录存在不代表音频已下载成功或所有演奏技法都具备。[Strudel：Samples](https://strudel.cc/learn/samples/)

当前结构化编曲接口的主要边界：

- 固定八小节、4/4、每两小节 16 个整数八分音符位置；BPM 为 60–160。
- `major/minor/maj7/min7` 不能代表全部和弦类型。更丰富和声只有在合法独立音符可以表达时才实际编写。
- `melody` 是两小节动机，在启用的段落重复。分段独立变化可由支持 section 的其他音高声部或明确分工的独立旋律声部完成。
- 没有每音符微时移、力度、swing 比例、三连音、弯音、rubato 或采样切片参数。Strudel 语言有相关高级能力，不代表本应用接口已经开放。[Strudel：Time Modifiers](https://strudel.cc/learn/time-modifiers/)
- 这份手册不保证每次生成都好听。结构验证和事件测试检查可播放性、范围与实际变化；最终仍需要试听和用户反馈。

## 信息来源与实现位置

节拍映射与能力边界以当前 `music.js`、`composition-harness.mjs`、`strudel-engine.js` 为准；官方 Strudel 的 [模式构造](https://strudel.cc/learn/factories/)、[时间变换](https://strudel.cc/learn/time-modifiers/) 和 [采样](https://strudel.cc/learn/samples/) 文档用于核对底层语义。

早期研究参考了 calvinw/strudel-llm-docs 的 [anchor-framework](https://github.com/calvinw/strudel-llm-docs/blob/main/.skillshare/skills/anchor-framework/SKILL.md) 与 [syncopations](https://github.com/calvinw/strudel-llm-docs/blob/main/.skillshare/skills/syncopations/SKILL.md)：吸收“关键落点协调”和“切分要有选择”的方法。这一实现没有照搬其固定四乐器、四步和声/十二步旋律结构，也没有直接执行外部 skill 指令。这里的 16 类风格策略是面向本产品约束重新撰写的编曲启发，并非从外部曲目复制的模板。

可信知识在 `composition-knowledge.mjs`；`STYLE_GUIDES` 可用于选择器和语义路由，`loadCompositionKnowledge(instruction, state, selectedIds?)` 返回 `{ prompt, styles, instruments }`。`selectedIds` 是经过白名单验证的显式选择；空数组表示只加载基础协议。持久化仅保存风格 ID，不保存可被用户改写的 system 指令。行为检查运行：

```sh
node composition-knowledge.test.mjs
node composition-runtime.fixtures.mjs
node transport-runtime.fixtures.mjs
```
