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

Search | Go
Wiki > Main > DocsIndex > CustomWPS (r107)

Custom WPS Display - File Format Specifications

Description / General Info

  • The Custom WPS Display is used as a means to customize the while playing screen to the user's likings.
  • After editing the .wps 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. 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.

The syntax for a viewport declaration is as follows:

LCD type Viewport declaration Notes
Mono %V|x|y|[width]|[height]|[font]| Font is a number - 0 is the built-in system font, 1 is the user-selected font
Greyscale %V|x|y|[width]|[height]|[font]|[fgshade]|[bgshade]| fgshade and bgshade are numbers in the range 0 (= black) to 3 (= white)
Colour %V|x|y|[width]|[height]|[font]|[fgcolor]|[bgcolor]| fgcolor and bgcolor are 6-digit RGB888 colours - e.g. FF00FF

  • 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.
  • The maximum number of viewports per screen is 16.
  • Only the x and y values need to be specified. The rest can be left blank if you want to use their default values (but it still needs the correct amount of | 's with -'s in the blank fields, i.e. %V|0|0|-|-|1|-|-|).
    • default width/height is the remainig 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

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

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

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)
%bv Show the battery level in volts
%bt Show estimated battery time left
%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
%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: "%?ca<%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 firmware/export/id3.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
%d1 First directory from end of file path.
%d2 Second directory from end of file path.
%d3 Third directory from end of file path.

Example for the the %dN commands: If the path is "/Rock/Kent/Isola/11 - 747.mp3", %d1 is "Isola", %d2 is "Kent"... You get the picture.

Playlist/Song Info

Tag Description
%pb Progress Bar
Archos Player/Studio: This will display a 1 character "cup" that empties as the time progresses.
Others: This will replace the entire line with a progress bar.
Optionally, you can set the height, position (both x and y) and width of the progressbar (in pixels): %pb|height|leftpos|rightpos|toppos|
%pf Player: 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
%pe Total Number of Playlist Entries
%pm Peak Meter The entire line is used as volume peak meter.
%pn Playlist Name (Without path or extension)
%pp Playlist Position
%pr Remaining Time In Song
%ps Shuffle. Shows 's' if shuffle mode is enabled.
%pt Total Track Time
%pv Current volume in decibels (dB). Can also be used in a conditional: %?pv<Mute|...|0 dB|Above 0 dB>
%Sp Current playback pitch

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, 0-4, in the order: Stop, Play, Pause, Fast Forward, Rewind

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

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. Foreseen future changes in WPS's features will extend the use of the "stop" status.


Tag Description
%xf Crossfade type, 0-4, in the order : Off, Shuffle, Track Skip, Shuffle and Track Skip, Always

Example: %?xf<Off|Shuffle|Track Skip|Shuffle & Track Skip|Always>


Tag Description
%X|filename.bmp| Load and set a backdrop image for the WPS. This image must be exactly the same size as your LCD. If no image is selected, the menu background will be be shown.
%P|filename.bmp| Load a Progress bar image for the WPS. Use %pb tag to show the progress bar
%x|n|filename|x|y| Load and always show the image

n = image ID (a-z and A-Z)
filename = filename (see notes below for instructions on where to place the file)
x = x coordinate
y = y coordinate.
%xl|n|filename|x|y|[nimages|] Preload an image for later display (useful for when your images are displayed conditionally)

n = image ID (a-z and A-Z)
filename = filename (see notes below for instructions on where to place the file)
x = x coordinate
y = y coordinate
nimages = number of images (tiled vertically, of the same height) contained in the bitmap.
%xdn[i] Display a preloaded image

n = image ID (a-z and A-Z)
i = (only for bitmap strips) sub-image ID (a-z and A-Z)


  • The images must be in a Rockbox compatible format (see table below for model specific BMP compatibility).

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

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

  • The image tag must be on its own line.

  • The ID is case sensitive, giving 52 possible IDs for images (a to z is 26, and then capital A to capital Z is 26 more).

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

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

Example 1:

This example loads and displays a background image, and preloads four other images at the same x and y position. Which image to display is determined by the %mm tag (the repeat mode).

Example 1a:

Since the filecount of images loaded can affect the WPS's loading time, it is in general recommended to apply the bitmap strips concept (a single image containing various images of the same dimensions, tiled vertically) wherever it's possible (in changing images placed in the same position), since it reduces the number of total bmp files to be loaded. Applying this to Example 1, former images b, c, d and e, used for showing the "repeat" status, would be placed vertically (equally sized) into a new single bmp, to conform image R (repeat.bmp), containing the four subimages (sub indexed Ra, Rb, Rc, Rd):

Example 2:

In this example using the "display image 'a'" tag (%xda) inside the viewport means that the bmp will be displayed at position x=78 and y=25 of the screen. (The preload coordinates (x=0, y=0) are relative to the viewport position (x=78, y=25).)

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 128x64 1-bit
iriver H10 (5/6Go) 128x128 1-bit, 24-bit no LCD remote n/a
iriver H10 (20Go) 160x128 1-bit, 24-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 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 ? ?

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| Define the picture settings. More details
%C Display the album art bitmap. More details


Tag Description
%m|x| Specify left margin


Tag Description
%al Text is left aligned
%ac Text is center aligned
%ar Text is right aligned

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.

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.

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.


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.

Alternating Sublines

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

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

Subline related special characters and tags:
   ;  : Split items on a line into separate sublines
  %t  : Set the subline display time. The '%t' is followed by either integer
        seconds (%t5), or seconds and tenths of a second (%t3.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%t4%ia;%s%it;%t3%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.

Other Tags

  %%  : 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 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 "archos\.rockbox\wps". The directory "archos\" represents the root of your device. Put some music files to "archos\" 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.

r107 - 18 Jun 2008 - 12:14:23 - MarcGuay

Parents: DocsIndex
Copyright © by the contributing authors.