72e9b61061
In the process, utilize the \download{} and \wikilink{} commands instead
of direct URLs.
Change-Id: Iad38c15c7b9cec95b6c011fd0dbdbb3326985bbc
806 lines
36 KiB
TeX
Executable file
806 lines
36 KiB
TeX
Executable file
% $Id$ %
|
|
\chapter{Advanced Topics}
|
|
|
|
\section{\label{ref:CustomisingUI}Customising the User Interface}
|
|
|
|
\subsection{\label{ref:CustomisingTheMainMenu}Customising The Main Menu}
|
|
|
|
It is possible to customise the main menu, i.e. to reorder or to hide some
|
|
of its items (only the main menu can be customised, submenus can not).
|
|
To accomplish this, load a \fname{.cfg} file (as described in
|
|
\reference{ref:manage_settings}) containing the following line:
|
|
\config{root~menu~order:items}, where ``items'' is a comma separated list
|
|
(no spaces around the commas!) of the following
|
|
words: \config{bookmarks}, \config{files}, \opt{tagcache}{\config{database}, }%
|
|
\config{wps}, \config{settings}, \opt{recording}{\config{recording}, }%
|
|
\opt{radio}{\config{radio}, }\config{playlists}, \config{plugins},
|
|
\config{system\_menu}, \config{shortcuts}.
|
|
Each of the words, if it occurs in the list, activates the appropriate item
|
|
in the main menu. The order of the items is given by the order of the words
|
|
in the list. The items whose words do not occur in the list will be hidden,
|
|
with one exception: the menu item \setting{Settings} will be shown even if
|
|
its word is not in the list (it is added as the last item then).
|
|
|
|
The following configuration example will change the main menu so that it will
|
|
contain only the items for the file browser, for resuming the playback, and
|
|
for changing the settings (the latter will be added automatically).
|
|
\begin{example}
|
|
\config{root menu order:files,wps}
|
|
\end{example}
|
|
|
|
|
|
To reset the menu items to the default, use \config{root~menu~order:-} (i.e.
|
|
use a hyphen instead of ``items'').
|
|
|
|
This configuration entry can only be created and edited with a text editor or
|
|
the Main Menu Config Plugin (see \reference{ref:main_menu_config}).
|
|
It is not possible to change this setting via the settings menu.
|
|
|
|
\subsection{\label{ref:OpenPlugins}Open Plugin Menu Items}
|
|
|
|
Rockbox allows you to choose a plugin to run for select menu options.
|
|
Simply choose the option in the setting menu and choose the plugin
|
|
you would like to run.
|
|
|
|
\subsection{\label{ref:GettingExtras}Getting Extras}
|
|
|
|
Rockbox supports custom fonts. A collection of fonts is available for download
|
|
in the font package at \url{https://www.rockbox.org/daily.shtml}.
|
|
|
|
\subsection{\label{ref:Loadingfonts}Loading Fonts}\index{Fonts}
|
|
Rockbox can load fonts dynamically. Simply copy the \fname{.fnt} file to the
|
|
\dap{} and ``play'' it in the \setting{File Browser}. If you want a font to
|
|
be loaded automatically every time you start up, it must be located in the
|
|
\fname{/.rockbox/fonts} directory and the filename must be at most 24 characters
|
|
long. You can browse the fonts in \fname{/.rockbox/fonts} under
|
|
\setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Font}
|
|
in the \setting{Main Menu}.\\
|
|
|
|
\note{Advanced Users Only: Any BDF font should
|
|
be usable with Rockbox. To convert from \fname{.bdf} to \fname{.fnt}, use
|
|
the \fname{convbdf} tool. This tool can be found in the \fname{tools}
|
|
directory of the Rockbox source code. See \wikilink{CreateFonts\#ConvBdf}
|
|
for more details. Or just run \fname{convbdf} without any parameters to
|
|
see the possible options.}
|
|
|
|
\subsection{\label{ref:Loadinglanguages}Loading Languages}
|
|
\index{Language files}%
|
|
Rockbox can load language files at runtime. Simply copy the \fname{.lng} file
|
|
\emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the
|
|
Rockbox directory browser or select \setting{Settings $\rightarrow$
|
|
General Settings $\rightarrow$ Language }from the \setting{Main Menu}.\\
|
|
|
|
\note{If you want a language to be loaded automatically every time you start
|
|
up, it must be located in the \fname{/.rockbox/langs} directory and the filename
|
|
must be a maximum of 24 characters long.\\}
|
|
|
|
If your language is not yet supported and you want to write your own language
|
|
file find the instructions on the Rockbox website:
|
|
\wikilink{LangFiles}
|
|
|
|
\opt{lcd_color}{
|
|
\subsection{\label{ref:ChangingFiletypeColours}Changing Filetype Colours}
|
|
Rockbox has the capability to modify the \setting{File Browser} to show
|
|
files of different types in different colours, depending on the file extension.
|
|
|
|
\subsubsection{Set-up}
|
|
There are two steps to changing the filetype colours -- creating
|
|
a file with the extension \fname{.colours} and then activating it using
|
|
a config file. The \fname{.colours} files \emph{must} be stored in
|
|
the \fname{/.rockbox/themes/} directory.
|
|
The \fname{.colours} file is just a text file, and can be edited with
|
|
your text editor of choice.
|
|
|
|
\subsubsection{Creating the .colours file}
|
|
The \fname{.colours} file consists of the file extension
|
|
(or \fname{folder}) followed by a colon and then the colour desired
|
|
as an RGB value in hexadecimal, as in the following example:\\*
|
|
\\
|
|
\config{folder:808080}\\
|
|
\config{mp3:00FF00}\\
|
|
\config{ogg:00FF00}\\
|
|
\config{txt:FF0000}\\
|
|
\config{???:FFFFFF}\\*
|
|
|
|
The permissible extensions are as follows:\\*
|
|
\\
|
|
\config{folder, m3u, m3u8, cfg, wps, lng, rock, bmark, cue, colours, mpa,
|
|
\firmwareextension{}, %
|
|
mp1, mp2, mp3, ogg, oga, wma, wmv, asf, wav, flac, ac3, a52, mpc, wv,
|
|
m4a, m4b, mp4, mod, shn, aif, aiff, spx, sid, adx, nsf, nsfe, spc, ape,
|
|
mac, sap, mpg, mpeg%
|
|
\opt{HAVE_REMOTE_LCD}{, rwps}%
|
|
\opt{lcd_non-mono}{, bmp}%
|
|
\opt{radio}{, fmr}%
|
|
, fnt, kbd}\\*
|
|
%It'd be ideal to get these from filetypes.c
|
|
|
|
All file extensions that are not either specifically listed in the
|
|
\fname{.colours} files or are not in the list above will be
|
|
set to the colour given by \config{???}. Extensions that
|
|
are in the above list but not in the \fname{.colours}
|
|
file will be set to the foreground colour as normal.
|
|
|
|
\subsubsection{Activating}
|
|
To activate the filetype colours, the \fname{.colours} file needs to be
|
|
invoked from a \fname{.cfg} configuration file. The easiest way to do
|
|
this is to create a new text file containing the following single
|
|
line:\\*
|
|
\\
|
|
\config{filetype colours: /.rockbox/themes/filename.colours}\\*
|
|
|
|
where filename is replaced by the filename you used when creating the
|
|
\fname{.colours} file. Save this file as e.g. \fname{colours.cfg} in the
|
|
\fname{/.rockbox/themes} directory and then activate the config file
|
|
from the menu as normal
|
|
(\setting{Settings} $\rightarrow$ \setting{Theme Settings}%
|
|
$\rightarrow$ \setting{Browse Theme Files}).
|
|
|
|
\subsubsection{Editing}
|
|
The built-in \setting{Text Editor} (see \reference{sec:text_editor})
|
|
automatically understands the
|
|
\fname{.colours} file format, but an external text editor can
|
|
also be used. To edit the \fname{.colours} file using Rockbox,
|
|
``play'' it in the \setting{File Browser}. The file will open in
|
|
the \setting{Text Editor}. Upon selecting a line, the following choices
|
|
will appear:\\*
|
|
\\
|
|
\config{Extension}\\
|
|
\config{Colour}\\*
|
|
|
|
If \config{Extension} is selected, the \setting{virtual keyboard}
|
|
(see \reference{sec:virtual_keyboard}) appears,
|
|
allowing the file extension to be modified. If \config{Colour}
|
|
is selected, the colour selector screen appears. Choose the desired
|
|
colour, then save the \fname{.colours} file using the standard
|
|
\setting{Text Editor} controls.
|
|
}
|
|
|
|
\opt{lcd_non-mono}{%
|
|
\subsection{\label{ref:LoadingBackdrops}Loading Backdrops}
|
|
Rockbox supports showing an image as a backdrop in the \setting{File Browser}
|
|
and the menus. The backdrop image must be a \fname{.bmp} file of the exact
|
|
same dimensions as the display in your \dap{} (\dapdisplaysize{} with the last
|
|
number giving the colour depth in bits). To use an image as a backdrop browse
|
|
to it in the \setting{File Browser} and open the \setting{Context Menu}
|
|
(see \reference{ref:Contextmenu}) on it and select the option
|
|
\setting{Set As Backdrop}. If you want rockbox to remember your
|
|
backdrop the next time you start your \dap{} the backdrop must be placed in
|
|
the \fname{/.rockbox/backdrops} directory.
|
|
}%
|
|
|
|
\subsection{UI Viewport}
|
|
By default, the UI is drawn on the whole screen. This can be changed so that
|
|
the UI is confined to a specific area of the screen, by use of a UI
|
|
viewport. This is done by adding the following line to the
|
|
\fname{.cfg} file for a theme:\\*
|
|
|
|
\nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}}
|
|
\nopt{lcd_color}{\opt{lcd_non-mono}{
|
|
\config{ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}}
|
|
\opt{lcd_color}{
|
|
\config{ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}}
|
|
\\*
|
|
|
|
\opt{HAVE_REMOTE_LCD}{
|
|
The dimensions of the menu that is displayed on the remote control of your
|
|
\dap\ can be set in the same way. The line to be added to the theme
|
|
\fname{.cfg} is the following:\\*
|
|
|
|
\nopt{lcd_non-mono}{\config{remote ui viewport: X,Y,[width],[height],[font]}}
|
|
\nopt{lcd_color}{\opt{lcd_non-mono}{
|
|
\config{remote ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}}
|
|
\opt{lcd_color}{
|
|
\config{remote ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}}
|
|
\\*
|
|
|
|
Only the first two parameters \emph{have} to be specified, the others can
|
|
be omitted using `$-$' as a placeholder. The syntax is very similar to WPS
|
|
viewports (see \reference{ref:Viewports}). Briefly:
|
|
|
|
\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}}
|
|
\nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-uivp-syntax.tex}}}
|
|
\opt{lcd_color}{\input{advanced_topics/viewports/colour-uivp-syntax.tex}}
|
|
|
|
\section{\label{ref:ConfiguringtheWPS}Configuring the Theme}
|
|
|
|
\subsection{Themeing -- General Info}
|
|
|
|
There are various different aspects of the Rockbox interface
|
|
that can be themed -- the WPS or \setting{While Playing Screen}, the FMS or
|
|
\setting{FM Screen} (if the \dap{} has a tuner), and the SBS or
|
|
\setting{Base Skin}. The WPS is the name used to
|
|
describe the information displayed on the \daps{} screen whilst an audio
|
|
track is being played, the FMS is the screen shown while listening to the
|
|
radio, and the SBS lets you specify a base skin that is shown in the
|
|
menus and browsers, as well as the WPS and FMS. The SBS also allows you to
|
|
control certain aspects of the appearance of the menus/browsers.
|
|
There are a number of themes included in Rockbox, and
|
|
you can load one of these at any time by selecting it in
|
|
\setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Browse Theme Files}.
|
|
It is also possible to set individual items of a theme from within the
|
|
\setting{Settings $\rightarrow$ Theme Settings} menu.
|
|
|
|
|
|
\subsection{\label{ref:CreateYourOwnWPS}Themes -- Create Your Own}
|
|
The theme files are simple text files, and can be created (or edited) in your
|
|
favourite text editor. To make sure non-English characters
|
|
display correctly in your theme you must save the theme files with UTF-8
|
|
character encoding. This can be done in most editors, for example Notepad in
|
|
Windows 2000 or XP (but not in 9x/ME) can do this.
|
|
|
|
\begin{description}
|
|
\item [Files Locations: ] Each different ``themeable'' aspect requires its own file --
|
|
WPS files have the extension \fname{.wps}, FM screen files have the extension
|
|
\fname{.fms}, and SBS files have the extension \fname{.sbs}. The main theme
|
|
file has the extension \fname{.cfg}. All files should have the same name.
|
|
|
|
The theme \fname{.cfg} file should be placed in the \fname{/.rockbox/themes}
|
|
directory, while the \fname{.wps}, \fname{.fms} and \fname{.sbs} files should
|
|
be placed in the \fname{/.rockbox/wps} directory. Any images used by the
|
|
theme should be placed in a subdirectory of \fname{/.rockbox/wps} with the
|
|
same name as the theme, e.g. if the theme files are named
|
|
\fname{mytheme.wps, mytheme.sbs} etc., then the images should be placed in
|
|
\fname{/.rockbox/wps/mytheme}.
|
|
\end{description}
|
|
|
|
All full list of the available tags are given in appendix
|
|
\reference{ref:wps_tags}; some of the more powerful concepts in theme design
|
|
are discussed below.
|
|
|
|
\begin{itemize}
|
|
\item All characters not preceded by \% are displayed as typed.
|
|
\item Lines beginning with \# are comments and will be ignored.
|
|
\end{itemize}
|
|
|
|
\note{Keep in mind that your \daps{} resolution is \dapdisplaysize{} (with
|
|
the last number giving the colour depth in bits) when
|
|
designing your own WPS, or if you use a WPS designed for another target.
|
|
\opt{HAVE_REMOTE_LCD}{The resolution of the remote is
|
|
\opt{iriverh100,iriverh300}{128$\times$64$\times$1}%
|
|
\opt{iaudiox5,iaudiom5,iaudiom3}{128$\times$96$\times$2}
|
|
pixels.
|
|
}
|
|
}
|
|
|
|
\subsubsection{\label{ref:Viewports}Viewports}
|
|
|
|
By default, a viewport filling the whole screen contains all the elements
|
|
defined in each theme file. The
|
|
\opt{lcd_non-mono}{elements in this viewport are displayed
|
|
with the same background/\linebreak{}foreground
|
|
\opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the}
|
|
text is rendered in the
|
|
same font as in the main menu. To change this behaviour a custom viewport can
|
|
be defined. A viewport is a rectangular window on the screen%
|
|
\opt{lcd_non-mono}{ with its own foreground/background
|
|
\opt{lcd_color}{colours}\nopt{lcd_color}{shades}}.
|
|
This window also has variable dimensions. To
|
|
define a viewport a line starting \config{{\%V(\dots)}} has to be
|
|
present in the theme file. The full syntax will be explained later in
|
|
this section. All elements placed before the
|
|
line defining a viewport are displayed in the default viewport. Elements
|
|
defined after a viewport declaration are drawn within that viewport.
|
|
Loading images (see Appendix \reference{ref:wps_images})
|
|
should be done within the default viewport.
|
|
A viewport ends either with the end of the file, or with the next viewport
|
|
declaration line. Viewports sharing the same
|
|
coordinates and dimensions cannot be displayed at the same time. Viewports
|
|
cannot be layered \emph{transparently} over one another. Subsequent viewports
|
|
will be drawn over any other viewports already drawn onto that
|
|
area of the screen.
|
|
|
|
|
|
\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-vp-syntax.tex}}
|
|
\nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-vp-syntax.tex}}}
|
|
\opt{lcd_color}{\input{advanced_topics/viewports/colour-vp-syntax.tex}}
|
|
|
|
\opt{lcd_non-mono}{
|
|
\subsubsection{Viewport Line Text Styles}
|
|
\begin{tagmap}
|
|
\config{\%Vs(mode[,param])}
|
|
& Set the viewport text style to `mode' from this point forward\\
|
|
\end{tagmap}
|
|
|
|
Mode can be the following:
|
|
|
|
\begin{rbtabular}{.75\textwidth}{lX}{\textbf{Mode} & \textbf{Description}}{}{}
|
|
clear & Restore the default style\\
|
|
invert & Draw lines inverted\\
|
|
color & Draw the text coloured by the value given in `param'. Functionally
|
|
equivalent to using the \%Vf() tag\\
|
|
\opt{lcd_color}{%
|
|
gradient & Draw the next `param' lines using a gradient as
|
|
defined by \%Vg. By default the gradient is drawn over 1 line.
|
|
\%Vs(gradient,2) will use 2 lines to fully change from the start colour to
|
|
the end colour\\}
|
|
\end{rbtabular}
|
|
}
|
|
\subsubsection{Conditional Viewports}
|
|
|
|
Any viewport can be displayed either permanently or conditionally.
|
|
Defining a viewport as \config{{\%V(\dots)}}
|
|
will display it permanently.
|
|
|
|
\begin{itemize}
|
|
\item {\config{\%Vl('identifier',\dots)}}
|
|
This tag preloads a viewport for later display. `identifier' is a single
|
|
lowercase letter (a-z) and the `\dots' parameters use the same logic as
|
|
the \config{\%V} tag explained above.
|
|
\item {\config{\%Vd('identifier')}} Display the `identifier' viewport.
|
|
\end{itemize}
|
|
|
|
Viewports can share identifiers so that you can display multiple viewports
|
|
with one \%Vd line.
|
|
|
|
\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-conditional.tex}}
|
|
\nopt{lcd_color}{%
|
|
\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-conditional.tex}}}
|
|
\opt{lcd_color}{\input{advanced_topics/viewports/colour-conditional.tex}}
|
|
\\*
|
|
|
|
\note{The tag to display conditional viewports must come before the tag to
|
|
preload the viewport in the \fname{.wps} file.}
|
|
|
|
\subsection{Info Viewport (SBS only)}
|
|
As mentioned above, it is possible to set a UI viewport via the theme
|
|
\fname{.cfg} file. It is also possible to set the UI viewport through the SBS
|
|
file, and to conditionally select different UI viewports.
|
|
|
|
\begin{itemize}
|
|
\item {\config{\%Vi('label',\dots)}}
|
|
This viewport is used as Custom UI Viewport in the case that the theme
|
|
doesn't have a ui viewport set in the theme \fname{.cfg} file. Having this
|
|
is strongly recommended since it makes you able to use the SBS
|
|
with other themes. If label is set this viewport can be selectivly used as the
|
|
Info Viewport using the \%VI tag. The `\dots' parameters use the same logic as
|
|
the \config{\%V} tag explained above.
|
|
|
|
\item {\config{\%VI('label')}} Set the Info Viewport to use the viewport called
|
|
label, as declared with the previous tag.
|
|
\end{itemize}
|
|
|
|
\subsection{\label{ref:multifont}Additional Fonts}
|
|
Additional fonts can be loaded within each screen file to be used in that
|
|
screen. In this way not only can you have different fonts between e.g. the menu
|
|
and the WPS, but you can use multiple fonts in each of the individual screens.\\
|
|
|
|
\config{\%Fl('id',filename,glyphs)}
|
|
|
|
\begin{itemize}
|
|
\item `id' is the number you want to use in viewport declarations, 0 and 1
|
|
are reserved and so can't be used.
|
|
\item `filename' is the font filename to load. Fonts should be stored in
|
|
\fname{/.rockbox/fonts/}
|
|
\item `glyphs' is an optional specification of how many unique glyphs to
|
|
store in memory. Default is from the system setting
|
|
\setting{Glyphs To Load}.
|
|
\end{itemize}
|
|
|
|
An example would be: \config{\%Fl(2,12-Nimbus.fnt,100)}
|
|
|
|
}
|
|
|
|
\subsubsection{Conditional Tags}
|
|
|
|
\begin{description}
|
|
\item[If/else: ]
|
|
Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}}
|
|
|
|
If the tag specified by ``\config{xx}'' has a value, the text between the
|
|
``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true
|
|
part), else the text between the ``\config{{\textbar}}'' and the
|
|
``\config{{\textgreater}}'' is displayed (the false part).
|
|
The else part is optional, so the ``\config{{\textbar}}'' 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 \config{\%} commands, including conditionals.
|
|
|
|
\item[Enumerations: ]
|
|
Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}}
|
|
|
|
For tags with multiple values, like Play status, the conditional can hold a
|
|
list of alternatives, one for each value the tag can have.
|
|
Example enumeration:
|
|
\begin{example}
|
|
\%?mp{\textless}Stop{\textbar}Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater}
|
|
\end{example}
|
|
|
|
The last else part is optional, and will be displayed if the tag has no value.
|
|
The WPS parser will always display the last part if the tag has no value, or if
|
|
the list of alternatives is too short.
|
|
\end{description}
|
|
|
|
\subsubsection{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 upper-case versions of the
|
|
three tags: \config{F}, \config{I} and \config{D}, they will instead refer to
|
|
the next song instead of the current one. Example: \config{\%Ig} is the genre
|
|
name used in the next song and \config{\%Ff} is the mp3 frequency.\\
|
|
|
|
\note{The next song information \emph{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!}
|
|
|
|
\subsubsection{\label{ref:AlternatingSublines}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
|
|
`\config{;}' character. The display time for
|
|
each subline defaults to 2 seconds unless modified by using the
|
|
`\config{\%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:
|
|
\begin{description}
|
|
\item[;] Split items on a line into separate sublines
|
|
\item[\%t] Set the subline display time. The
|
|
`\config{\%t}' is followed by either integer seconds (\config{\%t5}), or seconds
|
|
and tenths of a second within () e.g. (\config{\%t(3.5)}).
|
|
\end{description}
|
|
|
|
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:
|
|
\begin{example}
|
|
%s%t(4)%ia;%s%it;%t(3)%pc %pr : Display id3 artist for 4 seconds,
|
|
Display id3 title for 2 seconds,
|
|
Display current and remaining track time
|
|
for 3 seconds,
|
|
repeat...
|
|
\end{example}
|
|
|
|
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:
|
|
\begin{example}
|
|
%?it{\textless}%t(8)%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t(3)%s%ia{\textbar}%t(0){\textgreater}\\
|
|
\end{example}
|
|
|
|
The format above will do two different things depending if ID3 tags are
|
|
present. If the ID3 artist and title are present:
|
|
\begin{itemize}
|
|
\item Display id3 title for 8 seconds,
|
|
\item Display id3 artist for 3 seconds,
|
|
\item repeat\dots
|
|
\end{itemize}
|
|
If the ID3 artist and title are not present:
|
|
\begin{itemize}
|
|
\item Display the filename continuously.
|
|
\end{itemize}
|
|
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.
|
|
|
|
\subsubsection{Using Images}
|
|
You can have as many as 52 images in your WPS. There are various ways of
|
|
displaying images:
|
|
\begin{enumerate}
|
|
\item Load and always show the image, using the \config{\%x} tag
|
|
\item Preload the image with \config{\%xl} and show it with \config{\%xd}.
|
|
This way you can have your images displayed conditionally.
|
|
\item Load an image and show as backdrop using the \config{\%X} tag. The
|
|
image must be of the same exact dimensions as your display.
|
|
\end{enumerate}
|
|
|
|
\optv{swcodec}{% This doesn't depend on swcodec but we don't have a \noptv
|
|
% command.
|
|
Example on background image use:
|
|
\begin{example}
|
|
%X(background.bmp)
|
|
\end{example}
|
|
The image with filename \fname{background.bmp} is loaded and used in the WPS.
|
|
}%
|
|
|
|
Example on bitmap preloading and use:
|
|
\begin{example}
|
|
%x(a,static_icon.bmp,50,50)
|
|
%xl(b,rep\_off.bmp,16,64)
|
|
%xl(c,rep\_all.bmp,16,64)
|
|
%xl(d,rep\_one.bmp,16,64)
|
|
%xl(e,rep\_shuffle.bmp,16,64)
|
|
%?mm<%xd(b)|%xd(c)|%xd(d)|%xd(e)>
|
|
\end{example}
|
|
Four images at the same x and y position are preloaded in the example. Which
|
|
image to display is determined by the \config{\%mm} tag (the repeat mode).
|
|
|
|
\subsubsection{Example File}
|
|
\begin{example}
|
|
%s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>
|
|
%pb%pc/%pt
|
|
\end{example}
|
|
That is, ``tracknum -- title [artist, album]'', where most fields are only
|
|
displayed if available. Could also be rendered as ``filename'' or ``tracknum --
|
|
title [artist]''.
|
|
|
|
%\begin{verbatim}
|
|
% %s%?it<%?in<%in. |>%it|%fn>
|
|
% %s%?ia<%ia|%?d2<%d(2)|(root)>>
|
|
% %s%?id<%id|%?d1<%d(1)|(root)>> %?iy<(%iy)|>
|
|
%
|
|
% %al%pc/%pt%ar[%pp:%pe]
|
|
% %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)>
|
|
% %pb
|
|
% %pm
|
|
%
|
|
%\end{verbatim}
|
|
|
|
\section{\label{ref:manage_settings}Managing Rockbox Settings}
|
|
|
|
\subsection{Introduction to \fname{.cfg} Files}
|
|
Rockbox allows users to store and load multiple settings through the use of
|
|
configuration files. A configuration file is simply a text file with the
|
|
extension \fname{.cfg}.
|
|
|
|
A configuration file may reside anywhere on the disk. Multiple
|
|
configuration files are permitted. So, for example, you could have
|
|
a \fname{car.cfg} file for the settings that you use while playing your
|
|
jukebox in your car, and a \fname{headphones.cfg} file to store the
|
|
settings that you use while listening to your \dap{} through headphones.
|
|
|
|
See \reference{ref:cfg_specs} below for an explanation of the format
|
|
for configuration files. See \reference{ref:manage_settings_menu} for an
|
|
explanation of how to create, edit and load configuration files.
|
|
|
|
\subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} Files}
|
|
|
|
The Rockbox configuration file is a plain text file, so once you use the
|
|
\setting{Save .cfg file} option to create the file, you can edit the file on
|
|
your computer using any text editor program. See
|
|
Appendix \reference{ref:config_file_options} for available settings. Configuration
|
|
files use the following formatting rules: %
|
|
|
|
\begin{enumerate}
|
|
\item Each setting must be on a separate line.
|
|
\item Each line has the format ``setting: value''.
|
|
\item Values must be within the ranges specified in this manual for each
|
|
setting.
|
|
\item Lines starting with \# are ignored. This lets you write comments into
|
|
your configuration files.
|
|
\end{enumerate}
|
|
|
|
Example of a configuration file:
|
|
\begin{example}
|
|
volume: 70
|
|
bass: 11
|
|
treble: 12
|
|
balance: 0
|
|
time format: 12hour
|
|
volume display: numeric
|
|
show files: supported
|
|
wps: /.rockbox/car.wps
|
|
lang: /.rockbox/afrikaans.lng
|
|
\end{example}
|
|
|
|
\note{As you can see from the example, configuration files do not need to
|
|
contain all of the Rockbox options. You can create configuration files
|
|
that change only certain settings. So, for example, suppose you
|
|
typically use the \dap{} at one volume in the car, and another when using
|
|
headphones. Further, suppose you like to use an inverse LCD when you are
|
|
in the car, and a regular LCD setting when you are using headphones. You
|
|
could create configuration files that control only the volume and LCD
|
|
settings. Create a few different files with different settings, give
|
|
each file a different name (such as \fname{car.cfg},
|
|
\fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg
|
|
files} option to quickly change settings.\\}
|
|
|
|
A special case configuration file can be used to force a particular setting
|
|
or settings every time Rockbox starts up (e.g. to set the volume to a safe
|
|
level). Format a new configuration file as above with the required setting(s)
|
|
and save it into the \fname{/.rockbox} directory with the filename
|
|
\fname{fixed.cfg}.
|
|
|
|
\subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings}
|
|
menu} The \setting{Manage Settings} menu can be found in the \setting{Main
|
|
Menu}. The \setting{Manage Settings} menu allows you to save and load
|
|
\fname{.cfg} files.
|
|
|
|
\begin{description}
|
|
|
|
\item [Browse .cfg Files]Opens the \setting{File Browser} in the
|
|
\fname{/.rockbox} directory and displays all \fname{.cfg} (configuration)
|
|
files. Selecting a \fname{.cfg} file will cause Rockbox to load the settings
|
|
contained in that file. Pressing \ActionStdCancel{} will exit back to the
|
|
\setting{Manage Settings} menu. See the \setting{Write .cfg files} option on
|
|
the \setting{Manage Settings} menu for details of how to save and edit a
|
|
configuration file.
|
|
|
|
\item [Reset Settings]This wipes the saved settings
|
|
in the \dap{} and resets all settings to their default values.
|
|
|
|
\opt{IRIVER_H100_PAD,IRIVER_H300_PAD,IAUDIO_X5_PAD,SANSA_E200_PAD,SANSA_C200_PAD%
|
|
,PBELL_VIBE500_PAD,SAMSUNG_YH92X_PAD,SAMSUNG_YH820_PAD}{
|
|
\note{You can also reset all settings to their default
|
|
values by turning off the \dap, turning it back on, and holding the
|
|
\ButtonRec{} button immediately after the \dap{} turns on.}
|
|
}
|
|
\opt{IRIVER_H10_PAD}{\note{You can also reset all settings to
|
|
their default values by turning off the \dap, and turning it back on
|
|
with the \ButtonHold{} button on.}
|
|
}
|
|
\opt{IPOD_4G_PAD}{\note{You can also reset all settings to their default
|
|
values by turning off the \dap, turning it back on, and activating the
|
|
\ButtonHold{} button immediately after the backlight comes on.}
|
|
}
|
|
\opt{GIGABEAT_PAD}{\note{You can also reset all settings to their default
|
|
values by turning off the \dap, turning it back on and pressing the
|
|
\ButtonA{} button immediately after the \dap{} turns on.}
|
|
}
|
|
|
|
\item [Save .cfg File]This option writes a \fname{.cfg} file to
|
|
your \daps{} disk. The configuration file has the \fname{.cfg}
|
|
extension and is used to store all of the user settings that are described
|
|
throughout this manual.
|
|
|
|
Hint: Use the \setting{Save .cfg File} feature (\setting{Main Menu
|
|
$\rightarrow$ Manage Settings}) to save the current settings, then
|
|
use a text editor to customize the settings file. See Appendix
|
|
\reference{ref:config_file_options} for the full reference of available
|
|
options.
|
|
|
|
\item [Save Sound Settings]This option writes a \fname{.cfg} file to
|
|
your \daps{} disk. The configuration file has the \fname{.cfg}
|
|
extension and is used to store all of the sound related settings.
|
|
|
|
\item [Save Theme Settings]This option writes a \fname{.cfg} file to
|
|
your \daps{} disk. The configuration file has the \fname{.cfg}
|
|
extension and is used to store all of the theme related settings.
|
|
|
|
\end{description}
|
|
|
|
\section{\label{ref:FirmwareLoading}Firmware Loading}
|
|
|
|
\subsection{\label{ref:using_rolo}Using ROLO (Rockbox Loader)}
|
|
Rockbox is able to load and start another firmware file without rebooting.
|
|
You just ``play'' a file with the extension %
|
|
\opt{iriverh100,iriverh300}{\fname{.iriver}.} %
|
|
\opt{ipod}{\fname{.ipod}.} %
|
|
\opt{iaudio}{\fname{.iaudio}.} %
|
|
\opt{sansa,iriverh10,iriverh10_5gb,mrobe100,vibe500,samsungyh}{\fname{.mi4}.} %
|
|
\opt{sansaAMS,fuzeplus}{\fname{.sansa}.} %
|
|
\opt{gigabeatf,gigabeats}{\fname{.gigabeat}.} %
|
|
This can be used to test new firmware versions without deleting your
|
|
current version.
|
|
|
|
\opt{multi_boot}{
|
|
\subsection{\label{ref:using_multiboot}Using Multiboot}
|
|
\newcommand{\redirectext}{<playername>}
|
|
\opt{fuze}{\renewcommand*{\redirectext}{fuze}}
|
|
\opt{fuzev2}{\renewcommand*{\redirectext}{fuze2}}
|
|
\opt{fuzeplus}{\renewcommand*{\redirectext}{fuze+}}
|
|
\opt{clipplus}{\renewcommand*{\redirectext}{clip+}}
|
|
\opt{clipzip}{\renewcommand*{\redirectext}{clipzip}}
|
|
\opt{e200}{\renewcommand*{\redirectext}{e200}}
|
|
|
|
Using a specially crafted redirect file combined with special firmware builds
|
|
that allow the boot drive to be passed from the bootloader, some devices can
|
|
run Rockbox from a MicroSD card. You can even direct the bootloader to run the
|
|
firmware from a different folder within the SD card if desired.
|
|
\note{
|
|
Each supported model looks for a specific redirect file
|
|
(file extension is unique to each model).
|
|
}
|
|
|
|
Create \fname{/rockbox\_main.\redirectext{}} in the root of the SD card.
|
|
The redirect file should contain a single line denoting the path to the root
|
|
of the desired \fname{.rockbox} directory. A single forward slash ``/'' indicates
|
|
\fname{/.rockbox} in the root of the sd card.
|
|
\note{The redirect file does not work when placed on the internal drive.}
|
|
|
|
If instead you wanted to run the Rockbox from SD card \fname{/mybuild/.rockbox}
|
|
then your \fname{/rockbox\_main.\redirectext{}} file should contain:
|
|
``/mybuild/''
|
|
}
|
|
|
|
\section{Optimising battery runtime}
|
|
Rockbox offers a lot of settings that have high impact on the battery runtime
|
|
of your \dap{}. The largest power savings can be achieved through disabling
|
|
unneeded hardware components -- for some of those there are settings
|
|
available.
|
|
|
|
|
|
Another area of savings is avoiding or reducing CPU boosting
|
|
through disabling computing intense features (e.g. sound processing) or
|
|
using effective audio codecs.
|
|
The following provides a short overview of the most relevant settings and
|
|
rules of thumb.
|
|
|
|
\subsection{Display backlight}
|
|
The active backlight consumes a lot of power. Therefore choose a setting that
|
|
disables the backlight after timeout (for setting \setting{Backlight} see
|
|
\reference{ref:Displayoptions}). Avoid having the backlight enabled all the
|
|
time (Activating \setting{selectivebacklight}
|
|
\reference{ref:selectivebacklight} can further reduce power consumption).
|
|
|
|
\opt{lcd_sleep}{
|
|
\subsection{Display power-off}
|
|
Shutting down the display and the display controller saves a reasonable amount
|
|
of power. Choose a setting that will put the display to sleep after timeout
|
|
(for setting \setting{Sleep} see \reference{ref:Displayoptions}). Avoid to
|
|
have the display enabled all the time -- even, if the display is transflective
|
|
and is readable without backlight. Depending on your \dap{} it might be
|
|
significantly more efficient to re-enable the display and its backlight for a
|
|
glimpse a few times per hour than to keep the display enabled.
|
|
}
|
|
|
|
\opt{accessory_supply}{
|
|
\subsection{Accessory power supply}
|
|
As default your \dap{}'s accessory power supply is always enabled to ensure
|
|
proper function of connected accessory devices. Disable this power supply, if
|
|
-- or as long as -- you do not use any accessory device with your \dap{} while
|
|
running Rockbox (see \reference{ref:AccessoryPowerSupply}).
|
|
}
|
|
|
|
\opt{lineout_poweroff}{
|
|
\subsection{Line Out}
|
|
Rockbox allows to switch off the line-out on your \dap{}. If you do not need
|
|
the line-out, switch it off (see \reference{ref:LineoutOnOff}).
|
|
}
|
|
|
|
\opt{spdif_power}{
|
|
\subsection{Optical Output}
|
|
Rockbox allows to switch off the S/PDIF output on your \dap{}. If you do not
|
|
need this output, switch it off (see \reference{ref:SPDIF_OnOff}).
|
|
}
|
|
|
|
\opt{disk_storage}{
|
|
\subsection{Anti-Skip Buffer}
|
|
Having a large anti-skip buffer tends to use more power, and may reduce your
|
|
battery life. It is recommended to always use the lowest possible setting
|
|
that allows correct and continuous playback (see \reference{ref:AntiSkipBuf}).
|
|
}
|
|
|
|
\subsection{Replaygain}
|
|
Replaygain is a post processing that equalises the playback volume of audio
|
|
files to the same perceived loudness. This post processing applies a factor
|
|
to each single PCM sample and is therefore consuming additional CPU time. If
|
|
you want to achieve some (minor) savings in runtime, switch this feature off
|
|
(see \reference{ref:ReplayGain}).
|
|
|
|
\subsection{Peak Meter}
|
|
The peak meter is a feature of the While Playing Screen and will be updated with a
|
|
high framerate. Depending on your \dap{} this might result in a high CPU load. To
|
|
save battery runtime you should switch this feature off (see \reference{ref:peak_meter}).
|
|
\opt{ipodvideo}{
|
|
\note{Especially the \playerman{} \playertype{} suffers from an enabled peak meter.}
|
|
}
|
|
|
|
\subsection{Audio format and bitrate}
|
|
In general the fastest decoding audio format will be the best in terms of
|
|
battery runtime on your \dap{}. An overview of different codec's performance
|
|
on different \dap{}s can be found at \wikilink{CodecPerformanceComparison}.
|
|
|
|
\opt{flash_storage}{
|
|
Your target uses flash that consumes a certain amount of power during access.
|
|
The less often the flash needs to be switched on for buffering and the shorter
|
|
the buffering duration is, the lower is the overall power consumption.
|
|
Therefore the bitrate of the audio files does have an impact on the battery
|
|
runtime as well. Lower bitrate audio files will result in longer battery
|
|
runtime.
|
|
}
|
|
\opt{disk_storage}{
|
|
Your target uses a hard disk which consumes a large amount of power while
|
|
spinning -- up to several hundred mA. The less often the hard disk needs to
|
|
spin up for buffering and the shorter the buffering duration is, the lower is
|
|
the power consumption. Therefore the bitrate of the audio files does have an
|
|
impact on the battery runtime as well. Lower bitrate audio files will result
|
|
in longer battery runtime.
|
|
}
|
|
|
|
Please do not re-encode any existing audio files from one lossy format to
|
|
another based upon the above mentioned. This will reduce the audio quality.
|
|
If you have the choice, select the best suiting codec when encoding the
|
|
original source material.
|
|
|
|
\subsection{Sound settings}
|
|
In general all kinds of sound processing will need more CPU time and therefore
|
|
consume more power. The less sound processing you use, the better it is for
|
|
the battery runtime (for options see \reference{ref:configure_rockbox_sound}).
|