xmms-crossfade: XMMS Plugin for Crossfading / Continuous Output --------------------------------------------------------------- (c) 2000-2001 Peter Eisenlohr http://www.netcologne.de/~nc-eisenlpe2/xmms-crossfade 0. Index: --------- 1. Features 2. Installation 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: ---------------- 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. Older versions of XMMS did not include xmms-config. In this case, the configure script will guess the output plugin directory from xmms' installation path. You can always override the installation directory using the --libdir= option with configure. 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'. 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. 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 : 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. 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 . 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 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 and Baruch Even for feedback and help with debugging. ... to Sourav K. Mandal for the .spec file. Also many thanks to everyone else who has sent mail.