gamdl 深度拆解：Apple Music 无损下载与 4K 音乐视频的命令行方案-平芜编程栈

gamdl 深度拆解：Apple Music 无损下载与 4K 音乐视频的命令行方案

【免费下载链接】gamdlA command-line app for downloading Apple Music songs, music videos and post videos.项目地址: https://gitcode.com/GitHub_Trending/ga/gamdl

gamdl 是一个面向 Apple Music 订阅用户的命令行工具，负责把歌曲、音乐视频和 Post 视频无损下载为本地文件。它的硬指标很具体：音频最高 24-bit/192kHz 的 ALAC，音乐视频最高 2160p，同步歌词支持 lrc/srt/ttml 三种格式，全程参数可控。

安装（需 Python 3.10+，从 PyPI 直接装即可）：
```
pip install gamdl
```
准备登录态：在已登录 Apple Music 网页的浏览器里，用扩展把 Cookie 以 Netscape 格式导出，存为工作目录下的cookies.txt（也可用--cookies-path指定其他位置）。Cookie 就是请求媒体流的凭据，缺了它什么都下不了。
跑通第一条命令，-o指定输出目录：
```
gamdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511" -o "./Apple Music"
```
首次运行会自动生成配置文件（Linux 下为~/.gamdl/config.ini），之后常用参数都可以写进配置，命令行参数优先于配置值。

功能	关键参数	生效条件
导出 4K 音乐视频	`--music-video-resolution 2160p`	必须 h265 编码，且提供 L1`.wvd`或 SL3K`.prd`设备文件
歌曲无损下载	`--song-codec-priority alac`	建议启用 Wrapper v2（`--use-wrapper`）
挑选同步歌词格式	`--synced-lyrics-format`	默认`lrc`；`ttml`多数播放器不识别
整理目录与文件名	`--album-folder-template`等	模板变量见 README Configuration 一节

音乐视频默认上限是 1080p，把分辨率档位调到 2160p 就能拿到 4K 流：

gamdl "https://music.apple.com/us/album/..." --music-video-resolution 2160p --music-video-codec-priority h265

限制：1440p 与 2160p 只有 H.265 编码提供，且 4K 必须提供 Widevine L1 的.wvd（--wvd-path）或 PlayReady SL3K 的.prd（--prd-path）设备文件，否则拿不到该分辨率的流。

歌曲默认是 AAC 256kbps 的aac-web码流；改成alac可得到最高 24-bit/192kHz 的无损文件：

gamdl "https://music.apple.com/..." --song-codec-priority alac --use-wrapper

前置条件：ALAC 属非 web 流，受 API 限制，不带 Wrapper v2 服务时大概率失败；启用--use-wrapper后由 Wrapper 接管账号与解密，Cookie 也可跳过。其他编码器（含 Dolby Atmos 768kbps 的atmos）无需 Wrapper。

下载完成后自动写入艺术家、专辑、封面等元数据，并附带同步歌词：

gamdl "https://music.apple.com/..." --synced-lyrics-format srt

限制：ttml是 Apple Music 原生格式，多数播放器不认；要在播放器里显示歌词选lrc，要更精确的时间轴（适合当字幕）选srt。

输出目录和文件名按模板生成，默认是{album_artist}/{album}加{track:02d} {title}，可整体改写：

gamdl "https://music.apple.com/..." --album-folder-template "{album_artist}/{album} ({date:%Y})" --truncate 150

变量范围包括album、artist、track、date（支持 strftime 语法）等，完整列表和--exclude-tags的用法见 README 的 Template Variables 小节。

现象	原因	处理
登录相关报错、无法请求媒体流	`cookies.txt`过期或缺失	重新从浏览器导出一份；或改用`--use-wrapper`后不再依赖 Cookie
歌词无法在播放器显示	用了`ttml`格式	换`lrc`或`srt`重新下载歌词
单独 ALAC 下载失败、AAC 正常	非 web 无损流受 API 限制，非配置错误	启用 Wrapper v2 服务后再试
2160p 拿不到、自动降分辨率	未提供 DRM 设备文件	用`--wvd-path`或`--prd-path`提供 L1`.wvd`/ SL3K`.prd`

曲库整体迁移、换设备或整理本地媒体库的订阅用户：模板变量加--database-path指向的 SQLite 库记录已下载媒体，适合做增量归档。
在意输出规格的人：编码器、分辨率、歌词格式、封面尺寸（--cover-size默认 1200px）全部可参数化，这是官方导出渠道给不了的。
想把它嵌进自己流水线的人：gamdl/api/和gamdl/downloader/可直接作为 Python 库调用，README 的 Embedding 一节有完整示例。
劝退建议：如果目的只是"手机上能离线听"，Apple 自带下载足够稳定，不值得为 Cookie 维护和 DRM 设备文件花精力；gamdl 的价值在规格控制，不在"能下"。