ObjC

libpd has moved to GitHub: https://github.com/libpd

libpd project setup

These steps will show you how to set up a new Xcode project with libpd.

In order to set up Pd for iOS, open a shell, go to the directory where you want to put your Android projects, and perform the following steps:

git clone git://gitorious.org/pdlib/pd-for-ios.git
cd pd-for-ios  
git submodule init  
git submodule update

Xcode 4:

  • drag the libpd.xcodeproj file from the Finder into your project (drop it in the Project Navigator pane on the left)
  • go to project settings by clicking on your project’s blue icon, then select the main target of your app under “Targets”
  • under “Build Phases”, then “Target Dependencies”, click the plus icon and add libpd
  • under “Build Phases”, then “Link Binary With Libraries”, click the plus icon to choose the frameworks/libraries we need to add. Add libpd.a and AudioToolbox.framework.
  • under “Build Settings”, find the entry “Header Search Paths”. Add a recursive entry for your base libpd directory (most likely pd-for-ios/libpd).

That’s it. You should then be able to #import “PdAudio.h” and instantiate it as an object within your App Delegate or anywhere else in your project.

Xcode 3:

  • Ctrl-click on your project file in ‘Groups & Files’, select ‘Add->Existing File’
  • navigate to the libpd directory and select the libpd.xcodeproj file, the sub-project should now be in your list of files for the project
  • Right-click on your project’s target and select ‘Get Info’. Under the ‘General’ tab, select the plus marker under ‘Direct Dependencies’ – add libpd
  • still under the target properties, go to the ‘Build’ tab and search for ‘Header Search Paths’. Recursively add the libpd root folder so that xcode can find whatever files the libpd xcode project needs.
  • If you want to be able to ctrl-click on a method defined in the libpd subproject, you have to also add the same path from the last step to your ‘Header Search Paths’ within the ‘Project Info->build’ tab, (ctrl-click on your project to find it).
  • Ctrl-click on the ‘Groups & Files’ Header (right above your project file name' and enable ‘Target Membership’
  • a bunch of checkmarks should pop up next to all the files that will be added to your target – add the libpd.a file that appeared under the libpd.xcodeproj heirarchy
  • you should now be able to build your main project and it will detect that libpd.a still needs to be build, and build it.

Libpd Sample Projects for iOS

Some sample projects are provided in the folder pd-for-ios. These demonstrate basic functions of using Libpd on iOS.

PdTest01 – is a very simple Universal iPhone/Pad app that demonstrates using Libpd to load and run a Pd patch file. PdTest01 uses the mic input and outputs stereo audio.
Note: Unfortunately, PdTest01 does not currently run properly on older iOS devices. It is compatible with iPhone 3GS, iPhone 4, iPad, iPod touch 3rd gen (32GB and 64GB models) and iPod touch 4th gen. See device compatibility.

PdTest02 – is also a simple Universal iPhone/Pad app, but it is a bit more sophisticated in its use of Libpd. PdTest demonstrates the following:

  • Loading the Pd patch LoopWithExtern.pd which loads a sample file (Banjo_B3.wav),
  • Use of a compiled and linked-in Pd external (lrshift~.c),
  • Use of simple iOS user interface elements to communicate with Libpd,
  • Sending messages to Pd objects using the PdBase class.
  • Using the PdReceiverDelegate protocol to receive print messages from Libpd.

Note: PdTest02 is compatible with almost all iOS devices, but it does not do any audio input. See device compatibility.

Using the PdTest Sample Projects for iOS

The iOS sample projects PdTest01 and PdTest02 are currently set up to use the latest iOS SDK. But this feature only works automatically with iOS SDK 4.2 and later. The projects' settings use ‘Latest iOS’ as the Base SDK and iOS 3.0 as their iOS Deployment Target. That means the app will run on any device with iOS 3.0 or later. (These can be changed in the projects' GetInfo panels.)

If you are having problems with XCode recognizing the project’s base SDK, or if you are using an older versions of the iOS SDK with Libpd for iOS, you may need to set the Deployment Target and Base SDK manually in the projects' GetInfo panels and/or the targets' GetInfo panels.

PdAudio and PdBase Objective C Glue Classes

The PdAudio and PdBase classes provide the Objective C glue to libpd.

PdAudio initializes the iOS Audio Session.

A PdAudio object needs to created by your app. e.g.,

pdAudio = [[PdAudio alloc] initWithSampleRate:44100.0 andTicksPerBuffer:64 andNumberOfInputChannels:2 andNumberOfOutputChannels:2];

If you want to your app to work on older iOS devices running the armv6 processor you should use the alternate init method where you must specify AmbientAudio as the iOS Audio Session Category type. This method is demonstrated in PdTest02.
Note that AmbientAudio does not support recording or audio input.

PdBase provides an interface to libpd through class methods. These methods are analogous the libpd Java API.

PdBase shouldn’t be explicitly instantiated as an object. Just make sure you add the class to your app project by adding the source files. Then call the class methods just as you would C functions. e.g.,

[PdBase openFile:fileName path:filePath];
[PdBase computeAudio:YES];

You also need to say [pdAudio play];

File opening / closing API

To open/close a pd file (also called a patch), you use the PdBase class methods:

+ (void *)openFile:(NSString *)baseName path:(NSString *)pathName;
+ (void)closeFile:(void *)x;

If you are just adding your patches to the Xcode project’s Resources folder, you can pass in [[NSBundle mainBundle] bundlePath] for the pathName argument. The open method returns an opaque pointer that acts as a handle to close that instance of the file (you can open more than one) and also to get its ‘$0’ argument via the method:

+ (int)dollarZeroForFile:(void *)x;

There is also a utility class called PdFile that will take care of these opaque pointers for you, which also fits in common obj-c containers like NSArray and NSDictionary. The PdFile class will automatically close the file in its deallocate method, and it also contains some convenience ivars for the patch (name, path, dollarZero).

Using compiled C-language Externals on iOS:

Because iOS does not support dynamic libraries it is necessary to compile and statically link any C-language Pd externals in with your iOS app.
It is also necessary to explicitly initialize any such external before it can be used from a Pd patch. This registers the external objects as available to Libpd.

For example, to use the C-language external lrshift~ with an iOS app. Add lrshift~.c to your project (it is located in the extra folder along with the Libpd source). Then call the lrshift_tilde_setup() function after initializing Libpd.

extern void lrshift_tilde_setup(void);

- (BOOL)application:(UIApplication *)application   
    didFinishLaunchingWithOptions:(NSDictionary *)launchOptions   
{      
    pdAudio = [[PdAudio  alloc] initWithSampleRate:44100.0   
            andTicksPerBuffer:64 andNumberOfInputChannels:2   
            andNumberOfOutputChannels:2];  
    lrshift_tilde_setup();  
...

iOS Device Compatibility

The family of iOS devices has gotten large with many major device models and numerous major OS releases. Libpd is a performance intensive library that interacts closely with each device’s audio hardware. Consequently there’s quite a lot of variation in compatibility and performance. A developer should expect to test and understand the performance limits of Libpd on the devices they expect to support with their application.

  • iPad (iOS 4.3.3) – problems with PDTest02, could not get any sound.
  • iPad (iOS 4.2.1) – no reported problems.
  • iPhone 4 – no reported problems.
  • iPhone 3GS (iOS 4) – no reported problems.
  • iPhone 3G – audio problems with PlayAndRecord Audio Session on iOS 3; audio problems reported on iOS 4 with AmbientAudio.
  • iPhone EDGE (iOS 3) – audio problems with PlayAndRecord Audio Session. Ok with AmbientAudio.
  • iPod touch 1st gen (iOS 3) – audio problems with PlayAndRecord Audio Session. Ok with AmbientAudio.
  • iPod touch 2nd gen (iOS 4) – no output with PlayAndRecord Audio Session. Ok with AmbientAudio.
  • iPod touch 3rd gen (32GB & 64GB) (iOS 4) – no reported problems.
  • iPod touch 4th gen – no reported problems.

Known Issues:

Generally, we have found Libpd works best with the latest generations of iOS devices that use the armv7-family of CPUs. These include the iPad, the iPhone 3GS, iPhone 4 and latest two models of the iPod touch.

Older iOS devices using the armv6-family of processors have exhibited some problems with Libpd, but we have found ways that these devices can be used. Currently the iOS kAudioSessionCategory_PlayAndRecord Audio Session type doesn’t seem to work well (or at all) with these devices. They do, generally, work with other Audio Session types such as kAudioSessionCategory_AmbientAudio. This means that recording does not work on these devices.

There are reports of audio problems with the iPhone 3G running iOS 4 even when using AmbientAudio.

The iOS SDK Simulator is finicky when it comes to audio settings. As of iOS 4.3, it will not render clean audio unless you request eight ticks per buffer in the init method of PdAudio if you’re running at a sample rate of 44100Hz, or four ticks per buffer at 22050Hz.