Csound-Python

Csound can be controlled through its host API. On the XO, it is possible to write programs to use the API in C or C++, but the best way to go about it is to use the Python language. Csound offers a good level of control through its API and Python, allowing a host application to run and interface with Csound.

Importing the module

The Csound module for Python is imported using

import csnd

This will allow you to control an instance of Csound from your Python script. Some degree of help can be got by doing

help(csnd)

Or by using the pydoc command.

Basic operation

In general, you would want to

1) Create an instance of Csound: this is typically done using the Csound class (although there are other ways of doing the same thing):

cs = csnd.Csound()

2) Now you have a Csound instance, you will want to load up a CSD file, which can be done using the Compile method:

 res = cs.Compile("my.csd")

3) If the previous step succeeds (res is 0), then you can run Csound, using the Perform() method:

 cs.Perform()

This will run the whole score in the CSD file, returning when it is finished.

4) You can reset Csound, ready for a new compilation/performance:

 cs.Reset()

Threads

If you want to do other things while Csound is running, you will need to run the performance in a separate thread. This is perhaps the most typical way of doing things. You will need to set a Csound performance thread object to do it, passing the Csound object as a parameter:

 perf = csnd.CsoundPerformanceThread(cs)

Now all you need to do is play it:

 perf.Play()

You can also pause it whenever you like:

 perf.Pause()

At the end of the performance, the thread is extinguished. If you want to stop it before that, you can do this:

 perf.Stop()
 perf.Join()

It is important to Join() the thread after you stop, so the main thread waits until the performance one is finished before proceeding to do other operations on the Csound object.

Channels

Data can be sent to Csound using the 'named' software bus. This works on the basis of named channels that are set by the Python code or by Csound orchestra code. For instance:

 cs.SetChannel("frequency", 440.0)

Creates a channel in Csound (if it does not already exist) and sets the value of 440.0 to it. Likewise, data can be retrieved from Csound using

 value = cs.GetChannel("rms")

This sets the variable value with the data in the "rms" channel. C Channels can hold floating-point numeric values or strings.