acep

Files (8)

• SKILL.md
• char-tone.json · references/
• acep.cjs · scripts/
• f0-contour.cjs · scripts/
• lane-poke.cjs · scripts/
• lane-report.cjs · scripts/
• lyric-tones.cjs · scripts/
• tree-diff.cjs · scripts/

SKILL.md (first lines)

# `.acep` 工程文件：格式与安全改写

> 适用 **ACE Studio 2.1.8** · `acestudio-cli 0.17.0` · surface **17.1**（第三方宿主，**不走我们的桥**）。
> 本文数字全是**真机实测**（2026-10-04；样本 = 5.5 KB 单音符 Sing 工程 / 20.5 KB 带音高曲线工程 / 2 MB 真实歌曲工程 / 本机 93 个 `.acep` 普查）。
> surface 自述 pre-1.0、接口会变 ⇒ **先按 §0 判断该不该走文件**，别照抄本文。

## 0. ⛔ 先问三句（顺序不能反）

1. **CLI 能不能做？** 能 ⇒ **永远走 CLI**。CLI 有撤销栈（`history undo`）、指纹（`--if-match`）、原子拒写（失败什么都不改）；
   文件改**三样都没有** —— 没有撤销、没有指纹、没有校验回执，只有你自己写的自检。
   已知**只有文件里才有**的典型：**人声音高曲线**（`vocalparam` 里 `pitch` 恒 `available:false`）—— 那才是走文件的理由。
2. **ACE 加载时会不会把我的改动丢掉？** 会（实测：非法音素覆盖被静默清掉，见 §5.1）⇒ 写完**必须让 ACE 读回来复核**。
3. **我怎么验收？** 只读命令能不能证明改动生效（`clip note-content` / `phoneme list` / `project info`）？
   证明不了就别急着交付 —— 用**文件级自检 + ACE 读回**两层。

## 1. 容器：`ACEP2` = 1280 B 头 + 一个 zstd 帧

```
off 0        "ACEP2" + 01 01 00          魔数 + 版本三字节
off 8        u32   头部长度（= payload 起点；实测 1280）
off 12       u32   0
off 16       u64   压缩长度   ← 头长 + 压缩长 = 文件大小（可用来判"文件被截断没有"）
off 24       u64   原始长度   ← 解压后应有的字节数
off 32..1279       1248 B 高熵区（香农熵 7.84 bit/B；gzip/deflate/brotli/裸 zstd 全解不开）—— 用途未知
off 1280           zstd 帧（魔数 28 b5 2f fd …），解出来就是 payload
```

### 1.0 万一打不开：`.acep` 还有两种历史壳（**正常情况不用管**）

> 当前格式就是 §1 的 `ACEP2`，**正常路径不需要判壳**。只有"解不开/首字节不是 `ACEP2`"时才对一下下面两条——
> 工具 `info` 会直接点名是哪种（`unpack` / `get` / `dump` 三种壳里可读的两种都认）。

- **历史一（可读、可编辑）**：首字节 `{"compressMethod":"zstd"` —— 包装 JSON（`content` = base64 的 zstd 帧、`salt`、`version:1000`），解出来是**内层 JSON 文本**。
  改法**不是** §4，走 `set-json`（整树解析 → 改路径 → 重 stringify → 重 zstd → 重 base64 → 重建包装，只换 `content`）。
  实测（`我曾遇到.acep`，2023-08，改轨名）：**回读一致 ✅、包装键齐全 ✅**（内层 259,818 B → 文件 25,651 B）。
- **历史二（加密、已弃用，不处理）**：首字节 `{"content"` 且**没有** `compressMethod`（`salt` 是两段 `16 B*8 B`）——
  `content` 解 base64 后 **zstd（含补魔数）/gzip/deflate/brotli 全解不开**、熵 **7.978 bit/B** ⇒ **是加密**。
  **不尝试解密**（`info` 会明说"不碰"）；要那份工程只能用当年那版 ACE 打开后另存。
  ⚠️ `version:2` 只是它**唯一样本**的特征，**不是判据** —— 别拿版本号下结论。

> ✅ **旧壳会被 ACE 自己升级成新壳**（2026-10-04 实测，**很实用**）：拿一份"历史一"工程（`senpa.acep`，213,087 B）
> 让 ACE `project open` → `project save`，落盘后 `info` 报 **`ACEP2`**、76,152 B，**内容无损**（67 个音符、23 条 `pitchDelta` entry 与值域原样）。
> ⇒ **想让旧工程走文件路线（如画音高线）**：先让 ACE 打开并保存一次，升成 `ACEP2` 再动手（我们的写工具只吃新壳）。

### 1.1 打包（重新压缩）时只动三处

| 位置 | 写什么 |
|---|---|
| `off 8` | 头部长度（**不变**，仍是 1280） |
| `off 16` | 新压缩长度 |
| `off 24` | 新原始长度 |

**其余头部字节从源文件原样复制**，尤其那 1248 B 高熵区。

> 为什么敢原样复制：拿一份 ACE 自己存的工程，只改 payload 里的一个文本项、其余头字节照抄 ⇒ 头部**逐字节相同**、ACE 正常打开
> ⇒ 这说明高熵区**不是 payload 的校验和**（payload 都变了它却没变），也说明它至少不拦这种改法。

## 2. payload 是 **CBOR**（不是 JSON、也不是自定义二进制）

### 2.1 顶层与对象形态

顶层是 map（实测 **26 键**）：

```
version(22) versionRevision duration trackCells pianoCells colorIndex mergedPatternIndex
recordPatternIndex trackControlPanelW loop singer_library_id extraInfo patternIndividualColorIndex
tempoBrushOn minBpm(60) maxBpm(180) tempoTrackHeight canvas{width,height,frameRate,adaptive}
vocalControlRoute tempos[] timeSignatures[] master **tracks[100]** chordTrack videoTracks[] pianoDisplayConfig
```

- `tracks` 恒 **100 个槽位**（空槽也在，且被自动配色吃过颜色 —— 这就是 CLI 里"空轨道槽"的来源；读回来时空槽没有 `trackUuid`）。
- 轨道对象：`uuid/type/name/gain/pan/mute/solo/record/listen/color/externalFxChain/extraInfo/inputSource/`
  `soundSourceMetadata/singers/choirConfig/roomEffect/language/recordMode` + **`patterns[]`**。
- pattern 对象：`uuid/name/timeUnit/pos/dur/clipPos/clipDur/enabled/color/fadeIn/fadeOut/extraInfo`
  + **`notes[]`** + **`parameters{}`** + `vocalControls{}`。
- 音符里的歌词/读音：`lyric`（字）+ **`syllable`**（音素覆盖，空格分隔符号串；`""` = 没有覆盖、用默认发音）
  + `freezedDefaultSyllable`（冻结的默认读音）+ `headConsonants` / `tailConsonants`（**头/尾辅音长度，秒**）
  + `brLen`（呼吸长度）+ **`phonemeTimings`**（v2 的 pins：**数组的数组** `[[符号, 秒], …]`）—— 时长的两套存法见 **§2.4**。
  CLI 侧 `clip note-content` 的 `syllable` 字段就是它。

### 2.2 参数曲线 lane

```
tracks[i].patterns[j].parameters.<lane> = [ { type, offset, values }, … ]   // 实测 1 条或多条 entry
```

| lane | 样本数 | `offset` | 说明 |
|---|---|---|---|
| **`pitchDelta`** | **3095** | **360** | **人声音高曲线**（半音偏移，相对音符音高）—— 文件里唯一能改音高的地方 |
| `vuv` | 3095 | 360 | 有声/无声（0/1） |
| **`energy` / `tension` / `air`（envelope 系）** | **1 样本/tick** | 段起点 tick | ✅ **2026-10-05 定量**：`vocalparam read --param energy --range-begin 10000 --range-end 11000` 回 **`count:1000`、每层 `points:1000`** ⇒ **960 Hz**（**不是** pitchDelta 的 15/16 tick/样本） |
| `gender` / `mamba*` | 空 | — | ⚠️ 只在**新世代（singing-mamba）** clip 上有；ACE 明说"lane exist on the singing-mamba generation, this clip's singer is verse24" |

**编码**：`values` 是 CBOR 数组，每项 `0xfb` + **float64 大端** = **9 字节/值**
⇒ **元素个数不变时可以直接原位覆盖**，**完全不用重编码 CBOR**。这是本技能所有写法的地基。

- ⚠️ **entry 里的 tick 是「片段内局部坐标」，不是工程绝对 tick**（2026-10-05 实测）：
  绝对位置 = `pattern.pos` + entry 的 `offset`/`points` 里的 tick。
  证据：用户工程 `pattern.pos=3120`、`pitchDelta[0].offset=177` ⇒ 渲染音频的第一声正好在 `(3120+177)/960 = 3.434 s` ✓
  （`notes[].pos` 也是同一个局部坐标系 ⇒ 画曲线时**不要**自己加 `pattern.pos`。）

- ⚠️ **一条 lane 可以有 N 条 entry（曲线是分段存的）**：实测一份 2023 工程 `pitchDelta` **95 条**、`tension` **85 条**、`vuv` **78 条**
  （每条 entry 带自己的 `offset` + `values`）；我们自己的新工程常见 1 条（一条 lane 一条 entry）。
  - ✅ **ACE 保存时会"合并"分段**（2026-10-04 实测）：我们写 3 条 entry（offset `0`/`1121`/`2243`，覆盖 tick `0–3362`），ACE `save` 后变成**1 条** entry（offset `0` / 3586 样本），
    **值逐样本保留**（非零数与值域不变）。⇒ 多 entry 写是安全的；**别指望"写完还是几条"**，回读要按"合并后的那一条"比。

**⛔ 音高线有「三种画法」，落在「三个不同的地方」**（2026-10-05：用户指认画法 + 读其工程 `%USERPROFILE%\Documents\lala-resaved\未命名.acep` 照出存储位置）：

| 画法（UI 口径，用户 2026-10-05 指认） | 存在哪 | 形态 | 坐标语义 |
|---|---|---|---|
| ① **曲线** | `patterns[*].parameters.pitchDelta[i]` | `type:"data"` + `offset` + `values`（float64 数组） | **delta（半音，相对音符音高）** |
| ② **锚点** | 同一个 `pitchDelta` 里的另一条 entry | `type:"anchor"` + `points` + `pointsVUV`（**没有 `offset`/`values`**） | **绝对音高**（不是 delta！）`points` = `[tick, 音高, tick, 音高, …]`；`pointsVUV` = 每点一个 `0/1` |
| ③ **颤音（跟随音符走）** | **`notes[k].vibrato`**（音符自己的字段，**不在 lane 里**） | 对象，8 个字段（见下） | **音符内偏移**（`startPos` 相对本音符起点）⇒ 音符一挪，颤音跟着走 |

⇒ 所以 ① ② 会**混在同一条 lane 里**（一串 entry，按时间顺序接力），③ 则完全不在 lane 里。
⇒ **三种都能手写**（2026-10-05 逐项验收，见 §5.5）：① 等长原位覆盖；② 走 `scripts/acep.cjs anchor`（插 entry 只能追加到 lane 末尾）；③ 走 `scripts/acep.cjs vibrato`（没有颤音的音符要**插键**）。

> 💡 ACE 自己就是这么说的（`vocalparam layers` 里 pitch 行 `available:false` 的 `unavailableReason` 原文）：
> **"the channel stores a delta while the draw primitive takes absolute pitch, and anchors and vibrato ride on top"**

From Akunda123/SVIXAGENT, MIT.

More from Akunda123/SVIXAGENT