From 81f30ce6d1e0dab7b3d92ef2fbbbef2420c1b279 Mon Sep 17 00:00:00 2001 From: derselbst Date: Thu, 28 Sep 2017 20:08:53 +0200 Subject: [PATCH 01/16] add a test file for documenting fluid settings --- doc/fluidsettings.xml | 86 +++++++++++++++++++++++++++++++++++++++++++ doc/fluidsettings.xsl | 70 +++++++++++++++++++++++++++++++++++ 2 files changed, 156 insertions(+) create mode 100644 doc/fluidsettings.xml create mode 100644 doc/fluidsettings.xsl diff --git a/doc/fluidsettings.xml b/doc/fluidsettings.xml new file mode 100644 index 00000000..a5fb53fd --- /dev/null +++ b/doc/fluidsettings.xml @@ -0,0 +1,86 @@ + + + + + + something + int + 10 + 0-90 + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + asdf + num + 10 + [0;90] + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + qwer + bool + 10 + 0-90 + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + ölkj + str + 10 + "asdf", "jköl", "qwertz" + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + oipu + int + 10 + 0-90 + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + + + + + + channels + int + 10 + 0-90 + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + sample-timer + int + 10 + 0-90 + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + + + + reset-synth + bool + 10 + 0-90 + some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + + + + diff --git a/doc/fluidsettings.xsl b/doc/fluidsettings.xsl new file mode 100644 index 00000000..9372180f --- /dev/null +++ b/doc/fluidsettings.xsl @@ -0,0 +1,70 @@ + + + + + + + + +

FluidSettings

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
NameTypeDefault ValueAllowed ValuesDescription
+ . + + + + + + + + + + +
+ + + + + From 6e9f73afb83fe8f23220f95e94f24ddb19be8545 Mon Sep 17 00:00:00 2001 From: derselbst Date: Sun, 1 Oct 2017 14:26:32 +0200 Subject: [PATCH 02/16] port synth settings to xml --- doc/fluidsettings.xml | 202 +++++++++++++++++++++++++++++++++++------- doc/fluidsettings.xsl | 69 ++++++++++----- 2 files changed, 219 insertions(+), 52 deletions(-) diff --git a/doc/fluidsettings.xml b/doc/fluidsettings.xml index a5fb53fd..ce9cea83 100644 --- a/doc/fluidsettings.xml +++ b/doc/fluidsettings.xml @@ -3,56 +3,194 @@ - something + audio-channels int - 10 - 0-90 - some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + 1 + 1 + 128 + + By default, the synthesizer outputs a single stereo signal. Using this option, the synthesizer can output multichannel audio. Sets the number of stereo channel pairs. So 1 is actually 2 channels (a stereo pair). - asdf - num - 10 - [0;90] - some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + audio-groups + int + 1 + 1 + 128 + + Normally the same value as synth.audio-channels. LADSPA effects subsystem can use this value though, in which case it may differ. - qwer + chorus.active bool - 10 - 0-90 - some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + 1 (TRUE) + + When set to 1 (TRUE) the chorus effects module is activated. Otherwise, no chorus will be added to the output signal. Note that the amount of signal sent to the chorus module depends on the "chorus send" generator defined in the SoundFont. - ölkj + cpu-cores + int + 1 + 1 + 256 + + (Experimental) Sets the number of synthesis CPU cores. If set to a value greater than 1, then additional synthesis threads will be created to take advantage of a multi CPU or CPU core system. This has the affect of utilizing more of the total CPU for voices or decreasing render times when synthesizing audio to a file. + + + device-id + int + 0 + 0 + 126 + + Device identifier used for SYSEX commands, such as MIDI Tuning Standard commands. Only those SYSEX commands destined for this ID or to all devices will be acted upon. + + + ladspa.active + bool + 0 (FALSE) + + When set to "yes" the LADSPA subsystem will be enabled. This subsystem allows to load and interconnect LADSPA plug-ins. The output of the synthesizer is processed by the LADSPA subsystem. Note that the synthesizer has to be compiled with LADSPA support. More information about the LADSPA subsystem later. + + + midi-channels + int + 16 + 16 + 256 + + This setting defines the number of MIDI channels of the synthesizer. The MIDI standard defines 16 channels, so MIDI hardware is limited to this number. Internally FluidSynth can use more channels which can be mapped to different MIDI sources. + + + midi-bank-select str - 10 - "asdf", "jköl", "qwertz" - some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + gs + gm, gs, xg, mma + + This setting defines how the synthesizer interprets Bank Select messages. +
    +
  • gm: ignores CC0 and CC32 messages.
    • +
  • gs: (default) CC0 becomes the bank number, CC32 is ignored.
    • +
  • xg: CC32 becomes the bank number, CC0 is ignored.
    • +
  • mma: bank is calculated as CC0*128+CC32.
    • +
+ - oipu + min-note-length int 10 - 0-90 - some very very very very very very very very very very very very very very long very very very very very very very very very very very very very very very very very very very desc goes here + 0 + 65535 + + Sets the minimum note duration in milliseconds. This ensures that really short duration note events, such as percussion notes, have a better chance of sounding as intended. Set to 0 to disable this feature. + + + parallel-render + bool + 1 (TRUE) + + This is the low-latency setting. If on, you're allowed to call fluid_synth_write_s16, fluid_synth_write_float, +fluid_synth_nwrite_float or fluid_synth_process in parallel with the +rest of the calls, and it won't be blocked by time intensive calls to +the synth. Turn it off if throughput is more important than latency, e g +in rendering-to-file scenarios where underruns is not an issue. +

Deprecated:
As of 1.1.7 this option is deprecated. This option enforces thread safety for rvoice_mixer, which causes rvoice_events to be queued internally. The current implementation relies on the fact that this option is set to TRUE to correctly render any amount of requested audio. Also calling fluid_synth_write_* in parallel is not considered to be a use-case. It would cause undefined audio output, as it would be unpredictable for the user which rvoice_events specifically would be dispatched to which fluid_synth_write_* call. + + + + polyphony + int + 256 + 1 + 65535 + + The polyphony defines how many voices can be played in parallel. A note event produces one or more voices. Its good to set this to a value which the system can handle and will thus limit FluidSynth's CPU usage. When FluidSynth runs out of voices it will begin terminating lower priority voices for new note events. + + + reverb.active + bool + 1 (TRUE) + + When set to 1 (TRUE) the reverb effects module is activated. Otherwise, no reverb will be added to the output signal. Note that the amount of signal sent to the reverb module depends on the "reverb send" generator defined in the SoundFont. + + + + sample-rate + num + 44100.0 + 22050.0 + 96000.0 + + The sample rate of the audio generated by the synthesizer. + + + + threadsafe-api + bool + 1 (TRUE) + + Controls whether the synth's public API is protected by a mutex or not. Default is on, turn it off for slightly better performance if you know you're only accessing the synth from one thread only, this could be the case in many embedded use cases for example. Note that libfluidsynth can use many threads by itself (shell is one, midi driver is one, midi player is one etc) so you should usually leave it on. Also see synth.parallel-render. + + + + verbose + bool + 0 (FALSE) + + When set to 1 (TRUE) the synthesizer will print out information about the received MIDI events to the stdout. This can be helpful for debugging. This setting cannot be changed after the synthesizer has started. + + + + volenv + str + emu + compliant, emu + + Specifies the kind of volume envelope processing. This + esp. influences the way fluidsynth responses to noteon velocity. + The default setting 'emu' causes the envelope to be highly + dynamic (i.e. compatible with the EMU10K1). Alternatively this + may be set to 'compliant' for a less dynamic envelope, as it was + done before fluidsynth 1.0.9. Note that this setting can only be + changed until the first synth has been created. Changing it + afterwards will have no effect for the rest of fluidsynths +lifetime. + + + + effects-channels + int + 2 + 2 + 2 + Currently unused. + + + gain + num + 0.2 + 0.0 + 10.0 + The gain is applied to the final or master output of the synthesizer. It is set to a low value by default to avoid the saturation of the output when many notes are played. + diff --git a/doc/fluidsettings.xsl b/doc/fluidsettings.xsl index 9372180f..51aa1ccf 100644 --- a/doc/fluidsettings.xsl +++ b/doc/fluidsettings.xsl @@ -4,10 +4,30 @@ @@ -44,7 +52,7 @@ td Type Default Value Allowed Values - Description + @@ -57,7 +65,7 @@ td - + . @@ -86,8 +94,12 @@ td - - + + + + + + From 78233a191de5e6abdffe0f4856f487d74ca7c6d1 Mon Sep 17 00:00:00 2001 From: derselbst Date: Mon, 2 Oct 2017 16:46:18 +0200 Subject: [PATCH 06/16] port midi settings to xml --- doc/fluidsettings.xml | 48 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/doc/fluidsettings.xml b/doc/fluidsettings.xml index 8fd0bd9c..c31f9372 100644 --- a/doc/fluidsettings.xml +++ b/doc/fluidsettings.xml @@ -434,6 +434,54 @@ lifetime. + + + device + str + default + ALSA MIDI device to use for RAW ALSA MIDI driver. + + + + + + device + str + default + ALSA sequencer device to use for ALSA sequencer driver. + + + id + str + pid + ID to use when registering ports with the ALSA sequencer driver. If set to "pid" then the ID will be "FLUID Synth (PID)", where PID is the FluidSynth process ID of the audio thread otherwise the provided string will be used in place of PID. + + + + + + server + str + + Jack server to connect to for Jack MIDI driver. If an empty string then the default server will be used. + + + id + str + fluidsynth-midi + Client ID to use with the Jack MIDI driver. + + + + + + device + str + /dev/midi + Device to use for OSS MIDI driver. + + + reset-synth From 51181c679a3bc657687f7d2b0148df3f229fd7ca Mon Sep 17 00:00:00 2001 From: derselbst Date: Mon, 9 Oct 2017 21:10:47 +0200 Subject: [PATCH 07/16] revise layout of fluid settings documentation force it into the currently used table layout --- doc/fluidsettings.xsl | 109 ++++++++++++++++++++++++++++-------------- 1 file changed, 72 insertions(+), 37 deletions(-) diff --git a/doc/fluidsettings.xsl b/doc/fluidsettings.xsl index c7a2d82e..92109d55 100644 --- a/doc/fluidsettings.xsl +++ b/doc/fluidsettings.xsl @@ -6,38 +6,45 @@ @@ -58,7 +58,7 @@ td - + From 32cf418631a5afb87b66a14aa174212e06bb46cf Mon Sep 17 00:00:00 2001 From: derselbst Date: Mon, 16 Oct 2017 17:10:28 +0200 Subject: [PATCH 12/16] add a simple TOC to fluidsettings --- doc/fluidsettings.xml | 5 +++++ doc/fluidsettings.xsl | 31 +++++++++++++++++++++++++------ 2 files changed, 30 insertions(+), 6 deletions(-) diff --git a/doc/fluidsettings.xml b/doc/fluidsettings.xml index 95c18bdf..1c002782 100644 --- a/doc/fluidsettings.xml +++ b/doc/fluidsettings.xml @@ -11,6 +11,7 @@ https://stackoverflow.com/a/6251757 + Synthesizer settings audio-channels int 1 @@ -174,6 +175,7 @@ https://stackoverflow.com/a/6251757 From 69a4ce44c3b1a135d01b8060eac74d60cede51b2 Mon Sep 17 00:00:00 2001 From: derselbst Date: Wed, 18 Oct 2017 18:03:44 +0200 Subject: [PATCH 16/16] remove fluidsettings doc from manpage refer to xml instead --- doc/fluidsynth.1 | 227 +---------------------------------------------- 1 file changed, 1 insertion(+), 226 deletions(-) diff --git a/doc/fluidsynth.1 b/doc/fluidsynth.1 index 6074ff22..9dc2f238 100644 --- a/doc/fluidsynth.1 +++ b/doc/fluidsynth.1 @@ -141,232 +141,7 @@ Show version of program Size of each audio buffer .SH SETTINGS - -All settings are non-realtime (have no effect if set after startup), except for those -indicated as realtime. - -.TP -.B SYNTHESIZER - -.TP -.B synth.audio\-channels INT [min=1, max=128, def=1] -Number of audio channels (DOCME!). -.TP -.B synth.audio\-groups INT [min=1, max=128, def=1] -Number of audio groups (DOCME!). -.TP -.B synth.chorus.active BOOL [def=True] -Chorus effect enable toggle. -.TP -.B synth.cpu\-cores INT [min=1, max=256, def=1] -Number of CPU cores to use for multi-core support. -.TP -.B synth.device\-id INT [min=0, max=126, def=0] REALTIME -Device ID to use for accepting incoming SYSEX messages. -.TP -.B synth.effects\-channels INT [min=2, max=2, def=2] -No effect currently. -.TP -.B synth.gain FLOAT [min=0.000, max=10.000, def=0.200] REALTIME -Master synthesizer gain. -.TP -.B synth.ladspa.active BOOL [def=False] -LADSPA subsystem enable toggle. -.TP -.B synth.midi\-channels INT [min=16, max=256, def=16] -Total MIDI channel count (must be multiple of 16). -.TP -.B synth.midi\-bank\-select STR [def='gs' vals:'gm', 'gs', 'xg', 'mma'] -MIDI Bank Select message style. -.TP -.B synth.min\-note\-length INT [min=0, max=65535, def=10] -Minimum duration for note events (work around for very short percussion notes). -.TP -.B synth.overflow.age FLOAT [min=\-10000, max=10000, def=1000] -Weigthing (on overflow) for a voice's duration. -.TP -.B synth.overflow.percussion FLOAT [min=\-10000, max=10000, def=4000] -Weighting (on overflow) for a voice being on the drum channel. -.TP -.B synth.overflow.released FLOAT [min=\-10000, max=10000, def=\-2000] -Weighting (on overflow) for a voice that has been released, -i e note off and no sustain pedal. -.TP -.B synth.overflow.sustained FLOAT [min=\-10000, max=10000, def=\-1000] -Weighting (on overflow) for a voice that has been sustained, -i e note off, but sustain pedal held down. -.TP -.B synth.overflow.volume FLOAT [min=\-10000, max=10000, def=500] -Weighting (on overflow) for a voice's volume. -.TP -.B synth.parallel-render BOOL [def=True] -Enables low-latency audio rendering response, even if synth is otherwise busy. -Should always to be true for usage by fluidsynth executable. -.TP -.B synth.polyphony INT [min=1, max=65535, def=256] REALTIME -Voice polyphony count (number of simultaneous voices allowed). -.TP -.B synth.reverb.active BOOL [def=True] -Reverb effect enable toggle. -.TP -.B synth.sample\-rate FLOAT [min=22050.000, max=96000.000, def=44100.000] -Synthesizer sample rate. -.TP -.B synth.threadsafe-api BOOL [def=True] -Serializes access to the synth API. -Must always to be true for usage by fluidsynth executable. -.TP -.B synth.verbose BOOL [def=False] -Print received MIDI events to stdout. -.TP -.B synth.volenv STR [def='emu' vals:'compliant', 'emu'] -Specifies the kind of volume envelope processing. This esp. influences the way fluidsynth responses to noteon velocity. The default setting 'emu' causes the envelope to be highly dynamic (i.e. compatible with the EMU10K1). Alternatively this may be set to 'compliant' for a less dynamic envelope, as it was done before fluidsynth 1.0.9. - -.TP -.B GENERAL AUDIO - -.TP -.B audio.driver STR -Audio driver to use. Default and valid options depend on available drivers. -.TP -.B audio.input\-channels INT [min=0, max=2, def=0] -Not used currently? (DOCME). -.TP -.B audio.output\-channels INT [min=2, max=32, def=2] -DOCME -.TP -.B audio.period\-size INT [min=64, max=8192, def=64] -Period size for audio buffers. Used by many audio drivers. -.TP -.B audio.periods INT [min=2, max=64, def=16] -Count of audio buffers. Used by many audio drivers. -.TP -.B audio.realtime\-prio INT [min=0, max=99, def=60] -Realtime priority to assign to audio thread or 0 to disable high priority scheduling. -Only used by some audio drivers (currently 'alsa' and 'oss'). -.TP -.B audio.sample\-format STR [def='16bits' vals:'16bits','float'] -Audio output format, to select format for those drivers which support 16 bit or floating point. - -.TP -.B AUDIO DRIVER SPECIFIC - -.TP -.B audio.alsa.device STR [def='default'] -ALSA audio driver output device. -.TP -.B audio.coreaudio.device STR [def='default'] -CoreAudio driver output device. Valid options depend on system. -.TP -.B audio.dart.device STR [def='default'] -OS/2 Dart audio driver device. -.TP -.B audio.dsound.device STR [def='default'] -Device to use for DirectSound driver. Valid options depend on system. -.TP -.B audio.file.endian STR [def='auto' vals:'auto','big','cpu','little'] -File renderer or file driver byte order selection. 'auto' selects the default for the selected -file type. 'cpu' uses the CPU byte order. Limited to 'cpu' if no libsndfile support. -.TP -.B audio.file.format STR [def='s16' vals:'double','float','s16','s24','s32','s8','u8'] -File renderer or file driver audio format. Limited to 's16' if no libsndfile support. -.TP -.B audio.file.name STR [def='fluidsynth.wav'] -Output file name for file renderer or file driver. -.TP -.B audio.file.type STR [def='auto' vals:'aiff','au','auto','flac','oga','raw','wav'] -Output file type for file renderer or file driver. 'auto' attempts to determine type from file -extension in audio.file.name. Limited to 'raw' if no libsndfile support. Actual options will vary -depending on libsndfile library. -.TP -.B audio.jack.autoconnect BOOL [def=False] -If enabled, then FluidSynth is automatically connected to Jack system audio output ports. -.TP -.B audio.jack.id STR [def='fluidsynth'] -Client ID to use when connecting to Jack. -.TP -.B audio.jack.multi BOOL [def=False] -TRUE to enable multi-channel output. -.TP -.B audio.jack.server STR [def=''] -Jack server name. Blank for default. -.TP -.B audio.oss.device STR [def='/dev/dsp'] -OSS driver output device. -.TP -.B audio.portaudio.device STR [def='PortAudio Default'] -PortAudio driver output device. Available options depends on system. -.TP -.B audio.pulseaudio.adjust-latency BOOL [def=True] -Increases the latency dynamically if PulseAudio suggests so. -.TP -.B audio.pulseaudio.device STR [def='default'] -PulseAudio driver output device. -.TP -.B audio.pulseaudio.media-role STR [def='music'] -PulseAudio media role information. -.TP -.B audio.pulseaudio.server STR [def='default'] -PulseAudio driver server. - -.TP -.B GENERAL MIDI - -.TP -.B midi.driver STR -MIDI driver to use. Default and valid options depend on available drivers. -.TP -.B midi.realtime\-prio INT [min=0, max=99, def=50] -Realtime priority to assign to MIDI thread or 0 to disable high priority scheduling. -Only used by some MIDI drivers (currently 'alsa_seq', 'alsa_raw' and 'oss'). - -.TP -.B MIDI DRIVER SPECIFIC - -.TP -.B midi.alsa.device STR [def='default'] -ALSA raw MIDI driver device. -.TP -.B midi.alsa_seq.device STR [def='default'] -ALSA sequencer MIDI driver device. -.TP -.B midi.alsa_seq.id STR [def='pid'] -ALSA sequencer client ID. 'pid' will use process ID as part of the client name. -.TP -.B midi.coremidi.id STR [def='pid'] -Client ID to use for CoreMIDI driver. 'pid' will use process ID as port of the client name. -.TP -.B midi.jack.id STR [def='fluidsynth-midi'] -Jack MIDI driver client ID. -.TP -.B midi.jack.server STR [def=''] -Jack MIDI driver server. Blank to use default. -.TP -.B midi.oss.device STR [def='/dev/midi'] -OSS MIDI driver device. -.TP -.B midi.portname STR [def=''] -Port name used for CoreAudio and ALSA sequencer drivers. -.TP -.B midi.winmidi.device STR [def='default'] -Device for Windows MIDI driver. - -.TP -.B MISCELLANEOUS - -.TP -.B player.reset\-synth BOOL [def=True] -TRUE to reset synthesizer MIDI state between MIDI songs. -.TP -.B player.timing\-source STR [def='sample' vals:'sample','system'] -Selects timing source for MIDI sequencer. 'system' uses the system timer. 'sample' -uses the sample clock (amount of audio output, events synchronized with audio). -.TP -.B shell.port INT [min=1, max=65535, def=9800] -Shell command server TCP/IP port number to use. -.TP -.B shell.prompt STR [def=''] -Shell prompt string. +The settings to be specified with \-o are documented in the fluidsettings.xml hopefully shipped with this distribution or online at http://www.fluidsynth.org/api/fluidsettings.xml . We recommend viewing this file in a webbrowser, favourably Firefox. .SH SHELL COMMANDS .TP