ofxPd

<p align="center"> <img src="https://raw.github.com/danomatika/ofxPd/master/ofxaddons_thumbnail.png"/> </p>

Copyright (c) Dan Wilcox 2011-2023

BSD Simplified License.

For information on usage and redistribution, and for a DISCLAIMER OF ALL WARRANTIES, see the file, "LICENSE.txt," in this distribution.

See https://github.com/danomatika/ofxPd for documentation as well as the OF forum post on ofxPd

This project has been supported by the CMU Frank-Ratchye STUDIO for Creative Inquiry, the DU Emergent Digital Practices Program, and my time at the ZKM | Hertz-Lab.

Description

ofxPd is an Open Frameworks addon for running an instance of the Pure Data audio environment within an openFrameworks application. Audio, messages, and MIDI events can be passed to and from pure data patches and the library is thread safe.

Pure Data is a graphical patching environment for audio and multimedia (note: the gui and graphics features are not within the scope of this addon)

openFrameworks is a cross platform open source toolkit for creative coding in C++

Build Requirements

To use ofxPd, first you need to download and install Open Frameworks. Development is against the latest version of Open Frameworks on github. Checkout a tag if you need an earlier, stable version.

OF github repository

On macOS, you will need to install Xcode.

On Linux, you can use the Makefile.

On Windows, Qt Creator/Msys2 are recommended as the libpd sources do not currently build in Visual Studio. However, you can use a libpd.dll built by MinGW in a Visual Studio project. See the "Using ofxPd with Visual Studio" section below.

Installation

Place ofxPd within a folder in the apps folder of the OF dir tree:

openframeworks/addons/ofxPd

The easiest way to do this is via cloning with git:

cd openframeworks/addons/
git clone git://github.com/danomatika/ofxPd.git

Which version to use?

The master branch of ofxPd will work with the current stable version of openFrameworks and can be considered relatively stable.

Previous versions are tagged using Semantic Versioning with the updates to newer versions of openFrameworks and libpd noted in the changelog, CHANGES.txt. You can select the tag in the Github "Current Branch" menu or clone and check it out using git.

If you want to use ofxPd with a previous version of openFrameworks, checkout the corresponding version tag after cloning:

git clone git://github.com/danomatika/ofxPd.git
cd ofxPd
git checkout 1.5.3

Running the Example Projects

The example projects are in the pdExample & pdExampleIOS folders.

Project files for the examples are not included so you will need to generate the project files for your operating system and development environment using the OF ProjectGenerator which is included with the openFrameworks distribution.

To (re)generate project files for an existing project:

• Click the "Import" button in the ProjectGenerator
• Navigate to the project's parent folder ie. "ofxPd", select the base folder for the example project ie. "pdExample", and click the Open button
• Click the "Update" button

If everything went Ok, you should now be able to open the generated project and build/run the example.

Notes for iOS Projects

• As of iOS 10+, you will need to manually add a NSMicrophoneUsageDescription string to the project's info plist or the app will crash immediately:
  1. Click on the blue project at the top of the Xcode file tree (ie. something like "pdExampleIOS"
  2. Click the "Info" tab in the top/middle
  3. Under "Custom iOS Target Properties", hover over the last key in the list and click the "+" button
  4. Add the following:
  • Key: NSMicrophoneUsageDescription
  • Type: string
  • Value: a description string for the app like, ie. "This app needs to use the microphone for bla bla..."
• If you use the OF release zips from openFrameworks.cc, you need the iOS zip not the macOS zip
• Make sure that "iOS (Xcode)" is selected in the PG's "Platforms" box

pdMultiExample & Multiple Instance Support

This special example demonstrates ofxPd's multiple-instance support, where you can run multiple separate instances of libpd concurrently.

To build and run this example, the following C and C++ flags must be set: -DPDINSTANCE & -DPDTHREADS. If these are not set, the example will exit early with an error.

Makefile

For Makefile builds, these are set in pdMultiExample/config.make.

Project Generator

For project files which are created with the Project Generator (ie. Xcode), uncomment the line in addons_config.mk under the common target, save, then (re)generate the project with the PG.

Xcode

The defines can be added manually to the Xcode projects build settings: Other C Flags & Other C++ Flags.

PitchShifter

PitchShifter is a simple example application which uses an OF GUI to control a pitch shifter within a PD patch. Like the basic example, you will have to generate the project files using the ProjectGenerator.

How to Create a New ofxPd Project

Note: These instructions are for manually creating a new project from an existing ofxPd project and it's project files (aka Xcode, C::B, etc). You do not need to follow these steps if you use the ProjecGenerator app in which case you may need to add the C Flags as the PG currently seems to have a problem doing this. See the IDE specific instructions on how to do this.

To develop your own project based on ofxPd, either generate a new project with the ProjectGenerator or generate one of the examples, copy, and rename it. You probably want to put it in your apps folder, for example, after copying:

openFrameworks/addons/ofxPd/pdExample/ => openFrameworks/apps/myApps/pdExample/

It must be 3 levels down in the openFrameworks folder structure.

Then after renaming:

openFrameworks/apps/myApps/myPdProject/

For Xcode:

Rename the project in Xcode (do not rename the .xcodeproj file in Finder!): Xcode Menu->Project->Rename

Adding ofxPd to an Existing Project

Note: These instructions are for manually add ofxPd to an existing project. You do not need to follow these steps if you use the ProjecGenerator app in which case you may need to add the C flags as the PG currently seems to have a problem doing this. See the IDE specific instructions on how to do this.

If you want to add ofxPd to another project, you need to make sure you include the src folder:

openFrameworks/addons/ofxPd/src

You will also need to include some additional C flags for building the libpd source:

-DPD -DUSEAPI_DUMMY -DPD_INTERNAL -DHAVE_UNISTD_H -DHAVE_ALLOCA_H -DLIBPD_EXTRA

Note: -DLIBPD_EXTRA is optional if you do not need/use the externals in libpd/pure-data/extra

If you want to build ofxPd with the libpd experimental libpd multi-instance support (ie. for pdMultiExample), add these C flags as well:

-DPDINSTANCE -DPDTHREADS

For Xcode:

Additional C flags are needed per-platform:

• macOS: -DHAVE_LIBDL -DHAVE_MACHINE_ENDIAN_H -D_DARWIN_C_SOURCE

• iOS: -fcommon -DHAVE_MACHINE_ENDIAN_H -D_DARWIN_C_SOURCE

• Create a new group "ofxPd"

• Drag these directories from ofxPd into this new group: ofxPd/src

• Add a search path to: ../../../addons/ofxPd/libs/libpd/pure-data/src under Targets->YourApp->Build->Header Search Paths (make sure "All" is selected)

• Under Targets->YourApp->Build->Other C Flags (make sure "All" is selected), add

  <pre>-DPD -DUSEAPI_DUMMY -DPD_INTERNAL -DHAVE_UNISTD_H -DHAVE_ALLOCA_H -DLIBPD_EXTRA</pre>

  and the additional C flags noted above

  • Note: Make sure you use Other C Flags! Other C++ Flags will not work since libpd is written in C.

• Under Other C++ Flags, add

  <pre>-DHAVE_UNISTD_H=1</pre>

For Linux (Makefiles):

Edit addons.make in your project folder and add the following line to the end of the file: <pre>ofxPd</pre>

Using ofxPd with Visual Studio

Visual Studio only

As of spring 2020, the libpd sources should build directly in new versions of Visual Studio. Also, ofxPd projects use the included 64 bit copy of libwinpthread-1.dll used for the Msys2/MinGW build, so everything should be included.

Note: This has not been directly confirmed with OF & ofxPd. (At least no one has told me.) If you mainly use VS, try this first before building the libpd.dll via Msys2/MinGW.

Build libpd.dll with MinGW & use with Visual Studio

In order to use libpd with ofxPd in a Visual Studio project, you need a libpd.lib and libpd.dll libraries built using MinGW (Minimal GNU for Windows) which provides a Unix command shell and compiler.

You can check if there is a pre-compiled libpd for ofxPd available here:

http://docs.danomatika.com/releases/ofxPd/

If so, skip to the "Adding libpd" section, otherwise follow the steps below to set up a build environment and build libpd.

Building libpd with Msys2/MinGW

The steps for 64 bit are basically:

1. Set up Msys2/MinGW: see https://github.com/libpd/libpd#windows

• Make sure to follow all steps in the Msys2 setup instructions, ie. updating packages after install

2. Open an Msys2 shell (64 bit)
3. Build libpd: make
4. Install libpd to a temp folder: make install prefix=build/libpd

Adding libpd to a Visual Studio project

Replace the libpd source code in ofxPd with the libpd headers and library files:

1. Delet