DeepMusic is redefining how humans learn music, create music, and perform music.

DeepMusic 是 AI 驱动的音乐学习助手，Phase 1 聚焦钢琴学习。通过蓝牙 MIDI 数字钢琴连接，提供实时乐谱跟随、练习评估和智能曲谱库。

• 🎹 MIDI 连接 — 蓝牙 BLE + USB OTG 双连接方式，自动扫描，统一事件流
• 📖 智能乐谱跟随 — 实时跟踪弹奏位置，自动翻页
• 🎯 练习评估 — 音准 + 节奏多维评分（S/A/B/C/D/F）
• 🔁 区间循环练习 — 选择任意小节区间，反复循环练习难点段落
• ▶️ 自动播放 — 乐谱库自动播放试听，支持变速控制
• 🎼 曲谱库 — 30 首无版权曲谱，分类筛选
• 👤 用户系统 — 注册/登录、练习历史、收藏

cd server
npm install
cp .env.example .env
npm run db:generate && npm run db:migrate && npm run db:seed
npm run scores:import
npm run dev
# → http://localhost:3000/health

cd mobile
flutter pub get
flutter run

详细配置参见 SETUP.md。

deepmusic/
├── docs/                  # 设计文档
│   ├── PRD.md             # 产品需求
│   ├── ARCHITECTURE.md    # 技术架构
│   ├── ROADMAP.md         # 开发路线图
│   └── SETUP.md           # 环境配置
├── mobile/                # Flutter 移动端
│   └── lib/
│       ├── core/          # 基础设施 (主题/路由/常量)
│       ├── features/      # 功能模块 (home/midi/score/practice/profile)
│       ├── shared/        # 共享组件
│       └── data/          # 数据层 (仓库/数据源/模型)
├── server/                # Express 后端
│   ├── src/
│   │   ├── routes/        # API 路由 (auth/scores/practice/devices)
│   │   ├── services/      # 业务逻辑
│   │   └── middleware/    # 中间件 (验证/错误/404)
│   └── prisma/            # 数据模型 + 迁移

设计文档

• 产品需求文档 (PRD)
• 技术架构设计
• 开发路线图
• 环境配置文档

后端 API (26 个端点，全部测试通过)

• Auth: register / login / logout / me(GET) / me(PATCH)
• Scores: list / recommended / search / detail / upload / update / publish / delete / xml / favorite / unfavorite
• Practice: start / note / end / create / list / stats / detail / delete
• Devices: list / register / update / delete / connect
• User: profile(GET) / profile(PUT) / favorites / statistics
• Health check
• JWT 认证 + Token 黑名单 (登出失效)
• 文件上传 (Multer) + MusicXML 文件下载
• 收藏/取消收藏 (User-Score 多对多)
• 练习会话持久化 (Prisma PracticeSession, 事务化操作, 替代内存 Map)
• Prisma 数据模型 (Score/User/PracticeRecord/PracticeSession/Tag/Device) + 迁移
• 19 首乐谱种子数据导入

移动端核心模块

• Flutter 项目结构 + feature-based 组织
• AutoPlayer 自动播放引擎 (MIDI 事件调度 + 变速 + OSMD 跟随)
• Riverpod 状态管理 + 路由配置
• Dart 数据模型 (Score/Part/Measure/Note/TimeSignature/KeySignature)
• MusicXML 解析器 (score-partwise + timewise，含 divisions/和弦/休止符/变拍号)
• OSMD 乐谱渲染器 (WebView + JS Bridge 双向通信)
• ScoreFollower 乐谱跟随引擎 (和弦组匹配/容错跳过/自动翻页/手动翻页/区间循环)
• NoteEvaluator 音符评估器 (音准+节奏双维度评分)
• MidiService MIDI 服务 (BLE + USB 双连接, USB OTG 底层, BLE 断线自动重连)
• API Client (Dio + Token 管理)
• Auth Repository (register/login/logout/token 持久化)
• Score Repository (列表/搜索/详情/下载/收藏)
• Practice Repository (start→note→end 完整流程封装)
• SplashPage (登录状态检查, 自动路由)

前端页面

• AuthPage — 登录/注册 (表单验证, 模式切换, 跳过登录)
• HomePage — 设备连接卡片/快速开始/底部导航
• ScoreLibraryPage — 乐谱库浏览 (分类/搜索/筛选)
• ScoreViewPage — 乐谱详情 + OSMD 渲染 + 自动播放试听 (变速 0.5x-2.0x) + 收藏
• PracticePage — 练习界面 (OSMD 渲染 + 高亮跟随 + 手动翻页 + 区间循环练习 + 和弦显示/报告)
• PracticeHistoryPage — 练习历史 (分页/下拉刷新/左滑删除/详情)
• StatisticsPage — 学习统计 (累计时长/等级分布/最佳成绩)
• DeviceListPage — MIDI 设备扫描连接 (USB/BLE 分组展示, 热插拔检测)
• ProfilePage — 个人页面 (用户信息/统计/菜单/登出)

• 蓝牙 MIDI + USB MIDI 真机调试 (需 Yamaha P125 + Android 设备)
• 端到端集成测试
• 个人资料编辑 (F7.2)

• 离线乐谱缓存 (Hive 本地存储)
• 横屏/竖屏适配 (Practice/ScoreView/ScoreLibrary/Home 自适应布局)
• 暗色模式
• ScoreFollower 力度/表情评估 (Phase 2)
• App 发布 (Google Play / App Store)

• PRD — 产品需求文档
• ARCHITECTURE — 技术架构
• ROADMAP — 开发路线图
• SETUP — 环境配置

项目启动: 2026-03-15 | 最近更新: 2026-03-20 20:47