# A simple instrument

Martin McBride, 2017-09-23

Here we will design the simplest possible CSound instrument, and play a little tune. We will first take a look at a basic CSound setup.

## Setting up

You will need to download and install CSound. As this isn't meant to be a beginners guide, I won't cover that here.

There are various ways of running CSound. For this tutorial I will use CSoundQt (sometimes known as QuteCSound), as it is convenient way to edit and play smallish CSound files. It ships with the standard CSound installer, so you can just run it.

If you prefer to use the command line, or some other front end program, go ahead - it won't really affect these instructions to much.

We will also be using .csd files - these combine the orchestra (instrument definitions) and score into a single file, which is very convenient. Again, if you prefer to use separate orchestra and score files, feel free, but you will have to edit the examples here (cut and paste the separate parts into separate files). It is probably a lot easier just to use the combined files.

## Playing a tone

Here is a simple .csd file to play a few notes. We will use it to give a quick guided tour of the typical file layout, and so you can make sure your setup works.

<CsoundSynthesizer>

<CsOptions>
</CsOptions>

<CsInstruments>
ar = 44100
ksmps = 10
nchnls = 1
0dbfs  = 1

instr 1
asig oscil 0.1, 440, 1
out asig
endin
</CsInstruments>

<CsScore>
f 1 0 16384 10 1

i 1 0 0.5
i 1 1 0.5
i 1 2 0.5
e
</CsScore>

</CsoundSynthesizer>


A .csd file is a simple XML file. The main section, CsoundSynthesiser contains 3 subsections

• CsOptions that we don't use.
• CsInstruments containing the instrument definitions.
• CsScore containing the sequence of notes to be played.

Copy and paste the code into CSoundQt, and play it. You should hear three separate tones:

## CSound parameters

The first part for the file sets some basic parameters. These are fairly standard and shouldn't need to change in most cases.

ar = 44100
ksmps = 10
nchnls = 1
0dbfs  = 1


ar sets the audio sample rate. 44100 is the standard rate for CD quality audio, and is a good choice for basic experimentation. You can use a higher rate for even better quality. In the olden days you might have used a lower rate to make CSound run faster and use less memory and disk space. But with a modern computer these things are unlikely to be an issue.

ksmps sets the control sample rate. This is used for control signals such as envelopes, that don't need to run at the full audio rate. A value of 10 makes the control rate ten times slower than the audio rate, which is fine for most cases.

nchnls sets the number of audio channels - basically 1 for mono or 2 for stereo. For our experiments, we aren't going to worry about stereo at first, so keep it at 1.

0dbsf sets the maximum signal value to 1. This means that a signal that oscillates between -1 and +1 creates the loudest possible sound. A signal that oscillates between +/-0.5 creates a quieter sound. A signal that oscillates between +/-2 will get clipped to values of +/-1, creating a distorted sound.

## The instrument

This code creates an instrument:

instr 1
asig oscil 0.5, 440, 1
out asig
endin


The instr statement identifies this as instrument 1.

The next statement takes the form:

[result] oscil [amplitude], [frequency], [function]


This creates an oscillating signal. [amplitude] controls amplitude (or volume) of the signal, and is set to 0.5, half the maximum. [frequency] controls the frequency of the signal, and is set to 440 cycles per second (middle A on a piano).

{{% blue-note %}} Cycles per second (cps) is measured in Hertz (shortened to Hz). 1 cps = 1 Hz. {{% /blue-note %}}

[function] is the function that will be used to create the oscillator waveform. We will use function number 1 (see below).

[result] is where we will store the result (that is, the oscillating sound signal). We will use a variable called asig.

The next line is the out statement:

out [signal]


This defines the output of the instrument - the actual sound it makes. We use asig as the [signal] parameter, which means that our instrument will create a sound based on the 440Hz tone from the oscil statement.

## The function

The first part of the CsScore section contains the function statement:

f 1 0 16384 10 1


This line creates a table of values representing one cycle of a sine wave. The oscil statement uses this table to create a sound.

We will look at the parameters in a later tutorial. The important one here is the first parameter, 1, which is the identity of the function. The oscil statement references this in its [function] parameter. If your file has more than one function (as it usually will), each one has to have a different number to identify it.

## The note list

The next section is a list of notes to play:

i 1 0 0.5
i 1 1 0.5
i 1 2 0.5

e


Each line of the list has the format:

i [instrument] [start time] [duration]


The [instrument] is the number of the instrument to play. In our case, we only have one instrument, with the number 1 (the instrument number is defined in the instr statement).

The [start time] is the time at which the note should start playing. The time is given in "beats", but the default tempo is one beat per second so the start time is effectively measured in seconds.

The [duration] is how long the note lasts, again in beats.

In our case, there are three notes, using instrument 1. The notes start at times 0, 1 and 2, and last for half a beat each. So the sequence you should hear is tone, gap, tone, gap, tone.

Notice that the notes list ends with this line:

e


As you might have guessed, this indicates the end of the list.