Csound  6.16
Csound Documentation

Csound is a sound and music computing system. It was originally written by Barry Vercoe at the Massachusetts Institute of Technology in 1984 as the first C language version of this type of software. Since then Csound has received numerous contributions from researchers, programmers, and musicians from around the world.

Outline of the API

The Csound Application Programming Interfaces

The Csound Application Programming Interface (API) reference is contained herein. The Csound API actually consists of several APIs:

Purposes

The purposes of the Csound API are as follows:

Users

Users of the Csound API fall into two main categories: hosts and plugins.

Examples Using the Csound (host) API

The Csound command–line program is itself built using the Csound API. Its code reads (in outline) as follows:

#include "csound.h"
int main(int argc, char **argv)
{
void *csound = csoundCreate(0);
int result = csoundCompile(csound, argc, argv);
if(!result) {
while(csoundPerformKsmps(csound) == 0){}
csoundCleanup(csound);
}
csoundDestroy(csound);
return result;
}

Csound code can also be supplied directly using strings, either as a multi-section CSD (with the same format as CSD files) or directly as a string. It can be compiled any number of times before or during performance.

Using a CSD text

System options can be passed via the CSD text before the engine is started. These are ignored in subsequent compilations.

#include "csound.h"
const char *csd_text =
"<CsoundSynthesizer> \n"
"<CsOptions> -odac </CsOptions> \n"
"<CsInstruments> \n"
"instr 1 \n"
" out(linen(oscili(p4,p5),0.1,p3,0.1)) \n"
"endin \n"
"</CsInstruments> \n"
"<CsScore> \n"
"i1 0 5 1000 440 \n"
"</CsScore> \n"
"</CsoundSynthesizer> \n";
int main(int argc, char **argv)
{
void *csound = csoundCreate(0);
int result = csoundCompileCsdText(csound, csd_text);
result = csoundStart(csound);
while (1) {
result = csoundPerformKsmps(csound);
if (result != 0) {
break;
}
}
result = csoundCleanup(csound);
csoundReset(csound);
csoundDestroy(csound);
return result;
}

Using Csound code directly.

Options can be passed via csoundSetOption() before the engine starts.

#include "csound.h"
const char *orc_text =
"instr 1 \n"
" out(linen(oscili(p4,p5),0.1,p3,0.1)) \n"
"endin \n";
const char *sco_text = "i1 0 5 1000 440 \n";
int main(int argc, char **argv)
{
void *csound = csoundCreate(0);
int result = csoundSetOption(csound, "-d");
result = csoundSetOption(csound, "-odac");
result = csoundStart(csound);
result = csoundCompileOrc(csound, orc_text);
result = csoundReadScore(csound, sco_text);
while (1) {
result = csoundPerformKsmps(csound);
if (result != 0) {
break;
}
}
result = csoundCleanup(csound);
csoundReset(csound);
csoundDestroy(csound);
return result;
}

Everything that can be done using C as in the above examples can also be done in a similar manner in Python or any of the other Csound API languages.