| % $Id$ % |
| \chapter{\label{ref:wps_tags}WPS Tags} |
| \section{Status Bar} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%we} & Display Status Bar\\ |
| \config{\%wd} & Hide Status Bar\\ |
| \end{tagmap} |
| \end{table} |
| These tags override the player setting for the display of the status bar. |
| They must be noted on their own line (which will not be shown in the WPS). |
| |
| \section{Information from the track tags} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%ia} & Artist\\ |
| \config{\%ic} & Composer\\ |
| \config{\%id} & Album Name\\ |
| \config{\%ig} & Genre Name\\ |
| \config{\%in} & Track Number\\ |
| \config{\%it} & Track Title\\ |
| \config{\%iv} & ID3 version (1.0, 1.1, 2.2, 2.3, 2.4, or empty if not an ID3 tag)\\ |
| \config{\%iy} & Year\\ |
| \end{tagmap} |
| \end{table} |
| Remember that this information is not always available, so use the |
| conditionals to show alternate information in preference to assuming. |
| |
| These tags, when written with a capital ``I'' (e.g. \config{\%Ia} or \config{\%Ic}), |
| produce the information for the next song to be played. |
| |
| \section{Power Related Information} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%bl} & Numeric battery level in percents\\ |
| & Can also be used in a conditional: |
| \config{\%?bl{\textless}-1{\textbar}0{\textbar}1{\textbar}% |
| 2{\textbar}\ldots{\textbar}N{\textgreater}}, |
| where the value $-1$ is used when the battery level isn't |
| known (it usually is)\\ |
| \config{\%bv} & The battery level in volts\\ |
| \config{\%bt} & Estimated battery time left\\ |
| \config{\%bp} & ``p'' if the charger is connected (only on targets |
| that can charge batteries)\\ |
| \config{\%bc} & ``c'' if the unit is currently charging the battery (only on |
| targets that have software charge control or monitoring)\\ |
| \config{\%bs} & Remaining time of the sleep timer (if it is set)\\ |
| \end{tagmap} |
| \end{table} |
| |
| \section{Information about the file} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%fb} & File Bitrate (in kbps)\\ |
| \config{\%fc} & File Codec (e.g. ``MP3'' or ``FLAC''). % |
| This tag can also be used in a conditional tag, % |
| \config{\%?fc{\textless}mp1\-{\textbar}mp2\-{\textbar}mp3\-% |
| {\textbar}aiff\-{\textbar}wav\-{\textbar}ogg\-{\textbar}flac\-% |
| {\textbar}mpc\-{\textbar}a52\-{\textbar}wavpack\-{\textbar}alac\-% |
| {\textbar}aac\-{\textbar}shn\-{\textbar}sid\-{\textbar}adx\-% |
| {\textbar}nsf\-{\textbar}speex\-{\textbar}spc\-{\textbar}ape\-% |
| {\textbar}wma\-{\textbar}mod\-{\textbar}sap% |
| {\textbar}unknown{\textgreater}}.\\ |
| & The codec order is as follows: MP1, MP2, MP3, AIFF, WAV, |
| Ogg Vorbis (OGG), FLAC, MPC, AC3, WavPack (WV), ALAC, AAC, |
| Shorten (SHN), SID, ADX, NSF, Speex, SPC, APE, WMA, MOD, SAP.\\ |
| \config{\%ff} & File Frequency (in Hz)\\ |
| \config{\%fm} & File Name\\ |
| \config{\%fn} & File Name (without extension)\\ |
| \config{\%fp} & File Path\\ |
| \config{\%fs} & File Size (in Kilobytes)\\ |
| \config{\%fv} & ``(avg)'' if variable bit rate or empty string if constant bit rate\\ |
| \config{\%d1} & First directory from the end of the file path\\ |
| \config{\%d2} & Second directory from the end of the file path\\ |
| \config{\%d3} & Third directory from the end of the file path\\ |
| \end{tagmap} |
| \end{table} |
| Example for the \config{\%dN} commands: If the path is |
| ``/Rock/Kent/Isola/11 - 747.mp3'', \config{\%d1} is ``Isola'', |
| \config{\%d2} is ``Kent'' and \config{\%d3} is ``Rock''. |
| |
| These tags, when written with the first letter capitalized (e.g. \config{\%Fn} or \config{\%D2}), |
| produce the information for the next file to be played. |
| |
| \section{Playlist/Song Info} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%pb} & Progress Bar\\ |
| \opt{player}{ |
| & This will display a one character ``cup'' |
| that empties as the time progresses.} |
| \opt{lcd_bitmap}{ |
| & This will replace the entire line with a progress bar. \\ |
| & You can set the height, position and width of the progressbar % |
| (in pixels): \config{\%pb{\textbar}height{\textbar}leftpos% |
| {\textbar}rightpos{\textbar}toppos{\textbar}}} \\ |
| \opt{player}{% |
| \config{\%pf} & Full-line progress bar \& time display\\ |
| }% |
| \config{\%px} & Percentage Played In Song\\ |
| \config{\%pc} & Current Time In Song\\ |
| \config{\%pe} & Total Number of Playlist Entries\\ |
| \nopt{player}{% |
| \config{\%pm} & Peak Meter. The entire line is used as % |
| volume peak meter.\\% |
| }% |
| \config{\%pn} & Playlist Name (without path or extension)\\ |
| \config{\%pp} & Playlist Position\\ |
| \config{\%pr} & Remaining Time In Song\\ |
| \config{\%ps} & ``s'' if shuffle mode is enabled\\ |
| \config{\%pt} & Total Track Time\\ |
| \config{\%pv} & Current volume (in dB). Can also be used in a conditional: \\ |
| & \config{\%?pv{\textless}0{\textbar}1{\textbar}2{\textbar}\ldots% |
| {\textbar}N{\textgreater}}\\ |
| & 0 is used for mute, the last option is used for values greater than zero.\\ |
| \end{tagmap} |
| \end{table} |
| |
| \section{Runtime Database} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%rp} & Song playcount\\ |
| \config{\%rr} & Song rating (0-10). This tag can also be used in a conditional tag: % |
| \config{\%?rr{\textless}0{\textbar}1{\textbar}2{\textbar}3{\textbar}% |
| 4{\textbar}5{\textbar}6{\textbar}7{\textbar}8{\textbar}9{\textbar}% |
| 10{\textgreater}}\\ |
| \end{tagmap} |
| \end{table} |
| |
| \opt{swcodec}{ |
| \section{Sound (DSP) settings} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%Sp} & Current playback pitch \\ |
| \opt{swcodec}{ |
| \config{\%xf} & Crossfade setting, in the order: Off, Shuffle, Skip, Always\\ |
| \config{\%rg} & ReplayGain value in use (x.y dB). If used as a conditional, |
| Replaygain type in use: \config{\%?rg{\textless}Off{\textbar}Track% |
| {\textbar}Album{\textbar}TrackShuffle{\textbar}AlbumShuffle% |
| {\textbar}No tag{\textgreater}}\\ |
| } |
| \end{tagmap} |
| \end{table} |
| } |
| \opt{h100,h300}{ |
| \section{Hold Switches} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%mh} & ``h'' if the main unit hold switch is on\\ |
| \config{\%mr} & ``r'' if the remote hold switch is on\\ |
| \end{tagmap} |
| \end{table} |
| } |
| |
| \section{Virtual LED} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%lh} & ``h'' if the \disk\ is accessed\\ |
| \end{tagmap} |
| \end{table} |
| |
| \section{Repeat Mode} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%mm} & Repeat mode, 0-4, in the order: Off, All, One, Shuffle |
| \opt{player,recorder,recorderv2fm}{, A-B}\\ |
| \end{tagmap} |
| \end{table} |
| Example: \config{\%?mm{\textless}Off{\textbar}All{\textbar}One{\textbar}Shuffle% |
| {\textbar}A-B{\textgreater}} |
| |
| \section{Playback Mode Tags} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%mp} & Play status, 0-4, in the order: Stop, Play, Pause, |
| Fast Forward, Rewind\\ |
| \end{tagmap} |
| \end{table} |
| Example: \config{\%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}% |
| Ffwd{\textbar}Rew{\textgreater}} |
| |
| \section{Changing Volume} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%mv[t]} & ``v'' if the volume is being changed\\ |
| \end{tagmap} |
| \end{table} |
| |
| The tag produces the letter ``v'' while the volume is being changed and some |
| amount of time after that, i.e. after the volume button has been released. The |
| optional parameter \config{t} specifies that amount of time, in seconds. If it |
| is not specified, 1 second is assumed. |
| |
| The tag can be used as the switch in a conditional tag to display different things |
| depending on whether the volume is being changed. It can produce neat effects |
| when used with conditional viewports. |
| |
| Example: \config{\%?mv2.5{\textless}Volume changing{\textbar}\%pv{\textgreater}} |
| |
| The example above will display the text ``Volume changing'' if the volume is |
| being changed and 2.5 secs after the volume button has been released. After |
| that, it will display the volume value. |
| |
| \section{Settings} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%St{\textbar}<setting name>{\textbar}} & The value of the Rockbox |
| setting with the specified name. See \reference{ref:config_file_options} |
| for the list of the available settings.\\ |
| \end{tagmap} |
| \end{table} |
| |
| Examples: |
| \begin{enumerate} |
| \item As a simple tag: \config{\%St{\textbar}skip length{\textbar}} |
| \item As a conditional: \config{\%?St{\textbar}eq enabled{\textbar}{\textless}Eq is enabled{\textbar}Eq is disabled{\textgreater}} |
| \end{enumerate} |
| |
| |
| \opt{lcd_bitmap}{ |
| \section{Images} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \nopt{archos}{% |
| \config{\%X{\textbar}filename.bmp{\textbar}} |
| & Load and set a backdrop image for the WPS. |
| This image must be exactly the same size as your LCD.\\ |
| }% |
| \config{\%P{\textbar}filename.bmp{\textbar}} |
| & Load a Progress Bar image for the WPS. Use \config{\%pb} tag to show the |
| progress bar\\ |
| \config{\%x{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar}} |
| & Load and display an image\\ |
| & \config{n}: image ID (a-z and A-Z) for later referencing in \config{\%xd}\\ |
| & \config{filename}: file name relative to \fname{/.rockbox/} and including ``.bmp''\\ |
| & \config{x}: x coordinate\\ |
| & \config{y}: y coordinate.\\ |
| \config{\%xl{\textbar}n{\textbar}filename{\textbar}x{\textbar}y{\textbar}[nimages{\textbar}]} |
| & Preload an image for later display (useful for when your images are displayed conditionally)\\ |
| & \config{n}: image ID (a-z and A-Z) for later referencing in \config{\%xd}\\ |
| & \config{filename}: file name relative to \fname{/.rockbox/} and including ``.bmp''\\ |
| & \config{x}: x coordinate\\ |
| & \config{y}: y coordinate\\ |
| & \config{nimages}: (optional) number of sub-images (tiled vertically, of the same height) |
| contained in the bitmap. Default is 1.\\ |
| \config{\%xdn[i]} & Display a preloaded image\\ |
| & \config{n}: image ID (a-z and A-Z) as it was specified in \config{\%x} or \config{\%xl}\\ |
| & \config{i}: (optional) number of the sub-image to display (a-z for 1-26 and A-Z for 27-52). |
| By default the first (i.e. top most) sub-image will be used.\\ |
| \end{tagmap} |
| \end{table} |
| |
| Examples: |
| \begin{enumerate} |
| \item Load and display the image \fname{/.rockbox/bg.bmp} with ID ``a'' at 37, 109:\\ |
| \config{\%x{\textbar}a{\textbar}bg.bmp{\textbar}37{\textbar}109{\textbar}} |
| \item Load a bitmap strip containing 5 volume icon images (all the same size) |
| with image ID ``M'', and then reference the individual sub-images in a conditional:\\ |
| \config{\%xl{\textbar}M{\textbar}volume.bmp{\textbar}134{\textbar}153{\textbar}5{\textbar}}\\ |
| \config{\%?pv<\%xdMa{\textbar}\%xdMb{\textbar}\%xdMc{\textbar}\%xdMd{\textbar}% |
| \%xdMe>} |
| \end{enumerate} |
| |
| |
| \note{ |
| \begin{itemize} |
| \item The images must be in BMP format |
| \item The image tag must be on its own line |
| \item The ID is case sensitive, giving 52 different ID's |
| \item The size of the LCD screen for each player varies. See table below |
| for appropriate sizes of each device. The x and y coordinates must |
| repect each of the players' limits. |
| \end{itemize} |
| } |
| } |
| |
| \opt{albumart}{ |
| \section{Album Art} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%Cl{\textbar}x{\textbar}y{\textbar}[[l{\textbar}c{\textbar}r]maxwidth]{\textbar}[[t{\textbar}c{\textbar}b]maxheight]{\textbar}} |
| & Define the settings for albumart\\ |
| & \config{x}: x coordinate\\ |
| & \config{y}: y coordinate\\ |
| & \config{maxwidth}: Maximum height\\ |
| & \config{maxheight}: Maximum width\\ |
| \config{\%C} & Display the album art as configured. This tag can also be used as a conditional.\\ |
| \end{tagmap} |
| \end{table} |
| |
| The picture will be rescaled, preserving aspect ratio to fit the given |
| \config{maxwidth} and \config{maxheight}. If the aspect ratio doesn't match the |
| configured values, the picture will be placed according to the flags to the |
| \config{maxwidth} and \config{maxheight} parameters: |
| \begin{itemize} |
| \item \config{maxwidth}: |
| \begin{description} |
| \item[\config{l}.] Align left |
| \item[\config{c}.] Align center (default) |
| \item[\config{r}.] Align right |
| \end{description} |
| \item \config{maxheight}: |
| \begin{description} |
| \item[\config{t}.] Align left |
| \item[\config{c}.] Align center (default) |
| \item[\config{b}.] Align right |
| \end{description} |
| \end{itemize} |
| |
| Examples: |
| \begin{enumerate} |
| \item Load albumart at position 20,40 and display it without resizing:\\ |
| \config{\%Cl{\textbar}20{\textbar}40{\textbar}{\textbar}{\textbar}} |
| \item Load albumart at position 0,20 and resize it to be at most 100x100 |
| pixels. If the image isn't square, align it to the bottom-right |
| corner:\\ |
| \config{\%CL{\textbar}0{\textbar}20{\textbar}r100{\textbar}b100{\textbar}} |
| \end{enumerate} |
| } |
| |
| \section{Alignment} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%al} & Align the text left\\ |
| \config{\%ac} & Center the text\\ |
| \config{\%ar} & Align the text right\\ |
| \end{tagmap} |
| \end{table} |
| All alignment tags may be present in one line, but they need to be in the |
| order left -- center -- right. If the aligned texts overlap, they are merged. |
| |
| \section{Conditional Tags} |
| |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%?xx{\textless}true{\textbar}false{\textgreater}} |
| & If / Else: Evaluate for true or false case \\ |
| \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}} |
| & Enumerations: Evaluate for first / second / third / \dots / last condition \\ |
| \end{tagmap} |
| \end{table} |
| |
| \opt{rtc}{ |
| \section{Real Time Clock} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%cd} & Day of month\\ |
| \config{\%ce} & Zero padded day of month\\ |
| \config{\%cH} & Zero padded hour from 00 to 23 (24 hour format)\\ |
| \config{\%ck} & Hour from 0 to 23 (24 hour format)\\ |
| \config{\%cI} & Zero padded hour from 12 to 12 (am/pm format)\\ |
| \config{\%cl} & Hour from 12 to 12 (am/pm format)\\ |
| \config{\%cm} & Month\\ |
| \config{\%cM} & Minutes\\ |
| \config{\%cS} & Seconds\\ |
| \config{\%cy} & 2-digit year\\ |
| \config{\%cY} & 4-digit year\\ |
| \config{\%cP} & Capital AM/PM\\ |
| \config{\%cp} & Lowercase am/pm\\ |
| \config{\%ca} & Weekday name\\ |
| \config{\%cb} & Month name\\ |
| \config{\%cu} & Day of week from 1 to 7, 1 is Monday\\ |
| \config{\%cw} & Day of week from 0 to 6, 0 is Sunday\\ |
| \end{tagmap} |
| \end{table} |
| } |
| |
| \section{Other Tags} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%\%} & The character `\%'\\ |
| \config{\%{\textless}} & The character `{\textless}'\\ |
| \config{\%{\textbar}} & The character `{\textbar}'\\ |
| \config{\%{\textgreater}} & The character `{\textgreater}'\\ |
| \config{\%;} & The character `;'\\ |
| \config{\%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 ten scrolling lines. Scrolling lines can not |
| contain dynamic content such as timers, peak meters |
| or progress bars.\\ |
| \end{tagmap} |
| \end{table} |