Xiange Music MCP

弦歌 xiange

楽正線・一級

原作者：ZhongQuinnKing（メインアカウント表記） ライセンス：MIT。詳細は LICENSE.md をご覧ください。 商用利用・提携：まず [email protected] までご連絡ください（件名に【商用利用許諾】または【改編許諾】と明記してください）。このリポジトリの issue からもご連絡いただけます。

主流の AI 向けの音楽機能パッケージです。姉妹編：采诗はインターネットを読み、拾级は人に寄り添い、玉尺は文章を測り、弦歌は音楽を奏でます。

機能検証：実際のピアノ編曲プロジェクトを、選曲／ソース取得／譜面変換／譜面出力まで一貫して完了しました。成果物はすべてこのパッケージのものです。 プロジェクト自体が成果なのではなく、再利用可能なこのワークフローとツールこそが成果です。

パイプラインの概要

あらゆる入力（不鮮明な画像／スクリーンショット／鼻歌／一言／デジタルファイル）
  → 曲を特定：品質の低い入力は「手がかり」として扱い、無理に処理しない（docs/01）
  →
  ├─ 【デジタルソース直通ライン】ユーザーがデジタルファイルを所有している（自分で作成／正規版／ダウンロード）
  │     → 3 点セットを検証 → そのまま使用（最速・最も正確）
  └─ 【検索ライン】デジタルソースがない
        → 采诗でソースを探す：ウェブ全体から高品質な譜面を検索——弹琴吧／Bilibiliリンク／プラットフォーム横断検索（docs/02）
        → ソースを選定：デジタルソース ＞ 高解像度の印刷譜 ＞ 通常品質の印刷譜；手書きは使用しない
        → 譜面変換（エンジン連携＋複数エンジンによる合意、docs/03）
  →
  記号レイヤー：元の譜面画像から読み取って補完（連符／強弱／ペダル／運指）
  → 精密なレイアウト（Dorico）→ 譜面出力

各工程にソースと信頼度を明記します。 出庫ゲート：確認済みのものだけに「検証済み」と表示し、未確認のものはすべて「要確認」とします（「検証済み」と報告する場合は、標準レポートカードを添付してください。基準は docs/06 をご覧ください）。

クイックスタート（依存関係を含む）

環境：Python 3.11（参考環境では conda env music-transcribe を使用）。依存関係はツール別に分類されています。依存関係のないツールはインストール直後に使用できます。

• 依存関係なし（標準ライブラリのみ）：記譜関連の 2 つのツール（notation_check による点検／notation_fix による修復）。そのまま実行できます
• コア一式（requirements.txt：music21、numpy）：4 段階評価レポートカード（omr_eval）、音楽理論チェック（theory_check）、トリアージ（triage）、点検・修整（score_doctor）、合意形成（consensus）、デジタルソース検証 3 点セット（verify）、音声との照合（verify_vs_audio）
• レンダリング一式（requirements-render.txt：verovio、cairosvg、pillow）：レンダリング出力（vv_render／render_v4）と kern 修復（bekern_fix）
• ブラウザー一式（requirements-browser.txt：playwright）：簡譜処理（deliver_dolce）
• 入力ルーティング一式（requirements-vision.txt：opencv、numpy）：楽譜種別ルーティングツール、Bilibili のページ情報取得（bili_extract）

ワンコマンドでインストール：

bash install.sh core        # 分類ごとにインストール：core / render / browser / vision / all
bash install.sh all         # 4 分類すべてをインストール

5 分で始める：

python3 tools/xiange.py doctor              # 環境を自己診断（不足分があれば修復コマンドを表示）
python3 tools/xiange.py check 谱.musicxml   # 記譜を点検（依存関係なし、すぐ実行可能）
python3 tools/xiange.py selfcheck           # 判定基準レベルのセルフテストをすべて実行（まとめて確認）

（route／fix／export も同じシェルから実行できます。インストールできない場合は docs/12-故障排查 をご覧ください）

セルフテスト（判定基準レベルの 21 セット。CI と同じ内容）：

for f in tools/tests/test_*.py; do python3 "$f"; done

外部エンジン（SMT／Audiveris など）は pip の依存関係ではありません。連携方法は docs/03 をご覧ください。共通のエントリーポイントは tools/engine_runner.py です（エンジン登録簿と run.json に実行履歴を記録）。

よく使うコマンド：

• 記譜の点検：python3 tools/notation_check.py 谱.musicxml
• 譜面の点検：python3 tools/score_doctor.py inspect 谱.musicxml
• 楽譜種別のルーティング（入口）：python3 tools/工具_谱种路由.py 谱图.png。画像からまず楽譜種別（五線譜／タブ譜／簡譜など）を判定し、対応するエンジンと工程に進みます
• 音楽理論の点検：python3 tools/theory_check.py 谱.musicxml（声部交差／平行五度・八度／音程幅の上限を調整可能／密度の急減／音価）
• 完成品パッケージの出力：python3 tools/export_pack.py 谱.musicxml --out 目录 --title 曲名（五線譜 3 点＋mxl／mid＋簡譜 3 点＋試聴音源＋完成品カード＋zip）
• 譜面の規格チェック：python3 tools/yuchi_score_check.py 谱.musicxml（譜面の規格をチェック：小節の照合／付点の範囲外／タイの閉じ忘れ／臨時記号。診断のみで譜面は変更しません。記譜点検との役割分担はルール一式をご覧ください）

ナレッジライン：知识/90-音乐问答协议.md の 3 層パスに従って直接実行します。インストールは不要です。

ソース取得（再現ライン）：外部チャネルに依存します（采诗、オープンソースで公開：github.com/ZhongQuinnKing/caishi。各サイトの境界については docs/02 をご覧ください）。このチャネルを利用できない場合の代替手順：ローカルにあるファイルのみを処理するか、公開検索を使って自分で譜面を探します（弹琴吧／Bilibili などの直リンク先ページ）。docs/02 のソース分類と各サイトの境界に従ってください。無断で機能を縮小したり、ソースを捏造したりしません。

目录

• docs/ 工序文档
  • 01-输入处理（低质输入协议：差图＝认曲线索）
  • 02-源获取工序（数字源＋平台矩阵＋各站边界）
  • 03-引擎链（SMT／oemer 现状与目标）
  • 04-质量体系（四道自动关＋人工关＋拒收线＋分级承诺）
  • 05-交付标准
  • 06-评测口径（四级度量＋报告卡＋域内泛化分栏）
  • 07-已知局限（手写不做／低清拒收／符号层天花板）
  • 08-数字源验证教程（verify 三件套逐步命令）
  • 09-环境兼容矩阵（三平台实测）
  • 10-能力状态（各线：已验证／在办）
  • 11-出谱平替评估（MuseScore 4 第一轮实测）
  • 12-故障排查（常见坑速查；先跑 xiange doctor）
  • 13-复现挑战（公开基准样例包复现指引）
  • 引擎版本表（版本／权重／产物形态／验证日期／已知失败模式）
  • 册-五线谱／册-简谱（按谱种的工序卡）
• tools/ 工具脚本（四列：工具｜用途｜依赖档｜备注）

工具	用途	依赖档	备注
notation_check.py	记谱规范检器（符杠／符干／休止／谱表）	零依赖
yuchi_score_check.py	谱面规范查对（小节对账／附点／连音线／变音记号；只诊断）	零依赖	与记谱体检分工见 docstring
notation_fix.py	记谱规范后处理（幂等）	零依赖
omr_eval.py	统一评价引擎（四级度量＋标准报告卡）	核心	口径见 docs/06
theory_check.py	乐理错检器（声部交叉／平行五八度／跨度／密度／时值）	核心	跨度上限可调
score_doctor.py	谱面体检与修整（inspect／fix）	核心	fix 自带 .orig 备份
triage.py	待裁闭环（发现环＋机械裁＋三色报）	核心
verify.py	数字源验证三件套	核心	教程见 docs/08
verify_vs_audio.py	机器与谱面音频对拍	核心	下界指标
consensus.py	多引擎共识融合	核心
consensus2.py	共识 v2（质量加权＋闸门分流）	核心
consensus2_note.py	音符级对比试算	核心
remeasure.py	一键重测（机器×手工一致度）	核心
music_check.py	知识库定时质检	核心
vv_render.py	交付主链：MusicXML 到 SVG／PNG／PDF	渲染	A4 版式与批量
render_v4.py	v4 渲染（自查对照用）	渲染
bekern_fix.py	kern 语系骨架归一渲染	渲染
deliver_dolce.py	简谱腿：MusicXML 到简谱 PDF／PNG＋123 文本	浏览器	单声部
export_pack.py	成品导出层：MusicXML 到整包（八件＋试听件）	核心＋渲染＋浏览器	字体 OFL 闸／可容忍模式
工具_谱种路由.py	谱种路由入口（先判谱种再进链）	输入路由
bili_extract.py	B站提页（翻页式谱视频提取谱页）	输入路由
树转换器_v3.py	古琴减字树转换（数据加工；需 GUQINMM_BASE／AUTODAPU_CSV）	—	训练类
驱动_甲路_训练.py	古琴自训驱动（需 JIALU_SELF）	—	训练类
复测_四页分类隔离.py	分类层隔离复测（需 JIALU_SELF／JIALU_GEN 与 --pages）	—	评估件
engine_runner.py	统一引擎入口（图入 MusicXML 出；run.json 留痕）	零依赖（引擎另装）	引擎面
gen_bench.py	基准样例生成（合成谱例十一首）	核心
bench_run.py	基准样例跑批（过三检器出对照；防退化闸）	核心
xiange.py	统一 CLI 壳（route／check／fix／export／doctor／selfcheck）	零依赖	入口件
doc_check.py	文档与实况对账（防数字漂移，CI 挂载）	零依赖
kb_todo_scan.py	知识库待办核销扫描（[?] 台账工具化）	零依赖
m21_cache.py	music21 解析缓存层（单流程只解析一次）	核心	库件
工具_移调.py	MusicXML 整体移调（任意调）	零依赖	移宫线
工具_定调.py	歌者音域到建议调与推荐命令	零依赖	移宫线
工具_骨架表.py	设计数据到一页缩谱（骨架表）	零依赖	云韶线
工具_张力账.py	分段三量表（织体密度／音区重心／和声张力）	零依赖	云韶线

• 自测：tools/tests/ 二十一套（原六套：test_omr_eval 五场景、test_theory_check 十一病例、test_score_doctor 重叠判据与 fix 安全网、test_triage、test_same_name_parts 同名声部防塌陷、test_notation 记谱两件最小闭环与幂等；新增十二套：test_integration 六小节端到端过三检器、test_bekern_fix 归一化、test_remeasure 分桶与滤除、test_verify 度量与冒烟、test_deliver_dolce 依赖守卫与 CLI 契约、test_export_pack 出包契约与坏源 fail-closed、test_yuchi_score_check 谱面规范查对五场景与误报边界、test_engine_runner 引擎壳契约与双适配器冒烟、test_xiange 统一壳契约、test_consensus 共识三模式判读与缺文件契约、test_vv_render 渲染腿契约与 CJK 修复、test_spec_route 谱种路由契约与合成图判读；续增三套：test_verify_vs_audio 音高类一致度函数件与 CLI 契约、test_music_check 知识库质检 rc 口径与环境口、test_bili_extract 谱视频提页缺件降级与合成跑通），随时可复跑验证判据；另有过闸轻量静态查（ruff E9,F）
• examples/bench/ 公开基准样例包（十一首合成谱例＋清单＋定版预期；跑批 python3 tools/bench_run.py）。样例全部自造，验「流程可复现」，不承诺准确率数字
• SKILL.md 技能入口（给 AI 装包的总说明；两条能力线分流）
• xiange-mcp/ MCP 服务发布面（v0.2.0：识谱／光学识谱／音频转谱／音轨分离／乐理校验／记谱规范／格式互转移调／渲染出图，npm 包 xiange-mcp）
• CHANGELOG.md 更新日志（版本制度与版本史）
• CONTRIBUTING.md 贡献指南（含版权审查节）
• ROADMAP.md 路线图（六域排期与里程碑）
• NOTICE 权利与许可声明（五档许可记录＋接管条款）
• 知识/ 音乐知识底座（十域十六份约十万字：乐理记谱／和声／曲式／复调／配器／编配即兴／风格体系／世界音乐／音乐史／音乐教育，＋问答协议与动态档；入口见 知识/_总纲.md）。更新机制：按批修订升版（版本史见 CHANGELOG）；缺口走 issue（域／描述／来源）；最后核验 2026-10-13；时效类与开放项按巡检制定期复核（下轮巡检 2026 年 11 月上旬）

现状（2026-10-12）

已验证：

• 数字源路：钢琴编配项目全曲 1175 音符〔MIDI 发声数〕全数到谱（分布相似 0.987、零偏移对齐、抽核吻合）
• B站链：歌名 → 搜索 → 视频下载 → 19 页全曲提谱（免登录、全自动）
• 引擎链（无数字源转谱）：多引擎共识链打通（SMT／homr／Audiveris 三路互补，docs/03），全谱集批量实测落定
• 质量闸门：旧错误逐类对账、拦截机制上线（docs/04）；废品件被自检拦下并量化

在办（边界如实）：

• 符号层回填、Dorico 精排：按 docs/05 工序执行，自动化程度逐件推进
• 谱种线扩展：简谱／六线谱／工尺／古琴等分册在册，覆盖逐线扩展
• 维护节奏：按批推进，批内逐件销账；问题件走 issue 随批处理（本页核验日 2026-10-13）
• 能力状态一览：docs/10-能力状态.md（各线：已验证／在办，随批刷新）

边界与合规

• 数字源不随包分发（版权）；本包只给"找、验、合"的手艺
• 乐谱版权：本包仅处理用户合法持有的乐谱（自有、正版、公有领域或已获授权）；输入来源的合法性由用户自负其责；本包不提供受版权保护谱面的下载或分发
• 零出机原则；付费工具自动切平替