blob: eb2b7b736309ea449ec8c1c98d92257a3157b577 [file] [log] [blame]
Nils Wallméniuscb527ca2006-09-10 10:17:47 +00001% $Id$ %
Martin Arver8e8207f2006-02-11 00:57:17 +00002\chapter{Advanced Topics}
Martin Arver35dcf902006-03-08 17:58:11 +00003
Marc Guay85eec852008-06-24 05:16:23 +00004\section{\label{ref:CustomisingUI}Customising the User Interface}
Nils Wallménius12eb0582008-03-23 22:07:09 +00005\opt{lcd_bitmap}{
Marianne Arnoldaf78b5f2008-07-06 16:10:28 +00006\subsection{\label{ref:GettingExtras}Getting Extras}
7
Martin Arver7bdd03a2006-08-27 15:00:50 +00008Rockbox supports custom fonts. A collection of fonts is available for download
Marianne Arnoldaf78b5f2008-07-06 16:10:28 +00009in the font package at \url{http://www.rockbox.org/daily.shtml}.}
Martin Arver8e8207f2006-02-11 00:57:17 +000010
Nils Wallménius12eb0582008-03-23 22:07:09 +000011\opt{lcd_bitmap}{
Dominik Riebeling85deab12006-11-20 19:56:55 +000012 \subsection{\label{ref:Loadingfonts}Loading Fonts}\index{Fonts}
Nils Wallméniuscb527ca2006-09-10 10:17:47 +000013 Rockbox can load fonts dynamically. Simply copy the \fname{.fnt} file to the
14 \dap{} and ``play'' it in the \setting{File Browser}. If you want a font to
15 be loaded automatically every time you start up, it must be located in the
Marianne Arnoldb2f7c612007-12-14 02:03:58 +000016 \fname{/.rockbox/fonts} directory and the filename must be at most 24 characters
Nils Wallméniuscb527ca2006-09-10 10:17:47 +000017 long. You can browse the fonts in \fname{/.rockbox/fonts} under
Jonas Häggqvist4b831752009-06-22 17:37:36 +000018 \setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Font}
Alex Parker51743412009-08-25 21:51:55 +000019 in the \setting{Main Menu}.\\
20
Alexander Levind9306412010-05-18 20:45:32 +000021 \note{Advanced Users Only: Any BDF font should
Nils Wallméniuscb527ca2006-09-10 10:17:47 +000022 be usable with Rockbox. To convert from \fname{.bdf} to \fname{.fnt}, use
23 the \fname{convbdf} tool. This tool can be found in the \fname{tools}
Alexander Levind9306412010-05-18 20:45:32 +000024 directory of the Rockbox source code. See \wikilink{CreateFonts\#ConvBdf}
Alexander Levin3fa48ee2010-05-19 16:34:20 +000025 for more details. Or just run \fname{convbdf} without any parameters to
26 see the possible options.}
Dominik Riebelingebb8a222006-04-04 17:48:10 +000027}
Martin Arver8e8207f2006-02-11 00:57:17 +000028
29\subsection{\label{ref:Loadinglanguages}Loading Languages}
Dominik Riebeling85deab12006-11-20 19:56:55 +000030\index{Language files}%
Martin Arver47ea9062006-06-07 12:15:46 +000031Rockbox can load language files at runtime. Simply copy the \fname{.lng} file
Dominik Riebelingb7eef892006-04-10 21:47:09 +000032\emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the
Nils Wallménius15c5d262007-03-15 02:09:15 +000033Rockbox directory browser or select \setting{Settings $\rightarrow$
Alex Parker51743412009-08-25 21:51:55 +000034General Settings $\rightarrow$ Language }from the \setting{Main Menu}.\\
Martin Arver8e8207f2006-02-11 00:57:17 +000035
Dominik Riebelingb7eef892006-04-10 21:47:09 +000036\note{If you want a language to be loaded automatically every time you start
Marianne Arnoldb2f7c612007-12-14 02:03:58 +000037up, it must be located in the \fname{/.rockbox/langs} directory and the filename
Alex Parker51743412009-08-25 21:51:55 +000038must be a maximum of 24 characters long.\\}
Martin Arver8e8207f2006-02-11 00:57:17 +000039
Dominik Riebelingebb8a222006-04-04 17:48:10 +000040If your language is not yet supported and you want to write your own language
41file find the instructions on the Rockbox website:
Dominik Riebelingb394e182006-12-29 19:22:56 +000042\wikilink{LangFiles}
Martin Arver8e8207f2006-02-11 00:57:17 +000043
Nils Wallménius12eb0582008-03-23 22:07:09 +000044\opt{lcd_color}{
Alexander Levin71812ca2009-03-20 19:33:20 +000045 \subsection{\label{ref:ChangingFiletypeColours}Changing Filetype Colours}
Alex Parker6c4661c2009-03-18 14:24:28 +000046 Rockbox has the capability to modify the \setting{File Browser} to show
Alexander Levin71812ca2009-03-20 19:33:20 +000047 files of different types in different colours, depending on the file extension.
Alex Parker6c4661c2009-03-18 14:24:28 +000048
Alexander Levin71812ca2009-03-20 19:33:20 +000049 \subsubsection{Set-up}
Alexander Levin277ce9a2009-03-21 09:25:49 +000050 There are two steps to changing the filetype colours -- creating
Alexander Levin71812ca2009-03-20 19:33:20 +000051 a file with the extension \fname{.colours} and then activating it using
52 a config file. The \fname{.colours} files \emph{must} be stored in
53 the \fname{/.rockbox/themes/} directory.
54 The \fname{.colours} file is just a text file, and can be edited with
55 your text editor of choice.
Alex Parker6c4661c2009-03-18 14:24:28 +000056
Alexander Levin71812ca2009-03-20 19:33:20 +000057 \subsubsection{Creating the .colours file}
58 The \fname{.colours} file consists of the file extension
59 (or \fname{folder}) followed by a colon and then the colour desired
60 as an RGB value in hexadecimal, as in the following example:\\*
61 \\
62 \config{folder:808080}\\
63 \config{mp3:00FF00}\\
64 \config{ogg:00FF00}\\
65 \config{txt:FF0000}\\
66 \config{???:FFFFFF}\\*
Alex Parker6c4661c2009-03-18 14:24:28 +000067
Alexander Levin71812ca2009-03-20 19:33:20 +000068 The permissible extensions are as follows:\\*
69 \\
70 \config{folder, m3u, m3u8, cfg, wps, lng, rock, bmark, cue, colours, mpa,
71 \firmwareextension{}, %
72 \opt{swcodec}{mp1, }mp2, mp3%
73 \opt{swcodec}{, ogg, oga, wma, wmv, asf, wav, flac, ac3, a52, mpc,
74 wv, m4a, m4b, mp4, mod, shn, aif, aiff, spx, sid, adx, nsf, nsfe,
75 spc, ape, mac, sap}%
76 \opt{lcd_bitmap}{\opt{swcodec}{, mpg, mpeg}}%
77 \opt{HAVE_REMOTE_LCD}{, rwps}%
78 \opt{lcd_non-mono}{, bmp}%
79 \opt{radio}{, fmr}%
80 \opt{lcd_bitmap}{, fnt, kbd}}\\*
81 %It'd be ideal to get these from filetypes.c
Alex Parker6c4661c2009-03-18 14:24:28 +000082
Alexander Levin71812ca2009-03-20 19:33:20 +000083 All file extensions that are not either specifically listed in the
84 \fname{.colours} files or are not in the list above will be
85 set to the colour given by \config{???}. Extensions that
86 are in the above list but not in the \fname{.colours}
87 file will be set to the foreground colour as normal.
Alex Parker6c4661c2009-03-18 14:24:28 +000088
Alexander Levin71812ca2009-03-20 19:33:20 +000089 \subsubsection{Activating}
90 To activate the filetype colours, the \fname{.colours} file needs to be
91 invoked from a \fname{.cfg} configuration file. The easiest way to do
92 this is to create a new text file containing the following single
93 line:\\*
94 \\
95 \config{filetype colours: /.rockbox/themes/filename.colours}\\*
Alex Parker6c4661c2009-03-18 14:24:28 +000096
Alexander Levin71812ca2009-03-20 19:33:20 +000097 where filename is replaced by the filename you used when creating the
98 \fname{.colours} file. Save this file as e.g. \fname{colours.cfg} in the
99 \fname{/.rockbox/themes} directory and then activate the config file
100 from the menu as normal
101 (\setting{Settings} $\rightarrow$ \setting{Theme Settings}%
Jonas Häggqvist4b831752009-06-22 17:37:36 +0000102 $\rightarrow$ \setting{Browse Theme Files}).
Alex Parker6c4661c2009-03-18 14:24:28 +0000103
Alexander Levin71812ca2009-03-20 19:33:20 +0000104 \subsubsection{Editing}
105 The built-in \setting{Text Editor} (see \reference{sec:text_editor})
106 automatically understands the
107 \fname{.colours} file format, but an external text editor can
108 also be used. To edit the \fname{.colours} file using Rockbox,
109 ``play'' it in the \setting{File Browser}. The file will open in
110 the \setting{Text Editor}. Upon selecting a line, the following choices
111 will appear:\\*
112 \\
113 \config{Extension}\\
114 \config{Colour}\\*
115
116 If \config{Extension} is selected, the \setting{virtual keyboard}
117 (see \reference{sec:virtual_keyboard}) appears,
118 allowing the file extension to be modified. If \config{Colour}
119 is selected, the colour selector screen appears. Choose the desired
120 colour, then save the \fname{.colours} file using the standard
121 \setting{Text Editor} controls.
Nils Wallménius15c5d262007-03-15 02:09:15 +0000122}
123
Marianne Arnold81892462008-07-15 20:57:05 +0000124\opt{lcd_non-mono}{%
Nils Wallméniusda555882006-11-13 15:14:28 +0000125 \subsection{\label{ref:LoadingBackdrops}Loading Backdrops}
126 Rockbox supports showing an image as a backdrop in the \setting{File Browser}
127 and the menus. The backdrop image must be a \fname{.bmp} file of the exact
Alexander Levin87b2ad142010-05-20 16:20:58 +0000128 same dimensions as the display in your \dap{} (\dapdisplaysize{} with the last
Nils Wallméniusda555882006-11-13 15:14:28 +0000129 number giving the colour depth in bits). To use an image as a backdrop browse
Marianne Arnold90bcefa2008-03-03 23:01:44 +0000130 to it in the \setting{File Browser} and open the \setting{Context Menu}
131 (see \reference{ref:Contextmenu}) on it and select the option
Nils Wallméniusda555882006-11-13 15:14:28 +0000132 \setting{Set As Backdrop}. If you want rockbox to remember your
133 backdrop the next time you start your \dap{} the backdrop must be placed in
Marianne Arnoldb2f7c612007-12-14 02:03:58 +0000134 the \fname{/.rockbox/backdrops} directory.
Nils Wallméniusda555882006-11-13 15:14:28 +0000135}%
136
Alex Parkerab563da2009-09-20 16:48:45 +0000137\nopt{lcd_charcell}{
138 \subsection{UI Viewport}
139 By default, the UI is drawn on the whole screen. This can be changed so that
140 the UI is confined to a specific area of the screen, by use of a UI
141 viewport. This is done by adding the following line to the
142 \fname{.cfg} file for a theme:\\*
143
144 \nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}}
145 \nopt{lcd_color}{\opt{lcd_non-mono}{
146 \config{ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}}
147 \opt{lcd_color}{
148 \config{ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}}
149 \\*
150
151 \opt{HAVE_REMOTE_LCD}{
152 The dimensions of the menu that is displayed on the remote control of your
153 \dap\ can be set in the same way. The line to be added to the theme
154 \fname{.cfg} is the following:\\*
155
156 \nopt{lcd_non-mono}{\config{remote ui viewport: X,Y,[width],[height],[font]}}
157 \nopt{lcd_color}{\opt{lcd_non-mono}{
158 \config{remote ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}}
159 \opt{lcd_color}{
160 \config{remote ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}}
161 \\*
162 }
163
164 Only the first two parameters \emph{have} to be specified, the others can
Alexander Levinb57fe482009-12-23 20:05:29 +0000165 be omitted using `-' as a placeholder. The syntax is very similar to WPS
Alex Parkerab563da2009-09-20 16:48:45 +0000166 viewports (see \reference{ref:Viewports}). Briefly:
167
168 \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}}
169 \nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-uivp-syntax.tex}}}
170 \opt{lcd_color}{\input{advanced_topics/viewports/colour-uivp-syntax.tex}}
171}
172
Alex Parker40782d52010-05-13 08:13:31 +0000173\section{\label{ref:ConfiguringtheWPS}Configuring the Theme}
Martin Arver8e8207f2006-02-11 00:57:17 +0000174
Alex Parker40782d52010-05-13 08:13:31 +0000175\subsection{Themeing -- General Info}
Martin Arver8e8207f2006-02-11 00:57:17 +0000176
Alex Parker40782d52010-05-13 08:13:31 +0000177 There are various different aspects of the Rockbox interface
178 that can be themed -- the WPS or \setting{While Playing Screen}, the FMS or
179 \setting{FM Screen} (if the \dap{} has a tuner), and the SBS or
Jonathan Gordon32382932010-05-16 11:20:42 +0000180 \setting{Base Skin}. The WPS is the name used to
Alex Parker40782d52010-05-13 08:13:31 +0000181 describe the information displayed on the \daps{} screen whilst an audio
182 track is being played, the FMS is the screen shown while listening to the
Jonathan Gordon32382932010-05-16 11:20:42 +0000183 radio, and the SBS lets you specify a base skin that is shown in the
Alex Parker40782d52010-05-13 08:13:31 +0000184 menus and browsers, as well as the WPS and FMS. The SBS also allows you to
185 control certain aspects of the appearance of the menus/browsers.
186 There are a number of themes included in Rockbox, and
Nils Wallménius01bd7362009-02-04 14:22:35 +0000187 you can load one of these at any time by selecting it in
Alex Parker40782d52010-05-13 08:13:31 +0000188 \setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Browse Theme Files}.
189 It is also possible to set individual items of a theme from within the
190 \setting{Settings $\rightarrow$ Theme Settings} menu.
Martin Arver8e8207f2006-02-11 00:57:17 +0000191
Dominik Riebelingb7eef892006-04-10 21:47:09 +0000192
Alex Parker40782d52010-05-13 08:13:31 +0000193\subsection{\label{ref:CreateYourOwnWPS}Themes -- Create Your Own}
194The theme files are simple text files, and can be created (or edited) in your
195favourite text editor. To make sure non-English characters
Alex Parker1b0c77f2010-06-20 12:58:09 +0000196display correctly in your theme you must save the theme files with UTF-8
197character encoding. This can be done in most editors, for example Notepad in
198Windows 2000 or XP (but not in 9x/ME) can do this.
Alex Parker40782d52010-05-13 08:13:31 +0000199
200\begin{description}
201\item [Files Locations: ] Each different ``themeable'' aspect requires its own file --
202 WPS files have the extension \fname{.wps}, FM screen files have the extension
203 \fname{.fms}, and SBS files have the extension \fname{.sbs}. The main theme
204 file has the extension \fname{.cfg}. All files should have the same name.
205
206 The theme \fname{.cfg} file should be placed in the \fname{/.rockbox/themes}
207 directory, while the \fname{.wps}, \fname{.fms} and \fname{.sbs} files should
208 be placed in the \fname{/.rockbox/wps} directory. Any images used by the
209 theme should be placed in a subdirectory of \fname{/.rockbox/wps} with the
210 same name as the theme, e.g. if the theme files are named
211 \fname{mytheme.wps, mytheme.sbs} etc., then the images should be placed in
212 \fname{/.rockbox/wps/mytheme}.
213\end{description}
214
215All full list of the available tags are given in appendix
216\reference{ref:wps_tags}; some of the more powerful concepts in theme designe
217are discussed below.
Martin Arver8e8207f2006-02-11 00:57:17 +0000218
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000219\begin{itemize}
Martin Arver09c39612006-08-18 16:57:56 +0000220\item All characters not preceded by \% are displayed as typed.
221\item Lines beginning with \# are comments and will be ignored.
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000222\end{itemize}
Dominik Riebelingb7eef892006-04-10 21:47:09 +0000223
Alexander Levin87b2ad142010-05-20 16:20:58 +0000224\note{Keep in mind that your \dap{} resolution is \dapdisplaysize{} (with
Dominik Riebeling5ec38052006-08-28 18:09:17 +0000225 the last number giving the colour depth in bits) when
226 designing your own WPS, or if you use a WPS designed for another target.
227 \opt{HAVE_REMOTE_LCD}{The resolution of the remote is
Alexander Levin87b2ad142010-05-20 16:20:58 +0000228 \opt{h100,h300}{128$\times$64$\times$1}\opt{x5,m5}{128$\times$96$\times$2} pixels.}}
Martin Arver6fc30d62006-08-28 17:44:49 +0000229
Alex Parkerab563da2009-09-20 16:48:45 +0000230\nopt{lcd_charcell}{
231\subsubsection{\label{ref:Viewports}Viewports}
232
233By default, a viewport filling the whole screen contains all the elements
Alex Parker64d4ddf2010-06-20 12:58:41 +0000234defined in each theme file. The
Alex Parkerab563da2009-09-20 16:48:45 +0000235\opt{lcd_non-mono}{elements in this viewport are displayed
Alexander Levin64bb9a02010-05-18 20:23:22 +0000236 with the same background/\linebreak{}foreground
Alex Parkerab563da2009-09-20 16:48:45 +0000237 \opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the}
238text is rendered in the
239same font as in the main menu. To change this behaviour a custom viewport can
240be defined. A viewport is a rectangular window on the screen%
241\opt{lcd_non-mono}{ with its own foreground/background
242\opt{lcd_color}{colours}\nopt{lcd_color}{shades}}.
243This window also has variable dimensions. To
Alex Parker64d4ddf2010-06-20 12:58:41 +0000244define a viewport a line starting \config{{\%V(\dots}} has to be
245present in the theme file. The full syntax will be explained later in
Alex Parkerab563da2009-09-20 16:48:45 +0000246this section. All elements placed before the
247line defining a viewport are displayed in the default viewport. Elements
248defined after a viewport declaration are drawn within that viewport.
249\opt{lcd_bitmap}{Loading images (see Appendix \reference{ref:wps_images})
250 should be done within the default viewport.}
251A viewport ends either with the end of the file, or with the next viewport
252declaration line. Viewports sharing the same
253coordinates and dimensions cannot be displayed at the same time. Viewports
254cannot be layered \emph{transparently} over one another. Subsequent viewports
255will be drawn over any other viewports already drawn onto that
256area of the screen.
257
258\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-vp-syntax.tex}}
259\nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-vp-syntax.tex}}}
260\opt{lcd_color}{\input{advanced_topics/viewports/colour-vp-syntax.tex}}
261
262
263\subsubsection{Conditional Viewports}
264
265Any viewport can be displayed either permanently or conditionally.
Alex Parker64d4ddf2010-06-20 12:58:41 +0000266Defining a viewport as \config{{\%V(\dots}}
Alex Parkerab563da2009-09-20 16:48:45 +0000267will display it permanently.
268
269\begin{itemize}
Alexander Levine39f4092010-06-23 18:21:35 +0000270\item {\config{\%Vl('identifier',\dots)}}
Alexander Levine0bb22182010-05-12 22:07:49 +0000271This tag preloads a viewport for later display. `identifier' is a single
Alexander Levin5a379bc2010-05-20 16:35:45 +0000272lowercase letter (a-z) and the `\dots' parameters use the same logic as
Alex Parkerab563da2009-09-20 16:48:45 +0000273the \config{\%V} tag explained above.
Alexander Levine39f4092010-06-23 18:21:35 +0000274\item {\config{\%Vd('identifier')}} Display the `identifier' viewport.
Alex Parkerab563da2009-09-20 16:48:45 +0000275\end{itemize}
276
277Viewports can share identifiers so that you can display multiple viewports
278with one \%Vd line.
279
280\nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-conditional.tex}}
281\nopt{lcd_color}{%
282 \opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-conditional.tex}}}
283\opt{lcd_color}{\input{advanced_topics/viewports/colour-conditional.tex}}
284\\*
285
286\note{The tag to display conditional viewports must come before the tag to
287preload the viewport in the \fname{.wps} file.}
Alex Parker6d549df2010-05-13 08:13:37 +0000288
289\subsection{Info Viewport (SBS only)}
290As mentioned above, it is possible to set a UI viewport via the theme
291\fname{.cfg} file. It is also possible to set the UI viewport through the SBS
292file, and to conditionally select different UI viewports.
293
294 \begin{itemize}
Alexander Levine39f4092010-06-23 18:21:35 +0000295 \item {\config{\%Vi('label',\dots)}}
Alex Parker6d549df2010-05-13 08:13:37 +0000296 This viewport is used as Custom UI Viewport in the case that the theme
297 doesn't have a ui viewport set in the theme \fname{.cfg} file. Having this
298 is strongly recommended since it makes you able to use the SBS
299 with other themes. If label is set this viewport can be selectivly used as the
Alexander Levin5a379bc2010-05-20 16:35:45 +0000300 Info Viewport using the \%VI tag. The `\dots' parameters use the same logic as
Alex Parker6d549df2010-05-13 08:13:37 +0000301 the \config{\%V} tag explained above.
302
Alexander Levine39f4092010-06-23 18:21:35 +0000303 \item {\config{\%VI('label')}} Set the Info Viewport to use the viewport called
Alex Parker6d549df2010-05-13 08:13:37 +0000304 label, as declared with the previous tag.
305 \end{itemize}
Alex Parker1b0c77f2010-06-20 12:58:09 +0000306
307\subsection{\label{ref:multifont}Additional Fonts}
308Additional fonts can be loaded within each screen file to be used in that
309screen. In this way not only can you have different fonts between e.g. the menu
310and the WPS, but you can use multiple fonts in each of the individual screens.\\
311
Alexander Levine39f4092010-06-23 18:21:35 +0000312\config{\%Fl('id',filename)}
Alex Parker1b0c77f2010-06-20 12:58:09 +0000313
314 \begin{itemize}
Alex Parker994d9552010-06-20 16:23:47 +0000315 \item `id' is the number you want to use in viewport declarations, 0 and 1
Alex Parker1b0c77f2010-06-20 12:58:09 +0000316 are reserved and so can't be used.
317 \item `filename' is the font filename to load. Fonts should be stored in
318 \fname{/.rockbox/fonts/}
319 \end{itemize}
320
Alex Parker64d4ddf2010-06-20 12:58:41 +0000321 An example would be: \config{\%Fl(2,12-Nimbus.fnt)}
Alex Parker1b0c77f2010-06-20 12:58:09 +0000322
Alex Parkerab563da2009-09-20 16:48:45 +0000323}
324
Martin Arvera245e882006-03-08 15:04:36 +0000325\subsubsection{Conditional Tags}
Martin Arverd3d3e342006-03-15 10:56:14 +0000326
Martin Arver47ea9062006-06-07 12:15:46 +0000327\begin{description}
328\item[If/else: ]
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000329Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}}
Martin Arver8e8207f2006-02-11 00:57:17 +0000330
Martin Arver68e40172006-06-07 16:37:04 +0000331If the tag specified by ``\config{xx}'' has a value, the text between the
332``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true
333part), else the text between the ``\config{{\textbar}}'' and the
334``\config{{\textgreater}}'' is displayed (the false part).
335The else part is optional, so the ``\config{{\textbar}}'' does not have to be
336specified if no else part is desired. The conditionals nest, so the text in the
337if and else part can contain all \config{\%} commands, including conditionals.
Martin Arverd3d3e342006-03-15 10:56:14 +0000338
Martin Arver47ea9062006-06-07 12:15:46 +0000339\item[Enumerations: ]
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000340Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}}
Martin Arver8e8207f2006-02-11 00:57:17 +0000341
Martin Arver68e40172006-06-07 16:37:04 +0000342For tags with multiple values, like Play status, the conditional can hold a
343list of alternatives, one for each value the tag can have.
Martin Arver68e40172006-06-07 16:37:04 +0000344Example enumeration:
345\begin{example}
Martin Arver06424512006-10-25 22:12:25 +0000346 \%?mp{\textless}Stop{\textbar}\%Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater}
Martin Arver68e40172006-06-07 16:37:04 +0000347\end{example}
Martin Arver8e8207f2006-02-11 00:57:17 +0000348
Martin Arver68e40172006-06-07 16:37:04 +0000349The last else part is optional, and will be displayed if the tag has no value.
350The WPS parser will always display the last part if the tag has no value, or if
351the list of alternatives is too short.
Martin Arver47ea9062006-06-07 12:15:46 +0000352\end{description}
Martin Arver8e8207f2006-02-11 00:57:17 +0000353
Marc Guay85eec852008-06-24 05:16:23 +0000354\subsubsection{Next Song Info}
Dominik Riebelingb7eef892006-04-10 21:47:09 +0000355You can display information about the next song -- the song that is
Martin Arver8e8207f2006-02-11 00:57:17 +0000356about to play after the one currently playing (unless you change the
Martin Arvera245e882006-03-08 15:04:36 +0000357plan).
Martin Arver8e8207f2006-02-11 00:57:17 +0000358
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000359If you use the upper-case versions of the
Martin Arver68e40172006-06-07 16:37:04 +0000360three tags: \config{F}, \config{I} and \config{D}, they will instead refer to
361the next song instead of the current one. Example: \config{\%Ig} is the genre
Alex Parker51743412009-08-25 21:51:55 +0000362name used in the next song and \config{\%Ff} is the mp3 frequency.\\
Martin Arver8e8207f2006-02-11 00:57:17 +0000363
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000364\note{The next song information \emph{will not} be available at all
Martin Arver09c39612006-08-18 16:57:56 +0000365 times, but will most likely be available at the end of a song. We
366 suggest you use the conditional display tag a lot when displaying
367 information about the next song!}
Martin Arvera245e882006-03-08 15:04:36 +0000368
Alex Parkere56030a2009-05-15 21:17:21 +0000369\subsubsection{\label{ref:AlternatingSublines}Alternating Sublines}
Martin Arver8e8207f2006-02-11 00:57:17 +0000370
Martin Arver68e40172006-06-07 16:37:04 +0000371It is possible to group items on each line into 2 or more groups or
372``sublines''. Each subline will be displayed in succession on the line for a
373specified time, alternating continuously through each defined subline.
Martin Arver8e8207f2006-02-11 00:57:17 +0000374
375Items on a line are broken into sublines with the semicolon
Alexander Levin5a379bc2010-05-20 16:35:45 +0000376`\config{;}' character. The display time for
Martin Arver8e8207f2006-02-11 00:57:17 +0000377each subline defaults to 2 seconds unless modified by using the
Alexander Levin5a379bc2010-05-20 16:35:45 +0000378`\config{\%t}' tag to specify an alternate
Martin Arver8e8207f2006-02-11 00:57:17 +0000379time (in seconds and optional tenths of a second) for the subline to be
380displayed.
381
382Subline related special characters and tags:
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000383\begin{description}
384\item[;] Split items on a line into separate sublines
385\item[\%t] Set the subline display time. The
Alex Parker64d4ddf2010-06-20 12:58:41 +0000386`\config{\%t}' is followed by either integer seconds (\config{\%t5}), or seconds
387and tenths of a second within () e.g. (\config{\%t(3.5)}).
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000388\end{description}
Martin Arver8e8207f2006-02-11 00:57:17 +0000389
390Each alternating subline can still be optionally scrolled while it is
391being displayed, and scrollable formats can be displayed on the same
392line with non{}-scrollable formats (such as track elapsed time) as long
Martin Arvera245e882006-03-08 15:04:36 +0000393as they are separated into different sublines.
Martin Arvera245e882006-03-08 15:04:36 +0000394Example subline definition:
Martin Arver47ea9062006-06-07 12:15:46 +0000395\begin{example}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000396 %s%t(4)%ia;%s%it;%t(3)%pc %pr : Display id3 artist for 4 seconds,
Martin Arver49cdd5e2006-06-07 13:29:52 +0000397 Display id3 title for 2 seconds,
398 Display current and remaining track time
399 for 3 seconds,
400 repeat...
Martin Arver47ea9062006-06-07 12:15:46 +0000401\end{example}
Martin Arver8e8207f2006-02-11 00:57:17 +0000402
Martin Arver68e40172006-06-07 16:37:04 +0000403Conditionals can be used with sublines to display a different set and/or number
404of sublines on the line depending on the evaluation of the conditional.
Martin Arvera245e882006-03-08 15:04:36 +0000405Example subline with conditionals:
Martin Arver47ea9062006-06-07 12:15:46 +0000406\begin{example}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000407 %?it{\textless}%t(8)%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t(3)%s%ia{\textbar}%t(0){\textgreater}\\
Martin Arver47ea9062006-06-07 12:15:46 +0000408\end{example}
Martin Arver8e8207f2006-02-11 00:57:17 +0000409
Martin Arver68e40172006-06-07 16:37:04 +0000410The format above will do two different things depending if ID3 tags are
411present. If the ID3 artist and title are present:
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000412\begin{itemize}
413\item Display id3 title for 8 seconds,
414\item Display id3 artist for 3 seconds,
415\item repeat\dots
416\end{itemize}
417If the ID3 artist and title are not present:
418\begin{itemize}
419\item Display the filename continuously.
420\end{itemize}
Dominik Riebelingebb8a222006-04-04 17:48:10 +0000421Note that by using a subline display time of 0 in one branch of a conditional,
422a subline can be skipped (not displayed) when that condition is met.
Martin Arvera245e882006-03-08 15:04:36 +0000423
Martin Arvera245e882006-03-08 15:04:36 +0000424\subsubsection{Using Images}
Dominik Riebelingb7eef892006-04-10 21:47:09 +0000425You can have as many as 52 images in your WPS. There are various ways of
Dominik Riebelingebb8a222006-04-04 17:48:10 +0000426displaying images:
Martin Arvera245e882006-03-08 15:04:36 +0000427\begin{enumerate}
Martin Arver68e40172006-06-07 16:37:04 +0000428 \item Load and always show the image, using the \config{\%x} tag
429 \item Preload the image with \config{\%xl} and show it with \config{\%xd}.
430 This way you can have your images displayed conditionally.
Nils Wallméniusda555882006-11-13 15:14:28 +0000431 \nopt{archos}{%
Martin Arver09c39612006-08-18 16:57:56 +0000432 \item Load an image and show as backdrop using the \config{\%X} tag. The
433 image must be of the same exact dimensions as your display.
Nils Wallméniusda555882006-11-13 15:14:28 +0000434 }%
Martin Arvera245e882006-03-08 15:04:36 +0000435\end{enumerate}
Martin Arver959d23e2006-06-04 15:03:39 +0000436
Nils Wallménius12eb0582008-03-23 22:07:09 +0000437\optv{swcodec}{% This doesn't depend on swcodec but we don't have a \noptv
Nils Wallméniusda555882006-11-13 15:14:28 +0000438 % command.
Martin Arver47ea9062006-06-07 12:15:46 +0000439 Example on background image use:
440 \begin{example}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000441 %X(background.bmp)
Martin Arver47ea9062006-06-07 12:15:46 +0000442 \end{example}
443 The image with filename \fname{background.bmp} is loaded and used in the WPS.
Nils Wallméniusda555882006-11-13 15:14:28 +0000444}%
Martin Arver47ea9062006-06-07 12:15:46 +0000445
446Example on bitmap preloading and use:
447\begin{example}
Alex Parker64d4ddf2010-06-20 12:58:41 +0000448 %x(a,static_icon.bmp,50,50)
449 %xl(b,rep\_off.bmp,16,64)
450 %xl(c,rep\_all.bmp,16,64)
451 %xl(d,rep\_one.bmp,16,64)
452 %xl(e,rep\_shuffle.bmp,16,64)
453 %?mm<%xd(b)|%xd(c)|%xd(d)|%xd(e)>
Martin Arver47ea9062006-06-07 12:15:46 +0000454\end{example}
455Four images at the same x and y position are preloaded in the example. Which
Martin Arver68e40172006-06-07 16:37:04 +0000456image to display is determined by the \config{\%mm} tag (the repeat mode).
Martin Arvera245e882006-03-08 15:04:36 +0000457
458\subsubsection{Example File}
Martin Arver47ea9062006-06-07 12:15:46 +0000459\begin{example}
Dominik Riebelingf949c8e2006-06-07 17:09:06 +0000460 %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>
461 %pb%pc/%pt
Martin Arver47ea9062006-06-07 12:15:46 +0000462\end{example}
Dominik Riebelingebb8a222006-04-04 17:48:10 +0000463That is, ``tracknum -- title [artist, album]'', where most fields are only
464displayed if available. Could also be rendered as ``filename'' or ``tracknum --
465title [artist]''.
Martin Arvera245e882006-03-08 15:04:36 +0000466
Nils Wallménius12eb0582008-03-23 22:07:09 +0000467%\opt{lcd_bitmap}{
Martin Arvera245e882006-03-08 15:04:36 +0000468% \begin{verbatim}
Martin Arver47ea9062006-06-07 12:15:46 +0000469% %s%?it<%?in<%in. |>%it|%fn>
Alex Parker64d4ddf2010-06-20 12:58:41 +0000470% %s%?ia<%ia|%?d2<%d(2)|(root)>>
471% %s%?id<%id|%?d1<%d(1)|(root)>> %?iy<(%iy)|>
Martin Arver47ea9062006-06-07 12:15:46 +0000472%
473% %al%pc/%pt%ar[%pp:%pe]
474% %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)>
475% %pb
476% %pm
477% % \end{verbatim}
478%}
Martin Arver8e8207f2006-02-11 00:57:17 +0000479
Marc Guay85eec852008-06-24 05:16:23 +0000480\section{\label{ref:manage_settings}Managing Rockbox Settings}
Martin Arver8e8207f2006-02-11 00:57:17 +0000481
Alexander Levin15c850c2010-01-22 22:54:05 +0000482\subsection{Introduction to \fname{.cfg} Files}
Marianne Arnoldb24f5ce2008-01-17 19:45:22 +0000483Rockbox allows users to store and load multiple settings through the use of
484configuration files. A configuration file is simply a text file with the
485extension \fname{.cfg}.
Martin Arver8e8207f2006-02-11 00:57:17 +0000486
Marianne Arnolda352c622007-05-19 19:03:39 +0000487A configuration file may reside anywhere on the disk. Multiple
Martin Arver09c39612006-08-18 16:57:56 +0000488configuration files are permitted. So, for example, you could have
489a \fname{car.cfg} file for the settings that you use while playing your
490jukebox in your car, and a \fname{headphones.cfg} file to store the
Nils Wallménius01bd7362009-02-04 14:22:35 +0000491settings that you use while listening to your \dap{} through headphones.
Martin Arver8e8207f2006-02-11 00:57:17 +0000492
Martin Arver09c39612006-08-18 16:57:56 +0000493See \reference{ref:cfg_specs} below for an explanation of the format
Marianne Arnoldb24f5ce2008-01-17 19:45:22 +0000494for configuration files. See \reference{ref:manage_settings_menu} for an
Martin Arver09c39612006-08-18 16:57:56 +0000495explanation of how to create, edit and load configuration files.
Martin Arver8e8207f2006-02-11 00:57:17 +0000496
Alexander Levin15c850c2010-01-22 22:54:05 +0000497\subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} Files}
Michael DiFebbo06238412006-08-12 15:56:33 +0000498
Martin Arver09c39612006-08-18 16:57:56 +0000499The Rockbox configuration file is a plain text file, so once you use the
Nils Wallméniusb659c0c2008-03-22 15:26:45 +0000500\setting{Save .cfg file} option to create the file, you can edit the file on
Marianne Arnoldb24f5ce2008-01-17 19:45:22 +0000501your computer using any text editor program. See
Martin Arver09c39612006-08-18 16:57:56 +0000502Appendix \reference{ref:config_file_options} for available settings. Configuration
Marianne Arnoldb24f5ce2008-01-17 19:45:22 +0000503files use the following formatting rules: %
Martin Arver09c39612006-08-18 16:57:56 +0000504
505\begin{enumerate}
506\item Each setting must be on a separate line.
507\item Each line has the format ``setting: value''.
508\item Values must be within the ranges specified in this manual for each
509 setting.
510\item Lines starting with \# are ignored. This lets you write comments into
511 your configuration files.
512\end{enumerate}
513
514Example of a configuration file:
515\begin{example}
Alexander Levin005caba2009-03-22 12:14:03 +0000516 volume: 70
517 bass: 11
518 treble: 12
519 balance: 0
520 time format: 12hour
521 volume display: numeric
522 show files: supported
523 wps: /.rockbox/car.wps
524 lang: /.rockbox/afrikaans.lng
Martin Arver09c39612006-08-18 16:57:56 +0000525\end{example}
526
527\note{As you can see from the example, configuration files do not need to
528 contain all of the Rockbox options. You can create configuration files
529 that change only certain settings. So, for example, supppose you
Martin Arver56b339e2006-08-27 20:44:23 +0000530 typically use the \dap{} at one volume in the car, and another when using
Martin Arver09c39612006-08-18 16:57:56 +0000531 headphones. Further, suppose you like to use an inverse LCD when you are
532 in the car, and a regular LCD setting when you are using headphones. You
533 could create configuration files that control only the volume and LCD
534 settings. Create a few different files with different settings, give
535 each file a different name (such as \fname{car.cfg},
536 \fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg
Alex Parker51743412009-08-25 21:51:55 +0000537 files} option to quickly change settings.\\}
Nils Wallménius01bd7362009-02-04 14:22:35 +0000538
539 A special case configuration file can be used to force a particular setting
540 or settings every time Rockbox starts up (e.g. to set the volume to a safe
541 level). Format a new configuration file as above with the required setting(s)
542 and save it into the \fname{/.rockbox} directory with the filename
543 \fname{fixed.cfg}.
Martin Arver09c39612006-08-18 16:57:56 +0000544
545\subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings}
546 menu} The \setting{Manage Settings} menu can be found in the \setting{Main
Martin Arver56b339e2006-08-27 20:44:23 +0000547 Menu}. The \setting{Manage Settings} menu allows you to save and load
Nils Wallménius01bd7362009-02-04 14:22:35 +0000548 \fname{.cfg} files.
Martin Arver09c39612006-08-18 16:57:56 +0000549
550\begin{description}
Michael DiFebbo06238412006-08-12 15:56:33 +0000551
Nils Wallménius01bd7362009-02-04 14:22:35 +0000552\item [Browse .cfg Files]Opens the \setting{File Browser} in the
553 \fname{/.rockbox} directory and displays all \fname{.cfg} (configuration)
554 files. Selecting a \fname{.cfg} file will cause Rockbox to load the settings
Marianne Arnold8c547672010-07-04 22:33:37 +0000555 contained in that file. Pressing \ActionStdCancel{} will exit back to the
Nils Wallménius01bd7362009-02-04 14:22:35 +0000556 \setting{Manage Settings} menu. See the \setting{Write .cfg files} option on
557 the \setting{Manage Settings} menu for details of how to save and edit a
Martin Arver56b339e2006-08-27 20:44:23 +0000558 configuration file.
Martin Arver09c39612006-08-18 16:57:56 +0000559
Marc Guay162a8f22008-06-28 16:10:02 +0000560\item [Reset Settings]This wipes the saved settings
Nils Wallménius01bd7362009-02-04 14:22:35 +0000561 in the \dap{} and resets all settings to their default values.
Martin Arver09c39612006-08-18 16:57:56 +0000562
Szymon Dziokf7253e32010-05-24 19:24:38 +0000563 \opt{IRIVER_H100_PAD,IRIVER_H300_PAD,IAUDIO_X5_PAD,SANSA_E200_PAD,SANSA_C200_PAD%
564 ,PBELL_VIBE500_PAD}{
Marianne Arnold56b3f922008-01-20 16:33:12 +0000565 \note{You can also reset all settings to their default
Marc Guay162a8f22008-06-28 16:10:02 +0000566 values by turning off the \dap, turning it back on, and holding the
Nils Wallménius01bd7362009-02-04 14:22:35 +0000567 \ButtonRec{} button immediately after the \dap{} turns on.}
Martin Arver09c39612006-08-18 16:57:56 +0000568 }
Marc Guay162a8f22008-06-28 16:10:02 +0000569 \opt{IRIVER_H10_PAD}{\note{You can also reset all settings to
Marianne Arnold56b3f922008-01-20 16:33:12 +0000570 their default values by turning off the \dap, and turning it back on
Nils Wallménius01bd7362009-02-04 14:22:35 +0000571 with the \ButtonHold{} button on.}
Marcoen Hirschberg1e514772007-04-27 19:38:16 +0000572 }
Marc Guay162a8f22008-06-28 16:10:02 +0000573 \opt{IPOD_4G_PAD}{\note{You can also reset all settings to their default
574 values by turning off the \dap, turning it back on, and activating the
Nils Wallménius01bd7362009-02-04 14:22:35 +0000575 \ButtonHold{} button immediately after the backlight comes on.}
Marc Guay162a8f22008-06-28 16:10:02 +0000576 }
Marianne Arnold56b3f922008-01-20 16:33:12 +0000577 \opt{GIGABEAT_PAD}{\note{You can also reset all settings to their default
578 values by turning off the \dap, turning it back on and pressing the
Nils Wallménius01bd7362009-02-04 14:22:35 +0000579 \ButtonA{} button immediately after the \dap{} turns on.}
Marianne Arnoldb24f5ce2008-01-17 19:45:22 +0000580 }
581
Marc Guay85eec852008-06-24 05:16:23 +0000582\item [Save .cfg File]This option writes a \fname{.cfg} file to
Nils Wallménius01bd7362009-02-04 14:22:35 +0000583 your \daps{} disk. The configuration file has the \fname{.cfg}
Martin Arver09c39612006-08-18 16:57:56 +0000584 extension and is used to store all of the user settings that are described
585 throughout this manual.
Nils Wallménius01bd7362009-02-04 14:22:35 +0000586
Marc Guay85eec852008-06-24 05:16:23 +0000587 Hint: Use the \setting{Save .cfg File} feature (\setting{Main Menu
Nils Wallménius01bd7362009-02-04 14:22:35 +0000588 $\rightarrow$ Manage Settings}) to save the current settings, then
Martin Arver09c39612006-08-18 16:57:56 +0000589 use a text editor to customize the settings file. See Appendix
590 \reference{ref:config_file_options} for the full reference of available
591 options.
Dominik Riebelingd3bf94f2008-03-11 18:43:56 +0000592
Marc Guay85eec852008-06-24 05:16:23 +0000593\item [Save Sound Settings]This option writes a \fname{.cfg} file to
Nils Wallménius01bd7362009-02-04 14:22:35 +0000594 your \daps{} disk. The configuration file has the \fname{.cfg}
Dominik Riebelingd3bf94f2008-03-11 18:43:56 +0000595 extension and is used to store all of the sound related settings.
596
Marc Guay85eec852008-06-24 05:16:23 +0000597\item [Save Theme Settings]This option writes a \fname{.cfg} file to
Nils Wallménius01bd7362009-02-04 14:22:35 +0000598 your \daps{} disk. The configuration file has the \fname{.cfg}
Dominik Riebelingd3bf94f2008-03-11 18:43:56 +0000599 extension and is used to store all of the theme related settings.
Michael DiFebbo06238412006-08-12 15:56:33 +0000600
Martin Arver09c39612006-08-18 16:57:56 +0000601\end{description}
Martin Arver8e8207f2006-02-11 00:57:17 +0000602
Martin Arver8e8207f2006-02-11 00:57:17 +0000603\section{\label{ref:FirmwareLoading}Firmware Loading}
Martin Arver96f898e2006-03-25 09:22:43 +0000604\opt{player,recorder,recorderv2fm,ondio}{
Martin Arver7bdd03a2006-08-27 15:00:50 +0000605 When your \dap{} powers on, it loads the Archos firmware in ROM, which
Marianne Arnoldb2f7c612007-12-14 02:03:58 +0000606 automatically checks your \daps{} root directory for a file named
Martin Arver47ea9062006-06-07 12:15:46 +0000607 \firmwarefilename. Note that Archos firmware can only read the first
Thom Johansenc479b992008-02-13 13:32:44 +0000608 ten characters of each filename in this process, so do not rename your old
Martin Arver47ea9062006-06-07 12:15:46 +0000609 firmware files with names like \firmwarefilename.\fname{old} and so on,
Thom Johansen10d03442007-12-13 22:51:27 +0000610 because it is possible that the \dap{} will load a file other than the one
Martin Arver7bdd03a2006-08-27 15:00:50 +0000611 you intended.
Martin Arverd3d3e342006-03-15 10:56:14 +0000612}
Martin Arver8e8207f2006-02-11 00:57:17 +0000613
Marc Guay85eec852008-06-24 05:16:23 +0000614\subsection{\label{ref:using_rolo}Using ROLO (Rockbox Loader)}
Dominik Riebelingebb8a222006-04-04 17:48:10 +0000615Rockbox is able to load and start another firmware file without rebooting.
Dominik Riebeling27948882006-07-24 20:53:27 +0000616You just ``play'' a file with the extension %
617\opt{recorder,recorderv2fm,ondio}{\fname{.ajz}.} %
618\opt{player}{\fname{.mod}.} %
Dominik Riebelingf498d532008-12-07 23:00:15 +0000619\opt{h100,h300}{\fname{.iriver}.} %
Dominik Riebeling27948882006-07-24 20:53:27 +0000620\opt{ipod}{\fname{.ipod}.} %
621\opt{iaudio}{\fname{.iaudio}.} %
Szymon Dzioka09152b2010-04-15 18:35:41 +0000622\opt{sansa,h10,h10_5gb,vibe500}{\fname{.mi4}.} %
Rafaël Carrée3c9d6a2009-05-22 10:44:15 +0000623\opt{sansaAMS}{\fname{.sansa}.} %
Alex Parker51743412009-08-25 21:51:55 +0000624\opt{gigabeatf,gigabeats}{\fname{.gigabeat}.} %
Dominik Riebeling27948882006-07-24 20:53:27 +0000625This can be used to test new firmware versions without deleting your
Dominik Riebelingebb8a222006-04-04 17:48:10 +0000626current version.
Martin Arver8e8207f2006-02-11 00:57:17 +0000627
Martin Arver30b0e662006-06-15 11:56:50 +0000628\opt{archos}{\input{advanced_topics/archos-flashing.tex}}
Alexander Levinb57fe482009-12-23 20:05:29 +0000629
Andree Buschmann10023ad2010-03-29 17:58:17 +0000630\section{Optimising battery runtime}
631 Rockbox offers a lot of settings that have high impact on the battery runtime
632 of your \dap{}. The largest power savings can be achieved through disabling
633 unneeded hardware components -- for some of those there are settings
634 available.
635\opt{swcodec}{
636 Another area of savings is avoiding or reducing CPU boosting
637 through disabling computing intense features (e.g. sound processing) or
638 using effective audio codecs.
639} The following provides a short overview of the most relevant settings and
640 rules of thumb.
641
642\nopt{ondio}{
643\subsection{Display backlight}
644 The active backlight consumes a lot of power. Therefore choose a setting that
645 disables the backlight after timeout (for setting \setting{Backlight} see
646 \reference{ref:Displayoptions}). Avoid to have the backlight enabled all the
647 time.
648}
649
650\opt{lcd_sleep}{
651\subsection{Display power-off}
652 Shutting down the display and the display controller saves a reasonable amount
653 of power. Choose a setting that will put the display to sleep after timeout
654 (for setting \setting{Sleep} see \reference{ref:Displayoptions}). Avoid to
655 have the display enabled all the time -- even, if the display is transflective
656 and is readable without backlight. Depending on your \dap{} it might be
657 significantly more efficient to re-enable the display and its backlight for a
658 glimpse a few times per hour than to keep the display enabled.
659}
660
661\opt{accessory_supply}{
662\subsection{Accessory power supply}
663 As default your \dap{}'s accessory power supply is always enabled to ensure
664 proper function of connected accessory devices. Disable this power supply, if
665 -- or as long as -- you do not use any accessory device with your \dap{} while
666 running Rockbox (see \reference{ref:AccessoryPowerSupply}).
667}
668
669\opt{lineout_poweroff}{
670\subsection{Line Out}
671 Rockbox allows to switch off the line-out on your \dap{}. If you do not need
672 the line-out, switch it off (see \reference{ref:LineoutOnOff}).
673}
674
675\opt{spdif_power}{
676\subsection{Optical Output}
677 Rockbox allows to switch off the S/PDIF output on your \dap{}. If you do not
678 need this output, switch it off (see \reference{ref:SPDIF_OnOff}).
679}
680
681\opt{disk_storage}{
682\subsection{Anti-Skip Buffer}
683 Having a large anti-skip buffer tends to use more power, and may reduce your
684 battery life. It is recommended to always use the lowest possible setting
685 that allows correct and continuous playback (see \reference{ref:AntiSkipBuf}).
686}
687
Andree Buschmann2349cf52010-04-12 06:40:58 +0000688\opt{swcodec}{
689\subsection{Replaygain}
690 Replaygain is a post processing that equalises the playback volume of audio
691 files to the same perceived loudness. This post processing applies a factor
692 to each single PCM sample and is therefore consuming additional CPU time. If
693 you want to achieve some (minor) savings in runtime, switch this feature off
694 (see \reference{ref:ReplayGain}).
695}
696
Andree Buschmann10023ad2010-03-29 17:58:17 +0000697\opt{swcodec,disk_storage,flash_storage}{
698\subsection{Audio format and bitrate}
699\opt{swcodec}{
700 In general the fastest decoding audio format will be the best in terms of
701 battery runtime on your \dap{}. An overview of different codec's performance
702 on different \dap{}s can be found at \wikilink{CodecPerformanceComparison}.
703}
704
705\opt{flash_storage}{
706 Your target uses flash that consumes a certain amount of power during access.
707 The less often the flash needs to be switched on for buffering and the shorter
708 the buffering duration is, the lower is the overall power consumption.
709 Therefore the bitrate of the audio files does have an impact on the battery
710 runtime as well. Lower bitrate audio files will result in longer battery
711 runtime.
712}
713\opt{disk_storage}{
714 Your target uses a hard disk which consumes a large amount of power while
715 spinning -- up to several hundred mA. The less often the hard disk needs to
716 spin up for buffering and the shorter the buffering duration is, the lower is
717 the power consumption. Therefore the bitrate of the audio files does have an
718 impact on the battery runtime as well. Lower bitrate audio files will result
719 in longer battery runtime.
720}
721
722 Please do not re-encode any existing audio files from one lossy format to
723 another based upon the above mentioned. This will reduce the audio quality.
724 If you have the choice, select the best suiting codec when encoding the
725 original source material.
726}
727
728\opt{swcodec}{
729\subsection{Sound settings}
730 In general all kinds of sound processing will need more CPU time and therefore
731 consume more power. The less sound processing you use, the better it is for
732 the battery runtime (for options see \reference{ref:configure_rockbox_sound}).
733}