# Riff: why another player?

## What is Riff for?

Your own music and audiobooks on Android, mainly on aftermarket Android head units. Put your
collection on a drive, get in the car and listen. Phones and tablets work too if they run Android 12
or newer.

## Why another music player?

Poweramp, Musicolet and plenty of others already exist, and some are excellent. A head unit brings
its own annoyances: tiny buttons, strange display-density reports and power disappearing without a
polite shutdown. Riff grew out of wanting a player built around those conditions: large controls,
short routes through a collection, and books kept out of music shuffle.

The author's practical goal is music on roads where reception runs out first. Repeating one album
gets old, and making a fresh playlist for every drive is a chore. That is where offline analysis and
mood-based selection come in. The current application release is 1.1.0; the AI model remains public
beta.

## Will there be a macOS or iOS version?

Neither is planned. Android head units are the project’s reason for existing; a Mac player would
solve a different problem.

## Why does the interface look so utilitarian?

So you can hit the button on the first try. The author took inspiration from a milling-machine
control panel and a little from aircraft instruments. Seriously. Artwork is welcome, but clear
controls take priority over winning a skin contest.

## Do I need an account, subscription or internet connection?

No, not for listening. Bring your own files; analysis runs on the device without uploading the
music. Riff does not supply a catalog or download albums. Getting an APK or an update is separate.

## How do I start?

Install the signed APK from your distributor. If no media folders are selected, Riff opens the
folder picker. Choose **Add..**, pick a folder in Android's dialog, allow access, and confirm
**Media folders**. Give the library time to prepare, then browse and play.

Later, use **Settings → More… → Media folders…**. Android decides which directories and removable
drives appear in its picker. A disconnected drive cannot supply music just because permission was
previously granted.

## Does Riff move, delete or retag my audio?

Indexing reads the audio and keeps its own data separately. Display-text repair does not rewrite
source tags. Where writing is allowed, a small Riff identification folder may appear. Removing a
folder from the sources takes away access; it does not delete its music.

## How does A–Z search work?

Think of a letter filter for a long list. The author looked to car interfaces, including BMW and
Mercedes, for inspiration. Riff supports Cyrillic and Auto search: the keypad opens for long lists
and finishes when the results are short enough to choose comfortably.

Each step narrows names in the container you have open. It does not recursively search the entire
drive. **#** groups other characters rather than acting as a wildcard. Backspace undoes a step; the
A–Z control closes the keypad while keeping the filter.

## What does the AI do?

The APK contains a real offline model based on **EfficientAT**, with four tasks sharing one
backbone: Arousal, Valence, perceived speed (PTE), and genres. No internet connection is needed.

It is not a chat assistant or a perfect judge of taste. The model is beta quality. File analysis is
shared, while selection uses the active profile’s reactions, listening history and chosen
parameters. See the [current status](https://wiki.271.pics/Riff/LATEST/tldr) for edition-specific
validation.

## What do A, V and PTE mean?

Arousal is calm versus exciting: a quiet evening on the sofa versus wanting to jump around. Valence
is the positive versus gloomy tone. Together they describe emotion in the spirit of Russell's
two-axis model: high A/V is energetic and cheerful, low A/V calm and melancholic.

PTE is how fast the music feels. It is a separate estimate, not measured BPM. Fast is not always
exciting, and calm is not always slow. Values run from -1 to +1; you do not need to memorize the
numbers to choose music.

## Why is AI disabled or still analyzing?

It needs usable completed analysis. Playing successfully does not guarantee that analysis also
succeeded. AI is disabled in Books. If too few tracks qualify, a queue can be shorter than
requested; books and exclusions do not get waived to fill it. An automatically recognized book stays
out of AI even after you manually display it as Music.

## What do Like, Dislike and Ban mean?

The idea is simple: Like means “more often,” Dislike “less often,” and Ban “leave it out of AI
selection.” You can still play a banned file yourself. Changes are meant for later selections,
without rewriting the queue already playing.

Reactions are stored separately for each profile and used in later AI selections. The neural model
itself is shared: a Like changes selection preferences, rather than retraining a personal copy of
the network.

## Why ban a track instead of deleting it?

Holiday music may be welcome in winter and irritating on a summer road trip. Exclude it for a
season, then bring it back with the files intact. The author does not want a calendar-driven control
centre: head-unit clocks can be unreliable, and a simple player needs boundaries.

## How do I listen to audiobooks?

Switch **Books** on. Albums become **Titles**, and artists **Authors**. The mode is remembered for
each profile. A useful way to prepare files is adding a recognized **Audiobook** genre alongside the
literary genre, such as `Drama; Audiobook`, before copying them to the drive.

M4B filenames, supported media-kind tags and Android's actual **Audiobooks** folder provide other
automatic clues. If one representative member of a grouped album has an automatic book clue, the
whole album becomes a book. Matching Album text alone does not merge unrelated editions.

If detection gets it wrong, supported track, album/title and folder actions offer **Music** and
**Book** icon buttons. Tap either to select it, or tap the selected button again for **Auto**
(neither selected), which returns to inherited/detected classification. M4B/MP4 and supported MP3
chapters appear when present and valid; missing chapters are not invented.