# On-device explanations, shown by Explain in a setting's context menu.
#
# One stanza per setting, keyed by its cfg name -- the name it has in a .cfg
# file and in settings-guide.md. Complete: every setting with a name on
# screen has one, and so does every MENUITEM_FUNCTION in the settings tree.
# Action rows are keyed differently -- see the "action: " note further down.
#
# A new setting needs a stanza adding here, and the build does not care: one
# without is not an error, it simply has no explanation to show. Run
# tools/check-settings-docs.sh from the repository root to find any that have
# been missed, here or in settings-guide.md.
#
# Write for someone who has just found the setting and does not know what it
# does. Say what it changes, and where it is useful or costly. Two or three
# sentences; the screen is 320 pixels wide. Lines within a paragraph are joined
# when read, so wrap freely -- but keep lines under 160 characters, which is
# where the reader truncates.
#
# Shipped to /.rockbox/docs/settings-help.txt by bundle-help.sh.

[bass cutoff]
The frequency Bass works below. A lower number lifts only the deepest notes; a
higher one reaches up into the lower mids and can muddy voices.

Only does anything while Bass is set above zero.

[treble cutoff]
The frequency Treble works above. Lower reaches down towards voices, higher
affects only the very top.

Only does anything while Treble is set away from zero.

[eq precut]
Attenuates everything before the equaliser runs, to leave room for bands you
have boosted.

Boosting a band without precut can push the signal past what the output can
represent, which clips and sounds harsh. If a preset sounds worse loud than
quiet, this is the first thing to try.

[antiskip]
How much audio is read ahead and held in memory before the disk is allowed to
stop.

Raise it if playback stutters when the player is jostled. The cost is battery:
a bigger buffer means longer reads, but fewer of them.

[bidir limit]
Text narrower than this share of the line bounces back and forth instead of
scrolling off one side and round again.

Bigger numbers mean more lines bounce. At 0 everything scrolls in one
direction.

[surround_fx1]
The upper frequency limit of the Haas effect.

The effect works by delaying part of the signal, which smears sound that has
sharp attacks. Keeping the band away from the top end leaves cymbals and
consonants alone.

[surround_fx2]
The lower frequency limit of the Haas effect.

Bass carries most of the energy and almost none of the directional information,
so leaving it out of the effect keeps the low end solid.

[compressor knee]
How abruptly compression starts once the signal passes the threshold.

Hard knee applies the full ratio the moment the threshold is crossed. Soft knee
eases it in over a few decibels, which is less audible on music.

[compressor makeup gain]
Compression makes loud parts quieter, so the whole track ends up quieter. This
puts the level back.

Auto works out how much was lost and adds it back, which is what you want
unless you are matching another device.

[dithering enabled]
Adds a very quiet noise when reducing bit depth, which trades a little hiss for
the absence of a particular kind of distortion on very quiet passages.

Inaudible on almost all material through headphones.

[disk spindown]
How long the drive sits idle before it is allowed to stop.

The single largest battery saving on a player with a spinning disk, and it does
nothing at all on one with an SSD fitted.

[battery capacity]
The capacity of the cell actually fitted, in mAh.

Only affects the runtime estimate, not charging. Worth correcting after a
battery replacement, since a new cell is often a different size from the
original.

[debug log battery]
Writes a line a minute to battery.csv in the .rockbox/logs folder: the battery
voltage and level, and how much of the minute was spent playing, boosted, with
the backlight or screen on, and with the disk running. For working out what a
fast drain was spent on.

The log waits until the disk is about to sleep, so it never spins the disk up
itself. It costs a little CPU every tick, and switches itself off after the
time set in Switch Off After.

[storage mode]
Tells power management what kind of drive is fitted, which decides whether it
is worth spinning down and how aggressively.

Auto detects it. Set it by hand only if a replacement drive is being detected
wrongly.

[glyphs]
How many characters of the font are kept in memory at once.

The default is plenty for European languages. Raise it if text in Chinese,
Japanese or Korean redraws slowly, since those need far more than 250
characters on screen over time.

[progress bar radius]
Corner rounding of the progress bar, in pixels. A theme-author setting: most
themes draw their own bar and ignore it.

[database art row height]
Row height in the database browser when album or artist art is shown beside
rows. A theme-author setting -- it has to match the artwork the theme draws.

[dircache]
Keeps the layout of the disk in memory so the file browser does not have to
read it each time.

Makes browsing much faster and costs a little memory. Takes effect when you
leave the setting.

[autoresume enable]
Remembers how far through each track you were, and returns there rather than
starting from the beginning.

Meant for audiobooks and long podcasts. Needs a working database.

[replaygain type]
Uses the loudness information many rippers write into files, so albums recorded
at different levels play at a similar volume.

Album gain keeps the balance between tracks on one record; track gain levels
everything, which suits shuffling.

[replaygain preamp]
A fixed adjustment applied on top of whatever Replaygain works out.

Useful if the whole library ends up quieter than you want once levelling is
applied.

[crossfade]
Overlaps the end of one track with the start of the next.

The setting chooses when it happens: only when a track ends on its own, only
when you skip, or always. Overlapping a deliberately gapless album is usually
not what you want.

[volume]
Output level, and the same value the volume buttons move. Shown in decibels
below maximum, so -25 dB is quieter than -10 dB.

[volume limit]
A ceiling the volume control cannot pass. Useful with sensitive earphones,
where the usable range is squeezed into the bottom of the scale.

[bass]
Lifts or cuts the low end. Bass Cutoff decides how far up it reaches.

[treble]
Lifts or cuts the high end. Treble Cutoff decides how far down it reaches.

[balance]
Shifts the output towards one ear. Meant for correcting a hearing difference or
a worn earphone, not for effect.

[channels]
What ends up in each ear: normal stereo, both channels mixed to mono, one
channel in both ears, the two swapped, or karaoke, which cancels whatever is
common to both and so removes most centred vocals.

Mono is the useful one if you often listen with a single earbud.

[stereo_width]
Widens or narrows the stereo image. Below 100% pulls it towards mono; above
pushes it apart, which can sound impressive briefly and tiring for long.

[volume fade]
Ramps the volume down and up on stop and pause instead of cutting, which avoids
the click a hard stop can produce.

[afr enabled]
Tames the harshness that makes long listening tiring, mostly in the upper mids.
Subtle by design; if you can hear it working it is set too high.

[crossfeed]
Bleeds a little of each channel into the other, with a delay, so headphones
sound less like two separate sources bolted to your head.

Most noticeable on older recordings mixed hard left and right.

[crossfeed direct gain]
The level of the sound that reaches the ear it was mixed for. Lowering it makes
the effect stronger by making the crossfed path relatively louder.

[crossfeed cross gain]
The level of the sound crossing to the other ear. The main strength control:
closer to the direct gain means a narrower, more speaker-like image.

[crossfeed hf attenuation]
How much the crossed-over sound is dulled. A real head blocks high frequencies
far more than low ones, so this is what makes the effect sound natural rather
than like an echo.

[crossfeed hf cutoff]
The frequency above which the crossfed signal -- the part bled into the
opposite ear -- starts being dulled. Lower values roll it off earlier and give
a warmer, more distant effect.

[eq enabled]
Master switch for the ten-band equaliser. Graphical EQ is usually an easier
starting point than setting the bands by hand.

[surround enabled]
Delay in milliseconds for the Haas effect, which widens the image by delaying
part of the signal rather than by changing its level. Zero is off.

[surround balance]
How the widened signal is weighted between left and right.

[surround mix]
How much of the effect is blended with the untouched signal. Lower values keep
the original intact and add a suggestion of width.

[side only]
Applies the effect only to the difference between the channels, leaving
anything mixed to the centre -- usually the voice -- untouched.

[pbe]
Adds harmonics above notes that are too low for small drivers to reproduce, so
the ear infers the bass that is not physically there. Strength is a percentage;
it distorts if pushed.

[pbe precut]
Attenuates the signal so the harmonics the effect adds do not push it into
clipping.

[compressor threshold]
The level above which compression starts, and the switch for the whole effect
-- at 0 dB nothing is compressed.

Compression narrows the gap between loud and quiet, which keeps quiet passages
audible on a noisy train at the cost of some dynamics.

[compressor ratio]
How hard the signal is held down once past the threshold. 2:1 is gentle, Limit
allows essentially nothing above it.

[compressor attack time]
How quickly compression clamps down after a loud passage begins. Short catches
transients and can dull drums; longer lets the initial hit through.

[compressor release time]
How quickly it lets go again. Too short pumps audibly on bass notes; too long
leaves quiet material compressed after the loud part has passed.

[replaygain noclip]
Backs the gain off when applying it would push the track into clipping, rather
than clipping it.

[volume adjustment mode]
Direct moves the volume in fixed decibel steps. Perceptual divides the range
into steps that sound evenly spaced, which suits the bottom of the scale where
a decibel is a large change.

[perceptual volume step count]
How many steps Perceptual mode divides the range into. More steps mean finer
control and more presses to cross the range.

Direct mode never reads it, which is why the row is listed only in Perceptual.

[shuffle]
Plays the current list in a random order. Changing it reshuffles what is
already playing rather than waiting for the next list.

[repeat]
What happens at the end of the list: stop, start again, repeat the one track,
reshuffle and go again, or loop between two marks you set.

[play selected]
Choosing a track starts from that track rather than from the top of the folder,
with the rest of the folder queued behind it.

[single mode]
Stops after the current track, album, artist, genre or playlist instead of
carrying on. Useful for falling asleep to one record.

[party mode]
Anything selected is added to the end of the queue instead of replacing it, so
a second person cannot wipe out what is already lined up.

[cuesheet support]
Reads .cue files, so an album ripped as one long file still shows track names
and can be skipped through.

[chapter marks]
Reads the chapter list an audiobook carries inside it, so one long file shows
its chapter names, skips between them and marks them on the progress bar. It
reads .m4b files and .mp3 files with chapter frames, and a book of more than 99
chapters lists the first 99 of them.

[folder navigation]
At the end of a folder, move on rather than stopping: to the next folder, or to
one picked at random. The In Start Directory choices never leave the folder set
with Start Directory in the file browser.

Random picks one level at a time: each artist folder has the same chance, then
each album in it, so an artist with one album comes up as often as one with
twenty.

[skip length]
Makes skip jump a fixed amount of time instead of a whole track. For long
podcasts and mixes, where a track is an hour.

[prevent track skip]
Disables skipping entirely. For handing the player to someone else, or a pocket
that presses buttons.

[rewind across tracks]
Rewinding past the start of a track continues into the previous one instead of
stopping at the beginning.

[resume rewind]
Backs up a few seconds when resuming, so you hear a little of what came before
rather than restarting mid-word.

[rewind duration on pause]
Backs up a few seconds every time you unpause, so you hear a little of what came
before rather than restarting mid-word.

[beep]
A short beep when skipping tracks, as feedback that the press registered.

[playback frequency]
The sample rate the output runs at. Auto follows the file and is right almost
always; forcing a rate resamples everything.

[spun artwork]
Whether the report's cards show album and artist sleeves. A card without one
draws a pattern instead, as part of the design rather than a stand-in.

Off also gives the pictures' memory to the statistics, so on a very large
library fewer rows are dropped. Changing it inside the report reads the log
again, the same pause a change of year costs.

[spun top count]
How many rows the Top Artists, Top Songs and Top Albums sections show. Ten is
enough to see a shape without walking a long way; five is a podium and
twenty-five is a survey.

[spun badge order]
How the Achievements section is arranged. As Listed keeps the order the
achievements were written in, which groups related ones together. Earned First
puts what you have won at the front, Newest First orders those by when, and
Closest First leads with whatever you are nearest to winning.

[spun rank by]
What the Top Artists, Top Songs and Top Albums sections are ordered on. Plays
counts how often you started something. Minutes counts how long you listened
to it.

The two disagree more than you would expect. Plays favours short tracks and a
song you keep restarting; minutes favours albums you sit through and anything
long. Skips and night plays are counted either way, because neither has a
listening time to rank by.

[spike caption]
Names the track under Spike's field, with the time remaining beside it. The
field rises to make room, so the game is a little smaller with this on. Off
gives the whole panel to the game.

[spike caption scroll]
Whether a track name too long for the space travels along or is simply cut
off. It steps a character at a time on the beat rather than gliding, which is
what keeps it readable on this screen. Off is the calmer choice while you are
playing, and shows as much of the name as fits. Off as well while Scrolling is
off.

[spike audio offset]
How far ahead of the sound the game judges a press. Raise it if your presses
feel late when they sounded on the beat, lower it if they feel early. It
corrects the delay below the player's own buffer -- headphones and the codec
-- so it is worth setting once and leaving.

[play log]
Records what was played and when. On feeds the listening statistics; the
Last.fm setting writes a scrobble log a computer can upload.

In Last.fm mode the Playback Report reads that log, so an uploader that empties
it after sending also restarts the Report's totals and streaks.

[scan min step]
How far the first press of fast forward or rewind moves. Smaller is better for
finding a moment in a song, larger for crossing a long file.

[seek acceleration]
How quickly held seeking speeds up. Faster crosses an hour-long file in a
moment but overshoots a three-minute song.

[pause on headphone unplug]
Pauses when whatever is playing is unplugged -- headphones, a USB DAC, a dock
or a car -- so the music does not carry on without you or out of the iPod's
socket. Pause and Resume carries on when the same one is plugged back in.

[disable autoresume if phones not present]
Stops the player resuming at power-on when nothing is plugged in, which
otherwise plays into a dock or an empty socket.

[album art]
Where cover art comes from: the thumbnail cache, files beside the music, or
tags embedded in the files. Prefer Cache is fastest.

[crossfade fade in delay]
How long to wait after the incoming track starts before its volume begins to
rise.

[crossfade fade in duration]
How long the incoming track takes to reach full volume.

[crossfade fade out delay]
How long the outgoing track holds its level before starting to fall.

[crossfade fade out duration]
How long the outgoing track takes to fall silent. Longer overlaps blur the join
more.

[crossfade fade out mode]
Crossfade dips both tracks through the join. Mix holds the total level roughly
constant, which sounds fuller but muddier where both tracks are busy.

[autocreate bookmarks]
Saves your position when you stop, so you can come back to it. Ask prompts each
time; the recent-only settings save without adding a bookmark file to the
folder.

[autoupdate bookmarks]
Overwrites the existing bookmark for a folder instead of adding another, so the
list stays one entry per book rather than one per session.

[autoload bookmarks]
Offers the saved position when you next open a folder that has one.

[use most-recent-bookmarks]
Keeps a list of the last places you stopped, reachable from the main menu, as
well as bookmarks stored beside the music.

[autoresume next track]
Whether an automatic position is also remembered when a track changes on its
own. Custom limits it to folders you nominate, which is how to keep it for
podcasts without applying it to albums.

[sort playlists]
The order saved playlists are listed in: by name, or by when they were made.

[recursive directory insert]
Adding a folder to a playlist also adds everything in its subfolders.

[warn when erasing dynamic playlist]
Asks before replacing a queue you have built up by hand, which is otherwise
easy to lose with one Select.

[keep current track when replacing playlist]
Leaves the playing track in place when a new selection replaces the queue, so
the music does not stop mid-song.

[show shuffled adding options]
Adds Shuffle into Queue and Shuffle onto End to the Add to Queue menu, for a
folder or playlist.

[show queue options]
Adds the Play Once entries to the Add to Queue menu, or with In Submenu gathers
them in a Play Once submenu. A play-once track leaves the queue after it has
played and is skipped when the queue repeats; the queue marks it with a +.

[max files in playlist]
The largest number of tracks a playlist may hold. Building very large lists is
slow on this hardware, which is why the limit is lower here than on a computer.

[playlist viewer icons]
Draws icons beside the entries in the playing queue.

[playlist viewer indices]
Numbers the entries in the playing queue.

[playlist viewer track display]
Whether the queue shows filenames or the artist and title from the tags.

[sort case]
Whether uppercase sorts separately from lowercase, so that "Zoo" can come
before "apple".

[sort dirs]
The order folders are listed in: by name, or by when they were last written.

[sort files]
The order files are listed in, including grouping by type.

[sort interpret number]
Whether "track2" comes before "track10" by reading the digits as a number, or
after it by comparing them one character at a time.

[show files]
Which files the browser shows: everything, only what can be opened, only music,
or only playlists. The quickest way to make a cluttered folder readable.

[show filename exts]
Whether names are shown with their extension. Hiding it is tidier; showing it
helps when several files share a name.

[follow playlist]
Opens the browser at the folder the playing track came from, rather than where
you last were.

[show path in browser]
Puts the current folder, or the whole path to it, in the title bar.

[hotkey tree]
What the hotkey button does in the file browser.

[max files in dir]
The largest number of entries loaded from one folder or one Music list. A
longer folder is cut short; a longer Music list is shown a page at a time in
the database's order, so The/A/An and numbers are not sorted. Takes effect
after a restart.

[tagcache_scan_on_startup]
Rescans the library at every boot. Mostly redundant if Scan on Eject is on,
since that is when the music can actually have changed, and it costs time at
every start.

[tagcache_scan_on_eject]
Rescans after a USB session, which is the moment new music normally arrives.

[playlist engine]
Measures how each track actually sounds -- its tempo, loudness, tonal balance
and key -- so a playlist can be built from a song rather than from its tags.
Switching this on starts the analysis, which asks before it begins.

The analysis needs the charger and takes hours on a full library. Switching it
off hides the feature and leaves what has been measured on disk, so switching
it back on costs nothing.

[analysis depth]
How much of each track the analysis listens to. Thorough takes forty seconds.
Quick stops once the tempo has settled, around eleven, about three and a half
times faster -- but loudness, tone and key are measured over that shorter
stretch too, so its matches are noticeably worse.

Use Quick only if a full analysis on the player is too long to sit through;
the desktop tool does a whole library thoroughly. Changing this re-measures
nothing: Rebuild Sound Analysis does.

[mix starts with selected]
Whether Play Similar and Wind Down play the track you chose them from first.
Off, it is left out, and the playlist starts with the nearest match to it.

[continue playing]
Keeps the music going when a playlist runs out, by adding more tracks that
sound like what has been playing and carrying on into them. Works for any
playlist -- an album, a saved one, a folder, or one the engine built.

A playlist the engine built is continued on its own terms: a mood keeps aiming
at that mood rather than drifting away from it one extension at a time.
Anything else is continued from the track that just finished.

Nothing already in the playlist is added again.

[generated playlist length]
The most tracks Play Similar, a mood or a journey puts in the playlist. Forty
is about an evening.

It is a limit rather than a target. Only tracks that really do sound like what
was asked for are used, so a mood your library holds little of gives a short
playlist rather than a long one filled out with whatever was nearest.

A journey spreads its change across whatever length is set, so a short one
moves between its two moods in fewer steps rather than covering less ground.

[mood playlist]
How much a mood or a journey varies between runs. Predictable gives the same
playlist every time, until the library changes. Weekly gives the same one all
week and a new one next week. Variable picks between the nearest few at each
step, so every run differs.

Moods and journeys are on the Playlists screen, above the saved playlists.

[track playlist]
How much Play Similar varies between runs. Predictable gives the same playlist
every time from the same song, until the library changes. Weekly gives the
same one all week and a new one next week. Variable picks between the nearest
few at each step, so every run differs.

None of them reach further out for the difference -- the playlist is drawn
from the same neighbourhood either way.

[action: Library Sound]
What the analysis found across the whole library: how much of it has been
measured, how many tracks each mood can draw on, how tempos and keys are
spread, and how loud each decade's music is.

Percentages are of the measured tracks. Hold Select on a section to explain
its rows.

[action: Overview]
How many tracks have been measured, how many could not be read, and how many
settled on a tempo or a key. Slow, Fast and Hypnotic use only tracks with a
tempo, so a low tempo count makes those playlists short.

Compared To says what a track's Sound screen measures it against: your own
library once enough of it is measured, built-in numbers until then.

[action: Moods]
How many tracks each mood playlist can choose from. A track can be in several
moods; In no mood counts those that no mood will ever offer.

A playlist can still be shorter than its count: it skips tracks under 90
seconds and spaces out each artist, so matches by fewer than four artists give
no more than three tracks.

[action: Pace]
How many tracks fall in each Pace band: Very slow is under 70 BPM, then Slow
to 90, Relaxed to 110, Moderate to 130, Brisk to 150, Fast to 170 and Very
fast above.

Unclear counts tracks whose beat wandered too much to trust. Slow, Fast and
Hypnotic leave those out.

[action: Keys]
The keys the analysis found, most common first. Unclear counts tracks that
settled on no key, which is normal for about two fifths of a library.

Dark and Melancholy favour minor keys, and Bright and Uplifting major ones, so
a library short of either makes those moods short.

[action: Loudness by Decade]
How loud each decade's music is on average, by each track's year, with the
number of tracks in brackets. Nearer zero is louder: music from the late
1990s on is often mastered several dB louder than older music.

A decade with only a few tracks says more about those tracks than about the
decade.

[database scan paths]
Restricts scanning to chosen folders, so spoken-word or sample libraries stay
out of the music database.

The next update removes the tracks that are now outside the chosen folders, or
inside a folder holding a database.ignore file.

[year from folder]
Takes the year from the track's folder when its name starts with one, as in
"1998 - Album", instead of from the tags; a disc folder such as CD1 takes it
from the folder above. For libraries where the tags hold each track's own
release date and the folder holds the album's.

It replaces the year in the Music lists, album sorting and the carousel; the
now playing screen still shows the tag. Takes effect at the next rebuild.

[database sort albums by]
The order for every album list that has no row of its own under Albums By:
by name, by release year with either end first, or by album artist and then
name or year.

The four rows above it override this for the lists they name, so this is what
the rest of the Music menu follows.

[database sort artists by]
The order of the artist lists in Music: by name, or most played first. Plays
are counted from the albums an artist heads, so an artist who only guests on
other albums sorts with the unplayed ones.

[sort ignoring articles]
Sorts artists and albums as if a leading "The", "A" or "An" were not there, so
The Beatles sits among the Bs. The names still show in full.

Applies to the Music lists and By First Letter. The carousel has its own.

[album show year]
Shows each album's release year in the Music lists, before or after its name,
so a discography reads in order at a glance. The carousel has its own setting.

[skip single item lists]
When a Music list would hold only one row, opens that row straight away: an
artist with one album goes straight to its tracks. Back skips over it too.

A list of tracks always shows, even with one track in it.

[debug log tagcache]
Writes database scan progress to tagcache.log in the .rockbox/logs folder. For
working out why a track is missing from the database.

Lines wait in memory until the disk is about to sleep, so a crash can lose the
last few. Switches itself off after the time set in Switch Off After.

[search max rows]
How many results a search keeps. More results take longer to scroll than to
find; another letter is usually quicker.

[search min letters]
How many letters must be typed before searching starts. Raise it if
one-letter searches return more than they are worth.

[search order]
Which of tracks, albums and artists is listed first in search results.

[quiz title]
Music Quiz rounds that play a clip and ask which track it is.

[quiz artist]
Music Quiz rounds that play a clip and ask who it is by. The wrong answers are
artists that sound alike, or share the genre and decade, as the game goes on.

[quiz album]
Music Quiz rounds that play a clip and ask which album it is from. In the later
rounds the wrong answers are the same artist's other albums.

[quiz year]
Music Quiz rounds that play a clip and ask what year it is from. Off by default:
the answers start five years apart and end one apart, and they are only as
right as the year tags.

[segregate audiobooks]
Keeps spoken word out of the music and gives it an Audiobooks row on the main
menu; albums, artists, the carousel and search then show music only. Only the
genre tag counts: one containing "audiobook", "audio book" or "spoken word",
or exactly "book", "podcast", "speech" and the like.

Books keep their place: open one again under Audiobooks and a Resume row heads
its chapters. An album with one music track on it stays with the music.

[trim titles]
Shortens the album and track names on the now playing screen by dropping a
trailing note about the pressing -- "(feat. Clairo)", "[Live]", "- 2021
Remaster". Useful where long names scroll or get cut off.

Files and the database are untouched, so browsing and search still see full
names. The notes are patterns in /.rockbox/trim.config, one per line, with *
matching anything. Add your own to /.rockbox/library/user/trim.txt, which an
install leaves alone; switch this off and on to re-read them.

[featured artists]
Reads guest credits -- the "feat. Somebody" in a title or artist -- and lets
you browse by them: Music gains a Featured Artists row, and an artist's album
list gains the records they only guest on. Needs the database loaded to RAM.

A name with a comma or ampersand, like Tyler, The Creator, reads as two people
unless an album is under it. List such names one per line in
/.rockbox/library/user/known_artists.txt, then reboot, or switch Featured
Artists off and on.

[art cache album source]
Where album covers come from: the image in the album's folder, the art embedded
in a track's tags, or both, the first named taking precedence. Artist pictures
only ever come from image files.

Changing it reads every album again, which takes a while on a large library.

[art cache fast build]
Decodes each image once for the largest thumbnail and derives the smaller sizes
from it, instead of decoding once per size.

Much faster, slightly softer. Applies only to thumbnails made from now on.

[debug log artcache]
Writes thumbnail generation to art.log in the .rockbox/logs folder, with a line
for each album or artist left without art and the reason. For working out why
a particular album has no art.

Switches itself off after the time set in Switch Off After.

[database album art]
Draws album thumbnails beside the rows in the database browser. Needs a theme
that supports artwork in lists, or the rows are tall and empty.

[database artist art]
Draws artist photographs beside the rows in the database browser. Needs a theme
that supports artwork in lists, or the rows are tall and empty.

[database audiobook art]
Draws cover art beside the rows in the Audiobooks browser. Needs a theme that
supports artwork in lists, or the rows are tall and empty.

[database author art]
Draws a photograph beside each author in the Audiobooks browser, from a
folder.jpg in the author's folder. Without one the row shows a placeholder.

[wps art source]
Which picture the now-playing screen shows. Auto uses the artist photograph if
you arrived through the artist menu, and the album cover otherwise.

[album covers filter 1]
First of three image adjustments applied to the covers in Cover Flow. The
browser's rows are treated by the theme instead, so this changes the carousel
and nothing else.

[album covers filter 2]
Second image adjustment in the chain, applied after the first.

[album covers filter 3]
Third and last image adjustment in the chain.

[album covers on select]
What Select does on a cover: open the album's track list, or start playing it.

[album covers show album name]
Whether the album name is drawn over the covers, and where.

[album covers show year]
Shows the release year in the caption, before or after the album's name.

[album covers background]
Which colour fills the screen behind the covers: one of the theme's, which
follows Dynamic Colours, or Custom, a colour of your own that stays put.

Choosing Custom opens a colour picker; Custom Colour below it changes the colour
later. The captions turn black or white to read on it.

[album covers statusbar]
Draws the status bar over the carousel. Off gives the covers the whole screen.

[album covers sort same as music]
Sorts the carousels the way the Music lists are sorted: albums as All Albums,
artists and The/A/An as their Music settings. The carousel's own sort settings
are hidden while it is on. Choosing an order inside the carousel turns it off.

[album covers sort albums by]
The order covers appear in: by album name, by release year with either end
first, or by album artist and then name or year.

[album covers sort artists by]
The order artist portraits appear in: by name, or most played first.

[album covers sort ignoring articles]
Sorts covers and portraits as if a leading "The", "A" or "An" were not there,
so The Beatles sits among the Bs. The names still show in full.

[album covers view mode]
3D angles the covers away on both sides. Flat lays them face-on and the same
size, in two piles either side of the current one.

[album covers scroll speed]
How far a flick of the wheel carries. Affects both view modes.

[album covers random spin]
How many covers go past when holding Play picks an album at random. Long makes
more of a show of it and takes a little longer to land.

[album covers transition speed]
How quickly the 3D view settles after scrolling. No effect in Flat, which times
itself off the wheel instead.

[album covers center margin]
The gap between the front cover and its neighbours in the 3D view.

[album covers slide tuck]
How far the side covers stack back behind the front one in the 3D view.

[album covers parallel slides]
Draws the side covers face-on rather than angled, which reads as a row of
covers rather than a tunnel.

[album covers pile fade]
How far the two piles in the Flat view are blended towards the background, so
the cover in the middle stands out. Zero leaves them solid.

[album covers pile offset]
How far below the middle cover the Flat view's piles sit. A cover eases down
onto its pile as it leaves and back up as it arrives.

[wps]
The skin drawn while music is playing. Part of a theme; loading a theme sets
it.

[sbs]
The base skin -- the frame drawn behind lists and menus. Part of a theme.

[font]
The typeface used throughout the interface. A larger font is easier to read and
fits fewer rows on screen.

[font bold]
An optional bold companion to the interface font, used where a screen wants
emphasis. Unset means the regular font is used for both.

[backdrop]
An image drawn behind everything. Loading a theme replaces it, and a theme that
names none clears it rather than keeping the last one.

[foreground color]
The colour of text and lines. Reset by loading a theme.

[background color]
The colour behind them. Reset by loading a theme.

[selector type]
How the highlighted row is marked: a pointer beside it, the row inverted, or a
bar behind it in a flat or graduated colour.

[line selector start color]
The colour at the top of the graduated selector bar.

[line selector end color]
The colour at the bottom of the graduated bar behind the highlighted row.
Setting it the same as the start colour gives a flat bar instead of a fade.

[line selector text color]
The colour of the text on the highlighted row, which has to read against the
bar rather than against the background.

[list separator height]
The thickness of the rule between rows, in pixels. Auto follows the font, and
off draws none.

[list separator color]
The colour of the rule drawn between rows in lists. Only visible where the
separator has a height to draw.

[statusbar]
Whether the clock and battery strip is drawn, and at which edge.

[scrollbar]
Whether a scroll bar is drawn beside lists, and on which side.

[scrollbar width]
How wide the scroll bar beside lists is, in pixels.

[volume display]
Whether the status bar shows the volume as a bar or as a number.

[battery display]
Whether the status bar shows the battery as an icon or as a percentage.

[show disk activity]
Lets the theme show an indicator while the disk is being read or written.
While music plays the disk is read often enough to keep it on, and every frame
it animates repaints the status bar, which slows the screen underneath.

[show background tasks]
Lets the theme show an indicator while the database, the artwork cache or the
document index is being built in the background.

[show working]
Lets the theme show an indicator while the screen is busy loading something
it was asked for.

[show icons]
Draws an icon beside each row in lists and menus. Turning them off gives the
text more room.

[iconset]
The image file the list icons are taken from. A theme-author setting.

[viewers iconset]
The icon set used for file types in the browser. A theme-author setting.

[filetype colours]
A file naming a colour per extension, so the browser can colour-code types. A
theme-author setting.

[ui viewport]
The rectangle a theme reserves for lists, so its own decoration is not drawn
over. A theme-author setting.

[dynamic colors]
Recolours the interface from the artwork of whatever is playing. A skin not
written for it will look wrong, since it cannot know what its colours will
become.

[dynamic colors background]
Which of the album's two colours becomes the background. Auto takes the one
the artwork has most of; Light and Dark always take the lighter or the darker.

Light keeps a light theme light whatever is playing; the text is then the
darker colour, which may be harder to read where a skin draws it over the art.

[dialog colours]
How the confirmation and message boxes are coloured.

Auto, the default, uses the theme's own two colours plus one accent on the
selected button -- and the accent follows the album while Dynamic Colors is
running. Off is the same two colours with no accent: the selected button is
simply drawn inverted, which is what Rockbox has always done. On ignores both
and uses the nine colours below, which appear only in that mode.

[dialog box foreground]
The text colour inside a dialog. Only used when Dialog Colour Mode is On.

[dialog box background]
The fill colour inside a dialog. Only used when Dialog Colour Mode is On.

[dialog box border colour]
The colour of a dialog's own border. Only used when Dialog Colour Mode is On.

[dialog box border width]
The thickness of that border, in pixels. Zero draws none.

[dialog box margin]
How far the dialog is inset from the edges of the screen.

[dialog box shadow]
A solid drop shadow offset down and to the right, which lifts the box off
whatever is behind it. Zero turns it off.

Applies whatever Dialog Colour Mode is set to, so a theme can style the shadow
without taking over all nine colours.

[dialog box shadow colour]
The colour of the drop shadow behind confirmation and message boxes. Black by
default rather than a theme colour, because its job is to contrast with the box
whatever the theme is doing.

[dialog button foreground]
The text colour of an unselected dialog button.

[dialog button background]
The fill colour of an unselected dialog button.

[dialog button border colour]
The border colour of an unselected dialog button.

[dialog button foreground selected]
The text colour of the selected dialog button.

[dialog button background selected]
The fill colour of the selected dialog button, which is what marks it as
chosen.

[dialog button border colour selected]
The border colour of the selected dialog button.

[dialog button border width]
The thickness of a dialog button's border, in pixels.

[dialog button border radius]
How rounded the corners of a dialog button are. Zero is square.

[peak meter release]
How quickly the level meter falls back after a peak. Slower is easier to read,
faster is more honest about the signal.

[peak meter hold]
How long the meter holds at a peak before starting to fall.

[peak meter clip hold]
How long a clipping indication stays on screen once triggered.

[peak meter dbfs]
Whether the meter's scale is in decibels, which matches how loudness is
perceived, or a straight percentage.

[peak meter min]
The quiet end of the meter's range.

[peak meter max]
The loud end of the meter's range.

[scrolling enabled]
Whether text too long for its line scrolls. Off, it is cut short with "..."
instead, in lists, menus, the theme's own scrolling lines and the carousel's
captions, and the other scroll settings then have nothing to move. Spike's
Scroll Now Playing does nothing while this is off.

[scroll speed]
How quickly text too long for its line moves.

[scroll delay]
How long text waits before it starts moving, so a row can be read before it
slides.

[scroll step]
How many pixels each step of scrolling text moves. One is smooth and costs more
work; larger steps are jerkier and cheaper.

[screen scroll step]
How many pixels each step moves when a whole screen slides, rather than when
text scrolls within one line. Smaller is smoother and costs more work.

[scroll paginated]
Lists move a screenful at a time instead of a row at a time.

[list wraparound]
Passing the last item returns to the first, rather than stopping.

[list order]
Whether lists are traversed from the top down or the bottom up.

[hold_lr_for_scroll_in_list]
Holding left or right scrolls a list rather than repeating whatever those
buttons do on the current screen.

[text viewer colour mode]
Whether the text viewer follows the theme, inverts it, or uses plain black on
white or white on black.

[text viewer margin]
Insets the text from the edges of the screen, which is easier to read at the
cost of a few characters per line.

[text viewer line spacing]
Extra pixels between lines. A little space makes a wall of text much easier to
follow.

[text viewer page number]
Shows a page counter at the foot.

[text viewer font]
A font used only by the text viewer, so reading can use a different typeface
from the menus. Unset uses the interface font.

[lyric colour mode]
Whether the lyrics screen follows the theme, inverts it, or uses plain black on
white or white on black.

[lyric align]
Whether lyric lines are aligned left, centred or right.

[lyric line spacing]
Extra pixels between lyric lines.

[lyric previous opacity]
How far lines that have already been sung fade back. Lower makes the current
line stand out more.

[lyric next opacity]
How far lines still to come fade back.

[lyric animation]
How the display moves from one line to the next: instantly, or scrolling at one
of three speeds.

[lyric highlight]
Highlights individual words as they are sung, where the file carries word
timings. Files with only line timings are unaffected.

[lyric backlight]
Holds the backlight on while lyrics are showing, since a screen that keeps
going dark defeats the point. A track without lyrics goes dark as usual.
Costs battery.

[lyric font]
A font used only by the lyrics screen. Unset uses the interface font.

[backlight timeout]
How long the backlight stays on after the last button press. The single biggest
lever on battery life.

[backlight timeout plugged]
How long the backlight stays on after the last button press while the player
is charging. Kept separate from the battery figure because there is less
reason to be frugal on the mains.

[backlight on button hold]
What the backlight does while the hold switch is on: behave normally, stay off,
or stay on.

[caption backlight]
Wakes the backlight briefly at each track change, so you can see what started
without touching anything. Costs battery on a long album.

[backlight fade in]
How long the backlight takes to come up rather than snapping on.

[backlight fade out]
How long it takes to go down. A slow fade is gentler in the dark.

[backlight filters first keypress]
Only Lights Screen: the press that wakes the screen does nothing else, so you
cannot change a setting you could not see. Costs one extra press each time.
Also Acts lets that press do its job as well. A remote's or dock's buttons
always act.

[No Backlight On Selected Actions]
Lets the presses chosen in Exemptions -- play, seek, skip or volume
on the Now Playing screen and main menu -- work without lighting the screen.
Saves battery when you control playback blind.

[lcd sleep after backlight off]
Powers the panel down entirely a while after the backlight goes out. Saves more
than the backlight alone, and costs a moment to wake.

[brightness]
Panel brightness. Second only to the backlight timeout as a drain on the
battery.

[idle poweroff]
How long the player sits idle, not playing, before switching itself off. Zero
never does.

[sleeptimer duration]
How long the sleep timer runs for, after which the player switches itself off.
Sets the length only; starting the timer is a separate entry on the same
screen.

[sleeptimer on startup]
Starts the sleep timer automatically at power-on, for a player used mostly to
fall asleep to.

[keypress restarts sleeptimer]
Any button press resets the countdown, so the timer only fires once you have
actually stopped touching it.

[usb charging]
Whether the player charges from a USB connection. Force charges even from a
port that does not advertise enough current, which not every port tolerates.
On an iPod Classic, Force also tops up a nearly full battery from a plain
charger, which it otherwise leaves alone.

[car adapter mode]
Pauses when external power is cut and resumes when it returns, so the player
follows the car's ignition.

[delay before resume]
How long to wait after power returns before resuming, so a stall or a restart
does not start the music.

[show shutdown message]
Shows a message while shutting down, rather than the screen simply going dark.

[start in screen]
Which screen opens at power-on.

[action: Shut Down]
Switches the player off now, as holding Play does. Refused while charging, on
a player that cannot switch off on the charger.

[action: Reboot]
Restarts the player now. Refused while charging, as Shut Down is.

[settings mode]
How much of the settings tree is shown. Standard hides the advanced rows;
Everything shows all of them.

[show debug menu]
Reveals the debug screens under System. They read hardware and internal state;
nothing there is needed in normal use.

[time format]
Whether times are shown on a 12- or 24-hour clock.

[lang]
The language of the interface. Loading one replaces the built-in English.

[default codepage]
The character set assumed for tags that do not say which they use. Wrong
guesses show accented characters as nonsense; Unicode is right for anything
tagged recently.

[default browser]
Which browser the root and the now-playing screen return to: the database or
the files.

[wps select action]
Where Select goes from the now-playing screen.

[shortcuts instead of quickscreen]
Whether a long press opens the quick screen or the shortcuts menu.

[keyclick]
A click through the headphones on each button press. Feedback in a pocket,
irritating on a quiet passage.

[hardware keyclick]
A click from the player own speaker on each button press, rather than through
the headphones. Audible without anything plugged in.

[keyclick repeats]
Whether auto-repeat -- a held button -- clicks each time or only once.

[accessory protocol]
Answers docks, car kits and remotes that speak Apple's accessory protocol, over
the dock connector or USB. Off, they get no reply: a dock charges but will not
play or take its remote. Changes to USB take effect at the next connection.

[iap2 accessories]
Answers cars and other accessories that expect an iPhone, over USB. Auto
knows a car by a request of Apple's that a car sends and a computer does
not, and waits a second before handing a computer the disk, so a car never
takes it. On answers any accessory that asks and never offers the disk: a
computer gets none, and may retry the connection for a moment first. Off
answers none, as an iPod does. Shown only while Accessory Protocol is on.
With USB Sound Card on, a car makes the player drop off USB for a moment and come back
without the sound card.

[identify as]
The model a car or dock is told the player is. Try another if an accessory
takes control but plays nothing: some judge what a player can do by its model.
Changes over USB take effect at the next connection. A computer with Apple's
drivers may not show the disk with iPhone 4. Shown only while Accessory
Protocol is on.

[accessory browsing]
Lets a receiver, car or dock browse artists, albums, genres, composers and
audiobooks, up to this many songs in a list; a dock or receiver can also play
Playlist Engine moods.

Its memory is taken when browsing starts, or with a car's first cover, briefly
rebuffering playback, and given back on unplugging. Needs the database in RAM.
Off offers only the Queue and saved playlists, and a car no library at all; a
car connected while it was Off sees one only once plugged in again.

[car artwork]
The cover a car shows with each track, sent over Apple's accessory protocol.
Prefer Cache sends the art cache's 300-pixel cover, which appears at once,
and the album's image while the cache has not reached it. The other choices
send the image itself: sharper on a large screen, but a large one takes
seconds to arrive; only a JPEG is sent as it is, and none over 512 KB. As Album
Art follows the Album Art setting. Off sends none,
and a car that looks covers up itself shows its own.

An older car or a dock gets the art cache's cover whichever is chosen, and none
with Off.

[serial bitrate]
The speed of the dock connector's serial line. Auto suits every accessory that
follows the standard.

[accessory power supply]
Powers the accessory pin on the dock connector. Needed by some adapters, and a
constant drain if nothing is attached.

[lineout]
Enables the dock's line output, which bypasses the volume control and feeds an
amplifier at a fixed level.

[tv out size]
How large the screen is on the TV. 1x shows it pixel for pixel, sharp but
small in the middle. 2x fills most of the TV; on an iPod Video it is slower to
follow the screen, and on an iPod Classic it is softer.

[tv standard]
The video standard the TV expects. Most TVs take either; use the one that
looks steadier. iPod Video only: an iPod Classic always sends NTSC.

[remote track skip]
Two clicks on the earphone remote's centre button skip to the next track, and
three go back to the previous one. The cost is that a single click waits about
a third of a second to see whether another is coming, so play/pause responds
that much later.

Off, every click is play/pause and acts at once.

[usb mode]
What a USB connection does: present the disk to the computer, or charge only.
Charge only suits a plug that would otherwise take the disk and interrupt
playback. Docks and cars that play from the player over USB still work.

Drive Only presents the disk and nothing else, for a car stereo that reads
iPods as USB drives but does not see this one. It overrides Accessory
Protocol, Support iPhone Accessories, Identify As, USB Sound Card, USB HID and
USB DAC Output without changing them, so cars and docks that play from the
player over USB do not work until it is switched back. Docks on the dock
connector still do.
A change takes effect at the next connection.

[usb hid]
Presents the player as a keyboard or remote control to the computer, so its
buttons can drive playback there. On an iPod Video in mass-storage mode, USB
Sound Card takes its place when both are on.

[usb keypad mode]
What the buttons send while acting as a USB device: media keys, a mouse, or
presentation controls.

[usb-dac]
Lets a computer play through the player: it shows up as a sound card, and what
the computer plays comes out of the headphone socket. The computer's volume
control sets the player's.

Takes effect at the next restart, and while on it keeps about 130K of memory
back from playback. On an iPod Video in mass-storage mode it takes USB HID's
place, as there is room for only one of the two beside the disk.

[usb dac output]
On, a USB DAC plugged into the dock connector takes over playback, and
unplugging it hands playback back to the headphone socket, paused as Pause on
Unplug says. It is looked for
only when no computer answers within two seconds, and not while a dock is
talking to the player.

The check needs a charger's power, such as a USB-C splitter with a charger in
it. A DAC on its own supply with nothing else on the cable goes unnoticed: use
Turn On beside this. Off leaves every cable to the computer and charging.

[debug log usb]
Writes every USB connection step to usb.log in the .rockbox/logs folder,
without the USB Log debug screen open, and every message a dock or car
exchanges, over USB or the dock connector's serial pins. For working out why a
computer, dock or car will not connect. It writes to the disk whenever the log grows, and
connection steps wait for the log to reach the disk, which can slow them. With
a car, it also records every five seconds how much audio the car took.

Switches itself off after the time set in Switch Off After.

[debug log playback]
Writes a line to playback_errors.log in the .rockbox/logs folder for every
track playback skips or cannot finish, saying why: the file would not open,
had no codec, or the codec failed. For working out why tracks skip.

Costs nothing until a track fails. Switches itself off after the time set in
Switch Off After.

[debug log theme]
Writes a line to theme.log in the .rockbox/logs folder for each skin file a
theme loads: whether it loaded and how much memory it took, and any font or
bitmap that would not load. For working out why a theme looks wrong or will
not load. A skin that does not parse is logged without its line; CheckWPS
gives that.

Each line reaches the disk at once, so a theme change is a little slower.
Switches itself off after the time set in Switch Off After.

[debug log tasks]
Writes a line to tasks.log in the .rockbox/logs folder whenever a background
task starts or finishes: database updates, album art and the documents and
images index, with what each pass came to. For working out why the Building
indicator will not go away, or why a pass keeps starting.

Switches itself off after the time set in Switch Off After.

[debug log expiry]
How long the debug logs stay on, counted by the clock from when a log was
switched on, whether the player is on or off. When the time is up every log
switches itself off, and a message says so. Switching a log on starts the count
again.

Never keeps them on until they are switched off by hand, for chasing a fault
that comes and goes.

[action: Turn All Off]
Switches every debug log off at once. The files stay in the .rockbox/logs
folder.

[talk menu]
Speaks menu entries aloud. Needs a voice file on the player.

[talk dir]
Whether folder names are spoken, and whether by number or spelled out.

[talk file]
Whether filenames are spoken, and how.

[talk dir clip]
Plays a recorded .talk clip for a folder where one exists, instead of speaking
the name.

[talk file clip]
Plays a recorded .talk clip for an individual file where one exists, instead of
speaking its name.

[talk filetype]
Speaks the file's type along with its name.

[Announce Battery Level]
Says the battery level aloud as it falls past 50, 30, 15 and 5 percent. Needs
a voice file on the player.

[talk mixer level]
How loud speech is relative to the music underneath it.

[Screen Scrolls Out Of View]
Lets a line of scrolling text carry on past the edge of its viewport instead of
stopping at it. Looks better on a theme whose list has room to spare, and clips
awkwardly on one that does not.

[Disable main menu scrolling]
Stops long entries scrolling on the main menu, leaving them truncated. The main
menu is glanced at rather than read, and text moving under the cursor there is
more distracting than helpful.

# Action rows. These have no cfg name, so they are keyed by their label under
# an "action: " namespace. Renaming a row orphans its stanza -- Explain then
# says there is nothing, which is the safe way to fail.

[action: Update Database]
Looks for music added or changed since the last scan and folds it into the
database. The fix for a new album not showing up in the Music browser.

Much quicker than a rebuild, because it only reads what it has to.

[action: Rebuild Database]
Throws the database away and reads every file on the player again. Play
counts, ratings and last-played times are saved first and put back afterwards.

Slow -- minutes on a full disk -- and rarely what you want: Update Database
finds new music on its own. Worth it only if the database looks wrong rather
than merely incomplete.

[action: Update Index]
Makes Album Covers lay out its covers afresh the next time it opens, for a
carousel that looks wrong after the library has changed.

[action: Listening Progress]
How much of the album or artist you are standing on has been heard, and which
of its tracks have not. An artist lists their albums with a figure each;
opening one of those shows the tracks still unplayed.

The figures are the database's own play counts.

[action: Update Art Cache]
Generates thumbnails for artwork that does not have one yet, and redoes any
whose image has been replaced or deleted since.

The cache stops once it has covered everything it knew about, so artwork added
to folders it has already been through -- artist photographs especially -- is
never picked up on its own. This is how you ask. It also reads each album's
tags again when Album Art Source includes embedded art.

[action: Update Sound Analysis]
Measures tracks the sound analysis has not covered yet, and retries any it
previously could not read. The fix for new music that Play Similar does not
offer.

Needs the charger, and holds the player while it runs. Only appears once
Playlist Engine is switched on.

[action: Rebuild Sound Analysis]
Throws the sound analysis away and measures every track again.

Hours on a full library, and rarely what you want -- Update Sound Analysis
covers new music on its own. Worth it only if the measurements themselves look
wrong.

[action: Rebuild Art Cache]
Deletes every thumbnail and generates them all again from the original images.

Slow. Use it after changing Fast Build, which only affects thumbnails made from
then on, or if the cached images themselves look wrong.

[action: Rescan Documents & Images]
Rebuilds the flat Documents and Images lists from a walk of the disk.

It reruns itself after a USB session, which is when files normally change, so
this is for when they changed some other way.

[action: Rebuild Playback Report]
Discards the figures the Playback Report saved, the track names it resolved and
the moved folders it matched, so the next time it opens it reads the log and the
database over again.

The report does this by itself whenever the database is updated, and follows a
folder you moved or renamed to where its files are now. So this is for names
that still look wrong after an update. Costs a few seconds on that next open and
nothing else -- the log is the record, and the figures come back the same.

[action: Load Theme]
Opens the list of installed themes. Choosing one applies the whole look at
once -- fonts, skins, colours, which bars are drawn.

Loading a theme also clears any appearance change you made by hand, so that a
theme cannot inherit stray settings from the one before it. Anything you change
afterwards is kept for that theme and reapplied the next time it is loaded.

[action: Font]
Picks a font file from /.rockbox/fonts.

Under Appearance this is the interface font, used everywhere the theme does not
say otherwise. Inside a viewer's own settings it is the font that viewer uses,
leaving the rest of the interface alone.

Bigger fonts fit fewer rows on screen and slow scrolling slightly.

[action: Use UI Font]
Drops this viewer's own font and goes back to the one the rest of the interface
uses.

[action: While Playing Screen]
Picks the layout drawn while music is playing.

The list is of .wps files in /.rockbox/wps. A theme sets this for you; change it
here to keep a theme but play from a different screen.

[action: Base Skin]
Picks the frame drawn around the menus and browsers -- the status bar area, any
backdrop, and where the list is allowed to sit.

The list is of .sbs files in /.rockbox/wps. Themes with art beside their rows
need their own base skin, so changing this to something else can leave the lists
looking plain.

[action: Clear Backdrop]
Removes the background image, leaving the background colour showing through.

The backdrop comes back the next time a theme is loaded.

[action: Custom Colour]
The colour behind the carousel's covers while Background is Custom. Dynamic
Colours leave it alone, and the captions turn black or white to read on it.

[action: Foreground Colour]
The default text colour for lists and menus.

A skin that sets its own colours overrides this for the parts it draws. If text
has become unreadable, this and Background Colour are the pair to fix.

[action: Background Colour]
The colour behind lists and menus.

Only visible where there is no backdrop image; Clear Backdrop makes it visible
everywhere.

[action: Primary Colour]
The colour of the bar drawn behind the selected row, or its top edge when the
selector is a gradient.

[action: Secondary Colour]
The bottom edge of the selection gradient. It fades from Primary to this.

Only used when Line Selector Type is set to gradient; the other selector styles
ignore it.

[action: Text Colour]
The colour of the text on the selected row, which would otherwise be the normal
foreground colour and can vanish against a strong selector.

[action: Line Separator Colour]
The colour of the hairline drawn between rows.

Only visible once Line Separator has been given a height above zero.

[action: Box Text]
The text colour inside a confirmation or message box.

One of the nine dialog colours, which are used only when Dialog Colour Mode is
set to use them rather than following the theme.

[action: Box Background]
The colour filling a confirmation or message box.

[action: Box Border]
The colour of the line around a dialog box.

Invisible unless Dialog Box Border has a width above zero.

[action: Box Shadow Colour]
The colour of the shadow cast by a dialog box.

Invisible unless Dialog Box Shadow is on. A colour close to the background gives
a soft edge; a darker one makes the box look further off the screen.

[action: Button Text]
The label colour on the buttons in a dialog when they are not selected.

[action: Button Background]
The fill colour of the buttons in a dialog when they are not selected.

[action: Button Border]
The outline colour of the buttons in a dialog.

Invisible unless Dialog Button Border has a width above zero.

[action: Selected Button Text]
The label colour on the dialog button that is currently chosen.

This and its background are what tell you which way a Yes/No question will go,
so keep them clearly different from the unselected pair.

[action: Selected Button Background]
The fill colour of the dialog button that is currently chosen.

[action: Selected Button Border]
The outline colour of the dialog button that is currently chosen.

[action: Reset Colours]
Puts the foreground, background, selector and separator colours back to the
built-in defaults -- white on black.

It does not touch the dialog colours, the backdrop or the skins.

[action: Forget My Changes]
Discards every appearance change you have made by hand and returns to what the
current theme says.

Those changes are kept in a file beside the theme, and this deletes it. It
reaches wider than the Appearance screen: the carousel geometry, the playlist
viewer chrome and the scrolling settings are all included.

[action: Edit Main Menu]
Chooses which rows appear on the main menu and what order they are in.

Views from the Music browser can be promoted here, so an album list can sit on
the first screen you see.

[action: Edit Music Menu]
Chooses which views appear inside Music and in what order.

Turning off the ones you never open makes the list shorter without losing the
database entries behind them.

[action: All Albums]
The order for the Albums list opened straight from the Music menu, which holds
every album on the player.

Default follows Other Lists, so this row only needs setting when you want this
one list to differ.

[action: Artist]
The order for the album list inside an artist.

Year here reads as a discography in release order, which is usually what an
artist's albums want. Every album in the list is by the one artist, so the
artist orders are not offered, and a Default that names one sorts by the rest.

[action: Album Artist]
The order for the album list inside an album artist. Genre, Year and the
Playback History artist lists group by album artist too, so they follow this
row as well.

The artist orders are not offered, as under Artist, and a Default that names
one sorts by the rest.

[action: Composer]
The order for the album list inside a composer.

[action: Scale]
Whether the peak meter is scaled by loudness or by raw sample value.

Logarithmic matches how the ear hears level and keeps the meter moving over most
of its width; linear leaves quiet music pinned to the left.

[action: Minimum of Range]
The level the peak meter treats as the bottom of its scale.

Raising it stops quiet passages sitting at the far left, at the cost of hiding
how quiet they really are.

[action: Maximum of Range]
The level the peak meter treats as full scale.

Lower it if the meter never reaches the right-hand end.

[action: Select Directories to Scan]
Chooses which folders the database reads when it scans.

Leaving out folders of podcasts or audiobooks keeps them out of the album and
artist lists while still letting you play them from Files. Changing this offers
a rebuild; the next update honours it too.

[action: Export Modifications]
Writes play counts, ratings and last-played times to
/.rockbox/database_changelog.txt, the file Rockbox's own Import Modifications
reads. A rebuild keeps them by itself; use this to keep a copy, for instance
before installing other firmware.

[action: Import Modifications]
Reads back /.rockbox/database_changelog.txt, written by Export Modifications
here or in Rockbox, and folds those play counts and ratings into the current
database.

[action: Missing Album Artwork]
Lists the albums that have no artwork, so you can see what is worth finding
covers for.

Reads what is already in the artwork cache, so run Update Art Cache first if you
have just added images.

[action: Missing Artist Portraits]
Lists the artists that have no photograph.

Artist images are looked for beside the music and in the artist art folder.

[action: Create Playlist]
Builds a playlist from the folder you are in, including everything below it, and
saves it in the playlist catalogue.

[action: View Queue]
Opens what is queued to play now, where tracks can be moved or removed.

[action: Save Queue as Playlist]
Writes what is playing now to a playlist file, so that it survives being
replaced by the next thing you play.

[action: Reset Playlist Catalogue Directory]
Puts the playlist catalogue back to /Playlists.

Only useful if you have pointed it somewhere else and want the default back.

[action: Start File Browser at /]
Clears the saved start directory, so that Files opens at the root of the disk
again.

[action: Language]
Picks a language file from /.rockbox/langs. It takes effect at once.

Only text the firmware supplies is translated -- track and folder names are
whatever the files say.

[action: Set Time/Date]
Sets the clock, which is what timestamps play counts and what the status bar
shows.

[action: Save .cfg File]
Writes every setting that differs from the defaults to a .cfg file, which can be
loaded again later or copied to another player.

Useful as a backup before trying something drastic.

[action: Save Theme Settings]
Writes only the appearance settings -- fonts, skins, colours, bars -- to a .cfg
file. This is how a theme of your own is made.

[action: Save Sound Settings]
Writes only the sound settings -- volume, tone, equaliser, crossfeed -- to a
.cfg file.

[action: Browse .cfg Files]
Opens the list of saved .cfg files. Choosing one applies the settings it
contains and leaves everything else alone.

[action: Reset Settings]
Puts every setting back to the built-in default and restarts.

Themes, music and playlists are untouched -- this is the settings only. Save a
.cfg file first if there is anything you want back afterwards.

[action: Reset Context Menu]
Clears the four while-playing context menu slots, so that the menu goes back to
its default contents.

[action: Settings]
Chooses which button actions are allowed to happen with the backlight off.

An action enabled here does its job without lighting the screen; one that is not
lights the screen instead, and needs a second press.

[action: Background Tasks]
Shows what the player is doing in the background -- scanning, indexing, building
thumbnails -- and how far along it is.

The place to look when the disk is busy and nothing on screen says why.

[action: About]
What this firmware is, what it is built on and who made it.

[action: System Info]
Shows the version, how much memory and disk is free, the battery reading, and
how long the player has been running.

Select a running time to reset it.

[action: Credits]
The people who wrote Rockbox.

[action: License]
The GNU General Public License, version 2, which this firmware is released
under.

[action: Debug]
Diagnostic screens for developers. Nothing in here is needed to use the player,
and some of it can lock it up.

[action: Changed Settings]
Lists every setting that differs from its default, with what it is now.

The quick answer to what did I change, and each row opens the setting itself.

[action: Search]
Finds a setting by name. Type part of what you are after and it lists the
matches with the menu each one lives in.

It searches the display name, the name a setting has in a .cfg file, and a few
words describing it -- so art, cover and album all reach the artwork settings.

[action: Simple EQ]
The three-band tone control: bass, treble, and the mid-band between them.

Enough for most adjustments. Advanced EQ reaches the same filters with full
control over frequency and width.

[action: Advanced EQ]
Sets each of the five bands by hand -- frequency, gain and Q.

Q is how wide the band is: low values shape a broad area, high values pick out a
narrow problem.

[action: Graphical EQ]
Shows the equaliser curve and lets you drag the bands on it.

Quicker than the numeric screens for judging the shape, less precise for setting
an exact value.

[action: Save EQ Preset]
Writes the current equaliser settings to a .cfg file in /.rockbox/eqs, so they
can be loaded again later. This is the only thing that puts anything in that
folder: no presets are shipped, so Load EQ has nothing to offer until you have
saved one.

[action: Load EQ]
Loads a preset saved by Save EQ Preset, replacing the current band settings.
Empty on a new install, since none are shipped.

[action: Reset EQ]
Returns every band to flat, leaving the equaliser on.

[action: Time & Date Settings]
Opens the clock: the time and date themselves, and how they are shown.

The clock is what timestamps play counts and what the status bar reads from.
