qobuz-rest-api

July 17, 2026 · View on GitHub

Important

Music piracy is illegal in most countries. This project is intended for use with a valid Qobuz subscription for personal/educational purposes (e.g. in your homelab). Use responsibly.

Setup

Run pip install -r requirements.txt, then configure your .env file:

cp .env.example .env

Environment variables

Variable	Description
`QOBUZ_APP_ID`	Qobuz App ID — see Finding APP_ID and SECRET
`QOBUZ_SECRET`	Qobuz Secret — see Finding APP_ID and SECRET
`QOBUZ_TOKEN`	User token → localStorage of play.qobuz.com, key `localuser.token`
`QOBUZ_AUTH_TOKENS`	Pool of multiple tokens as a JSON array or comma-separated string — one is picked at random per request, skipping tokens that recently returned `401`
`QOBUZ_API_BASE`	Alternative Qobuz API base URL (default: `https://www.qobuz.com/api.json/0.2`)
`QOBUZ_PROXY`	Residential proxy for cloud hosting — `http://user:pass@host:port` or `socks5://user:pass@host:port`. Leave empty for direct.
`API_KEY`	If set, every request except `/`, `/docs`, `/openapi.json`, `/redoc` must include header `X-API-Key: <value>`. Strongly recommended if the port is reachable from outside localhost. Generate with `openssl rand -hex 32`.
`CORS_ORIGINS`	Comma-separated list of allowed browser origins. Empty (default) disables cross-origin browser access entirely.
`DOWNLOAD_ROOT`	Root directory all `output_dir` values are confined to (default: `./downloads`). Requests attempting to escape it (`../`, absolute paths) are rejected with `400`.
`LOG_LEVEL`	Log verbosity: `DEBUG`, `INFO`, `WARNING`, `ERROR` (default: `INFO`)
`DEV_MODE`	Set to `true` to log full upstream responses at DEBUG level
`CACHE_TTL_SECONDS`	TTL in seconds for the in-memory metadata cache (default: `600`). Set to `0` to disable.

Important

QOBUZ_APP_ID and QOBUZ_SECRET must be set manually. APP_ID and SECRET are a matched pair — using mismatched values will cause 400 Invalid Request Signature errors on all download endpoints.

Warning

This server has no authentication by default. If you expose port 8000 beyond 127.0.0.1 (e.g. on a homelab reachable from your LAN, or a cloud host), set API_KEY in .env and pass it as the X-API-Key header on every request. The bundled docker-compose.yml binds to 127.0.0.1:8000 for this reason — change it deliberately if you need broader access.

Start the server with:

python main.py

Or directly with uvicorn:

uvicorn main:app --host 0.0.0.0 --port 8000 --reload

Interactive docs available at http://localhost:8000/docs

Docker

A pre-built image is published automatically to the GitHub Container Registry on every push to main.

docker pull ghcr.io/bartolomeorusso9/qobuz-api:main

Run with your token:

docker run -d \
  -p 127.0.0.1:8000:8000 \
  -e QOBUZ_TOKEN=your_token_here \
  -e API_KEY=your_generated_api_key \
  -e LOG_LEVEL=INFO \
  ghcr.io/bartolomeorusso9/qobuz-api:main

Or with a .env file:

docker run -d \
  -p 127.0.0.1:8000:8000 \
  --env-file .env \
  ghcr.io/bartolomeorusso9/qobuz-api:main

Finding APP_ID and SECRET

APP_ID and SECRET must be extracted manually from the Qobuz web player. They are a matched pair — always use them together.

1. Get the APP_ID

Open play.qobuz.com, open DevTools (F12 / Cmd+Option+I), go to the Network tab and play any track. Click on a track/getFileUrl request — the app_id is visible in the query parameters.

2. Get the SECRET

In the DevTools Console, run:

fetch('https://play.qobuz.com/resources/8.1.0-b019/bundle.js')
  .then(r => r.text())
  .then(js => {
    const secrets = [...new Set([...js.matchAll(/[^a-f0-9]([a-f0-9]{32})[^a-f0-9]/g)].map(m => m[1]))]
    alert('SECRETs:\n' + secrets.slice(0, 5).join('\n'))
  })

Note

The bundle path (8.1.0-b019) changes with each Qobuz release. Find the current one by running in the console:

performance.getEntriesByType('resource').filter(r => r.name.endsWith('.js') && r.name.includes('/resources/')).map(r => r.name)

3. Get the QOBUZ_TOKEN

In DevTools go to Application → Local Storage → play.qobuz.com, or run in the console:

JSON.parse(localStorage.getItem('localuser')).token

4. Test the pair

Try each APP_ID candidate with the first SECRET until /download-url/{track_id} returns 200 OK instead of 400 Invalid Request Signature.

API Schema

Note

If API_KEY is set in .env, every request below (except GET /, /docs, /openapi.json, /redoc) must include header X-API-Key: <your key>. Omitted from the examples below for brevity.

`GET /`

Returns server status, auth state, proxy config and the API base in use. Always public, even when API_KEY is set.

Value	Format
`mp3`	MP3 320 kbps
`flac`	FLAC 16-bit (CD)
`hi24`	FLAC 24-bit ≤96 kHz
`hi96`	FLAC 24-bit >96 kHz (Hi-Res)

Field	Type	Default	Description
`track_id`	`str`	required	Qobuz track ID
`quality`	`str`	`flac`	Source quality: `mp3`, `flac`, `hi24`, `hi96`
`target_format`	`str`	same as `quality`	Output format: `mp3`, `flac`, `alac`, `wav`, `opus` — requires `ffmpeg` for conversion
`output_dir`	`str`	`./downloads`	Directory where the file will be saved, resolved relative to `DOWNLOAD_ROOT`. Paths attempting to escape it are rejected.
`filename_format`	`str`	`{track:02d} - {title}`	Filename template — see Filename format

Placeholder	Value
`{track}`	Track number (e.g. `1`)
`{title}`	Track title
`{artist}`	Performer name
`{album}`	Album title
`{year}`	Release year (e.g. `2026`)
`{date}`	Full release date (e.g. `2026-05-29`)
`{disc}`	Disc number
`{isrc}`	ISRC code
`{genre}`	Genre name