
Q-Synth
=======

Q-Synth is a package for driving software synthesizers via CNMAT's OSC ("Open
Sound Control") protocol, a standard interface for controlling synthesizers
and other multimedia programs in realtime, see the following URL for details:
http://www.cnmat.berkeley.edu/OpenSoundControl. The package also includes
special support for SuperCollider3 (http://www.audiosynth.com), arguably the
most advanced software synthesis program available right now.

To run this software you'll need the Q programming system, along with the
Q-Audio (>=2.3) and Q-Midi addon modules, available from
http://q-lang.sourceforge.net.

Please note that this package is still work in progress. The basic interfaces
to OSC and SuperCollider have been implemented and are fully functional. More
fancy GUI programs and interfaces to other sound synthesis software such as
Csound and Pd will likely be added in the future. As of this writing, the
software has only been tested on Linux and Windows. See below for some
installation instructions and a description of the scripts included in this
package.


INSTALL
=======

LINUX
-----

First make sure you have Jack (http://jackit.sf.net) and Stefan Kersten's
Linux port of SuperCollider (http://sourceforge.net/projects/supercollider)
installed. Jack is available as a precompiled package for the major Linux
distros, whereas SuperCollider for Linux is currently only available in
CVS. You can either use the RPMs provided on the Q homepage, or grab the
current CVS sources from http://supercollider.sourceforge.net and compile them
yourself (which is rather straightforward, once you have the necessary
libraries installed).

To install the Q-Synth module, you need to get either the source tarball or
one of the RPM packages provided on http://q-lang.sourceforge.net. The RPM
packages are ready to be installed with the RedHat package manager rpm. You
can also install from source, as follows:

	./configure --prefix=<prefix>
	make install

This will install the osc.q and sc.q scripts in the Q library directory
<prefix>/share/q/lib, the examples under <prefix>/share/q/examples/synth, and
the scgui application under <prefix>/share/q/apps/scgui. Make sure you get
the installation prefix right, it should match the install prefix of the Q
interpreter (/usr/local by default for installation from source; /usr if you
installed Q from an RPM package).

The latest and greatest version of Q-Synth can always be found in CVS (see the
q-synth module at http://sourceforge.net/cvs/?group_id=96881). When installing
from CVS sources, first run ./autogen.sh to create the configure script and
other configury stuff. Then proceed with a normal source install as described
above.


OS X
-- -

I didn't get around testing this package with SC3 on OS X yet, so currently
you're on your own. However, I see no reason why it shouldn't work, provided
that the sound server is properly configured and accepts OSC commands from an
UDP port. (Note that you'll have to put the SuperCollider directory on your
path if you want to run sclang and scsynth from the scripts provided with
Q-Synth.  Also, if your scsynth listens on a port different from the default
57110, you'll have to change sc.q accordingly.)


WINDOWS
-------

Q-Synth is included in the all-in-one Qpad.msi package for Windows, available
from the Q homepage. You also need to install SuperCollider, if you want to
use it.

A Windows port of SC3 (Psycollider) is available from the following URL:
http://swiki.hfbk-hamburg.de:8888/MusicTechnology/586. I tested an older
version of this package, and was able to get some sound from the server using
the scplay.q script and the sample synth definitions included in the Q-Synth
package. More recent version of Psycollider should work all right with
Q-Synth, but I haven't tested them yet.

Please note that, at present, the scgui.q script and the scope functions in
scplay.q won't work because they require some Unixish system functions which
are not available on Windows.


OSC.Q
=====

The osc.q script implements the OSC interface. It supports all standard OSC
features, including nested bundles and the standard data type tags (32 bit
floating point and integer values, strings and blobs). Operations are provided
to convert between binary OSC packets (represented as byte strings) and
corresponding Q data structures, as well as to implement a simple
communication layer via UDP. With the functions of this script you can control
OSC-aware synthesis programs such as Csound, Pure Data and SuperCollider (only
the latter has been tested at this time, so you might have to tweak osc.q for
other applications).


SC.Q
====

The package includes a second script, sc.q, to provide special support for
SuperCollider. SuperCollider3 (SC3 for short) is the latest incarnation of
James McCartney's well-known DSP and sound synthesis engine. It comes with its
own programming language, SCLang, through which you can program complex sound
analysis and synthesis functions, building on a large variety of built-in unit
generators. These "synthdefs" can then be loaded into the SC3 sound engine and
be controlled by external applications via OSC. The sc.q script implements an
interface to SC3 which lets you execute arbitrary SCLang code and control the
sound engine using OSC messages.

Note that before you can run the SuperCollider sound server on Linux, you must
start the Jack daemon. The easiest way to do this is by using the graphical
qjackctl program, available from http://qjackctl.sourceforge.net.

Here is how you can boot up a local SC3 sound server, compile and upload a
simple synth definition, run the synth, and stop it again. (You need to have a
synthdefs directory in the current directory to make this work.)

$ q sc

==> sc_start

==> sc "SynthDef(\"mysine\", { arg freq = 0, amp = 0; Out.ar(0, \
SinOsc.ar(freq, 0, [amp,amp])) }).writeDefFile"

==> sc_send (osc_message "/d_load" "synthdefs/mysine.scsyndef")

==> sc_send (osc_message "/s_new" ("mysine",4711,1,0,"freq",440,"amp",0.2))

==> sc_send (osc_message "/n_free" 4711)

==> sc_quit

Please refer to the SC3 documentation (to be found in the "build/Help" folder
of the SC3 sources) for a more complete explanation of what is going on
there. In particular, take a look at Server-Architecture.rtf which explains
the fundamental concepts behind SC3, and Server-Command-Reference.rtf which
describes the various OSC messages understood by the SC3 sound server.


SCPLAY
======

The scplay.q example demonstrates how to implement a monotimbral polyphonic
SC3 synth which can be played via your MIDI keyboard or another MidiShare
application like the graphical midi player contained in the Q-Midi package.
All control is done in Q, only the synths themselves are implemented in
SCLang. The script can be found in the examples subdirectory of the sources,
and will be installed into the <prefix>/share/q/examples/synth directory.

LINUX ONLY: To wire up the Q-Midi player with scplay.q, run the MidiShare
msconnect program and connect the "Playback" client with the "SuperCollider"
client, once the script has been started. If you already have Q-Midi 1.15 or
later, you can also use use the midicc application instead of msconnect;
midicc should establish the connection between Q-Midi Player and the
"SuperCollider" client automatically, once both clients have been started.

Detailed instructions can be found at the beginning of scplay.q. For instance,
here is how you run the included phase modulation synth:

$ q scplay

==> sc_start

==> play "phasemod"

To also show SuperCollider's audio output in a GGI window, replace the last
line with the following:

==> scope "phasemod"

The SCLang sources of the synth definitions can be found in synths.sc. Modify
these to your heart's content, add your own synths and effect units, etc. To
recompile all synths after you modified synths.sc, do the following:

==> compile


SCGUI
=====

(NOTE: On the Q website you can also find a much improved version of this
program with a nicer Qt GUI. Use that if you can. The older version of the
program included in this package is still provided for those who don't have Qt
on their system.)

The scgui.q script is an enhanced version of scplay.q with a Tk GUI. It
provides essentially the same functionality as scplay.q, but also lets you
control a variety of additional options like the desired synth and number of
voices, input channels, values of global control variables, etc., using
corresponding GUI elements, and it also allows you to compile synth
definitions and start the SuperCollider server with a single mouse click.
There's no real documentation for this program yet, but usage is fairly
straightforward and below we provide some information to get you started.

NOTE: To run this script, Tcl/Tk (>=8.3) and the BWidget extension are
required; you can get these from www.tcl.tk.

The script is installed as an executable in the <prefix>/share/q/apps/scgui
directory; a symbolic link in <prefix>/bin will be created as well. The script
can thus be run directly from the shell like so:

$ scgui

You can also specify the name of an SCLang file with synth definitions as
follows:

$ scgui examples/synths.sc

In this case the working directory will be changed to the path of the given
source file, if any. Both sclang and scsynth will then be started in that
directory.

To get up and running quickly, I recommend that you start out with the synth
definitions contained in the examples directory of the Q-Synth source
distribution (installed under <prefix>/share/q/examples/synth). Copy the
synths.sc file and the synthdefs directory with the .scsyndef files to some
location and start scgui from there:

$ scgui synths.sc

Everything should then be set up so that you can start playing the included
synths right away.

Note that the program assumes to find the binary synth definitions in the
synthdefs subdirectory of the current directory. If the synthdefs directory
does not yet exist, you will first have to compile the synths with the
`Compile' button. This will automatically create the synthdefs directory and
then feed the SCLang source file into sclang. Output from sclang goes to the
log window in the lower half of the scgui main window. The source file should
be written so that it takes care of writing the synth definitions using
SynthDef and writeDefFile, as shown in the provided synths.sc file. You can
edit the SCLang source file using the `Edit' button (the editor to be started
with this command can be configured at the beginning of scgui.q), and load a
new source file with the `Open' button.

Once the synth definitions have been compiled, you should be able to select
the synth you want to play in the combobox at the top of the scgui window. You
can also change the number of voices (i.e., the amount of polyphony) and the
MIDI channels from which to receive input with the corresponding controls on
the top of the scgui window.

To boot the SC3 sound server, push the `Boot' button located on the control
strip in the middle of the scgui window. If all goes well, some output from
scsynth will show in the log window, the button will now show `Quit' instead
of `Boot', and the status line at the bottom of the scgui window will show
`Server started'. You can now use the `Quit' button to shut down scsynth at
any time. If something goes wrong, you'll usually see some error message from
scsynth in the log window and the message `Error: scsynth process died
unexpectedly' in the status line. On Linux this usually means that Jack is not
running; make sure you started Jack and then try again. If the problem
persists then you should recheck your SC3 installation. You should be able to
run both sclang and scsynth from the command line; if these programs don't
work in the shell then they won't work in scgui either.

So far, so good. Now that the server is running, you should be able to hit the
`Play' button on the control strip. The status line will then display
`Playing'. Play some notes from your MIDI keyboard (or fire up the Q-Midi
player, make sure that it is connected to the "SuperCollider" client, and play
your favourite MIDI file). If everything is configured properly, you should
now hear some sound, and also see it in the wave display in the upper half of
the scgui window. The "LEDs" at the bottom of the wave display indicate the
voices which are currently playing. You can also record the sound by hitting
the `Record' button (watch the status line display `REC' in the rightmost
field when you do this), and stop the synth with the `Stop' button. Moreover,
the program responds to start and stop MIDI messages it receives.

In the control strip you also find some other controls for global gain,
panning etc. Play around with these to see what they do. The spinbox at the
right end of the control strip lets you control the rate at which the wave
display is updated; more precisely, it specifies the number of samples shown
in the display. Increasing the value "zooms out" horizontally and reduces the
framerate (i.e., the number of times per second the display is updated) and
thereby the CPU load. You can also change the recording level (and thereby the
vertical scale of the wave display) with the `Rec' control.

Note that scgui, like scplay, only supports monotimbral operation right now.
But you can run multiple instances of scgui at the same time (provided you
have enough CPU power). Each scgui instance runs its own instances of sclang
and scsynth, so multiple synths with different sounds can be played at the
same time. In this case it is often useful to assign the different instances
to different MIDI channels with the `Chan' combobox. Selecting the default
value of `All' in this field puts the synth in "omni" mode, in which it
accepts all MIDI channels except channel 10 (which is reserved for the drum
part in the General MIDI standard).

Also note that currently the signal path and certain postprocessing units,
such as the reverb and disk units are hardcoded into the program, so they
should always be present in the source file, or you should at least have the
corresponding binary .scsyndef files in the synthdefs subdirectory available.

Here's a brief run-down of the GUI elements in the scgui main window, listed
from top to bottom, left to right:

- Toolbar strip:

  - Open button: Opens a new SCLang source file with synth definitions.

  - Filename entry: Shows the selected filename. You can also type a new
    filename here.

  - Edit button: Opens the current SCLang file in the editor.

  - Compile button: Feeds the SCLang file to sclang to compile the included
    synth definitions.

  - Synth combobox: Lets you select the synth you want to play.

  - Voices spinbox: Controls the number of simultaneous voices, i.e., the
    desired amount of polyphony.

  - Channel combobox: Lets you select the MIDI channel(s) from which input
    is accepted.

- Wave display: Shows the current waveform, along with a strip of LEDs
  indicating which voices are currently playing. Also displays current scsynth
  average and peak CPU usage, and the time (mins:secs) since `Play' was hit.

- Control strip:

  - Boot button: Boot the sound server by starting scsynth.

  - Volume, Panning, Reverb and Recording level spinboxes: Control various
    synth parameters (global gain, pan, reverb and recording level).

  - Play button: Play the synth (also starts recording when `Record' was
    activated in advance).

  - Stop button: Stops the synth (and recording if activated).

  - Record button: Starts and stops recording mode. Recorded wave files will
    be written to scguiNNN.wav (with NNN a running counter) in the current
    working directory.

  - Rate spinbox: Lets you choose the number of samples shown in the wave
    display.

- Log window: Shows output from the sclang and scsynth processes.

- Status line: The status line consists of three fields with the following
  information.

  - Status messages: Some operations display results and error conditions here.

  - Scsynth status: Consists of four subfields indicating the number of loaded
    synthdefs, groups, synths and ugens while scsynth is running.

  - Record indicator: This field displays `REC' when recording mode is active.


TODO
====

- Provide access to the internal SC3 server (libscsynth). This will allow to
  bypass the socket interface and give access to the internal data structures
  of scsynth for maximum performance.

- Extend scgui to make it possible to configure new effects and postprocessing
  units along with their controls. Also add support for processing MIDI
  controller messages, pitch bends, etc., and add some keyboard shortcuts for
  the most important operations.

- Add interfaces to other OSC-aware programs, like Csound, Pd, ...


Enjoy!

October 2007
Albert Graef
ag@muwiinfa.geschichte.uni-mainz.de, Dr.Graef@t-online.de
http://www.musikwissenschaft.uni-mainz.de/~ag
