d2b625f818
Adds the ability to define 2 or more alternating lines on each line of the WPS and the ability to control how long each alternating line is displayed before switching to the next one. Backward compatible with the current WPS specification language (existing WPS files will display the same as they do now). His HTML version of the docs is found at: http://home.pacbell.net/csath/rockbox/details.html git-svn-id: svn://svn.rockbox.org/rockbox/trunk@4229 a1c6a512-1295-4272-9138-f99709370657
171 lines
6 KiB
Text
171 lines
6 KiB
Text
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, and 10 lines for the Recorder.
|
|
* All characters not preceded by % are displayed as typed.
|
|
* A line beginning with # is a comment
|
|
|
|
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.
|
|
|
|
Tags
|
|
----
|
|
ID3 Info Tags:
|
|
%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:
|
|
%bl : Show numeric battery level in percent
|
|
%bt : Show estimated battery time left
|
|
|
|
File Info Tags:
|
|
%fb : File Bitrate (in kbps)
|
|
%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 Tags:
|
|
%pb : Progress Bar
|
|
Player: This will display a 1 character "cup" that empties as the
|
|
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
|
|
|
|
Conditional Tags (If/Else block):
|
|
%?xx<|> : Conditional: if the tag specified by "xx" has a value, the
|
|
text between the "<" and the "|" is displayed, else the text
|
|
between the "|" and the ">" is displayed.
|
|
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.
|
|
|
|
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,
|
|
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<%t8%s%it|%s%fn>;%?ia<%t3%s%ia|%t0>
|
|
|
|
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.
|
|
|
|
-----------
|
|
|
|
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.
|
|
|
|
Example File
|
|
------------
|
|
%s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>
|
|
%pb%pc/%pt
|
|
|
|
That is, "tracknum - title [artist, album]", where most fields are only
|
|
displayed if available. Could also be rendered as "filename" or
|
|
"tracknum - title [artist]".
|
|
|
|
Default
|
|
-------
|
|
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>
|
|
%pc%?ps<*|/>%pt
|
|
|
|
and for recorder:
|
|
|
|
# Default WPS for Recorder
|
|
%s%?it<%?in<%in. |>%it|%fn>
|
|
%s%?ia<%ia|%?d2<%d2|(root)>>
|
|
%s%?id<%id|%?d1<%d1|(root)>> %?iy<(%iy)|>
|
|
|
|
%pc/%pt [%pp:%pe]
|
|
%fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)>
|
|
%pb
|
|
%pm
|