Custom WPS Display - File Format Specifications

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 as well.
• After editing the .wps or .sbs 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.

Tags

Viewports

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 for a viewport declaration is as follows: %V(x,y,[width],[height],[font]) Where: x is the x pixel, y is the y pixel (0,0 being top left). width is the pixel width of the viewport, using '-' means the full width. height is height of viewport ('-' is full height). font is the font number. 0 is the built in font, 1 is the user font, 2-9 are skin loaded fonts (see below)

Notes:

• 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 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 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 width and height values may also be negative which means almost the same as above...

Conditional Viewports

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

Viewport Colours

Fonts

Status Bar

It can also be used for the Custom Status Bar

ID3 Tag Info

Next Track 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

Real Time Clock

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

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

%?pS7<in first 7s of track|rest of track>

%?pE<in last 10s of track|rest of track>

Playlist viewer

This allows you to display some information for the upcoming tracks in the playlist (instead of just the next track).

• 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

Runtime Database and Replaygain

Hold Switches

Example: %?mh<Locked|Unlocked>

Virtual LED

Repeat Mode

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

Playback Mode

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.

Crossfade

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

Images

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)

%X - Load a background image

%x - Load and display an image

• 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

• 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() 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 - Load an image for display with %xd

1. The simplest is when the image is not a bitmap strip. %xd() will display that image in the current viewport at the relative pixel coordinates.
2. If the image is a bitmap strip:
   • %xd(, [, offset])
     • is the label of the image to draw
     • 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() is the final form: (only usable if the image label is one letter)
     • 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

Notes:

• 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

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

Bitmap Strips

%xl(M,volume.bmp,134,153,10)
%?pv<%xd(Ma)|%xd(Mb)|%xd(Mc)|%xd(Md)|%xd(Me)|%xd(Mf)|%xd(Mg)|%xd(Mh)|%xd(Mi)|%xd(Mj)>

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

Album Art

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

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

FM Radio tokens

Alignment

RTL Language alignment support

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.

Scrolling

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

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

Example: Can be used as a simple tag %St(skip length) or with conditionals %?St(eq enabled|<Equalizer is enabled|Equalizer is disabled>

Touchscreen areas (WPS only)

If action starts with & the area must be held to happen.

Action is one of:

• 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

Last Touchscreen Press (WPS only)

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

Current Screen

Example:

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

List Title (.sbs only)

Conditional Tags

If/else

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

%if(<tag>, <operator>, <operand> [,option count]) which lets you do very simple logical comparissons on other tags.
<tag> is the tag to check against
<operator> is the comparisson to do, any one of... =, !=, >, >=, <, <=    (when comparring against a string tag like %ia only = and != work, and it is done NOT case sensitive)
<operand> is either another tag, a number, or text.
[option count] is an optinal 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)<same artist>   <= this artist and next artist are the same.

Enumerations

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

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,
                                  repeat...

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:

  %?it<%t(8)%s%it|%s%fn>;%?ia<%t(3)%s%ia|%t(0)>

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,

repeat...

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

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

Other Tags

  %%  : 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 ipod5g.zip

Example WPS for the Gigabeat F

More examples can be found in user submitted WpsGallery

Tools

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

OPTIONS:
        -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 ./buildall.sh script - this will create many versions of checkwps, one for each target device.

Vim

In the Vim text editor, a script here provides syntax highlighting for WPS files.