Csound API  6.09
Csound API 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:

  • The basic Csound C API. Include csound.h and link with libcsound.a. This also includes the Cscore API (see below).
  • The basic Csound C++ API. Include csound.hpp and link with libcsound.a.
  • The interfaces API, includes a number of auxiliary C++ classes, which add functionality and support the wrapping of the Csound API by various languages (e.g. Python, Java, Lua).

Purposes

The purposes of the Csound API are as follows:

  • Declare a stable public application programming interface (API) for Csound in csound.h. This is the only header file that needs to be #included by users of the Csound API.
  • Hide the internal implementation details of Csound from users of the API, so that development of Csound can proceed without affecting code that uses the API.

Users

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

  • Hosts are applications that use Csound as a software synthesis engine. Hosts can link with the Csound API either statically or dynamically.
  • Plugins are shared libraries loaded by Csound at run time to implement external opcodes and/or drivers for audio or MIDI input and output. Plugin opcodes need only include the csdl.h header which brings all necessary functions and data structures. Plugins can be written in C or C++. For C++, OOP support is given through include/plugin.h (using the Csound allocator, for opcodes that do not involve standard C++ library collections) or include/OpcodeBase.hpp (using the standard ++ allocator, for opcodes that do use standard C++ library collections).

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;
}
Declares the public Csound application programming interface (API).
PUBLIC void csoundDestroy(CSOUND *)
Destroys an instance of Csound.
PUBLIC CSOUND * csoundCreate(void *hostData)
Creates an instance of Csound.
PUBLIC int csoundPerformKsmps(CSOUND *)
Senses input events, and performs one control sample worth (ksmps) of audio output.
PUBLIC int csoundCleanup(CSOUND *)
Prints information about the end of a performance, and closes audio and MIDI devices.
PUBLIC int csoundCompile(CSOUND *, int argc, const char **argv)
Compiles Csound input files (such as an orchestra and score, or CSD) as directed by the supplied comm...

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;
}
PUBLIC void csoundReset(CSOUND *)
Resets all internal memory and state in preparation for a new performance.
PUBLIC int csoundCompileCsdText(CSOUND *csound, const char *csd_text)
Behaves the same way as csoundCompileCsd, except that the content of the CSD is read from the csd_tex...
PUBLIC int csoundStart(CSOUND *csound)
Prepares Csound for performance.

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;
}
PUBLIC int csoundSetOption(CSOUND *csound, const char *option)
Set a single csound option (flag).
PUBLIC int csoundCompileOrc(CSOUND *csound, const char *str)
Parse, and compile the given orchestra from an ASCII string, also evaluating any global space code (i...
PUBLIC int csoundReadScore(CSOUND *csound, const char *str)
Read, preprocess, and load a score from an ASCII string It can be called repeatedly,...

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.