Using Python within Csound

One of the more powerful and open-ended features of Csound is its compatibility with the Python programming language. Python code can be embedded in your Csound orchestra—or, going the other direction, you can invoke Csound itself from within Python.

Csound is, among other things, a computer programming language. It might seem odd to want to embed code in a second programming language within your Csound code. Why not just write everything you need using Csound’s orchestra code syntax and avoid the hassle of learning an entirely new language?

In some cases, the answer may be, “Yes, that’s right. Just use plain Csound.” In other cases, using Python will offer some advantages, especially for the high-end user:

Python provides various ways to manipulate text strings. If your orchestra relies on being able to assemble strings on the fly, in order to pass them to the scoreline opcode, you may find that using Python will make your life easier. (Note: Starting with version 5.0, Csound includes a greatly expanded set of string manipulation opcodes, so Python loses some of its competitive edge in this area.)

Python implements lists and arrays. Csound has no equivalent of these data types; to get the same functionality without Python, you would have to resort to some fairly awkward workarounds using groups of tables. (Note, however, that Csound 5.14, released just before this book went to press, implements arrays as local data within instruments.)

Python comes with an extensive library of math functions, as well as a wealth of external modules, any of which may be useful for some sophisticated types of instruments.

For the Csound Journal, Issue 6 (May 2007), Andrés Cabrera wrote an excellent introduction to the use of Python within Csound. This article is available online (at www.csounds.com/journal/issue6/pythonOpcodes.html). If you want to learn the basics, it’s a must-read. The final section of the article provides an excellent example of how to use Python to create strings of notes using the logic of Markov chains. With Markov chains, you can control the precise likelihood that a note of any given pitch will be followed by a note of another given pitch. The results can be much more musically sensible than if each new pitch is chosen entirely at random.

More Ways to Code By the time you read this, Csound will probably have been expanded to allow the use of embedded code in the Lua programming language. The chief advantage of Lua, according to Michael Gogins, is that Lua runs much faster than Python. He also commented, “Lua is slightly more concise than Python, but because of some minor quirks, Python is slightly easier to write. Python currently has many more third-party libraries than Lua, but Lua has plenty and will get more. Lua is more elegant than Python, which is saying a lot, because Python is already very elegant.”

Python is one of the easier programming languages to learn. Its syntax is fairly straightforward, and excellent tutorials are available online. Another advantage for the newcomer is that Python is an interpreted language. Your code needn’t be compiled before it will run; you can experiment with it in real time, either from your computer’s command prompt or using the Python Shell, which is called IDLE. (Yes, the name is a reference to Monty Python’s Flying Circus.)

To get started, you’ll need to download Python from www.python.org. A number of versions are available. Csound 5.13 is compatible with Python 2.7, but not with more recent versions. If you’re using a later version of Csound, check the documentation or post a query to the Csound mailing list to find out which version of Python to install.

Tip Unlike Csound, Python makes strict use of indentation (via the Tab key) as a way to structure blocks of code. If you forget an indent, your code won’t run.

Your next task will be to learn Python. That process is not covered in Csound Power!

When installing Csound, you were asked whether to install the Python interface. This option is listed among the interfaces in the installer dialog. If you neglected to do that, you’ll need to run the installer again.

The Python Opcodes

There are a lot of Python opcodes. Fortunately, they’re named using a consistent syntax, so figuring out which one you need is easy. As The Canonical Csound Reference Manual explains, rather tersely, the syntax is:

  “py” + [optional context prefix] + [action name] + [optional x-time
  suffix]

What this means is as follows:

All python opcodes start with the letters “py”. Next, you may or may not need a lower-case “l”. If present, this causes any Python variables defined within the instrument to be local—specific to the current note event, and not carried over. In the absence of an “l”, Python variables are global. If they’re global, changes made by a variable in one Python function will be reflected in other functions that reference the same variable, even if those functions are running in other Csound instruments.

The action names for Python opcodes include init, eval, call, assign, exec, and run. The optional x-time suffix, “i”, tells Csound whether you want the Python opcode to run at init-time (if the “i” is present) or on every k-rate pass (if there’s no “i”).

The call opcodes have an added wrinkle. They call Python functions, and a function can return (output) from zero to eight values. A number appended to call tells Csound how many output values to expect. For example, after defining a Python function called get_note, you might write this:

  kp4, kp5, kp6 pycall3 “get_note”, kdata1, kdata2

This code would pass the values in kdata1 and kdata2 to the Python get_note function and put the three return values of the function into kp4, kp5, and kp6. Presumably, your code would then use these values with an event opcode to start a Csound note.

The Python opcodes can also be used in triggered form (suffix “t”). Triggered opcodes take an additional argument, the k-rate trigger, before the name of the function, file, or variable that the Python opcode will use. This is a k-rate trigger, so the suffixes “t” and “i” are mutually exclusive. The opcode will be triggered whenever the value of the trigger is not 0.

To use Python within Csound, you should call the pyinit opcode in your orchestra header. (pyinit is no longer needed in the most recent builds of Csound, but may still be needed in older versions.) Once you’ve done this, you can use pyruni in the header to set up an arbitrarily complex set of functions in Python.

Note Most Python code takes up more than one line. The Csound compiler will be able to cope with this structure if you surround the code with double curly braces. Use {{ at the beginning of the code and }} at the end.