Gamdl (Glomatico's Apple Music Downloader)
A command-line app for downloading Apple Music songs, music videos and post videos.
Join our Discord Server: https://discord.gg/aBjMEZ9tnq
✨ Features
- 🎵 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
- 🏷️ Rich Metadata - Automatic tagging with comprehensive metadata
- 🎤 Artist Support - Download all albums or music videos from an artist
- ⚙️ Highly Customizable - Extensive configuration options for advanced users
📋 Prerequisites
Required
- Python 3.10 or higher
- Active Apple Music subscription
- Apple Music Cookies - export your browser cookies in Netscape format while logged in at Apple Music:
- Firefox: Export Cookies
- Chromium: Get cookies.txt LOCALLY
Optional Dependencies
Wrapper
Run the Wrapper v2 server for wrapper-backed account, playback, and decryption requests. Enable it with --use-wrapper or use_wrapper = true. Configure wrapper HTTP account/playback calls with --wrapper-url or wrapper_url, and configure WV2D batch TCP decrypt with --wrapper-decrypt-host / --wrapper-decrypt-port.
gamdl builds a private Rust extension from gamdl/downloader/ammuxer as gamdl._ammuxer. That native media engine handles wrapper TCP decrypt/reassembly plus MP4/M4A writing and muxing; Python remains responsible for the CLI, downloads, metadata tagging, and high-level orchestration.
The wrapper is recommended when using the alac song codec. ALAC can be attempted without wrapper, but it probably won't work due to API limitations.
Note:
- When using the Wrapper, you'll be asked to insert your credentials to login if you haven't already.
- Newer wrapper-v2 builds use HTTP JSON for account/playback and WV2D batch TCP port
10020for decrypt. - For music videos, wrapper playback can provide additional metadata when available from Apple, including sort title (
sonm), sort artist (soar), sort album (soal), composer (©wrt), composer ID (cmID), composer sort (soco), comments (©cmt), gapless (pgap), and XID (xid). - Song codecs other than
alacdo not require the wrapper. - Cookies can be skipped when using the wrapper.
N_m3u8DL-RE
Use N_m3u8DL-RE as a faster download alternative to the default yt-dlp download mode. Enable it with --download-mode nm3u8dlre or download_mode = nm3u8dlre.
If the executable is not available in your system PATH, set its location with --nm3u8dlre-path or nm3u8dlre_path.
N_m3u8DL-RE also needs FFmpeg. If the FFmpeg executable is not available in your system PATH, set its location with --ffmpeg-path or ffmpeg_path.
📦 Installation
-
Install Gamdl via pip:
pip install gamdl
-
Set up the cookies file:
- Place the cookies file in the working directory as
cookies.txt, or - Specify the path using
--cookies-pathor in the config file
- Place the cookies file in the working directory as
-
Optional: Set up dependencies (only if you need the functionality) See the Optional Dependencies section to determine which optional tools you need.
🚀 Usage
gamdl [OPTIONS] URLS...
Supported URL Types
- Songs (Catalog/Library)
- Albums (Catalog/Library)
- Playlists (Catalog/Library)
- Music Videos (Catalog/Library)
- Artists
- Post Videos
- Apple Music Classical
Examples
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 |
⚙️ Configuration
Configure Gamdl using command-line arguments or a config file.
Config file location:
- Linux:
~/.gamdl/config.ini - Windows:
%USERPROFILE%\.gamdl\config.ini
The file is created automatically on first run. Command-line arguments override config values.
Configuration Options
| 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 |
--artist-auto-select |
Automatically select artist content to download (artist URLs) | - |
--database-path |
Path to the SQLite database file for registering downloaded media | - |
--no-config-file, -n |
Don't use a config file | false |
| Apple Music Options | ||
--cookies-path, -c |
Cookies file path | ./cookies.txt |
--wrapper-url |
Wrapper HTTP control base URL | http://127.0.0.1 |
--wrapper-decrypt-host |
Wrapper TCP decrypt host | 127.0.0.1 |
--wrapper-decrypt-port |
Wrapper TCP decrypt port | 10020 |
--language, -l |
Metadata language | en-US |
| Interface Options | ||
--cover-format |
Cover format | jpg |
--cover-size |
Cover size in pixels | 1200 |
--drm-backend |
DRM backend (widevine or playready) |
widevine |
--wvd-path |
.wvd file path | - |
--prd-path |
.prd file path | - |
--use-wrapper |
Use wrapper for account, playback, and decryption requests | false |
| Song Options | ||
--synced-lyrics-format |
Synced lyrics format | lrc |
--song-codec-priority |
Comma-separated codec priority | aac-web |
--use-album-date |
Use album release date for songs | false |
--no-synced-lyrics |
Don't download synced lyrics | false |
--synced-lyrics-only |
Download only synced lyrics | false |
| Music Video Options | ||
--music-video-resolution |
Max music video resolution | 1080p |
--music-video-codec-priority |
Comma-separated codec priority | h264,h265 |
--music-video-remux-format |
Music video remux format | m4v |
| Post Video Options | ||
--uploaded-video-quality |
Post video quality | best |
| Download & Path Options | ||
--output-path, -o |
Output directory path | ./Apple Music |
--temp-path |
Temporary directory path | . |
--nm3u8dlre-path |
N_m3u8DL-RE executable path | N_m3u8DL-RE |
--ffmpeg-path |
FFmpeg executable path | ffmpeg |
--download-mode |
Download mode | ytdlp |
| 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 |
--playlist-folder-template |
Playlist folder template | Playlists/{playlist_artist} |
--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 | {playlist_title} |
--date-tag-template |
Date tag template | %Y-%m-%dT%H:%M:%SZ |
--exclude-tags |
Comma-separated tags to exclude | - |
--truncate |
Max filename length | - |
| File Output Options | ||
--overwrite |
Overwrite existing files | false |
--save-cover, -s |
Save cover as separate file | false |
--save-playlist |
Save M3U8 playlist file | false |
Template Variables
Tags for templates and exclude-tags:
album,album_artist,album_idartist,artist_idcomposer,composer_iddate(supports strftime format:{date:%Y})disc,disc_totalmedia_typeplaylist_artist,playlist_id,playlist_title,playlist_tracktitle,title_idtrack,track_total
Tags for exclude-tags only:
album_sort,artist_sort,composer_sort,title_sortcomment,compilation,copyright,cover,gapless,genre,genre_id,lyrics,rating,storefront,xidall(special: skip all tagging)
Logging Level
DEBUG,INFO,WARNING,ERROR
Download Mode
ytdlp,nm3u8dlre
Cover Format
jpgpngraw- Raw format as provided by the artist (requiressave_coverto be enabled as it doesn't embed covers into files)
DRM Backend
widevineplayready
Metadata Language
Use ISO 639-1 language codes (e.g., en-US, es-ES, ja-JP, pt-BR). Don't always work for music videos.
Song Codecs
Web:
aac-web- AAC 256kbps 44.1kHzaac-he-web- AAC-HE 64kbps 44.1kHz
Non-web (alac can be attempted without wrapper, but it probably won't 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/192kHzask- Interactive codec selection
Synced Lyrics Format
lrcsrt- SubRip subtitle format (more accurate timing)ttml- Native Apple Music format (not compatible with most media players)
Music Video Codecs
h264h265ask- Interactive codec selection
Music Video Resolutions
- H.264:
240p,360p,480p,540p,720p,1080p - H.265 only:
1440p,2160p
Music Video Remux Formats
m4v,mp4
Post Video Quality
best- Up to 1080p with AAC 256kbpsask- Interactive quality selection
Artist Auto-Select Options
main-albumscompilation-albumslive-albumssingles-epsall-albumstop-songsmusic-videos
🐍 Embedding
Use Gamdl as a library in your Python projects:
import asyncio
from gamdl.api import AppleMusicApi
from gamdl.downloader import (
AppleMusicBaseDownloader,
AppleMusicDownloader,
AppleMusicMusicVideoDownloader,
AppleMusicSongDownloader,
AppleMusicUploadedVideoDownloader,
)
from gamdl.interface import (
AppleMusicBaseInterface,
AppleMusicInterface,
AppleMusicMusicVideoInterface,
AppleMusicSongInterface,
AppleMusicUploadedVideoInterface,
)
async def main():
# Create AppleMusicApi instance from cookies
apple_music_api = await AppleMusicApi.create_from_netscape_cookies(
cookies_path="cookies.txt",
)
# Check subscription
if not apple_music_api.active_subscription:
print("No active Apple Music subscription")
return
# Create base interface
base_interface = await AppleMusicBaseInterface.create(
apple_music_api=apple_music_api,
)
# Create specialized interfaces
song_interface = AppleMusicSongInterface(
base=base_interface,
)
music_video_interface = AppleMusicMusicVideoInterface(
base=base_interface,
)
uploaded_video_interface = AppleMusicUploadedVideoInterface(
base=base_interface,
)
# Create main interface
interface = AppleMusicInterface(
song=song_interface,
music_video=music_video_interface,
uploaded_video=uploaded_video_interface,
)
# Create base downloader
base_downloader = AppleMusicBaseDownloader(
interface=interface,
)
# Create specialized downloaders
song_downloader = AppleMusicSongDownloader(base=base_downloader)
music_video_downloader = AppleMusicMusicVideoDownloader(
base=base_downloader,
)
uploaded_video_downloader = AppleMusicUploadedVideoDownloader(base=base_downloader)
# Create main downloader
downloader = AppleMusicDownloader(
song=song_downloader,
music_video=music_video_downloader,
uploaded_video=uploaded_video_downloader,
)
# Download from URL
url = "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
download_queue = []
async for media in downloader.get_download_item_from_url(url):
download_queue.append(media)
for download_item in download_queue:
try:
await downloader.download(download_item)
except Exception as e:
print(f"Error downloading: {e}")
if __name__ == "__main__":
asyncio.run(main())
📄 License
MIT License - see LICENSE file for details
🤝 Contributing
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.
1 maintainer
Release files for gamdl 3.9.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| gamdl-3.9.1.tar.gz | 80.2 kB | Details |
Built distributions (wheels)
| File | Reset | |||
|---|---|---|---|---|
| gamdl-3.9.1-cp310-abi3-win_arm64.whl | CPython 3.10 | abi3 | Windows ARM64 | Details |
| gamdl-3.9.1-cp310-abi3-win_amd64.whl | CPython 3.10 | abi3 | Windows x86-64 | Details |
| gamdl-3.9.1-cp310-abi3-manylinux_2_34_x86_64.whl | CPython 3.10 | abi3 | Linux glibc 2.34+ x86-64 | Details |
| gamdl-3.9.1-cp310-abi3-manylinux_2_34_aarch64.whl | CPython 3.10 | abi3 | Linux glibc 2.34+ ARM64 | Details |
| gamdl-3.9.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl | CPython 3.10 | abi3 | macOS 10.12+ x86-64, macOS 10.12+ universal2 (ARM64, x86-64), macOS 11.0+ ARM64 | Details |
Total release size: 2.6 MB
Release files / gamdl-3.9.1.tar.gz
| Download URL | gamdl-3.9.1.tar.gz |
|---|---|
| Size | 80.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
9b119e26a337b3b51ebd0af302cbf80586ec9317d7eefa493eca4d87360bc92b
|
|
BLAKE2b-256 checksum How to use checksums |
f529909a6423a026ec770e911a6479217fb2dc7e60f32b89c7a5e40b228c1f8b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / gamdl-3.9.1-cp310-abi3-win_arm64.whl
| Download URL | gamdl-3.9.1-cp310-abi3-win_arm64.whl |
|---|---|
| Size | 360.5 kB |
| Tags | CPython 3.10 Windows ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
f464d8fab5a6e3f15f297f427cb391a733187cb131a60ea5670897df83eeb170
|
|
BLAKE2b-256 checksum How to use checksums |
51d8d3cb2691a266fefea954d06a0d1f393c17d4ce73942c1576b348054eafc9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / gamdl-3.9.1-cp310-abi3-win_amd64.whl
| Download URL | gamdl-3.9.1-cp310-abi3-win_amd64.whl |
|---|---|
| Size | 371.1 kB |
| Tags | CPython 3.10 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
b93aa3f8b6418441120977395bd87cb2839a4c8e7922951647b49d793db9838c
|
|
BLAKE2b-256 checksum How to use checksums |
0d1060745f1ae66e1344982f0e8b01c2383c5069e81920e822e06a32da59d1fc
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / gamdl-3.9.1-cp310-abi3-manylinux_2_34_x86_64.whl
| Download URL | gamdl-3.9.1-cp310-abi3-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 507.3 kB |
| Tags | CPython 3.10 Linux glibc 2.34+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
ee6f8af0775ccb07040632cc09e8f33ebde67133c9e7e0e06cf05f93c44f1cd3
|
|
BLAKE2b-256 checksum How to use checksums |
3aba2ba6bc356c250479e6c21518d5cee7f9f926d122c8f67a892cf0c18ff3e2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / gamdl-3.9.1-cp310-abi3-manylinux_2_34_aarch64.whl
| Download URL | gamdl-3.9.1-cp310-abi3-manylinux_2_34_aarch64.whl |
|---|---|
| Size | 495.6 kB |
| Tags | CPython 3.10 Linux glibc 2.34+ ARM64 abi3 |
|
SHA-256 checksum How to use checksums |
4cb7341cbc5302e5168019232f2d668f2c07cabee61aacb1c8ca0d81abb51493
|
|
BLAKE2b-256 checksum How to use checksums |
2deef755d3db320ac3bed0795302255dd61b5252372da64c7ddb446c999d412a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency logRelease files / gamdl-3.9.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl
| Download URL | gamdl-3.9.1-cp310-abi3-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl |
|---|---|
| Size | 825.1 kB |
| Tags | CPython 3.10 abi3 macOS 10.12+ universal2 (ARM64, x86-64) macOS 10.12+ x86-64 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
8d6fd6ae73bd443eaf9fce603f57acdbc2ddd6d156279e07fda81207be426c53
|
|
BLAKE2b-256 checksum How to use checksums |
3d49d69fff3fd5a4b7c9db84e7d2f255c3b312645eb945dc1d41f98345de976b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 22, 2026.
Transparency log
