也可以去github上看看源码的实现
3.3 演奏设置 1
① 加减 Key
类型：整数，范围 -100 ~ 100。

默认值：0（不移调）。

作用：在压缩之前对整个乐曲所有音符统一升降半音。

例子：Key = +2 时，原曲的 C（60）会变成 D（62），整体提高一个全音。移调后再进行压缩处理，可以改变乐曲最终落在游戏键盘上的位置和色彩。

3.4 演奏设置 2

② 映射反转
游戏内钢琴按键排列有三八度区域，可进行视觉或手感上的反转：

选项	作用
水平反转	每个八度内部按键左右镜像（原来的从左到右低→高，变成高→低）。
垂直反转	低音区与高音区互换，中音区保持不变。
两者同时勾选则为全反转（水平+垂直同时生效）。


4. 压缩方式详解（重要）

推荐：
若不确定，使用 ①最大覆盖中心八度直接裁剪 或 ②最大覆盖中心八度音名保留  或 ③最大覆盖中心 Key 音名保留，通常效果最佳，
也可以同时调节 加减 Key 参数，配合压缩方式微调最终落音位置。


游戏可演奏的音符固定为 36 ~ 71（三个八度，C2 ~ B4）。
多数钢琴曲音域远超此范围，必须进行智能移调+压缩。
以下以内置测试曲目 《Ave mujica》Imprisoned XII（Piano）.mid 为例说明各种方式的效果，该曲原始音域为 29 ~ 96（超出目标区间）。

假设示例原始音符包含：29, 36, 48, 60, 72, 84, 96 等。

4.1 整体加减 Key 音名关系保留
原理：计算原曲音域，尝试平移 12 的倍数（八度）使整体落入 36~71；若无法完美装入，则使用中心对齐的半音移调，然后低音区统一上翻八度，高音区统一下翻八度，保持组内相对音高关系（和声）。

示例：原曲 29~96（中心 62.5）。目标中心 53.5。

先用中心对齐偏移 base = round(53.5-62.5)= -9。所有音符减 9 半音：29→20, 36→27, 48→39, 60→51, 72→63, 84→75, 96→87。

低于 36 的统一加 12 的倍数：20+12=32（仍<36）→ 44；27→39。

高于 71 的统一减 12 的倍数：75→63, 87→75（仍>71）→ 63。
最终映射：29→44, 36→39, 48→39, 60→51, 72→63, 84→63, 96→63。
特点：保留了低音组与高音组内部的音程关系，适合和声强调的慢板段落。

4.2 整体加减 Key 直接裁剪
原理：与上相同进行半音移调，但越界音符逐个循环八度折叠（低音不断 +12，高音不断 -12），直到落入区间，不保留组内统一八度。

示例（沿用 base=-9）：20 → +12→32→44；27→39；75 → -12→63；87 → -12→75→63；96→87→75→63。
结果可能和 4.1 类似，但在某些复杂分布下会打破组间统一性。

4.3 整体加减八度音名关系保留
原理：只允许按完整八度（±12 的倍数）移动整体，无法进行半音移调。选择最接近目标中心的八度倍数平移，然后低/高越界部分统一八度调整。

示例：原曲中心 62.5，目标中心 53.5，最接近的八度偏移为 round((53.5-62.5)/12)= -1 八度（即 -12）。
平移到：17, 24, 36, 48, 60, 72, 84。
过低者（17,24）统一 +12（2 个八度）：17+24=41, 24+24=48；72 已 ≤71 保留；84 → -12→72（或再减变成 60）。最终可能 29→41, 36→48, 48→48, 60→48, 72→72, 84→72, 96→84? 84 仍 >71→72，所以 84→72, 96→84→72。
特点：严格保持原调性（不改变乐谱上的调号），适合追求原调演奏。

4.4 整体加减八度直接裁剪
原理：整体八度平移后，越界音逐个八度折叠（直接裁剪），不强制组内统一。

示例：与 4.3 步骤类似，但低音自行升八度到范围内，高音降八度。最终映射可能和 4.3 相近但无强制分组。

4.5 最大覆盖中心 Key 音名保留
原理：在 4.1 基础上，不简单使用原始音域中心，而是寻找能覆盖最多音符的 35 半音宽度窗口，取其中心作为对齐点，再进行 Key 移调和分组保留。
这可以把“音符密集区域”尽量放置在游戏键盘的舒适区，避免因边缘离群音符而使整体偏移过大。

4.6 最大覆盖中心 Key 直接裁剪
原理：最大覆盖中心 + Key 移调 + 直接裁剪，无分组保留。

4.7 最大覆盖中心八度音名保留
原理：最大覆盖中心 + 仅八度平移 + 分组保留。同样为保留原调性优化。

4.8 最大覆盖中心八度直接裁剪
原理：最大覆盖中心 + 八度平移 + 直接裁剪。

4.9 直接裁剪
原理：不以乐曲中心对齐，直接以 C4（60）为分界：

音符 ≥ 60 → 反复减 12 直到 ≤71；

音符 < 60 → 反复加 12 直到 ≥36。

示例：29 → +12→41；36 → +12→48；48→60；60→60；72→60；84→72→60；96→84→72→60。
结果：29→41, 36→48, 48→60, 60→60, 72→60, 84→60, 96→60。
许多高音会堆叠在 60 附近，丢失大量旋律信息。

5. 压缩方式总结与选择建议
分类	方法	保留调性	保留和声关系	适用场景
Key 移调 + 关系保留	4.1, 4.5	否（可改变半音）	是（分组保持）	重和声、分解和弦
Key 移调 + 直接裁剪	4.2, 4.6	否	否	快节奏单音旋律
八度移调 + 关系保留	4.3, 4.7	是	是	作者希望忠于原调
八度移调 + 直接裁剪	4.4, 4.8	是	否	忠实原调且不 care 分组
简单直接裁剪	4.9	否	否	极简处理，可能损失大







