A command-line app for downloading Apple Music songs, music videos and post videos.

https://nyatanvn.github.io/gamdl/

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 mp4box remux mode, music video downloads, and experimental song codecs.
• MP4Box: Required for mp4box remux mode.
• N_m3u8DL-RE: Required for nm3u8dlre download mode.

1. Install the package gamdl using pip

   pip install gamdl

2. For web interface usage, install additional dependencies:

   pip install -r web_requirements.txt

3. 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.

After cloning this repository from GitHub, you can quickly start the web interface using one of the provided startup scripts:

./start.sh

python3 start.py

Both scripts will:

• Set up a virtual environment (if needed)
• Install required dependencies
• Create necessary directories
• Check for cookies file
• Start the web interface at http://localhost:5000

Run Gamdl with the following command:

gamdl [OPTIONS] URLS...

For a user-friendly web interface, run:

python web_app.py

Then open your browser to http://localhost:5000

• User-Friendly GUI: Easy-to-use web interface with drag & drop functionality
• Real-Time Progress: Live download progress tracking with detailed status updates
• Cookie Management: Upload and test Apple Music cookies with automatic validation
• Instant Folder Creation: Downloads organized into timestamped folders immediately
• Live File Saving: Songs saved in real-time as they complete
• Basic & Advanced Modes:
  • Basic Mode: Simplified interface with sensible defaults
  • Advanced Mode: Full control over all download options
• Dependency Checking: Automatic system dependency verification
• Apple Music Connectivity Testing: Comprehensive cookie and API validation
• Metadata Preview: View song/album information before downloading
• Download Management: Track multiple downloads simultaneously

1. Upload Cookies: Drag and drop your Apple Music cookies file (automatically saved as cookies.txt)
2. Test Connection: Use the "Test Cookies" feature to verify Apple Music connectivity
3. Paste URLs: Add Apple Music URLs (songs, albums, playlists, artists)
4. Preview: Click "Get Preview" to see what will be downloaded
5. Configure: Choose basic or advanced mode and set your preferences
6. Download: Click "Start Download" and watch real-time progress
7. Monitor: View live logs and download status in the web interface

• 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.

The following variables can be used in the template folders/files and/or in the exclude_tags list:

• album
• album_artist
• album_id
• album_sort
• artist
• artist_id
• artist_sort
• comment
• compilation
• composer
• composer_id
• composer_sort
• copyright
• cover
• date: Supports strftime formats. For example, {date:%Y} will be replaced with the year of the release date.
• disc
• disc_total
• gapless
• genre
• genre_id
• lyrics
• media_type
• playlist_artist
• playlist_id
• playlist_title
• playlist_track
• rating
• storefront
• title
• title_id
• title_sort
• track
• track_total
• xid
• all: Skip tagging.

• ffmpeg: Default remuxing mode.
• mp4box: Alternative remuxing mode (doesn't convert closed captions in music videos).

• ytdlp: Default download mode.
• nm3u8dlre: Faster than ytdlp.

• 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.

• h264
• h265
• ask: Prompt to choose available video and audio codecs.

• m4v: Default remux format.
• mp4

• H.264 Resolutions:
  • 240p
  • 360p
  • 480p
  • 540p
  • 720p
  • 1080p
• H.265-only Resolutions:
  • 1440p
  • 2160p

• 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 (requires save_cover to save separately).

You can specify any path for storing a database file of downloaded media. This is useful if you want to avoid waiting for Gamdl to fetch metadata for checking if a media item has already been downloaded.

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)

for download_info in downloader_song.download(media_id="1624945512"):
    # Process download_info as needed
    pass