English | 中文

A beautiful desktop GUI for downloading hi-res music from Qobuz — built on top of streamrip.

Download · Features · Screenshots · Build from source · Architecture · License · Disclaimer

---

Download

Grab the latest build from the Releases page:

Platform	File	Size
Windows	Qrip Setup 0.1.0.exe	~80 MB
macOS (Apple Silicon)	Qrip-0.1.0-arm64.dmg	~130 MB

Requirements:

• Windows 10 or later
• macOS 11.0 or later (Apple Silicon)

Install and run — no Python install needed. The backend is compiled into a standalone binary that ships inside the app. macOS builds are Apple Silicon (arm64) only; Intel Mac users see Build from source.

The installers are currently unsigned: macOS shows an "unidentified developer" warning (right-click → Open, or allow it in System Settings), Windows SmartScreen asks for confirmation.

Features

• Sign in with Qobuz: the app opens a Qobuz login window and captures your auth token automatically — any login method works (Google, Apple, email). Credentials are stored locally and reused until they expire; every login window starts fresh so switching accounts is easy. A paste-a-token fallback is available.
• Search & browse: keyword search across albums, tracks and playlists, with covers, quality tags (FLAC bit depth / sample rate), year, label and duration shown up front. Results load more pages on demand.
• Paste a link: drop a Qobuz track / album / playlist URL and download it directly.
• High-res downloads: up to 24-bit / 192 kHz FLAC, quality configurable in settings.
• Album track list: expand an album to see every track and download individual ones.
• Live progress: per-item progress bars, speed and queue management on the Downloads tab — pause / resume / delete, with partial files cleaned up when you cancel.
• No database, no dedup: everything is always downloadable; existing files are simply overwritten.
• Sensible defaults: {artist} — {album} ({year}) folder layout, {artist} — {title} file names, cover embedded in the audio files.
• Naming templates: pick from presets or assemble your own from tokens, with a live preview.
• Cover art options: embed in audio files, optionally save cover.jpg separately.
• Extensible design: Qobuz-only today, but the architecture keeps the door open for more sources.

Screenshots

Build from source

Most users should just grab a packaged build from Download. This section is for running / packaging from source.

Requires Python 3.10+ and Node.js 20+.

Backend dependencies:

pip install -r python/requirements-build.txt

Frontend dependencies:

npm install

Run in development (Electron + Vite + FastAPI):

npm run electron:dev

Build the backend binary (PyInstaller, standalone, no Python needed at runtime):

npm run build:backend

Package the app (electron-builder — run on macOS for a .dmg, on Windows for an .exe):

npm run electron:build

The output is placed in the release/ directory.

PyInstaller cannot cross-compile, so a macOS .dmg must be built on macOS and a Windows .exe on Windows. To build automatically, push a v* tag (e.g. v0.1.0) or trigger the workflow manually from the Actions tab: GitHub Actions builds both packages and attaches them to the release.

Intel Macs: the arm64 build runs only on Apple Silicon. GitHub's free Intel macOS runners are scarce and being retired, so CI does not produce an Intel (x86_64) build. If you need one, build it on an Intel Mac with npm run electron:build (that build also runs on Apple Silicon via Rosetta).

Architecture

Qrip is three layers working together:

┌─────────────────────────────────────────┐
│  Electron (desktop shell)               │
│  · window & lifecycle management        │
│  · spawns the backend as a child proc   │
│  · OAuth window + token capture         │
│  · OS integration (file dialogs, links) │
├─────────────────────────────────────────┤
│  React + TypeScript (UI, inside Electron)│
│  · Login / Search / Downloads / Settings│
│  · talks to the backend over HTTP       │
├─────────────────────────────────────────┤
│  FastAPI (backend, localhost:8000)      │
│  · wraps the streamrip core library     │
│  · auth / search / download / config    │
└─────────────────────────────────────────┘
           ↓ calls
   streamrip core (vendored in this repo)

Highlights:

• Token capture: the OAuth window is created with a fresh in-memory session every time (no remembered accounts), and the X-User-Auth-Token header that the Qobuz web player sends after login is intercepted via webRequest.
• Real progress bars: streamrip's terminal progress bars don't work in a GUI, so Qrip polls the download folder's file sizes to derive progress and speed.
• Pause / resume / cancel: streamrip's download loop is a blocking sync loop that the event loop can't interrupt. Qrip monkey-patches it — the real transfer runs in a worker thread, and the chunk callback becomes the control point for pausing (sleeps the transfer thread), resuming and cancelling (raises through, closes file handles cleanly). Cancelling also sweeps away partial files and empty folders.
• Serial downloads: one track at a time, matching the streamrip CLI experience.

License

Qrip is released under the GNU General Public License v3.0.

Qrip vendors the streamrip core library (in streamrip/), which is also GPL-3.0 licensed — see streamrip/LICENSE.

Troubleshooting

Windows: "backend failed to start" / spawn ENOENT (or a crash popup)

Your antivirus (most commonly Windows Defender) quarantined the backend binary — unsigned apps built with PyInstaller are frequently false-flagged. To fix:

1. Open Windows Security → Virus & threat protection → Protection history, find qrip-server.exe and click Restore.
2. Add Qrip's install folder (e.g. C:\Users\<you>\AppData\Local\Programs\Qrip) to Virus & threat protection → Manage settings → Exclusions → Add an exclusion → Folder.
3. Restart Qrip (reinstall if the file can't be restored).

Backend diagnostics are written to %APPDATA%\Qrip\backend.log — attach it when reporting issues.

Login fails with a network / DNS error (e.g. "Could not contact DNS servers")

The backend must reach play.qobuz.com directly. If you use a proxy / VPN, make sure it runs in TUN / virtual-adapter mode (transparent for all apps) — a system-proxy-only setup is not picked up by the backend.

Disclaimer

I will not be responsible for how you use Qrip. By using Qrip, you agree to the terms and conditions of the Qobuz's API.