sv-scripting

Files (52)

• SKILL.md
• ArrangementSelectionState.md · api/
• ArrangementView.md · api/
• Automation.md · api/
• CoordinateSystem.md · api/
• GroupSelection.md · api/
• Home.md · api/
• MainEditorView.md · api/
• NestedObject.md · api/
• Note.md · api/
• NoteGroup.md · api/
• NoteGroupReference.md · api/
• PitchControlCurve.md · api/
• PitchControlPoint.md · api/
• PlaybackControl.md · api/
• Project.md · api/
• README.md · api/
• RetakeList.md · api/
• SV.md · api/
• ScriptableNestedObject.md · api/
• SelectionStateBase.md · api/
• TimeAxis.md · api/
• Track.md · api/
• TrackInnerSelectionState.md · api/
• TrackMixer.md · api/
• Tutorials.md · api/
• WidgetValue.md · api/
• _sync.json · api/
• BPM检测歧义.md · examples/
• MusicXML解析-NaN.md · examples/
• 咬字糊成一团.md · examples/
• 小节标记失效-纯音频工程.md · examples/
• 情绪推不上去-副歌不燃.md · examples/
• 拆轨拼接处断开或跳音.md · examples/
• 桥超时与宿主闪退.md · examples/
• 演唱机械感-像念稿.md · examples/
• 电音感与音色突变.md · examples/
• 载荷过大-ENAMETOOLONG.md · examples/
• 颤音假-像抽搐.md · examples/
• 01-official.md · references/
• 02-lyrics.md · references/
• 03-phonemes.md · references/
• 04-notes.md · references/
• 05-params.md · references/
• 06-track-misc.md · references/
• 07-melody-accent-pitch-params.md · references/
• 08-pit-drawing.md · references/
• 09-拆轨与拆音.md · references/
• 10-声库与声线.md · references/
• 11-风格配方.md · references/
• README.md · references/
• 官方API-实测勘误.md · references/

SKILL.md (first lines)

# Synthesizer V Studio 脚本开发

## 先看这里：症状索引

带着问题来的（报错/超时/闪退/结果不对），**先定位症状**，再去 `examples/` 里翻对应的那一篇：

| 症状 | 去哪看 |
|---|---|
| 工具报 `spawn ENAMETOOLONG`、请求没到宿主 | `examples/载荷过大-ENAMETOOLONG.md` |
| 桥超时 10s、宿主直接重启 | `examples/桥超时与宿主闪退.md` |
| 工具报 `unknown op: xxx`（改了桥但没生效）| `examples/桥超时与宿主闪退.md`（问题 B）|
| BPM 检测结果和实际不符、"对轨越到后面越偏" | `examples/BPM检测歧义.md` |
| 按小节对齐算出的偏移不对（纯音频工程）| `examples/小节标记失效-纯音频工程.md` |
| 解析乐谱/XML 后字段是 `NaN` / `none` / 空 | `examples/MusicXML解析-NaN.md` |
| 唱出来很机械、像念稿，一点人味都没有 | `examples/演唱机械感-像念稿.md` |
| 颤音听着假、像抽搐，加进去还不如不加 | `examples/颤音假-像抽搐.md` |
| 咬字糊成一团、听不清、口型也不对 | `examples/咬字糊成一团.md` |
| 情绪推不上去、副歌爆发不出来、抒情段一点都不感人 | `examples/情绪推不上去-副歌不燃.md` |
| 有电音感、金属感，参数一动就炸 | `examples/电音感与音色突变.md` |
| 拆完之后能听出是两轨、接缝处断掉或者跳到别的音高 | `examples/拆轨拼接处断开或跳音.md` |
| 报 `X is not a function` / `undefined not callable` | 下面「⚠️ API 勘误」一节 |
| 写操作被拒 / 宿主可撤销性丢失 | 下面「⚠️ API 勘误」第 3 条（`newUndoRecord`）|
| 不确定某件事 API 支不支持（导出音频 / 保存工程 / 导入音频轨 / 挑声库 / 枚举唱法名）| 下面「⛔ 官方 API 做不到的事」 |

## 结构

Synthesizer V Studio 脚本开发的完整参考，组织为四部分：

| 部分 | 目录 | 内容 |
|---|---|---|
| **API** | `api/` | 完整类文档（由官方 Scripting Manual HTML 原封不动转换）：每个类一个子 md，`api/README.md` 为索引。⚠️ **官方镜像，别往里写自研内容**（`tools/api-docs-sync.cjs --update` 整批重写；守卫 `check-api-mirror.cjs`） |
| **参考正文** | `references/` | **`01`–`11` 一条连续编号**（见下）：01–06 偏**代码片段**（官方仓库 + AKD 精选写法）· 07–11 偏**做法与手册**（调声 · Pit · 拆轨 · 声库 · 风格配方）· 另加 `官方API-实测勘误.md`（**实现侧**对官方 API 的实测勘误）。总索引见 `references/README.md` |
| **案例** | `examples/` | 真实踩坑记录：**问题 ⇒ 诊断 ⇒ 怎么改 ⇒ 改后效果 ⇒ 可复用判断标准** |

> 📌 **2026-09-21 目录合并（用户裁「先备份，再 B」）**：原先 `01`–`06` 在 `functions/`、`07`–`11` 在 `workflows/`，
> 现统一并入 **`references/01`–`11`**（编号连续、按**文档性质**分目录，与 `sv-lyricist` / `sv-ix` / `composition` 等技能一致）。
> **改名缘由（史证留着，免得下次又疑惑）**：原两个目录名沿自**上游官方手册的三段式**（站点分区就是 API / Functions / Workflows），
> 并非按我们的内容命名 —— `workflows/` 原定放"脚本类型 / 安装位置 / 调试技巧 / 常见 Bug / 最佳实践"
> （那行字当年写在 `workflows/.gitkeep` 里），但**这批内容始终没导入**，占位反被我们自己的主题手册（07–11）填了
> ⇒ 「名字像工作流、内容其实是手册」的**名实漂移**；且 `01`–`11` 本是连续编号，横跨两目录时**单看 `workflows/` 会以为缺 01–06**。
> ⚠️ **DSH 技能加载器只认"顶层目录里有 `SKILL.md`"**（`dsh-skill-filesystem`：`segments.length === 2 && segments[1] === "SKILL.md"`）
> ⇒ 子目录叫什么、有几层，**不影响注册与调用**；这次合并纯粹是为了**人和模型找东西时的直觉**。

> 时间单位：**blick**，`SV.QUARTER = 705600000` blicks = 一个四分音符。

## 案例（examples/）

每个案例都是**真机踩过的坑**，格式统一为「问题 ⇒ 诊断 ⇒ 怎么改 ⇒ 改后效果 ⇒ 可复用判断标准」。
遇到新问题先查这里；解决了新坑就补一篇（这是最省时间的资产，比重复踩第二次便宜得多）。

- `载荷过大-ENAMETOOLONG.md` — 载荷超 Windows 命令行上限（双重 base64 膨胀 7 倍）
- `BPM检测歧义.md` — `confidence` 无区分度，必须看候选列表 + 支持手动指定 BPM
- `小节标记失效-纯音频工程.md` — `getMeasureMarkAt` 在无音符组工程返回全 0，改用 tempo 换算
- `MusicXML解析-NaN.md` — 手写 XML 解析器漏了结束标签弹栈 + 叶子节点未坍缩
- `桥超时与宿主闪退.md` — 读 automation 点数据闪退；改了桥忘重载报 unknown op

**调声类案例**（同名症状 → 病因 → 手法 → 判据，与技术坑分开列）：

- `演唱机械感-像念稿.md` — 最大来源是音头 Pit 从没处理过；辅音长短、段内张力只有两档
- `颤音假-像抽搐.md` — 先清零深度；频率 5~8 / 幅度 0.5~2.0；下颤必须收回标准音高
- `咬字糊成一团.md` — 先排空格 / 多音字 / 前后鼻音，再按七级成本阶梯往上走
- `情绪推不上去-副歌不燃.md` — 力度 ≠ 张力；先做段落规划，张力满了就回头加 Pit
- `电音感与音色突变.md` — 五个独立来源；张力穿过 0 点要画成 S 形
- `拆轨拼接处断开或跳音.md` — 先确认要不要拆；摩擦音连住、塞擦音留缝

## API（已导入）

完整类文档见 `api/` 目录（由官方 HTML 文档转换，内容原封不动）：

- [api/README.md](api/README.md) — 类索引
- 核心类：`api/SV.md`（全局对象）、`api/Note.md`、`api/NoteGroup.md`、`api/NoteGroupReference.md`、`api/Track.md`、`api/Project.md`、`api/Automation.md`、`api/TimeAxis.md`
- 选择/视图：`api/MainEditorView.md`、`api/ArrangementView.md`、`api/TrackInnerSelectionState.md`、`api/SelectionStateBase.md`、`api/CoordinateSystem.md`
- 音高控制：`api/PitchControlCurve.md`、`api/PitchControlPoint.md`
- 其他：`api/PlaybackControl.md`、`api/TrackMixer.md`、`api/RetakeList.md`、`api/ScriptableNestedObject.md`、`api/NestedObject.md`、`api/WidgetValue.md`、`api/GroupSelection.md`

> ⭐ **先查文档，再调用**（2026-09-20 · **血泪规则**）：写脚本前**必须**先查清精确签名 —— 一条命令
> `node tools/api-lookup.cjs Note#setLyrics`（列类 `api-lookup.cjs Note` · 不知在哪类 `--search 关键词`）。
> ⛔ **别用"真机试错"确认签名**：试错在 SV1 上会弹模态框**冻死桥**（见 `known-bugs` 的 `SV-001`）；2026-09-20 正因没查文档，
> 把 `Automation.getPoints(begin, end)`（**文档里连返回结构例子都有**）误判成"序列化卡死"，把整族正常 API 拉黑了。

## 参考正文 · 01–06（以**代码片段**为主）

可复用函数库见 `references/` 的 **01–06**（来源：官方 svstudio-scripts + 本机 AKD 脚本 SV1/SV2 精选，全部 ES5.1）：

- [references/README.md](references/README.md) — **01–11 总索引** + 通用骨架 + ES5.1 约束 + 来源目录
- [references/01-official.md](references/01-official.md) — 官方仓库：异步对话框链/setTimeout 轮询/二分搜索/合并分割缩放音符/跳静音播放/随机化
- [references/02-lyrics.md](references/02-lyrics.md) — 歌词：收集/剪贴板往返/合并前移后移/+/−/多音节/lrc 导出/填词/简谱
- [references/03-phonemes.md](references/03-phonemes.md) — 音素：辅音判定/分割元音辅音/批量替换/辅音长度/音素比例/呼吸音/多音节+
- [references/04-notes.md](references/04-notes.md) — 音符：播放头分割/拼接/避免重叠/移调/随机偏移/分轨/选中播放/实时预览
- [references/05-params.md](references/05-params.md) — 参数：复制/同步映射/简化/PitchControl 曲线/固定音高/颤音/EDO19/detune
- [references/06-track-misc.md](references/06-track-misc.md) — 轨道/工程：分轨/跨轨复制/工程缩放/自动 BPM/和声/变色/水印

写脚本时按主题读取对应文件，函数可直接复制进桥脚本或新脚本（ES5.1）。

## 参考正文 · 07–11（以**做法与手册**为主）

⚠️ 「脚本类型 / 安装位置 / 调试技巧 / 常见 Bug / 最佳实践」这批内容**至今仍未导入**（当年是 `workflows/` 的预留位，
目录名已在 2026-09-21 合并时取消；那批踩坑经验的实际入口在 **`akdagent-playbook`**）。本目录现有 07–11：

- [references/07-melody-accent-pitch-params.md](references/07-melody-accent-pitch-params.md) — **旋律重音 → 倚音 → 渲染**完整链路：
  ① 重音判断（强拍/时值/跳进/歌词语义/邻音降权）；② `-` 歌词区分倚音(并入)/转音(独立)；
  ③ 倚音生成（**三种**：前倚音 §1.7 · 后倚音 / 音尾音阶行进 §1.8，含自动判型 `decideOrnament`；强规则：相连+大跳+长度）；④ **画音高线**（音头下沉/上扬/抖动、音尾让位、转音五类型、
  **倚音挖动态坑**、防电音/拖沓的幅度判据）；⑤ 参数应用 + **重音完整渲染配方**（Pit+张力+响度+发声+气声）；
  ⑥ **§3.5 段落力度规划 · 渐强六步 · 张力已满时的四条出路**（来源案例：`examples/情绪推不上去-副歌不燃.md`）。
- [references/08-pit-drawing.md](references/08-pit-drawing.md) — **Pit 绘制底层**：SV1 `PitchAutoMode`
  与手动模式的 12 个字段（tF0*/dF0*/fF0Vbr/pF0Vbr/tNoteOffset）、`NaN`=默认值的坑、
  **§2.4 九段响应表（形状 ↔ 属性，含可达区间与反解式）**、**SV1/SV2 双通道落地（属性 / `pitchDelta`）**、
  §6.2b 特殊音头、以及 `write_pit` 的实机验证结论。
- [references/09-拆轨与拆音.md](references/09-拆轨与拆音.md) — **拆音 / 拆轨主题**：拆音 vs 拆轨对照、
  "天然衔接"原理（唯一判定标准＝拼起来像一轨）、**五级成本阶梯**（换采样／音素力度 ⇒ 近义歌词 ⇒ 音素替换 ⇒ 拆音 ⇒ 拆轨）、
  **值得拆的 6 种情况**、五种方式（换辅音 / 改连贯度 / 替换清辅音 / 元音过渡 / 三轨拼一字）、通用坑与心态。
- [references/10-声库与声线.md](references/10-声库与声线.md) — **声库挑选 · 多声线切换 · AI 声库坑**：
  采样库 ↔ AI 声库总表、选库判断标准、**多声线切换点必须落在轻辅音上**（`b/p`、`d/t`、`z/c/s`）、
  AI 的坑（参数与音频错位、自动挖坑、自动加气泡音、`/U/` 不认）与正向红利；
  **§5.1 呼吸音上的两条坑**（采样库偏电 → 后期贴；AI 极短空拍 `br` → 改 `sil` 另拆一轨）。
- [references/11-风格配方.md](references/11-风格配方.md) — **唱法手法全集**（`风格化调声.md` 全量落地，「都搬过来」）：
  **通俗五型**（抒情喜舒缓/喜元气/怒摇滚/哀哭腔/哀颓废失声）· **R&B**（五声转音＋句尾落 la）· **说唱三型** ·
  **京剧旦角**（大颤 5.5 + 下颤 + 大开大合咬字）· **黄梅戏**（逐字装饰音）· **藏腔**（3 半音小尖尖＋上跳必须降张力）·
  **蒙古长调**（转音落五声 + 音头下沉多）· **岛呗** · **约德尔** · **呼麦**（做不到，如实告知）· **美声**（梭子形 + 音头硬边界 + EQ）·

From Akunda123/SVIXAGENT, MIT.

More from Akunda123/SVIXAGENT