﻿====================================================================
  yandexap — аудиофильский плеер Яндекс Музыки для 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. Файл конфигурации yandexap.conf
 13. Журнал работы
 14. Завершение работы
 15. Возможные проблемы и их решение


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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  * Поле «Токен или код авторизации» — вставьте OAuth-токен либо
    авторизационный код.
  * Ссылка «Открыть авторизацию» — открывает страницу Яндекс OAuth.
    После подтверждения доступа скопируйте из адресной строки параметр
    code (или вставьте всю ссылку целиком — код распознаётся
    автоматически) и нажмите «Войти».
  * Кнопка «Выйти» — завершает сеанс и удаляет сохранённый токен.

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

--------------------------------------------------------------------
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. Командная строка
--------------------------------------------------------------------
  yandexap.exe [параметры]

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

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


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

  [server]
  port = 8090
  [auth]
  token = ...
  refresh_token = ...
  [player]
  quality = auto
  volume = 80
  output_mode = auto
  device = default
  client_name = yandexap
  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-токен Яндекс Музыки.
  refresh_token      Токен обновления (заполняется автоматически).
  quality            Качество: flac | mp3 | auto.
  volume             Громкость 0..100.
  output_mode        Режим вывода: wasapi | asio | auto.
  device             Выбранное устройство (id WASAPI или имя ASIO-
                     драйвера); "default" — устройство по умолчанию.
  client_name        Имя клиента, передаваемое сервису.
  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ообщения приложения о запуске и критических ошибках пишутся в файл 
yandexap.log (рядом с exe). При запуске из консоли дополненный логом 
событий журнал дополнительно выводится на экран. При
возникновении проблем просмотрите последние строки журнала — там
указываются ошибки сети, устройства и т.п.

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

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

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


====================================================================
  yandexap · аудиофильский плеер Яндекс Музыки (Windows)
  © 2026 albumplayer.ru
====================================================================
