This is version 1.0 of xmms_ladspa, an Effect for XMMS that provides
(some of) the power of the Linux Audio Developer's Simple Plugin API
to your everyday MP3 and all-around media player.

Getting started
---------------

0. Install LADSPA and some LADSPA plugins  -- http://plugin.org.uk/
1. Make and install the source code of xmms_ladspa
2. Play some audio, try an Ogg Vorbis file or MP3
3. Bring up the XMMS preference dialog
4. Choose the Effect/General plugins tab
5. From the "Effect Plugins" list choose "LADSPA host 1.0"
5a. Remember to enable the plugin using the checkbox.
6. Hit 'Configure' -- You should see a list of installed LADSPA plugins
7. Choose a plugin and press "Add"
8. Do not cross the streams, that would be bad :)

The left hand side of XMMS LADSPA is a list of available LADSPA plugins
and the right hand side is a list (initially empty) of plugin instances
you're actually using. You can add plugins by choosing them on the
right and pressing "Add" or by double clicking them in the list.

You can add any number of plugins (and more than one instance of each
individual plugin) and the sound will be processed in order, first to
last. A box of control "knobs" will appear for each new plugin and if
you close it, it can be opened again by selecting the plugin and
pressing the "Configure" button below the list.

You can re-order running plugin instances by dragging their names up
or down the list on the right. To remove a plugin simply select it
and click the "Remove" button.

Controlling plugins
--------------------

Right now XMMS LADSPA doesn't include presets, but it does maintain
plugin configuration between sessions. So at least you can leave an
unfinished experiment, close XMMS and come back to it later.

The default XMMS LADSPA layout connects controls on each LADSPA
plugin to a visual interface in which each named control input
or output corresponds to one row in a vertical window. The name
is indicated on the left and the control "knobs" are on the right.

Most "knobs" are connected to two GUI controls, an entry widget
with spinbutton and a horizontal sliding scale. You can get good
coarse control with the slider, and fine tune things with the spinner
and if necessary by entering values directly.

In a few cases you'll see just a button labelled "Press" which
indicates that this control is an On/Off switch, when pressed in
the control is On or "TRUE" and otherwise it is Off or "FALSE"


Help! It doesn't work
---------------------

Q. How do I make it compile / install / untar ?

A. Sorry, I can't offer hand-holding at this stage, if compiling software
is daunting for you then XMMS LADSPA is not for you, yet.

Q. I installed the software and it seems to have worked OK but I
don't see a list of LADSPA plugins. What's wrong?

A. Do you actually have any LADSPA plugins? Did you set the environment
variable LADSPA_PATH properly ? Do other LADSPA hosts work ? The
answers to these questions should guide you to the real problem.

Q. I have XMMS LADSPA installed properly and I can see a list of
LADSPA plugins, but none of them seem to work. What's wrong?

A. Not all XMMS output plugins are compatible with Effects. Try the
XMMS built-in effects and see whether they work. If not then you
need an Output plugin with support for plugins. The latest versions
of XMMS might alleviate this problem too by moving Effect processing
into the core, rather than calling it from Output plugins (!)

Q. Most of the installed LADSPA plugins seem to work, but...

A. Obviously very few LADSPA plugins were specifically designed to
work with XMMS. So you may find that the requirements for the ones
you have problems with are incompatible with XMMS, or with the type
of audio files you are using (e.g. Mono vs Stereo). Check the
documentation for the plugin if there was any, and make sure you've
tried twiddling all the control settings before concluding that it
doesn't work.

BUGS

I'm now comfortable enough with this code to accept feedback. At this
time that means I'm happy to receive mail about bugs you've found or
suspect, and features you would like to see, but I don't promise to
reply.

The in-process plugin architecture used in LADSPA is vulnerable to
even small flaws in the plugins themselves. Bugs in any installed
LADSPA plugin and especially any plugin actively being used can cause
XMMS itself to freeze or crash. When reporting a crash or freeze to
me please specify the names and Unique IDs of the plugins you were
using at the time.

There are two groups of outstanding problems in xmms_ladspa, only half
of which are my fault.

1. My plugin isn't finished and it shows

xmms_ladspa doesn't use a proper auto* or even properly written Makefiles,
you may be reading this because it didn't build on your system, well,
sorry but for now you just get to keep both halves. I will fix it later.

Plugins which use LADSPA_PROPERTY_INPLACE_BROKEN will be.. broken in
XMMS LADSPA. Actually they probably break in a lot of places, but they
are technically permitted and so one day XMMS LADSPA should learn to
cope. If you use such a plugin or have written one, please contact me
about it.

There are no presets yet in XMMS LADSPA. Since version 1.0 your settings
are saved if XMMS quits (but not if it crashes unexpectedly) and will
be restored as much as possible when it is next restarted.

xmms_ladspa doesn't handle all audio streams properly. The effects of this
include: No LADSPA effects on 8-bit audio, multi-channel (more than
two channels) or audio which has the wrong bytesex for your platform.
Patches which improve this without uglifying the normal case are welcome.

The user interface for individual plugins is better than it was but
still far from usable for things like Hermes and the SooperLooper. This
should be / will be fixed by a future LADSPA sister standard that defines
how an external GUI (read, sweet-as-you-like graphics) can replace the
generic user interface in a host.

There is no intention to turn XMMS + XMMS LADSPA into something like
SpiralSynthModular or "the audio equivalent of Gimp". If a linear
sequence of plugins with limited controls isn't powerful enough then
you don't need a better version of XMMS LADSPA. Consider joining
the Linux Audio Users list and explaining your needs there.

2. XMMS is buggy / has irritating features, it is not alone

The shortcomings of software like XMMS are never so obvious as when you
are trying to make it do something it was never really intended to do.

There are no longer any outstanding "obvious" bugs in XMMS that affect
this plugin, but it's still very irritating that Effects must be called by
Output plugins explicitly. This makes it impossible to record your
efforts with LADSPA through the diskwriter for example! (If you find
this frustrating, get terminatorX or ardour, depending on how serious
you are about your audio processing)

Latency is good enough for a toy application, depending on your output
settings and other buffering. If you need something better then XMMS
(and by extension xmms_ladspa) can't really help. Check out JACK and
the low latency Linux kernel patches.

Nick.
