hello, world

Csound is a kind of programming language that allows you to generate and process music. I know so little about it that even such a brief description must be full of inaccuracies. But more or less this is what it is.

Although you can use different files and combine them, we are going here to use a unified file format, with 'csd' extension, so everything will be in a single file.

We create a file a build the skeleton. Comments are written after either // or ;, or between /* and */ for multiple lines.

<CsoundSynthesizer>
<CsOptions>
//options here for how to interact with devices and hardware
</CsOptions>
<CsInstruments>
//code about instruments here
</CsInstruments>
<CsScore>
//the score here: what and how to use the instruments defined above
</CsScore>
</CsoundSynthesizer>

To execute a program, just call csound file.csd from the terminal. There are many options for the command line, but here we are just doing a simple example.

A simple Hello, world would be like this:

<CsoundSynthesizer>
<CsOptions>
-odac  
</CsOptions>
<CsInstruments>
instr 1 
aSin      oscil    0dbfs/4, 440  
          out       aSin
endin  
</CsInstruments>
<CsScore>
i 1 2 3
</CsScore>
</CsoundSynthesizer>

Now I am going to write it again, but this time with several comments.

<CsoundSynthesizer>
<CsOptions>
-odac  // output sound through the default soundcard
//if the previous line is not present, a .wav file will be generated with the sound.
</CsOptions>
<CsInstruments>
instr 1 //begins definition of instrument we call '1'
/*
Now we will use a predefined function of Csound: oscil
There are thousands of such functions (called opcodes).
They are read from right to left. 
At the right is the input of the function.
At the centre is the function itself.
At the left is the output of the function.
output arguments <--- function <--- input arguments
In this case, oscil is just an oscillator function.
As input, it needs (at least) two arguments.
Arguments are separated by commas.
The first argument is the amplitude.
0dbfs is the relative amplitude (from 0 to 1).
We divide it by 4 to avoid ear and/or earphone damage.
The second argument is the frequency of oscillation, in Hertzs.
The output here is a single argument, that we call aSin.
*/
aSin      oscil    0dbfs/4, 440  
/*
Now we have the output of the function oscil stored in the variable aSin.
But we want to listen such oscillation, so we must pass it through another function, called out. 
The out function does not have output arguments, so there is nothing at the left.
*/
          out       aSin
endin  //ends instrument definition
</CsInstruments>
<CsScore>
/*
The score will be simple.
Each note begins with a line starting with an i.
The next argument, called the p1 argument, is the name or number of the instrument, in this case 1.
The second argument, called p2, is the time at which the instrument begins to play.
In this case, the instrument plays after 2 s from the beginning, at t=2 s.
The third argument, p3, is the duration of the note, in seconds. 
The note will sound from t=2 s until t=5 s.
*/
i 1 2 3
</CsScore>
</CsoundSynthesizer>