1 WhySynth 2 ======== 3 A software synthesizer plugin for the 4 DSSI Soft Synth Interface 5 6Introduction 7============ 8WhySynth is a versatile softsynth which operates as a plugin for the 9DSSI Soft Synth Interface. A brief list of features: 10 11- 4 oscillators, 2 filters, 3 LFOs, and 5 envelope generators per 12 voice. 13 14- 11 oscillator modes: minBLEP, wavecycle, chorused wavecycle, 15 asynchronous granular, three FM modes, waveshaper, noise, 16 PADsynth, and phase distortion. 17 18- 10 filter modes. 19 20- flexible modulation and mixdown options, plus effects. 21 22DSSI is a plugin API for software instruments (soft synths) with 23user interfaces, permitting them to be hosted in-process by audio 24applications. More information on DSSI can be found at: 25 26 http://dssi.sourceforge.net/ 27 28WhySynth is something of a mongrel, combining bits from Xsynth-DSSI, 29hexter, Csound, Mats Olsson's MSS, and various other programs, with 30inspiration from a number of my favorite long-hair-days synths 31(Matrix 6, ESQ-1, K4), and wavecycle data resynthesized from Claude 32Kaber's Virtual K4 samples and //christian's exegesis of the Ensoniq 33SQ-80 wavetable ROMs. See the enclosed file AUTHORS for more 34details. 35 36WhySynth is written by Sean Bolton, and copyright (c) 2012 under the 37GNU General Public License, version 2 or later. See the enclosed 38file COPYING for details. While this software is 'free' within the 39requirements of this license, I (Sean) would appreciate any or all 40of the following should you find WhySynth useful: 41 42 - an email stating where you're from and how you're using 43 WhySynth, sent to <whysynth /at/ smbolton /dot/ com>, or better 44 yet, a postcard sent to: 45 Sean Bolton 46 14722 30th Ave NE 47 Shoreline Washington 98155 USA 48 49 - copies of or links to music you've created with WhySynth. 50 51 - any patches you create for WhySynth. Yes! Please! 52 53 - suggestions for improving WhySynth. 54 55The patches distributed with WhySynth, including the default 56'factory' patches and those found in the 'extra' directory, have 57been placed in the public domain by their respective authors. See 58the enclosed file extra/COPYING-patches for details. 59 60The GUI is stiflingly dull. Anyone want to help make it look cool? 61 62Requirements 63============ 64WhySynth requires the following: 65 66 - DSSI version 0.9 or greater, available from the 67 dssi.sourceforge.net address above. 68 69 - liblo version 0.12 or greater (0.23 or greater recommended), a 70 library implementing the Open Sound Control (OSC) protocol, 71 available at: 72 73 http://liblo.sourceforge.net/ 74 75 - pkgconfig with PKG_CONFIG_PATH set appropriately to pick up 76 DSSI and liblo. 77 78 - FFTW version 3, available at: 79 80 http://www.fftw.org/ 81 82 (WhySynth contains code to use FFTW version 2, but it is 83 untested and not supported.) 84 85 - GTK+ version 2.4 or later. (If a suitable GTK+ installation 86 is not found, the plugin will be built without the GUI.) 87 88 - the LADSPA v1.x SDK. 89 90 - the ALSA headers (DSSI plugins use ALSA structures, but not 91 the actual drivers, so you don't necessarily need the 92 drivers installed.) Users of non-Linux systems can use 93 libdssialsacompat, available at: 94 95 http://smbolton.com/linux.html 96 97 - a working DSSI host. WhySynth has been tested with 98 jack-dssi-host, available in the DSSI distribution, and with 99 ghostess, available at: 100 101 http://smbolton.com/linux.html 102 103 - automake 1.7 and autoconf 2.57 or better if you wish to 104 recreate the build files. 105 106Installation 107============ 108The generic installation instructions in the enclosed file INSTALL 109aren't particularly helpful, so try this instead: 110 1111. Unpack the tar file. 112 1132. Make sure PKG_CONFIG_PATH is set correctly to locate the 114 dssi.pc and liblo.pc pkgconfig files. On many systems, this 115 will be: 116 117 $ PKG_CONFIG_PATH=/usr/local/lib/pkgconfig 118 $ export PKG_CONFIG_PATH 119 1203. 'cd' into the package directory and execute './configure'. 121 configure will add '-Wall' and my favorite optimizations to 122 CFLAGS for you if you don't include any '-Wall' or '-O' options. 123 If you're using gcc and wish to provide your own optimization 124 flags, you MUST at least use '-finline' and a non-zero '-O' flag 125 to get decent results. 126 1274. Enable debugging information if you desire: edit the file 128 src/whysynth.h, and define Y_DEBUG as explained in the 129 comments. 130 1315. Do 'make'. Hopefully it should build without warnings (or 132 errors.) 133 1346. 'make install' will install the following: 135 136 <prefix>/lib/dssi/whysynth.so 137 <prefix>/lib/dssi/whysynth/WhySynth_gtk 138 <prefix>/share/whysynth/current_default_patches.WhySynth 139 <prefix>/share/whysynth/more_K4_interpretations.WhySynth 140 <prefix>/share/whysynth/version_20051005_patches.WhySynth 141 <prefix>/share/whysynth/version_20051231_patches.WhySynth 142 <prefix>/share/whysynth/version_20090608_patches.WhySynth 143 1447. You may wish to manually install the documentation as well: this 145 README file, plus the files in the doc/ directory. 146 147Feedback on your experiences building WhySynth is appreciated. 148 149Operation 150========= 151To run the WhySynth plugin under the jack-dssi-host provided in the 152DSSI distribution, I do the following: 153 1541. Start JACK. 155 1562. Start jack-dssi-host, supplying the correct plugin path 157 and filename (substitute <prefix> as appropriate): 158 159 $ DSSI_PATH=<prefix>/lib/dssi jack-dssi-host whysynth.so 160 161 jack-dssi-host should start, and moments later the WhySynth 162 graphic user interface should appear. 163 1643. Use aconnect, or qjackctl to connect jack-dssi-host to a MIDI 165 source, such as vkeybd. 166 1674. Begin playing sounds! If you get no response, try clicking the 168 'Send Test Note' button in the WhySynth GUI. This sends a note 169 directly via the host to the plugin, so if you hear sound now, 170 look for a problem between the example host and your MIDI 171 source. If you still don't hear sound, I'd look for a problem 172 between the example host and your output device. If you 173 continue having trouble, you might recompile with Y_DEBUG bit 2 174 set, which will cause the plugin to continuously output a quiet 175 buzz to help debug your outgoing signal path. 176 177WhySynth starts with a default set of sound presets, or 'patches', 178that you can select either by selecting the GUI 'Patches' tab and 179clicking on the patch name, or by sending a MIDI program change from 180your MIDI source with the appropriate program number. 181 182Main WhySynth Window 183==================== 184Test Note 185--------- 186The 'Test Note' controls allow you to send a test note to the 187plugin, by clicking on the 'Send Test Note' button. Changing the 188'key' and 'velocity' sliders will change the pitch and velocity of 189the test note. A key of 60 is generally considered to be 190'Middle C'. 191 192Patches Tab 193----------- 194Selecting the 'Patches' tab displays a list of all the patches loaded. 195Clicking on the name of a patch causes that patch to be selected. 196 197Configuration Tab 198----------------- 199Tuning: Sets the tuning of this instance of the plugin, as Hz for 200 A-above-middle-C. 201 202Polyphony: Sets the maximum polyphony for this instance of the 203 plugin. If you attempt to play more notes than this setting, 204 already-playing notes will be killed so that newer notes can be 205 played. If you are getting xruns, try reducing this setting. 206 207Monophonic Mode: 208 'Off' - polyphonic operation. 209 'On' - monophonic operation, where the envelopes are 210 retriggered upon each incoming note on event. 211 'Once' - monophonic operation, where the envelopes are triggered 212 only on the first note on of a legato phrase -- that 213 is, if you hold one note while playing a second, the 214 envelopes will not be retriggered for the second note. 215 'Both' - monophonic operation, where the envelopes are 216 retriggered at each note on, and upon note off when 217 other keys are still held. 218 219Glide Mode: 220 'Legato Only' - portamento (a 'slide' in pitch between two 221 notes) is only used when a new note is played while 222 another is held. 223 'Non-legato Only' - portamento is only used for single 224 (staccato) notes, or the first note of a legato phrase. 225 'Always' - portamento is always used. 226 'Leftover' - like 'Always', but ... more difficult to predict. 227 'Off' - disables portamento. 228 229Cancel Notes On Program Change: This controls whether WhySynth will 230 stop any playing notes before it performs a program change, 231 which can prevent nasty surprises if the previous and new 232 patches are not compatible. Defaults to 'On'. 233 234File Menu 235--------- 236You may load additional patches by selecting 'Load Patch Bank...' 237from the GUI 'File' menu, and pointing the file chooser dialog to a 238WhySynth patch bank file. Near the bottom of this dialog is a spin 239button which allows you to specify the program number at which to 240begin loading the new patches. This allows you to overwrite the 241existing patches, or to add the new patches at the end. WhySynth 242will let you keep loading patches until you run out of memory, but 243the most you can really use via MIDI would be 16384 patches (128 244programs times 128 banks). 245 246Selecting 'Save Patch Bank...' from the 'File' menu will allow you 247to save your patch bank to a file. A file chooser dialog will 248appear, which you may use to specify a file name, as well as the 249range of patches to be saved. 250 251The 'Import Xsynth-DSSI Patches' menu option allows you to import 252patches from WhySynth's predecessor, Xsynth-DSSI. This conversion 253is fairly accurate, but often needs a little hand tweaking, 254especially where multiple modulators are used on the same 255destination. Like 'Load Patch Bank...', this import will ask for a 256file name, then a program number at which to begin import patches. 257You also have the option of importing the patches in 'dual' mode: 258each set of oscillator parameters in the Xsynth-DSSI patch is 259applied to two WhySynth oscillators (VCO1 to Osc1 and Osc3, VCO2 to 260Osc2 and Osc4), and the Xsynth-DSSI filter settings are applied to 261both WhySynth filters, with the busing and mixdown set to make 262creation of stereo patches easy. Note that the import routine won't 263do the stereo-ification for you -- you'll need to detune the 264oscillators, or apply different modulation settings, in order to get 265a stereo image. 266 267The '(Mis)Interpret K4 Patches...' menu option will do a similar 268import of Kawai K4 patches (from 15123-byte 'All Patch Data Dump' 269system exclusive format). Unfortunately, I don't own a K4, so I 270have no way of making this function anything more than a wild guess. 271Still, the results are sometimes interesting and useable. Patches 272which use PCM (non-single-cycle) samples or more than 4 unique sets 273of envelope parameters will be skipped. A 'dual' option is also 274available for doubling up 'single' mode patches ('twin' and 'double' 275modes need all four oscillators.) The default patch bank contains a 276number of these interpreted K4 patches, and another 454 are 277available in the included file extra/more_K4_interpretations.WhySynth. 278 279Note that selecting 'Quit' from the 'File' menu just quits the 280WhySynth GUI -- the host and plugin should continue to run. 281 282Edit Menu 283--------- 284Selecting a patch in the 'Patches' tab, then selecting 'Edit Patch...' 285from the 'Edit' menu, opens the Patch Edit window.... 286 287Patch Edit Window 288================= 289This windows allows you to edit patches. 290 291The 'Patch Name' text box allows you to change the name of a patch. 292You may optionally add a comment to a patch in the 'Comment' box. 293 294The controls in the Osc1, Osc2, Osc3, Osc4, Filters, Mix, Effect, 295LFOs, and Miscellaneous tabs offer real-time control of the 296synthesis parameters used by the plugin to create sound. Only some 297of the parameters on the EGO, EG1, EG2, EG3, and EG4 tabs are 298real-time; some take effect at the beginning of the next envelope 299segment, and some require a voice to be retriggered to take effect. 300The voice architecture is described in more detail below. 301 302The controls come in three varieties: rotary knobs, menu buttons, 303and spin buttons. The rotary knobs may be manipulated in several 304ways: 305 - Clicking and dragging a knob with mouse button 1 sets the 306 value directly, by making the knob pointer point toward the 307 mouse pointer. 308 - Clicking and dragging a knob with mouse button 3 allows 309 incremental adjustment of the knob's current value (without 310 a sudden jump.) Horizontal movement produces large variation 311 in the knob value, while vertical movement allows finer 312 control. 313 - Clicking on a knob with buttons 1 and 3 increment and 314 decrement the knob value. 315 316Many of the the bipolar patch parameters (whose values span zero, 317such as the 'Detune' and 'Amp Mod Amount' controls) have a small 318square button directly below the knob. Clicking this button will 319set the parameter directly to zero. 320 321The menu buttons may also be manipulated in several ways: 322 - Clicking the button with mouse button 1 will cause a menu of 323 choices to pop up. Clicking on one of the menu options will 324 select that value, however, it can be rather difficult to 325 audition the large number of choices using the mouse this 326 way. You may prefer to use the keyboard: 327 - The button may be selected for keyboard input by clicking it 328 with mouse button 2 or 3, or by repeatedly pressing the 329 tab key until the button is highlighted. 330 - Once the button is selected for input, you may use the up 331 arrow, down arrow, page-up and page-down keys to easily 332 browse through the available options. 333 334The 'Test Note' controls are similar to those of the main window, 335with the additional of a small square check button. If you click on 336this button, then the 'Send Test Note' button becomes a sticky 337'Toggle Test Note' button -- very handy for holding a note on while 338twiddling knobs. 339 340Once you have edited a patch to your satisfaction, you may save it 341back to the patch bank by clicking the 'Save Changes' button. You 342will be asked to which program number you would like to save your 343new patch. If you do not wish to overwrite an existing patch, 344selected the highest available patch number, next to which '(empty)' 345will be displayed, to save your changes to a new slot. Be sure to 346then use 'Save Patch Bank...' from the 'File' menu to save your 347changes to a file. 348 349The oscillator, filter, effect and envelope generator tabs contain 350'Copy' and 'Paste' buttons. These buttons allow the settings for 351their respective voice element to be copied to a 'clipboard', then 352pasted into another element of the same type, possibly even in 353another patch. 354 355Voice Architecture 356================== 357In overview, each WhySynth voice consists of four oscillators, whose 358output may be routed to two intermediate buses. Two filters then 359take their input from one or the other of these buses, or the second 360filter can take its input from the first. The two buses and the 361filter outputs are then mixed down to stereo. See the enclosed 362image doc/voice_block_diagram.png for a visual representation. 363 364The stereo outputs for all active voices are summed, then passed 365through a DC blocker (hard-synced minBLEP oscillators and waveshaper 366oscillators can produce a lot of DC.) The result can then be 367optionally processed by an effects section, which at the moment 368consists of either a plate reverb simulation or a dual delay. 369 370MIDI information, three low-frequency oscillators (LFOs), and five 371envelope generators are available for modulating oscillator and 372filter parameters, and many of the modulators can themselves be 373modulated by other modulators. 374 375Oscillators 376----------- 377Each of the four oscillators may be operated in one of ten modes, 378or turned off. All of the modes have eight common controls: 379 380- 'Pitch' and 'Detune' control the fundamental pitch of the 381 oscillator, relative to the MIDI key. The former is in 382 semitones, the latter in cents. 383 384- 'Bus A Send Level' and 'Bus B Send Level' control the amount of 385 the oscillator's output sent to each bus. 386 387- 'Pitch Mod[ulator] Source', 'Pitch Mod Amount', 'Amp[litude] Mod 388 Source', and 'Amp Mod Amount' allow selection of a modulation 389 source and amount for the oscillator pitch and output level. 390 391All of the modes also have a 'Waveform' control, whose meaning 392depends upon the mode, plus zero to four additional mode-dependent 393controls. For many of the modes, the 'Waveform' control selects one 394of some 168 different single-cycle 'wavecycle' waveforms. See the 395enclosed file doc/wavetable_guide for more information on these 396waveforms. 397 398The ten oscillator modes and their controls are: 399 4001. Asynchronous Granular - In this mode, the oscillator output is 401 generated from many small bursts, or 'grains' of sound. The 402 'Waveform' control selects the wavecycle waveform used as the 403 grain source. The additional controls in this mode are: 404 405 - 'Grain Lz' controls the average number of grains being summed 406 to create the sound at any one moment. The higher this 407 setting, the more complex the resulting sound, but also the 408 more CPU resources used! 409 410 - 'Grain Spread' controls the amount of random deviation in the 411 start times of each grain. 412 413 - 'Grain Envelope' controls the length and shape of each grain. 414 'Gaussian' is the typical bell curve, 'Rectangular' is just 415 that, and (Curtis) 'Roadsian' smoothly splices gaussian ends 416 on a rectangular middle. 417 418 - 'Grain Freq Dist[ribution]' controls the random deviation in 419 the frequency of each grain. 420 4212. 'FM Wave->Sine' Phase Modulation - The classic 'FM' synthesis 422 technique invented by John Chowning and popularized by the 423 Yamaha DX-7, with a twist. Here, one of the wavecycle waveforms 424 is used to modulate a sine wave. Additional controls are: 425 426 - 'Mod Freq Ratio' sets the ratio of the modulator and carrier 427 frequencies from 0.5 to 1 when fully counter-clockwise, in 428 integer steps up to 16 to 1 when fully clockwise. 429 430 - 'Mod Freq Detune' offers (very) fine tuning of the frequency 431 ratio. 432 433 - 'Mod Index Source' and 'Mod Index Amount' control the depth 434 of the phase modulation. 435 4363. 'FM Sine->Wave' Phase Modulation - As above, but here a sine wave 437 is used to modulate one of the wavecycle waveforms. 438 4394. 'FM Wave->LF Sine' Phase Modulation - One of the wavecycle 440 waveforms is used to modulate a very-low-frequency sine wave, 441 yielding an effect somewhat like a rotating speaker cabinet. 442 The additional controls for this mode are: 443 444 - 'Low Frequency' sets the frequency of the carrier sine wave, 445 from 1/8Hz to 2Hz. 446 447 - 'Mod Index Bias' sets a constant depth of modulation, to which 448 is added the variable modulation depth determined by the 449 'Mod Index Source' and 'Mod Index Amount' controls. 450 4515. minBLEP - This mode uses the minBLEP technique for generating 452 classic-analog waveforms with very little aliasing. The 453 available waveforms are: 454 455 0. Sawtooth+ 456 1. Sawtooth- 457 2. Rectangular 458 3. Triangular 459 4. Clipped Saw 460 5. Sample/Hold Noise (think '80s video game) 461 462 minBLEP oscillators may be 'hard synced' to the previous 463 (lower-numbered) oscillator by setting the 'Sync' control fully 464 to 1. See the discussion of synchronization below for more 465 information. 466 467 The Rectangular and S/H Noise waveforms also feature pulsewidth 468 and pulsewidth modulation settings, the Triangular waveform has 469 slope and slope modulation controls, and the Clipped Saw 470 waveform has tooth width and tooth width modulation controls. 471 Beware of overmodulating a Triangular wave's slope; it can 472 produce a loud 'pop' which I haven't yet found a fast way of 473 avoiding. 474 4756. Noise - This mode comes in four flavors: 476 477 0. White noise 478 1. Pink noise 479 2. Low-pass filtered white noise 480 3. Band-pass filtered white noise 481 482 For the last two, additional controls are provided for the 483 filter cutoff/center frequency, and resonance. 484 4857. PADsynth - An implementation of Nasca O. Paul's 'PADsynth' 486 bandwidth-enhanced additive synthesis algorithm. This mode 487 takes the spectral profile of the source wavecycle waveform, 488 spreads each partial over a range of frequencies, then 489 resynthesizes the waveform to create very harmonically rich 490 sound. 491 492 Two important differences between this mode and the previous 493 modes are that the resynthesis is not done in 'real time', and 494 the resulting sound samples use a significant amount of memory. 495 When you select a PADsynth patch, or make changes to one, it can 496 take up to several seconds before the resynthesized sound is 497 available (until which time WhySynth will substitute a simple 498 sine wave.) Depending on the number of multisamples the 499 wavecycle has, the resulting sound can take up to 3.5 megabytes 500 of memory _per oscillator_. PADsynth multisamples rendered with 501 the same parameters are shared between oscillators and WhySynth 502 instances, but if the parameters are different, it's easy to 503 have WhySynth eat up quite a bit of memory. 504 505 The controls for this mode are: 506 507 - 'Partial Width' sets the degree to which the energy of each 508 partial in the source wavecycle is spread over a range of 509 frequencies in the resulting sound. Higher widths result in 510 a thicker or more chorused sound. 511 512 - 'Partial Stretch' controls the amount by which the frequency 513 center of each source partial is adjusted up or down. Pianos 514 and other sound sources with stiff vibrating elements have a 515 slight positive stretch to their sound. Very high or very 516 low stretch values will result in metallic, clangorous, or 517 ring-modulated sounds. _Until you get a feel for what the 518 PADsynth controls do, always start with this control near 519 zero (straight up)_. 520 521 - 'Width Scale / Mode' combines the partial width scaling 522 parameter with the stereo/mono mode parameter. Even 523 numbered settings are stereo, which means that the sounds 524 written to Bus A and Bus B form a stereo image if 525 appropriately panned. The partial width scaling controls 526 the degree to which the partial width is increased for 527 higher partials. Many natural sound sources scale at around 528 100% -- that is, partial eight will have eight times the 529 spread of the fundamental. Lower scaling settings produce 530 more synthetic timbres, while at higher settings the upper 531 harmonics merge, creating 'noisy' or 'breathy' sounds. 532 533 - 'Damping' controls the reduction in strength of higher source 534 partials (sort of like a low pass filter). Low settings 535 result in a brighter sound. 536 5378. Phase Distortion - This mode implements phase distortion 538 synthesis similar to the Casio CZ-series synthesizers. Various 539 functions are used to speed or slow the phase progression of a 540 sine oscillator, adding harmonics to the signal and producing a 541 sound which is distinctly digital, yet often similar to classic 542 analog sounds. 543 544 The 'Waveform' control selects the resulting waveform when bias 545 or modulation is applied -- with zero bias and modulation, a 546 sine wave is always produced. The waveform may be either a 547 single shape, such as 'Sawtooth' or 'Pulse', or dual shapes 548 which alternate in successive cycles, such as 'Saw & Pulse'. 549 The alternation of the two shapes causes the oscillator to 550 sound an octave below normal. 551 552 The additional controls in this mode are: 553 554 - 'Mod Balance' is only available when using dual waveforms, 555 when it controls the relative amount of distortion applied 556 during each waveform's respective cycle. For example, if 557 the waveform selected is 'Saw & Pulse', and this control is 558 one fourth of the way from '1st' to '2nd', then during the 559 first, sawtooth cycle the oscillator will be twice as 560 responsive to bias and modulation as during the second, 561 pulse cycle. 562 563 - 'Bias' sets the minimum level of phase distortion. 564 565 - 'Mod Amt Source' and 'Mod Amt Amount' allow selection of a 566 modulation source and amount to control, together with the 567 'Bias' amount, the total depth of phase distortion. 568 5699. Wavecycle - In this mode, the oscillator produces one of the 168 570 or so different single-cycle waveforms. See the enclosed file 571 doc/wavetable_guide for more information on the waveforms. 572 573 Wavecycle oscillators may also be 'hard synced' to the previous 574 oscillator, but the minBLEP anti-aliasing used only compensates 575 for amplitude changes, not slope changes, at the phase reset, 576 and so they will alias more at higher frequencies than a minBLEP 577 oscillator would. The exception to this is waveform 0 'Sine 1', 578 which does have slope delta compensation. 579 580 Many of the waveforms are multi-sampled (for band limiting 581 and/or formant preservation), and there is a 'Wave Sel[ect] 582 Bias' control which may be used to bias the wavetable selection 583 toward the higher key ranges, for lower harmonic content. 584 58510. Wavecycle Chorus - This mode is similar to the previous 586 'Wavecycle' mode, except that five copies of the waveform are 587 generated simultaneously. The additional controls for this mode 588 are: 589 590 - 'Tuning Spread' sets the degree to which the pitch of each 591 copy differs from the others. 592 593 - 'Chorus Depth' determines the extent to which the additional 594 copies are mixed into the oscillator's output. At fully 595 counter-clockwise, only a single copy is mixed in, while 596 when fully clockwise, all five copies are included. 597 59811. Waveshaper - Classic waveshaping, with the wavecycle waveforms 599 used as the transfer functions. As of this writing (2005/12/31), 600 only one of the waveforms was created specifically for the 601 waveshaper, a (rather boring) Chebychev T5 function, yet many of 602 the other waveforms can yield interesting results. The 603 additional controls in this mode are: 604 605 - 'Phase Bias' adds a constant phase bias into the transfer 606 function, allowing you to shift the 'zero phase' point of 607 the wavecycle. 608 609 - 'Mod Amt Bias' sets the minimum level of the sine wave input 610 into the transfer function. 611 612 - 'Mod Amt Source' and 'Mod Amt Amount' allow selection of a 613 modulation source and amount for the transfer function input 614 level. 615 616Oscillator Synchronization 617-------------------------- 618Oscillators in minBLEP and wavecycle modes have the ability to 'hard 619sync' to another oscillator, so that the slave oscillator's phase 620resets whenever the master oscillator completes a cycle. Here are 621the rules for using sync: 622 6231. The oscillators are run in numeric order, from Osc1 through Osc4, 624 and a lower-numbered master oscillator must provide sync for a 625 higher-numbered slave. 626 6272. FM, minBLEP, phase distortion, wavecycle, wavecycle chorus, and 628 waveshaper oscillators can be masters. 629 6303. Only minBLEP and wavecycle oscillators can be slaves. 631 6324. Async granular, noise, and PADsynth oscillators neither generate 633 nor use sync, and may appear between master and slave. 634 6355. Multiple slaves may sync to one master. 636 6376. Any master overwrites the previous master's sync. 638 639Filters 640------- 641The two filters each may be operated in one of seven modes, or 642turned off. Filter 1 can take its input from Bus A or Bus B, and 643Filter 2 can take its input from either bus, or from the output of 644Filter 1. All filter modes have cutoff/center frequency, frequency 645modulation, and resonance/bandwidth controls. The filter modes are: 646 6471. The 2-pole (12dB/octave) low-pass filter from Xsynth. 648 6492. The 4-pole (24dB/octave) low-pass filter from Xsynth. 650 6513. Fons Adriaensen's MVC LPF-3, modeled after the voltage-controlled 652 lowpass filter invented by R. A. Moog. This mode has an 653 additional 'Drive' control which adjusts the level of the signal 654 within the filter, thereby changing the intensity of its 655 non-linear effects. 656 6574. The 4-pole low-pass filter from amSynth. 658 6595. A 4-pole low-pass filter with clipping. This is two, 2-pole 660 filter stages with a hard clipper before each stage. A 'Drive' 661 control adjusts the relative clipping threshold. 662 6636. A 4-pole band-pass filter. 664 6657. The 2-pole, constant-gain, 'resonz' band-pass filter from Csound. 666 In this mode, the 'Bandwidth' control operates backwards, so 667 that it has the same intuitive 'feel' as the 'Resonance' control 668 in other modes: turn it counter-clockwise for wider bandwidths, 669 clockwise for narrower. 670 6718. A 2-pole high-pass filter. 672 6739. A 4-pole high-pass filter. 674 67510. A 4-pole band-reject filter. 676 677Mix 678--- 679The mix controls allow setting the output level and left/right pan 680of each of Bus A, Bus B, Filter 1 output, and Filter 2 output. A 681Master Volume control controls the level of the resulting left and 682right outputs. 683 684Note that final output level is also 'hard-wired' to the EGO 685envelope generator. 686 687Effects 688------- 689Three effects are available: Tim Goetze's Versatile Plate reverb 690simulation, Sean Costello's Csound reverb, and a Dual Delay. All 691effects share a 'Mix' control, which sets the blend of wet (effect) 692and dry (uneffected) signals. 693 694The 'Plate Reverb' has these controls: 695 696- 'Bandwidth' controls the amount of high frequency passed from the 697 input into the reverb simulation. 698 699- 'Tail' controls the length of the reverb tail. 700 701- 'Damping' controls the attenuation of high frequencies 702 within the reverb 'tank'. 703 704The 'Dual Delay' has these controls: 705 706- 'Feedback' controls how much of the delayed signals is fed back 707 into the delay lines. 708 709- 'Feed Across' controls how much of the left signal (including 710 feedback) is fed into the right delay line, and vice versa for 711 right signal into left delay line. With zero Feed Across, the 712 left and right channel delays are completely independent. With 713 full Feed Across, sounds will 'ping-pong' between the two 714 channels. 715 716- 'Left Delay' and 'Right Delay' set the left and right delay times, 717 respectively. 718 719- 'Damping' controls the attenuation of high frequencies going in to 720 the delay lines. 721 722The 'SC Reverb' has these controls: 723 724- Greater 'Feedback' creates a longer reverb 'tail'. 725 726- A higher 'Low Pass Freq' causes less damping of high frequencies. 727 728- 'Pitch Mod' controls the amount of random pitch shift in the delay 729 lines. 730 731Modulation 732========== 733There are 23 different modulation sources available for every voice 734modulation option mentioned above, plus each of the LFOs and 735envelope generators can themselves be modulated. Briefly, the 736modulation sources are: 737 738 0. Constant On 739 1. Mod Wheel 740 2. Pressure 741 3. Key 742 4. Velocity 743 5. GLFO Bipolar 744 6. GLFO Unipolar 745 7. VLFO Bipolar 746 8. VLFO Unipolar 747 9. MLFO 0 Bipolar 748 10. MLFO 0 Unipolar 749 11. MLFO 1 Bipolar 750 12. MLFO 1 Unipolar 751 13. MLFO 2 Bipolar 752 14. MLFO 2 Unipolar 753 15. MLFO 3 Bipolar 754 16. MLFO 3 Unipolar 755 17. EGO 756 18. EG1 757 19. EG2 758 20. EG3 759 21. EG4 760 22. ModMix 761 762The 'Constant On' modulation source always has a value of '1', or 763fully on. 764 765MIDI Modulators 766--------------- 7671. Mod Wheel - This mod source takes the value of MIDI modulation 768 wheel (control change #1). 769 7702. Pressure - This mod source combines, for each voice, the MIDI 771 channel pressure and key (polyphonic) pressure for the note. 772 7733-4. Key and Velocity - These mods are set to the note's key and 774 velocity. 775 776LFOs 777---- 778There are three low-frequency oscillators available for use as 779modulators: an instrument-wide 'global' LFO (GLFO), a per-voice LFO 780(VLFO), and another per-voice multi-phase LFO (MLFO), which is 781actually four LFOs in one. 782 783Each LFO has two outputs, a bipolar (-1 to 1) output, and a unipolar 784(0 to 1) output. As a rule of thumb, the bipolar outputs tend to be 785best when modulating oscillator pitch or filter cutoff frequency, 786and the unipolar outputs tend to be best when modulating amplitude. 787 788Each LFO has a frequency control and a waveform selection control. 789The LFOs use the same waveforms as the wavecycle oscillators, but 790the wavetables also contain some non-bandlimited, Gibbs-effect-free 791waveforms specifically intended for use with the LFOs. These appear 792in the 'LFO' section of the wavetable pop-up menus. 793 794Each LFO also has amplitude modulation source and amount controls. 795Since the GLFO is one LFO shared by all voices within an WhySynth 796instance, it does not have any of the per-voice modulation sources 797available to it. 798 799The VLFO and MLFO both have 'Delay' controls which set the time from 800key-on that it takes the LFO to fade up to full strength. 801 802The MLFO is actually four LFOs with a common set of controls. The 803'Phase Spread' control sets the initial phase difference, in 804degrees, between successive MLFO LFOs, so that if this control is 805set at 90, then MLFO 0 will start with a phase of 0 degrees, MLFO 1 806with a phase of 90 degrees, MLFO 2 with 180, and MLFO 3 with 270. If 807the 'Random Freq' control is zero, the MLFO LFOs will maintain this 808phase difference over time. Otherwise, 'Random Freq' controls the 809random deviation in the individual LFOs frequencies, and their phase 810differences will drift over time. 811 812Envelope Generators 813------------------- 814There are five envelope generators per voice, each of which may be 815run in one of five modes, and EGs EG1 through EG4 may also be turned 816off. 817 818The Output Envelope Generator EGO is special, in that the final 819output amplitude of the voice is 'hard-wired' to be controlled by 820the EGO level, and the voice is terminated when EGO reaches the end 821of its final segment. 822 823The five EG modes all have four segments, with four 'time' controls 824setting the length of each segment, and three 'level' controls 825setting the level of the envelope between each segement. There are 826also four 'shape' controls, which determine how the envelope level 827changes within each segment. 'Lead' shapes at first approach the 828segment's ending value more quickly than 'Linear' and then slow 829their approach, 'Lag' shapes have slow initial approaches then 830quickly arrive at the ending value. 'Hold' and 'Jump' are special 831shapes which hold the segment's initial value for the duration of 832the segment, and jump immediately to the segment's ending value, 833respectively. See the enclosed images doc/eg_shapes_*.png for 834visual representations of the shapes. 835 836The five EG modes are named: 837 838 1. ADSR 839 2. AAASR 840 3. AASRR 841 4. ASRRR 842 5. One-Shot 843 844Modes 2, 3 and 4, run through their first three, two, and one 845segments, respectively, before pausing until the key is released. 846The knob labels in the GUI change with the mode to reflect this, so 847that the level control at which this pause takes place is always 848labeled 'Sustain Level'. Once the key is released, the EG then 849continues running through the remaining segments. 850 851Mode 5, 'One-Shot', does not pause for a sustain, but continues 852through all four segments regardless of the key on status. Mode 1, 853'ADSR', is just an AAASR envelope with some of the controls 854greyed-out to provide the traditional and sometimes convenient 855'ADSR' envelope. 856 857Each envelope has five additional controls: 858 859- 'Vel->Level' controls the sensitivity of the envelope levels to 860 the key velocity. At a setting of 0, the envelope always goes to 861 full output. At maximum MIDI velocity (127), the envelope 862 always goes to full output. Otherwise, the lower the velocity 863 and higher the sensitivity, the greater the reduction of the 864 envelope's output. 865 866- The 'Vel->Time', and 'Kbd->Time' control how the note velocity and 867 key influence the envelope times. When these controls are set to 868 positive amounts, the envelope times get shorter with higher 869 velocities and keys; similarly, with negative settings, the 870 times get longer with higher velocities and keys. 871 872- 'Amp Mod Source' and 'Amp Mod Amount' allow the envelope output to 873 be modulated by another modulator. 874 875ModMix 876------ 877On the 'Miscellaneous' tab, there are five controls for the 'ModMix' 878modulation source. This source actually takes two other modulation 879sources, mixes their values together in adjustable amounts, and adds 880an adjustable bias -- useful for when you need to modulate one 881parameter with two different modulators. 882 883Other Miscellaneous Controls 884---------------------------- 885Also on the 'Miscellaneous' tab are 'Glide Rate' and 'Bend Range' 886controls. The pitch from the MIDI key may be lagged by the 'Glide 887Rate' value, as determined by the glide mode and other keys in play 888(see above). 'Bend Range' sets the response to MIDI pitch bend, in 889semitones. 890 891MIDI Controller Mapping 892======================= 893For DSSI hosts that support MIDI controller mapping, WhySynth 894requests that they map one MIDI controller: 895 896- MIDI Control Change 5 "Portamento time" is mapped to the 897 PORTAMENTO 'glide' control, although in a somewhat backward way: 898 higher CC values map to shorter glide times, and lower CC values 899 to longer glide times. 900 901Other mappings can be configured by modifying the source code; see 902the function y_get_midi_controller() in the file src/dssp_synth.c 903for details. 904 905WhySynth itself interprets several other MIDI control messages: 906 907- MIDI Control Change 7 "Volume" controls the output level, without 908 affecting the Master Volume control. 909 910- MIDI Control Change 1 "Modulation wheel" is available as the "Mod 911 Wheel" modulation source. 912 913- MIDI channel pressure and key pressure are combined (per note) and 914 available as the "Pressure" modulation source. 915 916Questions That Might Be Frequently Asked 917======================================== 918Q. The plugin seems to work fine, but the GUI never appears. Why? 919 920A. Make sure the hostname of your machine is resolvable (if not, the 921OSC messages can't be sent between host and GUI). If your machine's 922hostname is 'foo.bar.net', make sure you either have an entry for 923'foo.bar.net' in /etc/hosts, or your DNS server can resolve it. Test 924this with e.g. 'ping foo.bar.net'. To test that the GUI itself 925works, you can start it by itself (without a DSSI host) by giving it 926the '-test' option, for example: 927 928 $ <prefix>/lib/dssi/whysynth/WhySynth_gtk -test 929 930Q. Help! I twist a knob, and get booted out of JACK! 931 932A. Particularly with the granular oscillators, it's really easy to 933eat up lots of CPU with WhySynth. Some suggestions for making the 934most of your setup: 935 - Use a recent version of JACK with a high '--timeout' value. 936 - Set the 'Polyphony' configuration setting to the minimum your 937 work needs. 938 - Use the most efficient oscillator or filter mode that will get 939 the sound you want: granular oscillators take the most CPU 940 (proportional to the 'Grain Lz' setting), followed by 941 PADsynth, waveshaper, FM, and wavecycle, with minBLEP 942 oscillators taking the least. Fons' MVC LPF-3 filter takes 943 more CPU than the other filters. 944 - Turn off any unused oscillators or EGs. 945 - Keep your EGO release times to a minimum, so active voices are 946 turned off promptly. 947 948Q. Woah! Where'd that nasty sound come from? 949 950A. If the sound you're getting sucks more than you think it should, 951check for the following: 952 - Volume too high: especially when using asynchronous granular 953 oscillators, or high filter resonance, your signal may be so 954 hot it's clipping. Try reducing the oscillator bus send 955 levels, the mix levels, and the master volume. 956 - YDB_AUDIO set: if you've got a ~600Hz buzz in the 957 output even when you're not playing anything, your plugin 958 was probably compiled with the XDB_AUDIO debug bit set. Fix 959 that and recompile. 960 - Pitch too high: even with the minBLEP oscillators, it is 961 possible to get audible aliasing on very high notes. This 962 is especially true when using oscillator sync while the 963 slave is producing a sine wave, since the band-limiting 964 technique doesn't deal as well with waveforms having 965 continuously varying slope. 966 - PADsynth 'Partial Stretch' too high or too low: if the stretch 967 control is not close to zero (midway), very clangorous or 968 metallic sounds result. 969 970Q. Help! My async granular patch sounds horribly out of tune, but 971only sometimes. What's wrong? 972 973A. Make sure your glide setting is completely off (for now, that's 974fully clockwise to '1'). Even a very little glide with long grain 975envelopes will cause the problem. 976 977Q. I upgraded from the 20100922 release to the 20120729 release, and 978the default patches changed, breaking my super-cool setup. What 979gives? 980 981A. Just load the extra/version_20100922_patches.WhySynth file. 982 983Q. How can I map other MIDI control change (CC) or NRPN messages to 984WhySynth ports? 985 986A. DSSI doesn't (yet) support run-time configuration of these 987controller mappings, but you can set up your own mappings by editing 988the function y_get_midi_controller() in the file src/dssp_synth.c, 989then recompiling. See the comments there for more information. 990 991Q. Uggh. The new cairo knobs look really nice, but they're too slow 992on my remote X display. What do I do? 993 994A. Change the line 'static int prefer_cairo = TRUE;' to FALSE in 995gtkknob.c and recompile. 996