NodeBox for OpenGL » Sound

NodeBox module nodebox.sound offers a set of convenience classes and functions to work with audio in an animation. Currently, it contains a single PD class.



Pd or PureData ( is a free graphical programming environment for audio processing. Building blocks  can be connected to manipulate audio input, or generate audio output. A network of building blocks is called a "patch", for example:

The /examples/11-sound/ script shows you how to communicate with the above patch:

from import *
from nodebox.sound import PD, LOCALHOST

# start=False means that you must open Pd manually and load the patch.
# This is necessary because we'll use the Pd GUI to control the animation.
pd = PD("02-in-out.pd", start=False)
def draw(canvas):
    data = pd.get("/output", host=LOCALHOST, port=44000)
    if data:
        size, color, angle = data
        translate(250, 250)
        fill(0, color/255.0, 0)
        rect(-size/2, -size/2, size, size)
    pd.send((canvas.mouse.x, canvas.mouse.y), "/input", host=LOCALHOST, port=44001)

def stop(canvas):

canvas.size = 500, 500, stop=stop)


The PD object can be used in NodeBox to create a network connection with PureData. When a patch (i.e. a .pd file) is given and start=True, loads the Pd application with the patch silently in the background. Otherwise, communication can be established with whatever patch is open in a running Pd. The buffer parameter specifies the size in bytes of the audio buffer swapped between NodeBox and Pd. The path parameter defines the location of the PD executable. By default, a number of common locations are searched:

  • the current folder,
  • /usr/local/bin/pd (Unix),
  • /Applications/ (OS X),
  • C:\Program Files\pd\bin\pd.exe (Windows).
pd = PD(patch=None, buffer=128, options={}, start=False, path=DEFAULT)
pd.output                                  # A string of info from Pd, or None.
pd.start()                                 # Starts Pd application in background.
pd.stop() # Returns True on success.
pd.send(data, path, host=LOCALHOST, port=44000)
pd.get(path, host=LOCALHOST, port=44001)
  • PD.get() returns a list of data sent from the given path in Pd.
  • PD.send() sends the given list of data over OSC to Pd.
    The path specifies the address where Pd receives the data e.g. "/creature/perch"

Network host and ports

The default host is LOCALHOST ( but another IP-address can be given. By default, NodeBox will receive data on network port 44000 and send data to Pd on port 44001. This is a convention. In the PureData patch, we'd like you to use port 44000 for sending data and 44001 for receiving data – following the convention makes it easier for other users to see what is happening.

receive data from Pd
send data with sendOSC
send data to Pd
receive data with dumpOSC

Command-line options

Command line options can be passed to the options dictionary in the PD constructor. By default, the dictionary contains {"-nogui": None} to start Pd in the background. Other options can be found here in the Pd documentation.

Stopping Pd

If Pd is started silently in the background, it is essential that it is also stopped when the animation exits! To achieve this, simply call PD.stop() in a Canvas.stop() event - see the example script above.