B WPS Tags

B.1 Status Bar

Tag	Description

%we	Display Status Bar
%wd	Hide Status Bar

These tags override the player setting for the display of the status bar. They must be noted on their own line (which will not be shown in the WPS).

B.2 Information from the track tags

Tag	Description

%ia	Artist
%ic	Composer
%iA	Album Artist
%id	Album Name
%iG	Grouping
%ig	Genre Name
%in	Track Number
%it	Track Title
%iC	Comment
%iv	ID3 version (1.0, 1.1, 2.2, 2.3, 2.4, or empty if not an ID3 tag)
%iy	Year
%ik	Disc Number

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

These tags, when written with a capital “I” (e.g. %Ia or %Ic), show the information for the next song to be played.

B.3 Viewports

Tag	Description

%V\|x\|y\|[width]\|[height]\|[font]\|[fgshade]\|[bgshade]\|	(see section 12.2.2)
%Vd’identifier’	Display the ’identifier’ viewport. E.g. %?C<%C%Vda\|%Vdb> will show viewport ’a’ if album art is found, and ’b’ if it isn’t.

B.4 Power Related Information

Tag	Description

%bl	Numeric battery level in percents
	Can also be used in a conditional: %?bl<-1\|0\|1\|2\|…\|N>, where the value −1 is used when the battery level isn’t known (it usually is)
%bv	The battery level in volts
%bt	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	Remaining time of the sleep timer (if it is set)

B.5 Information about the file

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\|ogg\|flac\|mpc\|a52\|wavpack\|alac\|aac\|shn\|sid\|adx\|nsf\|speex\|spc\|ape\|wma\|mod\|sap\|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, MOD, SAP.
%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 empty string if constant bit rate
%d1	First directory from the end of the file path
%d2	Second directory from the end of the file path
%d3	Third directory from the end of the file path

Example for the %dN commands: If the path is “/Rock/Kent/Isola/11 - 747.mp3”, %d1 is “Isola”, %d2 is “Kent” and %d3 is “Rock”.

These tags, when written with the first letter capitalized (e.g. %Fn or %D2), produce the information for the next file to be played.

B.6 Playlist/Song Info

Tag	Description

%pb	Progress Bar
	This will replace the entire line with a progress bar.
	You can set the position, width and height of the progressbar (in pixels) and load a custom image for it: %pb\|image.bmp\|x\|y\|width\|height\|
%px	Percentage Played In Song
%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	“s” if shuffle mode is enabled
%pt	Total Track Time
%pv	Current volume (in dB). Can also be used in a conditional:
	%?pv<0\|1\|2\|…\|N>
	0 is used for mute, the last option is used for values greater than zero.
%Sp	Current Playback Pitch

B.7 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>
%ra	Autoscore for the song

B.8 Sound (DSP) settings

Tag	Description

%Sp	Current playback pitch
%xf	Crossfade setting, in the order: Off, Auto Skip, Man Skip, Shuffle, Shuffle and Man Skip, Always
%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>

B.9 Hold Switches

Tag	Description

%mh	“h” if the main unit hold switch is on
%mr	“r” if the remote hold switch is on

B.10 Virtual LED

Tag	Description

%lh	“h” if the hard disk is accessed

B.11 Repeat Mode

Tag	Description

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

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

B.12 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>

B.13 Current Screen

Tag	Description

%cs	The current screen, 1-5, in the order: Menus, WPS, Recording screen, FM Radio screen, Current Playlist screen

The tag can also be used as the switch in a conditional tag. For players without some capabilities (e.g. having no FM radio) some values will be never yielded.

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

B.14 Changing Volume

Tag	Description

%mv[t]	“v” if the volume is being changed

The tag produces the letter “v” while the volume is being changed and some amount of time after that, i.e. after the volume button has been released. The optional parameter t specifies that amount of time, in seconds. If it is not specified, 1 second is assumed.

The tag can be used as the switch in a conditional tag to display different things depending on whether the volume is being changed. It can produce neat effects when used with conditional viewports.

Example: %?mv2.5<Volume changing|%pv>

The example above will display the text “Volume changing” if the volume is being changed and 2.5 secs after the volume button has been released. After that, it will display the volume value.

B.15 Settings

Tag	Description

%St\|<setting name>\|	The value of the Rockbox setting with the specified name. See section D for the list of the available settings.

Examples:

1.: As a simple tag: %St|skip length|
2.: As a conditional: %?St|eq enabled|<Eq is enabled|Eq is disabled>

B.16 Images

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.
%x\|n\|filename\|x\|y\|	Load and display an image
	n: image ID (a-z and A-Z) for later referencing in %xd
	filename: file name relative to /.rockbox/ and including “.bmp”
	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) for later referencing in %xd
	filename: file name relative to /.rockbox/ and including “.bmp”
	x: x coordinate
	y: y coordinate
	nimages: (optional) number of sub-images (tiled vertically, of the same height) contained in the bitmap. Default is 1.
%xdn[i]	Display a preloaded image
	n: image ID (a-z and A-Z) as it was specified in %x or %xl
	i: (optional) number of the sub-image to display (a-z for 1-26 and A-Z for 27-52). By default the first (i.e. top most) sub-image will be used.

Examples:

1.: Load and display the image /.rockbox/bg.bmp with ID “a” at 37, 109:
%x|a|bg.bmp|37|109|
2.: Load a bitmap strip containing 5 volume icon images (all the same size) with image ID “M”, and then reference the individual sub-images in a conditional:
%xl|M|volume.bmp|134|153|5|
%?pv<%xdMa|%xdMb|%xdMc|%xdMd|%xdMe>

Note:

The images must be in BMP format
The image tag must be on its own line
The ID is case sensitive, giving 52 different ID’s
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.

B.17 Album Art

Tag	Description

%Cl\|x\|y\|[[l\|c\|r]maxwidth]\|[[t\|c\|b]maxheight]\|	Define the settings for albumart
	x: x coordinate
	y: y coordinate
	maxwidth: Maximum height
	maxheight: Maximum width
%C	Display the album art as configured. This tag can also be used as a conditional.

The picture will be rescaled, preserving aspect ratio to fit the given maxwidth and maxheight. If the aspect ratio doesn’t match the configured values, the picture will be placed according to the flags to the maxwidth and maxheight parameters:

maxwidth:
l.
Align left
c.
Align centre (default)
r.
Align right
maxheight:
t.
Align top
c.
Align centre (default)
b.
Align bottom

Examples:

1.: Load albumart at position 20,40 and display it without resizing:
%Cl|20|40|||
2.: Load albumart at position 0,20 and resize it to be at most 100x100 pixels. If the image isn’t square, align it to the bottom-right corner:
%CL|0|20|r100|b100|

B.18 Alignment

Tag	Description

%al	Align the text left
%aL	Align the text left, or to the right if RTL language is in use
%ac	Centre the text
%ar	Align the text right
%aR	Align the text right, or to the left if RTL language is in use

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

B.19 Conditional Tags

Tag	Description

%?xx<true\|false>	If / Else: Evaluate for true or false case
%?xx<alt1\|alt2\|alt3\|…\|else>	Enumerations: Evaluate for first / second / third / …/ last condition

B.20 Subline Tags

Tag	Description

%t<time>	Set the subline display cycle time (%t5 or %t3.4 formats)
;	Split items on a line into separate sublines

Allows grouping of several items (sublines) onto one line, with the display cycling round the defined sublines. See section 12.2.2 for details.

B.21 Time and Date

Tag	Description

%cc	Check for presence of the clock hardware

The %cc tag returns “c” if the necessary hardware is present and can also be used as a conditional. This can be very useful for designing a WPS that works on multiple targets, some with and some without a clock. By using this tag as a conditional it is possible to display current date and time on those targets that support this , or alternate information on those that do not (like the H100).

Example: %?cc<%cH:%cM|No clock detected>

B.22 Other Tags

Tag	Description

%%	The character ‘%’
%<	The character ‘<’
%\|	The character ‘\|’
%>	The character ‘>’
%;	The character ‘;’
%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 ten scrolling lines. Scrolling lines can not contain dynamic content such as timers, peak meters or progress bars.

[next] [prev] [prev-tail] [front] [up]

B. WPS Tags

B.1 Status Bar

B.2 Information from the track tags

B.3 Viewports

B.4 Power Related Information

B.5 Information about the file

B.6 Playlist/Song Info

B.7 Runtime Database

B.8 Sound (DSP) settings

B.9 Hold Switches

B.10 Virtual LED

B.11 Repeat Mode

B.12 Playback Mode

B.13 Current Screen

B.14 Changing Volume

B.15 Settings

B.16 Images

B.17 Album Art

B.18 Alignment

B.19 Conditional Tags

B.20 Subline Tags

B.21 Time and Date

B.22 Other Tags