Preamble

These notes began as an unabashed reworking of Richard Boulanger's An Instrument Design TOOTorial. The initial purpose was to reconfigure the examples to conform to the the Unified File Format (UFF), which enables the original orchestra (.orc), and score (.sco) files, and csound command-line flags, to be combined in a single file. In combining the whole input to csound in a single, the UFF functions somewhat like a configuration file.

The Unified File Format file has a .csd extension. Its full specification is outlined in the The Canonical Csound Reference Manual under Unified File Format for Orchestras and Scores

The intent of this introduction is to familiarize the novice, in a somewhat informal way, with the syntax of the language, using several simple instrument examples. Many much more sophisticated examples are to be found through the References section at the end of this introduction.

Introduction

Csound is a sound and music computing system which was originally developed by Barry Vercoe in 1985 at MIT Media Lab, following the development of the Music "N" series of programs by Max Mathews and is collaborators, as documented in their seminal book The Technology pf Computer Music (see the References link, below). Since the 1990s, it has been developed by an active group of core developers. A wider community of volunteers contribute examples, documentation, articles, and takes part in the Csound development with bug reports, feature requests and discussions with the core development team.

Although Csound has a strong tradition as a tool for composing electro-acoustic music, it is used by composers, musicians, sonifiers and sound-designers for any kind of digital audio that can be made with the help of the computer. Csound has tradtionally been used in a non-interactive score driven context, but nowadays it is mostly used in in a real-time context. It can run on a host of different platforms incuding all major operating systems as well as Android and iOS. Csound can also be called through other programming languages such as Python, Lua, C/C++, Java, etc.

Installing Csound

This documentation assumes the you have a basic understanding of how to download, install and run software from the command line etc of your computer. The csoundinstaller can be downloaded for various platforms from the github csound site.

Python Interface to Csound

There has been extensive work on and with the Python interface to Csound. See the online ctcsound documentation for the definition of the API. Two other succinct introductory overviews in the recent publications are:
Lazzarini, V., Computer Music Instruments: Foundations, Design and Development (Springer 2017), Chapter 2: Music Programming Environments, and
Worrall, D., Sonification Design: From data to intelligible soundfields (Springer 2019), Chapter 6: The Sonipy Framework: Getting Started.

Example scripts are available in the toots_ctcsound directory of this site.

Index

The .csd files associated with these TOOTorials, can be downloaded: download Toots.zip

Overview of csound's operation from the computer's command-line

The csound program is run from the command-line like this:

$ csound myFile.csd

(where the $ sign is the computer's command-line prompt.


The basic structure of a .csd file is: 

<CsoundSynthesizer>
<CsOptions>

(options for controlling the csound program; as might otherwise be done from the command-line)

</CsOptions>
<CsInstruments>

(one or more instrument definitions)

</CsInstruments>
<CsScore>

(the score to initiate events on the instruments that were defined in the <CsInstruments> section)

</CsScore>
</CsoundSynthesizer>

Each of the sections of the .csd file (which can be created and edited in any plain-text editor, such as TextEdit on the Mac) contain specific types of commands or codes which are compiled and interpreted by the csound program. We will discuss the various sections of the .csd file, in detail later, however, when you execute the command
$ csound myFile.csd:
 - The score of events is sorted and ordered in time.
 - The orchestra is translated and loaded.
 - The wavetables,which we will see are defined as functions in the <CsScore> section, are computed and filled, and then,
 - The score is "performed". The score drives the orchestra by telling the specific instruments when and for how long to play, and what parameters to use during the course of each score event.

The <CsOptions> section

A full list of options can be listed by invoking the --help option on csound on the command-line, ie.
$ csound --help
A few of the many options include (the ; is the "comment to the end of the line" character): 


-odac     ; sound output to the computer's digital-to-analog-converter (DAC)

-o fnam   ; sound output filename

-i fnam   ; sound input filename

-W        ; create a WAV format output soundfile (use: -Wo "testy.wav")

-A        ; create an AIFF format output soundfile

-3        ; 24bit sound samples

-d        ; suppress all displays

-t N      ; use uninterpreted beats of the score, initially at tempo N

The <CsInstruments> section

The <Instruments> section of the .csd file contains two components:

Synthesis and output headers

A Csound orchestra generates signals at two rates:
- an audio sample rate and
- a control sample rate. The distinction between audio signals and sub-audio control signals is useful since it allows slower moving signals to require less compute time.
NB: In accord with the Sampling Theorem, each rate can represent signals with frequencies no higher than half that rate. In the header below, we have specified a sample rate of 44.1 kHz, a control rate of 4410 Hz, and then calculated the number of samples in each control period using the formula: ksmps = sr / kr.

<CsInstruments>
sr = 44100
kr = 4410
ksmps = 10
nchnls = 1
...
...

Instrument Definitions

All instruments are numbered (or named) and are referenced thus in the score, by using an i statement in first parameter-field of score statements. Each instrument consists of a set of unit generators, or software modules, which are patched together with i/o blocks — i-, k-, or a-rate variables. So, there are four types of variables :
 - setup only variables, set on instantiation, and apply to all instrument configurations
 - i-rate variables, changed at the note rate
 - k-rate variables, changed at the control signal rate
 - a-rate variables, changed at the audio signal rate

Orchestra Statements

Each statement occupies a single line and has the same basic format:

result action-generator arguments

To include an oscillator in our orchestra, it might specified as follows:

a1 oscil 10000, 440, 1

The three arguments for this oscillator set its
- amplitude (10000),
- frequency (440Hz), and
- wave table number (1).

The output is put in i/o memory block named a1. This output symbol (a) is significant in prescribing the rate at which the oscillator should generate output — here the audio or sampling rate (more later...). We could have named the result anything (e.g. asig) as long as it began with the letter a.


Like all unit generators, a full description of oscil can be found in the csound manual online

.

Comments

To include text in the orchestra or score which will not be interpreted by the program, precede it with a semicolon. This allows you to fully comment your code. On each line, any text which follows a semicolon will be ignored by the orchestra and score translators.

When Things Sound Wrong

When you design your own Csound instruments you may occasionally be surprised by the results. There will be times when you've computed a file for hours and your playback is just silence, while at other times you may get error messages which prevent the score from running, or you may hang the computer and nothing happens at all.

In general, Csound has a comprehensive error-checking facility that reports to your console at various stages of your run: at score sorting, orchestra translation, initializing each call of every instrument, and during performance. However, if your error was syntactically permissable, or it generated only a warning message, Csound could faithfully give you results you don't expect. Here is a list of the things you might check in your .csd files:

Suggestions for Further Study

Csound is such a powerful tool that we touch on only a few of its many features and uses. You are encouraged to take apart the instruments in the tutorials, rebuild them, modify them, and integrate the features of one into the design of another. To understand their capabilities you should compose short etudes with each.

There are many sources of information on Csound and software synthesis. The ultimate sourcebook for Csound is The Csound Book: Perspectives in Software Synthesis, Sound Design, Signal Processing, and Programming, edited by Richard Boulanger, and published by MIT Press.

Nothing will increase your understanding more than actually making sound with Csound. The best way to discover the full capability of these tools is to create your own audio with them. As you negotiate the new and uncharted terrain you will make many discoveries.



David Worrall (Ed)
Chicago, Illinois USA
March, 2020