YSFCforge/ysfc-forge

# YSFC Forge **基于浏览器的开源工具，专为 Yamaha MODX M / ESP Plugin / Montage M 演出文件设计** 逆向工程工具，适用于 Yamaha MODX M / ESP Plugin / Montage M 演出文件。 **完全通过对 Yamaha 未公开文件格式的二进制分析从零开始构建。** 在任何现代浏览器中打开 HTML 文件。直接在浏览器中拖放、合并、编辑并导出 `.Y2L` / `.Y2U` 文件。 无需安装。 无需上传至云端。 一切均在您的计算机本地运行。 ## 什么是 YSFC Forge？ YSFC Forge 是一个开源生态系统，用于探索、编辑和转换 Yamaha MODX M / ESP Plugin / Montage M 演出文件。 该项目结合了： - 音色库管理工作流 - 演出编辑 - 二进制逆向工程 - 跨合成器转换 - 参数映射 - 基于浏览器的工具集 - 优先离线的工作流 - 技术文档与归档 YSFC Forge 完全通过对 Yamaha 未公开文件格式的二进制分析从零开始构建。 ## 为什么会有这个项目 Yamaha MODX M / ESP Plugin / Montage M 文件格式在很大程度上是未公开的。 创建 YSFC Forge 的目的是为了： - 理解内部的二进制结构 - 构建现代的基于浏览器的工具集 - 简化演出管理 - 探索跨合成器转换的工作流 - 创建 Yamaha 从未发布过的工具 - 让高级编辑能够在离线状态下进行 ## 🎛 工具集 🎛 核心工具 | 工具 | 文件 | 功能说明 | |------|------|-------------| | **Forge Librarian** | `tools/ysfc_forge_v1.19.html` | 将多个 Y2L/Y2U 文件中的演出合并为一个文件并导出 | | **Performance Editor** | `tools/ysfc_performance_editor_v3.html` | 直接在浏览器中编辑 FM-X、AWM2 和 AN-X 参数 | 🔄 转换器 | 工具 | 文件 | 功能说明 | |---------|-----|-------------| | **DIVA Patch Translator** | `translators/ysfc_diva_h2p_converter_v2_15.html` | 分析 DIVA 音色并将其转换为 Y2L/Y2U 文件，随后加载到 Yamaha MODX M / ESP Plugin / Montage M 中 | | **Vital Patch Translator** | `translators/ysfc_vital_converter_v4_12.html` | 分析 Vital 音色并将其转换为 Y2L/Y2U 文件，随后加载到 Yamaha MODX M / ESP Plugin / Montage M 中 | | **Synth1 Patch Translator** | `translators/ysfc_synth1_converter_v5_12.html` | 分析 Synth1 音色并将其转换为 Y2L/Y2U 文件，随后加载到 Yamaha MODX M / ESP Plugin / Montage M 中 | 🧰 实用工具 | 工具 | 文件 | 功能说明 | |---------|-----|-------------| | **ESP Librarian** | `utilities/ysfc_esp_librarian_v7.html` | 独立原型音色库管理器，用于合并演出 | | **Smart Performance Name Compressor** | `utilities/ysfc_smart_name_compressor.html` | 独立原型工具，用于轻松实现 Yamaha MODX M 演出的标准化命名规范 | | **Synth Converter** | `utilities/ysfc_synth_converter.html` | 在不同格式（8种以上）之间转换 DIVA、Vital 和 Synth1 音色 | ## 📸 截图 *Forge Librarian — 拖放 Y2L 文件，选择演出，然后导出*  *Performance Editor — 带有算法图的 FM-X 运算器编辑器*  *ESP Librarian — 带有引擎检测和依赖摘要的演出列表*  *DIVA Patch Translator — 将 DIVA 音色转换为 Y2L/Y2U 文件及其他文件格式（另见 Vital Patch Translator 和 Synth1 Patch Translator）*  ## 🚀 快速开始 ### 从多个文件合并演出 1. 下载 `tools/ysfc_forge_v1.19.html` 2. 在浏览器中打开它 3. 拖放您的 `.Y2L` 或 `.Y2U` 文件 4. 选择所需的演出 5. 点击 **Save as Y2L** 或 **Save as Y2U** 6. 在 MODX M / Montage M 中导入导出的文件 ### 编辑演出 1. 下载 `tools/ysfc_performance_editor_v3.html` 2. 在浏览器中打开它 3. 点击 **Open Y2L** 并选择一个文件 4. 从左侧面板选择一个部分（运算器、滤波器、LFO 等） 5. 使用滑块调整参数 6. 点击 **Export Y2L** 进行保存 # 🔬 逆向工程状态 | 区域 | 覆盖率 | |---|---| | FM-X 运算器 | ~100% | | FM-X PEG | 100% | | FM-X LFO | 100% | | AWM2 | ~95% | | AN-X | ~99% | | Motion Sequencer | 100% | | Arp Common | 100% | | FX Types | 57 个已验证 | | 已映射参数总数 | ~668 | 详细的参数表和二进制文档可在以下文件中找到： `docs/YSFC_FORGE_FULL_CONTEXT_v10.md` # ⚙ 支持的硬件与格式 | | 支持 | |-|---------| | MODX M | ✅ 主要目标 | | ESP plugin | ✅ | | Montage M | 可能兼容 — 尚未全面测试 | | `.Y2L` (Library 文件) | ✅ | | `.Y2U` (User 文件) | ✅ 二进制格式完全一致 — 仅扩展名不同 | | `.X7L` / `.X8L` | ✅ 作为合并源（不能作为导出容器） | ### 引擎 | 引擎 | 音色库管理器 | 音色编辑器 | |--------|-----------|--------------| | FM-X | ✅ | ✅ 全部 8 个运算器、算法、PEG、LFO、滤波器、FM Color | | AWM2 | ✅ | ✅ 元素、滤波器、AEG、波形编号 | | AN-X | ✅ | ✅ OSC、滤波器 1/2、WaveFolder、ModEG | | DRUM | 可检测 | — | # 🧠 技术亮点 - ~668 个已映射参数 - 经过二进制验证的偏移量 - 完整的 Y2L/Y2U 容器文档 - 基于浏览器的序列化工作流 - 逆向工程的 FX 索引表 - 多引擎参数解析 - 优先离线的架构 # 🔒 理念 YSFC Forge 的设计围绕以下几点： - 优先离线的工作流 - 无遥测数据 - 浏览器原生工具 - 开放的逆向工程 - 人类可读的工具 - 仅本地处理 ## 工作原理 YSFC 二进制格式（`.Y2L`, `.Y2U`）**并未被 Yamaha 官方公开记录**。本项目中的每一个参数偏移量都是通过二进制差分分析发现的： 1. 从 MODX M 硬件或 ESP 插件导出一个已知更改了某个参数的测试文件 2. 将其与基线文件逐字节进行比较 3. 记录偏移量、编码方式和取值范围 4. 重复以上步骤 — 进行了 74 轮以上的测试，涵盖了大约 668 个已记录的参数字段 最终成果是 **Serializer v6** — 这是一个经验证的参数映射，覆盖了 FM-X、AWM2 和 AN-X 引擎中大约 99% 的可编辑参数。 ### 主要发现 - `Y2L` 和 `Y2U` 在字节上是完全一致的 — 仅文件扩展名会改变 ESP 显示导入对话框的方式 - 演出名称：字节 `perf[4:20]`，以空字符结尾。字节 `perf[20:24]` 包含波形采样 (waveform samples) 的 flash 地址 — 请勿将此区域填零。请参阅下面的 blob 格式说明 - 场景数量：`perf[6695]`，范围 1–8 - AWM2 滤波器 EG（Attack/Decay/Sustain/Release）**仅存在于 Part 级别**，而不是每个元素都有 - AN-X PitchEGDepth 编码：`raw = round(UI_cent × 247/4800) + 247`，范围 ±4800 音分 - 扩展包检测：如果任何 AWM2 元素中的 `waveformNumber > 256`，则意味着该演出需要合成器上安装了 Y2E 扩展包 ### Blob 格式说明 — 第三方库文件 紧跟在演出名称之后的字节（`blob[null_pos+1:24]`）必须格式正确，MODX 才能在加载文件时不出现“存储读写错误”(Storage read/write error)。具体而言： - `blob[null_pos+1:20]` 必须用零填充 - `blob[20:24]` 必须包含正确的波形 flash 地址（`0x15bcXXXX`），如果没有引用 ROM 采样，则为 `0x00000000` 直接从 Yamaha MODX M / ESP Plugin 导出的文件总是具有正确的值。来自第三方来源的库文件这些字节中可能包含旧的占位符值。Forge Librarian 和 ESP Librarian 都会在导出时应用 `sanitizePerfBlob()` 自动纠正此问题。 ### 参数覆盖范围 下表计算了所有部分中**独立的参数字段**数量。 FM-X OP 字段（每个运算器）仅计算一次 — 相同的 29 个字段在所有 8 个运算器中重复。 AWM2 Element 字段计算为所有 8 个元素的总数。 | 引擎 / 部分 | 字段数 | 备注 | 覆盖率 | |-----------------|--------|-------|----------| | FM-X — OP (每个运算器 × 8) | 29 | Coarse, Fine, Detune, AEG, PEG, Level, Spectral Form… | 100% | | FM-X — Part PEG | 16 | Pitch EG 电平与时间 | 100% | | FM-X — Part LFO 1st | 11 | Wave, Speed, Delay, Fade, KeyOnReset… | 100% | | FM-X — Part LFO 2nd | 8 | Wave, Speed (Normal/Extended), Phase, Delay… | 100% | | FM-X — Part Common | 15 | Algorithm, Feedback, Filter, FM Color, Volume… | 100% | | AWM2 — Element (共 8 个元素) | 150 | Waveform, AEG, Filter, Pan, 各元素的 Vel limits | ~95% | | AWM2 — Part | 26 | Filter EG, AEG Offset, Volume, AT Register… | 100% | | AN-X — Part | ~132 | OSC 1–3, Filter 1–2, WaveFolder, ModEG, EGs… OSC1 100% ★ | ~99% | | Insertion FX | 57 | 57 种已验证的 FX 类型 (THRU → Wave Folder) | 100% | | Controller Assign | 8 | Source, Destination, Curve, Polarity (Part + Perf) | 100% | | Performance Common | 10 | Name, Volume, Pan, Portamento… | 100% | | Scene metadata | 2 | 场景数, 上次活动场景 | 100% | | AfterTouch Register | 2 | Switch, Destination (Pitch / Filter Cutoff) | 100% | | SuperKnob + Assign values | 20 | SuperKnob 值, Assign1-8 值及开关 | 100% | | Assign positioners | 25 | 每个 assign 的 Left/Mid/Right 位置，MidPos enable | 100% | | Arp Common | 34 | Loop, Hold, Unit, NoteLimit, VelLimit, Swing, Octave… | 100% | | Motion Sequencer (4 条轨道) | 116 | LaneSwitch, Speed, Sync, Delay, FadeIn, Pulse A/B… | 100% | | Metadata flags | 4 | ArpMaster, MSMaster, Part seq/arp 状态字段 | 100% | | **总计** | **~668** | | **~99%** | **尚未详细映射的内容：** - 场景参数快照（每个场景存储的参数值） - Smart Morph - FM-X 第二 LFO 深度矩阵 (`abs=12547+`) - AN-X OSC1 现 100% 映射 — 所有字段均已解析 (步骤 74) ## 仓库结构 ``` ysfc-forge/ ├── tools/ │ ├── ysfc_forge_v1.19.html # Librarian / merge tool │ ├── ysfc_performance_editor_v3.html # Patch editor (FM-X, AWM2, AN-X) ├── translators/ │ └── ysfc_diva_h2p_converter_v2_15.html # Convert DIVA patches │ └── ysfc_vital_converter_v4_12.html # Convert Vital patches │ └── ysfc_synth1_converter_v5_12.html # Convert Synth1 patches ├── utilities/ │ └── ysfc_esp_librarian_v7.html # Prototype librarian │ ├── ysfc_smart_name_compressor.html # Easy standardized naming conventions │ ├── ysfc_synth_converter.html # Convert patches ├── serializer/ │ ├── ysfc_serializer_v6.py # Python parameter constants (v6) │ └── ysfc_fx_type_index.py # Insertion FX type index ├── docs/ │ ├── readme_svensk_version.txt # Information in Swedish │ ├── YSFC_FORGE_FULL_CONTEXT_v10.md # Full technical documentation │ ├── YSFC_FORGE_FULL_CONTEXT_v10_svensk_version.md # Full technical documentation (Swedish) │ ├── ysfc_parameterbetyg_v7_en.txt # Parameter ratings and offsets │ ├── ysfc_parameterbetyg_v7_svensk_version.txt # Parameter ratings and offsets (Swedish) └── README.md ``` ## 技术文档 详细的参数表、编码公式和二进制分析笔记位于 [`docs/YSFC_FORGE_FULL_CONTEXT_v10.md`](docs/YSFC_FORGE_FULL_CONTEXT_v10.md)。 Python 序列化器 (`serializer/ysfc_serializer_v6.py`) 包含所有经验证的绝对偏移量、编码类型和默认值作为命名常量 — 如果您想构建自己的工具，这会非常有用。 ### 编码参考（精选） | 类型 | 公式 | |------|---------| | direct u8 | `raw = value` | | center=64 | `raw = value + 64` | | center=128 | `raw = value + 128` | | AN-X PulseWidth | `raw = round(pct × 256/100)` | | AN-X SelfSyncPitch | `raw = round(UI/25) + 256` | | AN-X Filter FEGDepth | `raw = round(UI/50) + 256`，范围 ±12700 音分 | | AN-X PitchEGDepth | `raw = round(UI_cent × 247/4800) + 247`，范围 ±4800 音分 | | AN-X Assign / SuperKnob value | u16 little-endian，默认值=512 | | FM-X algorithm | `raw = algo − 1` | | FM-X OP detune | `raw = value + 15` | | InsA/B TypeIndex | `lo = idx & 0x7F`，`hi = (idx >> 7) & 0x7F` | | Waveform number | u16 little-endian，从 1 开始 | # ⚠ 已知限制 - **采样与波形** — 本工具用于合并演出。独立的用户波形扩展不能自动处理（尽管 ESP Librarian 会追踪 EWFM/DWFM 的依赖关系）。 - **X7L / X8L 作为容器** — 这些格式不能用作导出容器。请先将它们加载到您的合成器中并导出为 Y2L。 - **Montage M (原版)** — 格式可能与 MODX M 完全相同。未经测试。 - **场景参数快照** — 可以检测到场景数 (`perf[6695]`)，但每个场景的参数快照数据尚未完全映射。 - **Smart Morph** — 未映射。 - **多部分演出** — 引擎检测可以处理混合引擎的部分（如 AWM2 + FM-X 等），但音色编辑器目前仅显示第一个部分的引擎。 - **第三方库文件** — 来自其他来源的文件可能具有非标准的 blob 头值。Forge Librarian 会通过 `sanitizePerfBlob()` 自动纠正已知情况，但如果波形 flash 地址错误，不在修正表中的演出可能仍然无法加载。 ## 免责声明 本项目不隶属于、不受认可于、也不受赞助于 Yamaha 公司。MODX M、ESP plugin、Montage M 及相关产品名称为 Yamaha 公司的商标。对该文件格式进行逆向工程仅出于互操作性目的。使用风险自负，请始终备份您的原始文件。 ## 许可证 MIT — 详见 [LICENSE](LICENSE)

标签：AN-X, AWM2, DIVA Patch, ESP Plugin, FM-X, MIDI, .sys文件处理, Web音频, Yamaha MODX M, Yamaha Montage M, 二进制分析, 二进制发布, 云安全运维, 云资产清单, 前端工具, 参数映射, 后端开发, 多模态安全, 开源工具, 技术文档, 数据可视化, 数据转换, 未公开格式解析, 本地化处理, 浏览器工具, 离线应用, 跨平台转换, 逆向工具, 逆向工程, 雅马哈, 音乐制作, 音乐科技, 音效设计, 音色库管理, 音色文件编辑, 音频合成器, 音频插件