Music Workshop

音乐文件智能整理工具 - 通过元数据匹配、去重、自动入库，将散乱的音乐文件整理成规范的媒体库。

功能特性

• 🎵 元数据匹配：支持 AcoustID、MusicBrainz、网易云、QQ 音乐、Spotify 等多源匹配
• 🔧 缺失元数据补全：可视化编辑 title/artist/album_artist，实时预览入库路径
• 🗑️ 智能去重：基于音频指纹和元数据的重复检测，支持保留/替换/重命名策略
• 📂 自动整理入库：按 Artist/Album/Track - Title.ext 规范路径组织文件
• 🖥️ Web UI：React + Tailwind CSS，提供异常队列处理和批量操作界面
• 📊 任务跟踪：实时 WebSocket 推送，查看任务执行进度和日志

技术栈

层级	技术
前端	React 18, Vite, Tailwind CSS, Lucide Icons
后端	Python 3.11+, FastAPI, SQLite, Mutagen
匹配引擎	AcoustID, MusicBrainz, 网易云 API, QQ 音乐 API, Spotify API
音频处理	FFmpeg, Chromaprint (音频指纹)

项目结构

MusicWorkshop/
├── backend/               # FastAPI 后端服务
│   ├── app/
│   │   ├── services/      # 拆分后的服务模块（预览/执行/编排）
│   │   ├── exception_service.py
│   │   ├── matcher.py
│   │   ├── preprocessor.py
│   │   ├── repair_runner.py
│   │   └── ...
│   ├── tests/             # 单元测试
│   └── pyproject.toml     # ruff/black 配置
├── frontend/              # React 前端应用
│   ├── src/
│   │   ├── api/           # API 调用封装
│   │   ├── components/    # 可复用组件
│   │   └── pages/         # 页面组件
│   ├── .eslintrc.json     # ESLint 配置
│   ├── .prettierrc        # Prettier 配置
│   └── package.json
├── scripts/               # 辅助脚本
├── .pre-commit-config.yaml # Git hooks 配置
└── README.md

快速开始

环境要求

• Node.js 18+
• Python 3.11+
• FFmpeg (用于音频处理)
• Chromaprint (用于音频指纹)

安装依赖

# 后端
cd backend
pip install -r requirements.txt

# 前端
cd frontend
npm install

配置

1. 复制 backend/.env.example 为 backend/.env
2. 填写 API 密钥（AcoustID、MusicBrainz、网易云等）
3. 设置输入/输出目录路径

启动服务

# 后端 (开发模式)
cd backend
uvicorn app.main:app --reload --port 8000

# 前端 (开发模式)
cd frontend
npm run dev

访问 http://localhost:5173 打开 Web UI。

代码规范

本项目使用以下工具保证代码质量：

前端

cd frontend
npm run lint        # 检查代码规范
npm run lint:fix    # 自动修复
npm run format      # 格式化代码

后端

cd backend
ruff check .        # 检查代码规范
black .             # 格式化代码

Git Hooks (pre-commit)

pre-commit install  # 安装 Git hooks
pre-commit run --all-files  # 手动运行所有检查

API 文档

启动后端服务后访问 http://localhost:8000/docs 查看自动生成的 OpenAPI 文档。

测试

# 后端单元测试
cd backend
pytest

# 前端 (待补充)
cd frontend
npm test

许可证

MIT

贡献指南

欢迎提交 Issue 和 Pull Request。请确保代码通过 lint 检查和单元测试。

---

🤖 Generated with Claude Code