manual/rockbox_interface/tagcache.tex

   1 % $Id$ %
   2 \section{\label{ref:database}Database}
   3
   4 \subsection{Introduction}
   5 This chapter describes the Rockbox music database system. Using the information
   6 contained in the tags (ID3v1, ID3v2%
   7   \opt{SWCODEC}{, Vorbis Comments, Apev2, etc.}%
   8 ) in your audio files, Rockbox builds and maintains a database of the music
   9 files on your player and allows you to browse them by Artist, Album and Genre.
  10
  11 \subsection{Initializing the database}
  12 The first time you use the database, Rockbox will scan your disk for audio files.
  13 This can take quite a while depending on the number of files on your \dap{}.
  14 This scan happens in the background, so you can choose to return to the
  15 Main Menu and continue to listen to music.
  16 If you shut down your player, the scan will continue next time you turn it on.
  17 After the scan is finished you may be prompted to restart your \dap{} before
  18 you can use the database.
  19
  20 \subsection{\label{ref:databasemenu}The Database Menu}
  21
  22 \begin{description}
  23   \opt{SWCODEC}{
  24   \item[Load To Ram.]
  25     The database can either be kept on disk (to save memory), or
  26     loaded into RAM (for fast browsing). Setting this to \setting{Yes} loads
  27     the database to RAM, allowing faster browsing and searching. Setting this
  28     option to \setting{No} keeps the database on the disk, meaning slower
  29     browsing but it does not use extra RAM and saves some battery on boot up.
  30
  31     \note{If you browse your music frequently using the database, you should
  32       load to RAM, as this will reduce the overall battery consumption because
  33       the disk will not need to spin on each search.}
  34   }
  35
  36 \item[Auto Update.]
  37   If \setting{Auto update} is set to \setting{on}, each time the \dap{}
  38   boots, the database will automatically be updated.
  39   \opt{SWCODEC}{
  40     \note{The \setting{Auto Update} will only check for deleted files if the
  41       \setting{Directory Cache} (\setting{Settings $\rightarrow$ General
  42       Settings $\rightarrow$ System $\rightarrow$ Disk $\rightarrow$
  43       Directory Cache}) is enabled. \setting{Update now} includes that check
  44       whether dircache has been enabled or not.}
  45   }%
  46   \opt{MASCODEC}{\setting{Auto Update} does not detect deleted files. To remove
  47     deleted files from the database you need to run \setting{Update Now}.}%
  48
  49 \item[Initialize Now.]
  50   You can force Rockbox to rescan your disk for tagged files by
  51   using the \setting{Initialize Now} function in the \setting{Database
  52     Menu}.
  53   \warn{\setting{Initialize Now} removes all database files (removing
  54     runtimedb data also) and rebuilds the database from scratch.}
  55
  56 \item[Update Now.]
  57   \setting{Update now} causes the database to detect new and deleted files
  58   \opt{SWCODEC}{
  59     \note{Unlike the \setting{Auto Update} function, \setting{Update Now}
  60       will update the database regardless of whether the \setting{Directory Cache}
  61       is enabled. Thus, an update using \setting{Update now} may take a long
  62       time.
  63     }
  64   }
  65   Unlike \setting{Initialize Now}, the \setting{Update Now} function
  66   does not remove runtime database information.
  67
  68 \item[Gather Runtime Data.]
  69   When enabled, rockbox will record how often and how long a track is being played,
  70   when it was last played and its rating. This information can be displayed in
  71   the WPS and is used in the database browser to, for example, show the most played,
  72   unplayed and most recently played tracks.
  73
  74 \item[Export modifications.]
  75   This allows for the runtime data to be exported to the file \\
  76   \fname{/.rockbox/database\_changelog.txt}, which backs up the runtime data in
  77   ASCII format. This is needed when database structures change, because new
  78   code cannot read old database code. But, all modifications
  79   exported to ASCII format should be readable by all database versions.
  80
  81 \item[Import modifications.]
  82   Allows the \fname{/.rockbox/database\_changelog.txt} backup to be
  83   conveniently loaded into the database. If \setting{Auto Update} is
  84   enabled this is performed automatically when the database is initialized.
  85
  86 \end{description}
  87
  88 \subsection{Using the database}
  89 Once the database has been initialized, you can browse your music by Artist,
  90 Album, Genre and Song Name. To use the database, go to the \setting{Main Menu}
  91 and select \setting{Database}.\\
  92
  93 \note{You may need to increase the value of the \setting{Max files in dir
  94 browser} setting (\setting{Settings $\rightarrow$ General Settings
  95 $\rightarrow$ System $\rightarrow$ Limits}) in order to view long lists of
  96 tracks in the ID3 database browser.\\
  97
  98 There is no option to turn off database completely. If you do not want
  99 to use it just don't do the initial build of the database and do not load it
 100 to RAM.}
 101 %
 102 \begin{table}
 103 \begin{center}
 104   \begin{tabularx}{.75\textwidth}{XX}%
 105   \toprule%
 106   \textbf{Supported Tags}   & \textbf{Unsupported Tags} \\
 107   \midrule
 108   Artist           & Comment \\
 109   Album            & Performer\\
 110   Bitrate          & \\
 111   Composer         & \\
 112   Genre            & \\
 113   Length           & \\
 114   Title            & \\
 115   Track Number     & \\
 116   \bottomrule
 117   \end{tabularx}
 118 \end{center}
 119 \end{table}