Port
A Node.js module to spawn and communicate with Pure Data (aka Pd).
Example
var port = ; ;
Install
npm install port
API
Constructor: Port
var Port = ; var pd = options;
The new
keyword is optional.
Options
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.
Methods
Method: Port.create
- Spawns the Pd process.
- Listens for an incoming socket connection.
- Connects to on the write port.
Each of the 3 steps are individually executed depending on the configuration.
pd;
Method: Port.destroy
Kills the Pd process and ends all open connections.
pd;
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;
Method: Port.setOptions
Reconfigure an instance, changes only take effect after destroy and create methods have been called.
Arguments
- Data (object) - set configuration on an existing instance.
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.
Events
Port is an event emitter see also nodejs.org/api/events.html
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;
Event: connection
Fires when Pd connects and the read
port is specified.
pd;
Arguments
- Socket (object) - Exposes the socket connection from [netsend].
Event: connect
Fires when Port connects to Pd on the write port.
pd;
Arguments
- Socket (object) - Exposes the socket connection to [netreceive].
Event: data
Fires when Pd sends a message with [netsend].
pd;
Arguments
- 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;
Arguments
- Buffer - the stderr buffer object.
Event: destroy
Fires after the destroy method is called.
pd;
Tests
If tests fail, the child process may be manually terminated with killall pd
.
make test
Examples
Some examples are only proof of concept and are not optimized for best performance.
node examples/testing/division.js node examples/manipulation/server.js
Requires
- Vanilla Pure Data from crca.ucsd.edu/~msp/software.html or Pd-extended from puredata.info/downloads.
- Node.js from nodejs.org.