Skip to content

Wrapper Setup macOS

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

Wrapper Setup Guide: macOS (Apple Silicon)

Platform: macOS on Apple Silicon (M1/M2/M3/M4) Method: Docker (required — no native macOS build exists) Estimated time: 15-20 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.

Wrapper only runs on Linux. On macOS, we use Docker to run it inside a Linux container. The Docker image is built natively for arm64 (Apple Silicon) from source, so there is no emulation penalty.

Prerequisites

  • macOS on Apple Silicon (M1 or later)
  • An active Apple Music subscription
  • Docker Desktop for Mac installed and running

Step 1: Download the Wrapper Release

Open Terminal and run:

mkdir -p ~/wrapper-docker && cd ~/wrapper-docker

Download and extract the latest release:

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

This extracts:

  • wrapper — the launcher binary
  • rootfs/ — the Android runtime environment
  • Dockerfile — the container build instructions

Step 2: Prepare the Dockerfile

The included Dockerfile needs modifications for Apple Silicon. We use a multi-stage build that compiles Wrapper natively for arm64.

Replace the existing Dockerfile:

cat > Dockerfile << 'DOCKERFILE'
ARG BUILD_PLATFORM=linux/amd64
ARG RUNTIME_PLATFORM=linux/arm64

FROM --platform=${BUILD_PLATFORM} debian:13.2 AS build
ARG TARGET_ARCH=aarch64
ARG NDK_VERSION=23

SHELL ["/bin/bash", "-c"]

RUN \
    --mount=type=cache,target=/var/lib/apt,sharing=locked \
    --mount=type=cache,target=/var/cache/apt,sharing=locked \
    apt-get update && apt-get install -y \
    build-essential \
    cmake \
    unzip \
    git \
    lsb-release \
    gnupg \
    aria2 \
    gcc-aarch64-linux-gnu

WORKDIR /app
RUN bash -c "$(wget -O - https://apt.llvm.org/llvm.sh)"
RUN aria2c -o android-ndk-r${NDK_VERSION}b-linux.zip https://dl.google.com/android/repository/android-ndk-r${NDK_VERSION}b-linux.zip
RUN unzip -q -d ~ android-ndk-r${NDK_VERSION}b-linux.zip
RUN rm android-ndk-r${NDK_VERSION}b-linux.zip
COPY ./ ./

WORKDIR /app
RUN mkdir build
WORKDIR /app/build
RUN cmake -DTARGET_ARCH=${TARGET_ARCH} ..
RUN make -j$(nproc)

FROM --platform=${RUNTIME_PLATFORM} debian:13.2

WORKDIR /app
COPY --from=build /app/wrapper /app/wrapper
COPY --from=build /app/rootfs /app/rootfs
COPY entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh

CMD ["/app/entrypoint.sh"]

EXPOSE 10020 20020 30020
DOCKERFILE

Step 3: Create the Entrypoint Script

This script handles both the initial login flow and normal startup:

cat > entrypoint.sh << 'ENTRYPOINT'
#!/bin/sh
set -e

MUSIC_TOKEN_PATH="/app/rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN"

if [ ! -f "$MUSIC_TOKEN_PATH" ]; then
  echo "Login required: MUSIC_TOKEN not found."
  if [ -z "${USERNAME}" ] || [ -z "${PASSWORD}" ]; then
    echo "Error: USERNAME and PASSWORD environment variables must be set when MUSIC_TOKEN is missing." >&2
    exit 1
  fi
  exec ./wrapper \
    -L ${USERNAME}:${PASSWORD} \
    -F \
    -H 0.0.0.0 \
    "$@"
else
  exec ./wrapper \
    -H 0.0.0.0 \
    "$@"
fi
ENTRYPOINT
chmod +x entrypoint.sh

Step 4: Create docker-compose.yml

cat > docker-compose.yml << 'COMPOSE'
services:
  wrapper:
    image: wrapper:latest
    container_name: wrapper
    ports:
      - "10020:10020"
      - "20020:20020"
      - "30020:30020"
    volumes:
      - ./rootfs/data:/app/rootfs/data
    restart: unless-stopped
COMPOSE

Step 5: Build the Docker Image

This step compiles Wrapper from source for arm64. It takes several minutes on first run:

cd ~/wrapper-docker
docker build --tag wrapper .

Note: The build stage downloads the Android NDK and LLVM toolchain (~2-3 GB). Subsequent builds are cached and much faster.

Step 6: Log In to Apple Music

This is a one-time interactive step. Run:

cd ~/wrapper-docker
docker run -it -v ./rootfs/data:/app/rootfs/data \
  -e USERNAME="your_apple_id@email.com" -e PASSWORD="your_password" \
  wrapper

Replace your_apple_id@email.com and your_password with your actual Apple Music credentials.

Handling Two-Factor Authentication (2FA)

If your Apple ID has 2FA enabled (most do), the container will display:

[!] 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 window 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 code from your Apple device.

Successful Login

You should see output like:

[+] 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

Press Ctrl+C to stop the container. The login token is saved to disk and will persist.

Step 7: Start Wrapper Permanently

cd ~/wrapper-docker
docker compose up -d

Wrapper is now running in the background and will auto-restart if Docker is running.

Step 8: 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

Click Test Connection to verify.

Auto-Start on Boot

To have Wrapper start automatically when your Mac boots:

  1. Open Docker Desktop > Settings (gear icon)
  2. Go to General
  3. Enable "Start Docker Desktop when you sign in to your computer"
  4. Click Apply & restart

The chain is: Mac boots -> Docker Desktop starts -> Wrapper container starts

Managing Wrapper

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
Check status docker ps --filter name=wrapper

Troubleshooting

"Connection refused" in MeedyaDL

  • Verify Wrapper is running: docker ps --filter name=wrapper
  • Check logs: docker compose logs from ~/wrapper-docker/
  • Ensure ports 10020, 20020, 30020 are not used by other apps

"MUSIC_TOKEN not found" on startup

  • You need to complete the login step (Step 6) first
  • Re-run the interactive login command

2FA code timeout

  • You have 60 seconds to enter the code
  • Have the second terminal ready before starting the login
  • Write the code to the host path: ~/wrapper-docker/rootfs/data/data/com.apple.android.music/files/2fa.txt

Token expired

  • Delete the token and re-login: 
    rm ~/wrapper-docker/rootfs/data/data/com.apple.android.music/files/MUSIC_TOKEN
    Then repeat Step 6.

Password contains a colon (:)

  • The login parser uses : as a delimiter between username and password
  • If your password contains a colon, change your password to one without colons

MeedyaDL Wiki

Resources

Clone this wiki locally