% $Id$ %
\section{\label{ref:Voiceconfiguration}Voice}

  \begin{description}
  \item[Voice Menus.]
    This option controls the voicing of menus/settings as they are selected
    by the cursor. In order for this to work, a voice file must be present 
    in the \fname{/.rockbox/langs/} directory on the \dap.  Voice files are large
    and are not shipped with Rockbox by default.
    The voice file is the name of the language for which it is made, followed
    by the extension \fname{.voice}.  So for English, the file name would be 
    \fname{english.voice}.
    This option is on by default, but will do nothing unless the 
    appropriate voice file is installed in the correct place on the \dap.
    The Voice Menus have several limitations:
    \begin{itemize}
    \item Setting the Sound Option \setting{Channels} to \setting{Karaoke} may 
      disable voice menus.
    \item Most plugins \opt{rtc}{and the wake up alarm} do not support
      voice features.
    \item Voice files are checked for compatibility before they are loaded
      by the \dap. A message is displayed on startup ``Failed Reading .voice''
      if the \fname{.voice} file is not the correct version for your \dap.
    \end{itemize}

  \item[Voice Directories.]
    This option controls voicing of directory names. A voice file must be present 
    for this to work. Several options are available.
    \begin{description}
    \item[Spell.]
      Speak the directory name by spelling it out letter by letter.  Support
      is provided only for the most common letters, numbers and punctuation.
    \item[Numbers.]
      Each directory is assigned a number based upon its position in the
      file list.  They are then announced as ``Directory 1'', ``Directory 2''
      etc.
    \item[Off.]
      No attempt will be made to speak directory names.
    \end{description}
    You can use pre-generated .talk clips to have  directory names spoken 
    properly, but you must enable this explicitly (see below).

  \item[Use Directory .talk Clips.]
    This option turns on the use of .talk clips for directories. 
    \begin{description}
    \item[On.]
      Use special pre-recorded files (\fname{\_dirname.talk}) in each 
      directory. These must be generated in advance, and are typically 
      produced synthetically using a text-to-speech engine on a PC.
    \item[Off.]
      No checking is made for directory .talk clips; they are not used even if present.
      This can reduce disk activity.
    \end{description}
    Use of a .talk clip takes precedence over other directory name voicing. Otherwise 
    (e.g. if a .talk clip is not available), voicing uses the method set under 
    \setting{Voice Directories} above.

  \item[Voice Filenames.]
    This option controls voicing of filenames. Again, a voice file must be present 
    for this to work. The options provided are \setting{Spell}, \setting{Numbers}, 
    and \setting{Off} which function the same as for \setting{Voice Directories}.
    You can use pre-generated .talk clips to have filenames spoken properly, but
    you must enable this explicitly (see below).

  \item[Use File .talk Clips.]
    This option turns on the use of .talk clips for files. 
    \begin{description}
    \item[On.]
      Use special pre-recorded files for each file.
      This functions the same as for directories except that the .talk clip file 
      must have the same name as the described file with an extra .talk extension 
      (e.g. \fname{Punkadiddle.mp3} would require a file called \fname{Punkadiddle.mp3.talk}).
    \item[Off.]
      No checking is made for file .talk clips; they are not used even if present.
      This can reduce disk activity.
    \end{description}
    Use of a .talk clip takes precedence over other filename voicing. Otherwise 
    (e.g. if  a .talk clip is not available), voicing uses the method set under
     \setting{Voice Filenames} above.

  \item[Say File Type.]
    This option turns on voicing of file types when \setting{Voice Filenames}
    is set to \setting{Spell} or \setting{Numbers}.
    When \setting{Voice Directories} is set to \setting{Spell}, ``Directory''
    will be voiced after each spelled out directory.

  \item[Announce Battery Level.]
    When this option is enabled the battery level is announced when it falls
    under 50\%, 30\% and 15\%.

  \item[Voice Volume Level.]
    This allows you to specify the relative volume of the voice prompts as
    a percentage of the main audio volume.  It defaults to 100\%.

  \end{description}

See \wikilink{VoiceHowto} for more details on configuring speech support in Rockbox.