The basic Csound API is the C API. To use the Csound C API, you have to include csound.h in your source file and to link your code with libcsound. Here is an example of the csound command written using the Csound C API:
#include <csound/csound.h>
int main(int argc, char **argv)
{
CSOUND *csound = csoundCreate(NULL);
int result = csoundCompile(csound, argc, argv);
if (result == 0) {
result = csoundPerform(csound);
}
csoundDestroy(csound);
return (result >= 0 ? 0 : result);
}
First we create an instance of Csound, getting an opaque pointer that will be passed to most C API functions we will use. Then we compile the orc, sco pair of files or the csd file given as input argument through the argv parameter of the main function. If the compilation is successful (result == 0), we call the csoundPerform function. Finally, when csoundPerform returns, we destroy our instance before ending the program.
On a linux system, with libcsound named libcsound64 (double version of the csound library), supposing that all include and library paths are set correctly, we would build the above example with the following command:
gcc -DUSE_DOUBLE -o csoundCommand csoundCommand.c -lcsound64
The C API has been wrapped in a C++ class for convenience. This gives the Csound basic C++ API. With this API, the above example would become:
#include <csound/csound.hpp>
int main(int argc, char **argv)
{
Csound *cs = new Csound();
int result = cs->Compile(argc, argv);
if (result == 0) {
result = cs->Perform();
}
return (result >= 0 ? 0 : result);
}
Here, we get a pointer to a Csound object instead of the csound opaque pointer. We call methods of this object instead of C functions, and we don't need to call csoundDestroy in the end of the program, because the C++ object destruction mechanism takes care of this. On our linux system, the example would be built with the following command:
g++ -DUSE_DOUBLE -o csoundCommandCpp csoundCommand.cpp -lcsound64
The Csound API has been wrapped to other languages. The Csound Python API wraps the Csound API to the Python language. To use this API, you have to import the csnd module. The csnd module is normally installed in the site-packages or dist-packages directory of your python distribution as a csnd.py file. Our csound command example becomes:
import sys
import csnd
def csoundCommand(args):
csound = csnd.Csound()
arguments = csnd.CsoundArgVList()
for s in args:
arguments.Append(s)
result = csound.Compile(arguments.argc(), arguments.argv())
if result == 0:
result = csound.Perform()
return result
def main():
csoundCommand(sys.argv)
if __name__ =='__main__':
main()
We use a Csound object (remember Python has OOp features). Note the use of the CsoundArgVList helper class to wrap the program input arguments into a C++ manageable object. In fact, the Csound class has syntactic sugar (thanks to method overloading) for the Compile method. If you have less than six string arguments to pass to this method, you can pass them directly. But here, as we don't know the number of arguments to our csound command, we use the more general mechanism of the CsoundArgVList helper class.
The Csound Java API wraps the Csound API to the Java language. To use this API, you have to import the csnd package. The csnd package is located in the csnd.jar archive which has to be known from your Java path. Our csound command example becomes:
import csnd.*;
public class CsoundCommand
{
private Csound csound = null;
private CsoundArgVList arguments = null;
public CsoundCommand(String[] args) {
csound = new Csound();
arguments = new CsoundArgVList();
arguments.Append("dummy");
for (int i = 0; i < args.length; i++) {
arguments.Append(args[i]);
}
int result = csound.Compile(arguments.argc(), arguments.argv());
if (result == 0) {
result = csound.Perform();
}
System.out.println(result);
}
public static void main(String[] args) {
CsoundCommand csCmd = new CsoundCommand(args);
}
}
Note the "dummy" string as first argument in the arguments list. C, C++ and Python expect that the first argument in a program argv input array is implicitly the name of the calling program. This is not the case in Java: the first location in the program argv input array contains the first command line argument if any. So we have to had this "dummy" string value in the first location of the arguments array so that the C API function called by our csound.Compile method is happy.
This illustrates a fundamental point about the Csound API. Whichever API wrapper is used (C++, Python, Java, etc), it is the C API which is working under the hood. So a thorough knowledge of the Csound C API is highly recommended if you plan to use the Csound API in any of its different flavours. The main source of information about the Csound C API is the csound.h header file which is fully commented.
On our linux system, with csnd.jar located in /usr/local/lib/csound/java, our Java Program would be compiled and run with the following commands:
javac -cp /usr/local/lib/csound/java/csnd.jar CsoundCommand.java java -cp /usr/local/lib/csound/java/csnd.jar:. CsoundCommand
There are too an extended Csound C++ API, which adds to the Csound C++ API a CsoundFile class, the CsoundAC C++ API, which provides a class hierarchy for doing algorithmic composition using Michael Gogins' concept of music graphs, and API wrappers for the LISP, LUA and HASKELL languages.
In this introductory chapter we will focus on the basic C++ API, and the Python and Java API.
Michael Gogins 2006, "Csound and CsoundVST API Reference Manual", http://csound.sourceforge.net/refman.pdf
Rory Walsh 2006, "Developping standalone applications using the Csound Host API and wxWidgets", Csound Journal Volume 1 Issue 4 - Summer 2006, http://www.csounds.com/journal/2006summer/wxCsound.html
Rory Walsh 2010, "Developping Audio Software with the Csound Host API", The Audio Programming Book, DVD Chapter 35, The MIT Press
François Pinot 2011, "Real-time Coding Using the Python API: Score Events", Csound Journal Issue 14 - Winter 2011, http://www.csounds.com/journal/issue14/realtimeCsoundPython.html