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 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 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. 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 : 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. * 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: [obsoleted by new songchange detection] 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 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. 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. * When using the ALSA plugin as output, there may be a segfault when quitting XMMS while a song is being played. This can't be easily worked around without a patch to XMMS. I am working on a patch. 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, Matthias Saou and Dag Wieers 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, Benjamin Zeiss, Tuomas Airaksinen, Martin Gadbois, Ben Stanley, Stephan Niemz, Frank Klemm and Robert Johansson 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.