qconnect

Standalone Qobuz Connect CLI client originally based on the qconnect-* Rust crates from vicrodh/qbz.

TLDR

cargo install qconnect
# rehash (zsh) / hash -r (bash) / ...
qconnect serve
# In your player app choose qconnect-cli (hostname)

Install

Binaries can be found on the release pages.

cargo install qconnect

Development version

cargo install --git https://github.com/ahcm/qconnect

Linux Audio Builds

For local audio playback on Linux, prefer a normal glibc/dynamically linked build made on a compatible distro:

cargo build --release

Note

Avoid shipping Alpine/musl/static binaries as general-purpose audio builds. ALSA often resolves the default device through runtime-loaded modules such as PulseAudio/PipeWire config plugins. Static musl builds can link libasound but still fail at runtime with messages like Dynamic loading not supported or Unknown PCM default when those ALSA modules cannot be loaded on the target system.

Musl/static builds are still reasonable for state/control use.

Credentials

The easiest setup on a desktop machine is browser OAuth:

qconnect login

This opens Qobuz in your browser, captures the localhost callback, and saves the discovered app id plus QOBUZ_USER_AUTH_TOKEN under your qconnect config directory for later commands. Use qconnect login --print-token if you need the raw token for another environment.

On a headless machine, paste credentials directly:

qconnect login --manual

or use noninteractive arguments:

qconnect login --app-id '...' --user-auth-token '...'

The CLI can also connect with explicit environment variables:

export QOBUZ_APP_ID=...
export QOBUZ_USER_AUTH_TOKEN=...
qconnect status

or with already-created Qobuz Connect websocket credentials:

qconnect --endpoint 'wss://...' --jwt-qws '...' status

QOBUZ_APP_ID and QOBUZ_USER_AUTH_TOKEN are used to call https://www.qobuz.com/api.json/0.2/qws/createToken, which returns the Connect websocket endpoint and JWT.

Commands

Run as a headless Qobuz Connect renderer:

qconnect serve

This makes the process visible to other Qobuz Connect controllers and plays audio locally. Use serve --no-audio if you only want MPRIS updates.

List Linux audio backend/device ids:

qconnect audio-devices
qconnect audio-devices --audio-backend alsa

Select a backend/device explicitly:

qconnect serve --audio-backend alsa --audio-device hw:0,0

Inspect state:

qconnect status
qconnect queue --wait-secs 8

Control the active renderer:

qconnect load 123456 234567 --start-index 0
qconnect add 345678
qconnect play
qconnect pause
qconnect volume --set 65
qconnect shuffle on
qconnect repeat all

Use --json for machine-readable event output.