11.1Customising the User Interface

11.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 11.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, playlists, plugins, system_menu, shutdown,
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 10.4.7). It is not possible to change this setting via the settings
menu.

11.1.2Loading 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

11.2Configuring the Theme

11.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.

11.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 B; 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 char×11×1 (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.

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]”.

11.3Managing Rockbox Settings

11.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 11.3.2 below for an explanation of the format for configuration files.
See section 11.3.3 for an explanation of how to create, edit and load configuration
files.

11.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 C 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.

11.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 Stop 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.

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 C 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.

11.4Firmware Loading

When your player powers on, it loads the Archos firmware in ROM, which automatically
checks your player’s root directory for a file named archos.mod. Note that Archos firmware
can only read the first ten characters of each filename in this process, so do not rename your
old firmware files with names like archos.mod.old and so on, because it is possible that the
player will load a file other than the one you intended.

11.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 .mod. This can be used to test new firmware versions without
deleting your current version.

11.5Rockbox in Flash

11.5.1Introduction

When you bought your Studio/Player, it came with the Archos firmware in flash ROM. When
you power on your player, this Archos firmware starts, and then loads an updated firmware
from disk if present (archos.mod). An ordinary Rockbox installation only replaces the on-disk
firmware, leaving the flash ROM contents intact. That means the Archos firmware still
controls the boot process.

The main reason to change this is to improve the startup time of your player. The
Archos bootloader is rather slow. With Rockbox in flash, your player will boot much faster,
typically in three to five seconds. Furthermore you might prefer a clean Rockbox environment,
with as little remnants of the Archos software as possible. On your player it is also possible to
execute Rockbox directly from flash ROM, increasing the amount of free RAM for buffering
music. This is called Rombox.

Warning: Flashing your player is somewhat dangerous, like programming a mainboard
BIOS, CD/DVD drive firmware, mobile phone, etc. If the power fails, the chip breaks while
programming or most of all the programming software malfunctions, you’ll have a dead box.
We take no responsibility of any kind, you do that at your own risk. However, we tried as
carefully as possible to bulletproof this code. There are a lot of sanity checks. If any of them
fails, it will not program.

There’s an ultimate safety net to bring back boxes with even completely garbled flash content:
the UART boot mod, which in turn requires the serial mod. With that it’s possible to reflash
independently from the outside, even if the flash ROM is completely erased. This won’t work if
you have one of the rare “ROMless” boxes. These have no boot ROM and boot directly from
flash. If the first ≈2 KB of the flash ROM are flashed OK, Minimon can be used for the same
purpose.

11.5.2Terminology and Basic Operation

Firmware:

The flash ROM contents as a whole.

Image:

One operating software started from there.

The replacement firmware contains a bootloader and two images. The first image is the
permanent rescue software, to be used in case something is wrong with the second
(main) image. In current firmware files this first image contains Bootbox (see wiki for
details). The second image is what is booted by default. The current firmware files
contain a copy of Rockbox 3.2 in the main image. It can easily be updated/replaced
later.

The bootloader allows to select which image to run. Pressing Minus at boot selects the first
image. Play selects the second image, which will also be booted if you don’t press any button.
The button mapping is only there for completeness. Plus selects the built-in serial monitor
called Minimon. You should know this in case you invoke it by accident. Minimon won’t
display anything on the screen. To get out of it, perform a hardware shutdown of your
player.

11.5.3Initial Flashing Procedure

You only need to perform this procedure the first time you flash your Studio/Player. You may
also want to perform it in case the update procedure for the second image recommends it. In
the latter case do not perform the steps listed under “Preparation”.

Preparation

First, check whether your Studio/Player is flashable at all. Select System → Debug (Keep
Out!) → View HW Info. Cycle through the displayed values with Plus/ Minus until “Flash:”
is displayed. If it shows question marks, you’re out of luck, your player is not flashable
without modifying the hardware. You can stop here. Sorry.

If your player is flashable, you should perform a backup of the current flash ROM
contents, in case you want to restore it later. Select System → Debug (Keep Out!) →
Dump ROM contents. You’ll notice a few seconds of disk activity. When you connect
your player to the PC afterwards, you’ll find two files in the root of your player.
Copy the 256 KB-sized file named internal_rom_2000000-203FFFF.bin to a safe
place.

Flashing

Unzip the flash package to the root of your player. This will extract two files to
the root, firmware_<model>.bin and firmware_<model>_norom.bin. The flash
plugin will select the correct one for your player. Now safely disconnect USB.

3.

Make sure your batteries are in good shape and fully charged. Flashing doesn’t
need more power than normal operation, but you don’t want your player to run
out of power while flashing.

4.

Select Plugins → Applications, and run the firmware_flash plugin. It will tell
you about your flash and which file it is going to program. After pressing Menu it
will check the file. If the file is OK, pressing On will give you a big warning. If we
still didn’t manage to scare you off, you need to press Plus to actually program
and verify. The programming takes just a few seconds.

5.

In the unlikely event that the programming or verify steps should give you any
error, do not switch off the box! Otherwise you’ll have seen it working for the last
time. While Rockbox is still in RAM and operational, we could upgrade the plugin
via USB and try again. If you switch it off, it’s gone.

Note: After successful flashing you may delete the .bin files from the root of your
player.

Note: There are no separate flash packages for players modified to have 8 MB of RAM. You
need to use the corresponding package for non-modified Studio/Player. You should then install
a Rockbox image that makes use of all available RAM as described in the following
section.

11.5.4Updating the Rockbox Image in Flash

When Rockbox is booted from flash, it does not check for an updated firmware on disk. This is
one of the reasons why it boots faster than the Archos firmware. It means that whenever you
update Rockbox, you also need to update the image in the flash. This is a simple and safe
procedure:

1.

Download (or build) the Rockbox build you want to use, and unzip it to the root
of your player. Safely disconnect USB.

2.

ROLO into the new Rockbox version.

3.

Go to the file browser, and enter the .rockbox directory (you might need to set
the File View option to All.)

4.

Play the file rockbox.ucl, or preferably rombox.ucl, and follow the instructions.
The plugin handling this is rockbox_flash, a viewer plugin.

11.5.5Restoring the Original Flash ROM Contents

In case you ever want to restore the original flash contents, you will need the backup file. The
procedure is very similar to initial flashing, with the following differences:

1.

Check that you do not have any firmware_*.bin files in your player’s root.

2.

Select Plugins → Applications, and run the firmware_flash plugin. Write down
the filename it displays in the first screen, then exit the plugin.

3.

Connect USB, and copy the flash ROM backup file to the root of your player.
Only use the backup file from that very box, otherwise you’re asking for trouble!
Rename the file so that it matches the name requested by the firmware_flash
plugin. Safely disconnect USB.

Now follow the instructions given for initial flashing, starting with step 3.

11.6Optimising 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.

The following provides a short overview of the most relevant settings and rules of
thumb.

11.6.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).

11.6.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).

11.6.3Audio format and bitrate

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.