| 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<avg|> %?iv<(id3v%iv)|(no id3)> |
| %pb |
| %pm |