Spawn Pd (Pure Data) and communicate through TCP sockets


A Node.js module to spawn and communicate with Pure Data (aka Pd).

var port = require('port');
    'read': 8004,
    'write': 8005,
    'basepath': __dirname,
    'flags': {
        'nogui': true,
        'stderr': true,
        'send': 'pd dsp 1, dsp 0',
        'path': 'relative/to/basepath',
        'open': 'patch.pd'
.on('connect', function(){
    this.write('Hello [netreceive]!;\n');
.on('data', function(data){
    console.log('data receiving from [netsend]', data);
.on('stderr', function(buffer){
npm install port
var Port = require('port');
var pd = new Port(options);

The new keyword is optional.

  • host - (string) The domain of the Pd process. Defaults to localhost.
  • read - (number | null) The port to listen to Pd's [netsend]. Defaults to null.
  • write - (number | null) The port to connect to Pd's [netreceive]. Defaults to null.
  • encoding - (ascii | utf8 | base64 | hex | null) The encoding of the read and write socket, nodejs.org/api/stream.html#stream_stream_setencoding_encoding Defaults to null.
  • max - (number) Limits amount of incoming connections. Defaults to 1.
  • basepath - (string) -path flags are relative to basepath. Supports only flags object, but not flags array.
  • pd - (string) The command or location to spawn the Pd process. Defaults to an absolute path to the Pd binary on OS X. Defaults to 'pd' on Linux.
  • debug - (boolean) log parsed startup flags before spawning Pd.
  • flags - (object) The command line arguments for the Pd process. Expects an object of arguments. Read more about Pd's configuration flags on crca.ucsd.edu/~msp/Pd_documentation/x3.htm#s4 . Defaults to {}. Array support is deprecated.
  1. Spawns the Pd process.
  2. Listens for an incoming socket connection.
  3. Connects to on the write port.

Each of the 3 steps are individually executed depending on the configuration.


Kills the Pd process and ends all open connections.


Sends a packet containing one or many messages to Pd's [netreceive].

WARNING: write does not check if the write socket is ready and may error!

pd.write('Hello Pd!;\n');

Reconfigure an instance, changes only take effect after destroy and create methods have been called.

  1. Data (object) - set configuration on an existing instance.
    'read': 12345,
    'write': 12346,
    'basepath': __dirname,
    'flags': {
        'noprefs': true,
        'nogui': true,
        'stderr': true,
        'path': 'relatvie/path/to/dir',
        'open': 'patch.pd'

Returns true when the instance is connected and it is safe to send data with the write method.

Internal method, eventually useful for debugging. Turns flags object into an array. Adds dash prefix, omits flags that are falsy, supports path array, ensures -path and -open to be at the last position.

Port is an event emitter see also nodejs.org/api/events.html

Fires if the read port is specified and after Port.create is called. At this point Port is waiting for an incoming TCP connection from Pd's [netsend].

pd.on('listening', function(){ });

Fires when Pd connects and the read port is specified.

pd.on('connection', function(socket){ });
  1. Socket (object) - Exposes the socket connection from [netsend].

Fires when Port connects to Pd on the write port.

pd.on('connect', function(socket){ });
  1. Socket (object) - Exposes the socket connection to [netreceive].

Fires when Pd sends a message with [netsend].

pd.on('data', function(data){ });
  1. Data - a buffer object or a string (if encoding is not null).

Fires on every message that is written to the console the [print] object or anything else. This event is only available with -stderr or -nogui flag.

pd.on('stderr', function(buffer){ });
  1. Buffer - the stderr buffer object.

Fires after the destroy method is called.

pd.on('destroy', function(){ });

If tests fail, the child process may be manually terminated with killall pd.

make test

Some examples are only proof of concept and are not optimized for best performance.

node examples/testing/division.js
node examples/manipulation/server.js