Description / General Info
WPS and SBS
Base Skin on/off
Current Id3 Tags
Upcoming Id3 Tags
Current File Tags
Upcoming File Tags
Playback Mode Tag
Repeat Mode Tag
Hold Switch Tags
Power Related Information
Drive Actvity Tag
Runtime Database and Replay Gain
Real Time Clock
LCD Screen Sizes and BMP Compatibility
Basic Image Tags
Recording Screen Tokens
The rockbox interface can be modified to your liking using a custom theme, wps, and base skin. The theme, saved as a .cfg file, defines the font, icons, basic colors, and links the wps and base skin together. The wps, saved as a .wps, is displayed during audio playback, and presents predominantly audio related information. The base skin, saved as a .sbs, skins the menu and file browser, and is capable of presenting various information.
This guide is based on the "CustomWPS" guide. Another, less-featured but much simpler guide is found here, "SimpleGuideToWPSMaking".
The .cfg, .wps, and .sbs files can all be written in a simple text program such as notepad, gedit, pspad, etc. To create the files simply save them with the appropriate extension, e.g. a new theme could be saved as "newtheme.cfg". The other files, .wps and .sbs, are saved the same way. To ensure that non-english characters are saved, use UTF-8 encoding when you save.
While files can be placed anywhere on your device's drive, the ".rockbox" folder contains folders which make file organization easy and efficent. Theme files (.cfg), are placed in the /.rockbox/themes folder. The wps and base skin flies (.wps)(.sbs), are placed in the /.rockbox/wps folder. Images specific to the .wps or .sbs must be placed in a folder inside the /.rockbox/wps directory, and the folder must share names with the .wps and/or .sbs.
Using a wps called "newwps" as an example, you place the newwps.wps file in the /.rockbox/wps directory (meaning its location is /.rockbox/wps/newwps.wps), and also create a folder in that directory named "newwps" (its location is /.rockbox/wps/newwps). Now all images can be placed in the /.rockbox/wps/newwps folder.
Fonts, Icons, and Backdrops all have folders located in the /.rockbox directory. Also, keep in mind that the filenames under the /.rockbox directory must be no more than 24 characters.
Theme files are extremely simple and also work differently than wps or base skin files. This section is the solely devoted to themes, the information here does not apply to the wps or sbs files. Below is an example .cfg file.
foreground color: FFFFFF
background color: 000000
line selector start color: FFFFFF
line selector end color: FFFFFF
selector type: bar (gradient)
viewers iconset: /.rockbox/icons/example_small_viewers.bmp
line selector text color: 000000
filetype colours: /.rockbox/themes/filename.colours
ui viewport: ????????????????????????
The first line links the theme to a .wps, and the next connects it to a .sbs. Now, after the theme has been selected, it loads those two files. The user font is defined in the font line. The foreground color changes the color of the font and several other foreground objects, and the background color is used in viewports and/or if the backdrop should fail to load. Colors are defined using standard rgb hex codes. If the statusbar line reads "custom" then a custom wps is used, by writing "top" or "bottom" in, the default .sbs is used and located at either the top or bottom. The backdrop line links a backdrop to the theme. This backdrop is used for both the .wps and .sbs unless it is over-ridden by one of those files. The line selecter is the highlighted bar that shows you what entry is selected. A gradient can be used by writing in two different colors in the "start color" and "end color" lines. The other options for selector type are, "bar (inverse)" which makes the text on the selected line the background color, and changes the selector bar to the foreground color, ??????. The iconset and viewers inconset are linked to the icons. The line selector text color defines the color of the text on a line that is higlighted. Filetype colours can be read about here: CustomFiletypeColours.
In the example above, the current tracks artist ("%ia") is displayed for 4 seconds, then the current album ("%id") is displayed for 1/2 a second, following that, the current track title ("%it") is displayed for the default 2 seconds.
Sublines can also be scrolled (using "%s"), and can be in the same line as non-scrolled sublines, as long as they are divided (with the ";"). The example below makes the artist ("%ia") subline and track ("%it") subline scroll, while the album ("%id") subline does not scroll.
Futhermore, sublines can be used with conditionals (conditionals explained below). Here is an example (this will make more sense if you understand conditionals first):
The first thing the player comes to is a [current artist conditional ("%?ia")]. If the artist is known, it [displays it for 4 seconds ("%t4")], allowing it to [scroll ("%s")]. If the artist is not known, then a subline is [displayed for 0 seconds ("%t0")], which means that the entire conditional is no longer used. After one or the other is displayed for its alotted time, the player moves onto a [current track title conditional ("%?it")]. If the title is known, then it is [displayed for 4.5 seconds (%t4.5")], and is allowed to [scroll ("%s")] (its displayed indefinetly if the artist is not known). If the title is not known, then the [filename of the playing track ("%fn")] [is displayed for 2 seconds ("%t")] (but if the artist is not known, it is displayed indefinetly).
%?--<a|b> ~ %?ia<%ia|Artist Unknown> ~ %?in<%in|%pp>
The first example shows the form of a conditional, the "%?" means that it is in fact condtional. The "--" is replaced with some form of tag. The "<a|b>" section offers two options to the conditional (explained using other examples).
In the second example, the conditional deals with the current track's artist (ia). Applying the previous statement, "if 'yes' then 'a'; if 'no' then 'b'", to the condtional gives you this: "If 'yes there is artist information", then 'display it (%ia tag)', if 'no there is not artist information' then 'display text (Artist Unknown)'".
The third example is taken from the "UniCatcher" wps. It relates to current track number (in) and playlist position (pp). Applying the same statement gives you this: "If 'yes the year is known' then 'display it (%in tag)', if 'no the year is not known' then 'display playlist position (%pp tag)'".
Some forms of conditional tags have more than two values (a,b), for example, the repeat status conditional has 5, and each represents a different repeat mode. Here is the tag:
This basically works the same way, except there are more possible answers to the conditional's questions. Most of this kind of tag have set sections for the different values. In the shuffle conditional above, the first section will be displayed when shuffle is "Off", the second when suffle is in "All" mode, etc. You'll see more of these tags throughout the guide and each one is explained.
Hopefully that helped you.
The code for viewport declarations is as follows:
If any viewports are defined, text can no longer be loaded into the default viewport (use it for images).
Viewports should not overlap. If part or all of them should, however, the latest viewport covers the previous one.
Only the |x| and |y| positions need to be defined. The other fields can default by inserting a "-" into that field, but do not delete any fields.
i.e. ( %V|0|0|-|-|-|-|-| )
The |x| and |y| vaules can be negative, negative values are measured from the right side (x axis) or bottom (y axis)
The |width| and |height| vaules can also be negative. These are also measured from the far sides.
The default width/height is the remaining part of the screen
The default font is the user font (from .cfg)
The default shade (greyscale LCD) is black fg, white bg
The default colors (color LCD) are the theme colors (from .cfg)
The 'identifier' is a single, lowercase letter (a-z). Viewports can share identifiers, allowing them all to be loaded with one display tag. Keep in mind that the display tag [%Vd(a-z)] must come before the preload tag [%Vl|(a-z)|x|y|...].
A custom UI viewport (viewport for the menus and file browser) can be set using a special viewport tag. It's strongly recommended to use this in your .sbs as it allows it to be used with other themes.
^ Tag ^ Description ^
^%Vi|x|y|width|height|font|...^for "..." see note below conditional viewport table^
These tags either enable or disable the Base Skin on the WPS. These tags override player settings, so if your WPS relies on the Base Skin either being on or off, use them.
These tags all rely on Id3 information pulled from the audio track. They are also able to be used as conditionals, and its suggested that you use them as such so missing information doesnt leave blank spots.
**Version 1.0, 1.1, 2.2, 2.3, 2.4 or empty if no ID3 tag present
**If bitrate is variable, then tag displays "(avg)", if it is constant, nothing is displayed.
***Example for the the %d# tags: If the path is "/Rock/Kent/Isola/file.mp3", %d1 is "Isola", %d2 is "Kent"... You get the picture.
*The "%px" can be used as a conditional to create custom progress indicators. Both the "%ps" and "%pv" can be used as conditionals. The "%ps" is used in this way, "%?ps<on|off>" (off is not needed, "%?ps<on>" is fine), and "%pv" is used in this way, "%?pv<Mute|...|0 dB|Above 0 dB> ("|...|" can be filled with as many sections as you like, the number of dB between "mute" and "0" will then be divided by the number of sections put in. For example, say "mute" is at -100dB, and i made 10 sections in the "|...|" area. At -90dB, -80dB, -70dB, etc., the next conditional would be used because 100/10 is 10.)
**Archos Play/Studio only
The Playlist Viewer allows you to display information for the upcoming tracks in the playlist. The Viewer takes up the entire viewport it is placed in. The tag is below:
Inside "start" section is placed a digit, and that digit tells the playlist viewer where to begin in the playlist. A "0" makes the current track the beginning of the viewer's list, a "1" makes the next track top on the list, etc.
The "show if id3" section is used for tracks which have been buffered. You can insert any of the following tags into that field.
playlist position "%pp", any tag beginning with "%i", most tags beginning with "%f", track length "%pt", and "%s" (scrolls ENTIRE viewer)
The "show otherwise" section is displayed for tracks which have not been buffered, at this point really only the filename and playlist position is known.
For example, "%Vp|1|%pp - %it|%pp - %fn|", will start the list with the upcoming track, for buffered tracks it will display the track's playlist position a "-" then the track title, and for unbuffered tracks the track's playlist position a "-" and then the filename.
Note: The "|show if id3|" and "|show otherwise|" sections can each have up to 16 tags, and a maximum of 8 free text strings(each up to a max. of 8 characters).
The playback mode tag has a total of nine modes, but not all are used on every player. The tag present the modes as the digits "1-9", and the order is Stop, Play, Pause, Fast Forward, Rewind, Recording, Recording Paused, FM Radio Playing, FM Radio Muted. The tag is as follows:
"%?mp<Stop|Play|Pause|Ffwd|Rew|Rec|Rec pause|FM|FM pause>"
You don't have to include all modes if the player doesn't have certain capabilities, however, all players should be able to use the first five modes.
Note: Currently, playing status 0 (stop), is only entered for a brief period of time when the last file in a playlist ends, just before the "menu" screen is automatically displayed. Intended future changes in WPS's features will extend the use of the "stop" status.
These tags can be used as conditionals, for example, "%?mh<Locked|Unlocked>".
There are six modes of crossfading, the crossfade tag displays them in the digits 0-5. The order is as follows, Off, Automatic Track Skip Only, Manual Track Skip Only, Shuffle, Shuffle or Manual Track Skip, Always.
The "%xf" tag can also be used as a conditional, in this way:
%?xf<Off|Automatic Track Skip|Manual Track Skip|Shuffle|Shuffle or Manual Track Skip|Always>
These tags are related namely to the battery and charging.
**only on targets that have software charge control or monitoring
An example (using simple text) for a battery meter:
In the above example, if the charger is plugged in, then it asks the question, "is the battery charging" if yes, then it displays "Charging", if it is not charging, but is plugged in, then "Connected is displayed. If the charger is not connected, then a battery level meter appears which displays power level in 10's.
The "%lh" tag can also be used as a conditonal, in this way:
Before we dive into images, take a look at these notes:
-Images must be in a Rockbox compatible format (see table below for model specific BMP compatibility).
-The x and y coordinates for image location must repect the player's LCD screen limits. (see table below)
-An image tag must be on its own line.
-There is a buffer limit on how many bitmap pixels can be loaded in to memory which is calculated as such: ((LCD_HEIGHT*LCD_WIDTH*LCD_DEPTH/8) + (2*LCD_HEIGHT*LCD_WIDTH/8)). This means that the total visual size of all of the bitmaps used cannot exceed the total of this calculation. For 16-bit targets, this comes to 2.25 times the size of the screen.
-The coordinates define the position relative to the viewport the corresponding display bitmap tag (%xd) is in.
-Some image loading tags contain an indicator (a-z or A-Z), this indicator is used by display tags to load the image.
In the tags below, "-" represents the images filename (see File Location above for correct placement), "~" represent an image's indicator (a-z or A-Z)
The following examples implements some of the common image tags:
In the example, the first line loads "background.bmp" and sets it as the backdrop; the second line loads "static_icon.bmp", displays it at 50,50 and shows it constantly; the third, fourth, fifth and sith line load images at the same position and give them indicators b,c,d and e; in the seventh line, images b,c,d and e are loaded in a shuffle mode conditional, each shuffle mode will now load a different image. (See next section for this example redone using bitmap strips)
In this example, an image is loaded as defined as image "a", and is positioned at 0,0. In the the second line, a viewport is created at 78,25. In the third line, image "a" is displayed, but!!! since the image display tag is under a viewport declaration, the image's coordinates are now relative to the viewport's coordinates (so the image will appear at 78,25 on the screen).
A Bitmap strip is an extremely convenient way to store multiple images in one .bmp file. The individual iamges (equally sized) are tiled veritcally then saved a a single .bmp file. The individual images are then loaded as subimages using subindicators.
For exmaple, "%xl|R|repeat.bmp|16|64|4|" - "%?mm<%xdRa|%xdRb|%xdRc|%xdRd>", the first code splits image "R" into 4 images (...|4|) along the y axis (assuming the image were 25px wide, 100px tall, it would split it into four 25px*25px sections). The second code loads the image's four parts using subindicators, so "%xdRa" loads the first part, "%xdRb" loads the second, etc.
Since this method cuts down on the number of images used in a WPS or SBS, it's advisable to use them wherever possible (espcially for images that load in the same spot, like a repeat mode icon).
This is the first example in the Basic Image Tags section, redone using a bitmap strip and subindicators.
The first two lines are the same as the previous verison of the example, but now "repeat.bmp" is a bitmap strip with four sections (the "|4|" at the end). The last line displays the the four sections of the image using subindicators. "%xdRa" loads the top 1/4 of image "R", "%xdRb" loads the second 1/4 (just below the first 1/4), and so on.
You can display Album Art using the following tags. Album Art will be cropped to the "|maxwidth|maxheight|" dimensions if they are larger than those dimensions (more information about AA here, AlbumArt ).
There are two conditional tags for album-art, "%?C" and "%?Cn". They indicate whether bitmap files have been found for the current (%?C) and next tracks (%?Cn). They work exactly like usual conditional tags, "%?C<a|b>"
You are in the %cs<Main menu|WPS|Recording screen|FM Radio screen>
These tags are only applicable to touch screen targets.
If action starts with "&", the area must be held to invoke the action.
In the "%T" tag, action can be:
play - play/pause playback
stop - stop playback, exit the wps
prev - prev track
next - next track
ffwd - seek forward
rwd - seek backwards
menu - go back to the main menu
browse - go back to the file/db browser
shuffle - toggle shuffle mode
repmode - cycle the repeat mode
quickscreen - go into the quickscreen
contextmenu - open the context menu
playlist - go to the playlist viewer
progressbar - seeks to the appropriate position based on the touch
volume - sets the appropriate volume based on the touch
pitch - go into the pitchscreen
voldown - decrease volume by one step
volup - increase volume by one step
This tag can be used to display text or images or a viewport when the touchscreen get pressed (like an On Screen Display). If you put a number straight after %Tl it will be used as a timeout in seconds (%Tl2.5 will give a 2.5 second timeout) between the touchscreen press being released and the tag going false. If no number is specified it will use a 1 second timeout.
Can be used as a simple tag %St|skip length| or with conditionals %?St|eq enabled|<Equalizer is enabled|Equalizer is disabled>
!!!!!!Needs usable settings list!!!!!!
The EZWPS Visual Basic application can help beginners on Windows to create a WPS file.
You can use a Rockbox UISimulator to preview your WPS on your Windows PC. Extract the archive for your model and copy your .wps file into the existing subdirectory "simdisk\.rockbox\wps". The directory "simdisk\" represents the root of your device. Put some music files into the "simdisk\" directory and play them. Change the WPS by choosing your WPS from the menu, just as you would on the player itself. Adding the --debugwps command line switch will provide very detailed information on the loaded WPS that will help you with the design process.
The checkwps tool
checkwps is a tool that will check whether a WPS is compliant to the syntax. It will also display various levels of debugging information. The maximum level of debugging information is equivalent to what the UiSimulator outputs.
Usage: checkwps [OPTIONS] filename.wps
-vv more verbose
-vvv very verbose
This tool is included in a regular SVN checkout. To compile it, cd to the tools/checkwps/ directory and run the ./buildall.sh script - this will create many versions of checkwps, one for each target device.
In the Vim text editor, a script here provides syntax highlighting for WPS files.
r1 - 17 Feb 2010 - 01:11:15 - ThomasKirkpatrick
Copyright © by the contributing authors.