docs/CUSTOM_WPS_FORMAT

Custom WPS Display
wps.config File Format Specifications


Description / General Info
--------------------------
* The Custom WPS Display is used on the Rockbox Player ONLY, as a means 
  to customize the WPS to the user's likings.
* Plans to implement this feature into the recorder are in progress.
* The first line of the 2 line display is the customized line (scrolling).
* The second line is always the time display. (Elapsed & Total Time).
* The second line is not able to be customized.
* Any CR's, LF's, or CR/LF's (Commonly known as Newline/Return/Enter) in 
  the wps.config file will be treated as spaces. IE: Don't use them.
* After editing the wps.config file, you may need to reboot your Rockbox.
* All tags except for %%, %?, and %: contain 3 characters (%xx). Remember
  to type the tags correctly, or you will get unexpected output, or even
  possibly no output at all.
* All characters not preceded by % are displayed as typed.


File Location
-------------
The configuration file must be located in the root folder of the
device and must be named wps.config (lowercase)


Tags
----
ID3 Info Tags:
  %it : ID3 Title
  %ia : ID3 Artist
  %in : ID3 Track Number
  %id : ID3 Album
File Info Tags:
  %fc : Conditional Title/Filename
        Displays "Artist - Title" *or*
        Displays Filename if no ID3 Artist/Title
  %fd : Conditional Title/Filename
        Displays "Title - Artist" *or*
        Displays Filename if no ID3 Artist/Title
  %fb : File Bitrate
  %ff : File Frequency
  %fp : File Path
  %fn : File Name
  %fs : File Size (In Kilobytes)
Playlist/Song Info Tags:
  %pp : Playlist Position
  %pe : Playlist Total Entries
  %pc : Current Time In Song
  %pt : Total Track Time
Other Tags:
  %% : Displays a %
Conditional ID3/File Tags (If/Else block):
  The following two tags are completely optional, and meant only for those
    that wish to go crazy with customization. It lets you specify what to
    do when it finds an ID3 tag, and also when it doesn't find one. It can
    be placed anywhere within the wps.config file.  
  The first condition of the If/Else block is what to do when it DOES find
    valid ID3 tags. The second condition is what to do when there are no
    valid ID3 tags available.
  %? : Start/End an If/Else block
  %: : Seperator between If and Else
  Example:
    To display "Title - Artist" if there is ID3 available, or "Filename"
    if there is no ID3, the following string would be used:
      %?%it - %ia%:%fn%?
    Yes, you are not going crazy (although I may be)... This *IS* more
    confusing then Perl :-)


Example wps.config File (Without If/Else)
-----------------------
%pp/%pe: %fc * %fsKB


Example Output
--------------
ID3 Title:              None
ID3 Artist:             None
Playlist Position:      5
Playlist Total Entries: 10
Filename:               My Song.mp3
File Size:              3500
Elapsed Track Time:     2:23
Total Track Time:       3:01
The output of this on the player would be:
 ---------------------------
| 5/10: My Song.mp3 * 3500KB|
| 2:23/3:01                 |
 ---------------------------
Of course, the whole first line wouldn't fit, so it scrolls it.