ace-params

Files (1)

• SKILL.md

SKILL.md (first lines)

# ACE 参数功能表（人声曲线 + MIDI 参数）

> **适用范围**：ACE Studio（`app_version 2.1.8` · CLI `0.17.0` · **surface 17.1**）——
> 它**不走我们的桥**（没有心跳/op/面板），一切通过 `acestudio-cli` 或它的 MCP server（63 个工具，`<域>_read`/`<域>_edit`，与 CLI 同一套 surface）。
> ⚠️ 本技能只讲 ACE；**与 Synthesizer V / Instrument X 的桥、参数名、量纲无关**，别混用。
> 真机数据取自 **2026-10-03**（Verse 2.7 声库 / `singing-mamba` 引擎 / 逻辑 clip）；surface 仍自述 **pre-1.0、接口会变**
> ⇒ 任何结论**先按 §1 自查**，别照抄本文。

## 1. ⛔ 先自查（**最重要的一步**）

```powershell
`$cli = "`$env:ProgramFiles\ACE Studio\acestudio-cli.exe"
& $cli vocalparam layers --clip-uuid '{...}' --json     # 这一份 clip 到底有哪些参数/层/形状/尺度，available 是什么
```

- **不要按花名册（参数名列表）猜能不能写** —— 官方口径就是"**读 `available` 与 `unavailableReason`**"。
- `available` / `scale` / `valueRange` / `layers[].{layer,role,shape,access,sparse}` 都由这条命令给出；`layers` 为空 = 不可用。
- 参数花名册**随"声库的引擎世代"与"人声控制路由"变**：`engineGeneration`（如 `singing-mamba` / 老 `verse24`）与 `vocalControlRoute`（`dynamic` 或 `legacy-four-params`）都在这一份输出里报。
- 拿 clip-uuid：`clip list --track-index <N>`（**必须先有这个参数**，否则报缺参）。
- ⚠️ **同一个 clip 的读数会变，别缓存**：实测同一条 Sing clip 在几小时内从 `paramCount=1`（只列 `pitch`、且不可用）变成 `paramCount=6`（`air` 可用）——
  原因是**运行期解析出的声源不同**（后来明确是 `Verse23` / generation `v1`）⇒ **每次现读 `layers`**，不要按上一次结果或声库名推断。

## 2. 真机花名册 —— ⚠️ **两代引擎是两套东西**（2026-10-04 A/B：同一工程两条轨同时读）

> **本节最重要的一句话**：**`param` 名字一样 ≠ 同一种参数** —— **尺度 / 范围 / 层集合全都不一样**（引擎世代不同）。

| | **v2 代**：`Ember Rose` / `Verse 2.7` / `singing-mamba` | **v1 代**：`洛天依` / `Verse23` / `verse24` |
|---|---|---|
| `paramCount` | **7** | **6** |
| **`dynamic`** | ✅ `control` `[-1,1]` · 层只有 `user`/**points** | ❌ **根本没有这一项** |
| `air` | ✅ `model` `[0,1]` · `baseline`(ro,dense) + `user`(rw,dense) | ✅ **`envelope`** `[0.2, **2.5**]` · `baseline`(ro) + **`direct`**(rw) + **`envelope`**(rw) |
| `falsetto` | ✅ `model` `[0,1]` · 同上 | ✅ **`envelope`** `[0.3, 3]` · 同上 |
| `tension` | ✅ `model` `[0,1]` · 同上 | ✅ **`envelope`** `[0.3, 2.5]` · 同上 |
| `energy` | ✅ `model` `[0,1]` · 同上 | ✅ **`envelope`** `[0, 2]` · 同上 |
| **`formant`** | ❌ `available:false`（*"the clip's singing-mamba engine generation has no formant parameter"*） | ✅ **可用**：`envelope` `[-1,1]` · 只有 **`envelope`** 层(rw) |
| `pitch` | ❌ `available:false` | ❌ `available:false`（原因同） |
| `vocalControlRoute` | `dynamic` | **`dynamic`**（⚠️ **但一个 control lane 都不列**） |

#### 2.0 四条硬结论（每条都有 A/B 实测支撑）

1. ⛔ **`dynamic` 是新一代（v2 / `singing-mamba`）独有的** —— v1（`verse24`）花名册里**根本没有它**
   ⇒ 用户口径"**它是 ACE 2 的参数**"成立（详 §2b）。
2. ⛔ **"路由 = `dynamic`" ≠ "有 `dynamic` lane"**：v1 那条 clip **也报** `vocalControlRoute: "dynamic"`，
   但 **一个 control lane 都不列**（官方原话 *"a verse24 clip lists no lanes at all"*）
   ⇒ **路由是工程级设置；lane 有没有取决于引擎**。
3. ⛔ **同名参数的尺度/范围随引擎变**：`air` 在 v2 是 `model` `0..1`，在 v1 是 **`envelope` `0.2..2.5`**（**围绕 1.0 的乘数**）
   ⇒ **跨引擎抄数值一定错**；连"往 SV 换算"的公式也**只对它来源的那一代成立**（见 `akdagent-playbook` §四）。
4. ⛔ **层集合也随引擎变**（**我们之前把 v2 的结论外推了，这里纠正**）：
   - **v2**：`baseline`(ro) + **`user`**(rw) —— **没有** `direct`/`envelope`/`global`
   - **v1**：`baseline`(ro) + **`direct`**(rw) + **`envelope`**(rw) —— **没有** `user`
   ⇒ 所以**别再说"`envelope`/`direct` 这些层不存在"**（文档说"可能存在"是对的，**v1 上就存在**）；
   正确表述：**层集合由引擎决定，以 `vocalparam layers` 的矩阵为准**。

> 🔁 **v2 那套的复现**：两个不同声库读过（`Verse 2.7` + `Ember Rose`），字段逐一致 ⇒ 表稳。
> ⚠️ 但**同一条 clip 的读数也会变**（先后读到 `paramCount` 1 与 6，见 §1）⇒ **表可以信，读数必须每次现读**。

#### 2.0b 下面这张是 **v2 那套的逐字段原样**（供照抄/对账）

| 参数 | available | `scale` | `valueRange` | 层（`access` / `shape`） |
|---|---|---|---|---|
| `dynamic` | ✅ | `control` | `[-1, 1]` | `user`: **rw** / **points**（稀疏锚点） |
| `air` | ✅ | `model` | `[0, 1]` | `baseline`: ro / dense · `user`: **rw** / **dense** |
| `falsetto` | ✅ | `model` | `[0, 1]` | 同上 |
| `tension` | ✅ | `model` | `[0, 1]` | 同上 |
| `energy` | ✅ | `model` | `[0, 1]` | 同上 |
| `formant` | ❌ | — | — | reason：**"the clip's singing-mamba engine generation has no formant parameter"** |
| `pitch` | ❌ | `semitones` | — | reason：**"pitch curves are not on this surface yet: the channel stores a delta while the draw primitive takes absolute pitch, and anchors and vibrato ride on top"** |

⚠️ 从这张（v2 的）表直接读出来的两条：

1. **`formant` 与 `pitch` 是"看得见、用不了"**（**仅限 v2**；v1 上 `formant` 是**可用**的，见上面的 A/B 表）。
2. **`pitch` 的原因不是"没做完"，是语义对不上**（通道存 **delta**、draw 原语收 **absolute**，anchors/vibrato 还要叠上去）。

> 🔁 **2026-10-04 复现（换了声库）**：在另一声库（**`Ember Rose` / `Verse 2.7` / generation v2**，同 `singing-mamba` + route=`dynamic`）上再读一次，
> **这 7 行逐字段一致** —— 含 `dynamic` 只有 `user`/`points`、四个 `model` 参数的 `baseline`（只读/dense/`analyzed-pristine`）+ `user`（读写/dense/**sparse**）、
> `formant`/`pitch` 的 `available:false` 与各自原因原样 ⇒ **这张表是稳的**。
> ⚠️ **但"读数"本身会变**：同一条 v1 clip 我们先后读到 `paramCount=1` 和 `6`（见 §1）⇒ **表可以信，读数必须每次现读**。

### 2b. `dynamic` 是什么（**人声**，不是器乐）—— 以及"**为什么你可能没见过它**"

- **它是人声参数**：属于**"人声控制"（vocal controls）**——面板顶部那排 pill / 抽屉，**不是** MIDI/器乐参数。
  器乐那侧在别的域：`midiparam`（CC / pitchbend / velocity）、`instrument`/`fx`/`audio-plugin set-param`（归一化 `0..1`）。
- ⭐ **定性（用户 2026-10-04 确认）**：`dynamic` 是 **ACE 2 的参数，用来调整"整体动态"** ——
  即它**不是**逐音符的力度，而是**整段/整体的动态**（表情）旋钮；这与下面两条完全吻合：
  ① 官方原话 *"Dynamic stands in for those lanes"*（它替掉上一代那四条）；
  ② 我们实测**只在 `singing-mamba`（v2 代）的 clip 上见到它**（两次、两个不同声库都在）；而老一代 `verse24` 的 clip 花名册里**没有它**
  —— **2026-10-04 A/B 实测钉死**（同工程 index 0 = v2 有、index 4 = v1 没有，全表逐行比对，见 §2 表）。
  ⇒ **一句话记法**：`dynamic` = **ACE 2 的整体动态宏**（双极性：一头柔/气、一头力量/胸腔）。
- **它是"四合一替身"**：官方原话 *"Dynamic stands in for those lanes"* ⇒ `dynamic` 一个 lane **合并代表**
  老的四个（`power` / `soft` / `airy` / `chest`）；**它们四个在 `dynamic` 路由下根本不列出来**。
- **语义是双极性的表情宏**（官方示例原话）：**负值偏 Soft / Breathy，正值偏 Power / Chest** ——
  ⇒ ⚠️ 它**不等于"响度"**：它同时带了音色轴。转 SV 时只落 `loudness` 会丢音色那一半
  （要补就得同时给声线/`vocalMode_*`，SV 侧没有单一对应）。
- **它只在一条路由上存在**（`vocalControlRoute`，两条二选一）：
  | 路由 | 面板/花名册列出 | 不列出 |
  |---|---|---|
  | `dynamic` | **`dynamic`** + 该声库发布的其他所有 control | 被它合并的四个（`power`/`soft`/`airy`/`chest`） |
  | `legacy-four-params` | 四个（`power`/`soft`/`airy`/`chest`）+ 其他 control | **`dynamic`** |
- ⚠️ **路由在工程加载时定死、永远不改**：官方原话 *"it is never set"* —— **CLI 改不了、UI 也改不了**
  ⇒ 所以"我在面板上没见过 dynamic"**完全正常**，多半是你那个工程落在 `legacy-four-params` 路由上；
  想见到它只能**换声库/新工程**，没有"切过去"的操作。
- ⚠️ **引擎世代决定 control lane 有没有**：`dynamic`/`rap`/`opera`… 这些**人声控制**挂在 **`singing-mamba`** 面板上，
  官方原话 *"a verse24 clip lists no lanes at all"* —— **但这句话说的是 control lane**：
  实测老 `verse24`（v1 声库）的 clip **仍会列出 `model` 那四个**（我们读到 `paramCount=6`、`air.available=true`）。
  ⇒ 别把"没有 control lane"读成"没有参数"；**一切以当场 `vocalparam layers` 为准**。
- **层形状也特殊**：`dynamic` **只有 `user` 一层、形状 `points`**（没有 `baseline`/`envelope`/`direct`）
  ⇒ 因此它**没有 `global` 旋钮、也就没有 `effective` 合并曲线**（官方两处点名：`effective` 对 Dynamic 缺席）。
  写它就是写**锚点**：`--points '[[0,-0.5],[960,0.8]]'`（**不用** `--pos-begin`）。

## 3. 尺度不可混用（官方原话 "Scales are not interchangeable"）

| 尺度名 | 出现在哪 | 量纲 |
|---|---|---|
| `model` | **v2 代**的 `air`/`falsetto`/`tension`/`energy` | `0..1` |
| **`envelope`** | ⚠️ **它不只是"层"，也可以是参数自己的尺度**：**v1 代**的 `air`/`falsetto`/`tension`/`energy`/`formant` 全是这个尺度 | **围绕 `1.0` 的乘数**（实测范围举例 `air 0.2..2.5` · `falsetto 0.3..3` · `tension 0.3..2.5` · `energy 0..2` · `formant -1..1`） |
| `control` | `dynamic`（以及声库发布的"人声控制"） | lane 通常 `0..1.25`；`dynamic` 是 `[-1, +1]` |
| `semitones` | `pitch`（两代都不可用） | 半音 |

**同一个数字在不同参数上意思不同，写错不会报错 —— 会变成另一种意思。**

From Akunda123/SVIXAGENT, MIT.

More from Akunda123/SVIXAGENT