User:Crantila/FSC/Synthesizers/SuperCollider/Main

What SuperCollider Is
SuperCollider is many things, but above all:
 * An audio synthesis engine,
 * A flexible programming language, and
 * An interpreter to transform the programming language into synthesis instructions.

Technical Conventions for This Chapter
Because this chapter of the Musicians' Guide is more like a textbook or technical manual than a regular user manual, I have adopted several conventions commonly used in those contexts:
 * Plural forms of technical words are written with an apostrophe (for example: Synth's instead of Synths), which helps you to know that the technical word is being used.
 * Plural and singular forms of technical words - in particular of language classes - are always capitalized (for example: Synth instead of synth), which helps you to differentiate between the use of the word in SuperCollider and in the real world.
 * Other stuff?

Software and Hardware Requirements

 * JACK (see these instructions)
 * Planet CCRMA at Home (see these instructions)
 * JACK-capable audio interface

!!!! BUG: supercollider-gedit requires the packages 'gnome-python2-gconf' but didn't pull it in for me !!!!

Knowledge Requirements
SuperCollider is by far the most difficult program described in the Fedora Musicians' Guide. The SuperCollider applications themselves are easy to use, and they work very well, but they are merely tools to help you accomplish something useful. SuperCollider has an extremely powerful and flexible programming language, with libraries designed primarily for audio processing. As often happens with computers, however, this added flexibility and power comes at the cost of requiring greater understanding and learning on the part of the user.

Because SuperCollider involves actual programming, a rudimentary understanding of some principles and concepts of computer science will provide huge benefits to somebody learning the language. The following articles from a free encyclopaedia should not be considered mandatory reading, but you should refer to them as necessary while learning the language.
 * Computer Programming: You probably know what this is; it's what you'll be doing.
 * Programming Language: SuperCollider is a programming language.
 * Interpreter: This reads your code, and sends commands to the server, which cause it to produce sound.
 * Server: SuperCollider has a 'server' component, which is operated by the interpreter.
 * Functional Programming: SuperCollider can be treated as a "functional" language.
 * Imperative Programming: SuperCollider can be treated as an "imperative" language.
 * Object-oriented Programming: SuperCollider can be treated as an "object-oriented" language.

Available SuperCollider Packages
The SuperCollider packages are all held in the Planet CCRMA at Home repository, and there are a lot of them. Many of them have standard Fedora suffixes, but many are other kinds of optional components. Most of the optional features add libraries to SuperCollider, allowing you to use them in your audio programs. The specific features available in each additional package are not described here.
 * supercollider-ambiem : Optional Library ("Ambisonics classes for SC").
 * supercollider-debuginfo : Decodes the debugging information provided by SuperCollider.
 * supercollider-devel : Contains files needed for development with SuperCollider.
 * supercollider-dewdrop : Optional Library ("DewDrop external collection for SC").
 * supercollider-emacs : Adds SuperCollider support to the "emacs" text editor.
 * supercollider-extras : Optional Library ("Extra plugins and classes for SC").
 * supercollider-gedit : Adds SuperCollider support to the "gedit" text editor.
 * supercollider-libscsynth : "SuperCollider synthesis library."
 * supercollider-quarks : Optional Library ("Local quarks repository for SuperCollider").
 * supercollider-sclang : Help files, examples, the class library, and language interpreter.
 * supercollider-vim : Adds SuperCollider support to the "vim" text editor.
 * supercollider : Installs the "minimum requirements" to run SuperCollider.
 * supercollider-sclang
 * supercollider-libscsynth
 * fftw
 * w3m-el
 * emacs
 * supercollider-bbcut2 : Optional Library ("Beat tracking of audio streams").
 * supercollider-bbcut2-debuginfo : Decodes the debugging information provided by bbcut2.
 * supercollider-mathlib : Optional Library ("Useful classes for SC").
 * supercollider-redclasses : Optional Library ("Frederik Olofsson Red SC classes").
 * supercollider-redclasses-debuginfo : Decodes the debugging information provided by redclasses.
 * supercollider-world : Installs most SuperCollider packages.
 * supercollider
 * abmiem
 * -redclasses
 * -dewdrop
 * -emacs
 * -mathlib
 * -midifile
 * -extras
 * -bbcut2
 * -reduniverse
 * supercollider-midifile : Optional Library ("MIDI file reader for SuperCollider").
 * supercollider-reduniverse : Optional Library ("Sonification and visualization of dynamic systems").

Recommended Installation
If you have never used SuperCollider before, then I recommend installing the smallest number of packages possible. This will allow you to start learning with the core classes, available on all SuperCollider installations. Installing the bare minimum requirements will not prevent you from installing optional libraries in the future, of course.

The recommended installation also avoids installing the "emacs" or "vim" components, which - unless you are already a programmer - you probably don't know how to use. The "emacs" and "vim" text editors are extremely powerful and extensible, but they can be difficult to learn. Furthermore, there's no reason to learn them just for SuperCollider, because the component for GEdit is more than sufficient.

To install the minimum recommended installation for SuperCollider:  In a terminal, run su -c 'yum install supercollider supercollider-gedit'  Review the proposed installation carefully. The list may be quite long, and require a large download. 

Using GEdit to Write and Run Music Porgrams
The 'supercollider-gedit' package installs an extension for GEdit which allows editing and running SuperCollider code from within GEdit. There are also SuperCollider extensions for the "emacs" and "vim" text editors. This tutorial uses the GEdit extension, because it is easier to learn how to use GEdit than "vim" or "emacs."

Enable and Configure SCEd in GEdit
These steps should be followed the first time that you use GEdit's SuperCollider extension.
 * 1) Start "GEdit"
 * 2) Open the Preferences window (from the menu, select 'Edit > Preferences')
 * 3) Choose the 'Plugins' tab, and scroll down to "Sced," then make sure that it is selected.
 * 4) Click on the "Configure Plugin" button, then select a runtime folder where the SuperCollider server will store any synth sent to it during program execution.  The safest place for this folder could be a sub-folder of the location where you will store your SuperCollider code.

Enable SuperCollider Mode and Start a Server
These steps should be followed every time you open GEdit, and wish to use the SuperCollider extension. RESULT = 0 Welcome to SuperCollider, for help type ctrl-c ctrl-h (Emacs) or :SChelp (vim) or ctrl-U (sced/gedit) If this window gives a non-zero value for "RESULT," then an error has probably occurred, and you should scroll up to see what it is, and try to fix it. If you receive the following warning: "The GUI scheme 'swing' is not installed" then you will not be able to run any SuperCollider prorams that use a GUI (graphical user interface). The GUI components are not used anywhere in this Guide, and they are highly optional. SuperCollider 3 server ready.. JackDriver: max output latency 46.4 ms notification is on
 * 1) From the menu, select 'Tools > SuperCollider Mode'
 * 2) A 'SuperCollider' menu should appear, and a window at the bottom which says, "SuperCollider output".
 * 3) If you cannot see the window at the bottom, then select 'View > Bottom Pane' from the menu, so that it shows up.  It is sometimes important to see the information that SuperCollider provides in this window.
 * 4) After enabling SuperCollider mode, the window should display a series of notices.  Near the end should be something like this:
 * 1) You will probably also want to start a server at this point, so from the menu select 'SuperCollider > Start Server'.
 * 2) After the server starts, you should see messages from "JackDriver".  If a JACK server is not already started, then SuperCollider will start one automatically.
 * 3) If the SuperCollider server started successfully, you should see a message similar to this:

Executing Code in GEdit
You can execute code directly from GEdit, without having to use "sclang" from the command-line.
 * 1) Ensure that SuperCollider mode is enabled, and that a server has been started.
 * 2) Select the code that you wish to execute.  A single line of code may be executed simply by placing the text-input cursor on that line.
 * 3) Press 'Ctrl+E' on the keyboard, or from the menu select 'SuperCollider > Evaluate'
 * 4) To stop all sound on the server, press 'Esc' on the keyboard, or from the menu select 'SuperCollider > Stop Sound'
 * 5) If the server successfully executes the code, then it will output something to the "SuperCollider output" pane.  The output will be different, depending on what SuperCollider asked the server to do, but will usually either look like this: , or this:.

Other Tips for Using GEdit with SuperCollider

 * If you close GEdit while the SuperCollider server is running, then GEdit will automatically shut down the server.
 * If JACK is started by SuperCollider, then it will automatically terminate when the SuperCollider server terminates.
 * SuperCollider will automatically attempt to connect its outputs to the system's outputs. If your audio output doesn't work, then you should use "QjackCtl" to verify that it is correctly connected.
 * Other Functions available in the SuperCollider menu include:
 * Find Help (Opens the SuperCollider help file for currently-selected object).
 * Find Definition (Opens the SuperCollider source file for the currently-selected object).
 * Browse class (doesn't work for me?!?!?!?!)
 * Inspect Object (doesn't work for me?!?!?!?!)
 * Restart Interpreter (Restarts the SuperCollider interpreter; also closes running servers, but does not restart them).
 * Clear output (Clears all output from the "SuperCollider output" pane).

Basic Audio Programming with SuperCollider
This will be adapted from Scott Wilson and James Harkins' tutorial that is distributed with SuperCollider. It is distributed under the CC-BY-SA licence.