⚠️ 免责声明本项目仅用于学习交流使用，请勿在任何公开平台宣传该项目。
本项目不提供任何音乐内容的存储、分发或传播服务。用户使用本项目搜索、下载或整理的音乐资源，均来自用户自行配置的资源站点。开发者不对资源的版权合法性、内容质量或安全性负责。
用户使用本项目所产生的一切后果由用户自行承担，包括但不限于：
- 因下载或传播受版权保护的音乐内容而导致的法律纠纷
- 因使用资源站点而导致的账号封禁或其他后果
- 因使用本项目而产生的任何直接或间接损失
开发者不承担任何责任，亦不对用户的行为进行监控或干预。
请用户自觉遵守相关法律法规和版权规定，尊重知识产权。
MusicPilot 的诞生源于一个大胆的想法：能否让 AI 完全自主开发一个实用的音乐库管理工具？
经过深入分析 MoviePilot 的架构和代码，参考其 Chain + Module + Plugin 三层架构模式，MusicPilot 应运而生。
我们的目标：
- 🎯 聚焦核心需求：资源搜索、自动下载、元数据刮削
- 🚀 自动化优先：从搜索到下载到整理，全程自动化
- 🔌 扩展性强：插件系统支持第三方扩展
- 🎨 界面友好：基于 Vue 3 + Naive UI 的现代化界面
痛点 1：音乐资源分散，搜索困难
- 不同的资源站点有不同的搜索接口
- 每个站点需要手动登录、搜索、下载
- 下载后还需要手动整理文件和刮削元数据
痛点 2：音乐库管理繁琐
- 音乐文件散落在多个目录
- 元数据不完整，封面缺失
- 需要手动整理和刮削，耗时耗力
痛点 3：自动化的需求
- 订阅的艺术家发布了新专辑，希望能自动下载
- 下载后的文件能自动整理到正确的目录
- 元数据能自动刮削和补全
- 多站点支持：支持管理多个音乐资源站点
- 站点配置：站点地址、Cookie/Passkey、User-Agent、代理等
- 站点测试：一键测试站点连接状态
- 优先级设置：设置站点搜索优先级
- 关键词搜索：支持艺术家、专辑、曲目关键词搜索
- 高级过滤：大小、格式、编码、免费状态等过滤
- 站点范围：可在所有站点或指定站点搜索
- 搜索结果：显示站点、标题、大小、做种/下载、发布时间、免费状态、HR 等信息
- 一键下载：点击即可下载种子文件
- 下载器集成：支持推送到 qBittorrent / Transmission
- 下载管理：显示下载进度，支持暂停/恢复/重试
- 下载历史：记录所有下载历史
- 文件识别：自动识别下载的文件（艺术家/专辑/曲目）
- 元数据刮削：自动查询 MusicBrainz 获取元数据
- 文件整理：按规则整理文件（Artist/Album/Track.flac）
- 标签写入：自动写入元数据标签（ID3v2/Vorbis）
- 封面下载：自动下载专辑封面图片
- 数据库更新：自动更新数据库记录
- 浏览音乐库：按艺术家、专辑、曲目浏览
- 搜索功能：快速搜索音乐
- Web 播放器：基于 Howler.js 的在线播放器
- 播放列表：创建和管理播放列表
| 技术 | 版本 | 说明 |
|---|---|---|
| Web 框架 | FastAPI 0.115+ | 现代异步 Web 框架，自动生成 API 文档 |
| ORM | SQLAlchemy 2.0+ | Python 最流行的 ORM，支持异步 |
| 数据库 | SQLite / PostgreSQL | 开发用 SQLite，生产用 PostgreSQL |
| 任务调度 | APScheduler 3.10+ | Python 任务调度库 |
| 配置管理 | Pydantic Settings 2.0+ | 类型安全的配置管理 |
| 音频处理 | mutagen 1.47+ | 强大的音频元数据处理库 |
| Python | 3.12+ | 最新 Python 版本 |
| 技术 | 版本 | 说明 |
|---|---|---|
| 框架 | Vue 3.4+ | 渐进式 JavaScript 框架 |
| 构建工具 | Vite 5.0+ | 下一代前端构建工具 |
| UI 组件 | Naive UI 2.38+ | Vue 3 组件库，设计精美 |
| 状态管理 | Pinia 2.1+ | Vue 官方推荐的状态管理 |
| 路由 | Vue Router 4.2+ | Vue 官方路由 |
| HTTP 客户端 | Axios 1.6+ | Promise based HTTP 客户端 |
| 音频播放 | Howler.js 2.15+ | 强大的 HTML5 音频播放库 |
| Node | 20.12.1+ | Node.js 最新 LTS 版本 |
┌─────────────────────────────────────────────────────────────┐
│ 前端 (Vue 3) │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ 资源站点 │ │ 搜索 │ │ 音乐库 │ │ 播放器 │ │
│ │ 管理 │ │ 资源 │ │ 浏览 │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└────────────────────┬────────────────────────────────────┘
│ RESTful API
┌────────────────────▼────────────────────────────────────┐
│ FastAPI 后端 │
├────────────────────────────────────────────────────────────┤
│ ┌──────────────────────────────────────────┐ │
│ │ API 层 │ │
│ └──────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────▼──────────────────┐ │
│ │ Chain 层 │ │
│ │ TorrentsChain | TorrentsChain │ │
│ │ MetadataChain | TransferChain │ │
│ │ PlaylistChain | PlaybackChain │ │
│ └──────────────────────────────────────────┘ │
│ │ │
│ ┌────────────────────────▼──────────────────┐ │
│ │ Module Manager │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │MusicBrainz││ 资源站点 ││ 下载器 │ ... │ │
│ │ │ 模块 ││ 模块 ││ 模块 │ │ │
│ └──────────────────────────────────────────┘ │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ 数据层 (SQLAlchemy) │
│ ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐ │
│ │ Artist │ │ Album │ │ Track │ │Playlist│ │
│ │ 模型 │ │ 模型 │ │ 模型 │ │ 模型 │ │
│ └────────┘ └────────┘ └────────┘ └────────┘ │
└────────────────────┬────────────────────────────────────┘
│
┌────────────────────▼────────────────────────────────────┐
│ SQLite (开发) / PostgreSQL (生产) │
└───────────────────────────────────────────────────────────┘
外部集成：
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐
│ 资源站点 ││MusicBrainz││ qBittorrent││Transmission│
│ API ││ API ││ API ││ API │
└──────────┘ └──────────┘ └──────────┘ └──────────┘
- Python 3.12+
- Node.js 20.12.1+
- Git
# 克隆项目
git clone https://github.com/hhyo/MusicPilot.git
cd MusicPilot
# 后端
cd backend
pip install -r requirements.txt
python -m app.main
# 前端（另开终端）
cd frontend
npm install
npm run dev
# 访问
# 前端：http://localhost:5173
# 后端 API：http://localhost:3001/docs# 启动所有服务
docker-compose up -d
# 访问
# 前端：http://localhost:3000
# 后端 API：http://localhost:3001- ✅ 支持管理多个音乐资源站点
- ✅ 站点配置：地址、Cookie/Passkey、User-Agent、代理
- ✅ 站点测试：一键测试连接状态
- ✅ 优先级设置：自定义搜索优先级
- ✅ 关键词搜索：艺术家、专辑、曲目
- ✅ 高级过滤：大小、格式、编码、免费状态
- ✅ 站点范围：所有站点或指定站点
- ✅ 搜索结果：详细信息展示
- ✅ 一键下载种子文件
- ✅ 下载器集成：qBittorrent / Transmission
- ✅ 下载管理：进度、暂停、恢复、重试
- ✅ 下载历史记录
- ✅ 文件识别：自动识别艺术家/专辑/曲目
- ✅ 元数据刮削：MusicBrainz API
- ✅ 文件整理：按规则整理文件
- ✅ 标签写入：ID3v2/Vorbis
- ✅ 封面下载：自动下载封面
- ✅ 数据库更新
- ✅ 浏览音乐库：艺术家、专辑、曲目
- ✅ 搜索功能：快速搜索
- ✅ Web 播放器：在线播放
- ✅ 播放列表：创建和管理播放列表
| 里程碑 | 版本 | 周期 | 目标 | 状态 |
|---|---|---|---|---|
| M1 | v0.1.0 | Week 1-2 | 元数据链 | ✅ 已完成 |
| M2 | v0.2.0 | Week 3-4 | 播放列表 | ✅ 已完成 |
| M3 | v0.3.0 | Week 5-6 | 媒体库管理 | ✅ 已完成 |
| M4 | v0.4.0 | Week 7-8 | 资源站点和下载器对接 | ✅ 已完成 |
| M5 | v0.5.0 | Week 9-10 | 订阅功能 | ✅ 已完成 |
| M6 | v0.6.0 | Week 11-12 | 播放器界面 | ✅ 已完成 |
| M7 | - | Week 13 | CI/CD 修复 | ✅ 已完成 |
| M8 | - | Week 14 | 代码与架构审查 | ⏸️ 待开始 |
| M9 | - | Week 15-16 | 测试覆盖提升 | ⏸️ 待开始 |
| M10 | - | Week 17 | 产品验收 | ⏸️ 待开始 |
| M11 | v1.0.0 | Week 18 | 发布准备 | ⏸️ 待开始 |
| M12 | v1.1.0 | Week 19-20 | 插件系统完善 | ⏸️ 待开始 |
详细任务拆解：详见 任务清单
- 项目准则：GUIDELINES.md
- 需求分析：requirements.md
- 技术设计：tech-design.md
- 研发流程：flow.md
欢迎贡献！请查看 贡献指南。
MIT License
本项目深受以下项目启发：
- MoviePilot - 架构参考
- MusicBrainz - 元数据来源
- FastAPI - 后端框架
- Vue 3 - 前端框架
- Naive UI - UI 组件库
⭐ 如果这个项目对您有帮助，请给一个 Star！