mirror of
https://github.com/ZDoom/fluidsynth.git
synced 2024-12-13 14:11:14 +00:00
483 lines
17 KiB
Markdown
483 lines
17 KiB
Markdown
# FluidSynth LADSPA Interface
|
|
|
|
The [LADSPA](http://ladspa.org/) (Linux Audio Developer's Simple Plugin API)
|
|
binding can be used to route the FluidSynth audio output through any number of
|
|
LADSPA plugins. Please note that even though the "L" in LADSPA stands for
|
|
"Linux", it can also be used on different platforms, for example Windows or
|
|
MacOS. Check the "LADSPA on other Platforms" section at the end of this guide
|
|
for more information.
|
|
|
|
## Configuration
|
|
|
|
To configure and compile FluidSynth with LADSPA support, make sure you have the
|
|
LADSPA SDK installed (or at least the ladspa.h header file available in an
|
|
include path). Then compile FluidSynth in the usual way. You should see
|
|
`LADSPA support: yes` in the cmake output.
|
|
|
|
To enable the LADSPA engine, use the `synth.ladspa.active` setting when
|
|
starting FluidSynth:
|
|
|
|
fluidsynth -o synth.ladspa.active=1 ...
|
|
|
|
|
|
# Quickstart Tutorial
|
|
|
|
The following walks you through the process of adding a LADSPA plugin into your
|
|
FluidSynth configuration. It assumes that you are running FluidSynth on Linux,
|
|
that you have some experience with running Linux shell commands and that you
|
|
know how to start FluidSynth from the command line and use it to play a MIDI
|
|
file.
|
|
|
|
## Introduction to LADSPA
|
|
|
|
You don't need to to have detailed knowledge of LADSPA to use effects with
|
|
FluidSynth, but knowing some of it's concepts will help if you want to make the
|
|
best use of it.
|
|
|
|
If you have the LADSPA SDK installed you should be able to use the `listplugins`
|
|
Linux command to list all plugins installed in your LADSPA path. And to show
|
|
more details about a particular plugin library, you can use the `analyseplugin`
|
|
Linux command. Here is an example showing the details of the `delay.so` plugin
|
|
from the LADSPA SDK:
|
|
|
|
```
|
|
user@host:$ analyseplugin /usr/lib/ladspa/delay.so
|
|
|
|
Plugin Name: "Simple Delay Line"
|
|
Plugin Label: "delay_5s"
|
|
Plugin Unique ID: 1043
|
|
Maker: "Richard Furse (LADSPA example plugins)"
|
|
Copyright: "None"
|
|
Must Run Real-Time: No
|
|
Has activate() Function: Yes
|
|
Has deactivate() Function: No
|
|
Has run_adding() Function: No
|
|
Environment: Normal or Hard Real-Time
|
|
Ports: "Delay (Seconds)" input, control, 0 to 5, default 1
|
|
"Dry/Wet Balance" input, control, 0 to 1, default 0.5
|
|
"Input" input, audio
|
|
"Output" output, audio
|
|
```
|
|
|
|
This output tells you that the `delay.so` library contains only a single plugin
|
|
called "Simple Delay Line". Most importantly it lists the input and output
|
|
ports, which can be used to set plugin parameters and connect the audio input
|
|
and output to FluidSynth.
|
|
|
|
"Delay (Seconds)" and "Dry/Wet Balance" are input controls. They are the
|
|
parameters that a user can set to affect the way the plugin works. They control
|
|
how long the delay should be and how the dry and wet signals should be mixed
|
|
before writing them to the output.
|
|
|
|
"Input" and "Output" are audio ports which carry samples into the plugin and out
|
|
again after it has run. Mono plugins usually provide one set of input and output
|
|
audio ports, stereo plugins usually provide two sets. But there are even plugins
|
|
that only have a single output port and no input at all (think of noise
|
|
generators...)
|
|
|
|
Also note the line `Has run_adding() Function: No`. This specifies that this
|
|
plugin can not mix it's audio output into an output buffer, but will always
|
|
replace anything that is already there. This will become important again later
|
|
on.
|
|
|
|
## FluidSynth Host Ports
|
|
|
|
Just as LADSPA plugins have input and output ports, FluidSynth provides it's
|
|
own audio ports that can be connected to plugins. On a standard stereo setup,
|
|
the following four ports are automatically created:
|
|
|
|
- Main:L
|
|
- Main:R
|
|
- Reverb:Send
|
|
- Chorus:Send
|
|
|
|
The "Main:L" and "Main:R" ports can be connected to effect input and output
|
|
ports. They carry the main audio signals into the LADSPA effects and the
|
|
modified signals back into FluidSynth.
|
|
|
|
"Reverb:Send" and "Chorus:Send" can be used as effect inputs. They carry the
|
|
mono effect send signals (as determined by the reverb and chorus send
|
|
generators for each voice) into the LADSPA effects.
|
|
|
|
Please note that if you run FluidSynth with the internal reverb and chorus
|
|
effects active (which is the default), then those effects are already mixed
|
|
into the Main:L and Main:R channels. Fore more details, please see the "Signal
|
|
Flow" section below.
|
|
|
|
For host port setups in multi-channel configurations, please see the
|
|
"Multi-Channel Output" section below.
|
|
|
|
## Creating a Configuration File
|
|
|
|
You can configure LADSPA effects using the FluidSynth shell, but writing the
|
|
commands into a file and loading it at startup is much more comfortable. So
|
|
let's create a file `effects.txt` with the following contents:
|
|
|
|
effects.txt
|
|
```
|
|
ladspa_effect e1 /usr/lib/ladspa/delay.so
|
|
ladspa_link e1 Input Main:L
|
|
ladspa_link e1 Output Main:L
|
|
|
|
ladspa_effect e2 /usr/lib/ladspa/delay.so delay_5s
|
|
ladspa_link e2 Input Main:R
|
|
ladspa_link e2 Output Main:R
|
|
|
|
ladspa_start
|
|
```
|
|
|
|
As the "Simple Delay Line" plugin only works on a mono signal, the configuration
|
|
above creates two effects: the one we named "e1" reads from and writes to the
|
|
left FluidSynth audio channel "Main:L", the "e2" effect reads from and
|
|
writes to the right channel "Main:R".
|
|
|
|
Please note that we only specified the path to the library
|
|
`/usr/lib/ladspa/delay.so` when creating the "e1" effect, but not which plugin
|
|
from the library to use. This is possible because the delay.so library contains
|
|
only a single plugin. If you want to use a library that contains more than one
|
|
plugin, you would need to give the plugin name as well, as we've done when
|
|
creating the "e2" effect. The string to use here is what is called "Plugin
|
|
Label" in the `analyseplugin` output.
|
|
|
|
## Using the Configuration File
|
|
|
|
Lets start FluidSynth with ALSA output and the standard SoundFont, enable LADSPA
|
|
effects, load the effects.txt config file and give it a test MIDI file to play:
|
|
(You will need to replace the `test.mid` with your own MIDI file and maybe
|
|
change the paths to the effects.txt file and the SoundFont)
|
|
|
|
```
|
|
user@host:$ fluidsynth -a alsa -o synth.ladspa.active=1 -f effects.txt FluidR3_GM.sf2 test.mid
|
|
```
|
|
|
|
You should now hear the MIDI file played at a slightly lower volume with a one
|
|
second delay effect added on both left and right channel. If not, please check
|
|
the FluidSynth output for any error messages.
|
|
|
|
## Changing Parameters
|
|
|
|
You probably noticed that we did not set any values for the "Delay (Seconds)"
|
|
and "Dry/Wet Balance" control ports. The delay plugin specifies default
|
|
values for these parameters: 1 second delay and a dry/wet balance of 0.5 (check
|
|
the `analyseplugin` output above). So when you don't override them, the defaults
|
|
are automatically used for rendering.
|
|
|
|
Let's set different values now and set the delay time on the left channel to
|
|
half a second and to 1.5 seconds on the right channel:
|
|
|
|
```
|
|
ladspa_effect e1 /usr/lib/ladspa/delay.so
|
|
ladspa_link e1 Input Main:L
|
|
ladspa_link e1 Output Main:L
|
|
ladspa_set e1 Delay 0.5
|
|
|
|
ladspa_effect e2 /usr/lib/ladspa/delay.so
|
|
ladspa_link e2 Input Main:R
|
|
ladspa_link e2 Output Main:R
|
|
ladspa_set e2 Delay 1.5
|
|
|
|
ladspa_start
|
|
```
|
|
|
|
Start FluidSynth again and you should hear that the delay is shorter on the
|
|
left channel, longer on the right. You can even change control parameters while
|
|
FluidSynth is running. Just type the `ladspa_set ...` commands into the
|
|
FluidSynth shell.
|
|
|
|
And to check the difference that the LADSPA effects have on the sound output,
|
|
you can turn them off and on again during run-time. Just type in `ladspa_stop`
|
|
and `ladspa_start` into the FluidSynth shell.
|
|
|
|
### Port Name Matching
|
|
|
|
Plugin port names are sometimes very long, because the plugin writers want them
|
|
to be self-documenting. But note that we didn't need to give the complete port
|
|
name "Delay (Seconds)" in the `ladspa_set` commands, but chose to use a much
|
|
shorter version: "Delay".
|
|
|
|
When specifying a port name for the `ladspa_link` and `ladspa_set` commands,
|
|
the system will look for any port that *starts with* the name you gave it. If
|
|
there is only one match, then that port is chosen. If there are multiple
|
|
matches (meaning your port name is ambiguous), you will see an error asking
|
|
you to be more specific. So the configuration for the "e1" effect could also
|
|
have been written with much shorter port names:
|
|
```
|
|
ladspa_effect e1 /usr/lib/ladspa/delay.so
|
|
ladspa_link e1 In Main:L
|
|
ladspa_link e1 Out Main:L
|
|
ladspa_set e1 Del 0.5
|
|
```
|
|
|
|
# Signal Flow
|
|
|
|
The LADSPA effects unit runs immediately after the internal reverb and chorus
|
|
effects have been processed. When no effects have been configured, the LADSPA
|
|
engine is dormant and uses no additional system resources.
|
|
|
|
When at least one effect is configured and the engine is activated, the rendered
|
|
audio is passed into the LADSPA effects engine, the effects are run in the order
|
|
that they were created and the resulting audio is passed back into FluidSynth
|
|
(and from there to the sound card or other output).
|
|
|
|
## Effect Sends
|
|
|
|
Please note that SoundFont designers can specify how much signal each
|
|
instrument should add to the reverb and chorus effect sends. When FluidSynth
|
|
renders a block of audio, all currently sounding instruments are mixed into the
|
|
`Main` output channels. In addition, all instruments add their signal to the
|
|
effect send ports (`Reverb:Send` and `Chorus:Send`) according to the effect
|
|
send amount specified in the SoundFont.
|
|
|
|
If you want to replace the internal reverb or chorus effects with a LADSPA
|
|
plugin and you want to honour the decisions made by the SoundFont designer, you
|
|
should use the `Reverb:Send` or `Chorus:Send` ports as effect input and
|
|
`Main:L` and `Main:R` ports as effect outputs. (See the "Example Setups" section
|
|
below for an example on how to replace the internal reverb with a LADSPA plugin.)
|
|
|
|
Please note that FluidSynth uses a mono signal for both effects, that is why
|
|
there is only a single send port for reverb and chorus.
|
|
|
|
|
|
# LADSPA Command Reference
|
|
|
|
The following is a description of all LADSPA-related commands that are
|
|
available in the FluidSynth shell if it has been compiled with LADSPA
|
|
support.
|
|
|
|
- `ladspa_effect`: Create a new effect from a plugin library
|
|
- `ladspa_buffer`: Create a new buffer
|
|
- `ladspa_link`: Link an effect port to a host port or a buffer
|
|
- `ladspa_set`: Set the value of an effect control
|
|
- `ladspa_check`: Check the effect setup for any problems
|
|
- `ladspa_start`: Start the effects unit
|
|
- `ladspa_stop`: Stop the effects unit
|
|
- `ladspa_reset`: Reset the effects unit
|
|
|
|
## ladspa_effect
|
|
|
|
```
|
|
ladspa_effect <effect-name> <library-path> [plugin-name] [--mix [gain]]
|
|
```
|
|
|
|
Load the LADSPA plugin library given by `<library-path>` and create a new effect
|
|
(i.e. an instance of a plugin). `<effect-name>` can be chosen by the user and must
|
|
unique. `<plugin-name>` is optional if the library contains only one plugin.
|
|
|
|
If the optional `--mix` parameter is given, then the LADSPA engine will call the
|
|
`run_adding` interface of the plugin. This will make the effect add it's output
|
|
to the output buffers instead of replacing them. The `--mix` parameter takes an
|
|
optional float value `gain`, which will be multiplied with each sample before
|
|
adding to the output buffers.
|
|
|
|
Please note that there is no command to delete a single effect once created. To
|
|
remove effects, please use `ladspa_reset` to clear everything start from
|
|
scratch.
|
|
|
|
Can only be called when the effect unit is not active.
|
|
|
|
## ladspa_buffer
|
|
|
|
```
|
|
ladspa_buffer <buffer-name>
|
|
```
|
|
|
|
Create a new audio buffer called `<buffer-name>`. The buffer is able to be used as
|
|
mono output or mono input to an effect. Buffers can be used to connect plugins
|
|
between each other without overwriting the host ports with temporary data.
|
|
|
|
Please note that there is no command to delete a buffer. To remove buffers,
|
|
please use `ladspa_reset` to clear everything and start from scratch.
|
|
|
|
Can only be used when the effect unit is not active.
|
|
|
|
## ladspa_link
|
|
|
|
```
|
|
ladspa_link <effect-name> <audio-port-name> <buffer-or-host-port-name>
|
|
```
|
|
|
|
Connects an effect input or output port with a buffer or a host port. This
|
|
command can be called multiple times and will overwrite the previous connection
|
|
made on that effect port.
|
|
|
|
Please note that there is no command to unlink an effect port. Use
|
|
`ladspa_reset` to clear everything and start from scratch.
|
|
|
|
Can only be used when the effect unit is not active.
|
|
|
|
## ladspa_set
|
|
|
|
```
|
|
ladspa_set <effect-name> <control-port-name> <float-value>
|
|
```
|
|
|
|
Sets a control port of an effect to a float value. Can be used at any time,
|
|
even when the effect unit is active.
|
|
|
|
## ladspa_check
|
|
|
|
```
|
|
ladspa_check
|
|
```
|
|
|
|
Checks the LADSPA effect configuration for errors. This command is also
|
|
implicitly called when executing `ladspa_start`.
|
|
|
|
## ladspa_start
|
|
|
|
```
|
|
ladspa_start
|
|
```
|
|
|
|
Activates the effects unit and inserts the configured effects into FluidSynth's
|
|
audio rendering pipeline.
|
|
|
|
## ladspa_stop
|
|
|
|
```
|
|
ladspa_stop
|
|
```
|
|
|
|
Deactivates the effects unit and removes the configured effects from
|
|
FluidSynth's audio rendering pipeline. The configuration is left untouched, so
|
|
it can be started again with `ladspa_start`.
|
|
|
|
## ladspa_reset
|
|
|
|
```
|
|
ladspa_reset
|
|
```
|
|
|
|
Deactivates the effects unit if active and clears all configuration and loaded
|
|
plugins.
|
|
|
|
|
|
# Example Setups
|
|
|
|
All examples assume that your `LADSPA_PATH` environment variable points to the
|
|
directory containing the plugin libraries (e.g. /usr/lib/ladspa).
|
|
|
|
## Single Plugin
|
|
|
|
The following loads the delay.so plugin library from the LADSPA SDK and
|
|
instantiates the delay effect under the name "e1". It connects the main left
|
|
audio channel from FluidSynth with the plugin input and output and starts the
|
|
effects engine.
|
|
|
|
```
|
|
ladspa_effect e1 delay.so
|
|
ladspa_link e1 Input Main:L
|
|
ladspa_link e1 Output Main:L
|
|
ladspa_start
|
|
```
|
|
|
|
The audible effect should be an untouched right channel and a slightly
|
|
lower volume on the left with a delay effect of 1 second on top.
|
|
|
|
## Replacing the FluidSynth Reverb Effect
|
|
|
|
If you would like a different reverb implementation than the one built-in to
|
|
FluidSynth, you can use a LADSPA reverb plugin like the "TAP Reverb" from
|
|
[Tom's Audio Processing plugins](http://tap-plugins.sourceforge.net/ladspa.html).
|
|
|
|
Here is the analyseplugin output for the `tap_reverb.so` plugin:
|
|
```
|
|
user@host:$ analyseplugin /usr/lib/ladspa/tap_reverb.so
|
|
|
|
Plugin Name: "TAP Reverberator"
|
|
Plugin Label: "tap_reverb"
|
|
Plugin Unique ID: 2142
|
|
Maker: "Tom Szilagyi"
|
|
Copyright: "GPL"
|
|
Must Run Real-Time: No
|
|
Has activate() Function: Yes
|
|
Has deactivate() Function: No
|
|
Has run_adding() Function: Yes
|
|
Environment: Normal
|
|
Ports: "Decay [ms]" input, control, 0 to 10000, default 2500
|
|
"Dry Level [dB]" input, control, -70 to 10, default 0
|
|
"Wet Level [dB]" input, control, -70 to 10, default 0
|
|
"Comb Filters" input, control, toggled, default 1
|
|
"Allpass Filters" input, control, toggled, default 1
|
|
"Bandpass Filter" input, control, toggled, default 1
|
|
"Enhanced Stereo" input, control, toggled, default 1
|
|
"Reverb Type" input, control, 0 to 42.1, default 0, integer
|
|
"Input Left" input, audio
|
|
"Output Left" output, audio
|
|
"Input Right" input, audio
|
|
"Output Right" output, audio
|
|
```
|
|
|
|
Using this information we can create a LADSPA configuration:
|
|
|
|
effects.txt
|
|
```
|
|
ladspa_effect e1 /usr/lib/ladspa/tap_reverb.so
|
|
ladspa_link e1 "Input Left" Reverb:Send
|
|
ladspa_link e1 "Input Right" Reverb:Send
|
|
ladspa_link e1 "Output Left" Main:L
|
|
ladspa_link e1 "Output Right" Main:R
|
|
ladspa_start
|
|
```
|
|
|
|
Start FluidSynth with the internal reverb disabled. (You will need to replace
|
|
the `test.mid` with your own MIDI file and maybe change the paths to the
|
|
effects.txt file and the SoundFont)
|
|
|
|
```
|
|
user@host:$ fluidsynth -a alsa -R0 -o synth.ladspa.active=1 -f effects.txt FluidR3_GM.sf2 test.mid
|
|
```
|
|
|
|
You will hear the output with a reverb effect from the plugin. And you can
|
|
change the reverb control ports with the `ladspa_set` command while the MIDI
|
|
file is playing.
|
|
|
|
# Multi-Channel Output
|
|
|
|
FluidSynth is capable of generating multi-channel output by specifying the
|
|
`synth.audio-groups` and `synth.audio-channels` configuration settings.
|
|
Explaining multi-channel output in detail is out of scope for this guide. But
|
|
using multiple output channels has an effect on the host ports that are
|
|
available to LADSPA plugins.
|
|
|
|
As soon as you configure more than one audio-channel, the main audio ports will
|
|
not be called "Main:L" and "Main:R" anymore, but will have indices added to
|
|
their name. So if you start FluidSynth with `-o synth.audio-groups=2`, then the
|
|
following ports will be created:
|
|
|
|
- Main:L1
|
|
- Main:R1
|
|
- Main:L2
|
|
- Main:R2
|
|
- Reverb:Send
|
|
- Chorus:Send
|
|
|
|
If you want all main ports to act as outputs as well as inputs to the effects,
|
|
then you also need to increase the `synth.audio-channels` setting.
|
|
|
|
|
|
# LADSPA on other Platforms
|
|
|
|
LADSPA is a very simple plugin architecture and only requires the ladspa.h
|
|
header file as compile-time dependency. To build FluidSynth on non-Linux
|
|
platform with LADSPA support, download the ladspa.h file from
|
|
http://www.ladspa.org and place it somewhere in your compiler include path. Then
|
|
configure and build LADSPA as you normally would.
|
|
|
|
All information in the above documentation is valid for all other platforms as
|
|
well. Just make sure you use the file path format specific to your platform in
|
|
the `ladspa_effect` calls. For example, on Windows you should use
|
|
```
|
|
ladspa_effect c:\path\to\ladspa\plugin.dll
|
|
```
|
|
instead of
|
|
```
|
|
ladspa_effect /path/to/ladspa/plugin.so
|
|
```
|
|
|
|
Audacity provides a large number of precompiled LADSPA plugins for Windows and
|
|
MacOS: http://www.audacityteam.org/download/plug-ins/
|
|
|
|
To get the `analyseplugin` and `listplugins` commands on Windows, you can either
|
|
compile them yourself using the LADSPA-SDK source code from ladspa.org or install
|
|
ladspa-sdk via Cygwin.
|