SETBFREE(1)

📦
version 0.8.17 · 4 versions
, in arch rolling, debian trixie, fedora 43, fedora 44, ubuntu questing, ubuntu resolute, ubuntu stonking

🌸 setBfree — DSP tonewheel organ 🌸

okay bestie, welcome to SETBFREE(1), aka the User Commands corner of the manual, aka the place where we talk about a whole entire software synthesizer. sit down, grab a strawberry 🍓, we're doing this.

✨ NAME ✨

setBfree — DSP tonewheel organ. that's it, that's the name. iconic. no cap. 👑

🎀 SYNOPSIS 🎀

setBfree [ OPTIONS ] [ property=value ... ]

like, you give it some options, you give it some property=value pairs, and it sings. 💅

🦋 DESCRIPTION 🦋

setBfree — DSP tonewheel organ. (yes, again, because the manpage said it twice and we do not skip things in this house.)

so like, setBfree is a MIDI-controlled, software synthesizer designed to imitate the sound and properties of the electromechanical organs and sound modification devices that brought world-wide fame to the names and products of Laurens Hammond and Don Leslie. literally the whole vibe. the main character energy of organs. if you know you know. 🎹✨

💖 OPTIONS 💖

  • -c <filename>, --config <filename> — Load alternate config file over default. bye default, hello your config.
  • -C, --noconfig — Do not read the default configuration file. the equivalent built-in defaults are still set, so you're not left with nothing, bestie.
  • -d, --dumpcc — Print a list of MIDI-CC mappings on startup. like a little receipt of all your mappings 🧾
  • -D, --noCC — do not load default CC map on startup.
  • -h — Print short help text. the tl;dr version.
  • -H, --help — Print complete help text with parameter list. the full unhinged version, we love her.
  • -l <pgm> — Load a MIDI program-preset at startup (may override previous settings given with -r, -U,..). so like, order matters, she has opinions.
  • -M <filename>, --midnam <filename> — export current controller mapping to .midnam file.
  • -p <filename>, --program <filename> — Load alternate program file over default.
  • -P, --noprogram — Do not read the default program file. the built-in programs are cleared as well. so it's giving empty. 😭
  • -r, --randomize — Randomize initial preset (whacky but true). WHACKY BUT TRUE. it's in the manual, I'm not making this up.
  • -U, --upper <drawbar settings> — Specify initial drawbar settings, for the upper manual as 9 digits. e.g. 808000000
  • -V, --version — Print version information. flex the number, babe. 🌈

🌟 General Information 🌟

okay so this part is important, pay attention, no scrolling past.

The configuration consists of two parts: program (pgm) and config (cfg).

The static configuration of the properties of the instrument is defined in a .cfg file. There is no need to specify a config-file, as all configurable parameters have built-in default values. They can be overridden on startup using 'property=value' pairs or by loading a specific .cfg file. As the name /static implies, the properties can only be set on application start. Yet many of the properties merely define the initial value of settings which can later be modified during playback. The ones which can be dynamically modified are marked with an asterisk (*).

Properties are modified by sending MIDI Control-Commands (CC) to the synth. The mapping of CCs to function can be modified by setting the "midi.controller.{upper|lower|pedal}.<CC>=<function>" property. Function-names are equivalent to property-names. e.g. "midi.controller.upper.22=overdrive.outputgain" assigns the overdrive-gain to MIDI-CC 22 on MIDI-channel 1 (upper). (Note: each function can assigned only once, however MIDI-CC can be re-used and trigger multiple function at the same time.)

The program basically defines shortcuts. Loading a program is usually equivalent to sending a series of CC. Programs are commonly used to define instruments (e.g. draw-bar settings to mimic a flute) or provide scalepoints (e.g. reverb=64). There are a few special commands which are only available by recalling a program (randomize settings, split-manuals, enable overdrive).

Programs are defined in a .pgm file and are fixed after starting the application. They are activated by sending MIDI-program-change messages (also known as presets). MIDI-banks are ignored. So at most 127 programs can be specified.

At startup 'default.cfg' and 'default.pgm' in $XDG_CONFIG_HOME/setBfree/ (default: $HOME/.config/setBfree/) are are evaluated if the files exist, unless '--noconfig' or '--noprogram' options are given. An additional config or program file can be loaded using the '-c' and '-p' option respectively.

Example config: "/usr/share/setBfree/cfg/default.cfg"

Example program: "/usr/share/setBfree/pgm/default.pgm"

💜 Instrument Properties 💜

Below is a list of available property-value pairs and their default values. The default value is omitted "(-)" for properties which contain an array of values.

The type identifiers are:

  • 'S': text-string
  • 'I': integer
  • 'F': float
  • 'D': double-precision float

Properties marked with an asterisk (*) are available as MIDI CC functions. When used as CC, the values 0-127 (MIDI data) is mapped to a range of values appropriate to the function. In config-files or on the command-line you must you the type as specified e.g. "osc.temperament=gear60 osc.wiring-crosstalk=0.2"

🎛️ Parameters for 'Main' 🎛️

  • midi.driver — S ("jack") — The midi driver to use, 'jack' or 'alsa'
  • midi.port — S ("") — The midi port(s) to auto-connect to. With alsa it's a single port-name or number, jack accepts regular expressions.
  • jack.connect — S ("system:playback_") — Auto connect both audio-ports to a given regular-expression. This setting is ignored if either of jack.out.{left|right} is specified.
  • jack.out.left — S ("") — Connect left-output to this jack-port (exact name)
  • jack.out.right — S ("") — Connect right-output to this jack-port (exact name)

🎹 Parameters for 'MIDI Parser' 🎹

  • midi.upper.channel — I (1) — The MIDI channel to use for the upper-manual. range: [1..16]
  • midi.lower.channel — I (2) — The MIDI channel to use for the lower manual. range: [1..16]
  • midi.pedals.channel — I (3) — The MIDI channel to use for the pedals. range: [1..16]
  • midi.controller.reset — I ("-") — Clear existing CC mapping for all controllers (if non-zero argument is given). See also -D option.
  • midi.controller.upper.<cc> — S ("-") — Specify a function-name to bind to the given MIDI control-command. <cc> is an integer 0..127. Defaults are in midiPrimeControllerMapping() and can be listed using the '-d' commandline option. See general information.
  • midi.controller.lower.<cc> — S ("-") — see midi.controller.upper
  • midi.controller.pedals.<cc> — S ("-") — see midi.controller.upper
  • midi.transpose — I (0) — Global transpose (noteshift) in semitones.
  • midi.upper.transpose — I (0) — Shift/transpose MIDI-notes on upper-manual
  • midi.lower.transpose — I (0) — Shift/transpose MIDI-notes on lower-manual
  • midi.pedals.transpose — I (0) — Shift/transpose MIDI-notes on pedals
  • midi.upper.transpose.split — I (0) — Noteshift for upper manual in split mode
  • midi.lower.transpose.split — I (0) — Noteshift for lower manual in split mode
  • midi.pedals.transpose.split — I (0) — Noteshift for lower manual in split mode

🧚 Parameters for 'MIDI Program Parser' 🧚

  • pgm.controller.offset — I (1) — Compensate for MIDI controllers that number the programs from 1 to 128. Internally we use 0-127, as does MIDI. range: [0,1]

🌈 Parameters for 'Tone Generator' 🌈

this is the big one, the moment, the era. 🫶

  • osc.tuning — D (440.0) — Base tuning of the organ.
  • osc.temperament — S ("gear60") — Tuning temperament, gear-ratios/motor-speed. One of: "equal", "gear60", "gear50"
  • osc.x-precision — D (0.001) — Wave precision. Maximum allowed error when calculating wave buffer-length for a given frequency (ideal #of samples - discrete #of samples)
  • osc.perc.fast — D (1.0) — Fast percussion decay time
  • osc.perc.slow — D (4.0) — Slow percussion decay time
  • osc.perc.normal — D (1.0) — Percussion starting gain of the envelope for normal volume.
  • osc.perc.soft — D (0.5012) — Percussion starting gain of the envelope for soft volume.
  • osc.perc.gain — D (11.0) — Basic volume of the percussion signal, applies to both normal and soft
  • osc.perc.bus.a — I (3) — range [0..8]
  • osc.perc.bus.b — I (4) — range [0..8]
  • osc.perc.bus.trig — I (8) — range [-1..8]
  • osc.eq.macro — S ("chspline") — one of "chspline", "peak24", "peak46"
  • osc.eq.p1y — D (1.0) — EQ spline parameter
  • osc.eq.r1y — D (0.0) — EQ spline parameter
  • osc.eq.p4y — D (1.0) — EQ spline parameter
  • osc.eq.r4y — D (0.0) — EQ spline parameter
  • osc.eqv.ceiling — D (1.0) — Normalize EQ parameters.
  • osc.eqv.<oscnum> — D (-) — oscnum=[0..127], value: [0..osc.eqv.ceiling]; default values are calculated depending on selected osc.eq.macro and tone-generator-model.
  • osc.harmonic.<h> — D (-) — specify level of given harmonic number.
  • osc.harmonic.w<w>.f<h> — D (-) — w: number of wheel [0..91], h: harmonic number
  • osc.terminal.t<t>.w<w> — D (-) — t,w: wheel-number [0..91]
  • osc.taper.k<key>.b<bus>.t<wheel> — D (-) — customize tapering model. Specify level of [key, drawbar, tonewheel].
  • osc.crosstalk.k<key> — S (-) — value colon-separated: "<int:bus>:<int:wheel>:<double:level>"
  • osc.compartment-crosstalk — D (0.01) — Crosstalk between tonewheels in the same compartment. The value refers to the amount of rogue signal picked up.
  • osc.transformer-crosstalk — D (0) — Crosstalk between transformers on the top of the tg.
  • osc.terminalstrip-crosstalk — D (0.01) — Crosstalk between connection on the terminal strip.
  • osc.wiring-crosstalk — D (0.01) — Throttle on the crosstalk distribution model for wiring
  • osc.contribution-floor — D (0.0000158) — Signals weaker than this are not put on the contribution list
  • osc.contribution-min — D (0) — If non-zero, contributing signals have at least this level
  • osc.attack.click.level — D (0.5) — Amount of random attenuation applied to a closing bus-oscillator connection.
  • osc.attack.click.maxlength — D (0.6250) — The maximum length of a key-click noise burst, 100% corresponds to 128 audio-samples
  • osc.attack.click.minlength — D (0.1250) —

The minimum length of a key-click noise burst — 100% corresponds to 128 audio-samples. (That was the tail end of a param from before, but now let's keep it moving!) 💅

  • osc.release.click.level — D (0.25) — How much random attenuation gets applied to an opening bus-oscillator. 🎛️
  • osc.release.model — S ("linear") — The model used during key-release. One of "click", "cosine", "linear", "shelf". ✨
  • osc.attack.model — S ("click") — The model used during key-attack; one of "click", "cosine", "linear", "shelf". 💅

🎀 Parameters for 'Vibrato Effect' 🎀

  • scanner.hz — D (7.25) — Frequency of the vibrato scanner. 🌀
  • scanner.modulation.v1 — D (3.0) — Amount of modulation for the vibrato/chorus 1 setting. 🎚️
  • scanner.modulation.v2 — D (6.0) — Amount of modulation for the vibrato/chorus 2 setting. 🎚️
  • scanner.modulation.v3 — D (9.0) — Amount of modulation for the vibrato/chorus 3 setting. 🎚️

🔥 Parameters for 'Preamp/Overdrive Effect' 🔥

  • overdrive.inputgain — F* (0.3567) — How much the input signal is scaled as it enters the overdrive effect. The default is pretty hot, but you can try it however you like; range [0..1]. 🌶️
  • overdrive.outputgain — F* (0.07873) — How much the signal is scaled as it leaves the overdrive effect. You want this as high as possible without clipping — and you will notice when it clips. Test with a bass-chord on 88 8888 000 with percussion enabled and full swell, but turn down the amplifier/headphone volume first! Range [0..1]. 🔊
  • xov.ctl_biased — F* (0.5347) — Bias base; range [0..1]. ⚖️
  • xov.ctl_biased_gfb — F* (0.6214) — Global [negative] feedback control; range [0..1]. 🔄
  • overdrive.character — F* (-) — An abstraction to set xov.ctl_biased_fb and xov.ctl_biased_fb2. 🎭
  • xov.ctl_biased_fb — F* (0.5821) — This acts kinda like an analogue tone control for bass before the overdrive stage. Unity is around 0.6; lower values take away bass and lower the volume, while higher values give more bass and more signal into the overdrive. Must be less than 1.0. 🎸
  • xov.ctl_biased_fb2 — F* (0.999) — Same function as fb1 but controls the signal after the overdrive stage. Together they can reduce bass going into the overdrive and then recover it on the other side. Must be less than 1.0. 🎛️
  • xov.ctl_sagtobias — F* (0.1880) — Part of an attempt to recreate an artefact called 'power sag'. When a power amplifier is under heavy load, the voltage drops and alters the operating parameters, usually towards more and different kinds of distortion. The sagfb parameter controls the rate of recovery from the sag effect when the load is lifted. Must be less than 1.0. ⚡

🌀 Parameters for 'Leslie Cabinet Effect' 🌀

  • whirl.bypass — I (0) — If set to 1, completely bypass the leslie emulation. 🚫
  • whirl.speed-preset — I (0) — Initial horn and drum speed. 0: stopped, 1: slow, 2: fast. 🏎️
  • whirl.horn.slowrpm — D (40.32) — Target RPM for slow (aka choral) horn speed. 🐢
  • whirl.horn.fastrpm — D (423.36) — Target RPM for fast (aka tremolo) horn speed. 🐇
  • whirl.horn.acceleration — D* (0.161) — Time required to accelerate the horn (exponential time constant). ⏩
  • whirl.horn.deceleration — D* (0.321) — Time required to decelerate the horn (exponential time constant). ⏪
  • whirl.horn.brakepos — D* (0) — Horn stop position. Clockwise position where to stop. (0: free-stop, 1.0: front-center). 🛑
  • whirl.drum.slowrpm — D (36.0) — Target RPM for slow (aka choral) drum speed. 🐢
  • whirl.drum.fastrpm — D (357.3) — Target RPM for fast (aka tremolo) drum speed. 🐇
  • whirl.drum.acceleration — D* (4.127) — Time required to accelerate the drum (exponential time constant). ⏩
  • whirl.drum.deceleration — D* (1.371) — Time required to decelerate the drum (exponential time constant). ⏪
  • whirl.drum.brakepos — D* (0) — Drum stop position. Clockwise position where to stop. (0: free-stop, 1.0: front-center). 🛑
  • whirl.drum.width — D (0) — Drum stereo width (LV2 only) (-1: left mic, 0: stereo, 1: right mic). 🎚️
  • whirl.horn.width — D (0) — Horn stereo width (LV2 only) (-1: left mic, 0: stereo, 1: right mic). 🎚️
  • whirl.horn.radius — D (19.2) — Horn radius in centimeter. 📏
  • whirl.drum.radius — D (22.0) — Drum radius in centimeter. 📏
  • whirl.mic.distance — D (42.0) — Distance from mic to origin in centimeters. 📍
  • whirl.horn.mic.angle — D (180.0) — Horn Stereo Mic angle. 📐
  • whirl.horn.offset.z — D (0.0) — Offset of horn perpendicular to mic to front, in centimeters. ↕️
  • whirl.horn.offset.x — D (0.0) — Offset of horn towards left mic, in centimeters. ↔️
  • whirl.horn.level — D (0.7) — Horn wet-signal volume. 🔊
  • whirl.horn.leak — D (0.15) — Horn dry-signal signal leakage. 💧
  • whirl.drum.filter.type — I* (8) — This filter separates the signal to be sent to the drum-speaker. It should be a high-shelf filter with negative gain. Filter type: 0-8. See "Filter types" below. 🎛️
  • whirl.drum.filter.q — D* (1.6016) — Filter Quality, bandwidth. 🎚️
  • whirl.drum.filter.hz — D* (811.9695) — Filter frequency. 📶
  • whirl.drum.filter.gain — D* (-38.9291) — Filter gain. 🔊
  • whirl.horn.filter.a.type — I* (0) — This is the first of two filters to shape the signal to be sent to the horn-speaker; by default a low-pass filter with negative gain to cut off high frequencies. Filter type: 0-8. See "Filter types" below. 🎛️
  • whirl.horn.filter.a.hz — D* (4500) — Filter frequency. 📶
  • whirl.horn.filter.a.q — D* (2.7456) — Filter quality, bandwidth. 🎚️
  • whirl.horn.filter.a.gain — D* (-30.0) — Filter gain. 🔊
  • whirl.horn.filter.b.type — I* (7) — This is the second of two filters to shape the signal to be sent to the horn-speaker; by default a low-shelf filter with negative gain to remove frequencies which are sent to the drum. Filter type: 0-8. See "Filter types" below. 🎛️
  • whirl.horn.filter.b.hz — D* (300.0) — Filter frequency. 📶
  • whirl.horn.filter.b.q — D* (1.0) — Filter Quality, bandwidth. 🎚️
  • whirl.horn.filter.b.gain — D* (-30.0) — Filter gain. 🔊

🌈 Parameters for 'Reverb Effect' 🌈

  • reverb.wet — D (0.1) — Reverb Wet signal level; range [0..1]. 💧
  • reverb.dry — D (0.9) — Reverb Dry signal level; range [0..1]. 🌵
  • reverb.inputgain — D (0.1) — Reverb Input Gain. 🎤
  • reverb.outputgain — D (1.0) — Reverb Output Gain (modifies dry/wet). 🔊
  • reverb.mix — D* (0.1) — Reverb Mix (modifies dry/wet). 🎛️

🎛️ Filter Types (for Leslie) 🎛️

  • 0 — LPF low-pass
  • 1 — HPF high-pass
  • 2 — BF0 band-pass 0
  • 3 — BF1 band-pass 1
  • 4 — NOT notch
  • 5 — APF all-pass
  • 6 — PEQ peaking eq
  • 7 — LSH low shelf
  • 8 — HSH high shelf
Note that the gain parameter does not apply to type 0 Low-Pass-Filters.

🎹 Additional MIDI Control-Command Functions 🎹

These properties can not be modified directly, but are meant to be mapped to MIDI-controllers (see "General Information" above) e.g. midi.controller.upper.70=upper.drawbar16.

  • {upper|lower|pedal}.drawbar<NUM> — I* (-) — where <NUM> is one of [16, 513, 8, 4, 223, 2, 135 , 113, 1]. Set MIDI-Controller IDs to adjust given drawbar. -- The range is inversely mapped to the position of the drawbar, so that fader-like controllers work in reverse, like real drawbars. Note that the MIDI controller values are quantized into 0 ... 8 to correspond to the nine discrete positions of the original drawbar system: 0:8 (loudest), 1-15:7, 16-31:6, 32-47:5, 48-63:4, 64-79:3, 80-92:2, 96-110:1, 111-127:0(off). 🎚️
  • rotary.speed-preset — I* (-) — Set horn and drum speed; 0: stop, 1: slow, 2: fast. 🌀
  • rotary.speed-toggle — I* (-) — Toggle rotary.speed-preset between 1/2. 🔄
  • rotary.speed-select — I* (-) — Low-level access function 0..8 (3^2 combinations) [stop/slow/fast]^[horn|drum]. 🎛️
  • swellpedal1 — D* (0.7) — Set swell pedal gain. 🦶
  • swellpedal2 — D* (0.7) — Identical to swellpedal1. 🦶
  • vibrato.knob — I* (0) — <22: vibrato1, <44: chorus1, <66: vibrato2, <88: chorus2, <110 vibrato3, >=110: chorus3. 🎛️
  • vibrato.routing — I* (0) — <32: off, <64: lower, <96: upper, >=96: both. 🛣️
  • vibrato.upper — I* (0) — <64: off, >=64 on. 🔛
  • vibrato.lower — I* (0) — <64: off, >=64 on. 🔛
  • percussion.enable — I* (0) — <16: off, <63: normal, <112: soft, >=112: off. 🥁
  • percussion.decay — I* (0) — <64: fast-decay, >=64 slow decay. 🥁
  • percussion.harmonic — I* (0) — <64: third harmonic, >=64 second harmonic. 🎵
  • overdrive.enable — I* (0) — <64: disable overdrive, >=64 enable overdrive. 🎸

📚 EXAMPLES 📚

setBfree setBfree -p pgm/default.pgm midi.port="a2j:[AV]"
midi.driver=jack setBfree midi.port=129 midi.driver=alsa
jack.connect=jack_rack:in_ setBfree jack.out.left=system:playback_7
jack.out.right=system:playback_8 setBfree -U 868000000

🐞 REPORTING BUGS 🐞

Report bugs at <http://github.com/pantherb/setBfree/issues>.

Website and manual: <http://setbfree.org>

Copyright © 2008-2018 Robin Gareus <robin@gareus.org> Copyright © 2012 Will Panther <pantherb@setbfree.org> Copyright © 2010 Ken Restivo <ken@restivo.org> Copyright © 2003-2004 Fredrik Kilander <fk@dsv.su.se>

This is free software; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

That's the whole vibe, bestie! This is setBfree 0.8.13 from June 2024, and the manual page is SETBFREE(1). Stay slaying! 💖✨👑

📦 where this page comes from