# Riff: when something does not work

## Why are some files or albums missing?

Check the drive connection, permission for the actual folder and indexing progress first. Look in
**Folders**, and check Music/Books mode. An ordinary file without Album metadata may appear only in
Folders; supported CUE/chapter structures can supply an album identity. If it appears nowhere, check
readability and the actual format.

## Which formats work, and why does a file with a familiar extension fail?

The content matters more than the extension. Riff checks the real container and audio track against
available playback capabilities. Renaming something to .mp3 does not convert it. A small shareable
failing sample and its format help more than the filename alone.

## Why does playback stop with the screen off or in the background?

Closing the interface alone should not stop service playback. A vendor battery restriction,
audio-focus loss, Bluetooth Pause or an unplugged source can. Find the triggering event first; check
background restrictions if battery policy looks responsible. Include device, Android, edition and
reproduction steps when reporting it.

## Why are lock-screen or notification controls missing?

Android shows these from Riff's media session. Check the system notification/media-control settings
and whether playback is active. Vendor UI varies. Rebuilding your music library is not the answer to
a missing system button.

## Do Bluetooth and steering-wheel buttons work?

Standard Android media commands are the intended route. Some head units send wheel buttons only to
their own apps through a proprietary MCU path. Compare on-screen Play/Pause/Next with the external
commands and report the unit, firmware and connection. There is no universal MCU compatibility
promise.

## Does connecting Bluetooth or turning on the ignition start Riff?

Do not count on a universal trigger yet. The head unit may send Play itself; saved playback state is
a separate mechanism. Check what your actual unit does.

## Where do covers come from?

A suitable embedded cover comes first. Without it, fallback needs exactly one accessible, decodable
image next to the audio file. With several images, Riff does not guess between the front, back and
booklet. Otherwise you get default artwork. Automatic online downloads are not provided.

## Why are tags wrong or an album split?

Check Album, AlbumArtist, year and disc/track numbers. Folder relationships and CUE/TOC matter too;
matching Album text is not enough to merge unrelated editions. Without Title, a filename can become
the displayed name. Fix source tags externally and reindex. Riff does not guess an ambiguous broken
encoding into new text, and it does not rewrite your source tags.

## Why is a large collection still being prepared?

The first index, a changed format or new files can take time, especially on slow USB/SD. An intact
compatible catalog is reopened after integrity checks without waiting for a fresh scan. Album,
Artist and Genre rows use the ready catalog; the complete library is not rebuilt into a Player
object tree. Background discovery and analysis can still show progress after browsing is ready.

A track can play while optional AI/ReplayGain analysis is unfinished. Check source access and the
reported stage before resetting anything; a reset starts preparation again.

## What should I check when there is no sound or playback stutters?

Volume, selected output, file access and drive connection. Compare another file and internal
storage. If processing looks involved, try ReplayGain N. Note whether every file fails, just one
format, or only Bluetooth. Do not start by clearing all application data.

## How do I create audiobook bookmarks?

Start from a Book Title and use Bookmark. Playing the same file through Folders alone does not
enable it. Starting from an existing mark also lets you add marks. The minimum spacing defaults to
15 seconds on the complete book timeline, including chapter boundaries. The first bookmark saves the
dynamic Title queue. Opening the same Title reuses its saved queue and marks; removing the last mark
deletes that saved Book queue. Removing all queue members also removes its marks.
`player.bookmarkMinSpacingSeconds` in external `.riff/ui_config.json` can change it after restart.
The button is disabled inside that interval; equality is allowed. Missing durations or current
application-mode restrictions can also disable a new mark. Finishing a book does not delete your
manual marks.

## Are diagnostic exports or internal snapshots a backup?

Diagnostic exports help investigate problems; they are not a supported restore format. Snapshots on
the same drive cannot save you from losing the drive itself. Keep original audio independently.
There is no supported importer for another player's lists, ratings, history or marks, and
pre-release updates make no data-format compatibility promise.

## How should I report a problem or request a feature?

Give the edition/date, device and Android/firmware, then the steps, expected result and actual
result. Was it only Bluetooth, only USB, after a navigator prompt, or after the screen went off? A
screenshot, relevant diagnostics and a small shareable sample are useful. “Does not work” is harder
to act on. For a feature, describe the listening task it would solve. Leave out credentials and
unrelated personal data.

## Why does a CUE or chaptered file look like a folder?

When usable CUE/TOC structure has been read, Folders shows an album-named virtual folder containing
its fragments. Play and Add use those fragments; there is no extra Full file item to repeat the
whole container. A file belonging to several declared albums has a separate virtual folder for each.
Cover lookup still uses the underlying file and its containing directory.

## Where does ui_config.json go?

Put it in `.riff` beside `riff_root_uuid` in a media folder already admitted by Riff. All discovered
files participate in a deep merge at application startup. Their order is unspecified, so do not use
conflicting copies to choose a winner. Invalid input rejects the external overlay set and uses
packaged defaults. The private application directory is not a configuration source. There is no live
reload or Settings skin editor.