# Scheme SuperCollider, a Tutorial

## Prerequisites

Scheme SuperCollider ([rsc3][rsc3]) requires that
[SuperCollider][sc3], [Ikarus Scheme][ikarus], [R6RS][r6rs]
implementations of [SRFI][srfi]-[19][r6rs-srfi] and
[SRFI][srfi]-[27][r6rs-srfi] and [Emacs][emacs] are all installed and
working properly.

## Setting up Scheme SuperCollider

Scheme SuperCollider is currently only available as a set of
[darcs][darcs] repositories, the basic system is called `rsc3` and
requires the rhs and sosc libraries.  A simple build utility is also
required.

    $ darcs get http://slavepianos.org/rd/sw/mk-r6rs
    $ darcs get http://slavepianos.org/rd/sw/rhs
    $ darcs get http://slavepianos.org/rd/sw/sosc
    $ darcs get http://slavepianos.org/rd/sw/rsc3

To build ensure that the `mk-r6rs` library is on the scheme library
path and run the below in each project.

    $ (cd mk; make)

This installs the r6rs libraries to `~/lib/r6rs`.

## Setting up the Scheme SuperCollider Emacs mode

Add an appropriately modified variant of the following to `~/.emacs`

    (push "/home/rohan/sw/rsc3/emacs" load-path)
    (setq rsc3-help-directory "/home/rohan/sw/rsc3/help/")
    (setq rsc3-interpreter (list "ikarus" "/home/rohan/.rsc3"))
    (require 'rsc3)

The rsc3 emacs mode associates itself with files having the extensions
`.ss`, `.lss` and `.scm`.  When the `rsc3` emacs mode is active there
is a `Scheme SuperCollider` menu available.

## Documentation

The documentation for Scheme SuperCollider, including this tutorial,
is written in plain text, either ordinary scheme source files or in
/Bird notation/, a form of literate scheme where lines starting with
`>` are scheme code and everything else is commentary.

Unlike ordinary programs the Scheme SuperCollider help files cannot be
compiled to executables.  Each help file contains multiple independant
examples that can be evaluated using editor commands, either by
selecting from the `Scheme SuperCollider` menu or using the associated
keybinding.

## Interpreter Interaction

To start the scheme interpreter use `C-cC-s` (Scheme SuperCollider →
Scheme → Start scheme).

Starting the interpreter splits the current window into two windows.
If the scheme output window becomes obscured during a session you can
see it again by typing `C-cC-g` (Scheme SuperCollider → Scheme → See
scheme output).

To stop scheme type `C-cC-x` (Scheme SuperCollider → Scheme
→ Quit scheme).

## Starting the SuperCollider server

The SuperCollider server can be started from the command
line.  The help files assume that scsynth is listening for
UDP connections at the standard port on the local machine.

    $ scsynth -u 57110

## Basic SuperCollider Interaction

The SuperCollider server manages a graph of nodes with
integer identifiers.  The root node has ID zero.  By
convention ordinary graph nodes are placed in a group with
identifier 1, however this node is not created when scsynth
starts.

To create this node we need to send an OSC message to the
server, the expression to do this is written below.  To
evaluate an expression move the cursor to the closing
parenthesis and type `C-cC-e` (Scheme SuperCollider →
Expression → Evaluate).

> (with-sc3 (lambda (fd) (send fd (g-new1 1 add-to-tail 0))))

We can then audition a quiet sine oscillator at A440.

> (audition (out 0 (mul (sin-osc ar 440 0) 0.1)))

To stop the sound we can delete the group it is a part of,
the audition function places the synthesis node into the
group node with ID 1, the expression below deletes that
group.

> (with-sc3 (lambda (fd) (send fd (n-free1 1))))

In order to audition another graph we need to re-create a group with
ID 1.  Sound.SC3 includes a function `reset` that sequences these two
actions, first deleting the group node, then re-creating a new empty
group.

> (with-sc3 reset)

Using this command is so common there is a keybinding for it, `C-cC-k`
(Scheme SuperCollider → SCSynth → Reset scsynth).  After a reset we
can audition a new graph.

> (audition (out 0 (mul (sin-osc ar 220 0) 0.1)))

To see the server status type `C-cC-p` (Scheme SuperCollider → SCSynth
→ Display status), which sends:

> (with-sc3 display-server-status)

This prints a table indicating server activity to the scheme output
window.

    ***** SuperCollider Server Status *****
    # UGens                     0
    # Synths                    0
    # Groups                    2
    # Instruments               0
    % CPU (Average)             1.2261821031570435
    % CPU (Peak)                1.2635631561279297
    Sample Rate (Nominal)       44100.0
    Sample Rate (Actual)        44098.31557093504

## Multiple line expressions

Multiple line expressions are evaluated using the same mechanism as
single line expressions.

> (let* ((f1 (x-line kr 1 1000 9 remove-synth))
>        (f2 (mul-add (sin-osc ar f1 0) 200 800)))
>   (audition (out 0 (mul (sin-osc ar f2 0) 0.1))))

## Help Files

To find help on a UGen or on a SuperCollider server command place the
cursor over the identifier and type `C-cC-h` (Scheme SuperCollider →
Help → Scheme SuperCollider help).  This opens the help file, which
ought to have working examples in it, the above graph is in the
`SinOsc` help file, the `/s_new` help file explains what arguments are
required and what they mean.

The Scheme SuperCollider help files are derived from the help files
distributed with SuperCollider, the text is re-formatted to read well
as plain text and examples are translated into scheme.

## Monitoring incoming server messages

To monitor what OSC messages scsynth is receiving use the `dumpOSC`
server command to request that scsynth print text traces of incoming
messages to its standard output.

> (with-sc3 (lambda (fd) (send fd (dump-osc 1))))

To end printing send:

> (with-sc3 (lambda (fd) (send fd (dump-osc 0))))

[sc3]: http://www.audiosynth.com/
[ikarus]: http://www.cs.indiana.edu/~aghuloum/ikarus/
[srfi]: http://srfi.schemers.org/
[r6rs-srfi]: https://launchpad.net/scheme-libraries/
[emacs]: http://www.gnu.org/software/emacs/
[rsc3]: http://slavepianos.org/rd/?t=rsc3
[darcs]: http://darcs.net/
[r6rs]: http://www.r6rs.org/