# guzheng

**Repository Path**: imflyfish/guzheng

## Basic Information

- **Project Name**: guzheng
- **Description**: 古箏 · 物理建模弹拨合成器
浏览器里的二十一根弦古筝。发声不靠采样音色库，而是用 AudioWorklet 实时跑 数字波导（Digital Waveguide）物理模型：弦被拨响后每一个采样点都在算，音高、 频散、拍音、衰减、木箱共鸣全部由物理量推出来。

零外部依赖、零构建步骤 —— 纯 HTML + CSS + JS，丢进任意静态服务器即可打开。
- **Primary Language**: JavaScript
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-09-18
- **Last Updated**: 2026-09-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 古箏 · 物理建模弹拨合成器

浏览器里的**二十一根弦**古筝。发声不靠采样音色库，而是用 **AudioWorklet** 实时跑
数字波导（Digital Waveguide）物理模型：弦被拨响后每一个采样点都在算，音高、
频散、拍音、衰减、木箱共鸣全部由物理量推出来。

零外部依赖、零构建步骤 —— **纯 HTML + CSS + JS**，丢进任意静态服务器即可打开。

## 在线访问

**https://dev.321zou.com/guzheng/www**

无需安装、无需注册，打开即弹。第一次点弦（或按键）时启音 —— 浏览器要求用户手势
才能建 `AudioContext`，所以没有启动页，第一下就有声。

> 💡 建议用**手机或平板**打开：它是给手指设计的，触屏上有按弦、刮奏、摇指这些
> 键盘给不了的东西。PC 上也能弹，弦的右端会标出每根弦对应的键盘按键。

```
https://dev.321zou.com/guzheng/www/          → 入口页，自动换成琴页
https://dev.321zou.com/guzheng/www/main.html → 琴页本体（可单独访问/异地部署）
```

自建部署见 [快速开始](#快速开始)。

---

## 目录

- [它是什么](#它是什么)
- [在线访问](#在线访问)
- [快速开始](#快速开始)
- [功能一览](#功能一览)
- [演奏方式](#演奏方式)
- [软件架构](#软件架构)
- [物理模型要点](#物理模型要点)
- [三台引擎](#三台引擎)
- [面板参数](#面板参数)
- [曲目](#曲目)
- [二次开发](#二次开发)
- [已知约束与取舍](#已知约束与取舍)

---

## 它是什么

一台可在手机 / 平板上弹的古筝仿真器，同时是一份**物理建模的完整实现记录**。

- **音高是解出来的，不是查出来的**：环路总相位 = 2π 才有正确音高，代码逐弦解析
  求解分数延迟全通 + 色散全通 + 一阶低通三者的相位贡献（基频误差 < 0.11 音分）。
- **不同机型的音高差异会被测出来补回去**：启动后静默跑一次逐弦离线渲染测频，
  把机型 / 采样率带来的偏差逐弦补偿（见下文「自动调音」）。
- **三台引擎可 A/B 对比**：物理波导建模 / 1983 年原始的 Karplus-Strong /
  由 21 弦真实录音反解的实测引擎（**出厂默认**）。同一组参数一键切换 ——
  前两者是**时域波导递归**（阻尼由环路滤波器间接决定），第三者是
  **模态加法合成**（每个谐波的幅度与衰减率逐条查表），
  听得出"建模方式"本身带来的差别。

---

## 快速开始

### 1. 起一个静态服务器

音频处理器（AudioWorklet 源码）是用 `fetch` 取回的，**必须经 HTTP(S) 访问**。
直接双击本地 `index.html`（`file://`）会被浏览器安全策略拦掉。

```bash
cd guzheng
python3 -m http.server 8000
# 然后浏览器打开 http://localhost:8000/
```

任何等价方式均可（`npx serve`、nginx、对象存储静态托管……），只要能通过
HTTP 提供目录下的文件即可。想直接访问线上实例，见上方 [在线访问](#在线访问)。

### 2. 入口与琴页

站点根访问 `index.html` 时，它会立刻 `location.replace` 到 `main.html` 并保留
query / hash；没有 JS 的环境（或爬虫）则停在该页读到部署说明。所以：

- 正常用户：访问站点根即可。
- 想内嵌 / 指定入口：可直接访问 `main.html`。

### 3. 第一次触摸即启音

浏览器要求用户手势才能建 `AudioContext`，所以本琴**没有启动页**：第一次点弦
（或按键）时顺手把音频起起来，并补发这一击 —— 第一下就有声。若音频起不来
（`file://`、旧浏览器、处理器加载失败），当场的报错卡会说明原因，那颗按钮
可以重试。

---

## 功能一览

| 分类 | 能力 |
| --- | --- |
| 发声 | 物理波导建模（默认）/ Karplus-Strong 对照组，一键切换 A/B |
| 定弦 | **21 弦 · D 调五声**，凡四个八度 D2–D6；D / G / C / F / A 五种调式依实法移柱转调 |
| 演奏 | 触屏拨弦、横向刮奏、按弦区揉弦与滑音、花指、琶音、撮弦、泛音、摇指、键盘演奏 |
| 调音 | 自动调音（开机静默测量机型差异并逐弦补偿）、调音台逐弦校音/微调、基准音高、手工整度 |
| 录音 | 自动录制（拨弦即录、静音自动收尾）、手动录制、暂停续录、页内回放、导出 `webm` / `WAV` |
| 音色 | 12 个滑杆 + 4 个开关，全部对应可推导的物理量（见「面板参数」） |
| 分享 | 配置短码（`GZ1.…`）导出/导入，只包含你改动过的项；一键恢复出厂 |
| 移动端 | 视觉视口补偿（规避国产浏览器原生广告栏遮挡）、横屏沉浸模式、深夜音量一拉即轻 |
| 依赖 | **无**。无 npm、无打包、无 CDN、无字体/图标外部引用 |

---

## 演奏方式

### 触屏

| 手势 | 效果 |
| --- | --- |
| 点 **演奏区**（雁柱右侧） | 拨弦。落点越靠近岳山音色越亮，靠近雁柱越浑厚 |
| 演奏区**横向拖动** | 刮奏；纵向划过琴面则连续拨响经过的弦 |
| 点 **按弦区**（雁柱左侧） | 按弦，压得越深音越高（上限由「按弦上限」定） |
| 按弦区**上下拖动** | 滑音；快速抖动即揉弦 |
| **双击**某弦 | 摇指（持续数秒后自然收束） |

### 键盘

```
低音区  Z X C V B N M , . /      （第 21 → 12 弦）
高音区  Q W E R T Y U I O P ;    （第 11 → 1 弦）
Shift + 键   加强力度
空格         止息（全部按弦止音）
Esc          逐层退出：先收「精调参数」折叠，再关抽屉
```

### 底部工具条

一条栏装两套东西，点最左的 **♪ / 🎙** 切换：

- **播放模式** ♪：`▶/❚❚` 播放与停止 · 进度条可拖动定位 · `▼` 存录音 · `▷` 回放刚录的那段
- **录制模式** 🎙：`●/■` 手动起录与终止 · 显示已录时长 · 同两条录音键

---

## 软件架构

### 目录结构

```
guzheng/
├── index.html                 入口：UA/环境分流 → main.html（无 JS 时显示部署说明）
├── main.html                  琴页本体：全部 DOM + 按序加载脚本
├── css/
│   └── guzheng.css            全部样式（视口锁布局、抽屉、工具条、滑杆、深色主题）
└── js/
    ├── engine/
    │   ├── registry.js        引擎注册表：loadEngine() → Blob URL；下拉填充
    │   ├── physics.worklet.js 主引擎：分谐波波导 + 双偏振 + 面板模态 + 缠层金属嗡鸣
    │   ├── ks.worklet.js      对照组：Karplus-Strong 经典波导（故意做素）
    │   └── measured.worklet.js 实测引擎：模态加法合成，逐谐波查表（由 21 弦实录反解）
    ├── core.js                乐器定义 · 状态 P · 音频初始化 · 输出链 · 演奏动作
    ├── ui/
    │   ├── canvas.js          几何 layout() · 视觉视口探测 · 琴面绘制（含雁柱/弦序/唱名）
    │   ├── control.js         滑杆与开关绑定 · 调音台 · 引擎切换 · 配置导入导出
    │   ├── autotune.js        自动调音：离线渲染 + 相位差测频 + 逐弦补偿
    │   └── rec.js             自动/手动录制 · 分段暂停续录 · 回放 · webm/WAV 导出
    ├── score/
    │   ├── player.js          演奏框架：事件表 · 进度条 · 曲目表 · 名曲通用构件
    │   └── pieces/            八首曲子的谱面数据与编排（一音一文件）
    └── app.js                 启动流程 · 抽屉 · 面板 · 视口兜底轮询 · 渲染循环
```

### 加载顺序（有硬依赖，不要调换）

```html
registry.js                       ← 必须先于 core.js：initAudio 会调用 loadEngine()
core.js                           ← 乐器定义 / 状态 / 音频链 / pluck 等动作
ui/canvas.js                      ← layout() 与绘制
ui/control.js                     ← 绑定滑杆（加载瞬间即执行 bindRange）
ui/autotune.js                    ← 自动调音
ui/rec.js                         ← 声明 MODE，必须早于 player.js
score/player.js                   ← tpToggle 会在点击时读 MODE
score/pieces/*.js                 ← 各曲编排
app.js                            ← 最后：启动渲染循环，读取全部构件
```

### 全局脚本模式（关键约定）

所有 JS **不是 ES Module**，而是按 `<script src>` 顺序共享同一全局作用域。
这是刻意的取舍：worklet 侧的 `Blob` 加载拿不到相对路径基准。

因此有两条必须遵守的纪律：

1. 顶层一律用 `var` / `function`，**不要用 `const` / `let`**
   —— 后者是块级作用域，跨文件不可见。
2. **不要用 IIFE 包裹任何文件** —— 会切断与其它片段的联系。

### 数据流

```
用户手势 ──► control.js / canvas.js 命中判定 ──► pluck(i, opt)
                                                   │
                                       postMessage ─┘
                                                   ▼
                                        AudioWorklet（物理引擎）
                                                   │
   弦 ──► 音色滤波 ──► ┬─► 干声 ──────────────┐
                       └─► 混响(Convolver) ──┤
                                             ▼
                          压缩 ──► 主音量 ──► 深夜音量 ──┬─► 扬声器
                                                          └─► 录制取样点
```

- **深夜音量是独立第二级**，串在总音量之后：拉到 0.1 只是临时压小声，
  不动「总音量」这个音色设定值，白天拉回来分毫不变。
- **录音取样点挂在深夜音量之后且为旁路**：听到什么就录什么，但深夜音量拉到 0
  时录音仍拿到正常电平 —— 录音不该被监听音量绑架。
- 电平监视（AnalyserNode）与录制取样点同源，因此「判据」与「录到的内容」一致。

### 演奏调度

每首曲子先**离线排成一张事件表** `A = [{t, fn, label}]`，再一次性投放成定时器。
好处是定位变得干净：拖动进度条时清掉未触发的定时器、止息全部弦，只把
`t ≥ 目标时刻` 的事件按 `t − 目标` 重新投放 —— **从任意位置起奏，后面听到的
与整曲播放逐音一致**。「即兴」也先随机定表再投放，所以同样是"这一首"，可定位、可重听。

---

## 物理模型要点

以下每一项都是可推导或实测标定的量，不是"调出来的参数"。

**弦参数（21 弦）**

- 定弦 D 调五声，MIDI 38 起（D2）至 D6，四八度；`DEG = 1 2 3 5 6`
- 雁柱有效弦长 0.88 m → 0.13 m 等比递减
- 弦刚度 `B = π²·E·d² / (64·ρ·L⁴·f₀²)`，低音缠弦取芯线 0.36 mm、高音裸钢丝 0.24 mm；
  B 越大高次泛音偏高越多 —— 这正是钢弦"金属味"的来源
- 线密度含缠层（×2.6），而抗弯刚度只来自芯线 —— 这是缠弦能用细芯线换来低非谐性的原因

**数字波导环路**

- 延迟线 = 弦的往返周期；环路内串一阶全通（分数延迟精确定音 + 弦频散）、
  一阶 FIR 低通（频率相关损耗）、环路增益 `g`（决定 T60）
- 环路相位延迟逐弦解析求解，**基频误差 < 0.11 音分**
- 内耗常数 `C = 2.0e-5`（dB/s/Hz²），附加衰减率 `α(F) = C·F²`；
  标定依据：吉他高 E 弦基音 T60≈4 s、4 号谐音（1320 Hz）T60≈1.25 s 反解

**双偏振与琴体**

- 第二偏振（平行面板）与主偏振相差约 1.4 音分、衰减快 0.42 倍 ⇒ 双段衰减与拍音
- 桐木面板模态组：`面板共鸣` 管强度、`木板回音` 管尾长（0.06 s 为"共鸣有、回声没有"的分界）
- 弦间耦合默认 **0** —— 真琴会同情共振，但用户明确要求"弦与弦之间不能互相影响"，
  滑块保留方便自行加一点点

**张力与非线性**

- `P.tension` 在物理上等价于换一套线密度更大的弦：`T = μ(2Lf)² ∝ k`，
  派生 ①面板可显示牛顿数 ②非谐性 `B ∝ 1/k` ③起音漂移 `∝ 1/k` ④缠层内耗 `∝ 1/k`
  —— 拉紧即"高次谐音回到整数倍、起音不再上冲、音色更亮更实"
- 起音音高漂移：拨弦把弦拉长 `ΔL/L = π²a²/8L²`，`Δf/f = ½·ΔT/T`，故漂移 ∝ 力度²；
  实测重拨偏高可达 3.5 音分 —— 这是演奏表情，**刻意不补偿**

**低音余韵**

- 行业检测标准要求基准弦（第 21 弦）衰减时长 1.8–2.5 s，出厂按区间上沿标定
  （低音 2.4 s → 高音 3.4 s）；推子 `低音余韵` 整体缩放，供对比听
- 真琴低音是缠弦，缠层间微滑移是强内耗通道，且辐射效率高 ⇒ 低音衰减并不比高音慢

**缠层金属嗡鸣**

- 低音缠弦的"钢绳味"来自缠丝间接触刚度与层间微滑移，共振带约 850–1180 Hz，
  **与弦长无关**（按弱幂次 0.3 微调），只作用于最低九根缠弦
- 4 个无理步长散开的谐振峰，避免 21 弦在 850 Hz 齐声叠出啸叫

**激励**

- `触弦刃感` 是激励波形的**分数阶微分阶数 α**：`α=0` 位移型三角波（∝1/n²，温厚），
  `α=1` 速度型（∝1/n，尖锐），中间连续过渡，且零点梳始终不变
  —— 于是"音色在变而空心位置不动"，拧一下能听出方向

---

## 三台引擎

它们不是"同一件事的三种精度"，而是**三种不同的建模范式**。切换面板上的
「算法」下拉即可 A/B，参数原样平移（不做换算，见下）。

| 引擎 | 范式 | 音高/阻尼由什么决定 | 有声学琴体 | 特点 |
| --- | --- | --- | --- | --- |
| `physics` | 时域**波导递归** | 延迟线长度 + 环路滤波器的相位与幅频 | 有（15 只面板模态） | 分谐波波导 + 双偏振 + 缠层金属谐振；音高逐弦解析求解，误差 < 0.11 音分 |
| `ks` | 时域**波导递归**（极简） | 延迟线 + 一阶低通 | 无 | 1983 年原始算法，故意做素，作对照组 |
| `measured`（默认） | **模态加法合成** | 逐谐波**查表**（频率、幅度、衰减率） | 无（纯弦模型） | 参数由 21 弦真实录音反解；各次谐波**独立衰减** |

> **默认引擎是 `measured`**（v0.21 起）：它的逐弦参数由真实录音反解，
> 声音最贴近实录。代价是**没有箱体共鸣**（纯弦模型），想要"木箱在响"的
> 厚度就切到 `physics`。
>
> ★ 代码里「默认引擎」与「兜底引擎」是**两个不同的常量**，别混：
> `window.ENGINE` 是出厂默认（`measured`），
> `window.ENGINE_FALLBACK` 是"引擎名不认识时回落到哪"（`physics`）。
> 兜底跟着默认一起改的话，"导入了一个错别字引擎名"就会变成静默换引擎，
> 而不是回落到最保守的那个。

### 为什么值得有第三台：波导做不到"逐谐波独立衰减"

波导（含 KS）的环路里串的滤波器**同时决定所有谐波的阻尼** —— 想让 h1 长鸣
而 h4 飞快消失，只能靠"内耗补偿"这类技巧去近似。但真实录音告诉我们，
各次谐波的衰减率是彼此独立的：

```
弦 15 (E3)    实测衰减率
  h1  −30 dB/s        ← 长鸣，这就是"余韵"
  h4  −64 dB/s        ← 两倍多，1.1 秒内多掉约 37 dB
```

模态加法合成能**精确**做到这一点 —— 每个谐波一个二阶谐振器、各自一个衰减率。
这就是它存在的理由，而不只是"换一种写法"。

### `measured` 引擎的数据来源

由两段录音（由低音到高音依次拨奏 21 弦）反解，每弦测出三组量：

1. **前 10 次谐波的相对幅度** —— 低音弦 h1 极弱（弦 21 的 h1 比 h5 低 45 dB），
   能量集中在 3~5 次谐波，这是"低音听不出明确音高"的物理来源
2. **各次谐波的衰减率（dB/s）**，全部为负
3. **各次谐波相对整数倍频的偏离（音分）** —— 实测随音高**单调地从负变正**：

```
弦 21 ( 73 Hz)  −21 ~ −11 音分    低音弦谐波【偏低】
弦  6 (582 Hz)   −5 ~  +3 音分    过零点
弦  1 (1175 Hz)  +1 ~  +8 音分    高音弦谐波【偏高】
```

> 低音偏低**不是**弦刚度造成的（那会让谐波偏高），而是**缠弦的质量负载** ——
> 缠层让高次谐波的有效质量增大、频率被拖低。这是缠弦特有的效应，
> 单根裸弦不会这样，所以这张表必须**逐弦存**，不能用一个统一次谐性公式拟合。

### 各引擎的 `刃感` 不是同一回事

同一个旋钮在三个引擎里含义不同，所以 UI 读数千位**按引擎分别给**
（`registry.js` 的 `edgeReadout` / `edgeHint`），共用一个写法就是误导：

| 引擎 | 含义 |
| --- | --- |
| `physics` | 激励的分数阶微分阶数 α |
| `ks` | 激励的软化程度（低通次数） |
| `measured` | 高次谐波的额外衰减斜率 |

### 余韵均衡（`余韵均衡` 旋钮）

实测录音里各弦的余音长短差得很开 —— 用 −30 dB 判据实测：

```
bal = 0   （实测原样）  21弦 1.85s  ...  1弦 0.57s    极差 3.2×
bal = 1.0 （完全拉平）  21弦 0.61s  ...  1弦 0.77s    极差 1.6×
```

而且不只是"低音长、高音短"这么简单 —— **相邻弦之间也会跳变**，
听感上像"某几根弦自己拖尾"。这个旋钮就是在弦之间搬运余韵：
往右削弱差异，往左保留录音原貌。它与「余韵 T60」是两个独立维度：

| 旋钮 | 作用 |
| --- | --- |
| 余韵 T60 | 整台琴一起变长/变短（对 `t60Of` 整体缩放） |
| 余韵均衡 | 只在弦与弦之间搬运，总时长基本不变 |

> ★ 均衡系数 `BAL_K` 是**常数乘在每个谐波上**，所以只改"整体快慢"，
> 不改谐波之间的相对斜率 —— "高次谐波衰减远快于低次"这个音色特征完整保留。

### 未拨弦时应当完全无声

`measured` 引擎里有**两个必须留意的实现细节**，都是同一类陷阱
（"本该关掉/本该正常的东西变成一个极慢的谐振器"）：

1. **「关闭某一号谐波」不能靠"给一个很大的负 dB/s"去近似** ——
   `10^(−10000/(20·48000)) ≈ 0.976`，那仍是个**几乎不衰减的谐振器**，
   会持续振铃、制造出不该存在的分音。必须走"把系数直接置 0 并清状态"
   这条显式路径（见 `Partial.set` 的注释）。
2. **`DECAY` 表的列数必须等于 `NH`**。实测只测到前 8 次谐波，所以这张表
   最初只有 8 列，而 `HARM` 有 10 列 —— `dec[8]`/`dec[9]` 取到 `undefined`，
   参与乘除得到 `NaN`，而 `Partial.set` 里的 `if (!(r < 1))` 会把 `NaN`
   兜成 `r = 0.999999`（**τ ≈ 48 秒**）。后果是 42 个谐振器以错误系数
   长期振铃 —— 不报错、输出也不 NaN，极难定位。
   现在表已补齐 10 列，并且 `recalc` 里留了 `|| -30` 的显式兜底：
   最坏情况是"这一号谐波衰减中规中矩"，而不是变成一个失控的谐振器。

---

## 面板参数

滑杆的**出厂值只在 `main.html` 的 `value="…"` 属性里定义一次**，
`js/core.js` 的 `P` 字面量注释与之互相约束。面板会按当前引擎声明支持哪些参数，
自动收起用不到的旋钮（如 KS 与 measured 都没有琴体，就不显示「面板共鸣」；
KS 没有缠层金属层，也不显示「金属嗡鸣」）。

### 音色

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| 义甲硬度 | 0.55 | 义甲 vs 指腹：激励宽度与环路损耗曲线陡度，管"这根弦多亮" |
| 拨弦位置 | 0.10 | 靠近岳山明亮犀利，靠近雁柱浑厚 |
| 触弦刃感 | 0.50 | 激励的分数阶微分阶数 α，管"拨得多刃" |
| 低音余韵 | ×1.00 | 低音弦 T60 整体缩放（0.3×–3×） |
| 金属嗡鸣 | 35% | 最低九根缠弦的钢绳味，裸弦不受影响 |
| 余韵 T60 | ×1.00 | 全琴衰减倍率 |
| 高频衰减 | 0.28 | `rho`，泛音相对基音掉得多快 |
| 力度 | 72% | 默认落键力度 |
| 琴弦张力 | ×3.00 | 等价于换一套更紧的弦（低音吃满、高音吃三成半） |
| 开关 | — | `义甲` / `指腹`、`泛音`、`摇指` |

### 琴体与空间

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| 面板共鸣 | 0.62 | 箱体共鸣**多大**（强度） |
| 木板回音 | 0.06 s | 箱体共鸣**拖多长**（尾长）；上限 0.12 s 是 76 Hz 面板模态自身 Q 给出的物理边界 |
| 弦间耦合 | 0 | 同情共振强度（默认关，见上文） |
| 厅堂混响 | 30% | 干湿比：混响**给多大** |
| 混响长度 | 2.6 s | IR 时长：混响**有多长**（0.3 s 近距拾音 → 3 s 大厅） |
| 总音量 | 78% | 音色设定的一部分 |
| 揉弦深度 | 0.22 | 自动揉弦与乐句揉弦的深度 |

### 定调与演奏 / 调音台

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| 调式 | D | D / G / C / F / A，依实法移柱：G 升 mi，C 升 mi·la，F 升 re·mi·la，A 降 do |
| 滑音速度 | 13 | 半音/秒，按音提前量由它推出 |
| 按弦上限 | 3.0 半音 | 按弦区压到底的升高量 |
| 基准音高 | 0 ¢ | 全琴 A4 偏移 |
| 手工整度 | 1.0 ¢ | 0 = 电子校音器般分毫不差，越大越像老师傅手调 |
| 逐弦校音 / 复位微调 | — | 浏览器内离线渲染 21 弦、相位差测频复核（约 20 s，真测） |

### 自动调音

数字波导的实际发声频率取决于逐弦解出的环路延迟，不同机型/采样率/浮点路径
会有细微差别。开机后**静默**跑一次闭环自校：

1. 逐弦在 `OfflineAudioContext` 里单独轻拨
2. 取 0.40 s 起的稳态段，用**双窗相位差**解基频
   （0.05% 步长 DTFT 粗扫 → 相邻两窗相位差迭代 6 次）—— 精度不受 FFT bin 宽限制，
   最低弦 73 Hz 也能测到 0.1 音分量级
3. 把 `-偏差` 写进该弦补偿（`AUTOC`），并**重新实测**残差

为什么不测起音那一瞬：弦被拨响时张力升高、音会偏高，那是演奏表情，调掉反而失真。
全程不需要麦克风权限，也不影响你弹奏。

> ⚠ 不要改用"FFT 取峰 + 抛物线插值"：44.1 kHz 下 8192 点 FFT 的 bin 宽 5.38 Hz，
> 对 73.4 Hz 的最低弦相当于 122 音分，会把琴越调越歪。

### 自动录制

| 参数 | 默认 | 说明 |
| --- | --- | --- |
| 自动录制 | 关 | 拨响即录、静音自动收尾 |
| 静音判定 | 3.0 s | 连续静音多久算"弹完了" |
| 起录阈值 | −40 dBFS | 调低更灵敏，调高只录大声（避免环境噪声误触发） |

- 用**输出电平**（AnalyserNode）判断"你在弹"，而不是挂 `pluck()` 事件 ——
  刮奏/摇指一次手势响很多声、键盘与按弦区各走不同入口，只有电平判据能全覆盖。
- 起录前必须先**亲眼见到一次安静**（约 420 ms）才允许越阈，
  以免开机迎客琶音的余韵被当成"他在弹"。
- **暂停 = 把这一段先收尾存好**（而非 `MediaRecorder.pause()`），
  于是暂停期间可以立刻回放完整内容；继续录则接成新的一段，导出时首尾相接。
- `WAV` 是**下载时才转**（`decodeAudioData` → 16 bit PCM）：
  不转录制的实时路径，不常驻内存；微信等不认 `webm` 的地方也能直接打开。
  注意"改成录 `audio/mp4`"会让问题更严重 —— 本机 Chromium 返回的其实是 MP4+Opus。

---

## 曲目

| # | 曲名 | 说明 |
| --- | --- | --- |
| 1 | 《高山流水》 | 浙江筝曲，据《老六板》八板体主题与王巽之传谱技法编配（1=D，2/4） |
| 2 | 《渔舟唱晚》 | 娄树华据古曲《归去来辞》改编（1=D，4/4） |
| 3 | 《出水莲》 | 客家软线六十八板，罗九香传谱（1=G，4/4），4 与 ♭7 由 3、6 重按出 |
| 4 | 《寒鸦戏水》 | 潮州重六调六十八板（1=G，头板—拷拍—三板） |
| 5 | 《梅花三弄》 | 古曲古筝改编本（1=D），三弄以泛音、实音、中音区三次呈示 |
| 6 | 《茉莉花》 | 江苏民歌，五声短曲 |
| 7 | 《流水》 | 原创古筝小品，集中展示琶音、花指、滑音、摇指、泛音 |
| 8 | 《即兴》 | 五声音阶随机游走 + 古筝语汇，随机定表故可定位、可重听 |

各调旋转量由 `KEYS.off` 推出（D0 / G2 / C4 / F1 / A3）；定弦里没有的 4 与 ♭7
由 3、6 重按升高半音得到 —— 客家「软线」与潮州「重六」的色彩正在这两个音上，
必须**左手先按到位再弹**（按音），不是弹完再滑上去。

> 诸曲旋律依公开谱例与教材谱面转录编配，指法与加花为演奏化处理，非某一录音的复刻。

---

## 二次开发

### 新增一首曲子

1. 在 `js/score/pieces/` 下新建 `<id>.js`，照抄任意现有文件的头结构与
   「新增步骤」注释：

   ```js
   var XX_DATA = [['1', 1], ['3', 0.5] /* 五声唱名 + 时值(拍) */];
   function demoXx() {
     stopAll();
     const A = [];
     ev(A, 0, null, '《曲名》· 起');          // 段落标记
     addSeq(A, 0, 400, XX_DATA, { key: 'D' });
     runSeq(A, '《曲名》', 800);              // 第三参 = 尾韵留白(ms)
   }
   ```

2. 在 `main.html` 里加一行 `<script src="js/score/pieces/<id>.js"></script>`
3. 在 `js/score/player.js` 的 `PIECES` 表里加一行 `{ id, nm: '曲名', fn: demoXx }`

`PIECES` 是曲目列表、时长回填、播放高亮的**唯一数据源**：新增后中段列表与
底部进度条的时长会自动同步。

> ⚠ 曲目列表的时长是在该曲首次弹响时由 `runSeq` 回填的（与进度条同源），
> 不另外维护一份副本。

### 新增一台引擎（换/加算法）

只改 `js/engine/registry.js` 这一张表：

```js
window.ENGINES.myAlgo = {
  label: '我的算法',
  hint: '一句话说明',
  processorName: 'myalgo',        // ⚠ 必须唯一，同名 registerProcessor 会抛错
  src: 'js/engine/myalgo.worklet.js',
  edgeReadout: v => v.toFixed(2),
  edgeHint: '刃感的含义（按本引擎的物理含义写）',
  params: [/* 本引擎认的参数 key，不在表内的滑杆会自动收起 */],
  ignore: [/* 认但用不到的参数，列出来便于测试区分 */]
};
```

下拉框 (`#selEngine`) 由注册表同源填充，新增一项即自动多一个选项。
切换语义是**停音 → 重建 node → 原样重放参数**：参数不重置，
这样 A/B 对比才是公平的（两个算法 + 两组参数同时变就什么都说明不了）。
`AudioWorkletNode` 的构造来源变了，**物理上不可能无缝热替换**，正在响的弦必然被切断。

新引擎的处理器源码应当**沿用同一套报文协议**（`pluck` / `param` / `freq` /
`body` / `gain` / `bend` / `vib` / `damp` / `all` / `slide`），
用不到的字段静默忽略、绝不报错。

### 引擎报文协议（minimal 子集）

```js
{ type: 'pluck', s, p, v, sharp, noise, harm, dir, edge, t, bend, vib }
{ type: 'param', i, t60, rho, metal }
{ type: 'freq',  s, f, b, g, c, k, cents }
{ type: 'body',  mix, couple, echo }
{ type: 'gain',  g }
{ type: 'bend',  s, bend, press }   { type: 'release', s }
{ type: 'vib',   s, d, r }
{ type: 'damp',  s, k }             { type: 'slide', r }
{ type: 'all' }
```

### 调试钩子

| 符号 | 用途 |
| --- | --- |
| `window.ENGINE` / `window.ENGINES` | 当前引擎名 / 注册表 |
| `window.engineFor(name)` | 取引擎描述（未知名字回落 physics，绝不返回 undefined） |
| `window.loadEngine(name)` | 取该引擎的 Blob URL（按引擎名缓存，不 revoke） |
| `window.__loadWorklet(name)` | 源码获取的**唯一出口**，可被测试替换以穿透整条加载链路 |
| `window.__workletSource` | **当前**引擎的源码文本 |
| `window.fillEngineSelect()` | 把注册表填进 `#selEngine` |
| `window.AUTOTUNE` | 自动调音状态（`state` / `before` / `after` / `sig` …） |
| `window.P` / `window.N` / `window.GEO` | 运行参数 / 弦数（21）/ 画布几何 |

`P` 里的值与 `main.html` 的 `value="…"` 出厂值必须保持一致，多处注释写明了
这条纪律；配置导入 / 恢复出厂都走 `setParam()` 这一条通道（它会 `dispatchEvent`
一次 `input`），不新增第二条改参数的路径。

### 配置短码

```
GZ1.bright=0.62,pos=0.14,eng=ks,nail=0
```

- 前缀 `GZ1` 是版本标记，将来改名/删参数时导入端能明确拒绝而不是静默乱套
- **只写与出厂值不同的项** —— 一份长码 = 一次大改动，一眼可见
- 导入时按滑杆 `range` 夹取，超范围值进不来；不认识的键会回报告知
- 引擎本身也进短码，否则收到配置的人用着另一个算法，听到的音色完全不是一回事

---

## 已知约束与取舍

1. **必须经 HTTP(S) 打开**。AudioWorklet 源码走 `fetch` 取回，`file://` 会被
   浏览器安全策略拦掉。报错卡会区分"本地双击"与"经 HTTP 打开"两种情况给出对应提示。
2. **全局脚本模式**，不是 ESM。worklet 侧的 `Blob` 加载拿不到相对路径基准，
   引入 ESM 需要整个项目改造 —— 维持现状是既定取舍。
3. **切换算法不可能无缝**。`AudioWorkletNode` 的构造来源变了，只能销毁重建，
   正在响的弦会被切断；面板文案已明说这一点，不假装热替换。
4. **移动端要补偿原生 UI**。国产手机浏览器（vivo/OPPO/华为/UC/QQ）会在页面上方
   推出**原生广告栏**：它是浏览器自己画的 UI，不在 DOM 里，只压缩 `visualViewport`
   而不动布局视口，任何 DOM 查询都看不见它。所以只能从 `visualViewport` 读，
   并对 `resize` + `scroll` + 1 s 兜底轮询三重覆盖（实测存在"广告栏出来了、
   事件一个都不发"的情况）。取布局视口与视觉视口的**小值**，并挡住 `NaN`
   （`NaN` 传进 `createLinearGradient` 会让整台琴画不出来）。
5. **录音格式默认 `webm`/opus**，微信等场景请用「⤓ 存 WAV」（体积约为 opus 的 10 倍）。
   浏览器不能录 MP3；转码需引入编码器，与"零外部依赖的单包部署"冲突。
6. **录制的暂停是"分段"而非 `MediaRecorder.pause()`**：后者会让暂停期间无法回放
   *完整* 内容，而"暂停是为了先听一遍"正是用户的目的。代价是要维护分段账本。
7. **内嵌百度统计**（`hm.baidu.com`）。它异步插一个 `<script>`、不往 `body` 插可见元素，
   因此不撑高文档、不引发滚动条；被拦截时页面照常工作，它只是旁观者。
8. **各处默认值有联动**：`js/core.js` 的 `P` 字面量、`main.html` 的 `value` 属性、
   `registry.js` 的 `params` 表三者需一致；改一处请连带检查其余两处。

---

## 参与贡献

1. Fork 本仓库
2. 新建 `Feat_xxx` 分支
3. 提交代码
4. 新建 Pull Request

改动物理模型或参数默认值时，请在提交信息里说明**依据**（推导 / 实测数据），
本项目的注释密度就是为了让下一个人能验证这个依据，而不是重新猜一遍。