The ctcsound Module

The Csound API is a set of C functions and C++ classes that expose to hosts programs the functionalities of Csound.

ctcsound is a python module wrapping the access to the Csound API using two Python classes: Csound and CsoundPerformanceThread. ctcsound uses the ctypes python module which is an FFI (Foreign Function Interface) allowing Python to access C shared libraries. ctcsound is written in pure Python and it can be used with Python 2 and 3. ctcsound depends on the numpy Python module, and it needs Csound version 6.07 or higher.

Our session begins by importing the ctcsound module:



In [1]:

    
import ctcsound

Csound Instance

Let's create a Csound instance which is embedded in a ctcsound.Csound() object.



In [2]:

    
cs = ctcsound.Csound()

Csound outputs something like this in the console:

virtual_keyboard real time MIDI plugin for Csound
0dBFS level = 32768.0
Csound version 6.07 (double samples) Mar  8 2016
libsndfile-1.0.25

Most of the functions in the API are called with an opaque pointer to a csound instance as first argument. In ctcsound this mechanism has been integrated in the ctcsound.Csound Python class. Those API functions are then wrapped in methods of the class, the opaque pointer being added implicitly.

The C functions of the API are called with names beginning with csound. In the ctcsound.Csound class, the csound prefix and the first argument are omitted. For example: csoundCompileCsdText(CSOUND *csound, const char *txt) becomes cs.compileCsdText(txt).

The modern naming conventions for getter and setter are applied. This means that the get verb is omitted. So csoundGetSr(CSOUND *) becomes cs.sr().

If we need to read directly the opaque pointer to the Csound instance, we can get it from the csound() method of our object: cs.csound()

Let's get some general information:



In [3]:

    
# Get version numbers
v, va = cs.version(), cs.APIVersion()
print("Raw version values: {}, {}".format(v, va))

# Format version numbers
major, v = int(v/1000), v%1000
minor, patch = int(v/10), v%10
print('Csound version: {0}.{1:02d}.{2}'.format(major, minor, patch))
major, minor = int(va/100), va%100
print('API version: {0}.{1:02}'.format(major, minor))

# Get sample size
sampleSize = cs.sizeOfMYFLT()
print('Sample size: {}'.format(sampleSize))

# Show the value of the pointer to the Csound instance
print("Value of the opaque pointer: {}".format(cs.csound()))









    



Raw version values: 6091, 400
Csound version: 6.09.1
API version: 4.00
Sample size: 8
Value of the opaque pointer: 49424816

When we're done with our session, the Python garbage collector will destroy our cs object, and this destruction will implicitly cause the end of the Csound instance. We can explicitly see what is happening by deleting ourself the Python object:



In [4]:

    
del cs

Csound outputs something like this in the console:

end of score.          overall amps:      0.0
       overall samples out of range:        0
0 errors in performance
Elapsed time at end of performance: real: 5.899s, CPU: 0.008s