Gamdl 完整上手指南：6 个技巧把 Apple Music 无损音频与 4K 音乐视频下载到本地-港品优选

Gamdl 完整上手指南：6 个技巧把 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 订阅的用户，把歌曲、音乐视频和艺术家上传视频完整保存到本地，最高支持 ALAC 24-bit/192kHz 无损音频和 4K H.265 视频，适合想自建本地音乐库的发烧友，也适合需要高质量素材的内容创作者。本文从安装、首次下载到踩坑避雷，用一套完整流程带你上手 Apple Music 无损下载。

先回答三个高频问题：合法吗？免费吗？和在线下载站有什么区别？

在动手之前，很多读者会先纠结这三件事，这里一次性说清楚。

问题一：这算"盗版工具"吗？

Gamdl 本身要求你必须拥有有效的 Apple Music 订阅。它做的只是把你有权播放的内容，以本地文件形式保存下来供个人使用，性质上更接近"私人备份"而不是"盗版抓取"。作者在 README 中也明确说明了使用前提，下载内容请勿用于商业分发。

问题二：免费吗？

工具本身完全免费开源，只需要pip install gamdl一条命令。你要付出的成本只有两样：一份 Apple Music 订阅，以及一个浏览器导出的 Cookie 文件。

问题三：为什么不直接用网页在线下载站？

在线下载站一般只能抓到网页音频流，质量上限低、元数据残缺，还经常失效。Gamdl 走的是 Apple Music 官方 API 链路：直接拉取官方媒体元数据、播放清单和解密密钥，再配合 FFmpeg 或内置的 Rust 引擎完成解密与封装。这就是它能拿到 AAC 256kbps、Dolby Atmos 甚至 24-bit/192kHz 无损的关键——因为来源本身就是 Apple 的原始媒体文件，而不是网页二次转录。

三步完成安装与初始化

安装环节只需要三个步骤，按顺序执行即可。

第 1 步：安装本体

pip install gamdl

装完可以用gamdl --version验证是否成功。如果你想从源码跑，也可以克隆仓库后本地安装：

git clone https://gitcode.com/GitHub_Trending/ga/gamdl cd gamdl pip install .

第 2 步：准备 Cookie 文件

登录 music.apple.com 后，用浏览器扩展把 Cookie 导出成 Netscape 格式的cookies.txt，放在当前工作目录即可。Firefox 和 Chromium 系浏览器都有对应的导出扩展，导出后注意文件不要泄露给别人。

第 3 步：按需安装可选依赖

想要 ALAC 无损：需要运行 Wrapper v2 服务（后面会细说）
想要更快的下载速度：可以装 N_m3u8DL-RE，并在配置里把download_mode改成nm3u8dlre
FFmpeg：如果系统 PATH 里没有，需要手动指定--ffmpeg-path

这三样都不是必装的。只下普通 AAC 歌曲的话，装完第 1、2 步就能直接用了。

第一次下载：从一行命令到完整专辑

装好之后，第一次运行的体验比想象中简单。核心用法只有一种：

gamdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

把专辑链接丢进去，回车，程序会依次完成这些事：

解析 URL，识别内容类型（歌曲、专辑、播放列表、音乐视频、艺术家页面都支持）
通过 API 拉取媒体元数据，并校验你的订阅状态
根据编码器优先级选定音轨（默认aac-web，即 AAC 256kbps）
拉取加密媒体流，获取解密密钥
解密、封装，并用 mutagen 写入封面、歌词、艺术家等标签
按默认模板{album_artist}/{album}整理到./Apple Music目录

如果你的目标链接是一张有几十首歌的专辑，程序会按顺序批量下载，中途某个文件出错不会中断整个任务。下载过程中终端会输出每首歌的进度日志，日志级别可用--log-level DEBUG调高，方便排查问题。

如果是艺术家页面链接，程序会弹出交互式选择界面，让你勾选要下载的内容类型（正式专辑、合辑、现场专辑、单曲 EP、热门歌曲、音乐视频等）。方向键移动、空格勾选、Ctrl+A 全选、回车确认，非常直观。

6 个立刻提升体验的实用参数

用熟了基础命令之后，下面这 6 个参数是提升体验性价比最高的，建议逐个试一遍。

1. 指定音频编码器优先级

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

编码器按逗号分隔的优先级排列，前面的找不到就自动降级到后面的。默认是aac-web，想要无损就把它放在最前面。

2. 解锁 4K 视频

gamdl URL --music-video-resolution 2160p --music-video-codec-priority h265

注意一个容易踩的坑：H.264 最多只到 1080p，2160p（4K）和 1440p 只有 H.265 才有。

3. 换一种歌词格式

gamdl URL --synced-lyrics-format srt

默认输出 LRC 格式，多数播放器都认；想要更精确的时间轴可以换 SRT；TTML 是 Apple 原生格式，兼容性差，不建议默认使用。

4. 自定义文件命名与目录结构

gamdl URL --album-folder-template "{album_artist}/{date:%Y}/{album}" --single-disc-file-template "{track:02d} {title}"

模板变量很丰富：album、artist、track、disc、date（支持 strftime 格式化）等都能用，彻底告别"01 Track 1.mp3"式乱命名。

5. 保存独立封面

gamdl URL --save-cover --cover-format png --cover-size 2000

默认封面是内嵌进音频文件的，开启后可以额外保存一份独立封面文件，方便做媒体库展示。

6. 用数据库避免重复下载

gamdl URL --database-path "./downloads.db"

开启后，已下载的媒体会被登记进 SQLite 数据库，下次再遇到同一个资源会直接跳过，批量维护歌单时非常省事。

四个常见的坑与绕坑方法

下面这些是实际使用中最容易翻车的四个场景，提前知道能省不少时间。

坑一：ALAC 无损下不下来

ALAC 走的是非 Web 播放链路，受 API 限制，不借助 Wrapper 基本下不动。绕坑方法：运行 Wrapper v2 服务，加--use-wrapper参数启动，按提示输入账号凭据（首次需要登录，可能还要二步验证码）。注意新版 Wrapper 的解密端口默认是 TCP 10020，别搞混。

坑二：4K 选项不出现

检查编码器优先级是否包含h265。分辨率选项里 2160p 只对 H.265 开放，这是 Apple 媒体源本身的限制，不是程序 bug。

坑三：提示没有有效订阅

No active Apple Music subscription说明 Cookie 失效或账号没订阅。重新导出 Cookie 试试；如果用了 Wrapper，检查 Wrapper 登录状态。

坑四：下载到一半断网，全部重来

配合--database-path和--overwrite两个参数管理增量下载：已登记的跳过、断掉的重试，比全量重下高效得多。临时文件默认放在当前目录，也可以--temp-path指到 SSD 上加速。

想二次开发？它也能当 Python 库用

Gamdl 不只是命令行工具，还提供了一组清晰的异步 Python API。整体架构分三层，路径对应得很直白：

gamdl/api/：与 Apple Music 服务器通信，负责认证、媒体元数据与播放信息获取
gamdl/interface/：把元数据解析成媒体清单，处理歌词、编码器选择与解密密钥获取
gamdl/downloader/：负责流下载、解密、封装和标签写入

值得单独一提的是，解密与封装的核心工作其实是由一个 Rust 扩展完成的（源码在 gamdl/downloader/ammuxer/，用 PyO3 编译成 Python 扩展），兼顾了性能和可维护性。Python 侧只负责编排逻辑，这个分层思路本身就很值得学习。

嵌入到自己项目里也很直接：

import asyncio from gamdl.api import AppleMusicApi from gamdl.downloader import AppleMusicDownloader from gamdl.interface import AppleMusicInterface async def main(): api = await AppleMusicApi.create_from_netscape_cookies("cookies.txt") interface = await AppleMusicInterface.create(apple_music_api=api) downloader = AppleMusicDownloader(interface=interface) async for media in downloader.get_download_item_from_url(url): await downloader.download(media) asyncio.run(main())

配置层面同样照顾了两种习惯：既支持命令行参数覆盖，也支持首次运行自动生成的~/.gamdl/config.ini配置文件，两者并存时命令行参数优先。

常见问题速查（FAQ）

Q：支持下载哪些链接类型？

单曲、专辑、播放列表、音乐视频、艺术家页面、上传视频，以及 Apple Music Classical 的内容都在支持范围内。

Q：下载速度慢怎么办？

把下载模式换成 N_m3u8DL-RE：--download-mode nm3u8dlre，它比默认的 yt-dlp 下载模式更快。注意 yt-dlp 在这里只充当文件下载库，媒体流本身仍然来自 Apple 官方服务器。

Q：标签信息不全怎么办？

可以用--exclude-tags剔除不想要的标签（比如comment,genre_id），也可以调整--language切换元数据语言（如zh-CN、ja-JP），不过部分音乐视频的元数据语言不受该参数控制。

Q：想让配置永久生效，而不是每次敲参数？

在config.ini里写好一次即可，例如：

[gamdl] song_codec_priority = alac,aac-web music_video_resolution = 2160p output_path = /path/to/music

现在就去试试

如果你一直想把 Apple Music 里的内容沉淀成一份真正属于自己的本地音乐库，Gamdl 是目前完成度很高的开源方案之一：官方 API 链路保证音质上限，三层架构和 Rust 解密引擎保证稳定与可扩展，几十个配置项又能适配各种整理癖。从今天这条命令开始，把第一张专辑下载下来试试，再按自己的习惯调一调命名模板，很快你就能拥有一套专属的本地无损音乐库了。遇到问题可以去仓库提 issue，作者也欢迎关键 bug 修复的贡献。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析