SparrowLib（斯派若）是一个优先面向 macOS、同时支持 Linux 和 Windows 的本地音乐播放器。第一版只处理本地音频、歌词和封面， 不登录、不推送、不联网，重点是稳定播放、清晰的高密度曲库界面和个人可定制性。
- DEVELOPMENT.md：macOS 优先的环境搭建、架构调用链、测试和发布流程。
- SPEC.md：技术架构、数据模型、音频质量策略和实现约束。
- IMPLEMENTATION.md：一期实现边界、模块契约和完成标准。
- TODO.md：按里程碑维护的开发任务表。
本地文件 -> 曲库索引 -> 高密度列表 -> mpv 播放 -> 同名 LRC/封面
第一版不包含账号、推荐、广告、联网搜索、下载器、流媒体服务、音效和蓝牙 codec 诊断。联网的 yt-dlp 导入工具规划在后续阶段，并与播放器进程隔离。
- Python 3.12+
- PySide6 / Qt 6：桌面界面
- mpv 子进程与 JSON IPC：音频播放和播放状态
- Mutagen：标签与内嵌封面读取
- SQLite + FTS5：曲库索引和搜索
- Pillow：仅在需要时处理封面缩略图
- Python 标准库 LRC 解析器：优先读取音频旁边的同名
.lrc
播放器不自己实现 MP3/FLAC 解码器，也不添加均衡器、环绕声、杜比或其他 DSP。
conda activate sparrow
python -m pip install -e '.[dev]'
sparrow-lib应用直接读取用户配置的本地曲库，不联网、不上传音频；资源整理功能会在明确确认后移动本地文件。
在 macOS 上构建可双击启动的客户端：
python -m pip install -e '.[dev,macos]'
./packaging/build-macos.sh
open dist/macos/SparrowLib.app客户端需要独立安装 mpv（例如 brew install mpv），或通过 SPARROW_MPV_PATH 指定 mpv 路径。默认构建未签名，
分发给其他用户前应使用 Apple Developer 证书签名并完成 notarization。
yt-dlp 下载器作为独立 CLI 使用，文件先进入暂存目录，不会自动写入曲库：
python -m pip install -e '.[downloader]'
python scripts/download_library.py "artist song"
python scripts/download_library.py "video-url" --download "video-url"桌面客户端也可从 Tools → Download music… 打开下载窗口。搜索和下载在后台执行，默认暂存到
~/Music/SparrowLib Downloads；当前版本不会未经确认自动导入曲库。
开发优先在 macOS 进行，Linux 和 Windows 通过 GitHub Actions 构建和发布。运行时需要单独安装
mpv，也可以通过 SPARROW_MPV_PATH 指定 mpv 可执行文件路径。推送形如 v0.2.0 的 Git 标签后，
工作流会自动创建 GitHub Release，并上传 macOS、Windows、Linux 三个平台的客户端归档。
在 Fedora Linux 上构建 RPM：
./packaging/build-rpm.sh生成的 RPM 位于 dist/rpm/。
安装当前用户的 Fedora/Linux 桌面入口：
./packaging/install-desktop.sh运行 10,000 条合成曲库查询基准：
conda run -n sparrow python scripts/benchmark_library.py --count 10000