docs/CUSTOM_WPS_FORMAT

   1 Custom WPS Display
   2 File Format Specifications
   3
   4 Description / General Info
   5 --------------------------
   6 * The Custom WPS Display is used on both the Rockbox Player and Recorder,
   7   as a means to customize the WPS to the user's likings.
   8 * After editing the .wps file, "play" it to make it take effect.
   9 * The file may be 2 lines long for the Player, and 10 lines for the Recorder.
  10 * All characters not preceded by % are displayed as typed.
  11 * A line beginning with # is a comment
  12
  13 File Location
  14 -------------
  15 Custom WPS files may be located anywhere on the drive. The only restriction is
  16 that they must end in .wps. When you PLAY a .wps file, it'll be used for the
  17 future WPS screens. If the "played" wps file is located in the /.rockbox
  18 folder, it'll be remembered and used for subsequent restarts. Filenames in the
  19 /.rockbox folder must be no more than 24 characters long.
  20
  21 Tags
  22 ----
  23 ID3 Info Tags:
  24   %ia : ID3 Artist
  25   %ic : ID3 Composer
  26   %id : ID3 Album Name
  27   %ig : ID3 Genre Name
  28   %in : ID3 Track Number
  29   %it : ID3 Track Title
  30   %iv : ID3 Version (1.0, 1.1, 2.2, 2.3, 2.4 or empty if no id3 tag)
  31   %iy : ID3 Year
  32
  33
  34 Battery Info:
  35   %bl : Show numeric battery level in percent
  36   %bt : Show estimated battery time left
  37
  38 File Info Tags:
  39   %fb : File Bitrate (in kbps)
  40   %ff : File Frequency (in Hz)
  41   %fm : File Name
  42   %fn : File Name (without extension)
  43   %fp : File Path
  44   %fs : File Size (In Kilobytes)
  45   %fv : "(vbr)" if variable bit rate or "" if constant bit rate
  46   %d1 : First directory from end of file path.
  47   %d2 : Second directory from end of file path.
  48   %d3 : Third directory from end of file path.
  49
  50 Example for the the %dN commands: If the path is "/Rock/Kent/Isola/11 -
  51 747.mp3", %d1 is "Isola", %d2 is "Kent"... You get the picture.
  52
  53 Playlist/Song Info Tags:
  54   %pb : Progress Bar
  55         Player: This will display a 1 character "cup" that empties as the
  56                 progresses.
  57         Recorder: This will replace the entire line with a progress bar.
  58   %pf : Player: Full-line progress bar + time display
  59   %pc : Current Time In Song
  60   %pe : Total Number of Playlist Entries
  61   %pm : Peak Meter (Recorder only)
  62         The entire line is used as volume peak meter.
  63   %pn : Playlist Name (Without path or extension)
  64   %pp : Playlist Position
  65   %pr : Remaining Time In Song
  66   %ps : Shuffle. Shows 's' if shuffle mode is enabled.
  67   %pt : Total Track Time
  68   %pv : Current volume
  69
  70 Conditional Tags (If/Else block):
  71   %?xx<|> : Conditional: if the tag specified by "xx" has a value, the
  72             text between the "<" and the "|" is displayed, else the text
  73             between the "|" and the ">" is displayed.
  74             The else part is optional, so the "|" does not have to be
  75             specified if no else part is desired. The conditionals nest,
  76             so the text in the if and else part can contain all %
  77             commands, including conditionals.
  78
  79 Next Song Info
  80 --------------
  81 You can display information about the next song - the song that is about to
  82 play after the one currently playing (unless you change the plan).
  83
  84 If you use the uppercase versions of the three tags: F, I and D, they will
  85 instead refer to the next song instead of the current one. Example: %Ig is
  86 the genre name used in the next song and %Ff is the mp3 frequency.
  87
  88 Take note that the next song information WILL NOT be available at all times,
  89 but will most likely be available at the end of a song. We suggest you use the
  90 conditional display tag a lot when displaying information about the next song!
  91
  92 Alternating Sublines
  93 --------------------
  94 It is possible to group items on each line into 2 or more groups or "sublines".
  95 Each subline will be  displayed in succession on the line for a specified time,
  96 alternating continuously through each defined subline.
  97
  98 Items on a line are broken into sublines with the semicolon ';' character. The
  99 display time for each subline defaults to 2 seconds unless modified by using
 100 the '%t' tag to specify an alternate time (in seconds and optional tenths of a
 101 second) for the subline to be displayed.
 102
 103 Subline related special characters and tags:
 104    ;  : Split items on a line into separate sublines
 105   %t  : Set the subline display time. The '%t' is followed by either integer
 106         seconds (%t5), or seconds and tenths of a second (%t3.5).
 107
 108
 109 Each alternating subline can still be optionally scrolled while it is being
 110 displayed, and scrollable formats can be displayed on the same line with
 111 non-scrollable formats (such as track elapsed time) as long as they are
 112 separated into different sublines.
 113
 114   Example subline definition:
 115
 116   %s%t4%ia;%s%it;%t3%pc %pr     : Display id3 artist for 4 seconds,
 117                                   Display id3 title for 2 seconds,
 118                                   Display current and remaining track time
 119                                   for 3 seconds,
 120                                   repeat...
 121
 122 Conditionals can be used with sublines to display a different set and/or number
 123 of sublines on the line depending on the evaluation of the conditional.
 124
 125   Example subline with conditionals:
 126
 127   %?it<%t8%s%it|%s%fn>;%?ia<%t3%s%ia|%t0>
 128
 129   The format above will do two different things depending if ID3
 130   tags are present. If the ID3 artist and title are present :
 131
 132      Display id3 title for 8 seconds,
 133      Display id3 artist for 3 seconds,
 134      repeat...
 135
 136   If the ID3 artist and title are not present :
 137      Display the filename continuously.
 138
 139 Note that by using a subline display time of 0 in one branch of a conditional,
 140 a subline can be skipped (not displayed) when that condition is met.
 141
 142 -----------
 143
 144 Other Tags:
 145   %%  : Display a '%'
 146   %<  : Display a '<'
 147   %|  : Display a '|'
 148   %>  : Display a '>'
 149   %;  : Display a ';'
 150   %s  : Indicate that the line should scroll. Can occur anywhere in
 151         a line (given that the text is displayed; see conditionals
 152         above). You can specify up to 10 scrolling lines.
 153         Scrolling lines can not contain dynamic content such as timers,
 154         peak meters or progress bars.
 155
 156 Example File
 157 ------------
 158 %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>
 159 %pb%pc/%pt
 160
 161 That is, "tracknum - title [artist, album]", where most fields are only
 162 displayed if available. Could also be rendered as "filename" or
 163 "tracknum - title [artist]".
 164
 165 Default
 166 -------
 167 If you haven't selected a .wps file in the .rockbox directory, you get the
 168 hardcoded wps layout. The default WPS screen is for player:
 169
 170 # Default WPS for Player
 171 %s%pp/%pe: %?it<%it|%fn> - %?ia<%ia|%d2> - %?id<%id|%d1>
 172 %pc%?ps<*|/>%pt
 173
 174 and for recorder:
 175
 176 # Default WPS for Recorder
 177 %s%?it<%?in<%in. |>%it|%fn>
 178 %s%?ia<%ia|%?d2<%d2|(root)>>
 179 %s%?id<%id|%?d1<%d1|(root)>> %?iy<(%iy)|>
 180
 181 %pc/%pt [%pp:%pe]
 182 %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)>
 183 %pb
 184 %pm