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. Plugins can be written in C++ using either
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 API
The Csound command–line program is itself built using the Csound API. Its code reads (in outline) as follows:
int main(int argc, char **argv)
{
if(!result) {
}
return result;
}
The Csound API defines two modes of operation for hosts. In the first mode, a regular Csound score is performed and then performance automatically ends. This could be called "score mode." In the second mode, Csound continues to perform indefinitely until performance is explicitly ended by calling csoundStop. This could be called "live mode." Which mode is used is determined by when csoundStart is called. In more detail:
Score Mode
- The <CsOptions> section of the CSD file is processed.
- Either csoundStart must be called after csoundCompileCsd or csoundReadScore, or csoundReadScore must be called before csoundCompile.
- The score is pre-processed, and events are dispatched as regular score events. "f", "s", and "e" events are permitted in the score.
const char *csd_text = "blah blah blah";
int main(int argc, char **argv)
{
while (1) {
if (result != 0) {
break;
}
}
return result;
}
Live Mode
- The <CsOptions> section of the CSD file not processed; options must be set by calling csoundSetOption.
- csoundStart must be called before csoundCompileCsd or csoundReadScore.
- The score is not pre-processed, and events are dispatched as real-time events. "f", "s", and "e" events are not permitted.
const char *orc_text = "blah blah blah";
const char *sco_text = "blah blah blah";
int main(int argc, char **argv)
{
while (1) {
if (result != 0) {
break;
}
}
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.