Use a nice apostroph
[kugel-rb.git] / manual / advanced_topics / main.tex
1 % $Id$ %
2 \chapter{Advanced Topics}
4 \section{\label{ref:CustomisingUI}Customising the User Interface}
5 \opt{lcd_bitmap}{
6 \subsection{\label{ref:GettingExtras}Getting Extras}
8 Rockbox supports custom fonts. A collection of fonts is available for download
9 in the font package at \url{}.}
11 \opt{lcd_bitmap}{
12 \subsection{\label{ref:Loadingfonts}Loading Fonts}\index{Fonts}
13 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
16 \fname{/.rockbox/fonts} directory and the filename must be at most 24 characters
17 long. You can browse the fonts in \fname{/.rockbox/fonts} under
18 \setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ Font}
19 in the \setting{Main Menu}.\\
21 \note{Advanced Users Only: Any BDF font file up to 16 pixels high should
22 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}
24 directory of the Rockbox source code.}
27 \subsection{\label{ref:Loadinglanguages}Loading Languages}
28 \index{Language files}%
29 Rockbox can load language files at runtime. Simply copy the \fname{.lng} file
30 \emph{(do not use the .lang file)} to the \dap\ and ``play'' it in the
31 Rockbox directory browser or select \setting{Settings $\rightarrow$
32 General Settings $\rightarrow$ Language }from the \setting{Main Menu}.\\
34 \note{If you want a language to be loaded automatically every time you start
35 up, it must be located in the \fname{/.rockbox/langs} directory and the filename
36 must be a maximum of 24 characters long.\\}
38 If your language is not yet supported and you want to write your own language
39 file find the instructions on the Rockbox website:
40 \wikilink{LangFiles}
42 \opt{lcd_color}{
43 \subsection{\label{ref:ChangingFiletypeColours}Changing Filetype Colours}
44 Rockbox has the capability to modify the \setting{File Browser} to show
45 files of different types in different colours, depending on the file extension.
47 \subsubsection{Set-up}
48 There are two steps to changing the filetype colours -- creating
49 a file with the extension \fname{.colours} and then activating it using
50 a config file. The \fname{.colours} files \emph{must} be stored in
51 the \fname{/.rockbox/themes/} directory.
52 The \fname{.colours} file is just a text file, and can be edited with
53 your text editor of choice.
55 \subsubsection{Creating the .colours file}
56 The \fname{.colours} file consists of the file extension
57 (or \fname{folder}) followed by a colon and then the colour desired
58 as an RGB value in hexadecimal, as in the following example:\\*
60 \config{folder:808080}\\
61 \config{mp3:00FF00}\\
62 \config{ogg:00FF00}\\
63 \config{txt:FF0000}\\
64 \config{???:FFFFFF}\\*
66 The permissible extensions are as follows:\\*
67 \\
68 \config{folder, m3u, m3u8, cfg, wps, lng, rock, bmark, cue, colours, mpa,
69 \firmwareextension{}, %
70 \opt{swcodec}{mp1, }mp2, mp3%
71 \opt{swcodec}{, ogg, oga, wma, wmv, asf, wav, flac, ac3, a52, mpc,
72 wv, m4a, m4b, mp4, mod, shn, aif, aiff, spx, sid, adx, nsf, nsfe,
73 spc, ape, mac, sap}%
74 \opt{lcd_bitmap}{\opt{swcodec}{, mpg, mpeg}}%
75 \opt{HAVE_REMOTE_LCD}{, rwps}%
76 \opt{lcd_non-mono}{, bmp}%
77 \opt{radio}{, fmr}%
78 \opt{lcd_bitmap}{, fnt, kbd}}\\*
79 %It'd be ideal to get these from filetypes.c
81 All file extensions that are not either specifically listed in the
82 \fname{.colours} files or are not in the list above will be
83 set to the colour given by \config{???}. Extensions that
84 are in the above list but not in the \fname{.colours}
85 file will be set to the foreground colour as normal.
87 \subsubsection{Activating}
88 To activate the filetype colours, the \fname{.colours} file needs to be
89 invoked from a \fname{.cfg} configuration file. The easiest way to do
90 this is to create a new text file containing the following single
91 line:\\*
93 \config{filetype colours: /.rockbox/themes/filename.colours}\\*
95 where filename is replaced by the filename you used when creating the
96 \fname{.colours} file. Save this file as e.g. \fname{colours.cfg} in the
97 \fname{/.rockbox/themes} directory and then activate the config file
98 from the menu as normal
99 (\setting{Settings} $\rightarrow$ \setting{Theme Settings}%
100 $\rightarrow$ \setting{Browse Theme Files}).
102 \subsubsection{Editing}
103 The built-in \setting{Text Editor} (see \reference{sec:text_editor})
104 automatically understands the
105 \fname{.colours} file format, but an external text editor can
106 also be used. To edit the \fname{.colours} file using Rockbox,
107 ``play'' it in the \setting{File Browser}. The file will open in
108 the \setting{Text Editor}. Upon selecting a line, the following choices
109 will appear:\\*
111 \config{Extension}\\
112 \config{Colour}\\*
114 If \config{Extension} is selected, the \setting{virtual keyboard}
115 (see \reference{sec:virtual_keyboard}) appears,
116 allowing the file extension to be modified. If \config{Colour}
117 is selected, the colour selector screen appears. Choose the desired
118 colour, then save the \fname{.colours} file using the standard
119 \setting{Text Editor} controls.
122 \opt{lcd_non-mono}{%
123 \subsection{\label{ref:LoadingBackdrops}Loading Backdrops}
124 Rockbox supports showing an image as a backdrop in the \setting{File Browser}
125 and the menus. The backdrop image must be a \fname{.bmp} file of the exact
126 same dimensions as the display in your \dap{} (\genericimg{} with the last
127 number giving the colour depth in bits). To use an image as a backdrop browse
128 to it in the \setting{File Browser} and open the \setting{Context Menu}
129 (see \reference{ref:Contextmenu}) on it and select the option
130 \setting{Set As Backdrop}. If you want rockbox to remember your
131 backdrop the next time you start your \dap{} the backdrop must be placed in
132 the \fname{/.rockbox/backdrops} directory.
135 \nopt{lcd_charcell}{
136 \subsection{UI Viewport}
137 By default, the UI is drawn on the whole screen. This can be changed so that
138 the UI is confined to a specific area of the screen, by use of a UI
139 viewport. This is done by adding the following line to the
140 \fname{.cfg} file for a theme:\\*
142 \nopt{lcd_non-mono}{\config{ui viewport: X,Y,[width],[height],[font]}}
143 \nopt{lcd_color}{\opt{lcd_non-mono}{
144 \config{ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}}
145 \opt{lcd_color}{
146 \config{ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}}
149 \opt{HAVE_REMOTE_LCD}{
150 The dimensions of the menu that is displayed on the remote control of your
151 \dap\ can be set in the same way. The line to be added to the theme
152 \fname{.cfg} is the following:\\*
154 \nopt{lcd_non-mono}{\config{remote ui viewport: X,Y,[width],[height],[font]}}
155 \nopt{lcd_color}{\opt{lcd_non-mono}{
156 \config{remote ui viewport: X,Y,[width],[height],[font],[fgshade],[bgshade]}}}
157 \opt{lcd_color}{
158 \config{remote ui viewport: X,Y,[width],[height],[font],[fgcolour],[bgcolour]}}
162 Only the first two parameters \emph{have} to be specified, the others can
163 be omitted using `-' as a placeholder. The syntax is very similar to WPS
164 viewports (see \reference{ref:Viewports}). Briefly:
166 \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-uivp-syntax.tex}}
167 \nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-uivp-syntax.tex}}}
168 \opt{lcd_color}{\input{advanced_topics/viewports/colour-uivp-syntax.tex}}
171 \section{\label{ref:ConfiguringtheWPS}Configuring the WPS}
173 \subsection{WPS -- General Info}
175 \begin{description}
176 \item[Description: ] The WPS or \setting{While Playing Screen} is the name used
177 to describe the information displayed on the \daps{} screen whilst an audio
178 track is being played. The default WPS is a relatively simple screen
179 displaying Track name, Artist, Album etc. in the default font as a purely
180 text based layout. There are a number of WPS files included in Rockbox, and
181 you can load one of these at any time by selecting it in
182 \setting{Settings $\rightarrow$ Theme Settings $\rightarrow$ While Playing Screen}.
183 \opt{HAVE_REMOTE_LCD}{There is a related option to browse \fname{.rwps}
184 files for \daps{} with LCD remote controls installed. This will load a
185 similar WPS screen for the remote.}
187 \note{``Playing'' a \fname{.wps} from the \setting{File Browser} has the same effect.}
189 \item [File Location: ]Custom WPS files may be located anywhere on the drive.
190 The only restriction is that they must end in \fname{.wps}. When you ``play''
191 a \fname{.wps} file, it will be used for future WPS screens, and if the
192 ``played'' \fname{.wps} file is located in the \fname{/.rockbox/wps} directory, it
193 will be remembered and used after reboot. The name of the \fname{.wps} file must be
194 no more than 24 characters long for it to be remembered.
195 \end{description}
197 \subsection{\label{ref:CreateYourOwnWPS}WPS -- Build Your Own}
198 Quite simply, enter the WPS code in your favourite text editor, Notepad on
199 Windows works fine. When you save it, instead of saving it as a \fname{.txt}
200 file, save it as a \fname{.wps} file. Example: Instead of \fname{Rockbox.txt},
201 save the file as \fname{Rockbox.wps}. To make sure non english characters
202 display correctly in your WPS you must save the .wps file with UTF-8 character
203 encoding. This can be done in most editors, for example Notepad in Windows 2000
204 or XP (but not in 9x/ME) can do this. See appendix \reference{ref:wps_tags} for
205 all the tags that are available.
207 \begin{itemize}
208 \item All characters not preceded by \% are displayed as typed.
209 \item Lines beginning with \# are comments and will be ignored.
210 \end{itemize}
212 \note{Keep in mind that your \dap{} resolution is \genericimg{} (with
213 the last number giving the colour depth in bits) when
214 designing your own WPS, or if you use a WPS designed for another target.
215 \opt{HAVE_REMOTE_LCD}{The resolution of the remote is
216 \opt{h100,h300}{128x64x1}\opt{x5,m5}{128x96x2} pixels.}}
218 \nopt{lcd_charcell}{
219 \subsubsection{\label{ref:Viewports}Viewports}
221 By default, a viewport filling the whole screen contains all the elements
222 defined in the \fname(.wps) file. The
223 \opt{lcd_non-mono}{elements in this viewport are displayed
224 with the same background/foreground
225 \opt{lcd_color}{colours}\nopt{lcd_color}{shades} and the}
226 text is rendered in the
227 same font as in the main menu. To change this behaviour a custom viewport can
228 be defined. A viewport is a rectangular window on the screen%
229 \opt{lcd_non-mono}{ with its own foreground/background
230 \opt{lcd_color}{colours}\nopt{lcd_color}{shades}}.
231 This window also has variable dimensions. To
232 define a viewport a line starting \config{{\%V{\textbar}\dots}} has to be
233 present in the \fname{.wps} file. The full syntax will be explained later in
234 this section. All elements placed before the
235 line defining a viewport are displayed in the default viewport. Elements
236 defined after a viewport declaration are drawn within that viewport.
237 \opt{lcd_bitmap}{Loading images (see Appendix \reference{ref:wps_images})
238 should be done within the default viewport.}
239 A viewport ends either with the end of the file, or with the next viewport
240 declaration line. Viewports sharing the same
241 coordinates and dimensions cannot be displayed at the same time. Viewports
242 cannot be layered \emph{transparently} over one another. Subsequent viewports
243 will be drawn over any other viewports already drawn onto that
244 area of the screen.
246 \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-vp-syntax.tex}}
247 \nopt{lcd_color}{\opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-vp-syntax.tex}}}
248 \opt{lcd_color}{\input{advanced_topics/viewports/colour-vp-syntax.tex}}
251 \subsubsection{Conditional Viewports}
253 Any viewport can be displayed either permanently or conditionally.
254 Defining a viewport as \config{{\%V{\textbar}\dots}}
255 will display it permanently.
257 \begin{itemize}
258 \item {\config{\%Vl{\textbar}'identifier'{\textbar}\dots{\textbar}}}
259 This tag preloads a viewport for later display. `identifier' is a single
260 lowercase letter (a-z) and the '\dots' parameters use the same logic as
261 the \config{\%V} tag explained above.
262 \item {\config{\%Vd'identifier'}} Display the 'identifier' viewport.
263 \end{itemize}
265 Viewports can share identifiers so that you can display multiple viewports
266 with one \%Vd line.
268 \nopt{lcd_non-mono}{\input{advanced_topics/viewports/mono-conditional.tex}}
269 \nopt{lcd_color}{%
270 \opt{lcd_non-mono}{\input{advanced_topics/viewports/grayscale-conditional.tex}}}
271 \opt{lcd_color}{\input{advanced_topics/viewports/colour-conditional.tex}}
274 \note{The tag to display conditional viewports must come before the tag to
275 preload the viewport in the \fname{.wps} file.}
278 \subsubsection{Conditional Tags}
280 \begin{description}
281 \item[If/else: ]
282 Syntax: \config{\%?xx{\textless}true{\textbar}false{\textgreater}}
284 If the tag specified by ``\config{xx}'' has a value, the text between the
285 ``\config{{\textless}}'' and the ``\config{{\textbar}}'' is displayed (the true
286 part), else the text between the ``\config{{\textbar}}'' and the
287 ``\config{{\textgreater}}'' is displayed (the false part).
288 The else part is optional, so the ``\config{{\textbar}}'' does not have to be
289 specified if no else part is desired. The conditionals nest, so the text in the
290 if and else part can contain all \config{\%} commands, including conditionals.
292 \item[Enumerations: ]
293 Syntax: \config{\%?xx{\textless}alt1{\textbar}alt2{\textbar}alt3{\textbar}\dots{\textbar}else{\textgreater}}
295 For tags with multiple values, like Play status, the conditional can hold a
296 list of alternatives, one for each value the tag can have.
297 Example enumeration:
298 \begin{example}
299 \%?mp{\textless}Stop{\textbar}\%Play{\textbar}Pause{\textbar}Ffwd{\textbar}Rew{\textgreater}
300 \end{example}
302 The last else part is optional, and will be displayed if the tag has no value.
303 The WPS parser will always display the last part if the tag has no value, or if
304 the list of alternatives is too short.
305 \end{description}
307 \subsubsection{Next Song Info}
308 You can display information about the next song -- the song that is
309 about to play after the one currently playing (unless you change the
310 plan).
312 If you use the upper-case versions of the
313 three tags: \config{F}, \config{I} and \config{D}, they will instead refer to
314 the next song instead of the current one. Example: \config{\%Ig} is the genre
315 name used in the next song and \config{\%Ff} is the mp3 frequency.\\
317 \note{The next song information \emph{will not} be available at all
318 times, but will most likely be available at the end of a song. We
319 suggest you use the conditional display tag a lot when displaying
320 information about the next song!}
322 \subsubsection{\label{ref:AlternatingSublines}Alternating Sublines}
324 It is possible to group items on each line into 2 or more groups or
325 ``sublines''. Each subline will be displayed in succession on the line for a
326 specified time, alternating continuously through each defined subline.
328 Items on a line are broken into sublines with the semicolon
329 '\config{;}' character. The display time for
330 each subline defaults to 2 seconds unless modified by using the
331 '\config{\%t}' tag to specify an alternate
332 time (in seconds and optional tenths of a second) for the subline to be
333 displayed.
335 Subline related special characters and tags:
336 \begin{description}
337 \item[;] Split items on a line into separate sublines
338 \item[\%t] Set the subline display time. The
339 '\config{\%t}' is followed by either integer
340 seconds (\config{\%t5}), or seconds and tenths of a second (\config{\%t3.5}).
341 \end{description}
343 Each alternating subline can still be optionally scrolled while it is
344 being displayed, and scrollable formats can be displayed on the same
345 line with non{}-scrollable formats (such as track elapsed time) as long
346 as they are separated into different sublines.
347 Example subline definition:
348 \begin{example}
349 %s%t4%ia;%s%it;%t3%pc %pr : Display id3 artist for 4 seconds,
350 Display id3 title for 2 seconds,
351 Display current and remaining track time
352 for 3 seconds,
353 repeat...
354 \end{example}
356 Conditionals can be used with sublines to display a different set and/or number
357 of sublines on the line depending on the evaluation of the conditional.
358 Example subline with conditionals:
359 \begin{example}
360 %?it{\textless}%t8%s%it{\textbar}%s%fn{\textgreater};%?ia{\textless}%t3%s%ia{\textbar}%t0{\textgreater}\\
361 \end{example}
363 The format above will do two different things depending if ID3 tags are
364 present. If the ID3 artist and title are present:
365 \begin{itemize}
366 \item Display id3 title for 8 seconds,
367 \item Display id3 artist for 3 seconds,
368 \item repeat\dots
369 \end{itemize}
370 If the ID3 artist and title are not present:
371 \begin{itemize}
372 \item Display the filename continuously.
373 \end{itemize}
374 Note that by using a subline display time of 0 in one branch of a conditional,
375 a subline can be skipped (not displayed) when that condition is met.
377 \subsubsection{Using Images}
378 You can have as many as 52 images in your WPS. There are various ways of
379 displaying images:
380 \begin{enumerate}
381 \item Load and always show the image, using the \config{\%x} tag
382 \item Preload the image with \config{\%xl} and show it with \config{\%xd}.
383 This way you can have your images displayed conditionally.
384 \nopt{archos}{%
385 \item Load an image and show as backdrop using the \config{\%X} tag. The
386 image must be of the same exact dimensions as your display.
388 \end{enumerate}
390 \optv{swcodec}{% This doesn't depend on swcodec but we don't have a \noptv
391 % command.
392 Example on background image use:
393 \begin{example}
394 %X|background.bmp|
395 \end{example}
396 The image with filename \fname{background.bmp} is loaded and used in the WPS.
399 Example on bitmap preloading and use:
400 \begin{example}
401 %x|a|static_icon.bmp|50|50|
402 %xl|b|rep\_off.bmp|16|64|
403 %xl|c|rep\_all.bmp|16|64|
404 %xl|d|rep\_one.bmp|16|64|
405 %xl|e|rep\_shuffle.bmp|16|64|
406 %?mm<%xdb|%xdc|%xdd|%xde>
407 \end{example}
408 Four images at the same x and y position are preloaded in the example. Which
409 image to display is determined by the \config{\%mm} tag (the repeat mode).
411 \subsubsection{Example File}
412 \begin{example}
413 %s%?in<%in - >%?it<%it|%fn> %?ia<[%ia%?id<, %id>]>
414 %pb%pc/%pt
415 \end{example}
416 That is, ``tracknum -- title [artist, album]'', where most fields are only
417 displayed if available. Could also be rendered as ``filename'' or ``tracknum --
418 title [artist]''.
420 %\opt{lcd_bitmap}{
421 % \begin{verbatim}
422 % %s%?it<%?in<%in. |>%it|%fn>
423 % %s%?ia<%ia|%?d2<%d2|(root)>>
424 % %s%?id<%id|%?d1<%d1|(root)>> %?iy<(%iy)|>
426 % %al%pc/%pt%ar[%pp:%pe]
427 % %fbkBit %?fv<avg|> %?iv<(id3v%iv)|(no id3)>
428 % %pb
429 % %pm
430 % % \end{verbatim}
433 \section{\label{ref:manage_settings}Managing Rockbox Settings}
435 \subsection{Introduction to \fname{.cfg} Files}
436 Rockbox allows users to store and load multiple settings through the use of
437 configuration files. A configuration file is simply a text file with the
438 extension \fname{.cfg}.
440 A configuration file may reside anywhere on the disk. Multiple
441 configuration files are permitted. So, for example, you could have
442 a \fname{car.cfg} file for the settings that you use while playing your
443 jukebox in your car, and a \fname{headphones.cfg} file to store the
444 settings that you use while listening to your \dap{} through headphones.
446 See \reference{ref:cfg_specs} below for an explanation of the format
447 for configuration files. See \reference{ref:manage_settings_menu} for an
448 explanation of how to create, edit and load configuration files.
450 \subsection{\label{ref:cfg_specs}Specifications for \fname{.cfg} Files}
452 The Rockbox configuration file is a plain text file, so once you use the
453 \setting{Save .cfg file} option to create the file, you can edit the file on
454 your computer using any text editor program. See
455 Appendix \reference{ref:config_file_options} for available settings. Configuration
456 files use the following formatting rules: %
458 \begin{enumerate}
459 \item Each setting must be on a separate line.
460 \item Each line has the format ``setting: value''.
461 \item Values must be within the ranges specified in this manual for each
462 setting.
463 \item Lines starting with \# are ignored. This lets you write comments into
464 your configuration files.
465 \end{enumerate}
467 Example of a configuration file:
468 \begin{example}
469 volume: 70
470 bass: 11
471 treble: 12
472 balance: 0
473 time format: 12hour
474 volume display: numeric
475 show files: supported
476 wps: /.rockbox/car.wps
477 lang: /.rockbox/afrikaans.lng
478 \end{example}
480 \note{As you can see from the example, configuration files do not need to
481 contain all of the Rockbox options. You can create configuration files
482 that change only certain settings. So, for example, supppose you
483 typically use the \dap{} at one volume in the car, and another when using
484 headphones. Further, suppose you like to use an inverse LCD when you are
485 in the car, and a regular LCD setting when you are using headphones. You
486 could create configuration files that control only the volume and LCD
487 settings. Create a few different files with different settings, give
488 each file a different name (such as \fname{car.cfg},
489 \fname{headphones.cfg}, etc.), and you can then use the \setting{Browse .cfg
490 files} option to quickly change settings.\\}
492 A special case configuration file can be used to force a particular setting
493 or settings every time Rockbox starts up (e.g. to set the volume to a safe
494 level). Format a new configuration file as above with the required setting(s)
495 and save it into the \fname{/.rockbox} directory with the filename
496 \fname{fixed.cfg}.
498 \subsection{\label{ref:manage_settings_menu}The \setting{Manage Settings}
499 menu} The \setting{Manage Settings} menu can be found in the \setting{Main
500 Menu}. The \setting{Manage Settings} menu allows you to save and load
501 \fname{.cfg} files.
503 \begin{description}
505 \item [Browse .cfg Files]Opens the \setting{File Browser} in the
506 \fname{/.rockbox} directory and displays all \fname{.cfg} (configuration)
507 files. Selecting a \fname{.cfg} file will cause Rockbox to load the settings
508 contained in that file. Pressing \nopt{COWON_D2_PAD}{\ButtonLeft}
509 \opt{COWON_D2_PAD}{\ButtonPower{} or \TouchTopLeft} will exit back to the
510 \setting{Manage Settings} menu. See the \setting{Write .cfg files} option on
511 the \setting{Manage Settings} menu for details of how to save and edit a
512 configuration file.
514 \item [Reset Settings]This wipes the saved settings
515 in the \dap{} and resets all settings to their default values.
518 \note{You can also reset all settings to their default
519 values by turning off the \dap, turning it back on, and holding the
520 \ButtonRec{} button immediately after the \dap{} turns on.}
522 \opt{IRIVER_H10_PAD}{\note{You can also reset all settings to
523 their default values by turning off the \dap, and turning it back on
524 with the \ButtonHold{} button on.}
526 \opt{IPOD_4G_PAD}{\note{You can also reset all settings to their default
527 values by turning off the \dap, turning it back on, and activating the
528 \ButtonHold{} button immediately after the backlight comes on.}
530 \opt{GIGABEAT_PAD}{\note{You can also reset all settings to their default
531 values by turning off the \dap, turning it back on and pressing the
532 \ButtonA{} button immediately after the \dap{} turns on.}
535 \item [Save .cfg File]This option writes a \fname{.cfg} file to
536 your \daps{} disk. The configuration file has the \fname{.cfg}
537 extension and is used to store all of the user settings that are described
538 throughout this manual.
540 Hint: Use the \setting{Save .cfg File} feature (\setting{Main Menu
541 $\rightarrow$ Manage Settings}) to save the current settings, then
542 use a text editor to customize the settings file. See Appendix
543 \reference{ref:config_file_options} for the full reference of available
544 options.
546 \item [Save Sound Settings]This option writes a \fname{.cfg} file to
547 your \daps{} disk. The configuration file has the \fname{.cfg}
548 extension and is used to store all of the sound related settings.
550 \item [Save Theme Settings]This option writes a \fname{.cfg} file to
551 your \daps{} disk. The configuration file has the \fname{.cfg}
552 extension and is used to store all of the theme related settings.
554 \end{description}
556 \section{\label{ref:FirmwareLoading}Firmware Loading}
557 \opt{player,recorder,recorderv2fm,ondio}{
558 When your \dap{} powers on, it loads the Archos firmware in ROM, which
559 automatically checks your \daps{} root directory for a file named
560 \firmwarefilename. Note that Archos firmware can only read the first
561 ten characters of each filename in this process, so do not rename your old
562 firmware files with names like \firmwarefilename.\fname{old} and so on,
563 because it is possible that the \dap{} will load a file other than the one
564 you intended.
567 \subsection{\label{ref:using_rolo}Using ROLO (Rockbox Loader)}
568 Rockbox is able to load and start another firmware file without rebooting.
569 You just ``play'' a file with the extension %
570 \opt{recorder,recorderv2fm,ondio}{\fname{.ajz}.} %
571 \opt{player}{\fname{.mod}.} %
572 \opt{h100,h300}{\fname{.iriver}.} %
573 \opt{ipod}{\fname{.ipod}.} %
574 \opt{iaudio}{\fname{.iaudio}.} %
575 \opt{sansa,h10,h10_5gb,vibe500}{\fname{.mi4}.} %
576 \opt{sansaAMS}{\fname{.sansa}.} %
577 \opt{gigabeatf,gigabeats}{\fname{.gigabeat}.} %
578 This can be used to test new firmware versions without deleting your
579 current version.
581 \opt{archos}{\input{advanced_topics/archos-flashing.tex}}
583 \section{Optimising battery runtime}
584 Rockbox offers a lot of settings that have high impact on the battery runtime
585 of your \dap{}. The largest power savings can be achieved through disabling
586 unneeded hardware components -- for some of those there are settings
587 available.
588 \opt{swcodec}{
589 Another area of savings is avoiding or reducing CPU boosting
590 through disabling computing intense features (e.g. sound processing) or
591 using effective audio codecs.
592 } The following provides a short overview of the most relevant settings and
593 rules of thumb.
595 \nopt{ondio}{
596 \subsection{Display backlight}
597 The active backlight consumes a lot of power. Therefore choose a setting that
598 disables the backlight after timeout (for setting \setting{Backlight} see
599 \reference{ref:Displayoptions}). Avoid to have the backlight enabled all the
600 time.
603 \opt{lcd_sleep}{
604 \subsection{Display power-off}
605 Shutting down the display and the display controller saves a reasonable amount
606 of power. Choose a setting that will put the display to sleep after timeout
607 (for setting \setting{Sleep} see \reference{ref:Displayoptions}). Avoid to
608 have the display enabled all the time -- even, if the display is transflective
609 and is readable without backlight. Depending on your \dap{} it might be
610 significantly more efficient to re-enable the display and its backlight for a
611 glimpse a few times per hour than to keep the display enabled.
614 \opt{accessory_supply}{
615 \subsection{Accessory power supply}
616 As default your \dap{}'s accessory power supply is always enabled to ensure
617 proper function of connected accessory devices. Disable this power supply, if
618 -- or as long as -- you do not use any accessory device with your \dap{} while
619 running Rockbox (see \reference{ref:AccessoryPowerSupply}).
622 \opt{lineout_poweroff}{
623 \subsection{Line Out}
624 Rockbox allows to switch off the line-out on your \dap{}. If you do not need
625 the line-out, switch it off (see \reference{ref:LineoutOnOff}).
628 \opt{spdif_power}{
629 \subsection{Optical Output}
630 Rockbox allows to switch off the S/PDIF output on your \dap{}. If you do not
631 need this output, switch it off (see \reference{ref:SPDIF_OnOff}).
634 \opt{disk_storage}{
635 \subsection{Anti-Skip Buffer}
636 Having a large anti-skip buffer tends to use more power, and may reduce your
637 battery life. It is recommended to always use the lowest possible setting
638 that allows correct and continuous playback (see \reference{ref:AntiSkipBuf}).
641 \opt{swcodec}{
642 \subsection{Replaygain}
643 Replaygain is a post processing that equalises the playback volume of audio
644 files to the same perceived loudness. This post processing applies a factor
645 to each single PCM sample and is therefore consuming additional CPU time. If
646 you want to achieve some (minor) savings in runtime, switch this feature off
647 (see \reference{ref:ReplayGain}).
650 \opt{swcodec,disk_storage,flash_storage}{
651 \subsection{Audio format and bitrate}
652 \opt{swcodec}{
653 In general the fastest decoding audio format will be the best in terms of
654 battery runtime on your \dap{}. An overview of different codec's performance
655 on different \dap{}s can be found at \wikilink{CodecPerformanceComparison}.
658 \opt{flash_storage}{
659 Your target uses flash that consumes a certain amount of power during access.
660 The less often the flash needs to be switched on for buffering and the shorter
661 the buffering duration is, the lower is the overall power consumption.
662 Therefore the bitrate of the audio files does have an impact on the battery
663 runtime as well. Lower bitrate audio files will result in longer battery
664 runtime.
666 \opt{disk_storage}{
667 Your target uses a hard disk which consumes a large amount of power while
668 spinning -- up to several hundred mA. The less often the hard disk needs to
669 spin up for buffering and the shorter the buffering duration is, the lower is
670 the power consumption. Therefore the bitrate of the audio files does have an
671 impact on the battery runtime as well. Lower bitrate audio files will result
672 in longer battery runtime.
675 Please do not re-encode any existing audio files from one lossy format to
676 another based upon the above mentioned. This will reduce the audio quality.
677 If you have the choice, select the best suiting codec when encoding the
678 original source material.
681 \opt{swcodec}{
682 \subsection{Sound settings}
683 In general all kinds of sound processing will need more CPU time and therefore
684 consume more power. The less sound processing you use, the better it is for
685 the battery runtime (for options see \reference{ref:configure_rockbox_sound}).