﻿====================================================================
  qobuzap 1.0 — an audiophile Qobuz streaming player for Linux
  User Guide
====================================================================

Contents
  1. About the Project
  2. System Requirements
  3. Application Files
  4. Starting the Application
  5. Web Interface
  6. Signing In to Qobuz
  7. Main Tabs and Playback Controls
  8. Audio Settings
  9. Output Modes: bit-perfect, lossy, gapless
 10. Command Line
 11. The qobuzap.conf Configuration File
 12. Log
 13. Exiting the Application
 14. Troubleshooting


--------------------------------------------------------------------
1. About the Project
--------------------------------------------------------------------
qobuzap plays music from the Qobuz streaming service at the highest
available quality through ALSA, using the default audio device defined
in /etc/asound.conf.

The application consists of an engine that handles playback and
networking, and a web interface accessed through a browser.

--------------------------------------------------------------------
2. System Requirements
--------------------------------------------------------------------
  * Linux on x32, x64, arm32 or arm64.
  * The ALSA sound subsystem installed.
  * A driver for the audio device installed on the system.
  * An Internet connection to access Qobuz.
  * A Qobuz account and subscription.

--------------------------------------------------------------------
3. Application Files
--------------------------------------------------------------------
The application folder contains:

  * qobuzap       — the application executable;
  * qobuzap.conf  — the configuration file (created and updated
                    automatically; contains settings and tokens);
  * qobuzap.log   — the log file (created automatically);
  * readme_ru.txt — the Russian-language user guide;
  * readme_en.txt — this file.

The qobuzap.conf and qobuzap.log files are read from the application's
working directory, usually the folder containing qobuzap. The path to
the configuration file can be specified on the command line (see
section 10).

--------------------------------------------------------------------
4. Starting the Application
--------------------------------------------------------------------
Start qobuzap from a console or a script.

At startup, the configuration file is loaded and used to set the
operating parameters. The web interface becomes available at:
    http://127.0.0.1:8099
The port can be changed in the settings or configuration file.

When the application is started from a console, the log is displayed
there. The qobuzap.log file contains information about application
startup and critical errors.

--------------------------------------------------------------------
5. Web Interface
--------------------------------------------------------------------
Open the web interface at http://<device_IP>:8099, or locally at
http://127.0.0.1:8099.

The tabs appear on the left, or at the top in the mobile interface:
Recommendations, Search, My Albums, Playlists, Favorites, Radio and
Settings. The current account name is displayed at the bottom left.

In the desktop layout, the player panel appears on the right side of
the page. It contains the cover art, track information, seek bar,
controls (previous, play/pause, next, stop, playback mode, favorite
and lyrics) and a volume control.

In a narrow window or the mobile interface, the application menu
appears at the top of the page and can be scrolled horizontally. The
player panel can be shown or hidden by clicking the light-colored
triangle: it is at the bottom of the window when the panel is open and
at the top when the panel is collapsed.

--------------------------------------------------------------------
6. Signing In to Qobuz
--------------------------------------------------------------------
On the Settings tab, locate the sign-in section:

  * Enter your email address and password, then click Sign In.
  * Click Sign Out to end the session.

After a successful sign-in, the account name and Qobuz subscription
status, if applicable, appear at the top of the Settings tab and in
the bottom-left corner. The token is saved in qobuzap.conf, so you do
not need to sign in again the next time the application starts.
You can also sign in with a token using the user_auth_token parameter
in qobuzap.conf.

--------------------------------------------------------------------
7. Main Tabs and Playback Controls
--------------------------------------------------------------------
  * Recommendations — Qobuz selections.
  * Search — search for tracks, albums and artists. For a selected
    artist, an album list is available for selecting albums and adding
    them to your collection.
  * Playlists — manage your playlists: create, rename and delete them,
    and add or remove tracks.
  * Favorites — tracks, albums and artists marked as favorites using
    the player panel while listening.
  * Settings — sign-in and playback/output settings.

Controls:
  * Play/Pause — start or pause playback.
  * Next / Previous — move through the queue.
  * Stop — stop playback.
  * Mode (the button with circular arrows) — playback order
    (sequential / repeat / shuffle).
  * Favorite — add or remove a track from Favorites.
  * Lyrics — display song lyrics, if available.
  * Seek bar — seek within the track.
  * Volume — adjust the level (100% = no digital attenuation,
    required for bit-perfect playback).

Additional navigation in the web interface player panel:
While playing a playlist or stream, click the track title in the
player panel on the right to open the album containing the track in
the center pane. Click the artist's name to open the artist's
discography in the center pane. The Back button at the top left
returns you to the original playlist.

--------------------------------------------------------------------
8. Audio Settings
--------------------------------------------------------------------
Open the Settings tab to adjust the following parameters:

  * Quality selector:
       - Auto — FLAC if available; otherwise AAC/MP3;
       - FLAC (lossless) — lossless only;
       - AAC/MP3 — lossy compression.
  * Preferred lossy format:
       - AAC(256) — AAC at 256 kbps;
       - MP3 — MP3 at 320 kbps.
  * Player buffer, ms — the amount of data preloaded to smooth out
    network delays (default: 1000 ms).
  * Initial prebuffer, ms — playback starts only after this amount of
    data has been buffered (0 = immediately).
  * Output thread priority:
       - SCHED_FIFO (0 = off; requires root). Values from 1 to 99 set
         elevated priority levels.
       - nice (-20..19). Negative nice values increase priority;
         positive values decrease it.
  * ALSA transfer mode:
       - MMAP — direct access to the driver buffer, minimizing copies.
       - R/W — data blocks are passed to the driver via a function call.
  * ALSA period, ms — device period size; default 0 = auto. Set to 0
    to retain the driver value.
  * ALSA buffer, ms — device buffer size; default 0 = auto. Set to 0
    to retain the driver value.

When you click Apply, the selected audio settings are saved to the
configuration and take effect the next time the device is opened.

--------------------------------------------------------------------
9. Output Modes: bit-perfect, lossy, gapless
--------------------------------------------------------------------
  * bit-perfect — achieved when:
      - a FLAC stream (lossless) is selected;
      - the device is opened in an exact format, without resampling
        or bit-depth expansion involving actual processing;
      - volume is set to 100% (no digital attenuation).
    In this mode, data is sent to the DAC unchanged.
  * lossy — applies to lossy streams (MP3, etc.). Even with exact
    output, such a stream is marked as lossy; bit-perfect does not
    apply to it.
  * gapless — seamless playback: the next track is preloaded so that
    there is no pause between tracks. Enable it with the gapless
    configuration option.

--------------------------------------------------------------------
10. Command Line
--------------------------------------------------------------------
  qobuzap.exe [options]

  -c <file>,          Specify the path to the configuration file
  --config <file>     (default: qobuzap.conf next to the program).

Examples:
  qobuzap.exe
  qobuzap.exe -c /opt/qobuzap/qobuzap.conf

--------------------------------------------------------------------
11. The qobuzap.conf Configuration File
--------------------------------------------------------------------
The file uses INI format. Example:

  [server]
  port = 8099
  language = english
  [auth]
  email = ...
  password = ...
  user_auth_token = ...
  [player]
  quality = auto
  volume = 80
  device = default
  client_name = qobuzap
  ssl_verify = 1
  preload_ms = 1000
  preload_max_mb = 128
  gapless = 1
  prefetch_lead_ms = 15000
  start_ms = 500
  alsa_buffer_ms = 200
  alsa_period_ms = 50
  shed_priority = 0
  shed_nice = 0
  web_nice = 10

Parameter descriptions:
  port               Web interface port (default: 8090).
  language           Interface language: english/russian.
  email              User's email address.
  password           User's encrypted password.
  user_auth_token    Qobuz access token.
  quality            Quality: flac | mp3 | auto.
  volume             Volume, 0..100.
  device             ALSA device name (for example, default, hw:0,0).
  client_name        Client name passed to the service.
  ssl_verify         1 = verify TLS certificates; 0 = do not verify.
  preload_ms         Player playback buffer, in ms.
  preload_max_mb     Maximum preload per track, in MB (0 = unlimited).
  gapless            1 = preload and predecode the next track for
                     seamless playback.
  prefetch_lead_ms   How many ms before the end of the current track
                     to begin preloading.
  start_ms           Amount of data required in the player buffer
                     before playback starts, in ms.
  alsa_buffer_ms     ALSA buffer, in ms (0–4000; 0 = driver value).
  alsa_period_ms     ALSA period, in ms (0–1000; 0 = driver value).
  alsa_mode          mmap | rw.
  sched_priority     SCHED_FIFO for the output thread (0–99;
                     0 = off; requires root).
  sched_nice         nice value of the output thread (-20–19).
  web_nice           nice value of the web interface thread. The
                     default is 10: the interface runs at lower
                     priority to avoid interfering with playback.

Most parameters can be changed through the web interface. The file is
saved automatically when settings are changed or tokens are updated.

--------------------------------------------------------------------
12. Log
--------------------------------------------------------------------
Application startup messages and critical errors are written to
qobuzap.log. When the application is started from a console, the log,
including additional event messages, is also displayed on screen. If
you encounter a problem, check the last lines of the log for network,
device and other errors.

--------------------------------------------------------------------
13. Exiting the Application
--------------------------------------------------------------------
You can exit the application:
  * from the web interface (Settings tab → the Exit Application
    (/stop) link);
  * from the console by pressing Ctrl+C, if it was started there.

--------------------------------------------------------------------
14. Troubleshooting
--------------------------------------------------------------------

Crackling or stuttering:
  * Increase the ALSA buffer and period sizes, as well as the player
    buffer size, by multiples of their current values.

Account name is not displayed:
  * Sign in on the Settings tab (using a token or code).
  * If there is a temporary network issue, the name may load later;
    open Settings again.

Bit-perfect playback does not work:
  * For lossless playback, select FLAC quality, set the volume to 100%,
    and use a device that supports the track's sample rate and bit
    depth without resampling. Bit-perfect playback is not possible for
    MP3 because it is a lossy stream.

====================================================================
  qobuzap 1.0 · Audiophile Qobuz Player
  © 2026 albumplayer.ru
====================================================================
