Ximalaya-Downloader-Next

喜马拉雅音频下载器 · 重启版

下载你有权访问的喜马拉雅内容，支持单曲、专辑、断点续传、失败重试与任务恢复。

Python 3.10+ 本地 WebUI CLI 断点续传 AGPL-3.0

在 GitHub 上查看快速开始

它是怎么工作的

默认链路使用纯 Python 在本地生成 xm-sign，再通过 HTTP 请求播放信息。

Google Chrome 或 Microsoft Edge 只用于交互登录，以及 Cookie 缓存失效时从专用 Profile 读取已持久化会话，不负责默认下载请求。

xm-sign 只满足特定接口的签名要求，不能替代登录与内容授权。
每个浏览器的登录态、Cookie 缓存与设备指纹各自独立保存，切换浏览器互不覆盖。
请只下载你有权访问的内容。

功能特性

单曲与专辑

粘贴链接或 ID 即可下载单个音频或整张专辑，支持 --range 指定区间与三档音质选择，音质缺失时自动回退到可用规格。

断点续传与任务恢复

已存在的完整文件自动跳过，未完成的 .part 文件支持 HTTP Range 续传；Ctrl-C 保存进度优雅退出，随后 xdl resume 接着下。

本地 WebUI

xdl web 启动本地界面：登录、新建任务、选音质与区间、恢复任务、查看风控报告、调整设置，都在浏览器里完成。

风控友好

识别到风控信号会停止整批并只提示一次；可选 --risk-poll 自动等待恢复后继续下载，等待期间不反复请求。

快速开始

要求：Python 3.10+、Google Chrome 或 Microsoft Edge。

pip install -e .

# 启动本地 WebUI（自动打开 http://127.0.0.1:8787）
xdl web

# 或者继续使用 CLI：先登录，再下载
xdl login
xdl track <音频链接或 trackId>
xdl album <专辑链接或 albumId>

首次登录会在浏览器中完成交互验证，Cookie 与设备指纹保存在专用 Profile 中（~/.xdl/），成功后无需再刷新。两个浏览器都装了可以用 --browser edge 指定其一。

xdl track -F <链接或ID>              # 列出所有可用音质格式，不下载
xdl album <链接或ID> --range 1-20   # 只下载指定区间
xdl album <链接或ID> --quality high # high / standard / low
xdl --concurrency 3 album <链接或ID> # 自定义异步并发数（默认 1）
xdl --risk-poll album <链接或ID>     # 风控后自动轮询恢复
xdl resume                          # 恢复未完成任务
xdl risk-report                     # 汇总本地风控记录，不发网络请求

WebUI 默认只监听本机回环地址，没有远程访问认证，请不要把它直接暴露到公网。

使用边界

本工具不能替代登录与内容授权，只应下载你有权访问的内容。
提高并发会增加请求量，可能更容易触发平台风控，请保持默认并发或适度调整。
默认下载目录为当前目录下的 downloads，可用 --download-dir 修改。