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
  • Objects
  • pd : object
  • Patch : object
• 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, computeAudio) ⇒ 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, computeAudio) ⇒ 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

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.computeAudio(compute)

Ask pd to compute audio.

Kind: static method of pd

pd.getDevicesCount() ⇒ Object

Get system's audio devices count.

Kind: static method of pd

pd.listDevices() ⇒ Object

Lists system's audio devices.

Kind: static method of pd

pd.getDefaultInputDevice() ⇒ Object

Get default input audio device.

Kind: static method of pd

pd.getDefaultOutputDevice() ⇒ Object

Get default output audio device.

Kind: static method of pd

pd.getInputDevices() ⇒ Object

Get input audio devices.

Kind: static method of pd

pd.getOutputDevices() ⇒ Object

Get output audio devices.

Kind: static method of pd

pd.getDeviceAtIndex(index) ⇒ Object

Get device at given index.

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

pd.closePatch(patch)

Close a pd patch instance.

Kind: static method of pd

pd.addToSearchPath(pathname)

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

Kind: static method of pd

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

pd.subscribe(channel, callback)

Subscribe to named events send by a pd patch

Kind: static method of pd

pd.unsubscribe(channel, [callback])

Unsubscribe to named events send by a pd patch

Kind: static method of pd

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

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

pd.clearArray(name, [value])

Fill a pd array with a given value.

Kind: static method of pd

pd.arraySize(name) ⇒ Number

Retrieve the size of a pd array.

Kind: static method of pd
Returns: Number - size of the array

pd.startGUI(path) ⇒ Object

Starts Pure Data GUI if Pure Data is present on the system.

Kind: static method of pd

pd.pollGUI() ⇒ Object

Function to be called to update GUI and handle its messages. Use in a setInterval for example.

Kind: static method of pd

pd.stopGUI() ⇒ Object

Closes Pure Data GUI.

Kind: static method of pd

Patch : object

Object representing a patch instance.

Kind: global namespace

• Patch : object
  • .$0 : Number
  • .isValid : Boolean
  • .filename : String
  • .path : String

Patch.$0 : Number

Id of the patch. You should use this value to communicate with a given patch in send and receive channel.

Kind: static property of Patch
Read only: true

Patch.isValid : Boolean

Validity of the patch instance. False typically means that the given filename does not point to a valid pd patch, or that the patch has been closed.

Kind: static property of Patch
Read only: true

Patch.filename : String

Name of the the pd patch file

Kind: static property of Patch
Read only: true

Patch.path : String

Directory of the pd patch file

Kind: static property of Patch
Read only: true

Tests

To run the tests

# cf. test/index.js
npm run test

Todos

• ~~list devices~~ and choose device, is a portaudio problem
• midi event ? is there some real-world use case
• support pd externals, if only possible...
• rebuild portaudio without jack on linux

Credits

The library has received support from the Ircam's project BeCoMe.

License

BSD-3-Clause