caec53c0d1
whitespace git-svn-id: svn://svn.rockbox.org/rockbox/trunk@4643 a1c6a512-1295-4272-9138-f99709370657
184 lines
6.6 KiB
Text
184 lines
6.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.
|
|
|
|
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,
|
|
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
|