# Riff — вопросы и ответы

## Зачем ещё один плеер

### Что такое Riff?

Плеер для своей музыки и аудиокниг на Android. В первую очередь — для китайских Android-магнитол.
Записал коллекцию на накопитель, сел в машину и слушаешь.

### Но ведь уже есть Poweramp, Musicolet и ещё сотня плееров?

Есть, и хорошие. Просто у магнитолы свои неприятности: маленькие кнопки неудобны, экран может
странно сообщать свой размер, а питание исчезает без прощального диалога. Riff вырос из желания
сделать плеер под эти условия: крупные кнопки, короткие пути по библиотеке, книги отдельно от
музыкального перемешивания.

### А автору это зачем?

Ездить со своей музыкой там, где интернет закончился раньше дороги. Один и тот же альбом надоедает,
вручную собирать плейлисты каждый раз не хочется. Отсюда локальный анализ музыки и подбор по
настроению. Текущий релиз приложения — 1.1.0 FINAL. Модель AI остаётся public beta; автор
по-прежнему делает плеер прежде всего для собственного использования.

### Будет версия для macOS?

В планах её нет. Главная задача проекта — Android-магнитолы, а магнитол на macOS в этой истории пока
не встречалось. Версии для iOS тоже нет.

### На телефоне или планшете можно?

Да, если это Android 12 или новее и устройство поддерживает arm64-v8a. Автомобильные привычки
интерфейса при этом остаются.

### Это приложение для AAOS или Android Auto?

Нет, рассчитывай прежде всего на прямую установку на обычную Android-магнитолу. Полная интеграция с
AAOS и Android Auto пока не сделана. AAOS требует связи с автомобилем, включая ограничения в
движении; на сторонней магнитоле нужных сигналов может не быть или им нельзя доверять.

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

### Почему интерфейс такой суровый? Winamp был наряднее

Чтобы попадать по кнопке с первого раза. Среди источников вдохновения — пульт фрезерного станка и
немного авиационных приборов. Это не шутка. Обложки остаются, но удобство управления здесь важнее
конкурса тем оформления.

## Музыка и первый запуск

### Интернет, аккаунт и подписка нужны?

Для прослушивания — нет. Музыка твоя, анализ идёт на устройстве. Песни на сервер отправлять не
нужно. Riff не выдаёт каталог и не скачивает новые альбомы; APK и обновления получаются отдельно.

### Он бесплатный? Есть платные функции?

Код открыт под GPL-3.0-or-later. Пожертвование не открывает секретный эквалайзер или «настоящий AI»:
доступ к функциям, коду и использованию от него не зависит. Сторонний распространитель может брать
деньги за свою сборку — GPL это разрешает. У сторонних библиотек и модели есть собственные лицензии.

### Как добавить флешку или папку с музыкой?

Установи подписанный APK своего распространителя. При первом запуске Riff предложит выбрать папки:
**Add.. → папка в системном диалоге Android → разрешить доступ**. Подтверди **Media folders** и дай
библиотеке прочитаться.

Потом источники можно менять в **Settings → More… → Media folders…**. Если Android не показывает
накопитель в своём диалоге, одним нажатием в Riff это не исправить.

### Музыка есть на флешке, а в Riff её нет. Куда смотреть?

Начни с простого: флешка подключена, доступ к нужной папке разрешён, индексация закончилась?
Посмотри **Folders** и переключатель **Music/Books**. Файл может быть доступен через папку, но не
попасть в Albums из-за тегов. У CUE и файлов с главами есть свои правила группировки. Если файл не
виден вообще, проверь, читается ли он и поддерживается ли его настоящий формат.

### Какие форматы он играет?

Имеет значение содержимое файла и декодирование на устройстве, а не красивые буквы после точки.
Переименованный в `.mp3` файл от этого не станет MP3. Если что-то не играет, полезны точный формат и
небольшой пример файла, которым можно поделиться.

### Где обложка? Он сам её скачает?

Нет, интернет за обложкой не нужен и автоматически она не скачивается. Сначала Riff берёт подходящую
встроенную картинку. Без неё может взять изображение рядом с аудиофайлом, если в этой папке ровно
одна доступная картинка, которую удалось прочитать. Если их несколько, угадывать между `cover.jpg`,
задником и буклетом он не будет.

### Названия кривые, а один альбом стал тремя. Что делать?

Проверь исходные теги: Album, AlbumArtist, год, номера дисков и треков. Расположение файлов и
CUE/TOC тоже влияют на сборку альбома. Один и тот же текст Album ещё не повод склеить разные
издания. Без Title названием может стать имя файла.

Исправь теги внешним редактором и переиндексируй коллекцию. Riff осторожно исправляет некоторые
ошибки отображения кодировки, но не гадает, если результат неоднозначный.

### Он не испортит мои файлы?

Индексация читает аудио, а не переписывает в нём теги. Индекс и результаты анализа живут отдельно.
Где Android разрешает запись, может появиться небольшая служебная папка Riff. Удалить папку из
источников — значит закрыть плееру доступ, а не стереть музыку.

### Почему большая коллекция так долго готовится?

Тысячи файлов на медленной флешке — это тысячи чтений, а затем ещё анализ звука. Файл уже может
играть, хотя его анализ пока не готов. Смотри текущий статус и подключение накопителя. Повторные
сбросы базы только заставят работу начаться заново.

### Что за AU и IA в Rebuild DB?

**AU** пересчитывает AI и ReplayGain, **IA** заново строит индекс файлов. Выбери нужное и сохрани
**More**. Музыку это не удаляет, но придётся подождать, пока соответствующая часть библиотеки снова
станет готова.

## В машине

### Почему плеер замолкает с выключенным экраном?

Закрытие интерфейса само по себе не должно выключать звук: воспроизведение ведёт сервис. Но прошивка
может ограничивать фоновые приложения, Bluetooth — прислать Pause, навигатор — забрать аудиофокус, а
флешка — отключиться.

Сначала поймай момент остановки. Если дело в энергосбережении, проверь фоновые ограничения Riff в
настройках Android. Если не помогло, напиши модель магнитолы, прошивку и что именно происходит перед
остановкой.

### А кнопки в уведомлении или на экране блокировки где?

Их показывает Android на основе медиасессии Riff. Проверь системные настройки уведомлений и
медиакнопок, а также запущено ли воспроизведение. Внешний вид зависит от прошивки. Пересобирать
музыкальную базу ради пропавшей кнопки не надо.

### Кнопки на руле и Bluetooth работают?

Если устройство отправляет обычные медиакоманды Android, это нужный путь управления. Но часть
магнитол передаёт рулевые кнопки только своим встроенным приложениям через MCU. Riff не может
обещать поддержку любого такого протокола.

Сравни экранные Play/Pause/Next с теми же командами от внешнего устройства. Для разбирательства
нужны модель, прошивка и способ подключения.

### Он сам включится после зажигания или подключения Bluetooth?

Универсальный автозапуск от этих событий пока не обещан. Иногда магнитола сама посылает Play; иногда
речь о сохранённом состоянии плеера. Это разные вещи, и поведение конкретной магнитолы лучше
проверить на месте.

### Что будет, когда заговорит навигатор?

При нужном аудиофокусе музыка станет тише, а потом вернётся к прежней громкости. Книга остановится,
дождётся возвращения фокуса и продолжится с отступом на две секунды: так легче вспомнить прерванную
фразу. Если ты сам нажал Pause или Stop, автоматически продолжать вместо тебя Riff не будет.

### Кнопки слишком большие или слишком маленькие. Как поправить?

**Settings → More… → Diagonal**. Можно указать диагональ или выбрать **Card** и подогнать рисунок
под физическую карту либо поддерживаемую банкноту. Подтверди калибровку, затем сохрани **More**.
**Auto** возвращает стартовую оценку. Если сама прошивка растягивает или обрезает картинку,
результат тоже может пострадать.

## Поиск и подбор музыки

### Свой поиск — это попытка заново изобрести T9?

Скорее буквенный фильтр для длинного списка. Идея близка к автомобильным интерфейсам, на которые
ориентировался автор, включая BMW и Mercedes. В Riff есть кириллица и **Auto search**: клавиатура
сама открывается для длинного списка и заканчивает работу, когда выбирать уже несложно.

Каждый шаг сужает имена в открытом контейнере. Это не поиск по всем вложенным папкам. **#** собирает
прочие символы, а не заменяет любую букву.

### AI настоящий или просто модная надпись?

В сборке есть настоящая локальная модель на основе **EfficientAT**. У неё четыре задачи: Arousal,
Valence, воспринимаемая скорость PTE и жанры. Все они используют общий анализ звука, а не четыре
независимые тяжёлые модели. Интернет для этого не нужен.

Это не разговорный помощник и не обещание безошибочно понимать твой вкус. Модель ещё beta-качества.
Анализ файлов общий, а подбор учитывает реакции, историю и выбранные параметры активного профиля.

### Переведи A, V и PTE на человеческий

**A** — насколько музыка спокойная или возбуждающая: уютный вечер на диване против желания прыгать.
**V** — позитивный или мрачный оттенок. Эти две оси описывают настроение в духе модели эмоций
Рассела. Высокие A и V — энергично и радостно; низкие — спокойно и меланхолично.

**PTE** — ощущение «медленно/быстро». Это отдельная оценка, а не BPM. Быстрое не всегда бодрое,
спокойное не всегда медленное. Оценки A/V/PTE лежат от −1 до +1, но запоминать цифры для выбора
музыки не требуется.

### Почему AI ещё занят или выдал меньше треков?

Нужен готовый пригодный анализ. То, что файл играет, не гарантирует успешный анализ. В Books AI
выключен. Если подходящих треков мало, подборка будет короче — добавлять книги или обходить
исключения ради красивого числа Riff не должен. Автоматически распознанная книга не становится
кандидатом AI после ручного переключения в Music.

### Зачем Like, Dislike и Ban без доступа в интернет?

Чтобы объяснить локальному подбору твои предпочтения. Смысл такой: Like — чаще, Dislike — реже, Ban
— не включать в AI-подборку. Забаненный файл можно запустить вручную.

Реакции сохраняются отдельно для каждого профиля и учитываются в следующих AI-подборках. Уже
играющую очередь они не переписывают. Сама нейросеть при этом общая: лайк меняет предпочтение при
выборе трека, а не запускает обучение новой личной модели.

### Зачем банить, если можно просто удалить?

Новогодняя музыка хороша зимой, но на летнем пляже может надоесть. Забанил на сезон, потом вернул —
файлы целы. Делать из этого календарный комбайн автору не хочется: часам магнитолы не всегда стоит
верить, да и у простого плеера должны быть границы.

### А если любимый жанр одного слушателя раздражает другого?

Для этого есть профили **1**, **2**, **3** в Settings. У каждого свои плейлисты, история,
сохранённые позиции и режим Music/Books; коллекция общая. Можно завести один профиль себе, другой —
второму слушателю. Переключение не заменяет уже играющую очередь.

Для AI работает та же семейная дипломатия: например, оставить жанр в профиле 1, а в профиле 3
открыть **Genres**, выбрать его и поставить **Ban**. Следующая AI-подборка профиля 3 этот жанр
исключит; профиль 1 сохранит свои предпочтения. Для новой выдачи после переключения нужно запустить
новый подбор — уже готовая очередь остаётся прежней.

### Я изменил плейлист. Почему продолжает играть старая очередь?

Потому что при запуске плеер делает фиксированную очередь. Редактирование сохранённого плейлиста не
переписывает то, что уже играет. Повторы могут быть намеренными. AI тоже делает конечную подборку, а
не бесконечный поток новых решений.

## Аудиокниги

### Книги слушать можно? Как отделить их от музыки?

Да. Включи **Books**: Albums станут Titles, Artists — Authors. Самый понятный способ подготовить
файлы — добавить жанр **Audiobook** или распознаваемый его вариант, например **Аудиокнига**.
Литературный жанр можно сохранить рядом: `Драма; Audiobook`. Лучше поправить теги до копирования на
флешку.

Есть и другие признаки: расширение M4B, поддерживаемый тег типа медиа, системная папка Android
**Audiobooks**. Если у одного участника собранного альбома есть автоматический признак книги, весь
этот альбом считается книгой. Просто одинаковый текст Album в разных изданиях ещё не делает их одним
альбомом.

Если автоматика промахнулась, в действиях трека, книги/альбома или папки выбери **Book**, **Music**
или **Auto**. Последнее возвращает автоматическое или наследуемое правило.

### Главы M4B поддерживаются?

Да, а также поддерживаемые главы MP4 и MP3. Если они записаны в файле и правильно прочитаны, Riff их
покажет. Придумывать главы для файла без разметки он не будет.

### Как поставить закладку?

Начни книгу из **Title**, затем используй кнопку Bookmark. Запуск того же файла через Folders сам по
себе эту кнопку не открывает. От существующей закладки тоже можно продолжать книгу и добавлять новые
отметки.

Между отметками должно быть хотя бы 15 секунд по умолчанию. Если нужная длительность ещё неизвестна
или действие ограничено текущим автомобильным режимом, новая отметка может быть недоступна. Ручные
закладки не исчезают просто потому, что книга дослушана. Первая отметка сохраняет динамическую
очередь Title. Повторное открытие этого Title использует ту же очередь и закладки. Удаление
последней отметки удаляет сохранённую книжную очередь; удаление всех её элементов удаляет и отметки.
Интервал задаётся через `player.bookmarkMinSpacingSeconds` во внешнем `.riff/ui_config.json` рядом с
маркером тома и применяется после перезапуска. Внутри интервала кнопка серая и не работает; ровно на
границе закладку поставить можно. Расстояние считается по всей книге, включая границы глав.

### После выключения магнитолы продолжит с того же места?

Каждый профиль сохраняет последнюю динамическую очередь, её порядок и позицию — в том числе очередь
из альбома, папки или AI. Новая динамическая очередь заменяет предыдущую: отдельная позиция для
каждого когда-либо открытого альбома не ведётся. Сохранённый плейлист или книга с закладками держит
позицию в своей очереди. Если специально выбрать отдельный трек, он начнётся с начала.

Во время игры позиция сохраняется периодически. Если резко выдернуть питание, самый свежий кусок
прогресса может потеряться. Устойчивость к таким отключениям — одна из причин существования Riff, но
обещания «не потеряется ни одной секунды при любом сбое» здесь нет.

## Звук

### Где эквалайзер?

Его нет, и добавлять его автор не планирует. Настройку звучания он предпочитает оставлять
аудиотракту: системному DSP, например [JamesDSP](https://james34602.github.io/JamesDSPManager/),
либо отдельному процессору/усилителю с DSP — для машины автор предпочитает этот вариант. Подходит ли
системный вариант именно твоей магнитоле, зависит от её прошивки и способа вывода звука.

ReplayGain и ограничитель пиков в Riff есть: чтобы соседние записи не заставляли постоянно крутить
громкость. На Android плеер делает эту работу над аудиоданными сам.

### Что означает ReplayGain: F? А I и N?

**F** — обработка с выходом float32; **I** — обработка с выходом int16; **N** — без обработчика
ReplayGain Riff. В I/F на входе обработчика уже PCM16, к нему применяется поправка громкости, а
затем ограничитель пиков.

F не округляет результат второй раз до int16. Если на конкретном устройстве с ним есть проблемы,
можно попробовать I. Это не гарантия, что I совместим вообще с любой прошивкой. Менять режим нужно в
**Settings → More… → ReplayGain**, затем сохранить **More**.

### А цифры 16, 18, 23 и 0 рядом с режимом?

Это целевая громкость: **16** означает −16 LUFS, **18** — −18 LUFS, **23** — −23 LUFS. Сейчас
стартовая настройка — **F / 23**. Это не заставляет каждый момент песни иметь одинаковую громкость:
речь об общем уровне записи.

**0** убирает поправку ReplayGain, но в I/F ограничитель продолжает работать. Полностью убрать
обработчик Riff можно режимом **N**. Если подходящих gain-данных нет, плеер не придумывает поправку
только из выбранной цели.

### Откуда берётся ReplayGain? Лучше подготовить файлы заранее?

Да. Для расчёта по целой записи удобно использовать [rsgain](https://github.com/complexlogic/rsgain)
или [loudgain](https://github.com/Moonbase59/loudgain) и записать ReplayGain-теги до копирования на
флешку. Это добавление метаданных, а не переписывание самого звука. Riff также читает поддерживаемые
данные iTunes/Apple Music Sound Check — `iTunNORM`.

Если пригодных данных нет, Riff попробует измерить громкость сам. Обычно это три фрагмента по 20
секунд — до минуты суммарно, а не полный трек. Если измерить эти фрагменты не удалось, для музыки
возможен полный анализ; для аудиокниг такого запасного прохода нет.

### Значит, F делает плеер аудиофильским?

Нет. В режимах I/F обработчик начинает с PCM16, даже если исходный файл хранит больше бит. Float32
на выходе не вернёт точность, которая уже потеряна на входе. Задача Riff — удобное прослушивание в
машине, не битовая идентичность исходнику.

Если нужен именно bit-perfect и отдельный USB-тракт, это другая задача. Например,
[Resonāda](https://gitlab.com/resonada/resonada/-/blob/main/README.md) заявляет такие возможности;
совместимость всё равно нужно проверять со своим устройством и выходом.

### Звука нет или он заикается. С чего начать?

С громкости и выбранного выхода магнитолы, доступа к файлу и подключения флешки. Сравни другой файл
и воспроизведение с внутренней памяти. Если подозрение на обработку, попробуй ReplayGain **N**.
Отметь, проблема везде или только в одном формате/Bluetooth. Полный сброс приложения оставь не
первым шагом.

## Данные, обновления и помощь

### Media folders и Save data on — зачем два выбора папок?

Первое — откуда читать музыку. Второе — где хранить данные самого Riff: настройки, индекс, анализ,
историю и позиции. Подтверждение **Save data on…** перемещает эти данные и может остановить
воспроизведение. Уже завершённое перемещение или изменение источников не отменяется поздним Cancel в
родительском экране.

### Что делать с Waiting for USB/SD storage…?

Подключить тот же накопитель, который выбран для данных Riff, и дождаться его готовности. Плеер не
переключается молча на пустую внутреннюю базу.

Если решил начать заново, **Forget and reset to Internal → Reset** создаст новое внутреннее
состояние без переноса прежних настроек, плейлистов и истории. Саму внешнюю флешку эта команда не
стирает. **Cancel** оставляет ожидание. Сломанный накопитель ожиданием не починить.

### Можно перенести плейлисты из другого плеера или восстановить диагностический экспорт?

Музыкальные папки — да, выбирай те же оригиналы. Поддерживаемого импорта чужих плейлистов,
рейтингов, истории и закладок пока нет. Диагностический экспорт нужен разбираться с проблемами, а не
восстанавливать всё обратно.

Внутренние снимки Riff на той же флешке тоже не спасут от потери самой флешки. Оригинальную
коллекцию стоит держать отдельно.

### Обновление сохранит данные?

В 1.1.0 используется новый формат состояния: настройки, история, реакции, плейлисты и закладки из
1.0.x не импортируются. Аудиофайлы не меняются; библиотека будет построена заново. Подписанный APK
использует тот же ключ. Перемещение текущих данных между Internal и SD через **Save data on…**
поддерживается отдельно. Очистка приложения не является первым шагом при любой неисправности.

### Alpha и сообщение о старой сборке — это срок действия?

Нет. Надпись показывает канал и дату выпуска. После трёх календарных месяцев Alpha, Beta, Debug и
Test напоминают о возрасте при новом запуске процесса. Нажал **OK** — продолжил пользоваться. Это не
подписка и не отключение музыки по таймеру. [Свежий статус и сборки — здесь](/Riff/LATEST/tldr).

### Нашёл ошибку или есть идея. Что прислать?

Версию/дату Riff, модель устройства и Android/прошивку. Ещё — шаги, после которых всё сломалось, что
ожидалось и что получилось. Очень помогает уточнение: только Bluetooth, только USB, только после
навигатора или выключения экрана?

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

Подробности устройства Riff — в [документации](/Riff/LATEST/requirements). Есть и
[английский FAQ](/Riff/LATEST/faq).

## Что изменилось в 1.1.0

### Что важно при переходе с 1.0.x?

Настройки, история, реакции, плейлисты и закладки из старой SQLite-базы не импортируются.
Потребуется настроить Riff заново; исходная музыка и книги не преобразуются и не удаляются. Перенос
текущих данных 1.1.0 между Internal и SD остаётся отдельной поддерживаемой операцией.

### Нужно ли ждать полного сканирования при каждом старте?

Целый совместимый каталог открывается после проверки целостности до нового сканирования. Player
использует готовые каталоги Albums, Artists и Genres и создаёт строки текущей страницы, а не полное
дерево объектов. Фоновая обработка новых файлов и AI может продолжаться отдельно. Первый запуск,
новый формат или недоступный накопитель — другие ситуации; очистка данных не ускоряет подготовку, а
начинает её заново.

### Почему файл с CUE теперь выглядит как папка?

Если пригодная структура прочитана, в Folders появляется виртуальная папка с готовым названием
альбома и его фрагментами. Play и Add используют фрагменты, без дополнительного Full file. Если один
файл входит в несколько объявленных альбомов, для каждого будет своя виртуальная папка. Обложка
по-прежнему берётся из исходного файла или его каталога по обычным правилам.

### Где должен лежать ui_config.json?

В `.riff` рядом с `riff_root_uuid` внутри уже выбранной медиапапки. Все обнаруженные файлы
объединяются при запуске; порядок не гарантируется, поэтому конфликтующих копий лучше не делать.
Неверный файл отклоняет весь внешний набор настроек, после чего используются значения APK. Приватная
папка приложения не читается. Горячей перезагрузки и редактора skin в Settings нет.

### FINAL — значит всё уже проверено на любой магнитоле?

Нет. 1.1.0 — релиз приложения, а модель AI остаётся beta. Проверки больших библиотек, физического
отключения питания и полноценных автомобильных хостов продолжаются.