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

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

Custom WPS Display - File Format Specifications

Description / General Info

  • The Custom WPS Display is used on both the Rockbox Player and Recorder, as a means to customize the WPS to the user's likings.
  • After editing the .wps file, "play" it to make it take effect.
  • The file may be 2 lines long for the Player, 13 lines for the Recorder and 26 lines for the iRiver (with native Rockbox font of course).
  • All characters not preceded by % are displayed as typed.
  • A line beginning with # is a comment
  • Maximum file size used is 1600 bytes for bitmap units and 400 bytes for charcell units. If you have a bigger WPS file, only the first part of it will be loaded and used.

File Location

Custom WPS files may be located anywhere on the drive. 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.

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.


ID3 Info

Tag Description
%ia ID3 Artist
%ic ID3 Composer
%id ID3 Album Name
%ig ID3 Genre Name
%in ID3 Track Number
%it ID3 Track Title
%iv ID3 Version (1.0, 1.1, 2.2, 2.3, 2.4 or empty if no id3 tag)
%iy ID3 Year

Battery Info

Tag Description
%bl Show numeric battery level in percent. Can also be used in a conditional: %?bl<0|1|2|3|4>
%bt Show estimated battery time left
%bp "p" if the charger is connected

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|wav|vorbis|flac|mpc|a52|wavpack|unknown>
%ff File Frequency (in Hz)
%fm File Name
%fn File Name (without extension)
%fp File Path
%fs File Size (In Kilobytes)
%fv "(vbr)" 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
Player: This will display a 1 character "cup" that empties as the time progresses.
Recorder: This will replace the entire line with a progress bar.
%pf Player: Full-line progress bar + time display
%pc Current Time In Song
%pe Total Number of Playlist Entries
%pm Peak Meter (Recorder only) 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. Can also be used in a conditional: %?pv<0|1|2|3|4|5|6|7|8|9>

Runtime Database

Tag Description
%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>

Hold switches (iriver)

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

Repeat mode:

Tag Description
%mm Repeat mode, 0-4, in the order: Off, All, One, Shuffle, A-B (Archos only so far)

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

Playback mode tags:

Tag Description
%mp Play status, 0-4, in the order: Stop, Play, Pause, Fast forward, Rewind

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


Tag Description
%x|n|filename|x|y| Load and display an image

n = image ID (a-z and A-Z)
filename = filename (relative to /.rockbox/ and including .bmp)
x = x coordinate
y = y coordinate.
%xl|n|filename|x|y| Preload an image for later display

n = image ID (a-z and A-Z)
filename = filename (relative to /.rockbox/ and including .bmp)
x = x coordinate
y = y coordinate.
%xdn Display a preloaded image

n = image ID (a-z and A-Z)

Example: image /.rockbox/bg.bmp with ID "a" at 37, 109 would be: %x|a|bg.bmp|37|109|

Note: The images must be in a rockbox compatible format (1 bit per pixel BMP)

Note: The image tag must be on its own line

Note: The ID is case sensitive, giving 52 different ID's


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.

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.

Next Song Info

You can display information about the next song - the song that is about to play after the one currently playing (unless you change the plan).

If you use the uppercase versions of the three tags: F, I and D, they will instead refer to the next song instead of the current one. Example: %Ig is the genre name used in the next song and %Ff is the mp3 frequency.

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

Alternating Sublines

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

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

Subline related special characters and tags:
   ;  : Split items on a line into separate sublines
  %t  : Set the subline display time. The '%t' is followed by either integer
        seconds (%t5), or seconds and tenths of a second (%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 ';'
  %s  : Indicate that the line should scroll. Can occur anywhere in
        a line (given that the text is displayed; see conditionals
        above). You can specify up to 10 scrolling lines.
        Scrolling lines can not contain dynamic content such as timers,
        peak meters or progress bars.

Using images

You can have as many as 52 images in your WPS. There are two ways of displaying images:

  1. Load and always show the image, using the %x tag
  2. Preload the image with %xl and show it with %xd. This way you can have your images displayed conditionally.


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 File

%s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>

That is, "tracknum - title [artist, album]", where most fields are only displayed if available. Could also be rendered as "filename" or "tracknum - title [artist]".

More examples can be found in user submitted WpsGallery


If you haven't selected a .wps file in the .rockbox directory, you get the hardcoded wps layout. The default WPS screen is for player:
# Default WPS for Player
%s%pp/%pe: %?it<%it|%fn> - %?ia<%ia|%d2> - %?id<%id|%d1>
and for recorder:
# Default WPS for Recorder
%s%?it<%?in<%in. |>%it|%fn>
%s%?id<%id|%?d1<%d1|(root)>> %?iy<(%iy)|>

%fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)>


The EZWPS Visual Basic application can help beginners on Windows to create a WPS file.
r7 - 03 Oct 2005 - 21:56:23 - TomasSalfischberger

Parents: DocsIndex
Copyright © by the contributing authors.