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

(c)  2000-2001  Peter Eisenlohr <p.eisenlohr@gmx.net>
http://www.netcologne.de/~nc-eisenlpe2/xmms-crossfade


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

1.     Features
2.     Installation
2.1      Requirements
2.2      How to
2.2      Troubleshooting
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 v0.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 v0.2.3:
  
  * Automatically revert to gapless mode on prefaded tracks (live albums)

  New in v0.2.4:

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

  New in v0.2.6:

  * Support for a second effect plugin
  * Crossfading when seeking


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'.

  2.2 How to:

    Then, it's just the usual:

      ./configure
      make
      su
      make install

    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.

    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.1 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.


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.

  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 into the 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 usefull
    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).

    * 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'.


  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.


  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.

  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.

    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 anoying.

    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 between 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.

    * 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.


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.

  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.

  Please send any comments or bug reports to <p.eisenlohr@gmx.net>.

  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>.


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 could have been.

  ... to Manuel Ubeda, Alex Schuster and Gordon Decker for testing;
  to the XMMS staff, especially Olle, for XMMS, bug reports and support;
  to Ryan Weaver and Matthias Saou for building and announcing RPMs and
  to Martin Waitz 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 and
  Michael T. Watters II for feedback and help with debugging.

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

  Also many thanks to everyone else who has sent mail.