xmms-crossfade: XMMS Plugin for Crossfading / Continuous Output
---------------------------------------------------------------

(c)  2000-2006  Peter Eisenlohr <peter@eisenlohr.org>
http://www.eisenlohr.org/xmms-crossfade

Also supporting Audacious as well as BMP, although it has been discontinued.
BMPx is not supported, since it uses a completely different audio backend
(GStreamer), which is incompatible to XMMS plugins.

It is also possible to build XMMS-crossfade without any GUI functions for
use with noxmms (http://xmmsd.sourceforge.net/noxmms), a completely headless
version of XMMS.


0. Index:
---------

1.     Features
2.     Installation
2.1      Requirements
2.2      How to
2.3      Troubleshooting
2.4      Player patches
3.     Configuration
3.1.     Output
3.1.1.     Sample rate
3.1.2.     Builtin OSS driver
3.1.3.     Output plugin
3.2.     Effects
3.3.     Crossfader 
3.3.1.     Mixing buffer size
3.3.2.     Set parameters for
3.3.3.     Crossfade/transition type
3.4.     Gap Killer
3.5.     Misc
4.     Known bugs
5.     Credits


1. Features:
------------

  * Crossfading: Fade out the end of the current song while fading in
                 the beginning of the next for a smooth transition.

  * Continuous output: Avoid the clicks and pauses between songs

  * Gap-Killer: Some mp3-encoders produce small gaps of silence at the
                beginning or end of the stream. They can automatically
                be detected and removed.

  New in 0.2:

  * Use any existing output Plugin
  * Set crossfading parameters separately for manual and automatic songchange
  * Set fade length/volume separately for fade-in and out

  New in 0.2.3:
  
  * Automatically revert to gapless mode on prefaded tracks (live albums)

  New in 0.2.4:

  * Fadein/fadeout at start/stop of playback
  * Latency / quality optimizations

  New in 0.2.6:

  * Support for a second effect plugin
  * Crossfading when seeking

  New in 0.3.0:

  * Software mixer
  * Better songchange detection

  New in 0.3.1:

  * Fade on pause

  After that, only small features have been added, as the releases were
  addressing mostly bugfixes. Fore more details, please refer to the
  Changelog.


2. Installation:
----------------

  2.1 Requirements:
 
    You will need version 1.2.7 (or higher) of GLIB/GTK to compile
    XMMS-crossfade. Also, you might need to install certain
    development packages from your distro, which include header files
    and scripts necessary to compile XMMS-crossfade. Look for RPMs
    called 'libglib1.2-devel' and 'libxmms1-devel'.

    When compiling for Audacious, GTK2 is required.

  2.2 How to:

    Then, it's just the usual:

      ./configure
      make
      su
      make install

    To compile for other players, use:

      ./configure --enable-player=audacious
      ./configure --enable-player=noxmms

    This will install libcrossfade.so (along with the libtool support
    file libcrossfade.la) to the XMMS output plugin directory as
    reported by `xmms-config --output-plugin-dir`. On my machine, the
    Output plugin directoy is /usr/X11R6/lib/xmms/Output.

    If you want to install the plugin as a user plugin in your home
    directory, add the following option to 'configure':

      --libdir ~/.xmms/Plugins
      --libdir ~/.audacious/Plugins

    Note that this only works if the XMMS support for per-user plugin
    directories has not been disabled (--disble-user-plugin-dir).

    You need to restart your XMMS for the plugin to become available.
    Next, go to "Audio I/O Plugins" and select "Crossfade Plugin" from
    the list. After that, you should check the plugin's configuration.
    Make sure the right Output Device/Plugin is selected.

    You can uninstall XMMS-crossfade with 'make uninstall'.

  2.3 Troubleshooting:

    Since this has truely been a FAQ, here is some info on the
    'xmms-config not found' issue:

    'xmms-config' is a small shell script that comes with XMMS. It is
    used by plugins to query for compiler flags and installation
    directories.

    When building XMMS from source, it should be automatically
    installed together with the 'xmms' binary. On the other hand, if
    you installed XMMS as a binary (i.e. RPM or DEB) package,
    'xmms-config' may not be included. If this is the case, it is
    often contained in a separate development package. Mandrake, for
    example, puts 'xmms-config' in a package called
    'libxmms1-devel'. Other distributions may have a different naming
    scheme. Start looking for a '*-devel' package, or use your
    distribution's package management tool to search for the package
    containing 'xmms-config'.

    Note that what I said about 'xmms-config' above also applies to
    'glib-config' and 'gtk-config'. If the configure script complains
    about missing GLIB or GTK, you probably have to install the
    respective development packages.

  2.4 Player patches:

    As of version 0.3.9, XMMS-crossfade includes patches to the players
    to work around some problems with the XMMS plugin interface. For more
    details, see the 'Known Bugs' section at the end of this README. It
    is recommended to use these patches. The configure script will print
    a warning if it detectes an unpatched player executeable.


3. Configuration:
-----------------

  3.1. Output Tab:

    Select/configure output method. You can either use the builtin
    OSS driver or pick an existing Output Plugin.

    Note that for the settings in this tab to take effect, you need to
    stop and then restart playback.

  3.1.1. Output Tab -> Sample rate:

    Select the sample rate to be used for the mixing buffer. If you
    have a soundcard capable of playing 48 kHz audio and want to play
    48 kHz audio files without downsampling, you can activate this
    option. In all other cases, the default of 44100 Hz should be ok.

    WARNING: If your soundcard or the selected output plugin does not
             support 48 kHz audio, Bad Things may happen (i.e. lockup
             or crash of XMMS)


  3.1.2. Output Tab -> Builtin OSS Driver:

    Here you can set the builtin OSS driver's options. They are similar
    to the original OSS-driver's.

  Output Tab -> Builtin OSS Driver -> Device Tab:

    Select the DSP and mixer devices for the builtin OSS driver. The
    default entries map to /dev/dsp and /dev/mixer respectively.

  Output Tab -> Builtin OSS Driver -> Buffer Tab:

    Buffer Size / Preload Size: Set how much data the bultin OSS
    plugin will buffer. The settings range from 0 to 60000ms. The
    total buffer size is the sum of both settings (plus an additional
    sync buffer of approx. 250 ms). Default values are 0 for 'buffer'
    and 500 for 'preload'. The XMMS-crossfade-engine already does a
    lot of buffering on its own, so you only need a short preload here
    to avoid buffer underruns when starting playback.

    The 'Maximum device buffer size' will force the OSS plugin to allocate
    as many fragments as it can get from the OSS driver. By default, only
    23 fragments of 2048 bytes each are allocated, which is enough for about
    250 ms of audio.

    The Hardware device buffer is an advanced configuration option for
    setting the size and number of the OSS buffers directly. The OSS buffers
    are called 'fragments' and have a size of 2^x bytes, where x is in the
    range of 4..16 (4, 8, 16, ... , 65536). Not all sound hardware will
    support all fragment sizes, but if you select an invalid setting, OSS
    will automatically revert to the next usable fragment size.

    The number of fragments multplied with the fragment size will give you
    the total buffer size. The default is 22 fragments of 2048 bytes each
    This is a total of 45056 bytes, which is roughly equal to 255 ms of
    audio (at 44.1 kHz).
    
    You can try to decrease the number of fragments to minimize latency
    on songchange, but be aware that setting the value too low may result
    in choppy output.

  Output Tab -> Builtin OSS Driver -> Mixer Tab:

    With the 'Volume controls Master not PCM' option activated, XMMS'
    volume control will set the master volume of the soundcard. If it
    is deactived, the PCM (wave) mixer channel will be controlled.
    The default is to control the PCM mixer channel.

  3.1.3 Output Tab -> Output Plugin:

    With output method set to 'Output plugin', you can select an
    existing Output plugin to be used for playback. Select the plugin
    you wan to use from the combo box (note that the 'Crossfade'
    plugin can not use itself for output). The buttons 'Configure' and
    'About' open the configuration- and about-dialogs of the selected
    plugin, respectively.
  
  Output Tab -> Plugin compatibility options:

    For some plugins, special handling is necessary to make them work
    together with xmms-crossfade. Here is what the options do:

  Output Tab -> Plugin compatibility options -> Throttle Output:

    This will slow down the stream going to the output plugin. For plugins
    like OSS or ALSA, this is not necessary, since they can only
    receive data as fast as the hardware can play sounds. The
    disk_writer plugin, on the other hand, just writes all data it
    gets to disk, with virtually no delay. This way, the mixing buffer
    does not get a chance to fill, which in turn will break
    crossfading.

    Note that this option does not affect total throughput, it just
    starts writing data to the output plugin later, i.e. after the
    mixing buffer is full.

  Output Tab -> Plugin compatibility options -> Max block size:

    Set the maximum chunk size of the data being fed to the
    plugin. Some plugins can't handle very big blocks (the original
    OSS plugin will lock up if the chunk size exceeds its buffer
    size). The default value of 2304 matches the blocksize comming
    from the mpg123 input plugin.

  Output Tab -> Plugin compatibility options -> Force close/reopen:

    This will close and immediatelly reopen the output plugin during
    songchange/crossfade. Normally, you do not want to use this
    option, since it re-introduces short gaps during songchange.
    Again, it is useful only for the disk_writer plugin, which will
    write a separate file for each song instead of jut one big WAV.

 
  3.2. Effects Tab:

    Here you can select a second effect plugin to be used for playback.
    In contrast to the plugin you can select in XMMS' configuration dialog,
    this plugin will be applied before crossfading. This is only useful
    for a some plugins like the volume normalization plugin.
 

  3.3. Crossfader Tab:
 
    Configure the crossfading engine:

  3.3.1. Crossfader -> Mixing Buffer size:

    Specify the size of the mixing buffer. Mixing buffer space is
    required for pauses, fade-outs, offsetting (i.e. interleaving the
    end and beginning of two songs) and killing trailing gaps.
    Fade-ins and killing leading gaps are done on-the-fly and do not
    depend on mixing buffer space.

    The auto checkbox next to the mixing buffer size field enables
    automatic calculation of the buffer size. This will allocate
    enough mixing buffer space for all of the crossfade/transition
    types that are configured. This is the default.

    When allocating the buffer, XMMS-crossfade will internally add the
    "Mixing buffer preload" and an additional 250ms for syncing to the
    buffer size.

  3.3.2. Crossfader -> Set parameters for:

    You can set crossfading/transition parameters separately for the
    different types of songchange:

    * Start of playback:

    Allows you to fadein at start of playback.

    * Automatic songchange:

    An automatic songchange occurs when the end of a song is reached
    and XMMS advances to the next song in the playlist. The default
    configuration for automatic songchange is a crossfade of 6 seconds
    with an offset of minus 8 seconds (see 'Advanced crossfade' for an
    explanation of the offset parameter).

    * Automatic (gapless):

    This setting is also for the automatic transition between the end
    of a song and the beginning of the next song. The '(gapless)' is
    used when the 'Don't crossfade successive tracks' option is enabled
    and pre-faded songs are detected.

    By default, the gapless transition is set to None. You can also set
    it to a short (1 ms) crossfade to avoid clicks in some rare cases.

    * Manual songchange:

    A manual songchange is caused by user input, i.e. pressing the
    NEXT oder PREV buttons or doubleclicking on an entry in the
    playlist. The default behaviour of XMMS-crossfade is to flush
    output and start playing the newly selected song with as little
    delay as possible.

    * Manual stop:

    When pressing the STOP button, XMMS-crossfade can apply a smooth
    fadeout.

    * End of playlist:

    The end of the last song of the playlist can be fade out smootly.

    * Seeking:

    When seeking within the current song. The normal behaviour of XMMS
    is to flush the output device. Although giving you instant reaction,
    this does not sound very good and gives you clicks.

    For optimal quality, you should do a short crossfade here: The
    default of a 50 ms Simple Crossfade sounds nice. To minimize
    latency, you should also enable 'Limit OP buffer usage'.

    * Pause:

    As of version 0.3.1, you can configure XMMS-crossfade to do a short
    fade out/fade in when pausing/unpausing playback.


  3.3.3. Crossfader -> Crossfade/transition type:

    * Reopen output device:
   
    This is XMMS standard way of handling output plugins. At each
    songchange, the output plugin/device is closed and then
    reopened. This might be useful for compatiblity reasons only,
    since it will re-introduce the infamous gap between songs.
    
    * Flush output device:

    Flushes the output buffers, but does not close/reopen the output
    plugin/device. This is the best choice for manual songchanges,
    since it gives you almost instant feedback. The Drawback is that
    flushing the buffers will introduce a short gap in the output.

    * Fadein: 

    Allows you to specify the length and starting volume to be used
    for fading in the first song when starting playback.
    
    * Fadeout:

    Fadeout is only availble for the "Manual stop" and "End of playlist"
    configurations.

    You can also add an additional silence after the fadeout. This
    way, you can work around the kracks in the output when the
    audio device is closed.

    * None (gapless):

    Does not do anything on a songchange. Specifically, it does not
    close/reopen or flush the output plugin/device. The data from the
    next song is simply appended to the mixing buffer (modulo the
    silence at the end/beginning of the songs if the gap killer is
    enabled). The transition type 'None' does the same as a 'Pause' or
    a 'Simple crossfade' with length set to zero.

    * Pause:
  
    Inserts silence between two songs.

    * Simple crossfade:

    Does a simple, straightforward crossfade between the end of the
    last and the beginning of the next song. This is the same type of
    crossfade as in v0.1.x of XMMS-crossfade.

    * Advanced crossfade:
 
    The most flexible transition type. You can configure fade-out and
    fade-in parameters separately. You can also adjust how much the
    streams should overlap by adjusting the offset parameter.

    Example 1: offset < 0: mix streams together
    Example 2: offset > 0: insert pause between streams
     
       1) |----- out_len -----|    *  2) |out_len|
          |                   |    *     |       |
      ~~~~~-_        /T~~~~~~~T~~  * ~~~~~\      |               /T~~
             ~-_    / |       |    *       \     |              / |
                ~-_/  |       |    *        \    |             /  |
                  /~-_|       |    *         \   |            /   |
                 /    T-_     |    *          \  |           /    |
                /     |  ~-_  |    *           \ |          /     |
      _________/______|_____~-|__  * ___________\__________/______|__
               |in_len|       |    *             |         |in_len|
               |<-- offset ---|    *             |offset-->|
    

    The transition types 'None', 'Pause' and 'Simple crossfade' could
    be simulated with 'Advanced Crossfade' settings like this:

                          None  Pause  Simple XF  Fadein  Fadeout
      ------------------------------------------------------------
        Fade-out length:     0      0        len       0      len
             End volume:   n/a    n/a          0     n/a      vol
      ------------------------------------------------------------
                 Offset:     0    len       -len       0  silence
      ------------------------------------------------------------
         Fade-in length:     0      0        len     len        0
           Start volume:   n/a    n/a          0     vol      n/a
      ------------------------------------------------------------

    In fact, that is what XMMS-crossfade does internally when doing
    one of the 'Node', 'Pause' or 'Simple crossfade' transitions.


  3.4. Gap Killer Tab

  Gap Killer -> Leading gap killer:

    Set the maximum length for gaps at the beginning of a stream. The
    'Max. level' parameter sets the threshold of what is considered as
    silence. The default values are 500 ms / 512.

  Gap Killer -> Trailing gap killer:

    Same as Leading gap killer, only for the end of a stream. The
    settings are locked to the Leading gap killer settings by default.

  Gap Killer -> Advanced:

    * Skip to next zero crossing:  

    If enabled, XMMS-crossfade will take additional care to avoid clicks
    with pre-faded (gapless) tracks. XMMS-crossfade will cut off the end of
    the previous song (the beginning of the next song) only at a
    zero-crossing of the sample values.


  3.5. Misc Tab

  Misc -> Debug options:

    * Write debug output to <stderr>:

    Monitors what is going on in XMMS-crossfade. If you think you
    found a bug in XMMS-crossfade, please enable this option and send
    me the output.

    Note that you should disable debug output if you start XMMS from
    within Netscape. Netscape will spam you with dialogs containing
    the debug output captured from <stderr>.

    * Show Buffer Monitor:

    Enables the Buffer Monitor. This is a small window which shows how
    much data is in the buffers. The top display belongs to the mixing
    buffer, the bottom shows how much data is being buffered by the
    output plugin.

    The whole thing is just a gimmick, but it served me well during
    development of XMMS-crossfade. It is also interesting to watch
    during crossfade or playback of internet radio streams.

  Misc -> Volume control options:

    * Enable volume control:
  
    Enables/disables XMMS volume and balance controls.

    * Reverse balance:

    Reverses left and right with the balance control.

    * Software mixer:

    Enables software mixing support. This may be usefull for output plugins
    or soundcard drivers without volume control support.

  Misc -> Advanced options:

    * Songchange timeout:

    The songchange timeout is the maximum time XMMS-crossfade waits for
    the next song. If this timeout is exceeded, the output plugin/device
    is closed. As of version 0.3.11, if XMMS is patched with crossfade's
    songchange detection patch, this value can still be used to add extra
    buffer time to avoid shortened crossfades.

    The reason that there is this option has to do with XMMS' handling
    of output plugins: On a songchange (either manual or automatic),
    XMMS always closes the output plugin first before reopening it
    again for the next song.

    From the view of XMMS-crossfade this means that after having been
    closed by XMMS, it has to keep the output plugin/device opened and
    wait some time for a new song to start.

    If it does not wait long enough, it closes the output plugin/device
    before the new song starts, and you will hear a gap. If the timeout
    is too long, the delay after manually pressing the STOP button gets
    annoying.

    The default value of 500 ms should be a reasonable default for most
    people.

    * Mixing buffer preload:

    Tells XMMS-crossfade how much data it should buffer before it starts
    writing to the output plugin/device. Usually, this value can be set
    to 0, because the output plugin does preloading on its own.

    * Don't crossfade successive tracks

    This option enables the automatic detection of pre-faded or gapless
    tracks, like the tracks on some compilations or on most live albums.
    If such tracks are detected, crossfading will be disabled and only
    the gapkiller (if enabled) will be used for the songchange.

    For the next song to be considered successive to the previous, the
    following conditions are checked:

    1) Are both songs in the same directory?
    2) Are the track numbers (taken from the beginning of the filenames)
       successive?
    3) If the trailing gap killer is enabled: Is the end of the last
       song not silent?

    If conditions 1, 2 and 3 (if applicable) are true, crossfading
    will be disabled.

    For this to work, you have to put each album (to be exact: each CD
    of each album) in a directory of its own, and prepend the track
    number to the filename like this:

    .../The Chillout Album CD1/01 Massive Attack - Teardrop.mp3
    .../The Chillout Album CD1/02 Sven Vaeth - Harlequins Meditation.mp3
    .../The Chillout Album CD1/03 Nightmares on Wax - Nights Interlude.mp3
    .../The Chillout Album CD1/...

    .../The Chillout Album CD2/...

    .../The Chillout Album Volume 2 CD1/...

    If no track number can be found at the beginning of the filename,
    XMMS-crossfade will stick to the normal "Automatic Songchange" config.

    * Don't crossfade same file

    This option will disable crossfading from the same file to itself.
    This happens if you just have one file in the playlist and repeat
    is turned on.

    * Enable HTTP buffer underrun workaround

    Only enable this when you have problems playing internet HTTP
    audio streams. The problem was that the mpg123 decoder would start
    preloading every few seconds, which in turn would result in
    gaps. This misbehaviour seems to have disappeared in recent
    versions of XMMS. So just leave it turned off, since it also will,
    as a sideeffect, break crossfading between HTTP streams.

    * Limit OP buffer usage:

    With this option enabled, XMMS-crossfade will limit the amount of
    data being buffered by the output plugin. This way, you can decrease
    the latency between pressing STOP/NEXT/PREV and the new song actually
    being played.

    Beware that setting this value too low also increases the chance of
    buffer underruns. The default is 250 ms.

    * Keep output opened

    As soon as the apply button is pressed after activating this option,
    XMMS-crossfade will open the output device and keeps it open all the
    time, even if currently no song is playing. This can be useful to
    avoid the clicks caused by opening/closing the output device.    
  

4. Known bugs:
--------------

  * When playing the last song of a playlist (and "Repeat" is turned
    off), the last few seconds (= mixing buffer size) of playback
    can't be stopped. During this time, XMMS will already show the
    STOP sign in its display, and the analyzer will be stopped.

  * During crossfade, the analyzer display and any visualization
    plugins are not accurate. More precise, the display will freeze
    when XMMS has finished decoding the current song and begins to
    decode the next. Normal operation is resumed as soon as the first
    samples of the new song are being played.

  * There is some delay when pressing the STOP button until the song
    actually stops playing. FIX: you can try lowering the songchange
    timeout in the misc tab of the configuration dialog. Be careful
    though not to set this timeout too short - gapkilling/crossfading
    will break, and every songchange will be handled as if the user
    pressed STOP inbetween.

    NOTE: When using one of the player patches, this problem should
          no longer occur, as the improved, fail-safe songchange
          detection provided by the patch can be used.

  All of the above issues are due to the design of the plugin interface
  and can not be fixed.

  * When playing CDDA tracks with the standard CD audio plugin,
    crossfading will not work. This is because in audio mode the CD-ROM
    drive will read and convert the audio data on its own. The signal
    is then sent to the soundcard directly, bypassing effect plugins,
    the equalizer and visualization. You will need an CD audio input
    plugin that samples the audio data or reads it off the CD in its
    binary form.

  * Some output plugins don't work when the 'Limit OP buffer usage'
    advanced option is enabled.

  * There is a problem when using the ARTS output plugin: In some
    configurations, this results in distored/skipped output. While I do
    not have a real solution for this, there is a workaround: Setting
    'Limit OP buffer usage' to 400 ms in the 'Advanced' tab of
    XMMS-crossfade's configuration dialog will cure the worst of this
    effect. Thanks to Jason Carter for comming up with this.

  * There is a serious problem on some systems: Users who have the
    NPTL (Native Posix Thread Libary) version of glibc instaleld on
    their systems will experience a lockup or SEGFAULT when exitting
    XMMS while a song is being played using XMMS-crossfade. This is
    because of a bug in NPTL:

    http://sources.redhat.com/bugzilla/show_bug.cgi?id=654

    Fortunatelly, there is a workaround, which (unfortunatelly) requires
    a patch to XMMS itself. As of version 0.3.9 of XMMS-crossfade, these
    patches (for BMP and Audacious as well) are included in the
    distribution. It is now up to the developers and/or maintainers of
    the players to incorporate the patch into the players. The patch should
    be completely harmless, as it just introduces two new global variables
    that XMMS-crossfade can use to query information about the current state
    of the player. For more details, see patches/README.

  Please send any comments or bug reports to <peter@eisenlohr.org>.

  When submitting bug reports, please activate debug output in the Misc tab
  of the configuration dialog and send the output along with it. You might
  need to start XMMS from a console window to see the output, since it is
  written to <stderr>.

  * Last but not least, there is the bug that XMMS-crossfade is now misnamed
    because it supports BMP and Audacious as well. But since XMMS is the
    ancestor of the other players, the naming will stay the same. Package
    maintainers are free to name their packages differently, though ;)


5. Credits:
-----------
  Thanx...
 
  ... to Damon Chaplin for his GTK-GUI-generator 'GLADE'. With its help,
  doing the GUI was only half as painfull as it would have been.

  ... to Manuel Ubeda, Alex Schuster and Gordon Decker for initial testing;
  to the XMMS staff, especially Olle, for XMMS, bug reports and support;
  to Ryan Weaver, Matthias Saou and Dag Wieers for building and announcing
  RPMs and to Martin Waitz as well as Florian Ernst for doing the debian
  packages.

  ... to Thomas Nilsson, Jamie Zawinski, Jan Niehusmann, Deti Fliegl,
  Adrian Sutton, Daniel Burzynski, David Pollard, Kenneth Lareau,
  Sammy Atmadja, David Reveman, Derrick J. Brashear, Pete Pokrandt,
  Oliver Josephs, Baruch Even, Haakon Riiser, Nathan Walp,
  Michael T. Watters II, Ilja Gerhardt, Olli Eestil, Stephan Tillenburg,
  Matt Clements, David Mayo, Matthieu Sozeau, Benjamin Zeiss, Tuomas
  Airaksinen, Martin Gadbois, Ben Stanley, Stephan Niemz, Frank Klemm,
  Robert Johansson, Frank Stanek, Timo Nentwig, Michael Shigorin,
  Daniel Eckl, Carlo Capocasa, Jason Carter, Gtz Waschk, Gerald
  Schnabel, Alexander van der Hoff, Magnus Holmgren, dai, William Pittcock
  and Tony Vroon for feedback and help with debugging.

  ... to Sourav K. Mandal for the .spec file.

  ... to Thomas Vander Stichele for the quantaudio support.

  ... to Samuel Krempp for libsamplerate support.

  Also many thanks to everyone else who has sent mail.