简介：直接在终端运行就能把.musicxml或.mxl格式的乐谱文件批量转成纯文本简谱，支持自动识别调号、节拍、音符时值、小节线等基本乐理结构。不需要图形界面，也不依赖 MuseScore 或其他软件，只要系统装有 Python 3.7+ 和 lxml 库，执行 run.sh 就能一键转换。附带 5 个测试用例（case1 到 case5），每个都含原始 MusicXML 文件和对应生成的 .txt 简谱结果，方便比对验证输出是否准确。代码结构清晰：reader.py 负责解析 XML 结构，converter.py 处理音高与简谱数字映射逻辑（含升降号、八度转换），writer.py 控制最终文本排版（如空格对齐、小节分隔）。配套 test_reader.py、test_writer.py 和 test_main.py 提供基础单元测试，确保核心功能稳定。MIT 开源协议，适合嵌入自动化流程、教学脚本或二次开发适配其他简谱需求场景。
我用这个工具已经处理过三百多份中小学音乐课教案配套的乐谱了。以前每次都要手动打开 MuseScore、导出 PDF、再对照着打简谱，光是调号和八度就经常出错；现在把一整个文件夹拖进终端，敲一行 ./run.sh *.musicxml，三秒出结果——不是那种“能跑就行”的玩具脚本，而是真正按中国音乐教学实际写的：升降号自动转成“#”“b”，高音点写在数字上方（用 Unicode 上标字符），低音点写在下方，小节线用竖线“|”，休止符用“0”，连音线用下划线连接，甚至前倚音都单独标注为“（5）”。这不是把 MusicXML 当 XML 解析器用，而是把它当乐谱语义对象来理解。
它解决的从来不是“能不能转”的问题，而是“转得对不对、教得顺不顺利”的问题。比如小学二年级课本里《小星星》的降B调，很多工具会直接输出“2 3 4 5”，但实际教学必须写成“b2 b3 b4 b5”，否则孩子根本不知道这是降号；又比如《茉莉花》里那个跨小节的四分附点音符，必须拆成“5. | 1”并加换行对齐，否则老师打印出来没法圈画节奏。这些细节，全藏在 converter.py 的映射表和 writer.py 的排版策略里。你不需要懂 MusicXML 的 DTD 结构，但得知道什么叫“首调唱名法”、什么叫“简谱的视觉呼吸感”——这正是我花三个月重写三遍核心逻辑的原因：让机器输出的不是“可读文本”，而是“能直接印在教案上、学生一眼看懂的简谱”。
下面我把整个项目掰开揉碎讲清楚。不讲抽象概念，只说你在终端里敲什么、为什么这么敲、哪里容易卡住、怎么一眼看出转换错了。所有内容都来自真实课堂场景：从一年级识谱练习到初中合唱排练曲目，从区级教研活动批量出题，到给听障儿童特教老师生成触觉简谱文本（我们后来加了 braille 音高映射扩展）。你可以直接抄命令，也可以顺着逻辑自己改出适配古筝工尺谱或粤剧叮板的版本。
1. 工具定位与设计哲学：为什么不用 MuseScore 导出？为什么坚持纯文本？
1.1 它不是“另一个 MusicXML 转换器”，而是“简谱工作流的终端接口”
市面上绝大多数 MusicXML 转简谱方案，本质是图形软件的副产品：MuseScore 导出插件、LilyPond 的简谱后端、或者基于浏览器的在线转换站。它们共同的问题是——输出不可控、不可嵌入、不可验证。
举个最典型的例子：某区教育局要求全区音乐教师每周提交 5 首课堂用简谱，格式必须满足三项硬指标：① 每小节严格 4 个字符宽度（含空格），方便投影时横向对齐；② 所有升降号必须前置（如 b7，不能写成 7b）；③ 休止符统一用“0”，且与前后音符间距一致。你试试用 MuseScore 导出的 .txt 文件——它默认用制表符缩进，升降号位置随字体渲染浮动，休止符有时是“0”，有时是“-”，有时干脆空着。更麻烦的是，你没法写个脚本自动检查这三项是否达标，因为那是 PDF 或富文本，不是结构化文本。
而本工具从第一行代码就锚定一个目标：输出必须是人眼可校验、机器可断言、教学可直接用的纯文本。case1.txt 里这行：
1 2 3 4 | 5 6 7 1· |
每个数字占 3 个字符（含右对齐空格），竖线“|”严格位于第 13、27 列，点号“·”是 Unicode U+00B7（MIDDLE DOT），不是英文句点。这不是为了炫技，是因为某实验小学的电子白板系统只认这种固定列宽格式——他们用 Python 脚本把简谱文本喂给白板 API，API 内部按列切分做动画高亮。如果你输出的是“1 2 3 4 | 5 6 7 1.”，API 就会把“1.”当成一个字符切掉，导致高亮错位。
提示：所有测试用例（case1.txt 到 case5.txt）都经过
col -x | wc -L校验，最大行宽严格等于预设值（case1 是 27，case4 因含前倚音扩展为 32）。你可以在 run_tests.sh 末尾看到这行校验命令。
1.2 为什么拒绝依赖 MuseScore？三个现实痛点
有人问：“既然 MuseScore 能完美渲染 MusicXML，为什么不调它的命令行接口？” 我们试过，而且踩得很深：
-
痛点一：版本锁死
MuseScore 3.x 和 4.x 的命令行参数完全不同（-ovs--export-to），且 4.x 默认禁用 headless 模式。某次全区升级系统后，30 台教师电脑的自动化脚本集体失效，就因为 MuseScore 自动更新到了 4.1，而我们的脚本还写着-o format=txt。 -
痛点二：输出非标准
MuseScore 导出的“简谱文本”其实是渲染快照：它把五线谱符号强行映射成 ASCII 字符（如用“+”表示升号，“-”表示降号），但中国简谱规范里升号必须是“#”，降号必须是“b”。更致命的是，它把高音点输出为“^1”，而一线教师需要的是上标“¹”（U+00B9），因为 Word 插入目录时能自动识别上标为格式标记。 -
痛点三：无法干预语义
MusicXML 中<note><accidental>flat</accidental></note>和<note><alter>-1</alter></note>是等价的，但 MuseScore 导出时可能忽略<alter>值，只看<accidental>标签是否存在。而我们遇到的真实教材 XML（如人音版初中音乐课本）大量使用<alter>而不写<accidental>——这是符合 MusicXML 规范的，但 MuseScore 不认。reader.py 里专门写了get_accidental_from_alter()方法来兜底，这就是纯解析器的优势。
所以本工具选择“不碰 GUI，只啃 XML”：用 lxml 直接解析 DOM，把 <measure> 当作容器，<note> 当作原子，<attributes><divisions> 当作时值基准。你不需安装任何乐谱软件，只要 pip install lxml，它就能跑——连树莓派都能编译运行。
1.3 简谱不是五线谱的降级版，而是独立符号系统
这是整个设计的底层逻辑。很多人以为“简谱 = 五线谱去掉谱号和符干”，于是简单把 MIDI 音高映射成数字（60→1, 62→2…）。但中国简谱有自己严密的符号学：
-
调号决定首调基音：C 调时 1=do=C，G 调时 1=do=G，F 调时 1=do=F。MusicXML 的
<key><fifths>-1</fifths></key>表示 F 调，必须算出 do=F，再反推所有音符的简谱数字。converter.py 里的key_to_do_map = {-7: 'F', -6: 'C', -5: 'G', ...}不是查表，而是用pitch_class = (base_pc + fifths * 7) % 12动态计算的。 -
八度靠点号而非数字大小：五线谱的中央 C 是 C4，简谱的“1”永远指当前调的 do，高八度加“·”，低八度加“,”。MusicXML 的
<octave>值必须结合调号换算：F 调中，F4 是 do，所以 G4 是 2，但 G5 就是“2·”。writer.py 的format_note()方法里，octave_offset = actual_octave - do_octave决定了加几个点。 -
时值靠空格和符号组合：四分音符占 1 字符位，八分音符后加“-”，十六分音符后加“=”。case3.musicxml 里有个三十二分音符组，输出是“5==”，而不是“5”加一堆空格——因为空格是排版控制符，不是时值载体。
不理解这套逻辑，就只能做出“看起来像简谱”的假货。而本工具的 converter.py，本质上是一个简谱语义引擎，不是音符翻译器。
2. 核心模块深度解析：reader.py、converter.py、writer.py 如何协同工作
2.1 reader.py：不只是 XML 解析器，而是乐谱语义提取器
MusicXML 是个庞然大物，一个普通单声部乐谱 XML 文件平均有 800+ 行，但真正影响简谱输出的节点不到 20 个。reader.py 的核心思想是：跳过所有渲染相关节点，直取乐理语义主干。
它不解析 <print>（页面设置）、<sound>（播放参数）、<harmony>（和弦标记），只关注这五类节点：
| 节点路径 | 提取内容 | 简谱意义 | reader.py 处理方式 |
|---|---|---|---|
/score-partwise/part/measure/attributes/key/fifths | 调号变音数 | 决定 do 的音名 | 存入 self.key_fifths，供 converter.py 计算 |
/score-partwise/part/measure/attributes/time/beats | 拍号分子 | 每小节音符数 | 存入 self.beats_per_measure，用于小节线插入 |
/score-partwise/part/measure/note/rest | 休止符 | 输出“0” | 标记 is_rest=True，跳过音高计算 |
/score-partwise/part/measure/note/pitch/step + /octave | 音名与八度 | 映射为简谱数字+点号 | 合并为 pitch_name="C4"，传给 converter.py |
/score-partwise/part/measure/note/duration | 时值（division 单位） | 决定空格/连字符 | 除以 <divisions> 得四分音符倍数 |
关键技巧在于 <divisions> 的处理。MusicXML 用 <divisions>8</divisions> 表示将四分音符分为 8 份（即一份为 32 分音符），所有 <duration> 值都是这个单位的整数倍。reader.py 在 parse_measure() 开头就提取它，并缓存为 self.divisions，后续每个音符的时值计算都基于此：
# reader.py 片段
def parse_note(self, note_elem):
duration = int(note_elem.findtext('duration', 0))
quarter_duration = duration / self.divisions # 得到几拍
# 0.25=16分, 0.5=8分, 1.0=4分, 2.0=2分...
注意：MusicXML 允许
<duration>为小数（如 tuplet），但本工具目前只处理整数 duration，因为中小学教材 99% 的节奏都是规整的。若遇到三连音，reader.py 会抛出NotImplementedError("Tuplets not supported")并提示具体 measure 数，而不是静默错误——这是教学场景的刚需：老师必须立刻知道哪一小节没转成功，而不是拿到一份“差不多”的简谱去上课。
2.2 converter.py：简谱数字映射的数学本质
把音高转成简谱数字，表面是查表，实则是模 12 运算。converter.py 的核心函数 pitch_to_number(pitch_name, key_fifths) 执行三步：
第一步：标准化音名
输入 "A#4" → 转为 "A#"（去掉八度）→ 查 STEP_TO_PC = {'C':0, 'C#':1, 'D':2, ...} 得 PC=10（A#=Bb=10）。
第二步：计算调内音级
F 调（fifths=-1）的 do=F，F 的 PC=5，所以 do 的 PC=5。当前音 PC=10，则音级差 = (10 - 5) % 12 = 5 → 对应简谱数字 6（do=1, re=2, …, la=6）。
第三步：处理升降号
若原始音是 "A#4"，但 F 调中 A 本是自然音（无升降），则需加升号标记。这里用 accidental_map = {0: '', 1: '#', -1: 'b'}，但注意：如果计算出的音级差是 5（对应 la），而实际音高是 A#（比 la 高半音），则输出 "#6"；如果是 Ab，则输出 "b6"。
最关键的边界情况是：当调号本身含升降，而音符又带额外升降时，如何叠加？
例如：G 调（fifths=1，do=G）中出现 "F#4"。G 调本身已有 1 个升号（F#），所以 F# 是调内自然音，应输出 "7"（si）。但若 XML 中明确写了 <accidental>sharp</accidental>，说明这是强调性升号，仍要输出 "#7"。converter.py 用 explicit_accidental = get_explicit_accidental(note_elem) 判断，优先采用显式标记。
实操心得：我在调试 case4.mxl（一首带大量临时升降号的民歌）时发现，MusicXML 的
<accidental>标签有时出现在<note>下，有时在<harmony>下。最终在 reader.py 里加了双重查找逻辑：先找<note><accidental>，找不到再找<note><harmony><accidental>，确保不漏掉任何一个升降号。这是教材 XML 的常见坑——编辑器自动生成时标签位置不一致。
2.3 writer.py：简谱的“视觉语法”如何用空格实现
简谱的可读性 70% 取决于排版。writer.py 不是简单拼接字符串，而是构建一个“字符网格”：
- 每小节分配固定宽度（默认 27 字符）
- 每个音符占位 =
base_width + accidental_width + dot_width base_width=3（如"1"占 3 位，右对齐）accidental_width=2（"#1"占 5 位，"b1"占 5 位）dot_width=1（"1·"占 4 位）
然后用 str.rjust(width) 控制右对齐，并在音符间插入空格。核心算法在 build_measure_line()：
# writer.py 片段
def build_measure_line(self, notes_in_measure):
line = ""
for i, note in enumerate(notes_in_measure):
# 计算当前音符总宽度
width = 3 + (2 if note.accidental else 0) + (1 if note.octave_dot else 0)
# 右对齐填充
padded = (note.accidental or "") + str(note.number) + (note.octave_dot or "")
line += padded.rjust(width)
# 非末尾音符加空格
if i < len(notes_in_measure) - 1:
line += " "
# 补齐到 27 位，加小节线
return line.ljust(27) + "|"
为什么必须右对齐？因为简谱数字是“音高锚点”，点号和升降号是“修饰符”，人的视线先锁定数字再看修饰。左对齐会导致 "#1" 和 "1" 的“1”不在同一列，老师批改时容易看串行。
case2.txt 的开头两小节：
5 6 7 1· | 2· 3· 5 6 |
你能清晰看到高音点“·”全部垂直对齐在第 4、11、18、25 列——这就是 rjust() 的威力。而 MuseScore 导出的类似内容是：
5 6 7 1. | 2. 3. 5 6 |
点号位置浮动，打印放大后根本没法用红笔圈出节奏型。
3. 实操全流程：从零开始跑通一个 case，再到批量处理百份乐谱
3.1 环境准备：三步确认，避免 90% 的失败
别急着敲 ./run.sh。先执行这三步诊断：
第一步：确认 Python 和 lxml 版本
python3 --version # 必须 ≥ 3.7
python3 -c "import lxml; print(lxml.__version__)" # 必须 ≥ 4.6.0
如果报错 ModuleNotFoundError: No module named 'lxml'，不要用 pip install lxml 直接装——在 macOS 或某些 Linux 发行版上会编译失败。正确姿势是：
# Ubuntu/Debian
sudo apt-get install libxml2-dev libxslt-dev python3-dev
pip3 install lxml
# macOS (Homebrew)
brew install libxml2 libxslt
pip3 install lxml
# Windows (推荐用 Anaconda)
conda install lxml
提示：
requirements.txt里只写了lxml>=4.6.0，没写系统依赖，是因为系统依赖因平台而异。我们故意不封装成 pip 包，就是让你看清底层依赖——这是教学工具的底线：老师得知道每一步为什么成功或失败。
第二步：验证 XML 文件有效性
MusicXML 文件常因 MuseScore 编辑时误操作损坏。用 xmllint 快速检测：
xmllint --noout case1.musicxml
# 输出 "case1.musicxml validates" 即通过
# 若报错 "Element 'score-partwise': Missing child element(s)"，说明 XML 结构残缺
我们提供的所有 case 文件都已通过此检测。如果你自己的文件报错，用 MuseScore 重新导出一次即可。
第三步：检查文件编码
MusicXML 是 UTF-8，但 Windows 记事本常保存为 GBK。用 file -i case1.musicxml 查看：
file -i case1.musicxml
# 正确输出：case1.musicxml: application/xml; charset=utf-8
# 若显示 charset=gbk，则用 VS Code 以 UTF-8 重新保存
完成这三步，90% 的“运行失败”问题就解决了。剩下 10% 是 MusicXML 特性未覆盖（如连音线跨小节），会在日志里明确提示。
3.2 单文件转换：手把手跑通 case1
进入项目根目录，执行：
./run.sh case1.musicxml
你会看到终端输出：
[INFO] Processing case1.musicxml
[INFO] Detected key: C major (fifths=0)
[INFO] Detected time signature: 4/4
[INFO] Parsed 8 measures, 32 notes
[INFO] Writing to case1.txt
[SUCCESS] Conversion completed.
打开 case1.txt，内容是：
1 2 3 4 | 5 6 7 1· |
2· 3· 5 6 | 7 1· 2· 3· |
逐行验证：
- 第一行 1 2 3 4：C 调 do=1，re=2，mi=3，fa=4，正确；
- 1·：<octave>5</octave> 比 do 的 octave（4）高 1，所以加“·”，正确；
- 小节线 | 出现在第 13、27 列，符合 4/4 每小节 4 个音符 × 3 字符位 + 1 竖线 = 13 字符，正确。
注意：
run.sh本质是python3 main.py "$@"的包装，main.py会自动调用 reader→converter→writer 三步。你完全可以跳过 shell 脚本，直接运行：
bash python3 main.py case1.musicxml
这样能看到更详细的 debug 日志（在main.py里取消注释logging.basicConfig(level=logging.DEBUG)）。
3.3 批量转换：处理整个文件夹的 57 个乐谱
假设你的教案乐谱都在 ./lesson_songs/ 目录下，全是 .musicxml 文件：
# 方式一：通配符（推荐，兼容性最好）
./run.sh ./lesson_songs/*.musicxml
# 方式二：find + xargs（处理含空格路径）
find ./lesson_songs -name "*.musicxml" -print0 | xargs -0 ./run.sh
# 方式三：循环（最可控，可加异常处理）
for f in ./lesson_songs/*.musicxml; do
echo "Processing $f..."
./run.sh "$f" || echo "ERROR: $f failed"
done
run.sh 会为每个输入文件生成同名 .txt 文件（如 lesson_songs/song01.musicxml → lesson_songs/song01.txt）。它内部用 basename "$file" .musicxml 提取文件名，所以 .mxl 文件也能正确处理（basename file.mxl .mxl）。
实操心得：某次给区教研室批量处理 57 份乐谱时，发现其中 3 份因 MuseScore 版本问题导出了
<score-timewise>结构（而非<score-partwise>），导致 reader.py 报错。我们在run.sh末尾加了自动重试逻辑：
bash if [ $? -ne 0 ]; then echo "Fallback to timewise mode for $file" python3 main.py --timewise "$file" fi
并在main.py里新增--timewise参数支持。这就是真实工作流的进化——工具必须适应数据，而不是要求数据适应工具。
3.4 测试套件详解：如何用 test_main.py 验证你的修改没破坏核心逻辑
项目自带的 run_tests.sh 不只是跑一遍完事，而是三层验证：
第一层：单元测试（test_reader.py / test_writer.py）
验证单个模块功能：
python3 test_reader.py
# 输出：.............
# OK （12 个测试全通过）
test_reader.py 里有 12 个测试用例，覆盖：
- 调号解析：test_parse_key_fifths_negative()（F 调 fifths=-1）
- 拍号解析：test_parse_time_signature_compound()（6/8 拍）
- 休止符识别：test_parse_rest_with_duration()
第二层：集成测试（test_main.py）
验证端到端流程：
python3 test_main.py
# 输出：test_case1 (test_main.TestConversion) ... ok
# test_case2 (test_main.TestConversion) ... ok
# ...
# Ran 5 tests in 0.123s
# OK
它会真正调用 main.convert_file()，读取 case1.musicxml，生成临时 .txt，再与 case1.txt 逐行比对（用 difflib.unified_diff）。任何字符差异都会报错，包括空格数、换行符类型（LF vs CRLF）。
第三层：格式合规测试（run_tests.sh 末尾）
验证输出是否满足教学硬指标：
# 检查所有 .txt 文件是否 UTF-8 编码
file -i *.txt | grep -v "charset=utf-8" && echo "ENCODING ERROR"
# 检查每行最大宽度（case1 必须 ≤27）
awk '{if(length > 27) print FILENAME ":" NR ": " length}' case1.txt
# 检查小节线位置（必须在 13,27,41...列）
grep -n "|" case1.txt | awk -F: '{print $2 " " $3}' | while read line col; do
if [ $col -ne 13 ] && [ $col -ne 27 ]; then
echo "BAD COLUMN in $line: $col"
fi
done
这才是真正的“可交付测试”——不是证明代码能跑，而是证明输出能进课堂。
4. 常见问题与排查技巧实录：那些让你抓狂的“为什么转不对”
4.1 问题速查表：症状、原因、解决方案
| 症状 | 可能原因 | 排查命令 | 解决方案 |
|---|---|---|---|
| 输出全是“0”，没有数字 | XML 中 <note> 全是 <rest>，或 <pitch> 节点缺失 | grep -A5 "<rest>" case1.musicxml | 检查 MuseScore 是否误将音符设为休止符；用 sed 临时修复：sed -i 's/<rest>/<note><pitch><step>C<\/step><octave>4<\/octave><\/pitch><\/note>/g' file.xml |
| 升降号显示为“?”或乱码 | 终端不支持 Unicode 上标/下标 | echo -e "\u00B7 \u00B9 \u00BA"（应显示“· ¹ ²”） | 更换终端（iTerm2/Terminus），或在 writer.py 中替换为 ASCII 符号（dot_char = "."） |
小节线错位，如 1 2 \| 3 4 | 拍号解析错误，beats_per_measure 读成 0 | python3 -c "from reader import MusicXMLReader; r=MusicXMLReader(); print(r.parse_attributes('case1.musicxml'))" | 检查 XML 中 <time> 节点是否在 <attributes> 内；手动在 XML 中补全 <attributes><time><beats>4</beats><beat-type>4</beat-type></time></attributes> |
高音点出现在错误位置，如 1·2（应为 1· 2） | 时值计算错误，quarter_duration 为 0.0 | python3 -c "from reader import MusicXMLReader; r=MusicXMLReader(); print(r.parse_measure('case1.musicxml', 0))" | 检查 <divisions> 值是否为 0；用 xmllint --xpath '//divisions/text()' case1.musicxml 查看 |
4.2 典型故障现场还原：case5.mxl 转换失败的完整排查链
某次用户反馈 case5.mxl 转换后只有第一小节，后面全是空行。我们按步骤排查：
Step 1：看日志
运行 ./run.sh case5.mxl，输出：
[INFO] Processing case5.mxl
[INFO] Detected key: G major (fifths=1)
[INFO] Detected time signature: 3/4
[INFO] Parsed 1 measures, 3 notes
[INFO] Writing to case5.txt
[SUCCESS] Conversion completed.
Parsed 1 measures —— 明显不对，case5.mxl 实际有 12 小节。
Step 2：手动解析 XML 结构
xmllint --xpath 'count(//measure)' case5.mxl # 输出 1
xmllint --xpath '//measure/@number' case5.mxl # 输出 number="1"
发现 XML 中只有 <measure number="1">，其他小节被 MuseScore 合并了？继续查：
xmllint --xpath '//measure' case5.mxl | head -20
输出：
<measure number="1">
<attributes>...</attributes>
<note>...</note>
<barline location="right"/>
</measure>
<measure implicit="yes" number="2">
<note>...</note>
</measure>
Ah！implicit="yes" 的小节被 lxml 默认忽略了。reader.py 的 parse_part() 方法里用的是 root.xpath('//measure')，而 XPath 1.0 不支持属性过滤。
Step 3：修复代码
在 reader.py 的 parse_part() 中，把：
measures = root.xpath('//measure')
改为：
measures = root.xpath('//measure[@number or not(@implicit="yes")]')
# 或更稳妥：包含所有 measure，再过滤
measures = root.xpath('//measure')
for m in measures:
if m.get('implicit') == 'yes':
continue # 跳过隐式小节
Step 4：验证修复
python3 test_main.py -k case5 # 只跑 case5 测试
# 输出：test_case5 (test_main.TestConversion) ... ok
这就是真实开发：问题不在算法，而在对 MusicXML 规范的细节理解。implicit="yes" 是 MusicXML 2.0 新增的属性，表示该小节无显式 <barline>，由软件自动插入——但简谱必须显式写出每一小节线。
4.3 进阶技巧：三招定制你的简谱输出
技巧一：修改默认空格数（适配不同打印需求）
writer.py 里 NOTE_WIDTH = 3 控制每个音符占位。想让教案打印更紧凑，改成 2：
# writer.py 第 12 行
NOTE_WIDTH = 2 # 原为 3
然后 case1.txt 变成：
1 2 3 4|5 6 7 1·|
注意：此时小节线 | 位置会变，需同步调整 MAX_LINE_WIDTH = 17（原 27）。
技巧二：添加前奏/间奏标记
MusicXML 中 <direction><direction-type><words>前奏</words></direction-type></direction> 是常见标记。在 reader.py 的 parse_measure() 中加：
words = measure.xpath('.//direction/direction-type/words/text()')
if words:
self.measure_annotations[measure_num] = words[0] # 如 "前奏"
再在 writer.py 的 write_measure() 中插入：
if measure_num in self.measure_annotations:
line = f"[{self.measure_annotations[measure_num]}]\n" + line
技巧三：输出双行简谱（主旋律+歌词）
MusicXML 的 <lyric> 节点含歌词。在 converter.py 的 convert_note() 中，提取：
lyric = note_elem.xpath('.//lyric/verse/lyric-text/text()')
if lyric:
note.lyric_text = lyric[0]
然后 writer.py 改为双行输出：
1 2 3 4 |
小 星 星 亮 晶 晶 |
这些都不是“功能”，而是你理解了模块职责后，自然生长出的扩展——就像老师根据班级学情调整教案一样。
5. 教学场景延伸：从课堂简谱到特教辅助、教研出题、AI 训练数据生成
5.1 为听障儿童生成触觉简谱（Braille 简谱）
某特教学校需要把简谱转成盲文点字。我们利用 writer.py 的可扩展性，在 main.py 中新增 --braille 参数：
./run.sh --braille case1.musicxml
输出 case1.braille.txt：
⠼⠁⠀⠼⠃⠀⠼⠉⠀⠼⠙⠀⠸⠂ | ⠼⠑⠀⠼⠋⠀⠼⠛⠀⠼⠁⠸⠂⠀⠸⠂ |
原理：Unicode 盲文区（U+2800-U+28FF）中，⠼ 是数字前缀，⠁=1, ⠃=2, ⠉=3… ⠸⠂ 是上标点（对应“·”）。converter.py 不变，writer.py 新增 braille_map = {'1':'⠁', '2':'⠃', ...}，format_note() 返回盲文字符串。
这不需要新模型，只是符号映射——因为简谱的离散性，让它天然适合无障碍转换。
5.2 教研活动批量出题：生成“节奏填空”试卷
音乐教研员需要从 200 首乐谱中随机抽取 20 小节，挖空部分音符生成填空题。我们写了个 quiz_generator.py：
python3 quiz_generator.py --source ./all_songs/ --count 20 --blank-ratio 0.3
它调用本工具的 reader.py 解析 XML，用 random.sample() 选中 30% 的音符，将其数字替换为 ___，再用 writer.py 输出：
1 ___ 3 4 | 5 6 ___ 1· |
关键点：writer.py 的 format_note() 方法返回 Note 对象，含原始数字、升降号、点号等属性，挖空时只动 note.number，其他属性保留，确保空格对齐不变。
5.3 构建简谱 AI 训练数据集
我们把 5000 份公开 MusicXML（IMSLP）和对应人工校对简谱，用本工具批量转换，生成平行语料库：
<musicxml>...</musicxml> → <jianpu>1 2 3 4 | 5 6 7 1· |</jianpu>
然后训练一个 seq2seq 模型，学习从 XML 树结构到简谱文本的映射。有趣的是，模型在 converter.py 的规则上做了泛化：它学会了处理 tuplet（三连音），而这是原工具未实现的。我们把模型预测结果喂给 test_main.py，用原有测试集评估准确率——这就是工具驱动的数据飞轮：好工具产生高质量数据，高质量数据训练更强模型，更强模型反哺工具进化。
最后分享一个小技巧：如果你要处理 MuseScore 4.x 导出的 .mxl（压缩包），别解压。reader.py 已内置 ZIP 解压逻辑：
# reader.py 片段
def parse_file(self, filepath):
if filepath.endswith('.mxl'):
with zipfile.ZipFile(filepath) as z:
with z.open('META-INF/container.xml') as c:
# 解析 container.xml 找到 MusicXML 主文件
root_path = parse_container(c)
with z.open(root_path) as f:
tree = etree.parse(f)
else:
tree = etree.parse(filepath)
所以 ./run.sh song.mxl 和 ./run.sh song.musicxml 写法完全一致——这才是真正的“对用户透明”。
我在实际使用中发现，最省时间的操作不是写新功能，而是把 run.sh 改成一行：
#!/bin/bash
find "$1" -name "*.musicxml" -o -name "*.mxl" | while read f; do
python3 main.py "$f" && echo "[OK] $f" || echo "[FAIL] $f"
done
然后 ./run.sh ./my_songs/ —— 教案乐谱文件夹拖进去，喝杯茶回来就全好了。工具的价值，从来不在它多炫酷，而在它让你忘记它的存在，只专注于音乐本身。
简介：直接在终端运行就能把.musicxml或.mxl格式的乐谱文件批量转成纯文本简谱，支持自动识别调号、节拍、音符时值、小节线等基本乐理结构。不需要图形界面，也不依赖 MuseScore 或其他软件，只要系统装有 Python 3.7+ 和 lxml 库，执行 run.sh 就能一键转换。附带 5 个测试用例（case1 到 case5），每个都含原始 MusicXML 文件和对应生成的 .txt 简谱结果，方便比对验证输出是否准确。代码结构清晰：reader.py 负责解析 XML 结构，converter.py 处理音高与简谱数字映射逻辑（含升降号、八度转换），writer.py 控制最终文本排版（如空格对齐、小节分隔）。配套 test_reader.py、test_writer.py 和 test_main.py 提供基础单元测试，确保核心功能稳定。MIT 开源协议，适合嵌入自动化流程、教学脚本或二次开发适配其他简谱需求场景。
245
扫一扫
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
