docs/CUSTOM_WPS_FORMAT

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.
* The line that has the time displayed on it MUST NOT be the line that
  is scrolled, or the time will not be updated.
* All characters not preceded by % are displayed as typed.

File Location
-------------
The default configuration file must be located in the /.rockbox folder
of the evice and must be named default.wps (lowercase). Any other Custom
WPS files may be located anywhere on the drive. The only restriction
is that they must end in .wps

Tags
----
ID3 Info Tags:
  %ia : ID3 Artist
  %it : ID3 Track Title
  %in : ID3 Track Number
  %id : ID3 Album Name

File Info Tags:
  %fb : File Bitrate (in kbps)
  %ff : File Frequency (in Hz)
  %fp : File Path
  %fn : File Name (without extension)
  %fm : File Name
  %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.
  %pm : Peak Meter (Recorder only)
        The entire line is used as volume peak meter.
  %pp : Playlist Position
  %pe : Total Number of Playlist Entries
  %pc : Current Time In Song
  %pr : Remaining Time In Song
  %pt : Total Track Time

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.

Other Tags:
  %%  : 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 conditional 
        below). Only the first line with a %s will actually scroll.
        %s is ignored if combined with %pb, %pc or %pr on the same
        line (the result wouldn't be good anyway).

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 don't use a default.wps file, you get the hardcoded wps layout.
The default WPS screen is for player:

%s%pp/%pe: %?ia<%ia - >%?it<%it|%fm>
%pc/%pt

and for recorder:

%s%fp
%it
%id
%ia
%fb kbit %fv
Time: %pc / %pt
%pb