https://github.com/thisconnect/port
Port is an Node.js module to communicate and control Pd (Pure Data)
https://github.com/thisconnect/port
Last synced: 7 months ago
JSON representation
Port is an Node.js module to communicate and control Pd (Pure Data)
- Host: GitHub
- URL: https://github.com/thisconnect/port
- Owner: thisconnect
- License: mit
- Created: 2011-08-22T20:41:58.000Z (over 14 years ago)
- Default Branch: master
- Last Pushed: 2015-02-12T07:14:59.000Z (almost 11 years ago)
- Last Synced: 2025-05-14T18:56:22.007Z (8 months ago)
- Language: JavaScript
- Homepage:
- Size: 3.71 MB
- Stars: 37
- Watchers: 4
- Forks: 8
- Open Issues: 7
-
Metadata Files:
- Readme: readme.md
- License: license
Awesome Lists containing this project
README
# Port
A Node.js module to spawn and communicate with Pure Data (aka Pd).
Example
-------
```js
var port = require('port');
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){
console.log(buffer.toString());
})
.create();
```
Install
-------
```bash
npm install port
```
API
---
### Constructor: Port
```js
var Port = require('port');
var pd = new Port(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](http://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](http://crca.ucsd.edu/~msp/Pd_documentation/x3.htm#s4) .
Defaults to {}. Array support is deprecated.
Methods
-------
### 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.
```js
pd.create();
```
### Method: Port.destroy
Kills the Pd process and ends all open connections.
```js
pd.destroy();
```
### 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!
```js
pd.write('Hello Pd!;\n');
```
### Method: Port.setOptions
Reconfigure an instance, changes only take effect after destroy and create methods have been called.
##### Arguments
1. Data (object) - set configuration on an existing instance.
```js
pd.setOptions({
'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.
Events
------
Port is an event emitter see also
[nodejs.org/api/events.html](http://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].
```js
pd.on('listening', function(){ });
```
### Event: connection
Fires when Pd connects and the `read` port is specified.
```js
pd.on('connection', function(socket){ });
```
##### Arguments
1. Socket (object) - Exposes the socket connection from [netsend].
### Event: connect
Fires when Port connects to Pd on the write port.
```js
pd.on('connect', function(socket){ });
```
##### Arguments
1. Socket (object) - Exposes the socket connection to [netreceive].
### Event: data
Fires when Pd sends a message with [netsend].
```js
pd.on('data', function(data){ });
```
##### Arguments
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.
```js
pd.on('stderr', function(buffer){ });
```
##### Arguments
1. Buffer - the stderr buffer object.
### Event: destroy
Fires after the destroy method is called.
```js
pd.on('destroy', function(){ });
```
Tests
-----
If tests fail, the child process may be manually terminated with `killall pd`.
```bash
make test
```
Examples
--------
Some examples are only proof of concept and are not optimized for best performance.
```bash
node examples/testing/division.js
node examples/manipulation/server.js
```
Requires
--------
- Vanilla Pure Data from
[crca.ucsd.edu/~msp/software.html](http://crca.ucsd.edu/~msp/software.html)
or Pd-extended from [puredata.info/downloads](http://puredata.info/downloads).
- Node.js from [nodejs.org](http://nodejs.org/).