AMDL
EN

2.0 开发中 · 自托管 · 开源

Apple Music，
存进自己的硬盘。无损，标签齐全。

贴一个单曲、专辑、歌单、艺人或电台链接，或者直接搜索曲库。AMDL 把每首曲目下载、解密、重新封装、写好标签，存成完整的 .m4a：ALAC 最高 24 bit/192 kHz，也可以是杜比全景声或 AAC。

docker compose up -d
开始使用
ALAC，最高 24 bit
192kHz
链接，从单曲到电台
5种
二进制，服务端、CLI、MCP、TUI 都在里面
1个
需要的 Apple 开发者密钥
0

01 · 工作原理

从一条链接，到一个成品文件。

默认情况下，一种编码的重试次数用完，就换列表里的下一种，最后由 AAC-LC 兜底。

  1. 01

    解析

    从 Apple 曲库读出链接背后的单曲、专辑、歌单、艺人或电台，连同每首歌的元数据。

  2. 02

    下载

    从 Apple 的 CDN 拉取加密分片，失败了按退避间隔重试。

  3. 03

    解密

    在进程内用纯 Go 完成。密钥模板来自你的 wrapper，AMDL 自己不保存任何 Apple 账号和密钥。

  4. 04

    封装

    解密出的采样直接送进 ffmpeg，整首歌的明文不会写到磁盘上。

  5. 05

    标签

    先校验文件完整，再写入元数据、封面和歌词。

  6. 06

    保存

    按你的路径模板放进下载目录。已经存在的文件默认跳过，除非你要求覆盖。

02 · 产品

一套核心，四种用法。

所有产品都跑在同一套 Go 核心上。服务端部署一次，之后哪个顺手用哪个。

服务端

amdl serve

你要部署的后端：一个 Go 进程，一个 SQLite 数据库，/api/v1 下的 REST 和 Server-Sent Events 接口，网页控制台也在同一个端口上。GHCR 上有 amd64 和 arm64 镜像。

  • 重启不丢任务，下次启动从停下的地方接着跑。
  • 下载、解密和 wrapper 请求在整个进程里共用并发池。
  • 刻意不做账号和鉴权：访问控制交给前面的反向代理。
提交一张专辑，跟踪进度
 curl -X POST http://localhost:18080/api/v1/downloads \
    -H 'Content-Type: application/json' \
    -d '{"urls":["https://music.apple.com/us/album/1519740112"]}'
{"accepted":1,"rejected":0,"results":[{"status":"accepted","job":{"id":"job_4467…","status":"queued",…}}]}

 curl -N http://localhost:18080/api/v1/downloads/{job_id}/events

网页控制台

网页控制台

内嵌在服务端、挂在 /console/ 下的浏览器客户端。在这里搜曲库或贴链接，看着每首歌一步步走完，下好的专辑带着各自封面的配色。

  • 实时队列：每首歌一条阶段条，外加一条专辑总进度
  • 专辑有 Apple 动态封面时直接播放
  • 日志、系统状态和设置，手机上也好用
控制台总览：实时队列里两张专辑正在下载，下面是最新完成的专辑和封面墙控制台总览：实时队列里两张专辑正在下载，下面是最新完成的专辑和封面墙
手机上一张已完成专辑的任务抽屉手机上一张已完成专辑的任务抽屉
一张已完成专辑的任务抽屉，用专辑配色：专辑进度条，以及每首歌的时长和大小一张已完成专辑的任务抽屉，用专辑配色：专辑进度条，以及每首歌的时长和大小
新建下载：搜索 Yorushika 的结果，每首歌标出可用的音频格式新建下载：搜索 Yorushika 的结果，每首歌标出可用的音频格式

终端

CLI · MCP · TUI

amdl 一个二进制，三种用法。脚本和 agent 拿到的是 stdout 上的 JSON，每类失败有自己的退出码；amdl mcp 把同一套命令作为 MCP 工具提供；直接运行 amdl，就是给人用的交互界面：贴链接下载，打字就是搜索。

  • 内联渲染，完成的任务留在终端的滚动历史里。
  • 每个进行中的任务一张卡片，颜色取自专辑封面。
  • 自己没有服务器？amdl service install 把后端装成本机的后台服务，登录后自动启动。

桌面端 开发中

桌面应用

用 MyGo 原生界面绘制的桌面应用，支持 macOS、Windows 和 Linux。它可以连你的服务端当客户端，也可以自己跑下载流水线、连接远程的 wrapper，和命令行共用同一个后端、同一份下载记录。目前还没有发布。

桌面应用在 Windows 上的开发版，正在曲库里搜索 Yorushika桌面应用在 Windows 上的开发版，正在曲库里搜索 Yorushika
Windows 上的开发版

03 · 细节

那些原本得自己写脚本的事。

04 · 快速开始

几分钟就能跑起来。

你需要 Apple Music 订阅，和一个 wrapper：保管你 Apple Music 登录状态的服务。wrapper 可以跑在一台 Linux 机器上，也可以交给 amdl，在你自己电脑的 QEMU 虚拟机里运行。

  1. 1

    安装 amdl

    脚本会用发布附带的 SHA256SUMS 校验安装包，再把 amdl 放进 ~/.local/bin；这个目录不在 PATH 里时，会打印要加的那一行。Windows 上装进用户程序目录。

    macOS · Linux
     curl -fsSL https://raw.githubusercontent.com/AMDL-Web/apple-music-downloader/dev/deploy/install/install.sh | sh
    Windows · PowerShell
     [Net.ServicePointManager]::SecurityProtocol = [Net.ServicePointManager]::SecurityProtocol -bor 3072; irm https://raw.githubusercontent.com/AMDL-Web/apple-music-downloader/dev/deploy/install/install.ps1 | iex
  2. 2

    检查 ffmpeg

    每首曲目都要经过 ffmpeg。amdl doctor 会告诉你这台机器有没有装，没装就打印安装命令。

     amdl doctor
  3. 3

    准备 wrapper

    这条命令会下载上游的 wrapper 虚拟机，并按固定的哈希校验；它需要 QEMU，没装会提示你安装。已经在 NAS 或服务器上跑着 wrapper 的话，跳过这一步。

     amdl wrapper install
  4. 4

    运行后端

    这条命令把后端注册成登录后自动启动的服务，wrapper 也随它一起启动。wrapper 在别处的话，加上 --wrapper <它的地址>。amdl service status 会打印控制台地址，在它的 Account 页登录；也可以直接在终端里运行 amdl wrapper login。

     amdl service install
 amdl service status
  1. 1

    取得 Compose 文件

    放在一个空目录里。先建好 data/downloads，交给后端的运行用户（PUID:PGID，默认 1000:1000），不然 Docker 会以 root 身份创建它。第一次启动会补上 configs/ 和 data/ 里的其余目录。

     mkdir amdl && cd amdl
 mkdir -p data/downloads && chown 1000:1000 data/downloads
 curl -fsSLO https://raw.githubusercontent.com/AMDL-Web/apple-music-downloader/dev/deploy/docker-compose.yml
  2. 2

    启用 wrapper

    在 docker-compose.yml 里取消注释 wrapper-manager 服务和文件末尾的 volumes: 块，再把 wrapper 地址改成：

    AMDL_WRAPPER_ADDRESS: "http://wrapper-manager:8080"
  3. 3

    一起启动

    Compose 会从 v2 分支构建 wrapper-manager，所以主机要能上网。

     docker compose up -d
  4. 4

    登录，然后下载

    打开 http://localhost:18080/，进入 Settings › Account，用 Apple ID 登录。在 New download 里贴上链接，下好的文件在 ./data/downloads。

两种方式的全部选项，见安装指南和部署指南。

05 · 给 AI agent

为 agent 而生。

每个结果都是 stdout 上的 JSON，每个错误都是 stderr 上的 JSON 对象，退出码按失败类别区分。amdl cli search 按任务找命令，--dry-run 只打印改动、不真正发送；破坏性命令会先确认，不在终端里运行时必须加 --yes。

shell
 amdl search yorushika --types albums --limit 2 --fields name,url
{"albums":{"items":[{"name":"Beyond the Clouds, Only Me Downwind - Single","url":"https://music.apple.com/cn/album/beyond-the-clouds-only-me-downwind-single/6817316270"},{"name":"Plagiarism","url":"https://music.apple.com/cn/album/plagiarism/1519740112"}],"next_offset":2},"storefront":"cn","term":"yorushika"}
 amdl download https://music.apple.com/cn/album/plagiarism/1519740112 --dry-run
{"body":{"urls":["https://music.apple.com/cn/album/plagiarism/1519740112"]},"method":"POST","url":"http://nas.local:18080/api/v1/downloads"}
 amdl jobs delete job_4467…
{"error":{"code":"confirmation_required","message":"amdl jobs delete changes data that cannot be restored; nothing was changed","hint":"amdl jobs delete job_4467… --yes"}}
 echo $?
10

每次发布都附带 Linux、macOS 和 Windows 版的 amdl，服务端镜像里也自带一份，在 /app/amdl。 命令行参考

shell
 amdl context add nas http://nas.local:18080
{"current":true,"name":"nas","url":"http://nas.local:18080"}
 amdl cli setup --server nas --fields claude_code,mcp_json
{"claude_code":"claude mcp add amdl -- /home/me/.local/bin/amdl mcp --server nas","mcp_json":{"mcpServers":{"amdl":{"args":["mcp","--server","nas"],"command":"/home/me/.local/bin/amdl"}}}}
 claude mcp add amdl -- /home/me/.local/bin/amdl mcp --server nas
mcp.json
{
  "mcpServers": {
    "amdl": {
      "args": ["mcp", "--server", "nas"],
      "command": "/home/me/.local/bin/amdl"
    }
  }
}

amdl cli setup 打印编码 agent 接入所需的全部内容，不改动任何文件：claude mcp add 命令、Codex 的 config.toml 条目、mcpServers 条目、一段写进 AGENTS.md 的说明，以及一份 agent skill。之后从搜索到下载只要两次调用：search_catalog 和 start_download；wait_for_job 在等待时推送专辑进度。没有哪个工具负责登录 wrapper，密码不会经过模型。