Csound and CsoundAC 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.

CsoundAC is a Python extension module for doing algorithmic composition, in one which one writes music by programming in Python. Musical events are points in music space with dimensions {time, duration, event type, instrument, pitch as MIDI key, loudness as MIDI velocity, phase, pan, depth, height, pitch-class set, 1}, and pieces are composed by assembling a hierarchical tree of nodes in music space. Each node has its own local transformation of coordinates in music space. Nodes can be empty, contain scores or fragments of scores, generate scores, or transform scores. CsoundAC also contains a Python interface to the Csound API, making it easy to render CsoundAC compositions using Csound.

Licenses

Csound, CsoundAC, and CsoundVST

Copyright (C) 2001-2005 Michael Gogins, Matt Ingalls, John D. Ramsdell, John P. ffitch, Istvan Varga, Victor Lazzarini

This software is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this software; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

Manual

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.

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 extended Csound C++ API. Include CppSound.hpp and link with libcsound.a and libcsnd.a, which adds to the Csound C++ API a CsoundFile class for loading, saving, and editing Csound orchestra and score files.
• The CsoundAC C++ API. Include CsoundAC.hpp and link with libcsound.a, libcsnd.a, and libCsoundAC.a. The CsoundAC class contains an instance of the CppSound class, and provides a class hierarchy for doing algorithmic composition using Michael Gogins' concept of music graphs (previously known as Silence).
• The Csound Python API. Import the csnd Python extension module. This provides a complete Python wrapper for csound.hpp, CppSound, and CsoundFile. The Python API provides a complete Python wrapper for the entire Csound C++ API, and the Csound C++ API reference also serves as a reference to the Python API.
• The CsoundAC Python API. Import the CsoundAC Python extension module. The Python API provides a complete Python wrapper for the entire CsoundAC C++ API, including Silence, and the CsoundAC C++ API reference also serves as a reference to the Python API.
• An experimental LISP API.

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

The CsoundAC C++ API

CsoundAC extends the Csound API with C++. There is a C++ class for the Csound API proper (CppSound), another C++ class (CsoundFile) for manipulating Csound files in code, and additional classes for algorithmic composition based on music space. All these C++ classes also have a Python interface in the CsoundAC Python extension module.

You can build CsoundAC into your own software using the CsoundAC shared library and CsoundAC.hpp header file.

Cscore

Beginning with Csound 5, all of the Cscore functions described in the manual are now part of the Csound API, and they can be called from a program that calls the Csound library.

All of the CScore functions are renamed in the Csound API. For example, createv() is now cscoreCreateEvent(), and lcopy() is now cscoreListCopy(). In addition, each function takes an additional first parameter that is a pointer to a CSOUND instance. You can find the details in the header file, cscore.h, which may be included with your Csound distribution, or if not, can be found in Csound CVS `on SourceForge.

Before you can use any of the Cscore API functions, you must create a CSOUND instance and initialize Cscore by calling csoundInitializeCscore() -- see csound.h for an explanation. An example main program that does all of this Top/cscormai.c. You should add a function called cscore() with your own score-processing code. An example that does nothing except write the score back out unchanged can be found in the file Top/cscore_internal.c.

To create your own standalone Cscore program, you must compile cscormai.c (or your own main program) and the file containing your cscore() function, and link them with the Csound API library.

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.