Wrapper Setup Linux

Wrapper Setup Guide: Linux and Raspberry Pi

Platforms: Linux x86_64, Linux arm64, Raspberry Pi (64-bit OS) Method: Docker or native binary Estimated time: 10-15 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.

Linux is Wrapper's native platform. You can run it directly with a prebuilt binary, or use Docker for isolation and easier management.

---

Option A: Docker Installation (Recommended)

Prerequisites

• An active Apple Music subscription
• Docker Engine installed (see below)

Install Docker Engine

Ubuntu / Debian / Raspberry Pi OS (64-bit)

# Remove conflicting packages
for pkg in docker.io docker-doc docker-compose podman-docker containerd runc; do
  sudo apt-get remove -y $pkg 2>/dev/null
done

# Add Docker's official GPG key and repository
sudo apt-get update
sudo apt-get install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo \
  "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian \
  $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | \
  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Install Docker
sudo apt-get update
sudo apt-get install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

# Add your user to the docker group (avoids needing sudo)
sudo usermod -aG docker $USER

Log out and back in for the group change to take effect.

Note for Ubuntu: Replace https://download.docker.com/linux/debian with https://download.docker.com/linux/ubuntu in the repository URL above.

Step 1: Download the Wrapper Release

Choose the right release for your architecture:

x86_64 (Intel/AMD):

mkdir -p ~/wrapper-docker && cd ~/wrapper-docker
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

arm64 (Raspberry Pi / ARM servers):

mkdir -p ~/wrapper-docker && cd ~/wrapper-docker
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

Step 2: Build the Docker Image

x86_64:

cd ~/wrapper-docker
docker build --platform linux/amd64 --tag wrapper .

arm64 (Raspberry Pi):

cd ~/wrapper-docker
docker build --platform linux/arm64 --tag wrapper .

Raspberry Pi Note: If the arm64 release is missing the entrypoint.sh, you may need to clone the arm64 branch instead:

git clone https://github.com/WorldObservationLog/wrapper -b arm64 ~/wrapper-docker
cd ~/wrapper-docker && docker build --tag wrapper .

Step 3: Create docker-compose.yml

cat > ~/wrapper-docker/docker-compose.yml << 'EOF'
services:
  wrapper:
    image: wrapper:latest
    container_name: wrapper
    ports:
      - "10020:10020"
      - "20020:20020"
      - "30020:30020"
    volumes:
      - ./rootfs/data:/app/rootfs/data
    environment:
      - args=-H 0.0.0.0
    restart: unless-stopped
EOF

Step 4: Log In to Apple Music

cd ~/wrapper-docker
docker run -it -v ./rootfs/data:/app/rootfs/data \
  -e args="-L your_email:your_password -H 0.0.0.0" wrapper

Replace your_email:your_password with your Apple Music credentials.

Handling 2FA

When prompted, open a second terminal and run:

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

Replace YOUR_CODE with the 6-digit verification code. You have 60 seconds.

After successful login, press Ctrl+C.

Step 5: Start Wrapper Permanently

cd ~/wrapper-docker
docker compose up -d

Auto-Start on Boot

Docker Engine on Linux starts automatically via systemd. Since the compose file has restart: unless-stopped, the container will auto-start on boot.

Verify Docker is enabled:

sudo systemctl enable docker

---

Option B: Native Installation (No Docker)

For Linux x86_64 and arm64 systems that can run the binary directly.

Step 1: Download and Extract

x86_64:

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:

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

Step 2: Log In

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

For 2FA, when prompted, write the code to the file shown in the output:

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

After successful login, press Ctrl+C.

Step 3: Run as a Service

Start Wrapper:

cd ~/wrapper
./wrapper -H 0.0.0.0

To run in the background:

cd ~/wrapper
nohup ./wrapper -H 0.0.0.0 > wrapper.log 2>&1 &

Create a systemd Service (Auto-Start on Boot)

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

[Service]
Type=simple
User=$USER
WorkingDirectory=/home/$USER/wrapper
ExecStart=/home/$USER/wrapper/wrapper -H 0.0.0.0
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

Important: Replace $USER in the file above with your actual username.

Enable and start:

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

Check status:

sudo systemctl status wrapper

---

Configure MeedyaDL / gamdl

In MeedyaDL settings or gamdl config, set:

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

Command-Line Reference

Flag	Purpose	Default
-H, --host	Listen address	127.0.0.1
-D, --decrypt-port	Decryption service port	10020
-M, --m3u8-port	M3U8 service port	20020
-A, --account-port	Account service port	30020
-L, --login	Login credentials (user:pass)	—
-P, --proxy	Proxy server URL	—
-F, --code-from-file	Read 2FA code from file	off

Managing Wrapper

Docker

Action	Command
Start	cd ~/wrapper-docker && docker compose up -d
Stop	cd ~/wrapper-docker && docker compose down
View logs	cd ~/wrapper-docker && docker compose logs -f
Restart	cd ~/wrapper-docker && docker compose restart

Native (systemd)

Action	Command
Start	sudo systemctl start wrapper
Stop	sudo systemctl stop wrapper
View logs	journalctl -u wrapper -f
Restart	sudo systemctl restart wrapper

Troubleshooting

"Connection refused" in MeedyaDL

• Verify Wrapper is running: docker ps --filter name=wrapper or systemctl status wrapper
• Ensure ports 10020, 20020, 30020 are not blocked by a firewall
• For remote access, use -H 0.0.0.0 and update the MeedyaDL URL to the server's IP

Raspberry Pi: Slow Performance with x86_64 Image

• QEMU emulation of x86_64 on arm64 is extremely slow
• Always use the arm64 release or build from the arm64 branch
• Never use --platform linux/amd64 on Raspberry Pi

Token Expired

• Delete the token and re-login:

  rm ~/wrapper-docker/rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN
  # or for native:
  rm ~/wrapper/rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN

Password Contains a Colon (:)

• The login parser uses : as a delimiter
• Change your password to one without colons