Product SiteDocumentation Site

11.3. Basic Programming in SuperCollider

As with any programming language, you will start learning SuperCollider with the basic commands, that are of little use by themselves. However, since the language is so flexible, even the most basic commands can be combined in ways that create highly complex behaviours. The example program, "Method One," was written with the goal of illustrating how a single sound-generating object can be used to create an entire composition. This tutorial does not begin with audio-generating code, which helps to emphasize that SuperCollider is primarily a programming language.
This portion of the Guide is designed as a "reference textbook," which you can use both to learn the SuperCollider language in the first place, and to remind yourself about the language's features afterwards.
The section is most effective when read in small portions.

11.3.1. First Steps The Different Parts of SuperCollider

As you discovered when installing SuperCollider, there are actually many different components involved with SuperCollider. Here is a list of some of them, with brief descriptions of their purpose:
  • Programming language: this is an abstract set of rules and guidelines that allow you to write down instructions for producing sounds.
  • Interpreter: this is what is run in GEdit; it transforms the programming language instructions written by you into useful instructions for the server; also called the "client."
  • Server: this is what synthesizes the sound, according to instructions sent to it by the interpreter.
  • Library: these contain commands and the instructions to be executed when you call the commands; the interpreter looks up commands in the library when you call them.
This modular design allows for several advanced capabilities and features. Any particular element could theoretically be replaced without affecting other elements, as long as the methods of communication remain the same. As long as the programming language is the same, portions of the library can be modified, removed, or added at will; this happens often, and Planet CCRMA at Home provides a collection of library extensions. One of the most exciting capabilities is the ability to run the interpreter and server on different physical computers. The networking component is built into these components - they always communicate by UDP or TCP, even when run on the same computer! Although this ability is not used in this Guide, it is not difficult.
The most important thing to remember is that the SuperCollider interpreter is what deals with the programs you write. The SuperCollider server is controlled by the interpreter, but is an independent program. For simple things, like the Hello World Programs below, the server is not even used - after all, there is no audio for it to synthesize. "Hello, World!"

The first program that one traditionally makes when learning a new programming language is called "The Hello World Program." This is a simple and trivial application that simply prints outs the phrase, Hello, World! (or a variation of it). It might seem useless at first, but the ability to provide feedback to an application's user is very important, and this is essentially what the Hello World Program does.
Here is the program in SuperCollider:
"Hello, World!".postln;
Here is an extension to that program:
"Hello, World!".postln;
"Hello, SC!".postln;
As with all examples in this section, you should paste these programs into GEdit, and execute them with SuperCollider. Look at the output produced by the programs, but don't worry about it for now.
These programs are very small, but it highlights some key concepts of the SuperCollider language, described below. Return Values

Every SuperCollider program must provide the interpreter with a value (some information) when it has carried out all of its instructions. This value is called a "return value," because it is the value given by a program when it "returns" control to the interpreter. In a SuperCollider program, it is the last value stated in a program that automatically becomes the return value - no special command is required. When program execution ends, and control is returned to the SuperCollider interpreter, the interpreter outputs the return value in the "SuperCollider output" pane.
In the single-line Hello World Program above, the program produces the following output: Hello, World! Hello, World! The program appears to have been executed twice, but that is not the case. The first Hello, World! is printed by the program. The second Hello, World! appears because "Hello, World!.postln is the last (in this case, the only) value of the program. It is "returned" by the program, and the interpreter prints it.
In the two-line Hello World Program above, the program produces the following output: Hello, World! Hello, SC! Hello, SC! This makes it more clear that the program is not being executed twice, and that it is the last value of a program that is returned to the interpreter.
Try executing the following single-line programs. Look at the output produced by each, and determine whether it is printed by the program itself, the interpreter, or both.
  • "Hello, World!".postln;
  • "Hello, World!";
  • 5.postln;
  • 5;
Can you modify the two-line Hello World Program so that each line is printed only once?
In reality, every "function" must return a value. Functions are described in Section, “Functions”, but the difference is not yet important. Statements

A "statement" is a single instruction, which always ends with a semicolon. Exactly what constitutes a statement will become clear as you gain experience, and you will eventually automatically remember the semicolon.
In the Hello World Programs above, all of the statements contain the single instruction to post a line to the output screen. What happens when you remove the first semicolon, which marks the end of the first statement? The SuperCollider interpreter produces an unhelpful error message, and tells you that an error occurred after the forgotten semicolon. This is why it is important to always remember statement-concluding semicolons. Data Types: Numbers and Strings

In many programming languages, it is the programmer's responsibility to determine the type of data that is being used, and how it should be stored. The SuperCollider interpreter takes advantage of the power of modern computers, and deals with this on our behalf. This greatly simplifies basic tasks, because there are only two kinds of data to worry about, and they make perfect sense:
  • Numbers: These are numbers, written simply as numbers. Anything that can be done with real-world numbers can also be done with SuperCollider's numbers. They can be as large or small, positive or negative as you want. They can have any number of digits on either side of the decimal point.
  • Strings: These are a string of characters, written between two double-quote characters like "this." The double-quote characters are required so that SuperCollider knows where to begin and end the string of characters. A string of character can contain as many characters as you like, including one character and no characters. If you want to include a double-quote character in a string, you should put a blackslash before it. The following is interpreted by SuperCollider as a string with only a double-quote character: "\""
Here are some examples of numbers and strings:
  • 5
  • 18920982341
  • 0.00000000000001
  • "characters"
  • "@"
  • ""
  • "6"
Is the last example a number or a string? You and I recognize that it is a number inside a string, but SuperCollider treats it as a string. You can do string things with it, but you cannot do number things with it. You cannot add "6" to something, for example.
Try executing the following single-line programs. Think about why the SuperCollider interpreter produces the output that it does.
  • 6 + 3;
  • "6" + 3;
  • "six" + 3; Consecutive Execution

Complex SuperCollider programs contain many parts, which all do different things. Sometimes, executing all of these together doesn't make sense, and it can be difficult to know which portions of the program are supposed to be executed when. To help with this, the interpreter allows you to mark portions of your program between ( and ) so that you will know to execute them together.
Here is an example:
  "Hello, Fred!".postln;
  "Hello, Wilma!".postln;
  "Goodbye, Fred!".postln;
  "Goodbye, Wilma!".postln;
It doesn't make sense to say "hello" and "goodbye" at the same time, so separating these sections with parentheses will serve as a reminder. In case we try to execute all of the code at once, the SuperCollider interpreter will give us an error.