# Glomatico’s Apple Music Downloader
A Python CLI 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.
* **Artist Support**: Download all albums or music videos from an artist using their link.
* **Highly Customizable**: Extensive configuration options for advanced users.
## Prerequisites
* **Python 3.9 or higher** installed on your system.
* The **cookies file** of your Apple Music browser session in Netscape format (requires an active subscription).
* **Firefox**: Use the [Export Cookies](https://addons.mozilla.org/addon/export-cookies-txt) extension.
* **Chromium-based Browsers**: Use the [Open Cookies.txt](https://chromewebstore.google.com/detail/open-cookiestxt/gdocmgbfkjnnpapoeobnolbbkoibbcif) extension.
* **FFmpeg** on your system PATH.
* **Windows**: Download from [AnimMouse’s FFmpeg Builds](https://github.com/AnimMouse/ffmpeg-stable-autobuild/releases).
* **Linux**: Download from [John Van Sickle’s FFmpeg Builds](https://johnvansickle.com/ffmpeg/).
### Optional dependencies
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](https://www.bento4.com/downloads/): Required for `mp4box` remux mode, music video downloads, and experimental song codecs.
* [MP4Box](https://gpac.io/downloads/gpac-nightly-builds/): Required for `mp4box` remux mode.
* [N_m3u8DL-RE](https://github.com/nilaoda/N_m3u8DL-RE/releases/latest): Required for `nm3u8dlre` download mode.
## Installation
1. Install the package `gamdl` using pip
```bash
pip install gamdl
```
2. 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.
## Usage
Run Gamdl with the following command:
```bash
gamdl [OPTIONS] URLS...
```
### Supported URL types
* Song
* Album
* Playlist
* Music video
* Artist
* Post video
### Examples
* Download a Song:
```bash
gamdl "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
```
* Download an Album:
```bash
gamdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"
```
* Download from an Artist:
```bash
gamdl "https://music.apple.com/us/artist/rick-astley/669771"
```
### Interactive prompt controls
* **Arrow keys**: Move selection
* **Space**: Toggle selection
* **Ctrl + A**: Select all
* **Enter**: Confirm selection
## Configuration
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.json` on Linux and `%USERPROFILE%\.gamdl\config.json` 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` |
| `--save-cover`, `-s` / `save_cover` | Save cover as a separate file. | `false` |
| `--overwrite` / `overwrite` | Overwrite existing files. | `false` |
| `--read-urls-as-txt`, `-r` / - | Interpret URLs as paths to text files containing URLs separated by newlines. | `false` |
| `--save-playlist` / `save_playlist` | Save a M3U8 playlist file when downloading a playlist. | `false` |
| `--synced-lyrics-only` / `synced_lyrics_only` | Download only the synced lyrics. | `false` |
| `--no-synced-lyrics` / `no_synced_lyrics` | Don't download the synced lyrics. | `false` |
| `--config-path` / - | Path to config file. | `<home>/.gamdl/config.json` |
| `--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` |
| `--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_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` | Music video codec. | `h264` |
| `--quality-post` / `quality_post` | Post video quality. | `best` |
| `--no-config-file`, `-n` / - | Do not use a config file. | `false` |
### Tags variables
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`
* `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`
### Remux Modes
* `ffmpeg`: Default remuxing mode.
* `mp4box`: Alternative remuxing mode (doesn’t convert closed captions in music videos).
### Download modes
* `ytdlp`: Default download mode.
* `nm3u8dlre`: Faster than `ytdlp`.
### Song Codecs
* 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.
* `ask`: Prompt to choose available audio codec.
### Music Videos Codecs
* `h264`: Up to 1080p with AAC 256kbps.
* `h265`: Up to 2160p with AAC 256kpbs.
* `ask`: Prompt to choose available video and audio codecs.
### Post videos/extra videos qualities
* `best`: Up to 1080p with AAC 256kbps.
* `ask`: Prompt to choose available video quality.
### Synced lyrics formats
* `lrc`: Lightweight and widely supported.
* `srt`: SubRip format (has more accurate timestamps).
* `ttml`: Native Apple Music format (unsupported by most media players).
### Cover formats
* `jpg`: Default format.
* `png`: Lossless format.
* `raw`: Raw cover without processing (requires `save_cover` to save separately).
Raw data
{
"_id": null,
"home_page": null,
"name": "gamdl",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": null,
"author": "glomatico",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/e8/5d/eaed1b6ef697b3b21d23d79a11d1e292bfd317738480ad6a7a864e37d6d6/gamdl-2.4.1.tar.gz",
"platform": null,
"description": "# Glomatico\u2019s Apple Music Downloader\nA Python CLI app for downloading Apple Music songs, music videos and post videos.\n\n**Join our Discord Server:** https://discord.gg/aBjMEZ9tnq\n\n## Features\n* **High-Quality Songs**: Download songs in AAC 256kbps and other codecs.\n* **High-Quality Music Videos**: Download music videos in resolutions up to 4K.\n* **Synced Lyrics**: Download synced lyrics in LRC, SRT, or TTML formats.\n* **Artist Support**: Download all albums or music videos from an artist using their link.\n* **Highly Customizable**: Extensive configuration options for advanced users.\n\n## Prerequisites\n* **Python 3.9 or higher** installed on your system.\n* The **cookies file** of your Apple Music browser session in Netscape format (requires an active subscription).\n * **Firefox**: Use the [Export Cookies](https://addons.mozilla.org/addon/export-cookies-txt) extension.\n * **Chromium-based Browsers**: Use the [Open Cookies.txt](https://chromewebstore.google.com/detail/open-cookiestxt/gdocmgbfkjnnpapoeobnolbbkoibbcif) extension.\n* **FFmpeg** on your system PATH.\n * **Windows**: Download from [AnimMouse\u2019s FFmpeg Builds](https://github.com/AnimMouse/ffmpeg-stable-autobuild/releases).\n * **Linux**: Download from [John Van Sickle\u2019s FFmpeg Builds](https://johnvansickle.com/ffmpeg/).\n\n### Optional dependencies\nThe following tools are optional but required for specific features. Add them to your system\u2019s PATH or specify their paths using command-line arguments or the config file.\n* [mp4decrypt](https://www.bento4.com/downloads/): Required for `mp4box` remux mode, music video downloads, and experimental song codecs.\n* [MP4Box](https://gpac.io/downloads/gpac-nightly-builds/): Required for `mp4box` remux mode.\n* [N_m3u8DL-RE](https://github.com/nilaoda/N_m3u8DL-RE/releases/latest): Required for `nm3u8dlre` download mode.\n \n## Installation\n1. Install the package `gamdl` using pip\n ```bash\n pip install gamdl\n ```\n2. Set up the cookies file.\n * Move the cookies file to the directory where you\u2019ll run Gamdl and rename it to `cookies.txt`.\n * Alternatively, specify the path to the cookies file using command-line arguments or the config file.\n\n## Usage\nRun Gamdl with the following command:\n```bash\ngamdl [OPTIONS] URLS...\n```\n\n### Supported URL types\n* Song\n* Album\n* Playlist\n* Music video\n* Artist\n* Post video\n\n### Examples\n* Download a Song:\n ```bash\n gamdl \"https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512\"\n ```\n* Download an Album:\n ```bash\n gamdl \"https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511\"\n ```\n* Download from an Artist:\n ```bash\n gamdl \"https://music.apple.com/us/artist/rick-astley/669771\"\n ```\n\n### Interactive prompt controls\n* **Arrow keys**: Move selection\n* **Space**: Toggle selection\n* **Ctrl + A**: Select all\n* **Enter**: Confirm selection\n\n## Configuration\nGamdl can be configured by using the command-line arguments or the config file.\n\nThe config file is created automatically when you run Gamdl for the first time at `~/.gamdl/config.json` on Linux and `%USERPROFILE%\\.gamdl\\config.json` on Windows.\n\nConfig file values can be overridden using command-line arguments.\n| Command-line argument / Config file key | Description | Default value |\n| --------------------------------------------------------------- | ---------------------------------------------------------------------------- | ---------------------------- |\n| `--disable-music-video-skip` / `disable_music_video_skip` | Don't skip downloading music videos in albums/playlists. | `false` |\n| `--save-cover`, `-s` / `save_cover` | Save cover as a separate file. | `false` |\n| `--overwrite` / `overwrite` | Overwrite existing files. | `false` |\n| `--read-urls-as-txt`, `-r` / - | Interpret URLs as paths to text files containing URLs separated by newlines. | `false` |\n| `--save-playlist` / `save_playlist` | Save a M3U8 playlist file when downloading a playlist. | `false` |\n| `--synced-lyrics-only` / `synced_lyrics_only` | Download only the synced lyrics. | `false` |\n| `--no-synced-lyrics` / `no_synced_lyrics` | Don't download the synced lyrics. | `false` |\n| `--config-path` / - | Path to config file. | `<home>/.gamdl/config.json` |\n| `--log-level` / `log_level` | Log level. | `INFO` |\n| `--no-exceptions` / `no_exceptions` | Don't print exceptions. | `false` |\n| `--cookies-path`, `-c` / `cookies_path` | Path to .txt cookies file. | `./cookies.txt` |\n| `--language`, `-l` / `language` | Metadata language as an ISO-2A language code (don't always work for videos). | `en-US` |\n| `--output-path`, `-o` / `output_path` | Path to output directory. | `./Apple Music` |\n| `--temp-path` / `temp_path` | Path to temporary directory. | `./temp` |\n| `--wvd-path` / `wvd_path` | Path to .wvd file. | `null` |\n| `--nm3u8dlre-path` / `nm3u8dlre_path` | Path to N_m3u8DL-RE binary. | `N_m3u8DL-RE` |\n| `--mp4decrypt-path` / `mp4decrypt_path` | Path to mp4decrypt binary. | `mp4decrypt` |\n| `--ffmpeg-path` / `ffmpeg_path` | Path to FFmpeg binary. | `ffmpeg` |\n| `--mp4box-path` / `mp4box_path` | Path to MP4Box binary. | `MP4Box` |\n| `--download-mode` / `download_mode` | Download mode. | `ytdlp` |\n| `--remux-mode` / `remux_mode` | Remux mode. | `ffmpeg` |\n| `--cover-format` / `cover_format` | Cover format. | `jpg` |\n| `--template-folder-album` / `template_folder_album` | Template folder for tracks that are part of an album. | `{album_artist}/{album}` |\n| `--template-folder-compilation` / `template_folder_compilation` | Template folder for tracks that are part of a compilation album. | `Compilations/{album}` |\n| `--template-file-single-disc` / `template_file_single_disc` | Template file for the tracks that are part of a single-disc album. | `{track:02d} {title}` |\n| `--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}` |\n| `--template-folder-no-album` / `template_folder_no_album` | Template folder for the tracks that are not part of an album. | `{artist}/Unknown Album` |\n| `--template-file-no-album` / `template_file_no_album` | Template file for the tracks that are not part of an album. | `{title}` |\n| `--template-file-playlist` / `template_file_playlist` | Template file for the M3U8 playlist. | `Playlists/{playlist_title}` |\n| `--template-date` / `template_date` | Date tag template. | `%Y-%m-%dT%H:%M:%SZ` |\n| `--exclude-tags` / `exclude_tags` | Comma-separated tags to exclude. | `null` |\n| `--cover-size` / `cover_size` | Cover size. | `1200` |\n| `--truncate` / `truncate` | Maximum length of the file/folder names. | `null` |\n| `--codec-song` / `codec_song` | Song codec. | `aac-legacy` |\n| `--synced-lyrics-format` / `synced_lyrics_format` | Synced lyrics format. | `lrc` |\n| `--codec-music-video` / `codec_music_video` | Music video codec. | `h264` |\n| `--quality-post` / `quality_post` | Post video quality. | `best` |\n| `--no-config-file`, `-n` / - | Do not use a config file. | `false` |\n\n\n### Tags variables\nThe following variables can be used in the template folders/files and/or in the `exclude_tags` list:\n* `album`\n* `album_artist`\n* `album_id`\n* `album_sort`\n* `artist`\n* `artist_id`\n* `artist_sort`\n* `comment`\n* `compilation`\n* `composer`\n* `composer_id`\n* `composer_sort`\n* `copyright`\n* `cover`\n* `date`\n* `disc`\n* `disc_total`\n* `gapless`\n* `genre`\n* `genre_id`\n* `lyrics`\n* `media_type`\n* `playlist_artist`\n* `playlist_id`\n* `playlist_title`\n* `playlist_track`\n* `rating`\n* `storefront`\n* `title`\n* `title_id`\n* `title_sort`\n* `track`\n* `track_total`\n* `xid`\n\n### Remux Modes\n* `ffmpeg`: Default remuxing mode.\n* `mp4box`: Alternative remuxing mode (doesn\u2019t convert closed captions in music videos).\n\n### Download modes\n* `ytdlp`: Default download mode.\n* `nm3u8dlre`: Faster than `ytdlp`.\n\n### Song Codecs\n* Supported Codecs:\n * `aac-legacy`: AAC 256kbps 44.1kHz.\n * `aac-he-legacy`: AAC-HE 64kbps 44.1kHz.\n* Experimental Codecs (not guaranteed to work due to API limitations):\n * `aac`: AAC 256kbps up to 48kHz.\n * `aac-he`: AAC-HE 64kbps up to 48kHz.\n * `aac-binaural`: AAC 256kbps binaural.\n * `aac-downmix`: AAC 256kbps downmix.\n * `aac-he-binaural`: AAC-HE 64kbps binaural.\n * `aac-he-downmix`: AAC-HE 64kbps downmix.\n * `atmos`: Dolby Atmos 768kbps.\n * `ac3`: AC3 640kbps.\n * `alac`: ALAC up to 24-bit/192 kHz.\n * `ask`: Prompt to choose available audio codec.\n\n### Music Videos Codecs\n* `h264`: Up to 1080p with AAC 256kbps.\n* `h265`: Up to 2160p with AAC 256kpbs.\n* `ask`: Prompt to choose available video and audio codecs.\n \n### Post videos/extra videos qualities\n* `best`: Up to 1080p with AAC 256kbps.\n* `ask`: Prompt to choose available video quality.\n\n### Synced lyrics formats\n* `lrc`: Lightweight and widely supported.\n* `srt`: SubRip format (has more accurate timestamps).\n* `ttml`: Native Apple Music format (unsupported by most media players).\n \n### Cover formats\n* `jpg`: Default format.\n* `png`: Lossless format.\n* `raw`: Raw cover without processing (requires `save_cover` to save separately).\n",
"bugtrack_url": null,
"license": null,
"summary": "A Python CLI app for downloading Apple Music songs, music videos and post videos.",
"version": "2.4.1",
"project_urls": {
"homepage": "https://github.com/glomatico/gamdl",
"repository": "https://github.com/glomatico/gamdl"
},
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "127d840277ca316f32ae936473065216d4e67600862d7a754d29f76cfd8ac330",
"md5": "d57529b3186c0d481073b34907d44180",
"sha256": "1b36ea9601d3c79a744dbdb869f31fa5c59efdf6933ff4e54ac57901857520d7"
},
"downloads": -1,
"filename": "gamdl-2.4.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d57529b3186c0d481073b34907d44180",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 34342,
"upload_time": "2025-02-23T07:38:11",
"upload_time_iso_8601": "2025-02-23T07:38:11.812128Z",
"url": "https://files.pythonhosted.org/packages/12/7d/840277ca316f32ae936473065216d4e67600862d7a754d29f76cfd8ac330/gamdl-2.4.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "e85deaed1b6ef697b3b21d23d79a11d1e292bfd317738480ad6a7a864e37d6d6",
"md5": "8183f10bc81e06360c00c2368421dc05",
"sha256": "40e813a5974e5bd0fbee121671aafc855533c86f13aaa2c3442a622cc4fd712e"
},
"downloads": -1,
"filename": "gamdl-2.4.1.tar.gz",
"has_sig": false,
"md5_digest": "8183f10bc81e06360c00c2368421dc05",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 32618,
"upload_time": "2025-02-23T07:38:12",
"upload_time_iso_8601": "2025-02-23T07:38:12.985459Z",
"url": "https://files.pythonhosted.org/packages/e8/5d/eaed1b6ef697b3b21d23d79a11d1e292bfd317738480ad6a7a864e37d6d6/gamdl-2.4.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-23 07:38:12",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "glomatico",
"github_project": "gamdl",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "click",
"specs": []
},
{
"name": "colorama",
"specs": []
},
{
"name": "inquirerpy",
"specs": []
},
{
"name": "m3u8",
"specs": []
},
{
"name": "mutagen",
"specs": []
},
{
"name": "pillow",
"specs": []
},
{
"name": "pywidevine",
"specs": []
},
{
"name": "pyyaml",
"specs": []
},
{
"name": "termcolor",
"specs": []
},
{
"name": "yt-dlp",
"specs": []
}
],
"lcname": "gamdl"
}
JSON
