sv-texture

Files (1)

• SKILL.md

SKILL.md (first lines)

# 织体（Texture / 伴奏型）

> **分工一句话**：`composition` 管**配器 / 音色 / 结构性判断 / 混音**；本 skill 只管**同一串和弦怎么铺开**。
> 规矩：每条判断都要落成**具体音符或一次工具调用** —— "要有层次感""要更丰满"这类话等于没说（同 `composition` 的纪律）。

## 0. 三句话上手

1. **先定"一格几拍、一拍几个音"**（节奏密度），再选型（柱式/分解/琶音/…），最后定音区与层数。
2. **一段只能用 1~2 种主织体**；变化靠**加层 / 换型 / 改密度**，不要每小节都换花样。
3. **织体的职责是"托住旋律"**：给和声与律动，**不抢旋律音区、不抢重音**（旋律在哪，织体就让开那一层）。

## 1. 织体类型学（八类）

| 类型 | 长什么样 | 常见乐器 | 最适段落 | 技术要点（可直接落音符） |
|---|---|---|---|---|
| **柱式（block）** | 和弦音同时下，一拍或半拍一下 | 钢琴、弦乐组、pad | 副歌、结尾推进 | 4/4 常用 `♩` 或 `♩.`；低音单独一层（根音）比整块下移更好听 |
| **分解（broken）** | 和弦音按序流出，每拍 2~4 音 | 钢琴、竖琴、吉他 | 主歌、预副歌 | 4/4 八分：低-中-高-中（`1 3 5 3` 型）；每小节首音留给**低音根音** |
| **琶音（arpeggio）** | 逐音上行/下行铺满时值（十六分常见） | 合成器 arp、竖琴、拨弦 | 主歌到预副歌、电子副歌 | 十六分 `1-3-5-8`（含八度）上行；速度感来自**细分**而不是音量 |
| **切分（syncopated）** | 重音错开拍点（`♩ ♪♪` 移位、后半拍进） | 钢琴、电钢、吉他 | 预副歌、副歌 | 只改**重音位置**、不改和弦；与鼓的底鼓错开才有推动力 |
| **固定音型（ostinato）** | 一小节音型无限重复，和声换它不换 | 弦乐、合成器、吉他 riff | 全曲黏合剂、桥段 | 音型要**单数拍或跨小节**才有"滚"的感觉；换和弦时只改音高不改节奏 |
| **对位式（counter-line）** | 一条独立的低音/副旋律线与主旋律反向或错位 | 大提琴、贝斯、合成器 bass | 主歌第二遍、桥段 | 与旋律**反向进行**最安全；同向时用三/六度并保持节奏差 |
| **长音铺底（pad / sustain）** | 长音或长音+缓动，不参与律动 | pad、弦乐长音、风琴 | intro、主歌、桥段 | 一个和弦一个音或两音（**根音+五音**最稳）；不要与分解层同音区堆 |
| **节奏型 riff** | 短促、有律动的动机反复（常为单音+八度） | 电吉他、Synth lead、铜管 | 副歌、drop、hook | 动机 ≤ 2 拍，重复 4 次后**在第 4 次尾加花**；音高只跟和弦的根/五 |

> **组合原则**：一个段落通常 = **低音层（长音或走句）＋ 和声层（分解/柱式）＋ 色彩层（琶音/对位/加花）**，最多三层。
> 层数够了就**别再加**，改成"换型"（例：主歌 2 层 → 副歌把和声层从分解换成柱式）。

## 2. 段落 ↔ 织体 与推进手法

| 段落 | 主织体 | 密度（4/4） | 推进手法 | 常见错误 |
|---|---|---|---|---|
| **Intro** | 长音铺底 / 单乐器分解 | 稀疏（`♩` 级） | 只给色彩，留悬念 | 一上来就全奏（后面没得加） |
| **Verse 主歌** | 分解 或 ostinato | 八分 | 第二遍加对位低音 | 太满 ⇒ 副歌无处可去 |
| **Pre-chorus 预副歌** | 切分 / 密度递增的分解 | 八分→十六分 | ① 密度爬升 ② 低音级进上行 ③ 去掉一层留白 2 拍 | 直接抄副歌织体（推进感消失） |
| **Chorus 副歌** | 柱式 / 宽琶音 / riff | 四分柱式或十六分琶音 | 加层（弦乐/pad）+ 抬音区 | 只靠"变响"而不是"变型 + 加层" |
| **Bridge 桥段** | 长音铺底 / 对位式 | 最稀疏 | 拆掉节奏层（"静场"）再重建 | 继续堆 ⇒ 听不出桥段 |
| **Outro** | 柱式渐稀 / ostinato 收束 | 递减 | 反着走 intro 的路 | 突然全停 |

**推进三招**（缺推进感时按顺序试）：
1. **加层**：低音 → 加和声层 → 加色彩层（每次只加一层）。
2. **换型**：同一层从分解换柱式 / 从长音换切分（听感变化最大、成本最低）。
3. **改密度**：八分→十六分、或反过来在**关键一小节留白**。

## 3. 落到工具（AKDAgent）

### 3.1 和弦从哪来
- 音频轨在场：`sv_analyze_chord`（**务必先用伴奏**，人声混着的 chroma 不准 → `sv_separate_vocals`）
- 用户给了进行：直接用（如 `['C','G','Am','F']`）
- 声部内部进行（IX 织体/和声组）：`sv_create_harmony_group` 另有其用（**给主旋律配和声声部**，不是伴奏织体）

### 3.2 `sv_write_chords`（把和弦铺成音符）
| 参数 | 作用 | 织体侧建议 |
|---|---|---|
| `input` | 伴奏 WAV（分析和弦） | 用**纯伴奏** |
| `bpm` / `keyRoot` / `keyMode` | 拍速与调性 | 检测有歧义时**显式给**，避免小节线错位 |
| `segBeats` | 每段拍数（默认 4 = 一小节） | 想"两拍一和弦"就设 2 |
| `pattern` | **`block` 柱式 / `broken` 分解 / `arpeggio` 琶音** | 主歌优先 `broken`，副歌优先 `block`，电子段用 `arpeggio` |
| `startMeasure` | 从第几小节开始写 | 有前奏就跳过，别盖住 intro |
| `trackIndex` / `groupName` | 目标轨与组名 | **永远写进新建的独立组**，名字带用途（如 `Pad-broken`） |

> ⚠️ **能力边界（如实说）**：`sv_write_chords` 输出的是**和弦骨架**（按 `pattern` 铺开），
> **不是成品织体** —— 切分、ostinato、对位、加花这些要**在骨架上再改音符**（`run_script` 批量改，或让用户在钢琴窗微调）。
> 别拿"我们有织体库"来承诺（本 skill v1 = 类型学 + 配方 + 诊断，不是一键生成器）。

### 3.3 写音符的宿主规矩（和 `sv-project-format` / `akdagent-playbook` 一致）
- **判据看 `get_current_group.hostIsSv2`，别看组名**（音频轨的组也叫 `main`，用户也能把任意组改名 `main`）
- **SV1 ⇒ 写主组**（`hostIsSv2 == false`）：主组可写，**织体也写主组**（用户 2026-09-25 定）；**主组非空要先问用户**
- **SV2 / IX ⇒ 必须新建组**（`hostIsSv2 == true`）：IX 的 main 组不能 `addNote`、SV2 主组不可编辑
  ⇒ `write_chords` / `create_harmony_group` 本来就是新建组；`run_script` 也不豁免这条
- 写完**读回校验**：音符数、onset 是否对齐小节、音高范围是否超出乐器音域
- 改工程文件（.ixp/.svp）走安全三步：**用户先保存 → 我们改写 → 用户重载**
- **宿主版本**要留意：`node tools/known-bugs.cjs --list` 看当前已知缺陷/平台约束（**IX 1.0.0 的读点类 API 会冻桥** ⇒ 桥报 `hostOutdated` 时先让用户升级宿主）

### 3.4 按乐器生成织体：`sv_write_texture`（**主要给 IX 用**，2026-09-19 立项）

> 📌 这一节管"**给定乐器 + 段落 + 和弦来源，把织体铺出来**"。它跟 §1–§2 的关系：
> §1 的类型学/§2 的段落表是**判断依据**，这里是**执行落点**。代码在 `server/src/texture/`，离线回归 `cd server && npm run test:texture`（50 项）。

**两条交互路子（用户二选一）**

| 路子 | 谁定织体 | 怎么走 |
|---|---|---|
| **推荐 → 用户选** | 我先给候选，用户挑 | 工具返回 `suggestion`（乐器 × 段落的候选 + 每个候选的理由）；用户点头后再带 `texture` 调一次 |
| **首小节 → 模仿** | **用户自己写第一小节** | 用户写好一小节（或几小节）→ 我把它当模板，按每个目标小节的和弦重建（`texture:"imitate"`）—— 与 IX 侧边栏 `[IX]模板织体生成.js` 同一套映射 |

**和弦来源三种**（`chordSource`）
- `notes`（默认）= **从工程内音符按小节推和弦**（与 IX 侧边栏「旋律和弦生成」同口径：音高类向量 → `detectChord` + Krumhansl 调性）⇒ 适合"工程里已经有旋律/钢琴，照着配织体"。
- `progression` = 用户直接给进行（`['C','G','Am','F']`）⇒ 不依赖工程内容，适合"先铺伴奏"。
- `audio` = **分析音频 WAV**（`audioPath` 必填）⇒ 走与 `sv_write_chords` **同一套扒带链路**：先 `analyzeAudio` 拿调性/BPM，再 `extractChordTrack` 逐段出和弦。⚠️ **必须先拿调性**（实测：跳过这步 key 会是空的、`A#` 也不会被校正成 `Bb`）；扒带结果会**归整成"每小节一个窗口"**：起点**量化到十六分**（治浮点误差，实测 7.99 拍那种）、横跨多小节的段**展开到每一小节**、没有段覆盖的小节**沿用前一个和弦**并标 `carried`（`analysisFromSegs` 的三个坑都已在 `test:texture` 里立了回归）。
- 「音频 + 音符**结合**」（音频定骨架、音符纠错）**本版未实现**，需要时按 `sv_analyze_chord` / 音符分析各跑一次再人工取舍。

**乐器 → 织体（管乐 + 弦乐 13 件；"先做这两族"）**

| 乐器 | 首选织体 | 备选 | 基本不用 | 要点 |
|---|---|---|---|---|
| 长笛 / 短笛 | `broken`（分解）· `arpeggio` | `sustain` · `riff` | `counter` | 中高音区快速音型；低音区没共鸣 |
| 双簧管 / 英国管 | `sustain` · `counter` | `broken` | `arpeggio` · `ostinato` | 音色太突出 ⇒ 长音/对位，密集会抢旋律 |
| 单簧管 | `broken` · `sustain` | `counter` · `block` | — | 音域宽、音色温 ⇒ 内声部首选 |
| 巴松 / 大管 | `sustain` · `counter` | `block` | `arpeggio` · `ostinato` | 木管低音层：根音长音 / 对位走句 |
| 萨克斯 | `riff` · `broken` | `sustain` | `block` | riff 与切分最出味；密柱式会糊 |
| 小号 | `riff` · `block` | `sustain` | `arpeggio` · `ostinato` | 短促有力；连续分解换气跟不上 |
| 圆号 | `sustain` · `block` | `counter` | `riff` · `arpeggio` | 柔和中音区；快速音型不适合 |
| 长号 / 大号 | `sustain` · `block` | `riff` · `counter` | `arpeggio` | 低音铜管长音/柱式；大号不要走句 |
| 小提琴 | `sustain` · `broken` | `block` · `counter` | — | 主歌长音/分解、副歌柱式齐奏 |
| 中提琴 | `broken` · `counter` | `sustain` | — | 内声部；与一提琴同度会干涉 |
| 大提琴 | `counter` · `block` | `sustain` | `arpeggio` | 低音线首选；长音只给根音 |
| 低音提琴 | `sustain` · `counter` | — | `broken` · `arpeggio` · `riff` | 只做长音根音或行走低音 |
| 弦乐群 | `block` · `sustain` | `ostinato` · `counter` | — | 群奏柱式/长音；群奏分解会散 |

> 表是**推荐的起点**，真正的定案走"推荐 → 用户选"。加乐器 = 往 `server/src/texture/instruments.ts` 的 `INSTRUMENTS` 加一条（**别在别处硬编码乐器名**）。

**三条硬约束（工具自动套，`applied` 里如实回报，可用 `applyInstrumentRules:false` 关掉）**
1. **管乐必须留气口** —— 每 **2 小节**为一组，组尾那口气要 ≥ **0.5 拍**；晚于该点的尾音会被丢掉（否则歌手没地方换气）。
2. **弦乐要换弓** —— 连续同音型最多 2 小节，**第 3 小节自动镜像**（以该小节和弦根音为轴）；镜像后越界的音**先整八度移入音域、挪不进去才丢**（2026-09-21 起）。
3. **音域** —— 超出该乐器实用音域的音**先整八度上/下移入音域**（`liftIntoRange`；2026-09-21 真机验收后改 —— 旧行为"一越界就丢"会让**长笛在 C 和弦上整小节无音**），**挪不进去才丢并计数**；管乐低音区、低音提琴高音区最容易踩。
   · **`octaveShift` 现在对具名织体也生效**（同日修：此前 `block`/`broken`/`arpeggio` 三条路线把它写死成 0，只有 `template`/`imitate` 读它）；`plan.liftedIntoRange` 报移八度的音数，`sustain`/`counter` 的移八度数在 `warnings` 里如实写出。

**🆕 技法（`articulations?`，2026-09-21 · 仅 IX）**：统一给本次写入的**所有**音符设同一组技法（如整段 `["Pizz."]`、或 `["Con Sordino","Tenuto"]`）。
- 写入前按 **实测全局互斥图**做**组内自洽化**（保前丢后 + 去重），结果与剔除原因进回包 `articulations.requested/used/dropped`（剔除项另进 `warnings`）。

From Akunda123/SVIXAGENT, MIT.

More from Akunda123/SVIXAGENT