
QFSYNTH
=======

Copyright (c) 2005-2007 by Albert Graef, Johannes Gutenberg University Mainz,
Germany. Distributed under the GNU General Public License (GPL) Version 2 or
later (see the accompanying COPYING file for details).

QFSynth is a Qt-based graphical application for running Faust-based
polyphonic/monotimbral realtime software synths. It also includes a slightly
modified/extended version of the synth.q script included in the Q-Faust
distribution.

See the INSTALL file for installation instructions. After installation you
should be able to run the program by just typing "qfsynth". Note that QFSynth
expects to find the presets and synths in the directory in which it is run.
The program will issue a warning message at startup if this is not the
case. Some examples to start with are included in the distribution, see the
INSTALL file for instructions on how to work with these. To get started
quickly, you can just run qfsynth in the source directory which after "make &&
make -C examples" includes all the files that qfsynth needs.

NOTE: This release requires Q 7.8 or later.


USAGE
=====

Please first take a look at the Q-Faust documentation to get an idea what this
is all about. QFSynth basically allows you to put together a synth/effect
chain composed of Faust DSPs which takes MIDI and audio input and produces
audio output in realtime.

The main window of QFSynth is divided into an upper pane containing the
wave/FFT display (showing the current audio output when the synth is running)
and a lower pane with the synth, effect and devices configuration.

To get started quickly with one of the preconfigured synths, you can select a
preset from the combobox at the top of the window. Then press the "Start"
button. If everything is configured correctly, the synth should now start
playing in response to any MIDI input it gets. (If you get an error message
instead, try fiddling with the audio device configuration.)

You should also see the generated audio in the wave/FFT display. Use the
controls beneath the display to configure it to your liking (FFT: whether to
show the FFT instead of the time signal; Range: the range of frequencies shown
in the FFT display; X Scale: the number of audio buffers shown in the display,
use larger values to "zoom out"; Y Scale: scaling factor of the vertical axis
of the display, use larger values to "zoom in"; Ch: the audio channel to be
shown of a multi-channel signal).

Press the "Stop" button to stop the MIDI processing/audio generation loop. You
can also record the audio output in a WAV file with the "Record" button; the
file will be created in the current directory.

Note that the synth will connect itself to the MidiShare/ALSA bridge
automatically if it is running; you can also use QMidiCC (available from the Q
website) or msconnect (included in the MidiShare distribution) to connect the
QFSynth client to other MidiShare applications such as QMidiPlayer (also
available from the Q website).

To build your own synth, simply select the synth DSP on the "Synth" tab of the
lower pane. Then switch to the "Effects" tab and add any effect DSPs you want
to have, by selecting effects in the left-hand "Available FX" listbox and
pressing the right arrow ("Add effect") button to move them to the right-hand
"FX Chain" listbox. Existing effects can be removed by selecting them in the
"FX Chain" listbox and pressing the left arrow ("Remove effect"). On the
"Devices" tab you can specify the MIDI port/channel the synth should listen
to, and the audio input/output devices.

Note that the synth DSP must have certain freq, gain and gate control
variables, otherwise it will not show in the synth listbox at all, and the
number of corresponding outputs and inputs of consecutive DSPs in the chain
must match. (See the included .dsp files for some examples, and the
src/synth.q script for a more detailed explanation of the inner workings of
the synth/effect chain.) If any of the above conditions is violated, you will
get an error message when trying to start the synth. In that case check
whether the numbers of input and output channels match up (they're shown in
the listboxes, too), and also check whether your audio device is capable of
handling the number of output channels of the last DSP in the synth/effect
chain.

After selecting a synth in the "Synth" listbox, or an effect in the "FX Chain"
listbox, the control variables of the corresponding DSPs are shown in the
"Controls" widget at the bottom of the window. Here you can change the control
values by dragging around the sliders or changing the values in the spin
boxes. You can also assign an (absolute, or Reaktor-style incremental) MIDI
controller to each control by right-clicking on the control label and choosing
the appropriate option from the context menu. Note that to actually enable
MIDI controller input you'll also have to check the corresponding option on
the "Devices" tab.

When done with designing your synth configuration, you can save it with the
"Save" button next to the "Preset" combobox (type the desired name of the
preset in the combobox first). This will also save the current controller
assignments and control values, which will be restored next time the preset
gets loaded. There's a number of other buttons up there which let you delete
the current preset, create a new one, reset the control values to their
"factory settings", and reload synths, effects and presets.

For more information on how to create your own synth and effect DSPs please
take a look at the provided examples and refer to the Faust documentation. In
the synths directory you can also find a Makefile which allows you to compile
your Faust DSP modules.


Enjoy!
June 2006
Albert Graef <Dr.Graef@t-online.de>
