Gamdl 实战：Apple Music 无损下载与 4K MV 快速上手

Gamdl 实战：Apple Music 无损下载与 4K MV 快速上手

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

想在 Apple Music 里看到整张专辑、整支 MV 都想留在本地？Gamdl（Glomatico's Apple Music Downloader）是一条命令就能办到的 Apple Music 下载工具：它不靠录制或转码，而是模拟客户端请求，直接从官方接口拉原始编码文件——AAC 256kbps、最高 24-bit/192kHz 的 ALAC 无损、4K H.265 音乐视频，标签和同步歌词一并写好。它只需要一个活跃订阅加一份浏览器 Cookie，不依赖图形界面，适合命令行用户和想把它嵌进自动化脚本的开发者。

跑起来：从零到第一次成功

这一节带你完成安装、前置准备和第一次下载，走完你能得到本地落盘的第一首歌。

1. 安装

要求 Python 3.10 或更高。确认版本并安装：

python --version

pip install gamdl

再确认命令装对了：

gamdl --version

成功标志：终端打印出版本号（当前为 3.9）。

2. 前置准备

需要两样东西：一个有活跃订阅的 Apple Music 账号；一份 Netscape 格式的 Cookie 文件。用浏览器的"Export Cookies"类扩展在登录状态下把 music.apple.com 的 Cookie 导出为cookies.txt，放在工作目录即可，也可用-c参数指定其他路径。

3. 第一条下载命令

打开任意歌曲的 Apple Music 分享链接，执行：

gamdl "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"

成功标志：终端出现Starting Gamdl 3.9与Downloading "..."进度，./Apple Music目录按"艺术家/专辑"结构生成.m4a文件，结尾打印Finished with 0 error(s)。默认同步歌词会以同名.lrc写入同一目录；首次运行还会在~/.gamdl/config.ini自动生成一份完整配置，命令行参数都有对应项，命令行值优先。

把核心功能用到实处

这一节按使用频率给出四个任务，每个都附验证方法，做完你可以把批量、无损、4K、命名规则都用上。

任务一：批量下载 + 去重

目标：把多个链接一次下完，定时重复运行不产生冗余文件。

做法：链接每行一条写入urls.txt，用-r读取文件（启用后参数里给的是 txt 路径而不是 URL），并用--database-path指定一个 SQLite 数据库用于去重：

gamdl -r urls.txt --database-path "./history.db"

验证：重跑一次，已下过的条目日志出现Skipping "...": Registered in database；history.db文件存在。去重逻辑就几十行，在 gamdl/cli/database.py，存的是媒体 ID 到本地路径的映射。

任务二：无损音质（ALAC 优先）

目标：优先拿 ALAC 无损，没有的曲目自动回落到 AAC 256kbps。

做法：ALAC 走非 Web 流，受 API 限制，纯 Cookie 模式大概率解不开，README 明确建议配合本地 Wrapper v2 服务。先在~/.gamdl/config.ini的[gamdl]段开启：

[gamdl] use_wrapper = true wrapper_url = http://127.0.0.1 wrapper_decrypt_port = 10020

再下歌：

gamdl URL --song-codec-priority "alac,aac-web"

验证：用 ffprobe 看文件编码，无损曲目应为alac（24-bit/192kHz 规格以源文件为准）；没开 Wrapper 时终端会打印 ALAC 相关警告，看到它就说明该启用use_wrapper。

任务三：4K 音乐视频

目标：把 MV 下成 H.265 封装的 4K 文件。

做法：三个参数必须一起给——分辨率、编码器、容器。H.264 编码器最高只到 1080p，1440p/2160p 只有 H.265 提供：

gamdl URL --music-video-resolution 2160p --music-video-codec-priority h265 --music-video-remux-format m4v

验证：

ffprobe -v error -select_streams v:0 -show_entries stream=width,height,codec_name output.m4v

验证：输出应为 3840x2160、h265。

任务四：自定义目录与文件名

目标：用自己的模板控制归档结构，单独存封面。

做法：

gamdl URL --album-folder-template "{album_artist}/{date:%Y}/{album}" --single-disc-file-template "{track:02d} {title}" --save-cover --cover-format png --cover-size 2000

验证：输出目录变成艺术家/年份/专辑/01 曲目名.m4a结构，且每首歌旁多出一份 2000 像素 PNG 封面。所有可用模板变量（{album}、{artist}、{track:02d}等）在 README 的 Template Variables 一节有完整清单。

适用边界：什么场景选它、什么场景别选

这一节帮你判断自己是否在它的射程内，避免装完才发现用不上。

适合：有活跃 Apple Music 订阅、想整专辑/整艺术家批量存档、需要去重和定时任务、或想把它当 Python 库嵌进自己项目（API → Interface → Downloader 三层各自独立，改哪层动哪层，见 gamdl/api/ 与 gamdl/downloader/）。不适合：Tidal、Spotify 等其他平台——它只对接 Apple Music 官方接口；无账号批量抓取；需要图形界面的场景。想下普通网络视频直接用 yt-dlp 即可，不必绕道。

出问题了先看这里

四个高频故障，按"现象 → 原因 → 解法"排好，先对号入座。

1. 现象：启动即报No active Apple Music subscription found，什么都下不了。原因：Cookie 过期或订阅失效。解法：重新登录 music.apple.com，用扩展导出新的cookies.txt。

2. 现象：选了alac却全部失败，终端有 ALAC 警告。原因：ALAC 需要 Wrapper 服务配合，纯 Cookie 模式 API 解不开。解法：本地跑起 Wrapper v2 并开启use_wrapper = true；不想折腾就退回aac-web（256kbps）。

3. 现象：指定了 2160p，文件实际只有 1080p。原因：H.264 编码器不提供 4K 档。解法：--music-video-codec-priority中放h265。

4. 现象：批量任务中途报错后停止。原因：默认会打印异常详情。解法：加--no-exceptions让单条失败只记警告不中断，配合--log-file ./gamdl.log事后排查。

Gamdl 的价值可以收在三句话：直连官方接口拿原始媒体，标签与同步歌词自动写齐，下载完成即成品；三层架构让二次开发只动一层；Python 库模式下get_download_item_from_url生成器加download方法就能驱动整条流水线。接下来三件事：

• 跑gamdl --version与第一条下载命令，核对./Apple Music里的成品文件；
• 打开~/.gamdl/config.ini，把output_path、song_codec_priority改成你的长期默认值；
• 顺着 gamdl/api/、gamdl/downloader/ 读调用链，弄清"请求 → 解析 → 解密 → 封装"各在哪一层。

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