LibPd Unity Integration
LibPdIntegration is a wrapper for libpd developed at Abertay University for incorporating Pure Data patches into Unity. It currently supports Windows, OSX, Linux, and iOS (iOS support courtesy thefuntastic).
LibPdIntegration offers a couple of features which set it apart from existing implementations of libpd for Unity:
- It works with recent versions of Unity (at the time of writing, tested on 2018.4 LTS and 2019.4 LTS, though it should work on older versions too).
- It supports multiple instances. This was impossible with previous implementations, as libpd itself did not support running multiple patches side by side. The libpd developers have recently removed that limitation however, meaning LibPdIntegration can allow developers to run multiple Pd patches in their Unity projects. This also means it’s now feasible to build a 3D scene in Unity with multiple Pd patches all spatialised using Unity’s audio code.
This repository contains everything you need to incorporate Pd patches into your Unity project. First download it from the releases page, then copy the contents of the Assets folder into your project’s Assets folder. LibPdIntegration provides native libpd binaries for supported platforms in the Plugins subfolder, and a single C# script, LibPdInstance.cs in the Scripts subfolder.
PD patches should be placed in the StreamingAssets/PdAssets folder (you can create your own subfolders within).
To associate a Pd patch with a Unity GameObject, you need to add a single Lib Pd Instance Component to the GameObject. Doing this will also add an Audio Source Component; this is necessary because Unity does not process audio for GameObjects without an Audio Source.
Lib Pd Instance is our wrapper for libpd. To associate a Pd patch with it, drag the patch from your StreamingAssets/PdAssets folder to the Patch selector in the Inspector.
Note that the order of Components matters. Audio Source must come before Lib Pd Instance.
The Pipe Print To Console toggle provided by Lib Pd Instance lets you pipe any print messages sent by your Pd patch to Unity’s console for debugging purposes. Note that due to a limitation with libpd, this toggle is global. i.e. if you activate it for one Lib Pd Instance, it will be active for all Lib Pd Instances.
Spatialisation of Pure Data patches in Unity is a little convoluted. The following describes a method that does not require any external frameworks, but do check out the Spatialisation page on the wiki if you happen to be using an external audio framework like Steam Audio. The process is a bit more straightforward in that case.
For this method we need to use a special sound file (included in this repository) in our Audio Source, and use an
adc~ object in our PD patch to apply the Audio Source spatialisation to the output of our PD patch.
The necessary steps are:
Set the Audio Source’s AudioClip to our SpatialiserFix.wav sound file.
Ensure the Audio Source is set to Play On Awake and Loop.
Set Spatial Blend to 1(3D).
In Pure Data:
Multiply the output of your patch with the stereo input from an
adc~ object, like the section highlighted in blue here:
This will effectively apply the spatialisation that Unity applies to Audio Sources by default, to the output of our PD patch. For more information, see the LibPdIntegrationExamples project, and particularly the comments in the FilteredNoise-ADC.pd patch.
Only Pure Data Vanilla is supported. Additional objects (externals) included with distributions like Purr Data and Pd-Extended (deprecated) do not currently work. See issue 14 for an explanation of why this is; it will hopefully be resolved in a future release.
Although libpd provides C# bindings, 1.) I could not get them to play nicely with Unity, and 2.) they don’t currently support libpd’s new multiple instance system. As such, LibPdIntegration interfaces directly with the libpd C library. This may change if libpd’s C# bindings get updated in the future, but they should be functionally identical to the C library anyway, so I’m not sure it’s necessary.
readsf~does not work. This is due to a bug in pure data. At the time of writing there’s a pull request that should fix it; once that’s been approved I’ll try and get new libpd binaries built (anyone who can contribute OSX, Linux and iOS binaries please let me know!).
In the meantime, you can work around the problem by using
- Support for more platforms. As libpd itself is provided as a native binary, it needs to be compiled for each platform you plan to deploy to.
- Expand the example project.
- Gallery of projects using LibPdIntegration?
- LibPdIntegration Examples: An example Unity project demonstrating how to use LibPdIntegration.
- LibPdIntegration Tests: Internal project used to verify LibPdIntegration is working correctly.
- black and secret places: A project where myself (Niall Moody) and Yann Seznec are taking turns streaming the audio implementation using Pure Data and LibPdIntegration. You can view the stream playlist here, and if you want to follow along at home you can download releases for each stream from the github page.