% $Id$ %
\section{\label{ref:PlaybackOptions}Playback Options}
The \setting{Playback Options} submenu allows you to configure settings
related to audio playback.
\begin{description}
\item[Shuffle. ]Alters how Rockbox will select which song to play next.\\
  Options: \setting{Yes}/\setting{No}.
  %
\item[Repeat. ]Configures settings related to repeating of directories or
  playlists.\\
  Options: \setting{Off} / \setting{All} / \setting{One} / \setting{Shuffle}
  \nopt{ondiosp,ondiofm}{\setting{/A-B}}:
  \begin{description}
    %
  \item[Off. ]The current directory or playlist will not repeat
    when it is finished.
    \note{If you have the \setting{Auto change directory} option set to
      \setting{Yes}, Rockbox will move on to the next directory on your
      hard drive. If the \setting{Auto Change Directory} option is set to
      \setting{No}, playback will stop when the current directory or
      playlist is finished.}
    %
  \item[All. ]The current directory or playlist will repeat when it is
    finished.
    \note{This option does \emph{not} shuffle all files on your \dap.
      Rockbox is playlist oriented. When you play a song, a directory, or
      an album, Rockbox creates a playlist and plays it. Thus, to shuffle
      all songs on the \dap, you need to create a playlist of all songs on
      the player, and play that playlist with shuffle mode set to
      \setting{All}.}
    %
  \item[One. ]Repeat one track over and over.
    %
  \item[Shuffle. ]When the current directory or playlist has finished
    playing, it will be shuffled and then repeated.
    %
    \nopt{ondiosp,ondiofm}{
    \item[A-B. ]Repeats between two user defined points within a track,
      typically used by musicians when attempting to learn a piece of music.
      This option is more complicated to use than the others as the \dap\
      must first be placed into A-B repeat mode and then the start and end
      points defined.\\
      \fixme{
        Hold Play and press Left  --- Sets Start Point (A)\\
        Hold Play and press Right --- Sets End Point (B)\\
      }
    }
  \end{description}
  
\item[Play Selected First. ]This setting controls what happens when you
  select a file for playback while shuffle mode is on. If the
  \setting{Play Selected First} setting is \setting{Yes}, the file you
  selected will be played first. If this setting is \setting{No}, a random
  file in the directory will be played first.
  
\item[Resume on Startup. ]Rockbox can be configured to start playing automatically
  when you turn on the \dap. If the resume function is set to start
  automatically playing, Rockbox will start at the point where you last
  turned off the \dap. The options for the \setting{Resume on Startup}
  function are:
  \begin{description}
  \item[Yes. ]Rockbox will unconditionally try to resume.
  \item[No. ]Rockbox will not resume.
    \note{If \setting{Resume on Startup} is set to \setting{No}, Rockbox will
      start in the \setting{File Browser}.}
  \end{description}
  
  \item[Fast-Forward/Rewind. ]How fast you want search (fast forward or rewind)
    to accelerate when you hold down the button. \setting{Off} means no 
    acceleration. \setting{2x/1s} means double the search speed once every 
    second the button is held. \setting{2x/5s} means double the search speed 
    once every 5 seconds the button is held.
    
  \item[Anti-Skip Buffer. ]This setting allows you to control how much music is
    stored in the \daps{} memory whilst playing a song, acting as a buffer
    against shock or playback problems. The \dap{} transfers the selected
    amount of the forthcoming song into its memory at high speed whilst you are
    playing the song. It keeps a ``rolling'' buffer, which keeps feeding more
    of the forthcoming song into memory as it goes along.
    If the \dap{} is knocked, shaken or jogged heavily while Rockbox is trying
    to read the hard drive, Rockbox might not be able to read the drive.
    Rockbox will retry over and over again until it succeeds, but may
    eventually reach the end of the memory buffer. When that happens, Rockbox
    must stop playing and wait for more data from the disk, which causes your
    music to skip. The anti-skip setting tells Rockbox how much extra buffer
    memory to spare to handle this situation. This setting therefore allows you
    to reduce the chances of there being a gap or pause during playback of
    songs.
    
    \nopt{ondio}{
      \opt{MASCODEC}{The anti-skip buffer can be set to a value between 0 and 7
        seconds.}
    }%
    \opt{ondio}{
      The anti-skip buffer can safely be kept at zero. It will eventually be 
      eliminated.
    }%
    \opt{SWCODEC}{The anti-skip buffer can be set to various values between
      5 seconds and 10 minutes.}%
    
    \note{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.}
    
  \item[Fade on Stop/Pause. ]Enables and disables a fade effect when you
    pause or stop playing a song. If the Fade on Stop/Pause option is
    set to \setting{Yes}, your music will fade out when you stop or pause 
    playback, and fade in when you resume playback.
    
  \item[Party Mode. ]Enables unstoppable music playback. When new songs are
    selected, they are queued at the end of the current dynamic playlist
    instead of being played immediately. Pausing and stopping playback is
    disabled as well as skipping songs and launching plugins.

    \opt{SWCODEC}{
    \item[Crossfade. ]
      This setting enables a cross-fader. At the end of a song, the song will 
      fade out as the next song fades in, creating a smooth transition between 
      songs.\\
      Options:
      \begin{description}
      \item[Enable Crossfade. ]If set to \setting{Off}, crossfade is disabled.
        If set to \setting{Always}, songs will always crossfade into one
        another. If set to \setting{Shuffle}, crossfade is enabled when the
        shuffle feature is set to \setting{Yes}, but disabled otherwise. If set
        to track skip only, tracks will only crossfade when you manually change
        tracks.
        %
      \item[Fade In Delay. ]The ``fade in delay'' is the length of time between
        when the crossfade process begins and when the new track begins to fade
        in.
        %
      \item[Fade In Duration. ]The length of time, in seconds, that it takes
        your music to fade in.
        %
      \item[Fade Out Delay. ]The ``fade out delay'' is the length of time
        between when the crossfade process begins and when the old track begins
        to fade out.
        %
      \item[Fade Out Duration. ]The length of time, in seconds, that it takes
        your music to fade out.
        %
      \item[Fade Out Mode. ]If set to \setting{Crossfade}, one song will fade
        out and the next song will simultaneously fade in. If set to 
        \setting{Mix}, the ending song will continue to play as normal until 
        its end, while the starting song will fade in from under it. 
        \setting{Mix} mode is not
        used for manual track skips, even if it is selected here.
      \end{description}
      
      \note{The crossfade setting is particularly effective when the player is 
        set on shuffle.}
    }%
    
    \opt{SWCODEC}{
    \item[Replaygain. ]This allows you to control the replaygain function.
      The purpose of replaygain is to adjust the volume of the music played
      so that all songs (or albums, depending on your settings) have the
      same apparent volume. This prevents sudden changes in volume when
      changing between songs recorded at different volume levels.
      For replaygain to work, the songs must have been processed by a program
      that adds replaygain information to the ID3 tags (or Vorbis tags).
      \note{APEv2 tags are not currently supported.}
      
      Options for replaygain are:
      \begin{description}
      \item[Enable Replaygain. ]This turns on/off the replaygain function.
        %
      \item[Prevent Clipping. ]Avoid clipping of a song's waveform.
        If a song would clip during playback, the volume is lowered for 
        that song. Replaygain information is needed for this to work.
        %
      \item[Replaygain type. ]Choose the type of replaygain to apply:
        \begin{description}
        \item[Album Gain. ]Maintain a constant volume level between
          albums, but keep any intentional volume variations between 
          songs in an album. (If album gain value is not available,
          uses track gain information).
          %
        \item[Track Gain. ]Maintain a constant volume level between
          tracks. If track gain value is not available, no replaygain 
          is applied.
          %
        \item[Track Gain if Shuffling. ]Maintains a constant volume
          between tracks if \setting{Shuffle} is set to \setting{Yes}.
          Reverts to album mode if \setting{Shuffle} is set to \setting{No}.
        \end{description}
        %
      \item[Pre-amp. ]This allows you to adjust the volume when replaygain
        is applied. Replaygain often lowers the volume, sometimes quite
        much, so here you can compensate for that. Please note that a
        (large) positive pre-amp setting can cause clipping, unless
        prevent clipping is enabled.  The pre-amp can be set to any
        decibel (dB) value between -12dB and +12dB, in increments of 0.1{}dB.
      \end{description}
    }
    \opt{SWCODEC}{
      \item[Beep Volume. ]Controls the volume of the beep that is heard when
        skipping forward or backward between tracks. The beep is disabled when
        set to \setting{Off}.
    }

    \item[ID3 Tag Priority.] Select which version of ID3 tag to use if both are
      present.
    
\item[Auto-Change Directory. ]Control what Rockbox does when it reaches the end
  of a directory. If \setting{Auto-Change Directory} is set to \setting{Yes},
  Rockbox will continue to the next directory. If
  \setting{Auto-Change Directory} is set to \setting{No}, playback will stop at
  the end of the current directory.
  \note{You must have the \setting{Repeat} option set to \setting{No} for
    \setting{Auto-Change Directory} to function properly.}
  %
\opt{ipodnano,ipodvideo,ipodmini,ipod4g,ipod3g,ipodcolor}{
\item[Pause on headphone unplug.] Enables and disables automatic pausing of 
  playback when the headphones are disconnected from the \daps{} headphone 
  socket.
  %
  \begin{description}
  \item[Pause on headphone unplug. ]Options for automatic pause:
    \begin{description}
    \item[Off.] Disables automatic pause.
      %
    \item[Pause.] Pauses the \dap{} when the headphones are removed.
      %
    \item[Pause and Resume.] Pauses when the headphones are removed, and 
      resumes playback when they are reconnected.
  \end{description}
  \item[Duration to rewind.] Number of seconds (between 0 and 15) to rewind 
    playback when the headphones are removed.
    %
  \item[Disable auto-resume if phones not present.] This option will disable 
    the automatic resumption of playback at startup if the headphones are not 
    connected to the \dap{}.
    \note{This requires \setting{Resume on Startup} to be enabled.}
  \end{description}
}%
\end{description}