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, Genre,
  10 Song Name, etc.  The criteria the database uses to sort the songs can be completely
  11  customised. More information on how to achieve this can be found on the Rockbox
  12  website at \wikilink{DataBase}.
  13
  14 \subsection{Initializing the Database}
  15 The first time you use the database, Rockbox will scan your disk for audio files.
  16 This can take quite a while depending on the number of files on your \dap{}.
  17 This scan happens in the background, so you can choose to return to the
  18 Main Menu and continue to listen to music.
  19 If you shut down your player, the scan will continue next time you turn it on.
  20 After the scan is finished you may be prompted to restart your \dap{} before
  21 you can use the database.
  22
  23 \subsubsection{Ignoring Directories During Database Initialization}
  24
  25 You may have directories on your \dap{} whose contents should not be added
  26 to the database. Placing a file named \fname{database.ignore} in a directory
  27 will exclude the files in that directory and all its subdirectories from
  28 scanning their tags and adding them to the database. This will speed up the
  29 database initialization.
  30
  31 If a subdirectory of an `ignored' directory should still be scanned, place a
  32 file named \fname{database.unignore} in it. The files in that directory and
  33 its subdirectories will be scanned and added to the database.
  34
  35 \subsection{\label{ref:databasemenu}The Database Menu}
  36
  37 \begin{description}
  38   \opt{tc_ramcache}{
  39   \item[Load To RAM]
  40     The database can either be kept on \disk{} (to save memory), or
  41     loaded into RAM (for fast browsing). Setting this to \setting{Yes} loads
  42     the database to RAM, allowing faster browsing and searching. Setting this
  43     option to \setting{No} keeps the database on the \disk{}, meaning slower
  44     browsing but it does not use extra RAM and saves some battery on boot up.
  45
  46     \opt{HAVE_DISK_STORAGE}{
  47     \note{If you browse your music frequently using the database, you should
  48       load to RAM, as this will reduce the overall battery consumption because
  49       the disk will not need to spin on each search.}
  50     }
  51   }
  52
  53 \item[Auto Update]
  54   If \setting{Auto update} is set to \setting{on}, each time the \dap{}
  55   boots, the database will automatically be updated.
  56   \opt{swcodec}{
  57     \note{The \setting{Auto Update} will only check for deleted files if the
  58       \setting{Directory Cache} (\setting{Settings $\rightarrow$ General
  59       Settings $\rightarrow$ System $\rightarrow$ Disk $\rightarrow$
  60       Directory Cache}) is enabled. \setting{Update now} includes that check
  61       whether dircache has been enabled or not.}
  62   }%
  63
  64 \item[Initialize Now]
  65   You can force Rockbox to rescan your disk for tagged files by
  66   using the \setting{Initialize Now} function in the \setting{Database
  67     Menu}.
  68   \warn{\setting{Initialize Now} removes all database files (removing
  69     runtimedb data also) and rebuilds the database from scratch.}
  70
  71 \item[Update Now]
  72   \setting{Update now} causes the database to detect new and deleted files
  73   \opt{swcodec}{
  74     \note{Unlike the \setting{Auto Update} function, \setting{Update Now}
  75       will update the database regardless of whether the \setting{Directory Cache}
  76       is enabled. Thus, an update using \setting{Update now} may take a long
  77       time.
  78     }
  79   }
  80   Unlike \setting{Initialize Now}, the \setting{Update Now} function
  81   does not remove runtime database information.
  82
  83 \item[Gather Runtime Data]
  84   When enabled, rockbox will record how often and how long a track is being played,
  85   when it was last played and its rating. This information can be displayed in
  86   the WPS and is used in the database browser to, for example, show the most played,
  87   unplayed and most recently played tracks.
  88
  89 \item[Export Modifications]
  90   This allows for the runtime data to be exported to the file \\
  91   \fname{/.rockbox/database\_changelog.txt}, which backs up the runtime data in
  92   ASCII format. This is needed when database structures change, because new
  93   code cannot read old database code. But, all modifications
  94   exported to ASCII format should be readable by all database versions.
  95
  96 \item[Import Modifications.]
  97   Allows the \fname{/.rockbox/database\_changelog.txt} backup to be
  98   conveniently loaded into the database. If \setting{Auto Update} is
  99   enabled this is performed automatically when the database is initialized.
 100
 101 \end{description}
 102
 103 \subsection{Using the Database}
 104 Once the database has been initialized, you can browse your music
 105 by Artist, Album, Genre, Song Name, etc.  To use the database, go to the
 106  \setting{Main Menu} and select \setting{Database}.\\
 107
 108 \note{You may need to increase the value of the \setting{Max files in dir
 109 browser} setting (\setting{Settings $\rightarrow$ General Settings
 110 $\rightarrow$ System $\rightarrow$ Limits}) in order to view long lists of
 111 tracks in the ID3 database browser.\\
 112
 113 There is no option to turn off database completely. If you do not want
 114 to use it just do not do the initial build of the database and do not load it
 115 to RAM.}%
 116
 117 \begin{table}
 118   \begin{rbtabular}{.75\textwidth}{XXX}%
 119   {\textbf{Tag}   & \textbf{Type}  & \textbf{Origin}}{}{}
 120   filename              & string    & system \\
 121   album                 & string    & id tag \\
 122   albumartist           & string    & id tag \\
 123   artist                & string    & id tag \\
 124   comment               & string    & id tag \\
 125   composer              & string    & id tag \\
 126   genre                 & string    & id tag \\
 127   grouping              & string    & id tag \\
 128   title                 & string    & id tag \\
 129   bitrate               & numeric   & id tag \\
 130   discnum               & numeric   & id tag \\
 131   year                  & numeric   & id tag \\
 132   tracknum              & numeric   & id tag/filename \\
 133   autoscore             & numeric   & runtime db \\
 134   lastplayed            & numeric   & runtime db \\
 135   playcount             & numeric   & runtime db \\
 136   Pm (play time - min)  & numeric   & runtime db \\
 137   Ps (play time - sec)  & numeric   & runtime db \\
 138   rating                & numeric   & runtime db \\
 139   commitid              & numeric   & system \\
 140   entryage              & numeric   & system \\
 141   length                & numeric   & system \\
 142   Lm (track len - min)  & numeric   & system \\
 143   Ls (track len - sec)  & numeric   & system \\
 144   \end{rbtabular}
 145 \end{table}