MusicXML 4.0 学习与开发进度
最后更新：2026-01-30
当前状态：阶段一完成，待进入阶段二
📚 已完成的学习内容
1. Hello World
- 掌握了
score-partwise 基本结构
- 理解了
divisions 时值单位概念
- 学会了音高、时值、调号、拍号的表示方式
2. 文件结构
- 了解了
partwise vs timewise 两种组织方式
- 掌握了 Score Header 的组成部分
- 熟悉了 Music Data 的各类元素
3. MIDI兼容部分
- 掌握了音高、休止符、时值、连音线的表示
- 学会了和弦、歌词、反复记号的处理
- 理解了
backup/forward 实现多声部的机制
4. 记谱法基础
- 学会了符头类型、符干、符杠、临时记号
- 掌握了连音符(
time-modification/tuplet)的表示
- 理解了
voice 和 staff 处理多声部/跨谱表
5. 压缩文件格式
6. 和弦符号与图表
- 掌握了
<harmony> 元素用于和弦符号和功能和声分析
- 理解了
<root>, <kind>, <degree>, <bass> 等元素
- 了解了
<frame> 元素用于表示和弦图表（指板图）
7. 打击乐
- 了解了
<unpitched> 元素和 <display-step>/<display-octave>
- 掌握了
<staff-lines> 定义打击乐谱表
- 理解了
<notehead> 和 <measure-repeat> 元素
8. 六线谱
- 掌握了
<fret>、<string>、<staff-tuning>、<capo> 等元素
- 了解了
<hammer-on>、<pull-off> 等吉他技巧
9. 核心元素定义
- 详细学习了
<note>、<divisions>、<attributes>、<time-modification>、<barline>、<repeat> 等核心元素
✅ 阶段一开发完成
已创建的模块：src/music-core/
数据模型 (models/)
| 文件 |
说明 |
状态 |
types.ts |
基础类型定义（音名、时值、谱号等枚举） |
✅ |
Pitch.ts |
音高模型，支持首调/固定调转换 |
✅ |
Note.ts |
音符模型，包含时值、连音、歌词等 |
✅ |
Attributes.ts |
属性模型（调号/拍号/谱号/移调） |
✅ |
Direction.ts |
方向标记（速度/力度/渐变/踏板等） |
✅ |
Barline.ts |
小节线（反复/结尾/Segno/Coda） |
✅ |
Notations.ts |
记号（连线/演奏技法/装饰音） |
✅ |
Harmony.ts |
和弦符号 |
✅ |
Measure.ts |
小节模型 |
✅ |
Part.ts |
声部模型 |
✅ |
Score.ts |
乐谱顶层模型 |
✅ |
解析器 (parser/)
| 文件 |
说明 |
状态 |
MusicXMLParser.ts |
主解析器入口 |
✅ |
StructureParser.ts |
结构解析（score/part/measure） |
✅ |
NoteParser.ts |
音符解析（note/pitch/rest） |
✅ |
AttributesParser.ts |
属性解析（key/time/clef） |
✅ |
DirectionParser.ts |
方向标记解析 |
✅ |
BarlineParser.ts |
小节线和和弦解析 |
✅ |
工具函数 (utils/)
| 文件 |
说明 |
状态 |
XMLUtils.ts |
XML 解析辅助函数 |
✅ |
PitchUtils.ts |
音高转换、MIDI计算、首调转换 |
✅ |
DurationUtils.ts |
时值计算、divisions换算 |
✅ |
KeyUtils.ts |
调号信息、五度圈、音阶生成 |
✅ |
配置更新
tsconfig.json 添加了 @music-core 路径别名 ✅
🎯 核心收获（对简谱渲染器的价值）
| MusicXML概念 |
简谱对应 |
step+octave |
简谱数字(1-7) + 高低点 |
duration/divisions |
音符时值计算 |
dot |
附点 |
time-modification |
连音符标记 |
tie/tied |
连音线 |
beam |
减时线（下划线） |
backup/forward + voice |
多声部处理 |
harmony |
和弦标记 |
barline (repeat, ending) |
反复记号 |
📋 下一步计划
阶段二：简谱渲染器重构与首调支持
| 任务 |
说明 |
状态 |
| 目录重组 |
创建 src/renderers/ 目录结构 |
⬜ |
| 模型转换器 |
从 music-core 模型转换为渲染模型 |
⬜ |
| 首调转换服务 |
实现首调/固定调切换逻辑 |
⬜ |
| 迁移现有渲染器 |
将 jianpu-renderer 迁移到新架构 |
⬜ |
| 模式切换 |
实现运行时首调/固定调切换 |
⬜ |
阶段三：五线谱渲染器
📁 代码位置
src/music-core/
├── index.ts # 模块入口
├── models/ # 数据模型（11个文件）
├── parser/ # 解析器（7个文件）
└── utils/ # 工具函数（5个文件）
🔖 使用示例
import { MusicXMLParser, parseMusicXML } from '@music-core';
// 方式1：使用类
const parser = new MusicXMLParser({ validate: true });
const result = parser.parse(xmlString);
console.log(result.score.title);
// 方式2：使用便捷函数
const score = parseMusicXML(xmlString);
for (const part of score.parts) {
for (const measure of part.measures) {
for (const note of measure.getNotes()) {
if (note.pitch) {
// 获取简谱表示（首调）
const jianpu = note.pitch.toJianpuString(keyFifths, true);
console.log(jianpu);
}
}
}
}
休息愉快！晚点继续阶段二的开发。 🎵
