Instruments Simplified with Python Decorators

Python can be molded to look like an audio synthesis language with the help of decorators. In my last post, I showed an instrument graph built within a Python iterator class. However, Iterator classes are too clunky looking, and require more work than should be necessary for creating a simple graph. Read and download this blog’s example script here.

So how does it look in comparison?

def MyInstr(dur=1.0, amp=1.0, freq=440, tune=12):
    a1 = Sine(amp * 0.5, freq)
    a2 = Sine(amp * 0.5, freq * 2 ** (tune / 12.0))
    return Multiply(Sum(a1, a2), RiseFall(dur, 0.5))

The @Instr decorator signals to both the human and the computer that the proceeding definition is an instrument class. Much easier to deal with than having to fiddle around with class methods __init__(), __iter__() and next(). There’s less code to write, and far less chance to break the internals of an iterator class. And it more closely resembles an audio synthesis language. Here’s a near equivalent version written in Csound:

instr MyInstr
    idur = p3
    iamp = p4
    ifreq = p5
    itune = p6
    a1 oscils iamp * 0.5, ifreq, 0
    a2 oscils iamp * 0.5, ifreq * 2 ^ (itune / 12), 0
    kenv linseg 0, idur * 0.5, 1, idur * 0.5, 0
    out kenv * (a1 + a2)

What’s going on exactly? Well, to be honest, decorators have been eluding me for the past two weeks. It wasn’t until last night as I was halfway through watching Eddie Izzard’s Dress to Kill that it suddenly clicked. So any explanation I give will be insufficient. I’ll just say that @Instr refers to a generic graph iterator class designed by me that creates a new iterator class that assimilates def MyInstr. If you want to know more, you can read Bruce Eckel’s Introduction to Python Decorators.

Question: Cake or death?

Python Iterator Class as Instrument Graph

I built an iterator class from the graph in yesterday’s example. Read and download the full script here. Let’s take a look at the class, then discuss the implications:

class MyInstr:
    '''My Instrument'''

    def __init__(self, dur, amp=1.0, freq=440, tune=12):
        a1 = Sine(amp * 0.5, freq)
        a2 = Sine(amp * 0.5, freq * 2 ** (tune / 12.0))
        self.out = Multiply(Sum(a1, a2), RiseFall(dur, 0.5))

    def __iter__(self):
        self.index = 0
        self._iter = (i for i in self.out)
        return self
    def next(self): 
        if self.index >= ksmps: raise StopIteration 
        self.index += 1

What good is a graph defined as an iterator class? The class essentially works like a Csound instrument. Multiple instances with varied input can be created, like Csound score i-events. It is also, more or less, a new unit generator that can be patched into a new graph. Most importantly, they can be easily shared with others in the Slipmat community. Import. Reuse. Remix.

There is a downside. If you’re not familiar with Python code or Python iterator classes, then you probably can’t make heads or tails out of this. One of the fundamental principles of the Slipmat philosophy is that the code needs to be user-friendly. Iterator classes as graphs, well, that’s a big technical hurdle, especially for n00bs. I don’t like hurdles; they restrict the creative flow, and can be a show stopper.

Fortunately, there is a solution, which I’ll post later today. If you happen to follow my twitter feed, then you probably have figured out where I’m going.

Here’s the the new __main__:

if __name__ == "__main__":
    t = 0.002
    my_instr = MyInstr(t, 1, 440, 7)
    for frame in Run(t):
        print '%d:' % frame
        for i in my_instr:
            print 't%.8f' % i

This produces identical results to yesterday’s script. The only difference is that the code has been refactored to increase modularity and possibly clarity.

Control-Rate Envelope Generator

I wanted to generate a control-rate signal with my Python-Slipmat prototype. To my surprise, doing so was fairly straight forward; Python iterator classes have a control-rate mechanism built right in.

Read and download the full script at snipt.

I designed a simple envelope that generates a rise-fall shape. By default, the rise and fall times are identical, though users can specify a peak value relative to the duration. Here’s the code:

class RiseFall:
    '''A rise-fall envelope generator.'''
    def __init__(self, dur, peak=0.5):
        self.frames = int(dur * sr / float(ksmps))
        self.rise = int(peak * self.frames)
        self.fall = int(self.frames - self.rise) = 0
        self.v = 0
    def __iter__(self):
        self.index = 0
        if <= self.rise and self.rise != 0:
            self.v = / float(self.rise)
            self.v = (self.fall - ( - self.rise)) / float(self.fall)
            += 1
        return self
    def next(self):
        if self.index >= ksmps:
            raise StopIteration

        self.index += 1          
        return self.v

To make sense of this, I’m going to compare this Python iterator class to Csound. More or less, Csound works at three rates: init (i), control (k) and audio (a). All three of these are represented in class RiseFall. The i-rate of RiseFall is __init__(), the k-rate is __iter__() and the a-rate is next().

What makes RiseFall a k-rate unit generator is that the code that calculates the current value of the envelope resides in __iter__(), which gets executed at the beginning of each new frame of audio. If you look at class Sine, you’ll see that the code responsible for generating the sine wave is in the class method next().

And here is RiseFall added to our graph:

if __name__ == "__main__":
    t = 0.002
    a1 = Sine(0.5, 440)
    a2 = Sine(0.5, 440 * 2 ** (7 / 12.0))
    amix = Sum(a1, a2)
    aenv = RiseFall(t, 0.5)
    aout = Multiply(amix, aenv)

    for frame in Run(t):
        print '%d:' % frame
        for i in aout:
            print 't%.8f' % i

I also refactored class Mixer; It is now known as Sum, which can now sum two or more signals. Additionally, I added the class Multiply, which takes after Sum.

Slipmat Prototype & Processing

I experimenting combining the first Slipmat prototype (built with the Csound API) with Processing. Getting the two systems working together was fairly straight forward. Here’s the code that generated the video.

The following method from class Disc does two things when a disc collides with a border: change direction of the disc and trigger a slipmat event:

public void moveDisc() {
    x += xVelocity * SCALE_VELOCITY;
    y += yVelocity * SCALE_VELOCITY;

    if (x <= DISC_RADIUS || x >= width - 1 - DISC_RADIUS) {
        xVelocity *= -1;

    if (y <= DISC_RADIUS || y >= height - 1 - DISC_RADIUS) {
        yVelocity *= -1;

The method playNote() also belongs to class Disc, and is where the actual triggering of the Slipmat event occurs. The instances sp1 and sp2 are part of the Slipmat system. The “sp” is short for “sine percussion.”

public void playNote() {
    sp1.playNote(0.0, 0.35 * (1 - x / width), frequency);
    sp2.playNote(0.0, 0.35 * x / width, frequency);

Early Java Slipmat Prototype

Slipmat has been a pet project of mine for a few years now. The first working prototype was realized in Java. The code for this is up at sourceforge.

Originally, the idea was for slipmat to be a java interface layer that sits on top of Csound. Hence the slipmat metaphor. At one point, it became much too unwieldily and I had abandoned it. Until later when I picked up Python, and decided to give it another go. Python made things much easier all the way around, but I eventually abandoned that too, for reasons I’ll go into later.

Here is an excerpt from one of the original Java prototype examples:

public ControllerExample() {
    /* Create empty SynthRack */
    SynthRack synthRack = new SynthRack(false);
    /* Create modules */
    LinearSlide linearSlider = new LinearSlide();
    SynthBass bass = new SynthBass();
    Output output = new Output();

    /* Add modules to the SynthRack */

    /* Patch the SynthBass to the Output */

    /* Create a sequence */
    linearSlider.slide(1.0, 0.05, 2.0, bass.getOscillator1Detune());
    linearSlider.slide(1.125, 0.05, 1.5, bass.getOscillator1Detune());
    bass.playNote(0.0, 8.0, 0.5, 100);
    bass.playNote(2.5, 6.0, 0.25, 200);

    /* Set duration and press play */
    synthRack.setDuration((double) SCORE_DURATION);

The full code can be seen here. Once I get things sorted out at sourceforge, I’ll post the Python package there as well.

Roll Your Own Score Syntax

A music language that comes with a fully-loaded set of string capabilities, including regular expressions, would allow users to develop their own methods for notating music. For example, here is a horizontal representation for rhythm guitar.

@0  strum('C',  '/... /... /./. /...')
@4  strum('Dm', '/... /... //// /./.')
@8  strum('G7', '/... /... ///. ../.')
@12 strum('C',  '/... /... /... ///.')

The slash triggers an event and advances time by a 16th note. The dot just advances time by a 16th note. A space does nothing.

These 4 lines of code represent 24 events. Not only does this shorten the score and save keystrokes, but is far more readable than if each individual event was explicitly written. In fact, I bet there are many guitar players out there that could play this as it’s written, providing he or she was given a brief explanation about the notation.

What about a system for triggering drums? Here’s the all-to-familiar 4-beat rock pattern with 8th note hats.

trigger(hat(),   'x.x. x.x. x.x. x.x.')
trigger(snare(), '.... x... .... x...')
trigger(kick(),  'x... .... x... ....')

Once again, the music is notated horizontally. Instead of 12 lines of code, there are only 3. Let’s take a look at the vertical equivalent:

@0   hat()
@0   kick()
@0.5 hat()
@1   hat()
@1   snare()
@1.5 hat()
@2   hat()
@2   kick()
@2.5 hat()
@3   hat()
@3   snare()
@3.5 hat()

In theory, people could write slipmat modules that mimic other text-based notation systems, such as the Csound score language.

import CsoundScore as CS
from MyLibrary import bassFM
from MyLibrary import pad

# For mapping slipmat instruments to a Csound-styled score
instrs = {"i1": bassFM(), "i2": pad()}

# A Csound-styled score
score = '''
i 1 0 2 0.5 7.00
i 1 + . .   6.05

i 2 0 8 0.333 8.09 0.77 1000

CS.playScore(instrs, score)  # Play Csound-styled score

That would translate to:

@0 bassFM(2, 0.5, 7.00)
@2 bassFM(2, 0.5, 6.05)
@0 pad(8, 0.333, 8.09, 0.77, 1000)

Much of this can be done with some of the existing music languages out in the wild. The guitar strum and drum trigger examples can be accomplished in pure Csound code (see dseq — A Drum Machine Micro-Language). Even more so, Csound combined with the Python API can do some truly amazing things along these lines. Though it probably wouldn’t be nearly as fluid as a language that had this in mind when being designed from the ground up.

If you haven’t done so yet, take a moment to ponder the possibilities. And be sure to think about the things others will dream up that can be simply imported into your own compositions/synthesizers/sequencers/etc…

Importing Modules and Reusing Code

I want to begin discussing the implications of yesterday’s Python-Csound mockup code (which I’ll refer to as slipmat for the time being), starting with with imports:

import Wavetable
from Gen import sine
from Pitch import cpspch

All of Csound’s 1400+ opcodes are available at all times. Great for convenience, perhaps not so great for organization. In contrast, the Python language starts out with only the basics, a clean slate. To extend functionality, users import modules. This is a cleaner approach than having it all hang out. There are some other advantages, too.

First, let’s look at a hypothetical import block. Let’s say you were to design a “computer network music” ensemble inspired by The Hub. Some communication modules you might include:

import Jack
import MIDI
import Network
import OSC

A computer network music ensemble sounds like it might be a complex piece of software. Complex enough where doing all your work in one file would be tedious. So you decide to start a new file, my_network.slip, where you store your own custom opcode/unit generator function definitions. In your main file, you write this to import:

import my_network

Not only can you use my_network for this project, but that code can be reused in any number of future projects. Code reusability is a beautiful thing. In fact, this would apply to any properly written slipmat document. For example, a composition would double as a library of synthesizers that you could plug into your own work:

import Trapped  # Trapped in Convert by Dr. Richard Boulanger
signal =, 4, 0, 9.01, 600, 0.5, 20, 6, 0.66)

See trapped.csd.

What if Python DNA was Injected into Csound

Last year, I finally weened myself completely off of Perl and learned Python in its place. Colors have never been brighter. There is such an elegance to Python, and I would love to see this in a computer music language.

The following mockup code is what you would get if your combined the awesome powers of Csound with the beauty of Python. I’m taking some liberties. The example is ignorant of i, k and a-rate. Instead of an orchestra/score pair, everything is combined as one file. And I’m introducing a concept for scheduling events, @, which tells when to do something.

#!/usr/bin/env slipmat

import Wavetable
from Gen import sine
from Pitch import cpspch

def sine_arp(dur, amp, pitch, lfo_freq):
    this['dur'] = dur    
    pitch = cpspch(pitch)

    notes = [0, 3, 7, 8]
    arp = Wavetable.osc(1, lfo_freq, notes)
    freq = pitch + pitch * 2 ** (arp / 12.0)
    osc = Wavetable.osc(amp, pitch, sine(1000))
    output osc

def ping(amp=1.0, freq=262):
    this['dur'] = 0.5
    output Wavetable.osc(amp, freq, sine(32))
if __name__ == '__main__':
    def harmonic_pattern(freq=100):
        @0 ping(1.0, freq)
        @1 ping(0.8, freq * 2)
        @2 ping(0.6, freq * 3)
        @3 ping(0.4, freq * 4)
        @4 ping(0.2, freq * 5)
    sine_arp(4, 0.5, 8.00, 1 / 4)
    @4 sine_arp(4, 0.5, 7.07, 1 / 4)
    @8 harmonic_pattern()
    @13 harmonic_patten(cpspch(7.00))
    @18 ping()

I’ll comeback with a commented version of this in a few days. Though unlikely, it is my hope that some of you will take the time to try to figure out what is going on. My philosophy is that code should be human readable, and that syntax can help reinforce this.

On the Up

The Csound community has been making strides to improve the user-experience, and this effort is really beginning to shine through.

Csound now ships with QuteCsound, a new integrated frontend that comes loaded with extras.  The Csound @ Sourceforge page has been given a facelift, in terms of both looks and content.  The developers are taking much greater care to make sure installers work with as few as problems as possible.  This is only the beginning.

If you have tried Csound in the past, but had problems getting up and running, now is a good time to give it another try. If you do run into problems, don’t keep these issues to yourself.  Report them here or the mailing list, and these problems will be taken care of.

Thanks to all the hard work of the developers and others in the community, as it seems that Csound has a promising future.