Ripuz

Name: "Ripuz" is a play on Qobuz — ripping music from a service that ends in uz.

Self-hosted Qobuz → MusicBrainz Picard music downloader for UNRAID (and any Linux Docker host).

Downloads your Qobuz library at a configurable quality (MP3 320 → FLAC 24-bit/192kHz), enriches tags with MusicBrainz Picard headlessly, and organises files into your music library as Artist/Album/Title.FLAC.

Features

All bulk modes (Discography, Expand, Explicit upgrade) are two-phase: Ripuz first resolves the full album list, shows you a plan with an estimated download size, and waits for your confirmation before downloading anything. You can cancel at any time.

Additional capabilities:

• Per-album Picard tagging (MusicBrainz lookup, headless under Xvfb)
• Whole-library retag pass: finds files missing core tags or a MusicBrainz id and tags them in place (MusicBrainz lookup is forced on for this pass)
• Configurable quality tier via the Settings UI
• Optional synced .lrc lyrics download (Plex sidecar format)
• Optional prefer-explicit toggle for playlist downloads
• Disk-space floor guard — aborts a bulk job before the drive fills up
• Cross-job deduplication — two concurrent bulk jobs never download the same album twice
• HTTP Basic Auth (optional) for remote access

Getting your Qobuz auth token

Qobuz no longer allows third-party password login. Extract your browser session token:

1. Log in at play.qobuz.com
2. Press F12 → Application tab → Local Storage → https://play.qobuz.com
3. Find the localuser key and copy the token string from the JSON value.
4. Paste it in Ripuz Settings.

Quick start (Docker)

docker run -d --name ripuz --restart unless-stopped \
  -p 8080:8080 \
  -v /mnt/user/appdata/ripuz/config:/config \
  -v /mnt/user/appdata/ripuz/downloads:/downloads \
  -v /mnt/user/data/media/music:/music \
  -e PUID=99 -e PGID=100 -e UMASK=022 \
  suvirp/ripuz:latest

Then open http://your-server-ip:8080.

The image is published to Docker Hub (suvirp/ripuz) and GitHub Container Registry (ghcr.io/Suvir0/ripuz) on every push to main.

UNRAID deployment

Option A — Docker Compose

git clone https://github.com/Suvir0/ripuz.git
cd ripuz
docker compose up -d

Option B — UNRAID Community Apps

Use the included ripuz.xml template. Edit the volume paths:

Set PUID and PGID to match your UNRAID nobody/users (default 99/100).

Build locally

docker build -t ripuz .

Update on the server

docker pull suvirp/ripuz:latest && \
docker rm -f ripuz && \
docker run -d --name ripuz --restart unless-stopped \
  -p 9999:8080 \
  -v /mnt/user/appdata/ripuz/config:/config \
  -v /mnt/user/data/misc:/downloads \
  -v /mnt/user/data/media/music:/music \
  -e PUID=99 -e PGID=100 -e UMASK=022 \
  -e CONFIG_DIR=/config -e DOWNLOADS_DIR=/downloads \
  -e MUSIC_DIR=/music -e APP_PORT=8080 -e LOG_LEVEL=info \
  suvirp/ripuz:latest

Usage walkthrough

1. Settings — paste your Qobuz token, set music quality and optional toggles.
2. Add download — pick a mode, paste a Qobuz URL (or enable "scan my /music library" for Explicit upgrade).
3. Bulk jobs — after resolving, Ripuz shows you a plan:
   • Number of albums to download, estimated GB, albums already present or claimed by another job.
   • Click Confirm to start downloading, or Cancel to discard.
4. Jobs tab — watch live log output per job; cancel or delete finished jobs.
5. Result — files land in MUSIC_DIR/<Artist>/<Album>/<Title>.FLAC.

Environment variables

Quality tiers

Settings UI keys

The following settings are persisted in the DB and configurable via the Settings tab:

Architecture

HTTP request
    │
    ▼
app/main.py          FastAPI app + lifespan + REST API (/api/jobs, /api/settings, /healthz)
    │
    ▼
app/jobs.py          SQLite job queue + single background worker thread
    │
    ▼
app/pipeline.py      Orchestration: download → tag → move → verify → cleanup
    ├── app/qobuz_client.py   Qobuz API: playlist/artist/album/track resolution, explicit matching
    ├── app/qobuz_cli.py      Subprocess wrapper for `python -m qobuz_dl dl`
    ├── app/picard.py         Headless Picard runner (xvfb-run, per-album, best-effort)
    ├── app/mover.py          Read mutagen tags, move files to Artist/Album/Title.FLAC
    └── app/structure.py      FLAC discovery, album-dir listing, empty-dir cleanup, verify

app/db.py            SQLite schema: jobs, settings, album_cache; stale-job purge; cross-job dedup
app/settings_store.py  Persist settings to DB; render qobuz-dl config.ini
app/config.py        Env-driven paths and constants

Bulk job lifecycle:

queued → resolving → awaiting_confirm → (user clicks Confirm) → confirmed
       → downloading → tagging → verifying → done / done_with_warnings / error

Simple jobs (track, album, playlist) skip the resolve/confirm phases.

Project structure

app/
  main.py             FastAPI app + API routes
  config.py           Env-driven paths and constants
  db.py               SQLite: jobs, settings, album_cache
  settings_store.py   Persist settings + render qobuz-dl config.ini
  qobuz_client.py     Qobuz API resolution and explicit-match logic
  qobuz_cli.py        Subprocess wrapper for qobuz-dl
  picard.py           Headless Picard runner (xvfb-run + remote commands)
  pipeline.py         Orchestrate download → tag → move → verify → cleanup
  jobs.py             SQLite job queue + background worker thread
  mover.py            FLAC tag reader + file mover (Artist/Album/Title.FLAC)
  structure.py        FLAC discovery, album-dir listing, structure verification
  explicit.py         Fuzzy matching to find explicit twins of clean tracks/albums
  static/             index.html, app.js, style.css
picard/
  Picard.ini          Picard config template (tag-only; rename/move handled by mover.py)
scripts/
  drain_downloads.py  One-shot: move all pending downloads into the library (no re-tag)
  normalize_library.py  Relocate flat FLACs into Artist/Album/Title structure from tags
tests/                329 unit tests, all mocked (no real Qobuz account or Picard needed)
Dockerfile            python:3.12-slim + Picard + Xvfb + ffmpeg + gosu
entrypoint.sh         PUID/PGID/UMASK drop-privileges + Picard.ini path injection
docker-compose.yml    Local dev / UNRAID reference
ripuz.xml             UNRAID Community-Apps template

Running tests

python -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python -m pytest -v

No real Qobuz account, Picard installation, or Docker is required — all external calls are mocked.

Security

Ripuz ships with no authentication enabled by default for trusted-LAN homelab use.

• To enable HTTP Basic Auth, set RIPUZ_AUTH_PASS (and optionally RIPUZ_AUTH_USER).
• Do not expose port 8080 to untrusted networks; use a reverse proxy, VPN, or firewall.
• For stricter local file permissions on config/DB files, set UMASK=077.
• The /healthz endpoint is always accessible without credentials (for container health checks).

Troubleshooting

Legal / disclaimer

Ripuz orchestrates downloads using your own Qobuz subscription via the official authenticated API. No music is bundled or distributed with this software. Use for personal archival purposes only; this may violate Qobuz's Terms of Service. You are responsible for compliance with applicable laws and terms in your jurisdiction.

Notice

See CREDITS.md for third-party attribution and licenses.