﻿====================================================================
  zvukap 1.0 — аудиофильский плеер для музыкального сервиса Звук  
  (zvuk.com) для Linux
  Руководство пользователя
====================================================================

Содержание
  1. О проекте
  2. Системные требования
  3. Файлы приложения
  4. Запуск приложения
  5. Веб-интерфейс
  6. Вход в аккаунт 
  7. Основные вкладки и управление воспроизведением
  8. Настройки звука
  9. Режимы вывода: bit-perfect, lossy, gapless
 10. Командная строка
 11. Файл конфигурации zvukap.conf
 12. Журнал работы
 13. Завершение работы
 14. Возможные проблемы и их решение


--------------------------------------------------------------------
1. О проекте
--------------------------------------------------------------------
Приложение zvukap воспроизводит музыку из сервиса Звук с максимальным 
качеством через аудиоинтерфейс ALSA и default звуковое устройство, 
заданное в файле /etc/asound.conf.

Приложение состоит из «движка» (воспроизведение и сеть), и веб-интерфейса, 
который открывается в браузере. 

--------------------------------------------------------------------
2. Системные требования
--------------------------------------------------------------------
  * Система Linux x32/x64/arm32/arm64.
  * Установленная звуковая подсистема ALSA
  * Наличие в системе драйвера используемого аудиоустройства.
  * Доступ в Интернет для связи с сервисом Звук.
  * Учётная запись сервиса Звук (для полного доступа желательна
    подписка на сервис; без неё треки доступны в качестве MP3 128 kbps).

--------------------------------------------------------------------
3. Файлы приложения
--------------------------------------------------------------------
В папке приложения находятся:

  * zvukap       — исполняемый файл приложения;
  * zvukap.conf       — файл конфигурации (создаётся/обновляется
                          автоматически; содержит настройки и токены);
  * zvukap.log        — журнал работы (создаётся автоматически).
  * readme_ru.txt       — этот файл.

Файлы zvukap.conf и zvukap.log размещаются в рабочей папке приложения
(обычно это папка, где лежит zvukap). Путь к конфигурации можно
задать параметром командной строки (см. раздел 10).

--------------------------------------------------------------------
4. Запуск приложения
--------------------------------------------------------------------
Запустите zvukap из консоли или через скрипт.

При запуске загружается и используется для настройки режима работы файл 
конфигурации, а веб-интерфейс начинает работу по адресу:
    http://127.0.0.1:8095 или
(порт можно изменить в настройках/конфигурации).
Из локальной сети веб-интерфейс доступен по адресу:
http://<ip_адрес_устройства>:8095

Если запустить приложение из консоли, в неё выводится журнал работы.
Файл zvukap.log содержит информацию о запуске приложения и о критических
ошибках.

--------------------------------------------------------------------
5. Веб-интерфейс
--------------------------------------------------------------------
Откройте веб-интерфейс по адресу  http://<IP_устройства>:8095
или локально по адресу http://127.0.0.1:8095.

Слева (или вверху в мобильном интерфейсе) расположены вкладки: Рекомендации, 
Поиск, Мои альбомы, Плейлисты, Избранное, Радио, Настройки. Внизу слева 
отображается имя текущего аккаунта.

В формате рабочего стола в правой части страницы отображается панель плеера: 
обложка, информация о треке, полоса прокрутки, кнопки управления (предыдущий, 
играть/пауза, следующий, стоп, режим, в избранное, текст песни) 
и регулятор громкости.
В случае узкого окна или мобильного интерфейса меню приложения отображается вверху 
страницы и может прокручиваться по горизонтали, а панель плеера вызывается и 
скрывается кликом по светлому треугольнику, расположенному внизу окна при открытии 
панели плеера и вверху при её сворачивании.

--------------------------------------------------------------------
6. Вход в аккаунт сервиса Звук
--------------------------------------------------------------------
Вкладка «Настройки» → блок входа:

  * Поле «Токен» — для входа с подпиской вставьте токен, получив его 
  * Кнопка «Анонимный вход» — вход без подписки, качество MP3 128 kbps.
  * Кнопка «Выйти» — завершает сеанс.

После успешного входа вверху вкладки «Настройки» и в левом нижнем углу
появляется имя аккаунта и отметка о подписке (если есть).
Токен сохраняется в zvukap.conf, повторный вход при следующем запуске
не требуется.

--------------------------------------------------------------------
7. Основные вкладки и управление воспроизведением
--------------------------------------------------------------------
  * Рекомендации — персональные подборки.
  * Поиск — поиск треков, альбомов и исполнителей. Для выбранного 
    исполнителя доступен список его альбомов для выбора альбомов 
    и добавления их в коллекцию.
  * Мои альбомы — сохранённые альбомы.
  * Плейлисты — ваши плейлисты (создание, переименование, удаление,
    добавление и удаление треков).
  * Избранное — треки, отмеченные лайком в панели плеера при прослушивании.
  * Радио — персональный поток пользователя с настройкой его параметров и 
    потоки редакции.
  * Настройки — вход и параметры воспроизведения/вывода.

Управление:
  * Играть/Пауза — воспроизведение и пауза.
  * Следующий / Предыдущий — переход по очереди.
  * Стоп — остановка воспроизведения.
  * Режим (кнопка со стрелками по кругу) — порядок воспроизведения
    (последовательно / повтор / случайно).
  * Избранное — добавить/убрать трек в «Избранное».
  * Текст — показать текст песни (если доступен).
  * Полоса прокрутки — перемотка внутри трека.
  * Громкость — регулятор уровня (100% = без цифрового ослабления,
    необходимо для bit-perfect).

Дополнительная навигация в панели плеера в веб-интерфейсе:
Если в процессе воспроизведения плейлиста или потока в веб-интерфейсе 
в панели плеера справа кликнуть по названию трека, то в центральном поле 
открывается альбом, в который входит этот трек. Если в панели плеера кликнуть 
по имени исполнителя, то в центральном поле открывается дискография 
исполнителя трека. Кнопка "Назад" вверху слева возвращает в исходный плейлист.

--------------------------------------------------------------------
8. Настройки звука
--------------------------------------------------------------------
Откройте вкладку «Настройки». 
Там доступна настройка следующих параметров:

  * Селектор «Качество»:
       - Авто — FLAC при наличии, иначе MP3;
       - FLAC (lossless) — только без потерь;
       - MP3 — сжатие с потерями.
  * Буфер плеера, мс — объём предварительной загрузки, который 
    сглаживает сетевые задержки (по умолчанию 1000 мс).
  * Стартовый предзапас, мс — воспроизведение начинается только после
    накопления такого объёма данных (0 = сразу).
  * Приоритет потока вывода:
      - SCHED_FIFO (0 = выкл, нужен root). Значения больше нуля и до 99 задают 
	повышенные уровни приоритета.
      - nice (-20..19). Для параметра nice отрицательные значения означают 
	повышение приоритета, а положительные - его уменьшение.
   * Режим передачи в ALSA:
       - MMAP — прямой доступ к буферу драйвера (минимум копирований).
       - R/W  — передача блоков данных драйверу через вызов функции.
   * ALSA период , мс, по умолчанию 0 = авто - размер периода устройства, 
     0 — оставить значение драйвера.
   * ALSA буфер, мс, по умолчанию 0 = авто - размер буфера устройства, 
     0 — оставить значение драйвера.


При нажатии «Применить» выбранные параметры звука сохраняются в
конфигурацию и применяются при следующем открытии устройства.

--------------------------------------------------------------------
9. Режимы вывода: bit-perfect, lossy, gapless
--------------------------------------------------------------------
  * bit-perfect — достигается, когда:
      - выбран FLAC-поток (lossless);
      - устройство открыто «точно» (без ресемплинга и без расширения
        разрядности с реальной обработкой);
      - громкость установлена на 100% (нет цифрового ослабления).
    В этом режиме данные подаются на ЦАП без изменений.
  * lossy — для потоков с потерями (MP3 и т.п.). Даже при точном выводе
    такой поток помечается как «lossy»; bit-perfect к нему неприменим.
  * gapless — бесшовное воспроизведение: следующий трек предзагружается
    заранее, чтобы между треками не было паузы (включается опцией
    gapless в конфигурации).

--------------------------------------------------------------------
10. Командная строка
--------------------------------------------------------------------
  zvukap.exe [параметры]

  -c <файл>,          Указать путь к файлу конфигурации
  --config <файл>     (по умолчанию zvukap.conf рядом с программой).

Примеры:
  ./zvukap
  ./zvukap -c /opt/zvukap/zvukap.conf


--------------------------------------------------------------------
11. Файл конфигурации zvukap.conf
--------------------------------------------------------------------
Формат — INI. Пример:

  [server]
  port = 8095
  [auth]
  token = ...
  [player]
  quality = auto
  volume = 80
  device = default
  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

Описание параметров:
  port               Порт веб-интерфейса (по умолчанию 8090).
  token              Access-токен Звука.
  quality            Качество: flac | mp3 | auto
  volume             Громкость 0..100.
  device             Имя ALSA-устройства (например, default, hw:0,0). 
  ssl_verify         1 = проверять TLS-сертификаты, 0 = не проверять.
  preload_ms         Буфер воспроизведения плеера, мс.
  preload_max_mb     Максимум предзагрузки на трек, МБ (0 = без лимита).
  gapless            1 = предзагрузка и преддекодирование следующего
                     трека (бесшовно).
  prefetch_lead_ms   За сколько мс до конца текущего трека начинать предзагрузку.
  start_ms           Стартовый для воспроизведения размер данных в буфере 
		     плеера, мс.
  alsa_buffer_ms     Буфер ALSA, мс (0…4000; 0 = значение драйвера).
  alsa_period_ms     Период ALSA, мс (0…1000; 0 = значение драйвера).
  alsa_mode          mmap | rw 
  sched_priority     SCHED_FIFO для потока вывода (0…99; 0 = выкл; нужен root).
  sched_nice         nice потока вывода (-20…19).
  web_nice           nice потока веб-интерфейса. Стандартно 10: интерфейс получает
    		     пониженный приоритет, чтобы не мешать воспроизведению.

Большинство параметров можно менять из веб-интерфейса; файл сохраняется
автоматически при изменении настроек и обновлении токенов.

--------------------------------------------------------------------
12. Журнал работы
--------------------------------------------------------------------
Cообщения приложения о запуске и критических ошибках пишутся в файл 
zvukap.log. При запуске из консоли дополненный логом 
событий журнал дополнительно выводится на экран. При
возникновении проблем просмотрите последние строки журнала — там
указываются ошибки сети, устройства и т.п.

--------------------------------------------------------------------
13. Завершение работы
--------------------------------------------------------------------
Завершить приложение можно:
  * из веб-интерфейса (вкладка «Настройки» → ссылка «Завершить
    приложение (/stop)»);
  * из консоли сочетанием Ctrl+C (если запущено из консоли).

--------------------------------------------------------------------
14. Возможные проблемы и их решение
--------------------------------------------------------------------

Потрескивания/«заикание»:
  * Увеличьте кратно размеры буфера и периода ALSA и размер буфера.

Не отображается имя аккаунта:
  * Выполните вход на вкладке «Настройки» (токен или код).
  * При временных сетевых сбоях имя подгружается позже; откройте
    «Настройки» ещё раз.

Не работает bit-perfect:
  * Для lossless используйте качество FLAC, установите громкость 100% и
    устройство, поддерживающее частоту/разрядность трека без
    ресемплинга. Для MP3 bit-perfect недостижим (это lossy-поток).

====================================================================
  zvukap 1.0 · аудиофильский плеер для музыкального сервиса Звук
  © 2026 albumplayer.ru
====================================================================
