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

Search | Go
Wiki > Main > DocsIndex > CustomWPS

Custom WPS Display - File Format Specifications

Note: a Custom WPS Display file format specification also exists in the manual (13.2.2). The manual and this page differ in certain aspects and may not be up-to-date.

Description / General Info

  • The Custom WPS Display is used as a means to customize the while playing screen or Custom Status Bar to the user's likings. This guide was originally designed for the While Playing screen only, but unless explicitly noticed everything applies to the Custom Status Bar and the FM Screen as well.
  • After editing the .wps, .sbs or .fms file, "play" it to make it take effect.
  • All characters not preceded by % are displayed as typed.
  • Everything that follows a # in a line (including the newline character) is a comment.
  • The file size isn't limited, but the content is. If your WPS file is too complex, only the first part of it will be loaded and used.
  • Any text, including newlines, will be treated as text and will thus take up a line on the screen, unless the ONLY thing on the line is a non-text tag and a newline. Non-text tags are, for example, the status bar tags and the tags for image displaying.
  • For a simpler guide to making your own WPS, see the SimpleGuideToWPSMaking.

File Location

Custom WPS files may be located anywhere on the drive, although it's recommend to organize them in the ".rockbox/wps/" directory. The only restriction is that they must end in .wps. When you PLAY a .wps file, it'll be used for the future WPS screens. If the "played" wps file is located in the /.rockbox folder, it'll be remembered and used for subsequent restarts. Filenames in the /.rockbox folder must be no more than 24 characters long. Images will be looked for in the same-named folder in the ".rockbox/wps/" directory.

How To Create A .wps File

Quite simply, enter the WPS code in your favourite text editor, Notepad on Windows works fine. When you save it, instead of saving it as a .txt file, save it as a .wps file. Example: Instead of Rockbox.txt, save the file as Rockbox.wps. To make sure non english characters display correctly in your WPS you must save the .wps file 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.



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, and lines after a viewport declaration are drawn within that viewport. In Custom Status Bars, you can only load images in that default viewport. You cannot draw them or display text in it.

The syntax of the viewport declaration is: %V(x,y,[width],[height],[fontid]) where:

  • x is the x pixel, y is the y pixel (0,0 being top left)
  • width is the pixel width of the viewport ('-' means full width), height is height of viewport ('-' means full height).
  • fontid is the font identification number - 0 is the built in font, 1 is the user font, 2-9 are skin loaded fonts (see below).

  • In the Custom Status Bar, you must use viewports. You must not draw into the default full-screen viewport. However, loading images in the default vp is OK.
  • If any viewports are defined, you cannot display text in the default viewport (use it for images only)
  • Viewports cannot be layered transparently over one another. Subsequent viewport definitions will be drawn over any other viewports already drawn onto that area of the screen.
  • Only the x and y values need to be specified. The rest can be left empty if you want to use their default values (use '-' to achieve this, e.g. %V(0,0,-,-,1)).
    • default width/height is the remaining part of the screen
    • default font is the user font
    • default colour (16 bit lcd's) is the theme colours
    • default shade (2bit lcd's) is black FG on white BG
  • The x and y values may be negative which means "pixels from the far edge".. i.e x == -50 means 50 pixels from the right edge
  • The x, y, width and height value may be specified as percentages, the actual value will be calculated from the target's display at load time. Percentage parameters can be mixed with normal ones. Percentages can carry upto 1 fractional digit for increased precision. Example: %V(10.5%,10,80%,80,-)
  • The width and height values may also be negative which means almost the same as above (e.g. %V(50,-,-50,-,-) will go from 50 to 170 on a 220-pixel display).

Conditional Viewports

Any viewport can be conditionally displayed with minor changes to the above syntax.

Tag Description
%Vl('identifier',....) Preload a viewport for later display. 'identifier' is a single lowercase letter (a-z) and '....' is the same as the usual %V tag (above)
%Vd('identifier') Display the 'identifier' viewport. e.g %?C<%C%Vd(a)|%Vd(b)> will show viewport 'a' if album art is found, and 'b' if it isnt.

  • Viewports can share identifiers so you don't end up with bloated code like %?C<%V(da)%V(db)%V(dc)|%V(de)%V(df)%V(dg)>.
  • The conditional viewport display tag must come before the preload tag.

Info Viewport (Base Skin (.sbs) only)

Tag Description
%Vi(label,....) This viewport is used as Custom UI Viewport in case the theme doesn't have a ui viewport set in the theme.cfg. Using '-' for the label means it is used by default. Having this is strongly recommended since it makes you able to use Custom Status Bars with other themes. If label is set this viewport can be selectivly used as the Info Viewport using the %%VI tag
%VI(label) Set the Info Viewport to use the viewport labeled label
LCD type Colour values
Mono no colours. tag ignored
Greyscale in the range 0 (= black) to 3 (= white)
Colour 6-digit RGB888 colours - e.g. FF00FF

Viewport Colours

Tag Description
%Vf(colour) colour is used for the remainder of the viewports foreground colour.
%Vb(colour) colour is used for the remainder of the viewports background colour.
%Vg(start, end [, text]) start end and optional text colour for gradient coloured lines.
These need to be before any other tags after a %V() line or scrolling lines will not work as expected.

Viewport Line Text Styles

Tag Description
%Vs(mode[, param]) set the viewport text style to 'mode' for the remainder of the viewport
Mode is:
Mode Description
clear restore the default style
invert draw the line inverted
color Draw the text coloured the value given in param. Functionally equivalent to using the %Vf() tag
gradient Draw the next param lines using a gradient. by default the gradient is over 1 line. %Vg(gradient,2) will use 2 lines to fully change from the start colour to the end colour

Viewport Draw Layer

Tag Description
%VB Draw on the backdrop layer

Rockbox uses two framebuffers when it does a screen redraw. The bottom layer is used for the backdrop image (the static parts of the display behind text for example), and the upper layer (the text/images). Using this tag you can tell the skin engine to instead draw everything in this viewport onto the backdrop layer instead of the foreground layer. Don't draw text here as it may not work too well. If the skin has this any %X() tag will be ignored and the whole screen will have a solid background (with the colour specified in the settings), so to get the most out of this feature:
  1. Add a full screen viewport at the start of the skin .. i.e %V(0,0,-,-,-) %VB
  2. Use %x(filename, 0, 0) to draw a backdrop image (If you want one!)
  3. Then add %V(0,0,-,-,-) and continue with your skin as normal. Any viewports you want drawn on the backdrop need the %VB tag but otherwise code as normal.

Draw a rectangle! (optionally with a gradient)

Tag Description
%dr(x,y,width,height[colour1[,colour2]]) Colour a rectangle at pixel (x,y), width/height can be - to fill the viewport.
if both colours are left out the viewports foreground colour will be used if one colour is specified it will fill the rectangle that colour. if both colours are specified it will gradient fill the rectangle.


Tag Description
%Fl(fontid,filename,glyphs) fontid is the font identification number number that is used to reference the font in a viewport decleration. 0 and 1 are reserved so can't be used. filename is the font filename to load. glyphs is an optional specification of how many glyphs to reserve memory for. This should be large enough to prevent frequent glyph loading from disk. The default is 256 glyphs if not specified. fonts live in /.rockbox/fonts/ e.g. %Fl(2,12-Font.fnt,150)

Status Bar

These tags override the player setting for the display of the status bar, they must be on their own line.

Tag Description
%we Status Bar Enabled
%wd Status Bar Disabled
%wi Display the inbuilt statusbar in the current viewport

It can also be used for the Custom Status Bar

ID3 Tag Info

Remember that this information is not always available, so use the conditionals to show alternate information in preference to assuming.

Tag Description
%ia ID3 Artist*
%ic ID3 Composer*
%iA ID3 Album Artist*
%id ID3 Album Name*
%iG ID3 Grouping
%ig ID3 Genre Name
%in ID3 Track Number*
%it ID3 Track Title
%iC ID3 Comment
%iv ID3 Version (1.0, 1.1, 2.2, 2.3, 2.4 or empty if no ID3 tag)
%iy ID3 Year
%ik ID3 Disc Number
If a cuesheet is associated with the current playing track (and cuesheet support is enabled), the starred items above will be retrieved from the cuesheet instead of the audio track

Next Track Info

Tag Description
%Ix Next song ID3 tag info
%Fx Next song file info
%Dx Next song directory info

You can also display information about the next track in the playlist. If you use the uppercase versions of the I, F and D tag groups they will refer to the next song instead of the current one.

Example: %Ig is the genre name used in the next track and %Ff is the audio frequency of the next track.

Take note that the next song information WILL NOT be available at all times, but will most likely be available by the end of a song. We suggest you use the conditional display tags when displaying information about the next song, just in case.

Power-Related Information

Tags pertaining to power - namely battery level and charging.

Tag Description
%bl Show numeric battery level in percent. Can also be used in a conditional: %?bl<-1|0|1|2|...|N>
where the -1 value is used when the battery level isn't known (it usually is). Can also be used as a bar (See #Bar_Tags)
%bv Show the battery level in volts
%bt Show estimated battery time left or -1 if no runtime data is defined in target config file
%bp "p" if the charger is connected (only on targets that can charge batteries)
%bc "c" if the unit is currently charging the battery (only on targets that have software charge control or monitoring)
%bs Sleep timer - Time left until stop

Real Time Clock

Tags allowing to add a clock to your WPS. They will be empty if the time isn't set correctly.

Tag Description
%cc Is there a RTC?
%cd day of month (01..31)
%ce day of month, blank padded ( 1..31)
%cf use for a conditional for 12/24 hour format. %?cf<24 hour stuff|12 hour stuff>
%cH hour (00..23)
%ck hour (0..23)
%cI hour (01..12) - (that's a c and an uppercase i)
%cl hour (1..12) - (and this is a c and a lowercase L)
%cm month (01..12)
Can also be used in a conditional tag: %?cm<January|February|March|April|May|June|July|August|September|October|November|December>
%cM minute (00..59)
%cS second (00..60)
%cy last two digits of year (00..99)
%cY year (1970...)
%cP upper case AM or PM indicator
%cp lower case am or pm indicator
%ca abbreviated weekday name (Sun..Sat)
%cb abbreviated month name (Jan..Dec)
%cu day of week (1..7); 1 is Monday
Can also be used in a conditional tag: %?cu<Monday|Tuesday|Wednesday|Thursday|Friday|Saturday|Sunday>
%cw day of week (0..6); 0 is Sunday
Can also be used in a conditional tag: %?cw<Sunday|Monday|Tuesday|Wednesday|Thursday|Friday|Saturday>

For example, "%ca, %cb %cd, %cH:%cM:%cS" will display (assuming it's January 1st, a Sunday, at 04:10 and 42 seconds) "Sun, Jan 01, 04:10:42".

The tags have values only if the RTC is set properly. This means that to avoid having empty values displayed like ", , ::", you can use a conditional like this: "%?cc<%ca, %cb %cd, %cH:%cM:%cS|RTC needs setting!>"

File Info

Tag Description
%fb File Bitrate (in kbps)
%fc File Codec (e.g. "MP3" or "FLAC")
This tag can also be used in a conditional tag, %?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. See the AFMT_* enum in rockbox/lib/rbcodec/metadata/metadata.h
%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)" if variable bit rate or "" if constant bit rate
%d(1) First directory from end of file path.
%d(2) Second directory from end of file path.
%d(3) Third directory from end of file path.

Example for the the %d(N) commands: If the path is "/Rock/Kent/Isola/11 - 747.mp3", %d(1) is "Isola", %d(2) is "Kent"... You get the picture.

Playlist/Song Info

Tag Description
%pb(x,y,width,height,filename.bmp) Progress Bar
Archos Player/Studio: This will display a 1 character "cup" that empties as the time progresses. (only %pb)
Others: This will replace the current entire line with a 6 pixels 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 (-).
%pf Archos Player/Studio only: Full-line progress bar + time display
%px Percentage Played In Song. Can also be used in a conditional to create custom progress indicators.
%pc Current Time In Song (when used with %if() returns the number of seconds elapsed)
%pe Total Number of Playlist Entries
%pm Peak Meter The entire line is used as volume peak meter.
%pL Show the left channel peak meter value. Can also be used in a conditional: %?pL(0|1|2|...|N)
. Can also be used as a bar (See #Bar_Tags)
%pR Show the right channel peak meter value. Can also be used in a conditional: %?pR(0|1|2|...|N)
. Can also be used as a bar (See #Bar_Tags)
%pn Playlist Name (Without path or extension)
%pp Playlist Position
%pr Remaining Time In Song (when used with %if() returns the number of seconds remaining)
%ps Shuffle. Shows 's' if shuffle mode is enabled.
%pt Total Track Time (when used with %if() returns the number of seconds the track runs for)
%pv Current volume in decibels (dB). Can also be used in a conditional: %?pv<Mute|...|0 dB|Above 0 dB> Can also be used as a bar (See #Bar_Tags)
%pS Track is starting (optionally with a number for how many seconds the tag should stay true for after the song starts) Default time is 10s if no number used.
%?pS(7)<in first 7s of track|rest of track>
%pE Track is ending (optionally with a number for how many seconds the tag should stay true for before the song ends) Default time is 10s if no number used
%?pE<in last 10s of track|rest of track>
%Sp Current playback pitch

Playlist viewer

This allows you to display some information for the upcoming tracks in the playlist (instead of just the next track).
Tag Description
%Vp(start,skin code to render) Display the playlist viewer in the current viewport. The entire viewport will be used, so don't expect other tags in the same viewport to work well
  • start - the offset from the current playing track for the playlist to start showing (0 is start at the current track, 1 is the next track, etc)
  • "skin code to render" is a single line of code which should get displayed. It can have conditionals and sublines to make it interesting. Will be repeated for each line in the viewer
example: %Vp(1, %pp - %?it<%it|%fn>) will display the playlist position, then either the track title (from id3) or the filename. The viewer will display as many tracks as will fit in the viewport.

Runtime Database and Replaygain

Tag Description
%rg Replaygain value in use (x.y dB). If used as a conditional, Replaygain type in use: %?rg<Off|Track|Album|TrackShuffle|AlbumShuffle|No tag>
%rp Song playcount
%rr Song rating (0-10). This tag can also be used in a conditional tag, %?rr<0|1|2|3|4|5|6|7|8|9|10>
%ra Database autoscore for the song

Hold Switches

Tag Description
%mh "h" if the main unit hold switch is on
%mr "r" if the remote hold switch is on

Example: %?mh<Locked|Unlocked>

Virtual LED

Tag Description
%lh "h" if there is hard disk activity

Repeat Mode

Tag Description
%mm Repeat mode, 0-4, in the order: Off, All, One, Shuffle, A-B

Example: %?mm<Off|All|One|Shuffle|A-B>

Playback Mode

Tag Description
%mp Play status, 1-9, in the order: Stop, Play, Pause, Fast Forward, Rewind, Recording, Recording paused, FM Radio playing, FM Radio muted

Example: %?mp<Stop|Play|Pause|Ffwd|Rew|Rec|Rec pause|FM|FM pause>

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.


Tag Description
%xf Crossfade type, 0-5, in the order : Off, Automatic Track Skip Only, Manual Track Skip Only, Shuffle, Shuffle or Manual Track Skip, Always

Example: %?xf<Off|Automatic Track Skip|Manual Track Skip|Shuffle|Shuffle or Manual Track Skip|Always>


Images are used to make skins slightly more interesting than just plain text.

Because most uses of images are to display some player/setting state it is usual to create an "image strip" which groups all the images for a single tag into one vertical strip where only one of the images in the strip will be shown (explained below)

Tag Short Description
%X(filename.bmp) Load and set a backdrop image for the Skin.
%x(label, filename.bmp, x, y) load and display this image at the desired coordinates (viewport relative)
%xl(label, filename.bmp, x, y [, nimages]) Preload an image to be displayed later (optionally specifing the number of subimages in this bmp strip)
%xd(<subimage label>) or %xd(label[, <subimage number>[, subimage offset]]) Display a preloaded (sub)image

%X - Load a background image

filename.bmp is the filename of the image to load. If - is used then the background image from the Base Skin or settings will be used. if %X(d) is used NO background image will be used (so only the flat background colour will be used)

%x - Load and display an image

  • label is ignored unless %xd() is used with this image, which is not necessary. x,y are the viewport relative pixel coordinates to draw at

%xl - Load an image for display with %xd

  • label is some unique identifier for this image. All alphanemrical characters are supported (unicode might also work). If only a single letter is used you may use the shorter form of %xd(<subimage label>) to display it
  • nimages is an optional number of subimages in this bitmap strip. If this isnt specified then the whole image will always be displayed.

%xd - Display a preloaded (sub)image

This tag has a few forms.
  1. The simplest is when the image is not a bitmap strip. %xd(label) will display that image in the current viewport at the relative pixel coordinates.
  2. If the image is a bitmap strip:
    • %xd(label, <subimage number> [, offset])
      • label is the label of the image to draw
      • <subimage number> is either a number (1 being the first/top image) of the subimage to draw, or a tag which is useable in a conditional to automatically draw the corresponding subimage. (e.g %xd(playmode, %mm) is equivilant to %?mm<%xd(playmode, 1)|%xd(playmode, 2)|%xd(playmode, 3)|%xd(playmode, 4)>
      • offset is an offset into the bitmap strip to add before selecting the subimage. (i.e if there is no "stop" image then the above example would be changed to %xd(playmode, %mm, -1) is equivilant to %?mm<|%xd(playmode, 1)|%xd(playmode, 2)|%xd(playmode, 3)>
    • %xd(<subimage label>) is the final form: ( only usable if the image label is one letter)
      • <subimage label> is a 2 letter combination, the first letter being the image label, the second being the subimage letter, a = 1, b = 2, etc.. z = 26, A = 27

  • The images must be in a Rockbox compatible format (see table below for model specific BMP compatibility). On color displays, all common sorts of BMP are supported.

  • The size of the LCD screen for each player varies. See table below for appropriate sizes of each device. The x and y coordinates must repect each of the players' limits.

  • ARGB BMP's can be used for transparent images.

  • The colour magenta [R=255,G=0,B=255] is translated as transparent when used in BMP's, and can be used to create transparent (or background colour) parts in images in the WPS.

  • The colour pure cyan [R=0,G=255,B=255] is translated as foreground colour when used in BMP's, and therefore can be used to create images in the WPS that will be foreground dependent.

  • Similarly to the two notes just exposed, if monochrome bitmaps are used (real 1-bit ones) the black parts will use the foreground colour and the white parts will use the background colour (or transparent colour). This method also works on greyscale targets with shades set through %Vf/%Vb. Also, these bitmaps will be smaller and take less skin buffer.

  • The image tag must be on its own line.

  • The ID is case sensitive

  • Images will be searched for in a folder in the ".rockbox/wps/" directory with the same title as the WPS file. So, for example, if your WPS is titled RockboxWPS.wps, you need to create a folder titled RockboxWPS and place your image files inside of it.

  • The coordinates give the position relative to the viewport the corresponding display bitmap tag (%xd) is in.

Bitmap Strips

Bitmap Strips are used to display portions of an image. The images you wish to display must be tiled vertically within the "container" image. For example

The above code says "Load volume.bmp at coordinates x,y , which contains 10 subimages". So if the "volume.bmp" was 100 pixels high, this would display the top 10 pixels for %xdMa and the next 10 pixels for %xdMb and so on.

Also see the images section above for more information about the tag syntax.

LCD Screen Sizes / 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, 32-bit 128x64 1-bit
iriver H10 (5/6Go) 128x128 1-bit, 24-bit, 32-bit no LCD remote n/a
iriver H10 (20Go) 160x128 1-bit, 24-bit, 32-bit no LCD remote n/a
Archos Recorders 112x64 1-bit no LCD remote n/a
Archos Ondio 112x64 1-bit no remote n/a
iPod Nano 176x132 1-bit, 24-bit, 32-bit no remote n/a
iPod 4G Grey 160x128 1-bit no remote n/a
iPod 4G Color 220x176 1-bit, 24-bit, 32-bit no remote n/a
iPod 5G Video 320x240 1-bit, 24-bit, 32-bit no remote n/a
iPod Mini/Mini2G 138x110 1-bit no remote n/a
iAudio X5 160x128 1-bit, 24-bit, 32-bit 128x96 2-bit (4 gray levels)
Toshiba Gigabeat Fxx 240x320 1-bit, 24-bit, 32-bit ? ?
Toshiba Gigabeat Xxx 240x320 1-bit, 24-bit, 32-bit ? ?
SanDisk Sansa e200 176x220 1-bit, 24-bit, 32-bit no remote n/a
SanDisk Sansa Fuze 176x220 1-bit, 24-bit, 32-bit no remote n/a
SanDisk Sansa c200 132x80 1-bit, 24-bit, 32-bit no remote n/a
SanDisk Sansa Clip(+) 128x64 1-bit no remote n/a

Album Art

It is possible to make your WPS display cover art. See AlbumArt for full details. Both of the following tags are required:

Tag Description
%Cl(xpos,ypos,maxwidth,maxheight,[horizontal alignment],[vertical alignment]) Define the picture settings. More details. Horizontal alignment can be 'l', 'r', or 'c', for left, right and center. Vertical alignment can be 't', 'b', or 'c', for top, bottom and center.
%Cd Display the album art bitmap. More details
%C Use in a conditional to check if album art has been loaded

Recording Screen tokens (currently only usable in a .sbs skin)

Tag Description
%Rp Does this target have recording? If it doesnt the "true" of this conditional is completely ignored so you don't need to worry about tags which are not recognized on non recording targets
%Rm Currently recording in mono
%Rf Recording frequency/samplerate... 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
%Re Encoder being used: in the order Wav, aiff, wv, mp3. SWCODEC only!
%Rb Bitrate - SWCODEC (and MP3 only): %?Rb<8 | 16 | 24 | 32 | 40 | 48 | 56 | 64 | 80 | 96 | 112 | 128 | 144 | 160 | 192> HWCODEC: Quality setting.. 0-7 inclusive
%Rr Does this target currently record? Used in FM screen on HWCODEC targets.
%Rh Recording hour. Used in FM screen on HWCODEC targets.
%Rn Recording minute. Used in FM screen on HWCODEC targets.
%Rs Recording second. Used in FM screen on HWCODEC targets.

FM Radio tokens

Some of the radio tokens are better used as a switch for a conditional, i.e. as %?xx<stuff for true|stuff for false>.

Tag Description
%tp Does this target have a radio? If it doesn't, the "true" branch of this conditional is completely ignored so you don't need to worry about tags which are not recognized on non radio targets.
%tt Tuner tuned?
%tm Scan or preset mode? Scan is "true", preset is "false"
%ts Is the station in stereo?
%ta Minimum frequency (region specific) in MHz, with two decimal digits
%tb Maximum frequency (region specific) in MHz, with two decimal digits
%tf Current frequency in MHz, with two decimal digits
%tr Current signal strength in dBu
%Ti Current preset id, i.e. 1-based number of the preset within the presets list (usable in playlist viewer)
%Tn Current preset name (usable in playlist viewer)
%Tf Current preset frequency (usable in playlist viewer)
%Tc Preset count, i.e. the number of stations in the current preset list
%tx Does this target have RDS?
%ty RDS name
%tz RDS text


Tag Description
%al Text is left aligned
%aL Text is aligned left on LTR languages and right on RTL languages
%ac Text is center aligned
%ar Text is right aligned
%aR Text is aligned right on LTR languages and 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
%Sr Use as a conditional to define options for left to right, or right to left languages.

All alignment tags may be present in one line, but they need to be in the order left - center - right. If the aligned texts overlap, they are merged.


Tag Description
%s Indicates that the line should scroll

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.

Increasing/Decreasing Volume

Tag Description
%mv Indicates that volume is increasing/decreasing

This tag can be used to display text or images only when the volume is being changed. If you put a number straight after %mv it will be used as a timeout in seconds (e.g %mv(2.5) will give a 2.5s timeout) between the volume button being released and the tag going false. If no number is specified it will use a 1 second timeout

Can also be used as a conditional, and can be used with conditional viewports for some really neat effects.

Showing other settings

Tag Description
%St(setting name) Indicates value of the specified setting
%St(bar params, setting, (setting name)) Displays the setting value as a bar

Showing translated strings (LANGID)

Tag Description
%Sx(english_langstring) English name of a language dependent string

Note: prior to Dev version 6fb942d an invalid lang string aborted theme engine After patch g#3894 <ERR> is returned and can be tested against to provide fallback strings

Example: Can be used as a simple tag %Sx(Yes) or with conditionals %?if(%Sx(KiB), =, <ERR>)<KiB|%Sx(KiB)>

Touchscreen areas

Tag Description
%Tp Indicates if the target has a touchscreen or not
%T([label,] x,y,width,height,action,[options]) Invoke the action when the user presses in the touchscreen area. label is optional and only needed if you wish to link it with a %Tl (see below)

Action is one of:
Action Description
none do nothing
play play/pause playback
stop stop playback, exit the wps
prev prev track/item
next next track/item
wps_prev prev track
wps_next next track
ffwd seek forward
rwd seek backwards
progressbar seeks to the appropriate position based on the touch
shuffle toggle shuffle mode
repmode cycle the repeat mode
volume sets the appropriate volume based on the touch
voldown decrease volume by one step
volup increase volume by one step
mute mute/unmute playback volume
createbookmark create a bookmark in the currently-playing track
hotkey performs the action assigned to the hotkey
menu go back to the main menu
browse go back to the file/db browser
resumeplayback go back to the last music screen (wps or radio)
quickscreen go into the quickscreen
contextmenu open the context menu
playlist go to the playlist viewer
listbookmarks list the bookmarks for the currently-playing directory or playlist
trackinfo open the track info viewer
pitch go into the pitchscreen
setting_inc increase a config setting (the setting name is the next parameter) Example: %T(10,20,32,32,setting_inc,bass,[options])
setting_dec decrease a config setting (the setting name is the next parameter)
setting_set set a config setting to a specific value. Example: %T(10,20,32,32,setting_set, repeat, off,[options])
lock soft lock the touchregions effectivly disableing all regions unless they are the lock action (or have the allow_while_locked option (see below)
  • Not all config values are supported or work well. Outright unsupported settings will cause the parser to reject the theme. Other settings might not take effect immediately. similar limitations to the options allowed on the quickscreen
Available options:
option Description
repeat_press This region will trigger mulitple times when held (i.e for seeking)
long_press This region will trigger once after it is held for a long press
reverse_bar Reverse the bars touch direction (i.e seek right to left)
allow_while_locked Allows the region to be pressable when the skin is locked by the lock touch action

Last Touchscreen Press

Tag Description
%Tl Indicates that the touchscreen is pressed

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 (e.g %Tl(2.5) will give a 2.5s 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 also be used as a conditional, and can be used with conditional viewports for some really neat effects.

This tag can be given a label of a touch region so it only goes true if that region was touched recently. Example:
%?Tl(play_button, 1)<some text>
will display "some text" for one second after the touch region labeled "play_button" is pressed

Current Screen

Tag Description
%cs Current Screen, returns a number for use in conditionals, values below
  1. Menus
  2. WPS
  3. Recording screen
  4. FM Radio screen
  5. Current Playlist screen
  6. Settings menus
  7. File Browser
  8. Database Browser
  9. Plugins Browser
  10. Quickscreen
  11. Pitchscreen
  12. Setting chooser
  13. Playlist Catalog
  14. Plugin
  15. Context Menu
  16. System Menu
  17. Time And Date screen
  18. Bookmark browser
  19. Shortcuts Menu
  20. Track Info screen
  21. USB Screen

You are in the %?cs<Main menu|WPS|Recording screen|FM Radio screen|Current playlist screen|etc..>
%?if(%cs, =, 2)<This is the WPS>

List Title (.sbs only)

Tag Description
%Lt Title text, use it in a conditional so non list screens dont show a title when they shouldn't)
%Li Title icon. Same order as CustomIcons, except icon 0 is "no icon"

Drawing the lists using a skin

The entire list can now be drawn using the skin engine! To do this you need at least one viewport which will be drawn for each item on the screen, and the ui viewport configured (using the %Vi tag). To make this work do the following:
  1. Setup the ui viewport as normal. As many items as can fit in this viewport will be displayed (Titles are not included and need to be drawn in a seperate viewport manually)
  2. Create one or more viewports with a shared label which you want to display for each item. The x/y position is relative to an imaginary box which each item fits in inside the ui viewport.
  3. Tell the skin to draw the lists using the %LB() tag (see below)

Tag Description
%LT[(offset, nowrap)]* Get the current items text, can be used in normal viewports to get the selected items text
%LI[(offset, nowrap)]* Get the current items icon number, can be used in normal viewports to get the selected items icon number
%LN Get the position of the current item in the list (1-based). Useful for displaying numbered lists
%LR Get the row number on which the current item will be drawn (1-based). Can be used to change the style based on where on the screen the item appears.
%LC Get the column number on which the current item will be drawn (1-based). Can be used to change the style based on where on the screen the item appears.
%Lc Use as a conditional to determine if the current item is the selected item
%LB BAR TAG to show the scroll bar, params/options like other bar types. It still needs a bit of work though. Use as a conditional to find out if the bar is actually needed
%Lb(viewport, width, height [,tile]) specify the viewport label to draw for each item and the size of each item. if the last param is 'tile' it will form a grid instead of a list

%LI and %LT accept two optional parameters to get a different line option than the one currently being drawn. The first paramter is an offset from the current item. The second can be the word "nowrap" (without quotes) to make the line not wrap if the offset would go past either end of the list

%?LB<%LB(0,0,10,185, invert)> 
%s%?Lc<%Vg(00ffaa, ff0000, 000000)%Vs(gradient)%>%>%>%ac>zzzzzzz %LT zzzzz%s%?Lc<%ar%<%<%<> 

Conditional Tags


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.

%if() logical comparison tag

Syntax: %?if(tag, operator, operand [,option count])

This lets you do very simple logical comparissons on other tags.
  • tag is the tag to check against
  • operator is the comparison to do, any one of: =, =, >, >=, <, <= (when comparing against a string tag like %ia, only = and != work, and it is NOT case sensitive)
  • operand is either another tag, a number, or text.
  • option count is an optional number to use for the few tags which scale to the amount of options when used as a conditional (i.e %?pv<a|b|c|d> would have 4 options)

example: %?if(%pv, >=, 0)<Warning.. volume clipping|coool...>

That says "If the value from %pv (volume) is greater than or equal to 0 then display the warning line, otherwise the cool line."

%?if(%ia, =, %Ia) <= this artist and next artist are the same.

Note that %?if() evaluates tag enumerations as if they started from 1 (one) instead of 0 (zero). See: FS#12891.

For instance, %?if(%mp, =, 1) returns true when playback is stopped (first value of %mp). If you were to display %mp as is, when playback is stopped, the value 0 (zero) would be displayed, not 1 (one) like in the conditional.

It gets trickier when evaluating arbitrary numbers. When testing for font size, you need to test (value + 1). Here's a counter-intuitive example:
%?if(%ss(0, 2, %St(font), number), =, 15)<font size is 14px|font size is not 14px>
Here we use %St(font) to get the font name, we trim it with %ss() to keep the first two characters (which usually indicate the font size) while setting the type to "number", and we evaluate it. %?if() weirdness will evaluate that number as (number + 1): the above example returns true when the font is "14-Nimbus", even though we tested for the value "15".

-- GuillaumeCocatreZilgien - 22 Aug 2013

%and() and %or logical operators

Syntax: %and(tag, [tag, ...])

This tag allows you to check multiple tags in one conditional instead of doing nested conditionals. %and() will be true if all tags are true, %or() will be true if any tags are true


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

Skin Variables (Touchscreen only)

Tag Description
%vs(name, action, value [,max]) set a variables value, action is set to set the value, inc to increment by value, dec to decrement by value, touch to reset the timeout without changing the value
%vg(name) get a variables value
%vl(name [,timeout] check if the variable changed values in the last 'timeout'

Variables minimum value is 1 and are set to 1 on skin load.

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 %t(5), or seconds and tenths of a second %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:
  %s%t(4)%ia;%s%it;%t(3)%pc %pr   : Display id3 artist for 4 seconds,
                                  Display id3 title for 2 seconds,
                                  Display current and remaining track time
                                  for 3 seconds,

Conditionals can be used with sublines to display a different set and/or number of sublines on the line depending on the evaluation of the conditional.

Example subline with conditionals:

The format above will do two different things depending if ID3 tags are present. If the ID3 artist and title are present :

Display ID3 title for 8 seconds,

Display ID3 artist for 3 seconds,


If the ID3 artist and title are not present :

Display the filename continuously.

Note that by using a subline display time of 0 in one branch of a conditional, a subline can be skipped (not displayed) when that condition is met.

Bar Tags

Some tags can be used to display a bar which draws according to the value of the tag. To use these tags like a bar you need to use the following params (%XX should be replaced with the actual tag)

%XX(x, y, width, height, filename, [options])

The coordinates must be within the viewport's boundaries.

param Description
x X co-ordinate (viewport relative) to start displaying this bar
y Y co-ordinate (viewport relative) to start displaying this bar (- to have appear on the line of the tag, as if it was a text tag)
width width of this bar (- for the full viewport width)
height height of this bar (- for font height for horizontal bars, viewport height for vertical)
options Any or all of the possible options (a comma separated list) in the next table

option name description
horizontal Force the bar to be drawn horizontally
vertical Force the bar to be drawn vertically
invert Invert the draw direction (so right to left or top to bottom)
slider Draw an image at the bar's "value/position" over the top of the bar. The centre of the slider indicates current position. The next param must be the loaded image's label.
image Specify the image to use to draw the bar. The next param must be the filename of the image or the loaded image's label. If this option is not used a default image will be drawn instead.
backdrop Specify an image to draw as the bar's backdrop. The next param must be the loaded image's label.
nofill Don't draw the fill bar, only the empty image (use with slider for the desired effect)
noborder Don't draw the border for image-less bars, instead maximize the filling over the specified area. This does not work for bars which specify an image.
nobar Don't draw the bar at all (for use with slider)
notouch Don't create a touchregion for this bar automatically

To maintain backward compatibility a filename can be given as the first option instead of using the 'image, ' tuple.

Other Tags


Tag Description
%ss(start, length, tag) Get a substring of another tags value.

Use - for the length to get the full string starting at the 'start' index (0 being the first character).

It is possible to use %ss() to determine the length of a string in a conditional:
%?if(%ss(0, 20, %it), =, %it)<track title length is 20 characters or less|track title length is over 20 characters>
The above trims the track title to 20 characters, and then compares that string to the full track title. If the values are different, it means that the track title is longer than 20 characters.

-- GuillaumeCocatreZilgien - 22 Aug 2013

Special characters

  %%  : Display a '%'
  %<  : Display a '<'
  %|  : Display a '|'
  %>  : Display a '>'
  %;  : Display a ';'
  %#  : Display a '#'
  %(  : Display a '('
  %)  : Display a ')'
  %,  : Display a ','

Example Files

Example WPS for the iPod 5g

Download: Example WPS for

Example WPS for the Gigabeat F

Download: Example WPS for

More examples can be found in user submitted WpsGallery


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.

r249 - 14 Oct 2021 - 02:03:37 - WilliamWilgus

Parents: DocsIndex
Copyright © by the contributing authors.