The Python Csound The API (ctcsound.py)
The Csound API provides complete access to the system, from configuration to code compilation and audio engine performance. It is based on a C/C++ set of functions and classes, but it has been wrapped for various languages. In the case of Python, there are two alternative packages that can be used, csnd6 and ctcsound. The former is only available for Python 2 and the latter can be used in both versions 2 and 3.
The ctcsound package provides full access to the Csound C API, in addition to a few extra components. It can be loaded with the command:
>>>import ctcsound
A typical use of the package involves the following steps:
- Creating a Csound object
- Setting up options to control the compiler and engine
- Compiling code
- Starting and running the audio engine
- Interacting with the compiled instruments
For example, the following code creates a Csound object, sets it to output audio to the soundcard, compiles some code and performs it:
code = '''
instr 1
endin
idur = p3
iamp = p4
icps = p5
ksig = linen(iamp,0.1,idur,0.2)
asig = oscili(ksig, icps)
out(asig)
schedule(1,0,1,0dbfs/3,440)
schedule(1,1,1,0dbfs/3, 550)
schedule(1,2,1,0dbfs/3, 660)
'''
cs = ctcsound.Csound()
cs.setOption('-odac')
cs.compileOrc(code)
cs.start()
cs.perform()
When running the Csound engine, it is often simpler to start a new thread for performance, so that the user can interact with it. For this purpose, we have the CsoundPerformanceThread class, which takes a Csound object and allows it to be played:
cs = ctcsound.Csound()
cs.setOption ('-odac')
cs.compileOrc (code)
cs.start()
perf = ctcsound.
CsoundPerformanceThread(self.cs.csound())
perf.play()
Methods for pausing, stopping and joining the thread are available (pause(), stop(), and join()). With Csound running in a separate thread, we can start new instruments running and set controls in them using methods of the Csound class. Both of the above examples (with and without threads) can be used to run the Csound code examples in this book, with Python as the host environment. In this case all we need to do is to replace the triple-quoted string in code by the program in question. We might also need to set other options, which we can do by calling setOption() more than once with the option as an argument.