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

Repeat mode tags:
  %mf : repeat off, returns f
  %ma : repeat all, returns a
  %mo : repeat one, returns o
  %ms : repeat shuffle, returns s

Playback mode tags:
  %mp : play, returns p
  %mu : pause, returns u
  %mw : fastforward, returns w
  %mb : fastbackward, returns b

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.

Alignment Tags:
  %al : Text is left aligned
  %ac : Text is center aligned
  %ar : Text is right aligned

All alignment tags may be present in on line, but the need to be in the order
left - center - right. If the aligned texts overlap, they are merged.

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