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 Database tags: %rp : Playcount %rr : Rating %ra : Auto score 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 %?iv<(id3v%iv)|(no id3)> %pb %pm