1# FluidSynth LADSPA Interface 2 3The [LADSPA](https://ladspa.org/) (Linux Audio Developer's Simple Plugin API) 4binding can be used to route the FluidSynth audio output through any number of 5LADSPA plugins. Please note that even though the "L" in LADSPA stands for 6"Linux", it can also be used on different platforms, for example Windows or 7MacOS. Check the "LADSPA on other Platforms" section at the end of this guide 8for more information. 9 10## Configuration 11 12To configure and compile FluidSynth with LADSPA support, make sure you have the 13LADSPA SDK installed (or at least the ladspa.h header file available in an 14include path). Then compile FluidSynth in the usual way. You should see 15`LADSPA support: yes` in the cmake output. 16 17To enable the LADSPA engine, use the `synth.ladspa.active` setting when 18starting FluidSynth: 19 20 fluidsynth -o synth.ladspa.active=1 ... 21 22 23# Quickstart Tutorial 24 25The following walks you through the process of adding a LADSPA plugin into your 26FluidSynth configuration. It assumes that you are running FluidSynth on Linux, 27that you have some experience with running Linux shell commands and that you 28know how to start FluidSynth from the command line and use it to play a MIDI 29file. 30 31## Introduction to LADSPA 32 33You don't need to to have detailed knowledge of LADSPA to use effects with 34FluidSynth, but knowing some of it's concepts will help if you want to make the 35best use of it. 36 37If you have the LADSPA SDK installed you should be able to use the `listplugins` 38Linux command to list all plugins installed in your LADSPA path. And to show 39more details about a particular plugin library, you can use the `analyseplugin` 40Linux command. Here is an example showing the details of the `delay.so` plugin 41from the LADSPA SDK: 42 43``` 44user@host:$ analyseplugin /usr/lib/ladspa/delay.so 45 46Plugin Name: "Simple Delay Line" 47Plugin Label: "delay_5s" 48Plugin Unique ID: 1043 49Maker: "Richard Furse (LADSPA example plugins)" 50Copyright: "None" 51Must Run Real-Time: No 52Has activate() Function: Yes 53Has deactivate() Function: No 54Has run_adding() Function: No 55Environment: Normal or Hard Real-Time 56Ports: "Delay (Seconds)" input, control, 0 to 5, default 1 57 "Dry/Wet Balance" input, control, 0 to 1, default 0.5 58 "Input" input, audio 59 "Output" output, audio 60``` 61 62This output tells you that the `delay.so` library contains only a single plugin 63called "Simple Delay Line". Most importantly it lists the input and output 64ports, which can be used to set plugin parameters and connect the audio input 65and output to FluidSynth. 66 67"Delay (Seconds)" and "Dry/Wet Balance" are input controls. They are the 68parameters that a user can set to affect the way the plugin works. They control 69how long the delay should be and how the dry and wet signals should be mixed 70before writing them to the output. 71 72"Input" and "Output" are audio ports which carry samples into the plugin and out 73again after it has run. Mono plugins usually provide one set of input and output 74audio ports, stereo plugins usually provide two sets. But there are even plugins 75that only have a single output port and no input at all (think of noise 76generators...) 77 78Also note the line `Has run_adding() Function: No`. This specifies that this 79plugin can not mix it's audio output into an output buffer, but will always 80replace anything that is already there. This will become important again later 81on. 82 83## FluidSynth Host Ports 84 85Just as LADSPA plugins have input and output ports, FluidSynth provides it's 86own audio ports that can be connected to plugins. On a standard stereo setup, 87the following four ports are automatically created: 88 89- Main:L 90- Main:R 91- Reverb:Send 92- Chorus:Send 93 94The "Main:L" and "Main:R" ports can be connected to effect input and output 95ports. They carry the main audio signals into the LADSPA effects and the 96modified signals back into FluidSynth. 97 98"Reverb:Send" and "Chorus:Send" can be used as effect inputs. They carry the 99mono effect send signals (as determined by the reverb and chorus send 100generators for each voice) into the LADSPA effects. 101 102Please note that if you run FluidSynth with the internal reverb and chorus 103effects active (which is the default), then those effects are already mixed 104into the Main:L and Main:R channels. Fore more details, please see the "Signal 105Flow" section below. 106 107For host port setups in multi-channel configurations, please see the 108"Multi-Channel Output" section below. 109 110## Creating a Configuration File 111 112You can configure LADSPA effects using the FluidSynth shell, but writing the 113commands into a file and loading it at startup is much more comfortable. So 114let's create a file `effects.txt` with the following contents: 115 116effects.txt 117``` 118ladspa_effect e1 /usr/lib/ladspa/delay.so 119ladspa_link e1 Input Main:L 120ladspa_link e1 Output Main:L 121 122ladspa_effect e2 /usr/lib/ladspa/delay.so delay_5s 123ladspa_link e2 Input Main:R 124ladspa_link e2 Output Main:R 125 126ladspa_start 127``` 128 129As the "Simple Delay Line" plugin only works on a mono signal, the configuration 130above creates two effects: the one we named "e1" reads from and writes to the 131left FluidSynth audio channel "Main:L", the "e2" effect reads from and 132writes to the right channel "Main:R". 133 134Please note that we only specified the path to the library 135`/usr/lib/ladspa/delay.so` when creating the "e1" effect, but not which plugin 136from the library to use. This is possible because the delay.so library contains 137only a single plugin. If you want to use a library that contains more than one 138plugin, you would need to give the plugin name as well, as we've done when 139creating the "e2" effect. The string to use here is what is called "Plugin 140Label" in the `analyseplugin` output. 141 142## Using the Configuration File 143 144Lets start FluidSynth with ALSA output and the standard SoundFont, enable LADSPA 145effects, load the effects.txt config file and give it a test MIDI file to play: 146(You will need to replace the `test.mid` with your own MIDI file and maybe 147change the paths to the effects.txt file and the SoundFont) 148 149``` 150user@host:$ fluidsynth -a alsa -o synth.ladspa.active=1 -f effects.txt FluidR3_GM.sf2 test.mid 151``` 152 153You should now hear the MIDI file played at a slightly lower volume with a one 154second delay effect added on both left and right channel. If not, please check 155the FluidSynth output for any error messages. 156 157## Changing Parameters 158 159You probably noticed that we did not set any values for the "Delay (Seconds)" 160and "Dry/Wet Balance" control ports. The delay plugin specifies default 161values for these parameters: 1 second delay and a dry/wet balance of 0.5 (check 162the `analyseplugin` output above). So when you don't override them, the defaults 163are automatically used for rendering. 164 165Let's set different values now and set the delay time on the left channel to 166half a second and to 1.5 seconds on the right channel: 167 168``` 169ladspa_effect e1 /usr/lib/ladspa/delay.so 170ladspa_link e1 Input Main:L 171ladspa_link e1 Output Main:L 172ladspa_set e1 Delay 0.5 173 174ladspa_effect e2 /usr/lib/ladspa/delay.so 175ladspa_link e2 Input Main:R 176ladspa_link e2 Output Main:R 177ladspa_set e2 Delay 1.5 178 179ladspa_start 180``` 181 182Start FluidSynth again and you should hear that the delay is shorter on the 183left channel, longer on the right. You can even change control parameters while 184FluidSynth is running. Just type the `ladspa_set ...` commands into the 185FluidSynth shell. 186 187And to check the difference that the LADSPA effects have on the sound output, 188you can turn them off and on again during run-time. Just type in `ladspa_stop` 189and `ladspa_start` into the FluidSynth shell. 190 191### Port Name Matching 192 193Plugin port names are sometimes very long, because the plugin writers want them 194to be self-documenting. But note that we didn't need to give the complete port 195name "Delay (Seconds)" in the `ladspa_set` commands, but chose to use a much 196shorter version: "Delay". 197 198When specifying a port name for the `ladspa_link` and `ladspa_set` commands, 199the system will look for any port that *starts with* the name you gave it. If 200there is only one match, then that port is chosen. If there are multiple 201matches (meaning your port name is ambiguous), you will see an error asking 202you to be more specific. So the configuration for the "e1" effect could also 203have been written with much shorter port names: 204``` 205ladspa_effect e1 /usr/lib/ladspa/delay.so 206ladspa_link e1 In Main:L 207ladspa_link e1 Out Main:L 208ladspa_set e1 Del 0.5 209``` 210 211# Signal Flow 212 213The LADSPA effects unit runs immediately after the internal reverb and chorus 214effects have been processed. When no effects have been configured, the LADSPA 215engine is dormant and uses no additional system resources. 216 217When at least one effect is configured and the engine is activated, the rendered 218audio is passed into the LADSPA effects engine, the effects are run in the order 219that they were created and the resulting audio is passed back into FluidSynth 220(and from there to the sound card or other output). 221 222## Effect Sends 223 224Please note that SoundFont designers can specify how much signal each 225instrument should add to the reverb and chorus effect sends. When FluidSynth 226renders a block of audio, all currently sounding instruments are mixed into the 227`Main` output channels. In addition, all instruments add their signal to the 228effect send ports (`Reverb:Send` and `Chorus:Send`) according to the effect 229send amount specified in the SoundFont. 230 231If you want to replace the internal reverb or chorus effects with a LADSPA 232plugin and you want to honour the decisions made by the SoundFont designer, you 233should use the `Reverb:Send` or `Chorus:Send` ports as effect input and 234`Main:L` and `Main:R` ports as effect outputs. (See the "Example Setups" section 235below for an example on how to replace the internal reverb with a LADSPA plugin.) 236 237Please note that FluidSynth uses a mono signal for both effects, that is why 238there is only a single send port for reverb and chorus. 239 240 241# LADSPA Command Reference 242 243The following is a description of all LADSPA-related commands that are 244available in the FluidSynth shell if it has been compiled with LADSPA 245support. 246 247- `ladspa_effect`: Create a new effect from a plugin library 248- `ladspa_buffer`: Create a new buffer 249- `ladspa_link`: Link an effect port to a host port or a buffer 250- `ladspa_set`: Set the value of an effect control 251- `ladspa_check`: Check the effect setup for any problems 252- `ladspa_start`: Start the effects unit 253- `ladspa_stop`: Stop the effects unit 254- `ladspa_reset`: Reset the effects unit 255 256## ladspa_effect 257 258``` 259ladspa_effect <effect-name> <library-path> [plugin-name] [--mix [gain]] 260``` 261 262Load the LADSPA plugin library given by `<library-path>` and create a new effect 263(i.e. an instance of a plugin). `<effect-name>` can be chosen by the user and must 264unique. `<plugin-name>` is optional if the library contains only one plugin. 265 266If the optional `--mix` parameter is given, then the LADSPA engine will call the 267`run_adding` interface of the plugin. This will make the effect add it's output 268to the output buffers instead of replacing them. The `--mix` parameter takes an 269optional float value `gain`, which will be multiplied with each sample before 270adding to the output buffers. 271 272Please note that there is no command to delete a single effect once created. To 273remove effects, please use `ladspa_reset` to clear everything start from 274scratch. 275 276Can only be called when the effect unit is not active. 277 278## ladspa_buffer 279 280``` 281ladspa_buffer <buffer-name> 282``` 283 284Create a new audio buffer called `<buffer-name>`. The buffer is able to be used as 285mono output or mono input to an effect. Buffers can be used to connect plugins 286between each other without overwriting the host ports with temporary data. 287 288Please note that there is no command to delete a buffer. To remove buffers, 289please use `ladspa_reset` to clear everything and start from scratch. 290 291Can only be used when the effect unit is not active. 292 293## ladspa_link 294 295``` 296ladspa_link <effect-name> <audio-port-name> <buffer-or-host-port-name> 297``` 298 299Connects an effect input or output port with a buffer or a host port. This 300command can be called multiple times and will overwrite the previous connection 301made on that effect port. 302 303Please note that there is no command to unlink an effect port. Use 304`ladspa_reset` to clear everything and start from scratch. 305 306Can only be used when the effect unit is not active. 307 308## ladspa_set 309 310``` 311ladspa_set <effect-name> <control-port-name> <float-value> 312``` 313 314Sets a control port of an effect to a float value. Can be used at any time, 315even when the effect unit is active. 316 317## ladspa_check 318 319``` 320ladspa_check 321``` 322 323Checks the LADSPA effect configuration for errors. This command is also 324implicitly called when executing `ladspa_start`. 325 326## ladspa_start 327 328``` 329ladspa_start 330``` 331 332Activates the effects unit and inserts the configured effects into FluidSynth's 333audio rendering pipeline. 334 335## ladspa_stop 336 337``` 338ladspa_stop 339``` 340 341Deactivates the effects unit and removes the configured effects from 342FluidSynth's audio rendering pipeline. The configuration is left untouched, so 343it can be started again with `ladspa_start`. 344 345## ladspa_reset 346 347``` 348ladspa_reset 349``` 350 351Deactivates the effects unit if active and clears all configuration and loaded 352plugins. 353 354 355# Example Setups 356 357All examples assume that your `LADSPA_PATH` environment variable points to the 358directory containing the plugin libraries (e.g. /usr/lib/ladspa). 359 360## Single Plugin 361 362The following loads the delay.so plugin library from the LADSPA SDK and 363instantiates the delay effect under the name "e1". It connects the main left 364audio channel from FluidSynth with the plugin input and output and starts the 365effects engine. 366 367``` 368ladspa_effect e1 delay.so 369ladspa_link e1 Input Main:L 370ladspa_link e1 Output Main:L 371ladspa_start 372``` 373 374The audible effect should be an untouched right channel and a slightly 375lower volume on the left with a delay effect of 1 second on top. 376 377## Replacing the FluidSynth Reverb Effect 378 379If you would like a different reverb implementation than the one built-in to 380FluidSynth, you can use a LADSPA reverb plugin like the "TAP Reverb" from 381[Tom's Audio Processing plugins](http://tap-plugins.sourceforge.net/ladspa.html). 382 383Here is the analyseplugin output for the `tap_reverb.so` plugin: 384``` 385user@host:$ analyseplugin /usr/lib/ladspa/tap_reverb.so 386 387Plugin Name: "TAP Reverberator" 388Plugin Label: "tap_reverb" 389Plugin Unique ID: 2142 390Maker: "Tom Szilagyi" 391Copyright: "GPL" 392Must Run Real-Time: No 393Has activate() Function: Yes 394Has deactivate() Function: No 395Has run_adding() Function: Yes 396Environment: Normal 397Ports: "Decay [ms]" input, control, 0 to 10000, default 2500 398 "Dry Level [dB]" input, control, -70 to 10, default 0 399 "Wet Level [dB]" input, control, -70 to 10, default 0 400 "Comb Filters" input, control, toggled, default 1 401 "Allpass Filters" input, control, toggled, default 1 402 "Bandpass Filter" input, control, toggled, default 1 403 "Enhanced Stereo" input, control, toggled, default 1 404 "Reverb Type" input, control, 0 to 42.1, default 0, integer 405 "Input Left" input, audio 406 "Output Left" output, audio 407 "Input Right" input, audio 408 "Output Right" output, audio 409``` 410 411Using this information we can create a LADSPA configuration: 412 413effects.txt 414``` 415ladspa_effect e1 /usr/lib/ladspa/tap_reverb.so 416ladspa_link e1 "Input Left" Reverb:Send 417ladspa_link e1 "Input Right" Reverb:Send 418ladspa_link e1 "Output Left" Main:L 419ladspa_link e1 "Output Right" Main:R 420ladspa_start 421``` 422 423Start FluidSynth with the internal reverb disabled. (You will need to replace 424the `test.mid` with your own MIDI file and maybe change the paths to the 425effects.txt file and the SoundFont) 426 427``` 428user@host:$ fluidsynth -a alsa -R0 -o synth.ladspa.active=1 -f effects.txt FluidR3_GM.sf2 test.mid 429``` 430 431You will hear the output with a reverb effect from the plugin. And you can 432change the reverb control ports with the `ladspa_set` command while the MIDI 433file is playing. 434 435# Multi-Channel Output 436 437FluidSynth is capable of generating multi-channel output by specifying the 438`synth.audio-groups` and `synth.audio-channels` configuration settings. 439Explaining multi-channel output in detail is out of scope for this guide. But 440using multiple output channels has an effect on the host ports that are 441available to LADSPA plugins. 442 443As soon as you configure more than one audio-channel, the main audio ports will 444not be called "Main:L" and "Main:R" anymore, but will have indices added to 445their name. So if you start FluidSynth with `-o synth.audio-groups=2`, then the 446following ports will be created: 447 448- Main:L1 449- Main:R1 450- Main:L2 451- Main:R2 452- Reverb:Send 453- Chorus:Send 454 455If you want all main ports to act as outputs as well as inputs to the effects, 456then you also need to increase the `synth.audio-channels` setting. 457 458 459# LADSPA on other Platforms 460 461LADSPA is a very simple plugin architecture and only requires the ladspa.h 462header file as compile-time dependency. To build FluidSynth on non-Linux 463platform with LADSPA support, download the ladspa.h file from 464https://www.ladspa.org and place it somewhere in your compiler include path. Then 465configure and build LADSPA as you normally would. 466 467All information in the above documentation is valid for all other platforms as 468well. Just make sure you use the file path format specific to your platform in 469the `ladspa_effect` calls. For example, on Windows you should use 470``` 471ladspa_effect c:\path\to\ladspa\plugin.dll 472``` 473instead of 474``` 475ladspa_effect /path/to/ladspa/plugin.so 476``` 477 478Audacity provides a large number of precompiled LADSPA plugins for Windows and 479MacOS: https://www.audacityteam.org/download/plug-ins/ 480 481To get the `analyseplugin` and `listplugins` commands on Windows, you can either 482compile them yourself using the LADSPA-SDK source code from ladspa.org or install 483ladspa-sdk via Cygwin. 484