xmms-crossfade: XMMS Plugin for Crossfading / Continuous Output
---------------------------------------------------------------
(c) 2000-2003 Peter Eisenlohr
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 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).
* 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 :
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 .
* 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.
* 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.
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.
Please send any comments or bug reports to .
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 .
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 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,
Michael T. Watters II, Ilja Gerhardt, Olli Eestilä, Stephan Tillenburg,
Matt Clements, David Mayo, Matthieu Sozeau and Benjamin Zeiss
for feedback and help with debugging.
... to Sourav K. Mandal for the .spec file.
... to Thomas Vander Stichele for the quantaudio support.
Also many thanks to everyone else who has sent mail.