A command-line app for downloading Apple Music songs, music videos and post videos.
Join our Discord Server: https://discord.gg/aBjMEZ9tnq
- High-Quality Songs: Download songs in AAC 256kbps and other codecs.
- High-Quality Music Videos: Download music videos in resolutions up to 4K.
- Synced Lyrics: Download synced lyrics in LRC, SRT, or TTML formats.
- Artist Support: Download all albums or music videos from an artist using their link.
- Highly Customizable: Extensive configuration options for advanced users.
- Python 3.10 or higher installed on your system.
- The cookies file of your Apple Music browser session in Netscape format. Use one of the following extensions at the Apple Music homepage while logged in and with an active subscription to export the cookies:
- Firefox: Export Cookies.
- Chromium-based Browsers: Get cookies.txt LOCALLY.
- FFmpeg on your system PATH. Use one of the recommended builds:
- Windows: AnimMouse's FFmpeg Builds.
- Linux: John Van Sickle's FFmpeg Builds.
The following tools are optional but required for specific features. Add them to your system's PATH or specify their paths using command-line arguments or the config file.
- mp4decrypt: Required for
mp4boxremux mode, music video downloads, and experimental song codecs. - MP4Box: Required for
mp4boxremux mode. - N_m3u8DL-RE: Required for
nm3u8dlredownload mode.
-
Install the package
gamdlusing pippip install gamdl
-
Set up the cookies file.
- Move the cookies file to the directory where you'll run Gamdl and rename it to
cookies.txt. - Alternatively, specify the path to the cookies file using command-line arguments or the config file.
- Move the cookies file to the directory where you'll run Gamdl and rename it to
Run Gamdl with the following command:
gamdl [OPTIONS] URLS...- Song
- Public/Library Album
- Public/Library Playlist
- Music video
- Artist
- Post video
-
Download a Song:
gamdl "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512" -
Download an Album:
gamdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511" -
Download from an Artist:
gamdl "https://music.apple.com/us/artist/rick-astley/669771"
- Arrow keys: Move selection
- Space: Toggle selection
- Ctrl + A: Select all
- Enter: Confirm selection
Gamdl can be configured by using the command-line arguments or the config file.
The config file is created automatically when you run Gamdl for the first time at ~/.gamdl/config.ini on Linux and %USERPROFILE%\.gamdl\config.ini on Windows.
Config file values can be overridden using command-line arguments.
| Command-line argument / Config file key | Description | Default value |
|---|---|---|
--disable-music-video-skip / disable_music_video_skip |
Don't skip downloading music videos in albums/playlists. | false |
--read-urls-as-txt, -r / - |
Interpret URLs as paths to text files containing URLs separated by newlines | false |
--config-path / - |
Path to config file. | <home>/.gamdl/config.ini |
--log-level / log_level |
Log level. | INFO |
--no-exceptions / no_exceptions |
Don't print exceptions. | false |
--cookies-path, -c / cookies_path |
Path to .txt cookies file. | ./cookies.txt |
--language, -l / language |
Metadata language as an ISO-2A language code (don't always work for videos). | en-US |
--output-path, -o / output_path |
Path to output directory. | ./Apple Music |
--temp-path / temp_path |
Path to temporary directory. | ./temp |
--wvd-path / wvd_path |
Path to .wvd file. | null |
--overwrite / overwrite |
Overwrite existing files. | false |
--save-cover, -s / save_cover |
Save cover as a separate file. | false |
--save-playlist / save_playlist |
Save a M3U8 playlist file when downloading a playlist. | false |
--no-synced-lyrics / no_synced_lyrics |
Don't download the synced lyrics. | false |
--synced-lyrics-only / synced_lyrics_only |
Download only the synced lyrics. | false |
--nm3u8dlre-path / nm3u8dlre_path |
Path to N_m3u8DL-RE binary. | N_m3u8DL-RE |
--mp4decrypt-path / mp4decrypt_path |
Path to mp4decrypt binary. | mp4decrypt |
--ffmpeg-path / ffmpeg_path |
Path to FFmpeg binary. | ffmpeg |
--mp4box-path / mp4box_path |
Path to MP4Box binary. | MP4Box |
--download-mode / download_mode |
Download mode. | ytdlp |
--remux-mode / remux_mode |
Remux mode. | ffmpeg |
--cover-format / cover_format |
Cover format. | jpg |
--template-folder-album / template_folder_album |
Template folder for tracks that are part of an album. | {album_artist}/{album} |
--template-folder-compilation / template_folder_compilation |
Template folder for tracks that are part of a compilation album. | Compilations/{album} |
--template-file-single-disc / template_file_single_disc |
Template file for the tracks that are part of a single-disc album. | {track:02d} {title} |
--template-file-multi-disc / template_file_multi_disc |
Template file for the tracks that are part of a multi-disc album. | {disc}-{track:02d} {title} |
--template-folder-no-album / template_folder_no_album |
Template folder for the tracks that are not part of an album. | {artist}/Unknown Album |
--template-file-no-album / template_file_no_album |
Template file for the tracks that are not part of an album. | {title} |
--template-file-playlist / template_file_playlist |
Template file for the M3U8 playlist. | Playlists/{playlist_artist}/{playlist_title} |
--template-date / template_date |
Date tag template. | %Y-%m-%dT%H:%M:%SZ |
--exclude-tags / exclude_tags |
Comma-separated tags to exclude. | null |
--cover-size / cover_size |
Cover size. | 1200 |
--truncate / truncate |
Maximum length of the file/folder names. | null |
--codec-song / codec_song |
Song codec. | aac-legacy |
--synced-lyrics-format / synced_lyrics_format |
Synced lyrics format. | lrc |
--codec-music-video / codec_music_video |
Comma-separated music video codec priority. | h264,h265 |
--remux-format-music-video / remux_format_music_video |
Music video remux format. | m4v |
--quality-post / quality_post |
Post video quality. | best |
--resolution / resolution |
Target video resolution for music videos. | 1080p |
--no-config-file, -n / - |
Do not use a config file. | false |
The following variables can be used in the template folders/files and/or in the exclude_tags list:
albumalbum_artistalbum_idalbum_sortartistartist_idartist_sortcommentcompilationcomposercomposer_idcomposer_sortcopyrightcoverdate: Supports strftime formats. For example,{date:%Y}will be replaced with the year of the release date.discdisc_totalgaplessgenregenre_idlyricsmedia_typeplaylist_artistplaylist_idplaylist_titleplaylist_trackratingstorefronttitletitle_idtitle_sorttracktrack_totalxidall: Skip tagging.
ffmpeg: Default remuxing mode.mp4box: Alternative remuxing mode (doesn't convert closed captions in music videos).
ytdlp: Default download mode.nm3u8dlre: Faster thanytdlp.
- Supported Codecs:
aac-legacy: AAC 256kbps 44.1kHz.aac-he-legacy: AAC-HE 64kbps 44.1kHz.
- Experimental Codecs (not guaranteed to work due to API limitations):
aac: AAC 256kbps up to 48kHz.aac-he: AAC-HE 64kbps up to 48kHz.aac-binaural: AAC 256kbps binaural.aac-downmix: AAC 256kbps downmix.aac-he-binaural: AAC-HE 64kbps binaural.aac-he-downmix: AAC-HE 64kbps downmix.atmos: Dolby Atmos 768kbps.ac3: AC3 640kbps.alac: ALAC up to 24-bit/192 kHz (no reports of successful downloads have been made).ask: Prompt to choose available audio codec.
h264h265ask: Prompt to choose available video and audio codecs.
m4v: Default remux format.mp4
- H.264 Resolutions:
240p360p480p540p720p1080p
- H.265-only Resolutions:
1440p2160p
best: Up to 1080p with AAC 256kbps.ask: Prompt to choose available video quality.
lrc: Lightweight and widely supported.srt: SubRip format (has more accurate timestamps).ttml: Native Apple Music format (unsupported by most media players).
jpg: Default format.png: Lossless format.raw: Raw cover without processing (requiressave_coverto save separately).
Gamdl can be used as a library in Python scripts. Here's a basic example of downloading a song by its ID:
from gamdl import AppleMusicApi, ItunesApi, Downloader, DownloaderSong
apple_music_api = AppleMusicApi.from_netscape_cookies(cookies_path="cookies.txt")
itunes_api = ItunesApi(
storefront=apple_music_api.storefront,
language=apple_music_api.language,
)
downloader = Downloader(
apple_music_api=apple_music_api,
itunes_api=itunes_api,
)
downloader.set_cdm()
downloader_song = DownloaderSong(downloader=downloader)
downloader_song.download(media_id="1624945512")