| % $Id$ % |
| \chapter{\label{ref:wps_tags}WPS Tags} |
| \section{Status Bar} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%we} & Status Bar Enabled\\ |
| \config{\%wd} & Status Bar Disabled\\ |
| \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. |
| |
| \section{ID3 Info} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%ia} & ID3 Artist\\ |
| \config{\%ic} & ID3 Composer\\ |
| \config{\%id} & ID3 Album Name\\ |
| \config{\%ig} & ID3 Genre Name\\ |
| \config{\%in} & ID3 Track Number\\ |
| \config{\%it} & ID3 Track Title\\ |
| \config{\%iv} & ID3 Version (1.0, 1.1, 2.2, 2.3, 2.4 or empty if no id3 tag)\\ |
| \config{\%iy} & ID3 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. |
| |
| \section{Power Related Information} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%bl} & Show numeric battery level in percent.\\ |
| & Can also be used in a conditional: |
| \config{\%?bl{\textless}-1{\textbar}0{\textbar}1{\textbar}% |
| 2{\textbar}\ldots{\textbar}N{\textgreater}}\\ |
| & Where the -1 value is used when the battery level isn't |
| known (it usually is).\\ |
| \config{\%bv} & Show the battery level in volts\\ |
| \config{\%bt} & Show 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} & Sleep timer. Shows the remaining time if the sleeptimer is set\\ |
| \end{tagmap} |
| \end{table} |
| |
| \section{File Info} |
| \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}vorbis\-{\textbar}flac\-% |
| {\textbar}mpc\-{\textbar}a52\-{\textbar}wavpack\-{\textbar}alac\-% |
| {\textbar}aac\-{\textbar}shn\-{\textbar}sid\-{\textbar}adx\-% |
| {\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.\\ |
| \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 ``'' if constant bit rate\\ |
| \config{\%d1} & First directory from end of file path.\\ |
| \config{\%d2} & Second directory from end of file path.\\ |
| \config{\%d3} & Third directory from end of 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'' \dots{} You get the picture. |
| |
| \section{Playlist/Song Info} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%pb} & Progress Bar\\ |
| \opt{player}{ |
| & This will display a 1 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} & Shuffle. Shows 's' if shuffle mode is enabled.\\ |
| \config{\%pt} & Total Track Time\\ |
| \config{\%pv} & Current volume (x dB). Can also be used in a conditional: \\ |
| & \config{\%?pv{\textless}0{\textbar}1{\textbar}2{\textbar}\ldots% |
| {\textbar}N{\textgreater}}\\ |
| \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} & Display 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 amout of time. If it is not |
| specified, 1 sec 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}} & Display the value of any Rockbox setting\\ |
| \end{tagmap} |
| \end{table} |
| Example: Can be used as a simple tag \config{\%St{\textbar}skip length{\textbar}} or with conditionals |
| \config{\%?St{\textbar}eq enabled{\textbar}{\textless}Equalizer is enabled{\textbar}Equalizer is disabled{\textgreater}}. |
| |
| \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}: filename 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}: filename 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 a rockbox compatible format (1 bit per pixel BMP) |
| \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} |
| } |
| |
| \section{Alignment} |
| \begin{table} |
| \begin{tagmap}{}{} |
| \config{\%al} & Text is left aligned\\ |
| \config{\%ac} & Text is center aligned\\ |
| \config{\%ar} & Text is right aligned\\ |
| \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 24\\ |
| \config{\%ck} & Hour from 0 to 24\\ |
| \config{\%cI} & Zero padded hour from 12 to 12\\ |
| \config{\%cl} & Hour from 12 to 12\\ |
| \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{\%\%} & Display a `\%'\\ |
| \config{\%{\textless}} & Display a `{\textless}'\\ |
| \config{\%{\textbar}} & Display a `{\textbar}'\\ |
| \config{\%{\textgreater}} & Display a `{\textgreater}'\\ |
| \config{\%;} & Display a `;'\\ |
| \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 10 scrolling lines. Scrolling lines can not |
| contain dynamic content such as timers, peak meters |
| or progress bars.\\ |
| \end{tagmap} |
| \end{table} |
| |