LibPDBinding 0.13.0

The C# API for LibPd

Example

The code includes an example of integrating LibPD with NAudio. This example uses LibPD as a custom NAudio.Wave.IWaveProvider.

Instance Class API

Class LibPDBinding.Managed.Pd

This is the main class, and the only one that can be instanciated. It deviates from the C API, because you cannot set the number of channels, sample rate and search paths later.

Constructors

• Pd (int inputChannels, int outputChannels, int sampleRate): Creates a new instance of Pd with the specified number of input and output channels with the specified sample rate.
• Pd (int inputChannels, int outputChannels, int sampleRate, IEnumerable<string> searchPaths): Creates a new instance of Pd with the specified number of input and output channels with the specified sample rate, and adds the specified paths to search for patches and externals.

Audio Processing

• Start (): Starts audio processing.
• Stop (): Stops audio processing.
• Process (int ticks, short[] inBuffer, short[] outBuffer), Process (int ticks, float[] inBuffer, float[] outBuffer), Process (int ticks, double[] inBuffer, double[] outBuffer): Reads samples from the input buffer, processes them for the specified number of ticks, and writes the output to the output buffer. The input buffer must be at least of size [InputChannels] * [Blocksize] * [ticks], output buffer least of size [OutputChannels] * [Blocksize] * [ticks].

Other Properties And Methods

• Inputs {get;}: Gets the number of input channels.
• Outputs {get;}: Gets the number of output channels.
• SampleRate {get;}: Gets the sample rate.
• Blocksize {get;}: Gets the blocksize.
• Messaging {get;}: Gets the instance of [Messaging] for this instance.
• Midi {get;}: Gets the instance of [Midi] for this instance.
• IsComputing {get;}: Returns true, iff audio computing is started.
• LoadPatch (string path): Loads a patch in Pd. If no file is found at the specified path, this instance will return null.
• GetArray (string name): Gets an array in Pd.

Class LibPDBinding.Managed.Patch

This class is used to manage Pd patches. A patch can be loaded by calling LoadPatch (string path) on an instance of Pd. Keep the instance, otherwise the GC may call Dispose () and therefore close the patch.

• DollarZero {get;}: Gets $0 of the patch.
• Dispose (): Closes the patch.

Class LibPDBinding.Managed.Messaging

An instance of this class is available as a property of an instance of Pd.

Sending Data

If exactly one IAtom is sent with the Send () overloads, then this atom is converted to a single symbol or float message in Pd, else a list message is sent.

• Send (string receiver, string message, params IAtom[] atoms): Sends a general message to the specified receiver with a range of atoms.
• Send (string receiver, params IAtom[] atoms): Sends a message to the specified receiver with a range of atoms.
• Send (string receiver, Bang bang): Sends a bang message to the specified receiver.

Binding And Unbinding to Receivers

• Bind (string receiver): Sets this instance to receive messages to the specified receiver.
• Unbind (string receiver): Unsets this instance to receive messages to the specified receiver.

Events

• Print: Occurs, when print is called in Pd.
• Bang: Occurs, when a bang is received on a subscribed receiver.
• Float: Occurs, when a float message is received on a subscribed receiver.
• Symbol: Occurs, when a symbol message is received on a subscribed receiver.
• List: Occurs, when a list message is received on a subscribed receiver.
• Message: Occurs, when a general message is received on a subscribed receiver.

Class LibPDBinding.Managed.PdArray

This class is used to access Pd arrays. An array can be accessed by calling GetArray (string name) on an instance of Pd.

• Name {get;}: Gets the name of Pd array.
• Size {get;}: Gets the size of the Pd array.
• Read (int start, int length): Reads values from the Pd array starting from the specified start for the specified length.
• Write (float[] newContent, int start, int length): Writes the values of the specified new content to the Pd array starting from the specified start for the specified length.
• Resize (int length): Resizes the Pd array.

Class LibPDBinding.Managed.Midi

An instance of this class is available as a property of an instance of Pd.

Sending Data

• SendNoteOn (int channel, int pitch, int velocity)
• SendProgramChange (int channel, int value)
• SendControlChange (int channel, int controller, int value)
• SendPitchbend (int channel, int value)
• SendAftertouch (int channel, int pitch, int velocity)
• SendPolyAftertouch (int channel, int pitch, int velocity)
• SendMidiByte (int port, int value)
• SendSysex (int port, int value)

Events

• NoteOn
• ProgramChange
• ControlChange
• Pitchbend
• Aftertouch
• PolyAftertouch
• MidiByte

Static Class API (Obsolete)

The low level C API has been abstracted into the static class LibPdBinding.LibPd. All methods are static methods on that class, properties are static properties.

Opening and Closing Patches

• public static void ReInit(): Reinitializes LibPD. It is called automatically on startup and is usually not needed.
• public static void AddToSearchPath(string sym): Adds sym to the Pd search path.
• public static void ClearSearchPath(): Clears the Pd search path. Is usually not needed.
• public static int OpenPatch(string filepath): Opens a patch and returns $0 for that patch. May throw exceptions, if the file does not exist or no handle is returned from LibPD.
• public static bool ClosePatch(int p): Closes the patch with $0 == p.

Audio Processing

• public static int BlockSize: Gets the blocksize of Pd (default: 64).
• public static int OpenAudio(int inputChannels, int outputChannels, int sampleRate): Initializes audio rendering for the specified number of input and output channels and the sample rate. The method returns 0 iff audio initialization succeeds.
• public static void ComputeAudio(bool state): Turns Pd audio computation on and off.
• public static int Process(int ticks, short[] inBuffer, short[] outBuffer), public static int Process(int ticks, float[] inBuffer, float[] outBuffer), public static int Process(int ticks, double[] inBuffer, double[] outBuffer): Read one buffer of input samples from inBuffer, process them with Pd, and write one buffer of output samples to outBuffer. In order to reduce the overhead of functions calls, libpd offers the option of processing more than one Pd tick per audio rendering call. For minimal latency, choose one tick. If you run into performance issues, try a larger number. The size of each buffer must be the product of the number of channels, the number of ticks, and the number of samples per tick. (The number of samples per tick is the value returned by Blocksize, i.e., 64.) Samples will be interleaved in the buffer, i.e., if there are two input channels, then inBuffer[0] is the first sample for the left channel, inBuffer[1] is the first sample for the right channel, inBuffer[2] is the second sample for the left channel, etc. The return value is 0 if and only if the call succeeded.
• public static int ProcessRaw(float[] inBuffer, float[] outBuffer): Process one Pd tick and copy the contents of the buffers directly to/from Pd, without striping.

Sending Messages to Pd

• public static int SendMessage(string receiver, string message, params object[] args): Sends message to receiver in Pd.
• public static int SendList(string receiver, params object[] args): Sends a list message to a receiver in Pd.
• public static int SendBang(string recv), public static int SendFloat(string recv, float x), public static int SendSymbol(string recv, string sym): Send bang, float and symbol messages to recv.

Receiving Messages from Pd

Before receiviong messages, you must subscribe to the correspondents receiver. Pd will then emit events, that include the receiver as first parameter.

• public static bool Subscribe(string sym): Subscribes to messages on receiver sym. This method returns true, if subscription was successful.
• public static bool Unsubscribe(string sym): Unsubscribes from messages on receiver sym. This method returns true, if unsubscription was successful.
• public static event LibPDPrint Print: Delegate for Pd print messages, defined by public delegate void LibPDPrint(string text)
• public static event LibPDBang Bang: Delegate for Pd bang messages, defined by public delegate void LibPDBang(string recv), where recv is the subscribed receiver name.
• public static event LibPDFloat Float: Delegate for Pd float messages, defined by public delegate void LibPDFloat(string recv, float x), where recv is the subscribed receiver name, and x is the float value.
• public static event LibPDSymbol Symbol: Delegate for Pd symbol messages, defined by public delegate void LibPDSymbol(string recv, string sym), where recv is the subscribed receiver name, and sym is the symbol value.
• public static event LibPDList List: Delegate for Pd list messages, defined by public delegate void LibPDList(string recv, object[] args), where recv is the subscribed receiver name, and args is the list value as an array of floats and strings.
• public static event LibPDMessage Message: Delegate for Pd bang messages, defined by public delegate void LibPDMessage(string recv, string msg, object[] args), where recv is the subscribed receiver name, msg is the name of the message and args the list value as an array of floats and strings.

Accessing Arrays in Pd

• public static int ArraySize(string name): Gets the size of the array name.
• public static int ReadArray(float[] destination, string source, int srcOffset, int n): Reads values from Pd array source into destination. srcOffset is the offset of values in the Pd array, n the number of values to read. Returns 0 on success. Will return a negative error code if the array in Pd does not exist or if the range given by n and srcOffset exceeds the range of the array.
• public static int WriteArray(string destination, int destOffset, float[] source, int n): Writes values from source into Pd array destination. destOffset is the offset of values in the Pd array, n the number of values to read. Returns 0 on success. Will return a negative error code if the array in Pd does not exist or if the range given by n and destOffset exceeds the range of the array.