`node-libpd`

Node.js bindings for libpd using portaudio as audio backend.

Install

npm install [--save] node-libpd

Table of Content

Basic Usage
Notes / Caveats:
- Install on Mac OSX
- Install on Raspberry Pi
API
Tests
Todos
Credits
License

Basic Usage

const pd = require('node-libpd');
// or if you use some transpiler such as babel
// import pd from 'node-libpd';

// init pd
const initialized = pd.init({
  numInputChannels: 0,
  numOutputChannels: 2,
  sampleRate: 48000,
  ticks: 1, // a pd block (or tick) is 64 samples, be aware that increasing this value will throttle messages (tbc)
});

// instantiate a patch
const patchPathname = path.join(process.cwd(), 'pd', 'my-patch.pd');
const patch = pd.openPatch(patchPathname);

// subscribe to messages from the patch
pd.subscribe(`${patch.$0}-output`, msg => {
  console.log(msg);
});

// send message to the patch
pd.send(`${patch.$0}-input`, 1234);

// send a scheduled message
const now = pd.currentTime; // time in sec.
// send message to the patch in two seconds from `now`, this accuracy of the
// scheduling will depend on the number of ticks defined at initialization
pd.send(`${patch.$0}-input`, 1234, now + 2);

// close the patch
pd.closePatch(patch);

Notes / Caveats:

The library is meant to be used in a Node.js environment, it cannot run in a browser and never will.
The library can only be used with pd-vanilla objects, it does not, and maybe will never, support externals.
The audio interface used is the one that is set as default system wise.
The bindings are created with N-API, therefore v1 should work on Node.js > 10.x.x, for previous version of Node.js you should install node-libpd v0.2.6 that was created with Nan (be aware that this version won't receive support).
The library does not support all the interface of libpd, however the most important ones should be there. The API has also been adapted at particular places to match common JS idiomatisms.

Tested on MAC OSX 10 and Raspbian Stretch Lite version 9 (raspberry pi 3) - for other platforms, dynamic libraries for libpd and portaudio should probably be built.

Install on Mac OSX

xcode-select --install

Install on Raspberry Pi

apt-get install -y ... ???

API

Objects

pd : object: Singleton that represents an instance of the underlying libpd library
Patch : object: Object representing a patch instance.

pd : `object`

Singleton that represents an instance of the underlying libpd library

Kind: global namespace

pd : object
- .currentTime : Number
- .init(config) ⇒ Boolean
- .destroy()
- .openPatch(pathname) ⇒ Object
- .closePatch(patch)
- .addToSearchPath(pathname)
- .clearSearchPath()
- .send(channel, value, [time])
- .subscribe(channel, callback)
- .unsubscribe(channel, [callback])
- .writeArray(name, data, [writeLen], [offset]) ⇒ Boolean
- .readArray(name, data, [readLen], [offset]) ⇒ Boolean
- .clearArray(name, [value])
- .arraySize(name) ⇒ Number

pd.currentTime : `Number`

Current audio time in seconds since init as been called.

Kind: static property of pd
Read only: true

pd.init(config) ⇒ `Boolean`

Configure and initialize pd instance. You basically want to do that at the startup of the application as the process is blocking and that it can take a long time to have the audio running.

Kind: static method of pd
Returns: Boolean - a boolean defining if pd and portaudio have been properly initialized

Param	Type	Default	Description
config	`Object`
[config.numInputChannels]	`Number`	`1`	num input channels requested
[config.numOutputChannels]	`Number`	`2`	num output channels requested
[config.sampleRate]	`Number`	`4800`	requested sampleRate
[config.ticks]	`Number`	`1`	number of blocks (ticks) processed by pd in one run, a pd tick is 64 samples. Be aware that this value will affect / throttle the messages sent to and received by pd, i.e. more ticks means less precision in the treatement of the messages. A value of 1 or 2 is generally good enough even in constrained platforms such as the RPi.

pd.destroy()

Destroy the pd instance. You basically want to do that want your program exists to clean things up, be aware the any call to the pd instance after calliing destroy migth throw a SegFault error.

Kind: static method of pd

pd.openPatch(pathname) ⇒ `Object`

Open a pd patch instance. As the same patch can be opened several times, think of it as a kind of poly with a nice API, be careful to use patch.$0 in your patches.

Kind: static method of pd
Returns: Object - - instance of the patch

Param	Type	Description
pathname	`String`	absolute path to the pd patch

pd.closePatch(patch)

Close a pd patch instance.

Kind: static method of pd

Param	Type	Description
patch	`Patch`	a patch instance as retrived by `openPatch`

pd.addToSearchPath(pathname)

Add a directory to the pd search paths, for loading libraries etc.

Kind: static method of pd

Param	Type	Description
pathname	`String`	absolute path to the directory

pd.clearSearchPath()

Clear the pd search path

Kind: static method of pd

pd.send(channel, value, [time])

Send a named message to the pd backend

Kind: static method of pd

Param	Type	Description
channel	`String`	name of the corresponding `receive` box in the patch the avoid conflict a good practice is the prepend the channel name with `patch.$0`
value	`Any`	payload of the message, the corresponding mapping is made with pd types: Number -> float, String -> symbol, Array -> list (all value that neither Number nor String are ignored), else -> bang
[time]	`Number`	audio time at which the message should be sent. If null or < currentTime, is sent as fast as possible. (@tbc messages are processed at pd control rate).

pd.subscribe(channel, callback)

Subscribe to named events send by a pd patch

Kind: static method of pd

Param	Type	Description
channel	`String`	channel name corresponding to the pd send name
callback	`function`	callback to execute when an event is received

pd.unsubscribe(channel, [callback])

Unsubscribe to named events send by a pd patch

Kind: static method of pd

Param	Type	Default	Description
channel	`String`		channel name corresponding to the pd send name
[callback]	`function`		callback that should stop receive event. If null, all callbacks of the channel are removed

pd.writeArray(name, data, [writeLen], [offset]) ⇒ `Boolean`

Write values into a pd array. Be carefull with the size of the pd arrays (default to 100) in your patches.

Kind: static method of pd
Returns: Boolean - true if the operation succeed, false otherwise

Param	Type	Default	Description
name	`Name`		name of the pd array
data	`Float32Array`		Float32Array containing the data to be written into the pd array.
[writeLen]	`Number`	`data.length`	@todo confirm behavior
[offset]	`Number`	`0`	@todo confirm behavior

pd.readArray(name, data, [readLen], [offset]) ⇒ `Boolean`

Read values into a pd array.

Kind: static method of pd
Returns: Boolean - true if the operation succeed, false otherwise

Param	Type	Default	Description
name	`Name`		name of the pd array
data	`Float32Array`		Float32Array to populate from pd array values
[readLen]	`Number`	`data.length`	@todo confirm behavior
[offset]	`Number`	`0`	@todo confirm behavior