Skip to content
Port is an Node.js module to communicate and control Pd (Pure Data)
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.


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


Constructor: 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, 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 . Defaults to {}. Array support is deprecated.


Method: Port.create

  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.


Method: Port.destroy

Kills the Pd process and ends all open connections.


Method: Port.write

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');

Method: Port.setOptions

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'

Method: Port.isRunning

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

Method: Port.parseFlags

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

Event: listening

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(){ });

Event: connection

Fires when Pd connects and the read port is specified.

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

Event: connect

Fires when Port connects to Pd on the write port.

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

Event: data

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).

Event: stderr

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.

Event: destroy

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


You can’t perform that action at this time.