Csound API  6.07
Csound API Documentation

Csound is a unit generator-based, user-programmable, user-extensible computer music 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.

An Example Using the Csound API

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

#include "csound.h"
int main(int argc, char **argv)
{
// Create Csound.
void *csound = csoundCreate(0);
// One complete compile/perform cycle.
int result = csoundCompile(csound, argc, argv);
if(!result) {
while(csoundPerformKsmps(csound) == 0){}
csoundCleanup(csound);
}
// Destroy 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.