gamdl
Advanced tools
A command-line app for downloading Apple Music songs, music videos and post videos.
Join our Discord Server: https://discord.gg/aBjMEZ9tnq
Add these tools to your system PATH for additional features:
mp4box remux mode, music videos, and experimental codecsmp4box remux modenm3u8dlre download mode, which is faster than the default downloaderInstall Gamdl via pipx:
pipx is recommended for installing Gamdl to avoid dependency conflicts, but you can also use pip.
pipx install gamdl
Setup cookies:
cookies.txt, or--cookies-path or in the config filegamdl [OPTIONS] URLS...
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"
Interactive Prompt Controls:
| Key | Action |
|---|---|
| Arrow keys | Move selection |
| Space | Toggle selection |
| Ctrl + A | Select all |
| Enter | Confirm selection |
Configure Gamdl using command-line arguments or a config file.
Config file location:
~/.gamdl/config.ini%USERPROFILE%\.gamdl\config.iniThe file is created automatically on first run. Command-line arguments override config values.
| Option | Description | Default |
|---|---|---|
| General Options | ||
--read-urls-as-txt, -r | Read URLs from text files | false |
--config-path | Config file path | <home>/.gamdl/config.ini |
--log-level | Logging level | INFO |
--log-file | Log file path | - |
--no-exceptions | Don't print exceptions | false |
--no-config-file, -n | Don't use a config file | false |
| Apple Music Options | ||
--cookies-path, -c | Cookies file path | ./cookies.txt |
--wrapper-account-url | Wrapper account URL | http://127.0.0.1:30020 |
--language, -l | Metadata language | en-US |
| Output Options | ||
--output-path, -o | Output directory path | ./Apple Music |
--temp-path | Temporary directory path | . |
--wvd-path | .wvd file path | - |
--overwrite | Overwrite existing files | false |
--save-cover, -s | Save cover as separate file | false |
--save-playlist | Save M3U8 playlist file | false |
| Download Options | ||
--nm3u8dlre-path | N_m3u8DL-RE executable path | N_m3u8DL-RE |
--mp4decrypt-path | mp4decrypt executable path | mp4decrypt |
--ffmpeg-path | FFmpeg executable path | ffmpeg |
--mp4box-path | MP4Box executable path | MP4Box |
--amdecrypt-path | amdecrypt executable path | amdecrypt |
--use-wrapper | Use wrapper and amdecrypt | false |
--wrapper-decrypt-ip | Wrapper decryption server IP | 127.0.0.1:10020 |
--download-mode | Download mode | ytdlp |
--remux-mode | Remux mode | ffmpeg |
--cover-format | Cover format | jpg |
| Template Options | ||
--album-folder-template | Album folder template | {album_artist}/{album} |
--compilation-folder-template | Compilation folder template | Compilations/{album} |
--no-album-folder-template | No album folder template | {artist}/Unknown Album |
--single-disc-file-template | Single disc file template | {track:02d} {title} |
--multi-disc-file-template | Multi disc file template | {disc}-{track:02d} {title} |
--no-album-file-template | No album file template | {title} |
--playlist-file-template | Playlist file template | Playlists/{playlist_artist}/{playlist_title} |
--date-tag-template | Date tag template | %Y-%m-%dT%H:%M:%SZ |
--exclude-tags | Comma-separated tags to exclude | - |
--cover-size | Cover size in pixels | 1200 |
--truncate | Max filename length | - |
| Song Options | ||
--song-codec | Song codec | aac-legacy |
--synced-lyrics-format | Synced lyrics format | lrc |
--no-synced-lyrics | Don't download synced lyrics | false |
--synced-lyrics-only | Download only synced lyrics | false |
| Music Video Options | ||
--music-video-codec-priority | Comma-separated codec priority | h264,h265 |
--music-video-remux-format | Music video remux format | m4v |
--music-video-resolution | Max music video resolution | 1080p |
| Post Video Options | ||
--uploaded-video-quality | Post video quality | best |
Use these variables in folder/file templates or --exclude-tags:
| Variable | Description |
|---|---|
{album}, {album_artist}, {album_id}, {album_sort} | Album info |
{artist}, {artist_id}, {artist_sort} | Artist info |
{title}, {title_id}, {title_sort} | Title info |
{composer}, {composer_id}, {composer_sort} | Composer info |
{track}, {track_total}, {disc}, {disc_total} | Track numbers |
{genre}, {genre_id} | Genre info |
{date} | Release date (supports strftime: {date:%Y}) |
{playlist_artist}, {playlist_id}, {playlist_title}, {playlist_track} | Playlist info |
{compilation}, {gapless}, {rating} | Media properties |
{comment}, {copyright}, {lyrics}, {cover} | Additional metadata |
{media_type}, {storefront}, {xid} | Technical info |
all | Special: Skip all tagging |
DEBUG, INFO, WARNING, ERRORytdlp, nm3u8dlreffmpegmp4box - Preserve the original closed caption track in music videos and some other minor metadatajpgpngraw - Raw format as provided by the artist (requires save_cover to be enabled as it doesn't embed covers into files)Use ISO 639-1 language codes (e.g., en-US, es-ES, ja-JP, pt-BR). Don't always work for music videos.
Stable:
aac-legacy - AAC 256kbps 44.1kHzaac-he-legacy - AAC-HE 64kbps 44.1kHzExperimental (may not work due to API limitations):
aac - AAC 256kbps up to 48kHzaac-he - AAC-HE 64kbps up to 48kHzaac-binaural - AAC 256kbps binauralaac-downmix - AAC 256kbps downmixaac-he-binaural - AAC-HE 64kbps binauralaac-he-downmix - AAC-HE 64kbps downmixatmos - Dolby Atmos 768kbpsac3 - AC3 640kbpsalac - ALAC up to 24-bit/192kHz (unsupported)ask - Interactive experimental codec selectionlrcsrt - SubRip subtitle format (more accurate timing)ttml - Native Apple Music format (not compatible with most media players)h264h265ask - Interactive codec selection240p, 360p, 480p, 540p, 720p, 1080p1440p, 2160pm4v, mp4best - Up to 1080p with AAC 256kbpsask - Interactive quality selectionUse the wrapper and amdecrypt to download songs in ALAC and other experimental codecs without API limitations. Cookies are not required when using the wrapper.
--use-wrapper flag or set use_wrapper = true in configUse Gamdl as a library in your Python projects:
import asyncio
from gamdl.api import AppleMusicApi, ItunesApi
from gamdl.downloader import (
AppleMusicBaseDownloader,
AppleMusicDownloader,
AppleMusicMusicVideoDownloader,
AppleMusicSongDownloader,
AppleMusicUploadedVideoDownloader,
)
from gamdl.interface import (
AppleMusicInterface,
AppleMusicMusicVideoInterface,
AppleMusicSongInterface,
AppleMusicUploadedVideoInterface,
)
async def main():
# Create AppleMusicApi instance (from cookies or wrapper)
apple_music_api = await AppleMusicApi.create_from_netscape_cookies(
cookies_path="cookies.txt",
)
itunes_api = ItunesApi(
apple_music_api.storefront,
apple_music_api.language,
)
# Check subscription
assert apple_music_api.active_subscription
# Set up interfaces
interface = AppleMusicInterface(apple_music_api, itunes_api)
song_interface = AppleMusicSongInterface(interface)
music_video_interface = AppleMusicMusicVideoInterface(interface)
uploaded_video_interface = AppleMusicUploadedVideoInterface(interface)
# Set up base downloader and specialized downloaders
base_downloader = AppleMusicBaseDownloader()
song_downloader = AppleMusicSongDownloader(
base_downloader=base_downloader,
interface=song_interface,
)
music_video_downloader = AppleMusicMusicVideoDownloader(
base_downloader=base_downloader,
interface=music_video_interface,
)
uploaded_video_downloader = AppleMusicUploadedVideoDownloader(
base_downloader=base_downloader,
interface=uploaded_video_interface,
)
# Main downloader
downloader = AppleMusicDownloader(
interface=interface,
base_downloader=base_downloader,
song_downloader=song_downloader,
music_video_downloader=music_video_downloader,
uploaded_video_downloader=uploaded_video_downloader,
)
# Download a song
url = "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
url_info = downloader.get_url_info(url)
if url_info:
download_queue = await downloader.get_download_queue(url_info)
if download_queue:
for download_item in download_queue:
await downloader.download(download_item)
if __name__ == "__main__":
asyncio.run(main())
MIT License - see LICENSE file for details
Currently, I'm not interested in reviewing pull requests that change or add features. Only critical bug fixes will be considered. However, feel free to open issues for bugs or feature requests.
FAQs
A command-line app for downloading Apple Music songs, music videos and post videos.
We found that gamdl demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
/Security News
Impostor NuGet package Tracer.Fody.NLog typosquats Tracer.Fody and its author, using homoglyph tricks, and exfiltrates Stratis wallet JSON/passwords to a Russian IP address.
Security News
Deno 2.6 introduces deno audit with a new --socket flag that plugs directly into Socket to bring supply chain security checks into the Deno CLI.
Security News
New DoS and source code exposure bugs in React Server Components and Next.js: what’s affected and how to update safely.