| % $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}, \opt{PLAYER_PAD}{\config{shutdown}, }\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. |
| |
| \opt{lcd_bitmap}{ |
| \subsection{\label{ref:GettingExtras}Getting Extras} |
| |
| Rockbox supports custom fonts. A collection of fonts is available for download |
| in the font package at \url{http://www.rockbox.org/daily.shtml}.} |
| |
| \opt{lcd_bitmap}{ |
| \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{}, % |
| \opt{swcodec}{mp1, }mp2, mp3% |
| \opt{swcodec}{, 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}% |
| \opt{lcd_bitmap}{\opt{swcodec}{, mpg, mpeg}}% |
| \opt{HAVE_REMOTE_LCD}{, rwps}% |
| \opt{lcd_non-mono}{, bmp}% |
| \opt{radio}{, fmr}% |
| \opt{lcd_bitmap}{, 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. |
| }% |
| |
| \nopt{lcd_charcell}{ |
| \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. |
| } |
| } |
| |
| \nopt{lcd_charcell}{ |
| \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. |
| \opt{lcd_bitmap}{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. |
| \nopt{archos}{% |
| \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]''. |
| |
| %\opt{lcd_bitmap}{ |
| % \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} |
| \opt{player,recorder,recorderv2fm,ondio}{ |
| When your \dap{} powers on, it loads the Archos firmware in ROM, which |
| automatically checks your \daps{} root directory for a file named |
| \firmwarefilename. Note that Archos firmware can only read the first |
| ten characters of each filename in this process, so do not rename your old |
| firmware files with names like \firmwarefilename.\fname{old} and so on, |
| because it is possible that the \dap{} will load a file other than the one |
| you intended. |
| } |
| |
| \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{recorder,recorderv2fm,ondio}{\fname{.ajz}.} % |
| \opt{player}{\fname{.mod}.} % |
| \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{archos}{\input{advanced_topics/archos-flashing.tex}} |
| |
| \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. |
| \opt{swcodec}{ |
| 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. |
| |
| \nopt{ondio}{ |
| \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 to have the backlight enabled all the |
| time. |
| } |
| |
| \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}). |
| } |
| |
| \opt{swcodec}{ |
| \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}). |
| } |
| |
| \opt{lcd_bitmap}{ |
| \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.} |
| } |
| } |
| |
| \opt{swcodec,disk_storage,flash_storage}{ |
| \subsection{Audio format and bitrate} |
| \opt{swcodec}{ |
| 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. |
| } |
| |
| \opt{swcodec}{ |
| \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}). |
| } |