13.1Customising the User Interface

13.1.1Customising The Main Menu

It is possible to customise the main menu, i.e. to reorder or to hide some of its items (only the
main menu can be customised, submenus can not). To accomplish this, load a .cfg file (as
described in section 13.3) containing the following line: root menu order:items, where
“items” is a comma separated list (no spaces around the commas!) of the following words:
bookmarks, files, database, wps, settings, recording, radio, playlists, plugins,
system_menu, shortcuts. Each of the words, if it occurs in the list, activates the appropriate
item in the main menu. The order of the items is given by the order of the words in the list.
The items whose words do not occur in the list will be hidden, with one exception: the menu
item Settings will be shown even if its word is not in the list (it is added as the last item
then).

The following configuration example will change the main menu so that it will contain only the
items for the file browser, for resuming the playback, and for changing the settings (the latter
will be added automatically).

root menu order:files,wps

To reset the menu items to the default, use root menu order:- (i.e. use a hyphen instead of
“items”).

This configuration entry can only be created and edited with a text editor or the Main Menu
Config Plugin (see section 12.4.12). It is not possible to change this setting via the settings
menu.

13.1.2Getting Extras

13.1.3Loading Fonts

Rockbox can load fonts dynamically. Simply copy the .fnt file to the player and “play” it in
the File Browser. If you want a font to be loaded automatically every time you start up, it
must be located in the /.rockbox/fonts directory and the filename must be at most 24
characters long. You can browse the fonts in /.rockbox/fonts under Settings → Theme
Settings → Font in the Main Menu.

Note: Advanced Users Only: Any BDF font should be usable with Rockbox. To convert from
.bdf to .fnt, use the convbdf tool. This tool can be found in the tools directory of the
Rockbox source code. See CreateFonts#ConvBdf for more details. Or just run convbdf
without any parameters to see the possible options.

13.1.4Loading Languages

Rockbox can load language files at runtime. Simply copy the .lng file (do not use the .langfile) to the player and “play” it in the Rockbox directory browser or select Settings → General
Settings → Language from the Main Menu.

Note: If you want a language to be loaded automatically every time you start up, it must be
located in the /.rockbox/langs directory and the filename must be a maximum of 24
characters long.

If your language is not yet supported and you want to write your own language file find the
instructions on the Rockbox website: LangFiles

13.1.5Changing Filetype Colours

Rockbox has the capability to modify the File Browser to show files of different types in
different colours, depending on the file extension.

Set-up

There are two steps to changing the filetype colours – creating a file with the extension
.colours and then activating it using a config file. The .colours files must be stored in the
/.rockbox/themes/ directory. The .colours file is just a text file, and can be edited with
your text editor of choice.

Creating the .colours file

The .colours file consists of the file extension (or folder) followed by a colon
and then the colour desired as an RGB value in hexadecimal, as in the following
example:

All file extensions that are not either specifically listed in the .colours files or are
not in the list above will be set to the colour given by ???. Extensions that are in
the above list but not in the .colours file will be set to the foreground colour as
normal.

Activating

To activate the filetype colours, the .colours file needs to be invoked from a .cfg
configuration file. The easiest way to do this is to create a new text file containing the
following single line:

filetype colours: /.rockbox/themes/filename.colours

where filename is replaced by the filename you used when creating the .colours file. Save this
file as e.g. colours.cfg in the /.rockbox/themes directory and then activate the
config file from the menu as normal (Settings→ Theme Settings→ Browse Theme
Files).

Editing

The built-in Text Editor (see section 12.4.24) automatically understands the .colours file
format, but an external text editor can also be used. To edit the .colours file using Rockbox,
“play” it in the File Browser. The file will open in the Text Editor. Upon selecting a line, the
following choices will appear:

ExtensionColour

If Extension is selected, the virtual keyboard (see section 4.1.3) appears, allowing the file
extension to be modified. If Colour is selected, the colour selector screen appears.
Choose the desired colour, then save the .colours file using the standard Text Editor
controls.

13.1.6Loading Backdrops

Rockbox supports showing an image as a backdrop in the File Browser and the menus. The
backdrop image must be a .bmp file of the exact same dimensions as the display in your player
(128×128×16 with the last number giving the colour depth in bits). To use an image as a
backdrop browse to it in the File Browser and open the Context Menu (see section 4.1.2) on it
and select the option Set As Backdrop. If you want rockbox to remember your backdrop the
next time you start your player the backdrop must be placed in the /.rockbox/backdrops
directory.

13.1.7UI Viewport

By default, the UI is drawn on the whole screen. This can be changed so that the UI is
confined to a specific area of the screen, by use of a UI viewport. This is done by adding the
following line to the .cfg file for a theme:

ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]

Only the first two parameters have to be specified, the others can be omitted using ‘−’ as
a placeholder. The syntax is very similar to WPS viewports (see section 13.2.2).
Briefly:

‘fgcolour’ and ‘bgcolour’ are 6-digit RGB888 colours, e.g. FF00FF.

‘font’ is a number: 0 is the built-in system font, 1 is the user-selected font.

ui viewport: 15,20,100,150,-,-,-

This displays the menu starting at 15px from the left of the screen and 20px from the top of
the screen. It is 100px wide and 150px high. The font and the foreground/background colours
are defined in the theme .cfg file or in the Theme Settings menu.

13.2Configuring the Theme

13.2.1Themeing – General Info

There are various different aspects of the Rockbox interface that can be themed – the WPS or
While Playing Screen, the FMS or FM Screen (if the player has a tuner), and the SBS or
Base Skin. The WPS is the name used to describe the information displayed on the
player’s screen whilst an audio track is being played, the FMS is the screen shown
while listening to the radio, and the SBS lets you specify a base skin that is shown
in the menus and browsers, as well as the WPS and FMS. The SBS also allows
you to control certain aspects of the appearance of the menus/browsers. There are
a number of themes included in Rockbox, and you can load one of these at any
time by selecting it in Settings → Theme Settings → Browse Theme Files. It is also
possible to set individual items of a theme from within the Settings → Theme Settings
menu.

13.2.2Themes – Create Your Own

The theme files are simple text files, and can be created (or edited) in your favourite text
editor. To make sure non-English characters display correctly in your theme you
must save the theme files with UTF-8 character encoding. This can be done in most
editors, for example Notepad in Windows 2000 or XP (but not in 9x/ME) can do
this.

Files Locations:

Each different “themeable” aspect requires its own file – WPS files
have the extension .wps, FM screen files have the extension .fms, and SBS files
have the extension .sbs. The main theme file has the extension .cfg. All files
should have the same name.

The theme .cfg file should be placed in the /.rockbox/themes directory, while the
.wps, .fms and .sbs files should be placed in the /.rockbox/wps directory. Any
images used by the theme should be placed in a subdirectory of /.rockbox/wps
with the same name as the theme, e.g. if the theme files are named mytheme.wps,mytheme.sbs etc., then the images should be placed in /.rockbox/wps/mytheme.

All full list of the available tags are given in appendix section D; some of the more powerful
concepts in theme design are discussed below.

All characters not preceded by % are displayed as typed.

Lines beginning with # are comments and will be ignored.

Note: Keep in mind that your player’s resolution is 128×128×16 (with the last number giving
the colour depth in bits) when designing your own WPS, or if you use a WPS designed for
another target.

Viewports

By default, a viewport filling the whole screen contains all the elements defined in each
theme file. The elements in this viewport are displayed with the same background/
foreground colours and the text is rendered in the same font as in the main menu. To change
this behaviour a custom viewport can be defined. A viewport is a rectangular window
on the screen with its own foreground/background colours. This window also has
variable dimensions. To define a viewport a line starting %V(… has to be present in
the theme file. The full syntax will be explained later in this section. All elements
placed before the line defining a viewport are displayed in the default viewport.
Elements defined after a viewport declaration are drawn within that viewport. Loading
images (see Appendix section D.21) should be done within the default viewport. A
viewport ends either with the end of the file, or with the next viewport declaration line.
Viewports sharing the same coordinates and dimensions cannot be displayed at the
same time. Viewports cannot be layered transparently over one another. Subsequent
viewports will be drawn over any other viewports already drawn onto that area of the
screen.

%Vg defines a gradient fill that can then be used with the %Vs tag. ‘start’ and
‘end’ set the initial and final colours, and the optional ‘text’ sets the text colour.
Colours are 6-digit RGB888, e.g. FF00FF.

‘font’ is a number: 0 is the built-in system font, 1 is the current menu font, and
2-9 are additional skin loaded fonts (see section 13.2.4).

Only the coordinates have to be specified. Leaving the other definitions blank will
set them to their default values.

Note: The correct number of commas with hyphens in blank fields are still needed.

%V(12,20,-,-,1) %Vf(000000) %Vb(FFFFFF) %Vg(FFC0CB, FF0000, FFFF00) %sThis viewport is displayed permanently. It starts 12px from the left and %s20px from the top of the screen, and fills the rest of the screen from %sthat point. The lines will scroll if this text does not fit in the viewport. %sThe user font is used, and the foreground and background are set to black %sand white respectively. The line gradient is set to pink to red with yellow %text.

Viewport definition

Default value

width/height

remaining part of screen

font

user defined

foreground/background
colours

defined by theme

Viewport Line Text Styles

Tag

Description

%Vs(mode[,param])

Set the viewport text style to ‘mode’ from this point forward

Mode can be the following:

Mode

Description

clear

Restore the default style

invert

Draw lines inverted

color

Draw the text coloured by the value given in ‘param’. Functionally
equivalent to using the %Vf() tag

gradient

Draw the next ‘param’ lines using a gradient as defined by %Vg.
By default the gradient is drawn over 1 line. %Vs(gradient,2) will
use 2 lines to fully change from the start colour to the end colour

Conditional Viewports

Any viewport can be displayed either permanently or conditionally. Defining a viewport as
%V(… will display it permanently.

%Vl(’identifier’,…) This tag preloads a viewport for later display. ‘identifier’
is a single lowercase letter (a-z) and the ‘…’ parameters use the same logic as the
%V tag explained above.

%Vd(’identifier’) Display the ‘identifier’ viewport.

Viewports can share identifiers so that you can display multiple viewports with one %Vd
line.

This example checks for album art. Album art will be displayed in viewport ‘a’,
if it is found. Otherwise a red flashing warning will be displayed in viewport ‘b’.

Note: The tag to display conditional viewports must come before the tag to preload the
viewport in the .wps file.

13.2.3Info Viewport (SBS only)

As mentioned above, it is possible to set a UI viewport via the theme .cfg file. It is also
possible to set the UI viewport through the SBS file, and to conditionally select different UI
viewports.

%Vi(’label’,…) This viewport is used as Custom UI Viewport in the case that
the theme doesn’t have a ui viewport set in the theme .cfg file. Having this is
strongly recommended since it makes you able to use the SBS with other themes.
If label is set this viewport can be selectivly used as the Info Viewport using the
%VI tag. The ‘…’ parameters use the same logic as the %V tag explained above.

%VI(’label’) Set the Info Viewport to use the viewport called label, as declared
with the previous tag.

13.2.4Additional Fonts

Additional fonts can be loaded within each screen file to be used in that screen. In this way
not only can you have different fonts between e.g. the menu and the WPS, but you can use
multiple fonts in each of the individual screens.

%Fl(’id’,filename,glyphs)

‘id’ is the number you want to use in viewport declarations, 0 and 1 are reserved
and so can’t be used.

‘filename’ is the font filename to load. Fonts should be stored in /.rockbox/fonts/

‘glyphs’ is an optional specification of how many unique glyphs to store in memory.
Default is from the system setting Glyphs To Load.

An example would be: %Fl(2,12-Nimbus.fnt,100)

Conditional Tags

If/else:

Syntax: %?xx<true|false>

If the tag specified by “xx” has a value, the text between the “<” and the “|” is
displayed (the true part), else the text between the “|” and the “>” is displayed
(the false part). The else part is optional, so the “|” does not have to be specified
if no else part is desired. The conditionals nest, so the text in the if and else part
can contain all % commands, including conditionals.

Enumerations:

Syntax: %?xx<alt1|alt2|alt3|…|else>

For tags with multiple values, like Play status, the conditional can hold a list
of alternatives, one for each value the tag can have. Example enumeration:

%?mp<Stop|Play|Pause|Ffwd|Rew>

The last else part is optional, and will be displayed if the tag has no value. The WPS
parser will always display the last part if the tag has no value, or if the list of
alternatives is too short.

Next Song Info

You can display information about the next song – the song that is about to play after the one
currently playing (unless you change the plan).

If you use the upper-case versions of the three tags: F, I and D, they will instead refer to the
next song instead of the current one. Example: %Ig is the genre name used in the next song
and %Ff is the mp3 frequency.

Note: The next song information will not be available at all times, but will most likely be
available at the end of a song. We suggest you use the conditional display tag a lot when
displaying information about the next song!

Alternating Sublines

It is possible to group items on each line into 2 or more groups or “sublines”. Each subline will
be displayed in succession on the line for a specified time, alternating continuously through
each defined subline.

Items on a line are broken into sublines with the semicolon ‘;’ character. The display time for
each subline defaults to 2 seconds unless modified by using the ‘%t’ tag to specify an
alternate time (in seconds and optional tenths of a second) for the subline to be
displayed.

Subline related special characters and tags:

;

Split items on a line into separate sublines

%t

Set the subline display time. The ‘%t’ is followed by either integer seconds (%t5), or
seconds and tenths of a second within () e.g. (%t(3.5)).

Each alternating subline can still be optionally scrolled while it is being displayed, and
scrollable formats can be displayed on the same line with non-scrollable formats (such as track
elapsed time) as long as they are separated into different sublines. Example subline definition:

Four images at the same x and y position are preloaded in the example. Which image to
display is determined by the %mm tag (the repeat mode).

Example File

%s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]> %pb%pc/%pt

That is, “tracknum – title [artist, album]”, where most fields are only displayed if available.
Could also be rendered as “filename” or “tracknum – title [artist]”.

13.3Managing Rockbox Settings

13.3.1Introduction to .cfg Files

Rockbox allows users to store and load multiple settings through the use of configuration files.
A configuration file is simply a text file with the extension .cfg.

A configuration file may reside anywhere on the disk. Multiple configuration files are
permitted. So, for example, you could have a car.cfg file for the settings that you use while
playing your jukebox in your car, and a headphones.cfg file to store the settings that you use
while listening to your player through headphones.

See section 13.3.2 below for an explanation of the format for configuration files.
See section 13.3.3 for an explanation of how to create, edit and load configuration
files.

13.3.2Specifications for .cfg Files

The Rockbox configuration file is a plain text file, so once you use the Save .cfg file option to
create the file, you can edit the file on your computer using any text editor program. See
Appendix section E for available settings. Configuration files use the following formatting
rules:

1.

Each setting must be on a separate line.

2.

Each line has the format “setting: value”.

3.

Values must be within the ranges specified in this manual for each setting.

4.

Lines starting with # are ignored. This lets you write comments into your
configuration files.

Note: As you can see from the example, configuration files do not need to contain all of the
Rockbox options. You can create configuration files that change only certain settings. So, for
example, suppose you typically use the player at one volume in the car, and another when
using headphones. Further, suppose you like to use an inverse LCD when you are in the
car, and a regular LCD setting when you are using headphones. You could create
configuration files that control only the volume and LCD settings. Create a few
different files with different settings, give each file a different name (such as car.cfg,
headphones.cfg, etc.), and you can then use the Browse .cfg files option to quickly change
settings.

A special case configuration file can be used to force a particular setting or settings every time
Rockbox starts up (e.g. to set the volume to a safe level). Format a new configuration file as
above with the required setting(s) and save it into the /.rockbox directory with the filename
fixed.cfg.

13.3.3The Manage Settings menu

The Manage Settings menu can be found in the Main Menu. The Manage Settings menu
allows you to save and load .cfg files.

Browse .cfg Files

Opens the File Browser in the /.rockbox directory and displays all
.cfg (configuration) files. Selecting a .cfg file will cause Rockbox to load the
settings contained in that file. Pressing Cancel will exit back to the Manage
Settings menu. See the Write .cfg files option on the Manage Settings menu for
details of how to save and edit a configuration file.

Reset Settings

This wipes the saved settings in the player and resets all settings to
their default values.

Note: You can also reset all settings to their default values by turning off the
player, and turning it back on with the Hold button on.

Save .cfg File

This option writes a .cfg file to your player’s disk. The configuration
file has the .cfg extension and is used to store all of the user settings that are
described throughout this manual.

Hint: Use the Save .cfg File feature (Main Menu → Manage Settings) to save the
current settings, then use a text editor to customize the settings file. See Appendix
section E for the full reference of available options.

Save Sound Settings

This option writes a .cfg file to your player’s disk. The
configuration file has the .cfg extension and is used to store all of the sound related
settings.

Save Theme Settings

This option writes a .cfg file to your player’s disk. The
configuration file has the .cfg extension and is used to store all of the theme
related settings.

13.4Firmware Loading

13.4.1Using ROLO (Rockbox Loader)

Rockbox is able to load and start another firmware file without rebooting. You just “play” a
file with the extension .mi4. This can be used to test new firmware versions without
deleting your current version.

13.5Optimising battery runtime

Rockbox offers a lot of settings that have high impact on the battery runtime of your player.
The largest power savings can be achieved through disabling unneeded hardware components
– for some of those there are settings available.

Another area of savings is avoiding or reducing CPU boosting through disabling
computing intense features (e.g. sound processing) or using effective audio codecs.
The following provides a short overview of the most relevant settings and rules of
thumb.

13.5.1Display backlight

The active backlight consumes a lot of power. Therefore choose a setting that disables the
backlight after timeout (for setting Backlight see section 8.4). Avoid having the backlight
enabled all the time (Activating selectivebacklight section 8.4 can further reduce power
consumption).

13.5.2Anti-Skip Buffer

Having a large anti-skip buffer tends to use more power, and may reduce your battery life. It is
recommended to always use the lowest possible setting that allows correct and continuous
playback (see section 7.5).

13.5.3Replaygain

Replaygain is a post processing that equalises the playback volume of audio files to the same
perceived loudness. This post processing applies a factor to each single PCM sample and is
therefore consuming additional CPU time. If you want to achieve some (minor) savings in
runtime, switch this feature off (see section 7.9).

13.5.4Peak Meter

The peak meter is a feature of the While Playing Screen and will be updated with a high
framerate. Depending on your player this might result in a high CPU load. To save battery
runtime you should switch this feature off (see section 4.3.2).

13.5.5Audio format and bitrate

In general the fastest decoding audio format will be the best in terms of battery runtime on
your player. An overview of different codec’s performance on different players can be found at
CodecPerformanceComparison.

Your target uses a hard disk which consumes a large amount of power while spinning – up to
several hundred mA. The less often the hard disk needs to spin up for buffering and the
shorter the buffering duration is, the lower is the power consumption. Therefore the bitrate of
the audio files does have an impact on the battery runtime as well. Lower bitrate audio files
will result in longer battery runtime.

Please do not re-encode any existing audio files from one lossy format to another based upon
the above mentioned. This will reduce the audio quality. If you have the choice, select the best
suiting codec when encoding the original source material.

13.5.6Sound settings

In general all kinds of sound processing will need more CPU time and therefore consume more
power. The less sound processing you use, the better it is for the battery runtime (for options
see section 6).