dev builds
themes manual
device status forums
mailing lists
IRC bugs
dev guide

Search | Go
Wiki > Main > CustomizedDisplayGuide

Comprehensive Yet Comprehendible Customized Display Guide

Description / General Info
File Creation
File Location

Alternating Sublines
Conditional Tag
Conditional Viewports
Info Viewport
Base Skin on/off
Id3 Tags
Current Id3 Tags
Upcoming Id3 Tags
File Tags
Current File Tags
Upcoming File Tags
Playlist Tags
Progress Bar
Playlist Viewer
Playback Mode Tag
Repeat Mode Tag
Hold Switch Tags
Crossfade Tag
Power Related Information
Drive Actvity Tag
Runtime Database and Replay Gain
Real Time Clock
LCD Screen Sizes and BMP Compatibility
Basic Image Tags
Bitmap Strips
Album Art
Recording Screen Tokens
Current Screen
Other Settings
Other Tags

Description / General Info

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".
File Creation

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.
File Location

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.

wps: /.rockbox/wps/example.wps
sbs: /.rockbox/wps/
font: /.rockbox/fonts/example.fnt
foreground color: FFFFFF
background color: 000000
statusbar: custom
backdrop: /.rockbox/backdrops/example.bmp
line selector start color: FFFFFF
line selector end color: FFFFFF
selector type: bar (gradient)
iconset: /.rockbox/icons/example_small.bmp
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.


All information below is applicable to both the .wps and .sbs unless otherwise stated. "Tag" refers to a code (example: %al) that displays information, displays or loads images, positions an object or otherwise executes some action.



The following codes are applicable to text and in some cases images.
Tag Action
%al Aligns to the left
%ac Aligns in the center
%ar Aligns to the right

For Right to Left language support, us these codes:
Tag Action
%aL Aligns to the left on LTR languages and to the right on RTL languages
%aR Aligned to the right on LTR languages and to the left on RTL languages
%ax The next tag should follow the language direction (what that means is deifned by the individual tag). Currently %Cl and %V support this

Tag Action
%s Scrolls the line

This tag can occur anywhere in a line, given that the text is displayed (see conditionals). You can specify up to 10 scrolling lines. Scrolling lines can not contain dynamic content such as timers, peak meters or progress bars.
Alternating Sublines

Items on a line can be grouped into "sublines". Each subline will be displayed in sucession for a certain amount of time, with the player continuously alternating between them. The itmes in a line are divided with a semi-colon, ";". Each subline is dispalyed for 2 seconds unless the line is modified using the "%t#" tag.
Tag Action
%t# Sets display time for a subline

In the tag above, "#" represent a whole number. This number equals the number of seconds the line is displayed. For example, "%t4" will cause a subline to be displayed for 4 seconds. You can also specify tenths of a second like this, "%t4.6" or "%t0.1". Here's an example of an alternating subline:


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).
Conditional Tag

This is definetly not the simplest of all tags, but since the word "conditionally" will pop up through out the guide, you should go ahead and look at how this tag works. The conditional tag basically says "if 'yes' then 'a'; if 'no' then 'b'". Below is a simple form, and two actual conditionals:

%?--<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.

By default, a WPS fills the whole screen, and that screen is split into lines. Viewports allow you to specify a rectangular window in this screen, complete its own foreground/background colour. For the WPS, all lines before the first viewport declaration are drawn in the default (full-screen) viewport. Lines after a viewport declaration are drawn within that viewport. In Base Skins, you can only load images in that default viewport, you cannot draw tags into it or display text in it.

The code for viewport declarations is as follows:
LCD Type Viewport Declaration
Mono %V x y width height font  
Greyscale %V x y width height font fgshade bgshade  
Color %V x y width height font fgcolor bgcolor  

The |x| field determines the starting point for the vieport along the horizontal axis. The |y| field does the same, but for the vertical axis. The |width| and |height| fields set dimensions for the viewport. In the |font| field, you can put a "0" or a "1"; the 0 will load the deault system font for that viewport, and the 1 will load the user font defined in the .cfg file. For greyscale LCD's, fgshade and bgshade are defined by numbers 0-3;0=black, 3=white. For Color LCD's, fgcolor and bgcolor are defined by hexcode colors; e.g. EEC40B?.

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)
Conditional Viewports

Viewports can also be conditionally displayed. For exmaple, if album art is loaded, one set of viewports can appear, if, however, album art is not found, another set of viewports could appear. Tags are below:
Tag Action
%Vl 'identifier' x y width height font ... Preloads a viewport for display.
%Vd'indentifier' Displays the conditional viewport

In the first tag line, "..." should be deleted, replaced with "fgshade|bgshade|", or replaced with "fgcolor|bgcolor|" depending on LCD type.

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|...].
Info Viewport

!!Base Skin (.sbs) only!!

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^
Base Skin on/off

!!WPS (.wps) only!!

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.
Tag Action
%we Base Skin enabled
%wd Base Skin disabled
Id3 Tags

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.
Current Id3 Tags
Tag Action
%ia Id3 Artist*
%ic Id3 Composer*
%iA Id3 Album Artist*
%id Id3 Album Name*
%iG Id3 Grouping
%ig Id3 Genre
%in Id3 Track Number*
%it Id3 Track Title
%iC Id3 Comment
%iv Id3 Verison**
%iy Id3 Year
%ik Id3 Disc Number

*If a cuesheet is associated with the current track, and cuesheet support is enabled, "*"ed information will come form cuesheet instead of track.
**Version 1.0, 1.1, 2.2, 2.3, 2.4 or empty if no ID3 tag present
Upcoming Id3 Tags

To draw information from the upcoming track, simply replace the lowercase "i" in the current Id3 tags with an uppercase "I". For example, "%Ia" displays the upcoming artist, "%It" displays the upcoming track title, etc.
File Tags

File tags are relative to the file itself, rather than the audio you hear.
Current File Tags
Tag Action
%fb File Bitrate (in kbps)
%fc File Codec (e.g MP3 or FLAC)*
%ff File Frequency (in Hz)
%fk File Frequency (in KHz)
%fm File Name
%fn File Name (without extension)
%fp File Path
%fs File Size (in kilobytes)
%fv "(avg)" or ""<--blank**
%d1 1st directory from end of path***
%d2 2nd directory from end of path***
%d3 3rd directory from end of path***

*Codec tag can also be used as a conditional, %?fc<mp1|mp2|mp3|AIFF|wav|vorbis|flac|mpc|a52|wavpack|alac|aac|shorten|SID|ADX|NSF|speex|SPC|APE|WMA|unknown>. The codec order is as follows: MP1, MP2, MP3, AIFF, WAV, Ogg Vorbis (OGG), FLAC, MPC, AC3, WavPack? (WV), ALAC, AAC, Shorten (SHN), SID, ADX, NSF, Speex, SPC, APE, WMA, ???.
**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.
Upcoming File Tags

Same as with upcoming Id3 tag, simply replace the first letter of the tag with it's capital version. For example, "%Fb" displays upcoming birate, and %D1 displays the upcoming track's directory.
Playlist Tags
Tag Action
%pc Track time elapsed
%pr Track time remaining
%pt Track time total
%px Elapsed time in %*
%pe Total # of playlist entries
%pn Playlist name (without ext. or path)
%pp Playlist position
%pm Entire line used as volume peak meter
%Sp Current playback pitch
%pf Full-line progress bar + time display**
%ps Shuffle, shows s if shuffle in on*
%pv Displays volume in dB*
%mv Indicates volume increasing/decreasing*

*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
Progress Bar

The progress bar is a image that loads relative to the time elapsed. For example, half-way through your song, 50% of the image would be visible. Progress bars load horizontally, and you can use up to three, with a maximum of one per viewport.The progress bar tag will replace an entire line with a 6 pixel high progress bar if no bitmap and other parameters are defined. Optionally, you can set the image to use, as well as its position and size. Any parameter can be set to the default by using a dash "-".

Tag Action
%pb filename.bmp x y width height   Loads and positions progress bar

For the Archos Player/Studio, this will display a one character "cup" that empties as the time progresses (only %pb).
Playlist Viewer

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:

Tag Action
%Vp start show if id3 show otherwise   Displays the "playlist viewer"

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).
Playback Mode Tag

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:

Tag Action
%mp Playback Mode

The tag can also be used as a conditional, which is used in this way:
"%?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.
Repeat Mode Tag

The repeat mode tag displays the five different repeat modes in the digits "0-4". The order is, 0 = Off, 1 = All, 2 = One, 3 = Shuffle, 4 = A-B. The tag is as follows:

Tag Action
%mm Repeat mode

The tag can also be used as a conditional, which is used in this way:
Hold Switch Tags

Tag Action
%mh Shows "h" if hold is on
%mr Shows "r" if remote hold is on

These tags can be used as conditionals, for example, "%?mh<Locked|Unlocked>".
Crossfade Tag

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.

Tag Action
%xf Displays crossfade mode

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>
Power Related Information

These tags are related namely to the battery and charging.

Tag Action
%bl Shows battery level in number %*
%bv Shows battery level in volts
%bt Shows estimated battery time left
%bp Shows a "p" if charger is connected*
%bc Shows a "c" if currently charging* **
%bs Shows time left on sleep timer

*Can be used as a conditional. For "%bl", "%?bl<-1|0|1|2|...|N>" where "-1" is when battery level is unknown (it usually is known), and "|...|" filled with as many sections as desired. For "%bp" use "%?bp<-|->; for "%bc" use "%?bc<-|->".
**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.
Drive Actvity Tag

Tag Action
%lh Shows a "h" when drive is active

The "%lh" tag can also be used as a conditonal, in this way:
Runtime Database and Replay Gain

Tag Action
%rp Shows number of times song has been played
%rr Shows song rating using "0-10"*
%ra Shows database autoscore for the song
%rg Shows Replay Gain value in use (x.ydB)*

*Can be used as a conditional. For "%rr", "%?rr<0|1|2|3|4|5|6|7|8|9|10>" is used; for "%rg", "%?rg<Off|Track|Album|TrackShuffle|AlbumShuffle|No tag>" is used.
Real Time Clock

Tag Action
%cc Is there an RTC?
%cd Day of month (01-31)
%ce Day of month, blank padded (1-31)
%cm Month (01-12)*
%cb Abbreviated month name (Jan-Dec)
%ca Abbreviated weekday name (Sun-Sat)
%cu Day of week (1-7), 1 is Monday*
%cw Day of week (0-6), 0 is Sunday*
%cf Conditional for 12/24 hour format*
%cH Hour (00-23)
%ck Hour (0-23)
%cI Hour (01-12)
%cl Hour (1-12)
%cM Minute (00-59)
%cS Second (00-59)
%cy Last digits of year (00-99)
%cP Upper-case AM or PM indicator
%cp Lower-case am or pm indicator

*Can be used as a conditional. "%cm" is used as "%?cm<January|February|March|April|May|June|July|August|September|October|November|December>"; "%cu" is used as" %?cu<Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday>"; "%cw" is used as "%?cw<Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday>"; "%cf" is used as %?cf<24 hour stuff|12 hour stuff>.


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.
LCD Screen Sizes and BMP Compatibility

Player Main LCD Size Main LCD - BMP's Remote LCD Size Remote LCD - BMP's
iriver H1x0 160x128 1-bit 128x64 1-bit
iriver H3x0 220x176 1-bit, 24-bit 128x64 1-bit
iriver H10 (5/6Go) 128x128 1-bit, 24-bit no remote n/a
iriver H10 (20Go) 160x128 1-bit, 24-bit no remote n/a
Archos Recorders 112x64 1-bit no remote n/a
Archos Ondio 112x64 1-bit no remote n/a
iPod Nano 176x132 1-bit, 24-bit no remote n/a
iPod 4G Grey 160x128 1-bit no remote n/a
iPod 4G Color 220x176 1-bit, 24-bit no remote n/a
iPod 5G Video 320x240 1-bit, 24-bit no remote n/a
iPod Mini/Mini2G 138x110 1-bit no remote n/a
iAudio X5 160x128 1-bit, 24-bit 128x96 2-bit (4 gray levels)
Toshiba Gigabeat Fxx 240x320 1-bit?, 24-bit ? ?
Toshiba Gigabeat Xxx 240x320 1-bit?, 24-bit ? ?
SanDisk Sansa e200 176x220 1-bit?, 24-bit no remote n/a
SanDisk Sansa c200 132x80 1-bit?, 24-bit ? ?

Basic Image Tags

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)

Tag Action
%X filename.bmp   Loads a backdrop image for the WPS. This image must be exactly the same size as your LCD.
%Xd Disables the backdrop
%x ~ -.bmp x y   Loads and always shows the image
%xl ~ -.bmp x y #oftiles   Preloads an image for display (useful when images are displayed conditionally)
%xd~* Displays a preloaded image

*For bitmap strips (see below) the tag becomes "%xd+indicator+subindicator". Example, %xdGb or %xdce

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).
Bitmap Strips

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.
Album Art

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

Tag Action
%Cl xpos ypos maxwidth maxheight   Loads Album Art More Details
%C Displays Ablbum Art More Details

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>"


Recording Screen Tokens

!!Base Skin Only!!

Tag Action
%Rp Does target have recording? (If not, the "true" of this conditional is ignored so don't worry about recording tags on non recording targets
%Rm Currently recording in mono
%Rf Recording Frequency/Samplerate*
%Re Encoder being used (in the order WAV, AIFF, WV, MP3. SWCODEC only!)
%Rb Bitrate; SWCODEC and MP3: %?Rb<8 16 24 32 40 48 56 64 80 96 112 128 144 160 192> HWCODEC: Quality setting.. 0-7 inclusive

*Conditional always uses the values; HWCODEC: %?Rf|44|48|32|22|24|16> ; SWCODEC: %Rf<96|88|64|48|44|32|24|22|16|12|11|8> (remember, your target may not support all of these).
Current Screen

Tag Action
%cs Screens from 1-4, in the order: Menus, WPS, Recording screen, FM Radio screen

Example use:

You are in the %cs<Main menu|WPS|Recording screen|FM Radio screen>

!!WPS Only!!

These tags are only applicable to touch screen targets.

Tag Action
%T x y width height action   Invoke the action when the user presses in the touchscreen area

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

Tag Action
%Tl Indicates that the touchscreen is pressed

Can also be used as a conditional or with conditional viewports.

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.
Other Settings

Tag Action
%St setting name   Indicates value of the specified setting

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!!!!!!
Other Tags

Tag Action
%% Displays a "%"
%< Displays a "<"
%   Displays a " "
%> Displays a ">"
%; Displays a ";"
%# Displays a "#"



The EZWPS Visual Basic application can help beginners on Windows to create a WPS file.

The UISimulator

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

-v verbose
-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 ./ 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.