Apple Music ALAC / Dolby Atmos Downloader

English | 简体中文 | Cloud Server / Proxy Setup

Original script by Sorrow. Modified with fixes and improvements.

This command-line tool downloads albums, songs, playlists, stations and music videos from Apple Music, preserves or embeds metadata and lyrics, and supports ALAC, AAC and Dolby Atmos. Use it only with content you are entitled to access and in accordance with Apple's terms and applicable law.

Contents

• Features
• Supported formats
• Requirements
• Quick Start
• Configuration
• Usage
• Upgrade
• For Developers
• Get media-user-token
• Lyrics options
• Credits

Features

1. Inline cover art and LRC lyrics.
2. Word-by-word and unsynchronized lyrics.
3. Artist album downloads.
4. Streaming download and decryption for large files.
5. Music-video downloads using in-process mp4ff decryption.
6. Interactive search and track selection.

Supported formats

Stations require a valid media-user-token from an active subscription.

Requirements

Install and prepare these before running the downloader:

1. wrapper-lite: github.com/WorldObservationLog/wrapper/tree/lite. Required backend decryption service. Start it before using this downloader and set its HTTP endpoint in lite-server, for example http://127.0.0.1:12340.
2. ffmpeg (Optional): Required only for post-download conversion, animated artwork, or ffmpeg-dependent features. See ffmpeg.org.

Note: If you are using the precompiled release binaries, Go is NOT required. Go (1.23.1+) is only needed if you build from source (see For Developers).

Quick Start

Download the precompiled binary for your operating system and architecture from the latest GitHub Releases:

---

Windows (PowerShell)

1. Open PowerShell and run the following command to download the executable:

# Download precompiled binary (example for 64-bit Windows)
Invoke-WebRequest -Uri "https://github.com/zhaarey/apple-music-downloader/releases/latest/download/amdl_windows_amd64.exe" -OutFile "amdl.exe"

2. Run amdl.exe once to automatically generate the default config.yaml:

.\amdl.exe

3. Open and edit config.yaml to set your lite-server address and destination paths.
4. Test running the downloader:

.\amdl.exe --help

Example:

.\amdl.exe "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

---

macOS

1. Download the precompiled binary:

# For Apple Silicon (M-series):
curl -L -o amdl https://github.com/zhaarey/apple-music-downloader/releases/latest/download/amdl_darwin_arm64

# For Intel Macs:
# curl -L -o amdl https://github.com/zhaarey/apple-music-downloader/releases/latest/download/amdl_darwin_amd64

# Grant execution permission
chmod +x amdl

Tip (macOS Gatekeeper): If macOS blocks running amdl because it is from an unidentified developer, remove the quarantine attribute:

xattr -d com.apple.quarantine amdl

2. Run amdl once to automatically generate the default config.yaml:

./amdl

3. Edit config.yaml with your settings.
4. Run the downloader:

./amdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

---

Linux

1. Download the precompiled binary:

# For x86_64 / amd64:
curl -L -o amdl https://github.com/zhaarey/apple-music-downloader/releases/latest/download/amdl_linux_amd64

# For ARM64:
# curl -L -o amdl https://github.com/zhaarey/apple-music-downloader/releases/latest/download/amdl_linux_arm64

# Grant execution permission
chmod +x amdl

2. Run amdl once to automatically generate the default config.yaml:

./amdl

3. Edit config.yaml with your settings.
4. Run the downloader:

./amdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

---

Android (Termux)

Install Termux from F-Droid or the official GitHub releases (do not use the obsolete Play Store version).

1. Update packages and install curl (and optionally ffmpeg):

pkg update && pkg upgrade
pkg install -y curl ffmpeg

2. Grant access to shared Android storage (creates ~/storage/shared):

termux-setup-storage

3. Download precompiled binary:

curl -L -o amdl https://github.com/zhaarey/apple-music-downloader/releases/latest/download/amdl_android_arm64
chmod +x amdl

4. Run amdl once to automatically generate the default config.yaml:

./amdl

5. Edit config.yaml. To save downloads into Android's shared Music directory, point the paths in config.yaml to the shared mount:

paths:
  alac: "/sdcard/Music/amdl"
  atmos: "/sdcard/Music/amdl-atmos"
  aac: "/sdcard/Music/amdl-aac"
  mv: "/sdcard/Music/amdl-mv"

6. Run:

./amdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

Tips for Termux:

• For long downloads, prevent Android from sleeping with termux-wake-lock (release with termux-wake-unlock when done).
• If wrapper-lite runs on another device on your network, point lite-server to that device's LAN IP, not 127.0.0.1.
• These instructions target current Android arm64 Termux environments; 32-bit Android is not a documented target.
• If self-update on an older version fails with lookup api.github.com on [::1]:53 ... connection refused, re-download the binary once as in step 3; later versions update normally.

Configuration

When amdl is run for the first time without an existing configuration file, it automatically creates config.yaml in the current directory from an embedded default template.

At minimum, review and set:

general:
  # wrapper-lite HTTP API endpoint.
  lite-server: "http://127.0.0.1:12340"

  # Required for stations. See "Get media-user-token" below.
  media-user-token: "your-media-user-token"

# Destination folders. Relative paths are resolved from the working directory.
paths:
  alac: "AM-Lossless"
  atmos: "AM-Atmos"
  aac: "AM-AAC"
  mv: "AM-MV"

If wrapper-lite runs on another machine or container, replace 127.0.0.1 with that host's reachable LAN or public address.

Usage

Before running any command, make sure:

1. wrapper-lite is running.
2. config.yaml exists and has the correct lite-server value.

Album

./amdl "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

On Windows:

.\amdl.exe "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

Single song

./amdl "https://music.apple.com/us/album/never-gonna-give-you-up-2022-remaster/1624945511?i=1624945512"
./amdl "https://music.apple.com/us/song/you-move-me-2022-remaster/1624945520"

Artist albums

./amdl --all-album "https://music.apple.com/us/artist/taylor-swift/159260351"

Playlist

./amdl "https://music.apple.com/us/playlist/taylor-swift-essentials/pl.3950454ced8c45a3b0cc693c2a7db97b"

Interactive selection

./amdl --select "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

Enter track numbers separated by spaces.

Interactive search

./amdl --search album "never gonna give you up"
./amdl --search song "you move me"
./amdl --search artist "taylor swift"

Dolby Atmos

./amdl --atmos "https://music.apple.com/us/album/1989-taylors-version-deluxe/1713845538"

AAC

./amdl --aac "https://music.apple.com/us/album/1989-taylors-version-deluxe/1713845538"

Show quality information

./amdl --debug "https://music.apple.com/us/album/1989-taylors-version-deluxe/1713845538"

Common options

--alac-max <sample-rate>
--atmos-max <bitrate>
--aac-type <aac|aac-lc|aac-binaural|aac-downmix>
--mv-max <resolution>
--mv-audio-type <atmos|ac3|aac>
--lite-server <wrapper-lite-url>

Get media-user-token

media-user-token is required for stations.

1. Open Apple Music and sign in.
2. Open browser developer tools with F12.
3. Go to Application > Storage > Cookies > https://music.apple.com.
4. Find the cookie named media-user-token and copy its value.
5. Paste it into general.media-user-token in config.yaml.
6. Restart the downloader.

Lyrics options

Configure lyrics settings under metadata.lyrics in config.yaml:

metadata:
  lyrics:
    save-file: false                      # Save .lrc or .ttml file to disk
    embed: true                           # Embed lyrics directly into audio container tags
    type: "lyrics"                        # Lyrics type: "lyrics" (standard line-by-line) or "syllable-lyrics" (word-by-word)
    format: "lrc"                         # Lyrics file format: "lrc" or "ttml"
    extra: ""                             # Additional options: "" (default), "translation", or "pronunciation"

Tips:

• Set general.language in config.yaml (e.g. "en-US", "zh-Hans-CN", "ja") to control the target language for translated lyrics.
• extra: set to "translation" for translated lyrics or "pronunciation" for phonetic/romanized lyrics (when provided by Apple Music).

Upgrade

Built-in Self Update (Recommended)

Upgrade to the latest official release with automatic checksum verification and interactive configuration migration:

# Check and perform self-update with interactive config migration
./amdl --update

# Shorthand flag
./amdl -U

# Check for updates without downloading
./amdl --check-update

# Automated / non-interactive mode (automatically accept new option defaults)
./amdl -U -y

On Windows PowerShell:

# Perform self-update
.\amdl.exe --update

# Shorthand flag
.\amdl.exe -U

Note: Self-update automatically creates a timestamped config.yaml.bak_... backup and safely guides the migration of new settings without overwriting your credentials, custom paths, or comments. If a proxy is configured in config.yaml, the updater automatically routes through it.

Manual Binary Update

Download the latest precompiled executable from GitHub Releases and replace your current amdl / amdl.exe binary.

For developers building from source, see For Developers.

For Developers

If you want to contribute, modify the code, or build the downloader from source:

Prerequisites

1. Go 1.23.1 or newer: go.dev/dl.
2. Git: git-scm.com.
3. ffmpeg: ffmpeg.org (optional for audio conversion or animated artwork).

Clone and Build

macOS / Linux:

git clone https://github.com/zhaarey/apple-music-downloader.git
cd apple-music-downloader
cp config.yaml.example config.yaml
go build -o amdl .
./amdl --help

Windows (PowerShell):

git clone https://github.com/zhaarey/apple-music-downloader.git
cd apple-music-downloader
copy config.yaml.example config.yaml
go build -o amdl.exe .
.\amdl.exe --help

Run in Development

go run . "https://music.apple.com/us/album/whenever-you-need-somebody-2022-remaster/1624945511"

Update Source Code

git pull
go build -o amdl .

On Windows (PowerShell):

git pull
go build -o amdl.exe .

Releasing

Releases are driven by the VERSION file. When a push to main carries a VERSION whose v<VERSION> tag does not exist yet, the Release workflow builds every platform and publishes a GitHub Release with that tag. To cut a release, bump VERSION (e.g. 0.1.0 → 0.1.1) and merge it into main. A version with a suffix such as 0.2.0-beta.1 is published as a pre-release.

Release binaries self-update from the repository that built them, so a fork's releases update from the fork.

Credits

• Sorrow created the original script.
• WorldObservationLog created wrapper / wrapper-lite, used as the backend decryption service.
• Sendy McSenderson contributed the streaming download-and-decrypt implementation.
• go-mp4tag writes station MP4 metadata.
• FFmpeg supports optional conversion and animated-artwork features.