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