Orchestra and Score
In Csound, you must define "instruments", which are units which "do things", for instance playing a sine wave. These instruments must be called or "turned on" by a "score". The Csound "score" is a list of events which describe how the instruments are to be played in time. It can be thought of as a timeline in text.
instr 1 ... instrument instructions come here... endin
Score events in Csound are individual text lines, which can turn on instruments for a certain time. For example, to turn on instrument 1, at time 0, for 2 seconds you will use:
i 1 0 2
The Csound Document Structure
A Csound document is structured into three main sections:
- CsOptions: Contains the configuration options for Csound. For example using "-o dac" in this section will make Csound run in real-time instead of writing a sound file.1
- CsInstruments: Contains the instrument definitions and optionally some global settings and definitions like sample rate, etc. 2
- CsScore: Contains the score events which trigger the instruments.
Each of these sections is opened with a <xyz> tag and closed with a </xyz> tag. Every Csound file starts with the <CsoundSynthesizer> tag, and ends with </CsoundSynthesizer>. Only the text in-between will be used by Csound.
<CsoundSynthesizer>; START OF A CSOUND FILE <CsOptions> ; CSOUND CONFIGURATION -odac </CsOptions> <CsInstruments> ; INSTRUMENT DEFINITIONS GO HERE ; Set the audio sample rate to 44100 Hz sr = 44100 instr 1 ; a 440 Hz Sine Wave aSin oscils 0dbfs/4, 440, 0 out aSin endin </CsInstruments> <CsScore> ; SCORE EVENTS GO HERE i 1 0 1 </CsScore> </CsoundSynthesizer> ; END OF THE CSOUND FILE ; Anything after is ignored by Csound
Comments, which are lines of text that Csound will ignore, are started with the ";" character. Multi-line comments can be made by encasing them between "/*" and "*/".
"Opcodes" or "Unit generators" are the basic building blocks of Csound. Opcodes can do many things like produce oscillating signals, filter signals, perform mathematical functions or even turn on and off instruments. Opcodes, depending on their function, will take inputs and outputs. Each input or output is called, in programming terms, an "argument". Opcodes always take input arguments on the right and output their results on the left, like this:
output OPCODE input1, input2, input3, .., inputN
For example the oscils opcode has three inputs: amplitude, frequency and phase, and produces a sine wave signal:
aSin oscils 0dbfs/4, 440, 0
In this case, a 440 Hertz oscillation starting at phase 0 radians, with an amplitude of 0dbfs/4 (a quarter of 0 dB as full scale) will be created and its output will be stored in a container called aSin. The order of the arguments is important: the first input to oscils will always be amplitude, the second, frequency and the third, phase.
Many opcodes include optional input arguments and occasionally optional output arguments. These will always be placed after the essential arguments. In the Csound Manual documentation they are indicated using square brackets "". If optional input arguments are omitted they are replaced with the default values indicated in the Csound Manual. The addition of optional output arguments normally initiates a different mode of that opcode: for example, a stereo as opposed to mono version of the opcode.
A "variable" is a named container. It is a place to store things like signals or values from where they can be recalled by using their name. In Csound there are various types of variables. The easiest way to deal with variables when getting to know Csound is to imagine them as cables.
If you want to patch this together: Oscillator->Filter->Output,
you need two cables, one going out from the oscillator into the filter and one from the filter to the output. The cables carry audio signals, which are variables beginning with the letter "a".
aSource buzz 0.8, 200, 10, 1 aFiltered moogladder aSource, 400, 0.8 out aFiltered
In the example above, the buzz opcode produces a complex waveform as signal aSource. This signal is fed into the moogladder opcode, which in turn produces the signal aFiltered. The out opcode takes this signal, and sends it to the output whether that be to the speakers or to a rendered file.
Other common variable types are "k" variables which store control signals, which are updated less frequently than audio signals, and "i" variables which are constants within each instrument note.
Using the Manual
The Csound Reference Manual is a comprehensive source regarding Csound's syntax and opcodes. All opcodes have their own manual entry describing their syntax and behavior, and the manual contains a detailed reference on the Csound language and options.
In CsoundQt you can find the Csound Manual in the Help Menu. You can quickly go to a particular opcode entry in the manual by putting the cursor on the opcode and pressing Shift+F1. WinXsound , Cabbage and Blue also provide easy access to the manual.
- Find all options ("flags") in alphabetical order at www.csounds.com/manual/html/CommandFlags.html or sorted by category at www.csounds.com/manual/html/CommandFlagsCategory.html .^
- It is not obligatory to include Orchestra Header Statements (sr, kr, ksmps, nchnls, etc.) in the
section. If they are omitted, then the default value will be used:
sr (audio sampling rate, default value is 44100)
kr (control rate, default value is 4410, but overwritten if ksmps is specified, as kr=sr/ksmps)
ksmps (number of samples in a control period, default value is 10)
nchnls (number of channels of audio output, default value is 1 (mono))
0dbfs (value of 0 decibels using full scale amplitude, default is 32767)
Modern audio software normal uses 0dbfs = 1
Read chapter 01 to know more about these terms from a general perspective. Read chapter 03A to know more in detail about ksmps and friends. ^