Skip to content

Wrapper Setup Native

Jump to bottom
Salem874 edited this page Mar 26, 2026 · 1 revision

Wrapper Setup Guide: Native Installation (No Docker)

Supported Platforms: Linux x86_64, Linux arm64 Not supported natively: macOS, Windows (use Docker — see platform-specific guides) Estimated time: 5-10 minutes

Overview

Wrapper is a tool that enables downloading Apple Music songs in lossless codecs (ALAC, etc.) without API limitations. It runs as a local server that MeedyaDL / gamdl connects to.

This guide covers installing Wrapper directly on Linux without Docker. This is the simplest and fastest method for supported platforms.

Prerequisites

  • Linux — x86_64 or arm64 architecture
  • An active Apple Music subscription
  • curl, unzip (install via your package manager if missing)

Step 1: Download the Release

x86_64 (Intel/AMD desktops, servers, VPS)

mkdir -p ~/wrapper && cd ~/wrapper
curl -L -o wrapper-release.zip \
  "https://github.com/WorldObservationLog/wrapper/releases/download/Wrapper.x86_64.1dac7bb/Wrapper.x86_64.1dac7bb.zip"
unzip -o wrapper-release.zip
chmod +x wrapper

arm64 (Raspberry Pi, ARM servers, Oracle Cloud free tier, etc.)

mkdir -p ~/wrapper && cd ~/wrapper
curl -L -o wrapper-release.zip \
  "https://github.com/WorldObservationLog/wrapper/releases/download/Wrapper.arm64.latest/Wrapper.arm64.e338fa6.zip"
unzip -o wrapper-release.zip
chmod +x wrapper

Verify the download

cd ~/wrapper
./wrapper --help

You should see usage information with flags like -H, -D, -M, -A, -L.

Step 2: Log In to Your Apple Music Account

Run the wrapper with your Apple Music credentials:

cd ~/wrapper
./wrapper -L "your_email@example.com:your_password" -H 0.0.0.0

Important: Replace your_email@example.com and your_password with your actual Apple Music credentials. Your password must not contain a colon (:) character.

What happens during login

  1. Wrapper connects to Apple's authentication servers
  2. You'll see [+] logging in... followed by dialog handler messages
  3. If 2FA is enabled, proceed to the next section
  4. If login succeeds without 2FA, you'll see the token and listening messages

Handling Two-Factor Authentication (2FA)

Most Apple IDs have 2FA enabled. When prompted, the output will show:

[!] Enter your 2FA code into rootfs/data/data/com.apple.android.music/files/2fa.txt
[!] Waiting for input...

You have 60 seconds. Open a second terminal and run:

echo -n YOUR_CODE > ~/wrapper/rootfs/data/data/com.apple.android.music/files/2fa.txt

Replace YOUR_CODE with the 6-digit verification code sent to your Apple device.

Successful login output

[+] account info cached successfully
[+] StoreFront ID: 143444-2,31
[+] Music-Token: AozLzN1LkWGJps...
[!] listening m3u8 request on 0.0.0.0:20020
[!] listening 0.0.0.0:10020
[!] listening account info request on 0.0.0.0:30020

The token is now saved in rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN. You only need to log in once.

Press Ctrl+C to stop the server.

Step 3: Run Wrapper

Foreground (manual)

cd ~/wrapper
./wrapper -H 0.0.0.0

Background (manual)

cd ~/wrapper
nohup ./wrapper -H 0.0.0.0 > wrapper.log 2>&1 &
echo $! > wrapper.pid

To stop it later:

kill $(cat ~/wrapper/wrapper.pid)

As a systemd Service (Recommended for Servers)

Create the service file:

sudo tee /etc/systemd/system/wrapper.service > /dev/null << EOF
[Unit]
Description=Apple Music Wrapper Service
After=network.target

[Service]
Type=simple
User=$(whoami)
WorkingDirectory=$HOME/wrapper
ExecStart=$HOME/wrapper/wrapper -H 0.0.0.0
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable wrapper
sudo systemctl start wrapper

Check it's running:

sudo systemctl status wrapper

The service will now auto-start on boot.

Step 4: Configure MeedyaDL / gamdl

In MeedyaDL settings or your gamdl config file, set:

Setting Value
use_wrapper true
wrapper_account_url http://127.0.0.1:30020
wrapper_decrypt_ip 127.0.0.1:10020

If Wrapper is running on a different machine on your network, replace 127.0.0.1 with that machine's IP address.

Command-Line Reference

Usage: wrapper [OPTION]...

  -h, --help              Print help and exit
  -V, --version           Print version and exit
  -H, --host=STRING       Listen address (default: 127.0.0.1)
  -D, --decrypt-port=INT  Decryption service port (default: 10020)
  -M, --m3u8-port=INT     M3U8 service port (default: 20020)
  -A, --account-port=INT  Account service port (default: 30020)
  -P, --proxy=STRING      Proxy server URL
  -L, --login=STRING      Credentials in username:password format
  -F, --code-from-file    Read 2FA code from file (default: off)

Examples

Listen on all interfaces (required for remote access):

./wrapper -H 0.0.0.0

Use custom ports:

./wrapper -H 0.0.0.0 -D 11020 -M 21020 -A 31020

Use a proxy:

./wrapper -H 0.0.0.0 -P "http://proxy.example.com:8080"

Building from Source

If no prebuilt binary is available for your architecture, or you want the latest code:

Prerequisites

sudo apt install build-essential cmake curl unzip git

Build

git clone https://github.com/WorldObservationLog/wrapper
cd wrapper
mkdir build && cd build
cmake ..
make -j$(nproc)

The wrapper binary and rootfs/ directory will be in the parent directory.

Troubleshooting

"Connection refused" in MeedyaDL

  • Ensure Wrapper is running: systemctl status wrapper or ps aux | grep wrapper
  • Check that the ports match between Wrapper and MeedyaDL config
  • If accessing remotely, ensure Wrapper is listening on 0.0.0.0 (not 127.0.0.1)
  • Check firewall: sudo ufw allow 10020 && sudo ufw allow 20020 && sudo ufw allow 30020

Wrapper exits immediately

  • Check if the MUSIC_TOKEN exists: ls ~/wrapper/rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN
  • If missing, complete the login step first

Token expired

  • Delete the token and re-login: 
    rm ~/wrapper/rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN
./wrapper -L "your_email:your_password" -H 0.0.0.0

2FA code not accepted

  • Ensure you're writing the code without a trailing newline: use echo -n (not echo)
  • Ensure the path is correct: rootfs/data/data/com.apple.android.music/files/2fa.txt
  • You have 60 seconds from when the prompt appears

Password contains a colon (:)

  • The -L flag uses : as the delimiter between username and password
  • Passwords with colons will be truncated — change your password to one without colons

"ANDROID_DATA not set" / "ANDROID_ROOT not set" warnings

  • These are non-fatal warnings from Android's bionic libc
  • Wrapper should still function correctly despite these messages
  • If it crashes with a segfault after these warnings, your architecture may not be supported — try the Docker method instead

MeedyaDL Wiki

Resources

Clone this wiki locally