2024-04-08 10:11:22 +00:00
# Glomatico's Apple Music Downloader
2024-05-20 07:08:22 +00:00
A Python CLI app for downloading Apple Music songs/music videos/posts.
2022-12-11 04:23:47 +00:00
2024-04-14 16:26:03 +00:00
**Discord Server:** https://discord.gg/aBjMEZ9tnq
2023-09-30 04:14:32 +00:00
## Features
2024-05-25 04:49:38 +00:00
* Download songs in AAC 256kbps and other codecs
2023-09-30 04:14:32 +00:00
* Download music videos up to 4K
2024-04-08 18:08:11 +00:00
* Download synced lyrics in LRC, SRT or TTML
2023-10-02 19:56:26 +00:00
* Choose between FFmpeg and MP4Box for remuxing
2023-09-30 04:14:32 +00:00
* Choose between yt-dlp and N_m3u8DL-RE for downloading
2023-09-30 17:00:05 +00:00
* Highly customizable
2024-04-23 03:00:25 +00:00
* Use artist links to download all of their albums or music videos
2024-04-08 10:09:57 +00:00
## Prerequisites
* Python 3.8 or higher
2024-05-20 07:06:37 +00:00
* The cookies file of your Apple Music browser session (requires an active subscription)
2024-04-08 10:09:57 +00:00
* You can get your cookies by using one of the following extensions on your browser of choice at the Apple Music website with your account signed in:
* Firefox: https://addons.mozilla.org/addon/export-cookies-txt
* Chromium based browsers: https://chrome.google.com/webstore/detail/gdocmgbfkjnnpapoeobnolbbkoibbcif
* FFmpeg on your system PATH
* Older versions of FFmpeg may not work.
* Up to date binaries can be obtained from the links below:
* Windows: https://github.com/AnimMouse/ffmpeg-stable-autobuild/releases
* Linux: https://johnvansickle.com/ffmpeg/
* (Optional) mp4decrypt on your system PATH
* Required to download music videos and songs in non-legacy formats.
* Binaries can be obtained from here: https://www.bento4.com/downloads/.
2023-09-30 04:14:32 +00:00
## Installation
2024-04-08 10:09:57 +00:00
1. Install the package `gamdl` using pip
2023-09-30 04:14:32 +00:00
```bash
pip install gamdl
```
2024-04-11 09:59:14 +00:00
2. Place your cookies file in the directory from which you will be running gamdl and name it `cookies.txt` .
2023-02-04 23:40:07 +00:00
2024-04-08 10:09:57 +00:00
## Usage
2024-04-11 09:49:32 +00:00
```bash
gamdl [OPTIONS] URLS...
```
### Examples
2023-08-27 03:48:02 +00:00
* Download a song
2023-09-30 04:14:32 +00:00
```bash
2024-04-10 22:10:27 +00:00
gamdl "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
2023-08-27 03:48:02 +00:00
```
* Download an album
2023-09-30 04:14:32 +00:00
```bash
2024-04-10 22:10:27 +00:00
gamdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"
2023-08-27 03:48:02 +00:00
```
2024-04-23 03:00:25 +00:00
* Choose which albums or music videos to download from an artist
```bash
gamdl "https://music.apple.com/us/artist/rick-astley/669771"
```
2024-05-17 02:11:26 +00:00
2024-05-20 07:06:37 +00:00
### Interactive prompt controls
2024-05-17 02:11:26 +00:00
* Arrow keys - Move selection
2024-05-20 07:06:37 +00:00
* Space - Toggle selection
2024-05-17 02:11:26 +00:00
* Ctrl + A - Select all
2024-05-20 07:06:37 +00:00
* Enter - Confirm selection
2022-12-12 11:39:38 +00:00
2023-08-27 03:48:02 +00:00
## Configuration
2024-05-10 22:24:01 +00:00
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.
2024-05-20 18:58:12 +00:00
| 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` |
| `--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` |
| `--print-exceptions` / `print_exceptions` | 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-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. | `40` |
| `--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` |
2022-12-18 01:59:39 +00:00
2024-04-10 21:55:27 +00:00
2023-08-27 03:48:02 +00:00
### Tags variables
2023-08-27 22:59:18 +00:00
The following variables can be used in the template folders/files and/or in the `exclude_tags` list:
2023-08-27 03:48:02 +00:00
* `album`
* `album_artist`
* `album_id`
* `album_sort`
* `artist`
* `artist_id`
* `artist_sort`
* `comment`
* `compilation`
* `composer`
* `composer_id`
* `composer_sort`
* `copyright`
* `cover`
2023-09-07 18:33:13 +00:00
* `date`
2023-08-27 03:48:02 +00:00
* `disc`
* `disc_total`
* `gapless`
* `genre`
* `genre_id`
* `lyrics`
* `media_type`
* `rating`
* `storefront`
* `title`
* `title_id`
* `title_sort`
* `track`
* `track_total`
* `xid`
2024-04-08 17:59:02 +00:00
2024-04-08 18:26:05 +00:00
### Remux modes
2024-04-08 18:08:11 +00:00
The following remux modes are available:
* `ffmpeg`
* Can be used without mp4decrypt only for songs and when using legacy song codecs
* `mp4box`
* Requires mp4decrypt
* Doesn't convert closed captions in music videos that have them
* Can be obtained from here: https://gpac.wp.imt.fr/downloads
2024-04-08 18:26:05 +00:00
### Download modes
2024-04-08 18:08:11 +00:00
The following download modes are available:
* `ytdlp`
* `nm3u8dlre`
* Faster than `ytdlp`
* Requires FFmpeg
* Can be obtained from here: https://github.com/nilaoda/N_m3u8DL-RE/releases
2024-04-08 18:09:20 +00:00
### Song codecs
2024-04-08 17:59:02 +00:00
The following codecs are available:
* `aac-legacy`
* `aac-he-legacy`
2024-05-25 04:44:59 +00:00
2024-05-25 04:47:21 +00:00
The following codecs are also available, **but are not guaranteed to work** , as currently most (or all) of the songs fails to be downloaded when using them:
2024-04-08 17:59:02 +00:00
* `aac`
* `aac-he`
* `aac-binaural`
* `aac-downmix`
* `aac-he-binaural`
* `aac-he-downmix`
* `atmos`
2024-04-10 22:02:34 +00:00
* `ac3`
* `alac`
2024-04-09 00:13:17 +00:00
* `ask`
2024-05-25 04:44:59 +00:00
* When using this option, gamdl will ask you which codec from this list to use that is available for the song.
2024-04-08 17:59:02 +00:00
### Music videos codecs
The following codecs are available:
2024-04-23 03:00:25 +00:00
* `h264` (up to 1080p, with AAC 256kbps)
* `h265` (up to 2160p, with AAC 256kpbs)
2024-04-08 17:59:02 +00:00
* `ask`
2024-04-11 09:52:15 +00:00
* When using this option, gamdl will ask you which audio and video codec to use that is available for the music video.
2024-04-08 17:59:02 +00:00
2024-04-08 18:26:14 +00:00
### Post videos/extra videos qualities
2024-04-08 18:08:11 +00:00
The following qualities are available:
2024-04-12 21:14:55 +00:00
* `best` (up to 1080p, with AAC 256kbps)
2024-04-08 17:59:02 +00:00
* `ask`
2024-04-11 09:52:15 +00:00
* When using this option, gamdl will ask you which video quality to use that is available for the video.
2023-01-05 00:17:07 +00:00
2024-04-08 18:08:11 +00:00
Post videos doesn't require remuxing and are limited to `ytdlp` download mode.
2024-04-08 17:59:02 +00:00
2024-04-08 18:09:20 +00:00
### Synced lyrics formats
2024-04-08 18:08:11 +00:00
The following synced lyrics formats are available:
* `lrc`
* `srt`
* `ttml`
2024-04-08 18:22:22 +00:00
* Native format for Apple Music synced lyrics.
2024-05-20 07:09:31 +00:00
* Highly unsupported by most media players.
2024-04-08 18:08:11 +00:00
2024-04-08 18:09:20 +00:00
### Cover formats
2024-04-08 18:08:11 +00:00
The following cover formats are available:
* `jpg`
* `png`
2024-06-03 00:15:03 +00:00
* `raw`
2024-06-03 03:49:16 +00:00
* This format gets the raw cover without any processing.
* Note that when you use this format, the cover image will not be embedded within the files. To address this, you can enable `save_cover` option to save the cover as a separate file.
