﻿====================================================================
  yandexap — аудиофильский плеер Яндекс Музыки для Linux
  Руководство пользователя
====================================================================

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


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

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

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

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

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

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

--------------------------------------------------------------------
4. Первый запуск
--------------------------------------------------------------------
Запустите yandexap из консоли или через скрипт.

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

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

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

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

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

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

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

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

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

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

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

  * Селектор «Качество»:
       - Авто — FLAC при наличии, иначе AAC/MP3;
       - FLAC (lossless) — только без потерь;
       - AAC/MP3 — сжатие с потерями.
  * Предпочтительный lossy формат:
       - AAC(256) - формат AAC 256 kbps;
       - MP3 — формат MP3 320 kbps.
  * Буфер плеера, мс — объём предварительной загрузки, который 
    сглаживает сетевые задержки (по умолчанию 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. Командная строка
--------------------------------------------------------------------
  yandexap.exe [параметры]

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

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


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

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

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

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

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

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

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

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