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

Содержание
  1. О проекте
  2. Системные требования
  3. Файлы приложения
  4. Запуск приложения
  5. Значок в трее и графический виджет
  6. Веб-интерфейс
  7. Вход в аккаунт
  8. Основные вкладки и управление воспроизведением
  9. Настройки звука
     9.1. Устройство вывода (WASAPI / ASIO)
     9.2. WASAPI Exclusive
     9.3. ASIO
     9.4. Буферизация плеера и приоритет потока
     9.5. Качество звука
 10. Режимы вывода: bit-perfect, lossy, gapless
 11. Командная строка
 12. Файл конфигурации zvukap.conf
 13. Журнал работы
 14. Завершение работы
 15. Возможные проблемы и их решение


--------------------------------------------------------------------
1. О проекте
--------------------------------------------------------------------
Приложение zvukap воспроизводит музыку из сервиса
Звук с максимальным качеством через
эксклюзивные аудиоинтерфейсы Windows:

  * WASAPI Exclusive (монопольный доступ к устройству, в обход
    системного микшера);
  * ASIO (драйверы профессиональных и аудиофильских устройств).

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

--------------------------------------------------------------------
2. Системные требования
--------------------------------------------------------------------
  * Windows 7/8/10/11 (32/64-разрядная).
  * Установленный драйвер аудиоустройства; для ASIO — ASIO-драйвер
    производителя для используемой платформы приложения (x86 или x64).
  * Доступ в Интернет для связи с сервисом Звук.
  * Учётная запись сервиса Звук (для полного доступа желательна
    подписка на сервис; без неё треки доступны в качестве MP3 128 kbps).

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

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

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

--------------------------------------------------------------------
4. Запуск
--------------------------------------------------------------------
Запустите zvukap.exe (двойным щелчком или из ярлыка). Откроется
графический виджет, а в системном трее появится значок приложения.

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

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

--------------------------------------------------------------------
5. Значок в трее и графический виджет
--------------------------------------------------------------------
Графический виджет — компактное окно с обложкой, названием трека,
исполнителем, значками формата и органами управления:

  * Верхняя строка:
      - слева — кнопка свернуть/скрыть в трей;
      - справа — ссылка «веб-интерфейс» (открывает браузер).
  * Обложка альбома.
  * Исполнитель и название трека.
  * Значки формата:
      - кодек и разрядность вывода, например «FLAC 16-bit», «MP3 16-bit»;
      - «bit-perfect» — только для lossless-потока (FLAC) при выводе
        без изменений и громкости 100%. Для MP3 и других форматов с
        потерями этот значок не показывается (поток помечается как lossy).
  * Полоса прокрутки трека (клик — перемотка).
  * Кнопки: предыдущий, играть/пауза, следующий, стоп, избранное.
  * Регулятор громкости.

Виджет можно перетаскивать за любую свободную область и скрывать в
трей. После нажатия на ссылку «веб-интерфейс» виджет автоматически
скрывается в трей через 2 секунды, чтобы не мешать работе в браузере.

Меню значка в трее (правый клик) содержит команды:
  * Играть/Пауза;
  * Стоп;
  * Следующий / Предыдущий;
  * Показать/скрыть виджет;
  * Веб-интерфейс (открыть в браузере);
  * Выход (завершить приложение).
Двойной/одинарный левый клик по значку в трее показывает или скрывает
виджет.

--------------------------------------------------------------------
6. Веб-интерфейс
--------------------------------------------------------------------
Веб-интерфейс — основной способ навигации по каталогу сервиса Звук.
Откройте его по адресу http://127.0.0.1:8090 или через ссылку в виджете
/ пункт меню трея «Веб-интерфейс».

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

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

Веб-интерфейс доступен и с других устройств в локальной сети, если
разрешить при первом запуске доступ к веб-серверу из сети.

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

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

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

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

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

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

--------------------------------------------------------------------
9. Настройки звука
--------------------------------------------------------------------
Откройте вкладку «Настройки». Блоки параметров вывода показываются в
зависимости от выбранного устройства: для ASIO — одни, для WASAPI —
другие. Тип вывода (ASIO или WASAPI Exclusive) определяется
автоматически по выбранному устройству — отдельного переключателя нет.

9.1. Устройство вывода (WASAPI / ASIO)
--------------------------------------
В списке «Устройство вывода» перечислены все доступные устройства:
  * [WASAPI] ... — обычные звуковые устройства Windows в монопольном
    (exclusive) режиме;
  * [ASIO] ... — драйверы ASIO.
Значение «По умолчанию» использует WASAPI-устройство по умолчанию.

После выбора устройства нажмите «Применить». При смене устройства
воспроизведение останавливается, и устройство переоткрывается при
следующем запуске воспроизведения (это сделано намеренно — «горячее»
переключение устройства во время проигрывания могло приводить к сбою).

9.2. WASAPI Exclusive
---------------------
  * Режим WASAPI Exclusive:
      - Pull (Event-driven) — рекомендуемый режим, драйвер сам
        «вытягивает» данные по событию;
      - Push (Timer-driven) — вывод по таймеру (актуален для некоторых
        устройств/драйверов).
  * Буфер WASAPI Exclusive, мс — размер буфера вывода в миллисекундах;
    0 = значение по умолчанию (50 мс). Меньший буфер уменьшает
    задержку, но повышает нагрузку и риск «заикания».

9.3. ASIO
---------
  * Буфер ASIO, семплов — размер буфера ASIO-драйвера в кадрах (сэмплах);
    0 = размер по умолчанию драйвера (рекомендуется оставить 0).
  * Панель ASIO — открывает собственную панель управления драйвера
    (Control Panel), где настраиваются буфер и другие параметры устройства.

Про размер буфера ASIO:
  * При значении 0 приложение запрашивает у драйвера «предпочтительный»
    (preferred) размер и использует его ровно так, как драйвер его сообщил — 
    это штатный режим драйвера.
  * Если задать конкретное значение, оно проверяется на допустимость и
    выравнивается по гранулярности драйвера (granularity).

9.4. Буферизация плеера и приоритет потока
------------------------------------------
  * Буфер плеера, мс — объём предварительной загрузки, который 
    сглаживает сетевые задержки (по умолчанию 1000 мс).
  * Стартовый предзапас, мс — воспроизведение начинается только после
    накопления такого объёма данных (0 = сразу).
  * «держать аудиоустройство открытым между треками» — не закрывать
    устройство при переходах между треками (снижает паузы, помогает
    gapless).
  * Приоритет потока вывода:
      - Обычный (Normal);
      - Высокий (High);
      - Реального времени (MMCSS Pro Audio) — максимальный приоритет
        звукового потока (для WASAPI).

9.5. Качество звука
-------------------
Селектор «Качество»:
  * Авто — FLAC при наличии, иначе MP3;
  * FLAC (lossless) — только без потерь;
  * MP3 — сжатие с потерями.

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


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


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

  --no-gui, -nogui    Запуск без графического виджета (только движок и
                      веб-интерфейс; в консоли).
  -c <файл>,          Указать путь к файлу конфигурации
  --config <файл>     (по умолчанию zvukap.conf рядом с программой).

Примеры:
  zvukap.exe
  zvukap.exe --no-gui
  zvukap.exe -c D:\music\zvukap.conf


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

  [server]
  port = 8095
  [auth]
  token = ...
  [player]
  quality = auto
  volume = 80
  output_mode = auto
  device = default
  ssl_verify = 1
  preload_ms = 1000
  preload_max_mb = 128
  gapless = 1
  prefetch_lead_ms = 15000
  start_ms = 500
  keep_open = 1
  wasapi_buffer_ms = 50
  wasapi_event_mode = 1
  asio_buffer_size = 0
  thread_priority = 1

Описание параметров:
  port               Порт веб-интерфейса (по умолчанию 8090).
  token              Access-токен Звука.
  quality            Качество: flac | mp3 | auto.
  volume             Громкость 0..100.
  output_mode        Режим вывода: wasapi | asio | auto.
  device             Выбранное устройство (id WASAPI или имя ASIO-
                     драйвера); "default" — устройство по умолчанию.
  ssl_verify         1 = проверять TLS-сертификаты (рекомендуется),
                     0 = не проверять.
  preload_ms         Буфер воспроизведения плеера, мс.
  preload_max_mb     Максимум предзагрузки на трек, МБ (0 = без лимита).
  gapless            1 = предзагрузка и преддекодирование следующего
                     трека (бесшовно).
  prefetch_lead_ms   За сколько мс до конца текущего трека начинать предзагрузку.
  start_ms           Стартовый для воспроизведения размер данных в буфере 
                     плеера, мс.
  wasapi_buffer_ms   Буфер WASAPI Exclusive, мс (0 = 50 мс).
  wasapi_event_mode  1 = Pull (event), 0 = Push (timer).
  asio_buffer_size   Буфер ASIO, кадры (0 = по умолчанию драйвера).
  thread_priority    0 = Normal, 1 = High, 2 = Time-Critical.

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


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

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

При завершении убирается значок из трея и корректно закрывается
аудиоустройство.

--------------------------------------------------------------------
15. Возможные проблемы и их решение
--------------------------------------------------------------------
Нет звука:
  * Проверьте, что выбрано правильное «Устройство вывода» и нажато
    «Применить».
  * Для ASIO убедитесь, что выбран пункт [ASIO] вашего драйвера, а не
    одноимённое WASAPI-устройство.
  * Проверьте уровень громкости (регулятор VOL) и системную громкость.
  * Посмотрите zvukap.log.

ASIO Control Panel не открывается или сразу закрывается:
  * Панель доступна только для ASIO-устройств и не все ASIO драйверы её
    предоставляют. Сначала выберите [ASIO] устройство и нажмите «Применить».
  * Панель открывается заранее (до начала воспроизведения); это
    позволяет выполнить настройки драйвера предварительно.

Аудиоустройство не открывается (занято):
  * Закройте другие приложения, использующие это устройство в
    монопольном режиме, или закройте панель ASIO перед воспроизведением.

Потрескивания/«заикание»:
  * Увеличьте «Буфер WASAPI» (мс) или «Буфер ASIO» (сэмплов).
  * Для ASIO попробуйте оставить размер буфера по умолчанию (0).
  * Установите для WASAPI приоритет потока «Реального времени (MMCSS Pro Audio)».

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

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


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