{"id":50850168,"url":"https://github.com/dylan121322/music-dl-android","last_synced_at":"2026-06-14T13:07:16.562Z","repository":{"id":361744537,"uuid":"1255640573","full_name":"dylan121322/music-dl-android","owner":"dylan121322","description":"Music DL Android 专版 — 原生 Java Material You UI + Chaquopy Python 运行时","archived":false,"fork":false,"pushed_at":"2026-06-01T04:37:00.000Z","size":225,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-01T05:15:05.999Z","etag":null,"topics":["android","chaquopy","flac","material-you","music-downloader","music-search","python","qq-music"],"latest_commit_sha":null,"homepage":"https://github.com/dylan121322/music-dl-android","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dylan121322.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-01T03:25:30.000Z","updated_at":"2026-06-01T04:37:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/dylan121322/music-dl-android","commit_stats":null,"previous_names":["dylan121322/music-dl-android"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/dylan121322/music-dl-android","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylan121322%2Fmusic-dl-android","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylan121322%2Fmusic-dl-android/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylan121322%2Fmusic-dl-android/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylan121322%2Fmusic-dl-android/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dylan121322","download_url":"https://codeload.github.com/dylan121322/music-dl-android/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dylan121322%2Fmusic-dl-android/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34322314,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-14T02:00:07.365Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["android","chaquopy","flac","material-you","music-downloader","music-search","python","qq-music"],"created_at":"2026-06-14T13:07:15.837Z","updated_at":"2026-06-14T13:07:16.557Z","avatar_url":"https://github.com/dylan121322.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Music DL\n\n多平台音乐下载工具 — 聚合搜索、歌单批量下载、多音源自动回退、AI 音源发现、网页搜索兜底。\n提供 Web GUI（FastAPI + 原生 JS）和 Android 原生 App（Java + Chaquopy）。\n\n## 下载\n\n| 平台 | 下载 |\n|------|------|\n| Android APK | [app-debug.apk](https://github.com/dylan121322/music-dl-android/releases/tag/v1.5.1) |\n| macOS (Apple Silicon) | [MusicDL-macOS-arm64.zip](https://github.com/dylan121322/music-dl/releases/latest) |\n| Windows (x64) | [MusicDL-Windows-x64.zip](https://github.com/dylan121322/music-dl/releases/latest) |\n\n\u003e 点开即用，无需安装 Python。解压后双击 `MusicDL` 即可。\n\u003e\n\u003e **macOS 用户**：若提示「无法验证是否包含恶意软件」，在终端执行以下命令后即可打开：\n\u003e\n\u003e ```bash\n\u003e xattr -dr com.apple.quarantine /path/to/MusicDL   # 将解压后的 MusicDL 文件夹拖入终端即可自动填入路径\n\u003e ```\n\n## 功能\n\n- **聚合搜索**：同时搜索 QQ音乐 + 网易云 + 酷狗 + GitHub，结果去重合并，显示来源标签\n- **Android 原生 App**：Material You 风格，AMOLED 纯黑 + 紫色点缀，大卡片 + 来源色条\n- **内置播放器**：Native MediaPlayer，音频焦点管理，拔出耳机自动暂停\n- **下载源选择**：自动 / QQ / 网易云 / 酷狗 / GitHub / 网页搜索\n- **多引擎网页搜索**：Bing + DuckDuckGo 并行搜索，AI 智能排序候选页面\n- **三层下载回退**：主音源 → 备选音源（精确歌名优先）→ 网页搜索（AI 辅助）\n- **AI 音源发现**：支持 DeepSeek / OpenAI / Claude，自动搜索 + 分析网页 + 注册新音源\n- **LX Music 兼容**：支持导入洛雪音乐 JS 音源（纯 Python 解析，无需 Node.js）\n- **FLAC 无损**：QQ音乐/网易云/酷狗均支持 FLAC 音质（需登录）\n- **链接下载**：粘贴任意音乐链接，规则 + AI 两级提取音频 URL，自动下载\n- **运行时日志**：自动轮转日志文件（5MB×3），JSON/TXT 导出 API\n- 多平台登录：QQ 音乐 / 网易云 / 酷狗（标签切换，独立 Cookie）\n- Chrome CDP 一键自动提取 Cookie（含 HttpOnly）\n- 未登录自动回退到免费音源，不卡等待\n- 暂停/恢复登录（调试用）\n\n---\n\n## LX Music 音源兼容\n\n支持导入洛雪音乐的 JS 音源文件，纯 Python 解析，无需 Node.js。\n\n**使用方式**：\n1. 将 `.js` 音源文件放入 `~/.config/music-dl/lx_sources/` 目录\n2. 重启应用，音源自动加载并加入搜索和下载回退链\n3. 或点击侧边栏「导入 LX 音源」手动加载\n\n## 安装\n\n### 桌面端 (macOS / Windows / Linux)\n\n```bash\ncd music-dl\npip install -r requirements.txt\n# Chrome CDP Cookie 提取需要：\npip install websocket-client cryptography\n```\n\n### Android\n\n**方式 A: APK 直接安装**\n从 [Releases](https://github.com/dylan121322/music-dl/releases) 下载最新 APK，直接安装。\n\n**方式 B: 自行构建**\n```bash\ncd android\n# Windows: powershell -File build_full.ps1\n# macOS/Linux: bash build_apk.sh\n# 需要 Android SDK + JDK 17+ + Python 3.12\n```\n\n\u003e APK 使用 Chaquopy 嵌入 Python 运行时，原生 Java UI（Material You 设计），支持音频焦点管理、耳机拔出检测、StrictMode 调试。\n\n### 桌面端独立窗口（可选）\n\n```bash\npython launcher.py             # 内置 WebView 窗口，无需打开浏览器\n```\n\n## 快速开始\n\n### Web GUI（推荐）\n\n```bash\npython server.py\n# 打开 http://localhost:8765\n```\n\n1. 侧边栏 → **🔑 登录** → 选择平台（QQ/网易云/酷狗）\n2. **打开Chrome** → 在打开的页面微信/QQ扫码登录\n3. **提取Cookie** → 自动从 Chrome CDP 读取并保存\n4. 搜索歌曲 → 勾选 → 选择下载源 → **下载选中**\n\n### 下载源说明\n\n| 源 | 说明 |\n|------|------|\n| 自动 | 已登录优先 QQ，未登录自动回退免费源 |\n| QQ | 仅使用 QQ 音乐 |\n| 网易云 | 仅使用网易云音乐 |\n| 酷狗 | 仅使用酷狗音乐 |\n| 网页 | 跳过音乐平台，直搜 mp3 站 + AI 分析 |\n\n### AI 配置（网页搜索和音源发现需要）\n\n侧边栏 → 🤖 AI 发现音源：\n1. 选择模型（DeepSeek / OpenAI / Claude）\n2. 填入模型名称、API Key、Base URL\n3. 点击「保存 AI 配置」\n\n### CLI\n\n```bash\n# 登录\npython main.py login\n\n# 搜索\npython main.py search \"晴天\"\n\n# 歌单下载\npython main.py dl \"https://c6.y.qq.com/base/fcgi-bin/u?__=TOKEN\"\npython main.py dl \"https://y.qq.com/n/ryqq/playlist/123456.html\"\n\n# 设置\npython main.py config\npython main.py config --dir ~/Music\n```\n\n## 多平台登录\n\n侧边栏提供三个平台的登录标签：\n\n| 平台 | 登录方式 | Cookie 关键字段 | 登录后作用 |\n|------|---------|----------------|------------|\n| QQ 音乐 | 微信/QQ 扫码 | `qqmusic_key` / `qm_keyst` | VIP 歌曲 + 收藏下载 |\n| 网易云音乐 | 微信/QQ/手机扫码 | `MUSIC_U` | VIP 歌曲 + 320kbps |\n| 酷狗音乐 | 手机扫码 | 通用 | 备用音源下载 |\n\n\u003e CDP Cookie 提取对三个平台通用：打开对应网站 → 手动登录 → 点「提取Cookie」\n\n## 歌单链接格式\n\n| 格式 | 示例 |\n|------|------|\n| 短链接 | `c6.y.qq.com/base/fcgi-bin/u?__=...` |\n| 歌单页 | `y.qq.com/n/ryqq/playlist/123456.html` |\n| 分享页 | `i.y.qq.com/n2/m/share/details/taoge.html?id=...` |\n| 纯数字 | `9718789079` |\n\n## 音质选项\n\n| 选项 | 码率 | 格式 |\n|------|------|------|\n| `128kbps` | 128kbps | M4A |\n| `320kbps` | 320kbps | MP3 |\n| `flac` | 无损 | FLAC |\n\n## 项目结构\n\n```\nmusic-dl-android/\n├── server.py               # FastAPI App 组装 (69行)\n├── server_models.py        # Pydantic 请求/响应模型 + Android专有FavoritesRequest\n├── server_state.py         # 状态管理: get_api(Lock), lifespan(TTL清理)\n├── server_routes_config.py # 配置端点 (5个)\n├── server_routes_search.py # 多平台并行搜索+去重\n├── server_routes_download.py # 下载/播放/进度SSE (6端点)\n├── server_routes_auth.py   # CDP登录/源管理/日志 (10端点)\n├── server_routes_android.py # 🔒 Android 专有: stream代理/cache/favorites/debug\n├── android/                # Android App（Chaquopy Python-in-Android）\n│   ├── app/\n│   │   ├── build.gradle    # 构建配置 (versionCode 6, versionName 1.5.1)\n│   │   └── src/main/\n│   │       ├── java/com/musicdl/MainActivity.java  # 原生 Java UI\n│   │       ├── python/server_runner.py             # Python 进程管理\n│   │       └── res/                                # Material You 主题\n│   ├── build_apk.sh        # macOS/Linux 构建脚本\n│   └── build_full.ps1      # Windows 构建脚本\n├── tests/                  # 测试套件（pytest + httpx）\n│   ├── conftest.py         # 测试 fixtures\n│   ├── test_api.py         # API 端点测试\n│   ├── test_utils.py       # 工具函数测试\n│   ├── test_logger.py      # 日志引擎测试\n│   └── test_exporter.py    # 导出模块测试\n├── main.py                 # CLI 入口\n├── api.py                  # QQ 音乐 API + CDP HTML 歌单提取\n├── downloader.py           # 多线程下载引擎 + 3层回退\n├── models.py               # Song 数据模型\n├── utils.py                # 工具函数、Cookie 解析、g_tk 计算\n├── cdp_cookies.py          # Chrome CDP Cookie 提取（含 HttpOnly）\n└── sources/                # 多音源系统\n```\n\n## 双仓架构\n\n本仓库为 Android 专版，与[主线仓库](https://github.com/dylan121322/music-dl)共享核心代码，采用选择性同步。\n\n| 仓库 | 版本 | 说明 |\n|------|------|------|\n| [music-dl](https://github.com/dylan121322/music-dl) (主线) | v1.4.5 | 桌面端 Web GUI + CLI |\n| [music-dl-android](https://github.com/dylan121322/music-dl-android) (专版) | v1.5.1 | Android App + CDN代理/缓存 |\n\n**同步策略：** 绝不 merge，用 `git checkout upstream/main -- \u003cfiles\u003e` 选择性同步。\n\n**Android 专有模块 (`server_routes_android.py`):**\n\n| 端点 | 功能 | 安全措施 |\n|------|------|----------|\n| `/api/stream?url=` | CDN音频URL代理 | 域名白名单, 无Cookie转发 |\n| `/api/cache?url=` | CDN音频缓存 | 域名白名单 + Content-Type音频校验 |\n| `/api/favorites` | QQ音乐收藏 | 401未登录拦截 |\n| `/debug/play` | 音频格式调试 | — |\n\n## 下载回退链路\n\n```\n下载请求\n  ├─ ① QQ 音乐（主音源，VIP 需要登录）\n  │   └─ 下载 ✅ / 失败 ↓\n  ├─ ② 已知音源（网易云、酷狗、模板源、AI发现源）\n  │   └─ 下载 ✅ / 失败 ↓\n  └─ ③ 针对性网络搜索\n      ├─ Bing 搜索 \"{歌名} {歌手} mp3\"\n      ├─ 逐个打开结果页面\n      ├─ 扫描 .mp3/.m4a 链接 + 测试可用性\n      └─ 下载 ✅ / 跳过 ⏭\n```\n\n## AI 音源发现\n\n侧边栏 → 🤖 AI 发现音源：\n\n| 层级 | 方法 | 说明 |\n|------|------|------|\n| Phase 1 | 直接探测 | 向已知免费 API 域名发测试请求 |\n| Phase 2 | 网络搜索 | Bing 搜索音乐 API |\n| Phase 3 | 逐页分析 | 打开每个结果 → AI/规则分析 → 生成模板 |\n\n| 分析引擎 | 需要 Key | 能力 |\n|----------|---------|------|\n| rule-based | 免费 | 自动识别 JSON API 字段映射、HTML 模式 |\n| OpenAI | `sk-...` | LLM 理解任意页面结构 |\n| Claude | `sk-ant-...` | LLM 理解任意页面结构 |\n\n## 原理\n\n- **歌单提取**：CDP 控制 Chrome 打开歌单页，解析嵌入的 `songList` JSON\n- **Cookie 提取**：Chrome DevTools Protocol 读取所有 Cookie（含 HttpOnly）\n- **下载链接**：调用 QQ 音乐 `GetVkey` 获取 CDN 地址\n- **VIP 识别**：已登录自动跳过付费标记，VIP 歌曲直接下载\n- **音源回退**：VIP 歌曲无账号时自动从网易云/酷狗/网络搜索替代\n- **g_tk 计算**：`hash33(qqmusic_key)` — QQ 和微信登录均支持\n\n## 配置文件\n\n`~/.config/music-dl/config.json`：\n\n```json\n{\n  \"download_dir\": \"~/Music\",\n  \"quality\": \"320kbps\",\n  \"workers\": 3,\n  \"accounts\": {\n    \"qq\": \"uin=...; qqmusic_key=...\",\n    \"netease\": \"MUSIC_U=...\",\n    \"kugou\": \"kg_mid=...\"\n  }\n}\n```\n\n## 运行时日志\n\n应用自动记录日志到 `~/.config/music-dl/logs/music-dl.log`，5MB 自动轮转，保留 3 个备份。\n\n```bash\n# 查看日志统计\ncurl http://127.0.0.1:8765/api/logs/status\n\n# 导出今日 JSON\ncurl -X POST http://127.0.0.1:8765/api/logs/export \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"format\":\"json\",\"date\":\"2026-06-01\"}'\n\n# 导出全文 TXT\ncurl -X POST http://127.0.0.1:8765/api/logs/export \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"format\":\"txt\"}'\n```\n\n## 测试\n\n```bash\npip install pytest pytest-asyncio httpx\npytest tests/ -v    # 65 tests (API / 工具函数 / 日志 / 导出 / 链接提取)\n```\n\n## 依赖\n\n- Python 3.8+（Android 兼容）/ 桌面端 Python 3.10+\n- fastapi, uvicorn, requests, rich\n- websocket-client, cryptography\n- Google Chrome（CDP Cookie 提取需要）\n\n## API 参考\n\n| 端点 | 方法 | 说明 |\n|------|------|------|\n| `/api/status` | GET | 登录状态、音质、下载目录 |\n| `/api/search` | POST | 聚合搜索 `{\"keyword\":\"晴天\",\"limit\":20}` |\n| `/api/play` | POST | 获取播放链接 `{\"mid\":\"xxx\",\"quality\":\"320kbps\"}` |\n| `/api/cache` | GET | 缓存音频到本地 `?url=...` |\n| `/api/stream` | GET | 流式播放 `?path=...` 或代理 `?url=...` |\n| `/api/download` | POST | 批量下载 `{\"songs\":[...],\"quality\":\"320kbps\"}` |\n| `/api/download/progress/{id}` | GET | SSE 下载进度 |\n| `/api/downloads` | GET | 已下载文件列表 |\n| `/api/favorites` | POST | 收藏列表（需登录） |\n| `/api/playlist` | POST | 歌单提取 `{\"url\":\"...\"}` |\n| `/api/link` | POST | 链接下载 `{\"url\":\"...\",\"quality\":\"320kbps\"}` |\n| `/api/login/cookie` | POST | Cookie 登录 `{\"cookie\":\"...\",\"platform\":\"qq\"}` |\n| `/api/login/chrome` | POST | 打开 Chrome 登录页 `?platform=qq` |\n| `/api/login/cdp` | POST | CDP 提取 Cookie `?platform=qq` |\n| `/api/login/suspend` | POST | 暂停登录 `?platform=qq` |\n| `/api/login/restore` | POST | 恢复登录 `?platform=qq` |\n| `/api/logs/status` | GET | 日志统计（行数、错误数、文件大小） |\n| `/api/logs/export` | POST | 导出日志 `{\"format\":\"json\"\\|\"txt\",\"date\":\"2026-06-01\"}` |\n| `/api/sources/discover` | POST | AI 发现音源 |\n| `/api/sources/status` | GET | 音源可用性检测 |\n| `/api/sources/lx/import` | POST | 导入 LX 音源 |\n| `/api/config` | GET/POST | 配置读写 |\n| `/api/config/ai` | GET/POST | AI 配置读写 |\n| `/debug/play` | GET | 播放诊断 |\n\n## 参考与致谢\n\n本项目为原创实现，以下项目提供了 API 接口分析参考：\n\n| 项目 | 作者 | License | 参考内容 |\n|------|------|---------|----------|\n| [qqmusicdownloader](https://github.com/yuqie6/qqmusicdownloader) | yuqie6 | — | 歌单/搜索 API 模块名 |\n| [qq-music-api](https://github.com/copws/qq-music-api) | copws | — | musicu.fcg 接口格式 |\n| [MCQTSS_QQMusic](https://github.com/huahuadiandian/MCQTSS_QQMusic) | huahuadiandian | — | 收藏 API 接口分析 |\n\n### 第三方依赖 License\n\n| 依赖 | License |\n|------|---------|\n| [fastapi](https://github.com/fastapi/fastapi) | MIT |\n| [uvicorn](https://github.com/encode/uvicorn) | BSD |\n| [requests](https://github.com/psf/requests) | Apache 2.0 |\n| [rich](https://github.com/Textualize/rich) | MIT |\n| [websocket-client](https://github.com/websocket-client/websocket-client) | Apache 2.0 |\n| [cryptography](https://github.com/pyca/cryptography) | Apache 2.0 / BSD |\n## 免责声明\n\n本工具是一个基于 Python 的命令行和 Web 工具，可以从多个平台搜索和下载音乐。工具的本意是**聚合搜索**，方便寻找音乐，解决不知道哪个平台有版权的问题。API 均从公开网络中获得，**不是破解版**。\n\n**禁止将本工具用于商业用途**，如产生法律纠纷与本人无关。\n\n如有侵权，请联系我删除。\n\n## 联系作者\n\n- **GitHub Issues**：[提交 Issue](https://github.com/dylan121322/music-dl/issues)\n\n---\n\n## 使用提示\n\n- Cookie 有时效性（约 2-3 天），过期后需重新登录\n- CDP Chrome 端口默认 9233，需保持 Chrome 运行\n- 歌单提取依赖 CDP Chrome，确保 Chrome 未被完全关闭\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylan121322%2Fmusic-dl-android","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdylan121322%2Fmusic-dl-android","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdylan121322%2Fmusic-dl-android/lists"}