B WPS Tags

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
%id	Album Name
%ig	Genre Name
%in	Track Number
%it	Track Title
%iv	ID3 version (1.0, 1.1, 2.2, 2.3, 2.4, or empty if not an ID3 tag)
%iy	Year

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), produce the information for the next song to be played.

B.3. 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.4. 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)
%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.5. Playlist/Song Info

Tag	Description

%pb	Progress Bar
	This will replace the entire line with a progress bar.
	You can set the height, position and width of the progressbar (in pixels): %pb\|height\|leftpos\|rightpos\|toppos\|
%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.

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

B.7. Sound (DSP) settings

Tag	Description

%Sp	Current playback pitch
%xf	Crossfade setting, in the order: Off, Shuffle, 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.8. Virtual LED

Tag	Description

%lh	“h” if the hard disk is accessed

B.9. Repeat Mode

Tag	Description

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

B.10. Playback Mode Tags

Tag	Description

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

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

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

B.13. 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.
%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 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.

B.14. 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:

B.15. Alignment

Tag	Description

%al	Align the text left
%ac	Center the text
%ar	Align the text right

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.

B.16. 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.17. 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.18. Time and Date

Tag	Description

%cd	Day of month
%ce	Zero padded day of month
%cH	Zero padded hour from 00 to 23 (24 hour format)
%ck	Hour from 0 to 23 (24 hour format)
%cI	Zero padded hour from 12 to 12 (am/pm format)
%cl	Hour from 12 to 12 (am/pm format)
%cm	Month
%cM	Minutes
%cS	Seconds
%cy	2-digit year
%cY	4-digit year
%cP	Capital AM/PM
%cp	Lowercase am/pm
%ca	Weekday name
%cb	Month name
%cu	Day of week from 1 to 7, 1 is Monday
%cw	Day of week from 0 to 6, 0 is Sunday
%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 (like the Video), or alternate information on those that do not .

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

B. WPS Tags

B.1. Status Bar