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;
}

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.