# Audio2Sheet **Repository Path**: liuchangng/audio2-sheet ## Basic Information - **Project Name**: Audio2Sheet - **Description**: 一句话：把任何音频（本地文件或 YouTube 链接）转成 MIDI + 五线谱，支持 35 种乐器、多模型对比、分轨播放。 - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-08-18 - **Last Updated**: 2026-09-10 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # 音频转乐谱工具 **定位**：本地离线优先的音频→MIDI→钢琴卷帘+五线谱 Web 工具 **目标用户**：音乐人、编曲爱好者、音乐学习者、AI 研究者 **设计理念**：**Less is More · 暗色 Studio 美学 · 离线优先** --- ## 功能概览 ``` 音频文件 (MP3/WAV/FLAC/OGG/M4A) │ ▼ FFmpeg 格式统一（16kHz 单声道） │ ▼ MuScriptor GPU 推理（small/medium/large 自动适配） │ ▼ MIDI 文件 ├──▶ 钢琴卷帘（静态 PNG / Canvas 动画播放，可切换） ├──▶ 五线谱生成（分轨 PNG， MuseScore CLI 渲染） ├──▶ 逐轨隔离播放 + 全曲混合音轨 ├──▶ 和弦/调性时间轴分析 └──▶ 三模型差异对比模式（重合度矩阵 + 分歧区段） ``` --- ## 技术架构 ### 前后端分离 ``` ┌─────────────────────────┐ REST + JSON ┌──────────────────────────┐ │ web/ (Vue 3 SPA) │ ──────────────────────▶ │ server/ (FastAPI) │ │ ├ TopBar │ │ ├ api/ (路由) │ │ ├ Library（左·持久库） │ ◀──── PNG/JSON/WAV ───── │ ├ core/ (引擎) │ │ ├ TranscribePanel │ │ └ services/ (jobs,scan) │ │ └ AnalyzePanel（分析） │ └──────────────┬───────────┘ └─────────────────────────┘ │ 调用 models/*.safetensors │ ffmpeg / MuseScore4 ▼ output/*.mid + 产物 ``` | 层级 | 选型 | 说明 | |---|---|---| | 后端 | **FastAPI + Uvicorn**，Python 3.12，uv 管理依赖 | 异步任务、自动 OpenAPI、WebSocket 进度 | | 核心引擎 | torch + muscriptor + pretty_midi + symusic + pypianoroll + music21 + matplotlib | 推理与可视化 | | 前端 | **Vue 3 + Vite + TypeScript + Pinia**（手写暗色 Studio 组件） | 中文 UI，响应式布局 | | 主题 | 暗色 Studio（底 `#0d0f17`→`#161a26`→`#1e2330`，主色琥珀 `#f0a830`，辅色青 `#4fd1e0`） | 沿历史视觉契约 | --- ## 目录结构 ``` Audio2Sheet/ ├── server/ # 后端 │ ├── pyproject.toml # uv 依赖管理 │ ├── server/ │ │ ├── main.py # FastAPI 应用工厂（CORS + 路由 + 静态文件挂载） │ │ ├── config.py # 路径配置（OUTPUT_DIR / MODELS_DIR / FFMPEG / MUSESCORE） │ │ ├── api/ │ │ │ ├── models.py # GET /api/models, POST /api/models/{size}/download │ │ │ ├── transcribe.py # POST /api/transcribe, GET /api/jobs/{id} │ │ │ ├── library.py # GET /api/library, GET /api/library/{id}, DELETE │ │ │ └── analysis.py # roll / roll-data / harmony / score / player / compare │ │ └── core/ │ │ ├── model_manager.py # CUDA 检测 + 模型下载（断点续传） │ │ ├── converter.py # FFmpeg → 16k 单声道 WAV │ │ ├── transcriber.py # MuScriptor 推理封装（异步） │ │ ├── constants.py # 35 个合法乐器名 + 中文标签映射 │ │ ├── visualizer.py # pypianoroll 卷帘 → PNG │ │ ├── roll_data.py # 音符数据提取（Canvas 动画用） │ │ ├── player_engine.py # MIDI → 分轨 WAV + 混合音轨 │ │ ├── score_writer.py # MuseScore CLI → PDF │ │ ├── harmony.py # music21 和弦/调性分析 │ │ └── compare.py # 音符级重合度矩阵 + 分歧区段 │ └── tests/ ├── web/ # 前端（Vue 3） │ ├── package.json / vite.config.ts │ └── src/ │ ├── api/client.ts # fetch 封装 + 类型定义 │ ├── constants/instruments.ts # 乐器常量 + 中文标签 │ ├── stores/ # Pinia 状态管理 │ └── components/ │ ├── TopBar.vue │ ├── Library.vue # 左·持久结果库 │ ├── TranscribePanel.vue # 右·转录流程 │ ├── AnalyzePanel.vue # 右·分析 Tab 容器 │ ├── Stepper.vue # 步骤指示器 │ └── views/ │ ├── RollView.vue # 钢琴卷帘（静态 PNG + Canvas 动画） │ ├── ScoreView.vue # 五线谱分轨 │ ├── PlayerView.vue # 逐轨隔离播放 │ ├── HarmonyView.vue # 和弦/调性时间轴 │ └── CompareView.vue # 三模型对比 ├── models/ # 模型权重（medium 已就绪） ├── output/ # 转录产物（运行期生成） └── README.md # 本文件 ``` --- ## API 接口 | 方法 | 路径 | 说明 | |---|---|---| | GET | `/api/health` | 健康检查 | | GET | `/api/models` | 查询模型状态（small/medium/large + CUDA 信息） | | POST | `/api/models/{size}/download` | 下载指定尺寸模型 | | POST | `/api/transcribe` | 上传音频，触发转录（返回 `{job_id}`） | | GET | `/api/jobs/{job_id}` | 轮询转录进度 | | GET | `/api/library` | 列出所有转录结果（含中文乐器名） | | GET | `/api/library/{id}` | 获取单个结果详情 | | DELETE | `/api/library/{id}` | 删除结果 | | POST | `/api/analyze/roll` | 生成钢琴卷帘 PNG | | POST | `/api/analyze/roll-data` | 提取音符数据（用于 Canvas 动画） | | POST | `/api/analyze/harmony` | 和弦/调性分析 | | POST | `/api/analyze/score` | 五线谱生成（返回 `{urls, tracks:[{name,url}]}`） | | POST | `/api/analyze/player` | 分轨/混合音轨合成（返回 `mix_url` + 分轨列表） | | POST | `/api/analyze/compare` | 多结果对比（返回 `{matrix, labels, divergent}`） | --- ## 快速开始 ### 前置条件 - Python 3.12+ - **uv**（[安装](https://docs.astral.sh/uv/getting-started/installation/)） - FFmpeg（已装于系统） - MuseScore 4（可选，用于五线谱） - NVIDIA GPU（推荐，CUDA 12.x 兼容 13.3 驱动） ### 1. 启动后端 ```bash cd server uv sync # 首次安装依赖 uv run python -m uvicorn server.main:app --host 0.0.0.0 --port 8000 ``` ### 2. 构建前端 ```bash cd web npm install # 首次安装依赖 npm run build # 生产构建 ``` > 前端产物由后端 `/` 路径静态托管（`app.mount("/", StaticFiles(...))`）。 ### 3. 访问应用 ``` http://localhost:8000 ``` --- ## 功能实现状态 | 模块 | 状态 | 备注 | |---|---|---| | 模型管理 | ✅ 已完成 | CUDA 自动检测、medium 模型就绪 | | 音频格式转换 | ✅ 已完成 | FFmpeg → 16kHz 单声道 WAV | | 转录引擎 | ✅ 已完成 | MuScriptor GPU 推理，异步任务 | | 钢琴卷帘（静态） | ✅ 已完成 | pypianoroll → PNG | | 钢琴卷帘（动画） | ✅ 已完成 | Canvas 实时绘制 + `