1SETBFREE(1)                      User Commands                     SETBFREE(1)
2
3
4

NAME

6       setBfree - DSP tonewheel organ
7

SYNOPSIS

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

DESCRIPTION

12       setBfree - DSP tonewheel organ
13
14       setBfree is a MIDI-controlled, software synthesizer designed to imitate
15       the sound and properties of the electromechanical organs and sound mod‐
16       ification  devices  that brought world-wide fame to the names and prod‐
17       ucts of Laurens Hammond and Don Leslie.
18

OPTIONS

20       -c <filename>, --config <filename>
21              Load alternate config file over default
22
23       -C, --noconfig
24              Do not  read  the  default  configuration  file  the  equivalent
25              built-in defaults are still set
26
27       -d, --dumpcc
28              Print a list of MIDI-CC mappings on startup
29
30       -D, --noCC
31              do not load default CC map on startup
32
33       -h     Print short help text
34
35       -H, --help
36              Print complete help text with parameter list
37
38       -l <pgm>
39              Load  a  MIDI  program-preset  at startup (may override previous
40              settings given with -r, -U,..)
41
42       -M <filename>, --midnam <filename>
43              export current controller mapping to .midnam file
44
45       -p <filename>, --program <filename>
46              Load alternate program file over default
47
48       -P, --noprogram
49              Do not read the default program file the built-in  programs  are
50              cleared as well
51
52       -r, --randomize
53              Randomize initial preset (whacky but true)
54
55       -U, --upper <drawbar settings>
56              Specify initial drawbar settings, for the upper manual as 9 dig‐
57              its. e.g. 808000000
58
59       -V, --version
60              Print version information
61
62   General Information:
63              The configuration consists of two parts: program (pgm) and  con‐
64              fig (cfg).
65
66              The  static configuration of the properties of the instrument is
67              defined in a .cfg file. There is  no  need  to  specify  a  con‐
68              fig-file,  as  all configurable parameters have built-in default
69              values. They can be overridden on startup using 'property=value'
70              pairs  or by loading a specific .cfg file.  As the name /static/
71              implies, the properties can only be set  on  application  start.
72              Yet  many  of  the properties merely define the initial value of
73              settings which can later be modified during playback.  The  ones
74              which  can  be  dynamically modified are marked with an asterisk
75              (*)
76
77              Properties are modified by sending MIDI Control-Commands (CC) to
78              the  synth.   The  mapping of CCs to function can be modified by
79              setting   the   "midi.controller.{upper|lower|pedal}.<CC>=<func‐
80              tion>"   property.    Function-names  are  equivalent  to  prop‐
81              erty-names.   e.g.   "midi.controller.upper.22=overdrive.output‐
82              gain" assigns the overdrive-gain to MIDI-CC 22 on MIDI-channel 1
83              (upper) (Note: each function can  assigned  only  once,  however
84              MIDI-CC can be re-used and trigger multiple function at the same
85              time.)
86
87              The program basically defines 'shortcuts'. Loading a program  is
88              usually  equivalent to sending a series of CC. Programs are com‐
89              monly used to define  instruments  (e.g.  draw-bar  settings  to
90              mimic  a  flute) or provide scalepoints (e.g. reverb=64).  There
91              are a few special commands which are only available by recalling
92              a program (randomize settings, split-manuals, enable overdrive).
93
94              Programs are defined in a .pgm file and are fixed after starting
95              the  application.  They  are  activated  by  sending   MIDI-pro‐
96              gram-change  messages  (also  known as 'presets') MIDI-banks are
97              ignored. So at most 127 programs can be specified.
98
99              At  startup  'default.cfg'  and   'default.pgm'   in   $XDG_CON‐
100              FIG_HOME/setBfree/  (default:  $HOME/.config/setBfree/)  are are
101              evaluated if the files exist, unless '--noconfig'  or  '--nopro‐
102              gram'  options  are given.  An additional config or program file
103              can be loaded using the '-c' and '-p' option respectively.
104
105              Example config: "/usr/share/setBfree/cfg/default.cfg"
106
107              Example program: "/usr/share/setBfree/pgm/default.pgm"
108
109   Instrument Properties:
110              Below is a list of  available  property-value  pairs  and  their
111              default  values.  The default value is omitted "(-)" for proper‐
112              ties which contain an array of values.
113
114              The type identifiers are: 'S': text-string, 'I':  integer,  'F':
115              float, 'D': double-precision float.
116
117              Properties marked with an asterisk (*), are available as MIDI CC
118              functions. When used as CC, the  values  0-127  (MIDI  data)  is
119              mapped  to  a  range  of values appropriate to the function.  In
120              config-files or on the command-line you must  you  the  type  as
121              specified e.g. "osc.temperament=gear60 osc.wiring-crosstalk=0.2"
122
123   Parameters for 'Main':
124       midi.driver
125              S  ("jack")
126
127              The midi driver to use, 'jack' or 'alsa'
128
129       midi.port
130              S  ("")
131
132              The  midi  port(s)  to  auto-connect to. With alsa it's a single
133              port-name or number, jack accepts regular expressions.
134
135       jack.connect
136              S  ("system:playback_")
137
138              Auto connect both audio-ports  to  a  given  regular-expression.
139              This  setting  is  ignored if either of jack.out.{left|right} is
140              specified.
141
142       jack.out.left
143              S  ("")
144
145              Connect left-output to this jack-port (exact name)
146
147       jack.out.right
148              S  ("")
149
150              Connect right-output to this jack-port (exact name)
151
152   Parameters for 'MIDI Parser':
153       midi.upper.channel
154              I  (1)
155
156              The MIDI channel to use for the upper-manual. range: [1..16]
157
158       midi.lower.channel
159              I  (2)
160
161              The MIDI channel to use for the lower manual. range: [1..16]
162
163       midi.pedals.channel
164              I  (3)
165
166              The MIDI channel to use for the pedals. range: [1..16]
167
168       midi.controller.reset
169              I  ("-")
170
171              Clear existing CC mapping for all controllers (if non-zero argu‐
172              ment is given). See also -D option.
173
174       midi.controller.upper.<cc>
175              S  ("-")
176
177              Speficy  a  function-name to bind to the given MIDI control-com‐
178              mand. <cc> is an integer 0..127. Defaults are  in  midiPrimeCon‐
179              trollerMapping()  and  can  be listed using the '-d' commandline
180              option. See general information.
181
182       midi.controller.lower.<cc>
183              S  ("-")
184
185              see midi.controller.upper
186
187       midi.controller.pedals.<cc>
188              S  ("-")
189
190              see midi.controller.upper
191
192       midi.transpose
193              I  (0)
194
195              Global transpose (noteshift) in semitones.
196
197       midi.upper.transpose
198              I  (0)
199
200              Shift/transpose MIDI-notes on upper-manual
201
202       midi.lower.transpose
203              I  (0)
204
205              Shift/transpose MIDI-notes on lower-manual
206
207       midi.pedals.transpose
208              I  (0)
209
210              Shift/transpose MIDI-notes on pedals
211
212       midi.upper.transpose.split
213              I  (0)
214
215              Noteshift for upper manual in split mode
216
217       midi.lower.transpose.split
218              I  (0)
219
220              Noteshift for lower manual in split mode
221
222       midi.pedals.transpose.split
223              I  (0)
224
225              Noteshift for lower manual in split mode
226
227   Parameters for 'MIDI Program Parser':
228       pgm.controller.offset
229              I  (1)
230
231              Compensate for MIDI controllers that number the programs from  1
232              to 128. Internally we use 0-127, as does MIDI. range: [0,1]
233
234   Parameters for 'Tone Generator':
235       osc.tuning
236              D  (440.0)
237
238              Base tuning of the organ.
239
240       osc.temperament
241              S  ("gear60")
242
243              Tuning  temperament,  gear-ratios/motor-speed.  One of: "equal",
244              "gear60", "gear50"
245
246       osc.x-precision
247              D  (0.001)
248
249              Wave precision. Maximum allowed error when calculating wave buf‐
250              fer-length  for  a given frequency (ideal #of samples - discrete
251              #of samples)
252
253       osc.perc.fast
254              D  (1.0)
255
256              Fast percussion decay time
257
258       osc.perc.slow
259              D  (4.0)
260
261              Slow percussion decay time
262
263       osc.perc.normal
264              D  (1.0)
265
266              Percussion starting gain of the envelope for normal volume.
267
268       osc.perc.soft
269              D  (0.5012)
270
271              Percussion starting gain of the envelope for soft volume.
272
273       osc.perc.gain
274              D  (11.0)
275
276              Basic volume of the percussion signal, applies  to  both  normal
277              and soft
278
279       osc.perc.bus.a
280              I  (3)
281
282              range [0..8]
283
284       osc.perc.bus.b
285              I  (4)
286
287              range [0..8]
288
289       osc.perc.bus.trig
290              I  (8)
291
292              range [-1..8]
293
294       osc.eq.macro
295              S  ("chspline")
296
297              one of "chspline", "peak24", "peak46"
298
299       osc.eq.p1y
300              D  (1.0)
301
302              EQ spline parameter
303
304       osc.eq.r1y
305              D  (0.0)
306
307              EQ spline parameter
308
309       osc.eq.p4y
310              D  (1.0)
311
312              EQ spline parameter
313
314       osc.eq.r4y
315              D  (0.0)
316
317              EQ spline parameter
318
319       osc.eqv.ceiling
320              D  (1.0)
321
322              Normalize EQ parameters.
323
324       osc.eqv.<oscnum>
325              D  (-)
326
327              oscnum=[0..127], value: [0..osc.eqv.ceiling]; default values are
328              calculated depending on selected osc.eq.macro  and  tone-genera‐
329              tor-model.
330
331       osc.harmonic.<h>
332              D  (-)
333
334              speficy level of given harmonic number.
335
336       osc.harmonic.w<w>.f<h>
337              D  (-)
338
339              w: number of wheel [0..91], h: harmonic number
340
341       osc.terminal.t<t>.w<w>
342              D  (-)
343
344              t,w: wheel-number [0..91]
345
346       osc.taper.k<key>.b<bus>.t<wheel>
347              D  (-)
348
349              customize  tapering  model.  Specify  level  of  [key,  drawbar,
350              tonewheel].
351
352       osc.crosstalk.k<key>
353              S  (-)
354
355              value colon-separated: "<int:bus>:<int:wheel>:<double:level>"
356
357       osc.compartment-crosstalk
358              D  (0.01)
359
360              Crosstalk between tonewheels in the same compartment. The  value
361              refers to the amount of rogue signal picked up.
362
363       osc.transformer-crosstalk
364              D  (0)
365
366              Crosstalk between transformers on the top of the tg.
367
368       osc.terminalstrip-crosstalk
369              D  (0.01)
370
371              Crosstalk between connection on the terminal strip.
372
373       osc.wiring-crosstalk
374              D  (0.01)
375
376              Throttle on the crosstalk distribution model for wiring
377
378       osc.contribution-floor
379              D  (0.0000158)
380
381              Signals weaker than this are not put on the contribution list
382
383       osc.contribution-min
384              D  (0)
385
386              If non-zero, contributing signals have at least this level
387
388       osc.attack.click.level
389              D  (0.5)
390
391              Amount of random attenuation applied to a closing bus-oscillator
392              connection.
393
394       osc.attack.click.maxlength
395              D  (0.6250)
396
397              The maximum length of a key-click noise burst, 100%  corresponds
398              to 128 audio-samples
399
400       osc.attack.click.minlength
401              D  (0.1250)
402
403              The  minimum length of a key-click noise burst, 100% corresponds
404              to 128 audio-samples
405
406       osc.release.click.level
407              D  (0.25)
408
409              Amount of random attenuation applied to an opening  bus-oscilla‐
410              tor
411
412       osc.release.model
413              S  ("linear")
414
415              Model  applied  during  key-release,  one  of "click", "cosine",
416              "linear", "shelf"
417
418       osc.attack.model
419              S  ("click")
420
421              Model applied during key-attack; one of "click", "cosine", "lin‐
422              ear", "shelf"
423
424   Parameters for 'Vibrato Effect':
425       scanner.hz
426              D  (7.25)
427
428              Frequency of the vibrato scanner
429
430       scanner.modulation.v1
431              D  (3.0)
432
433              Amount of modulation for vibrato/chorus 1 setting
434
435       scanner.modulation.v2
436              D  (6.0)
437
438              Amount of modulation for vibrato/chorus 2 setting
439
440       scanner.modulation.v3
441              D  (9.0)
442
443              Amount of modulation for vibrato/chorus 3 setting
444
445   Parameters for 'Preamp/Overdrive Effect':
446       overdrive.inputgain
447              F* (0.3567)
448
449              This  is  how  much  the input signal is scaled as it enters the
450              overdrive effect. The default value is quite hot, but you can of
451              course try it in anyway you like; range [0..1]
452
453       overdrive.outputgain
454              F* (0.07873)
455
456              This is how much the signal is scaled as it leaves the overdrive
457              effect. Essentially this value should be  as  high  as  possible
458              without clipping (and you *will* notice when it does - Test with
459              a bass-chord on 88 8888 000 with  percussion  enabled  and  full
460              swell,  but do turn down the amplifier/headphone volume first!);
461              range [0..1]
462
463       xov.ctl_biased
464              F* (0.5347)
465
466              bias base; range [0..1]
467
468       xov.ctl_biased_gfb
469              F* (0.6214)
470
471              Global [negative] feedback control; range [0..1]
472
473       overdrive.character
474              F* (-)
475
476              Abstraction to set xov.ctl_biased_fb and xov.ctl_biased_fb2
477
478       xov.ctl_biased_fb
479              F* (0.5821)
480
481              This parameter behaves somewhat like an  analogue  tone  control
482              for  bass mounted before the overdrive stage. Unity is somewhere
483              around the value 0.6, lesser values takes away bass  and  lowers
484              the  volume  while higher values gives more bass and more signal
485              into the overdrive. Must be less than 1.0.
486
487       xov.ctl_biased_fb2
488              F* (0.999)
489
490              The fb2 parameter has the same function as fb1 but controls  the
491              signal  after  the  overdrive stage. Together the two parameters
492              are useful in that they can reduce the amount of bass going into
493              the  overdrive  and  then  recover it on the other side. Must be
494              less than 1.0.
495
496       xov.ctl_sagtobias
497              F* (0.1880)
498
499              This parameter is part of an attempt  to  recreate  an  artefact
500              called  'power  sag'. When a power amplifier is under heavy load
501              the voltage drops and alters the  operating  parameters  of  the
502              unit,  usually  towards  more and other kinds of distortion. The
503              sagfb parameter controls the  rate  of  recovery  from  the  sag
504              effect when the load is lifted. Must be less than 1.0.
505
506   Parameters for 'Leslie Cabinet Effect':
507       whirl.bypass
508              I  (0)
509
510              If set to 1, completely bypass the leslie emulation
511
512       whirl.speed-preset
513              I  (0)
514
515              Initial horn and drum speed. 0:stopped, 1:slow, 2:fast
516
517       whirl.horn.slowrpm
518              D  (40.32)
519
520              Target RPM for slow (aka choral) horn speed
521
522       whirl.horn.fastrpm
523              D  (423.36)
524
525              Target RPM for fast (aka tremolo) horn speed
526
527       whirl.horn.acceleration
528              D* (0.161)
529
530              Time required to accelerate the horn (exponential time constant)
531
532       whirl.horn.deceleration
533              D* (0.321)
534
535              Time required to decelerate the horn (exponential time constant)
536
537       whirl.horn.brakepos
538              D* (0)
539
540              Horn  stop  position.  Clockwise  position  where  to  stop. (0:
541              free-stop, 1.0:front-center)
542
543       whirl.drum.slowrpm
544              D  (36.0)
545
546              Target RPM for slow (aka choral) drum speed.
547
548       whirl.drum.fastrpm
549              D  (357.3)
550
551              Target RPM for fast (aka tremolo) drum speed.
552
553       whirl.drum.acceleration
554              D* (4.127)
555
556              Time required to accelerate the drum (exponential time constant)
557
558       whirl.drum.deceleration
559              D* (1.371)
560
561              Time required to decelerate the drum (exponential time constant)
562
563       whirl.drum.brakepos
564              D* (0)
565
566              Drum stop  position.  Clockwise  position  where  to  stop.  (0:
567              free-stop, 1.0:front-center)
568
569       whirl.drum.width
570              D  (0)
571
572              Drum  stereo width (LV2 only) (-1: left mic, 0: stereo, 1: right
573              mic)
574
575       whirl.horn.width
576              D  (0)
577
578              Horn stereo width (LV2 only) (-1: left mic, 0: stereo, 1:  right
579              mic)
580
581       whirl.horn.radius
582              D  (19.2)
583
584              Horn radius in centimeter
585
586       whirl.drum.radius
587              D  (22.0)
588
589              Drum radius in centimeter
590
591       whirl.mic.distance
592              D  (42.0)
593
594              Distance from mic to origin in centimeters
595
596       whirl.horn.mic.angle
597              D  (180.0)
598
599              Horn Stereo Mic angle
600
601       whirl.horn.offset.z
602              D  (0.0)
603
604              Offset of horn perpendicular to mic to front, in centimeters
605
606       whirl.horn.offset.x
607              D  (0.0)
608
609              Offset of horn towards left mic, in centimeters
610
611       whirl.horn.level
612              D  (0.7)
613
614              Horn wet-signal volume
615
616       whirl.horn.leak
617              D  (0.15)
618
619              Horn dry-signal signal leakage
620
621       whirl.drum.filter.type
622              I* (8)
623
624              This filter separates the signal to be sent to the drum-speaker.
625              It should be a high-shelf  filter  with  negative  gain.  Filter
626              type: 0-8. see "Filter types" below.
627
628       whirl.drum.filter.q
629              D* (1.6016)
630
631              Filter Quality, bandwidth
632
633       whirl.drum.filter.hz
634              D* (811.9695)
635
636              Filter frequency.
637
638       whirl.drum.filter.gain
639              D* (-38.9291)
640
641              Filter gain
642
643       whirl.horn.filter.a.type
644              I* (0)
645
646              This  is the first of two filters to shape the signal to be sent
647              to the horn-speaker; by default a low-pass filter with  negative
648              gain  to cut off high frequencies. Filter type: 0-8. see "Filter
649              types" below.
650
651       whirl.horn.filter.a.hz
652              D* (4500)
653
654              Filter frequency
655
656       whirl.horn.filter.a.q
657              D* (2.7456)
658
659              Filter quality, bandwidth
660
661       whirl.horn.filter.a.gain
662              D* (-30.0)
663
664              Filter gain
665
666       whirl.horn.filter.b.type
667              I* (7)
668
669              This is the second of two filters to shape the signal to be sent
670              to the horn-speaker; by default a low-shelf filter with negative
671              gain to remove frequencies which are sent to  the  drum.  Filter
672              type: 0-8. see "Filter types" below.
673
674       whirl.horn.filter.b.hz
675              D* (300.0)
676
677              Filter frequency
678
679       whirl.horn.filter.b.q
680              D* (1.0)
681
682              Filter Quality, bandwidth
683
684       whirl.horn.filter.b.gain
685              D* (-30.0)
686
687              Filter gain
688
689   Parameters for 'Reverb Effect':
690       reverb.wet
691              D  (0.1)
692
693              Reverb Wet signal level; range [0..1]
694
695       reverb.dry
696              D  (0.9)
697
698              Reverb Dry signal level; range [0..1]
699
700       reverb.inputgain
701              D  (0.1)
702
703              Reverb Input Gain
704
705       reverb.outputgain
706              D  (1.0)
707
708              Reverb Output Gain (modifies dry/wet)
709
710       reverb.mix
711              D* (0.1)
712
713              Reverb Mix (modifies dry/wet).
714
715   Filter Types (for Leslie):
716       0      LPF low-pass
717
718       1      HPF high-pass
719
720       2      BF0 band-pass 0
721
722       3      BF1 band-pass 1
723
724       4      NOT notch
725
726       5      APF all-pass
727
728       6      PEQ peaking eq
729
730       7      LSH low shelf
731
732       8      HSH high shelf
733
734       Note that the gain parameter does not apply to type 0 Low-Pass-Filters.
735
736   Additional MIDI Control-Command Functions:
737              These  properties can not be modified directly, but are meant to
738              be mapped to MIDI-controllers (see "General Information"  above)
739              e.g. "midi.controller.upper.70=upper.drawbar16".
740
741       {upper|lower|pedal}.drawbar<NUM>
742              I* (-)
743
744              where  <NUM>  is  one  of [16, 513, 8, 4, 223, 2, 135 , 113, 1].
745              Set MIDI-Controller IDs to adjust given drawbar. -- The range is
746              inversely  mapped  to  the  position  of  the  drawbar,  so that
747              fader-like controllers work in reverse, like real drawbars. Note
748              that  the  MIDI  controller values are quantized into 0 ... 8 to
749              correspond to the nine discrete positions of the original  draw‐
750              bar  system:  0:8 (loudest), 1-15:7, 16-31:6,  32-47:5, 48-63:4,
751              64-79:3, 80-92:2, 96-110:1, 111-127:0(off)
752
753       rotary.speed-preset
754              I* (-)
755
756              set horn and drum speed; 0-stop, 1:slow, 2:fast
757
758       rotary.speed-toggle
759              I* (-)
760
761              toggle rotary.speed-preset between 1/2
762
763       rotary.speed-select
764              I* (-)
765
766              low-level    access    function    0..8    (3^2    combinations)
767              [stop/slow/fast]^[horn|drum]
768
769       swellpedal1
770              D* (0.7)
771
772              set swell pedal gain
773
774       swellpedal2
775              D* (0.7)
776
777              identical to swellpedal1
778
779       vibrato.knob
780              I* (0)
781
782              <22:vibrato1,     <44:chorus1,     <66:vibrato2,    <88:chorus2,
783              <110vibrato3, >=110:chorus3
784
785       vibrato.routing
786              I* (0)
787
788              <32:off, <64:lower, <96:upper, >=96:both
789
790       vibrato.upper
791              I* (0)
792
793              <64:off, >=64 on
794
795       vibrato.lower
796              I* (0)
797
798              <64:off, >=64 on
799
800       percussion.enable
801              I* (0)
802
803              <16:off, <63:normal, <112:soft, >=112:off
804
805       percussion.decay
806              I* (0)
807
808              <64: fast-decay, >=64 slow decay
809
810       percussion.harmonic
811              I* (0)
812
813              <64: third harmonic, >=64 second harmonic
814
815       overdrive.enable
816              I* (0)
817
818              <64: disable overdrive, >=64 enable overdrive
819

EXAMPLES

821       setBfree    setBfree    -p     pgm/default.pgm     midi.port="a2j:[AV]"
822       midi.driver=jack   setBfree  midi.port=129  midi.driver=alsa  jack.con‐
823       nect=jack_rack:in_       setBfree       jack.out.left=system:playback_7
824       jack.out.right=system:playback_8 setBfree -U 868000000
825

REPORTING BUGS

827       Report bugs at <http://github.com/pantherb/setBfree/issues>.
828       Website and manual: <http://setbfree.org>
829
831       Copyright © 2008-2018 Robin Gareus <robin@gareus.org>
832       Copyright © 2012 Will Panther <pantherb@setbfree.org>
833       Copyright © 2010 Ken Restivo <ken@restivo.org>
834       Copyright © 2003-2004 Fredrik Kilander <fk@dsv.su.se>
835
836       This is free software; see the source for copying conditions.  There is
837       NO warranty; not even for MERCHANTABILITY or FITNESS FOR  A  PARTICULAR
838       PURPOSE.
839
840
841
842setBfree 0.8.11                  December 2019                     SETBFREE(1)
Impressum