TUTORIAL - Processing and libPD for Android

Processing is a fantastic graphics library, and Pure Data is an equally awesome sound library.  Android is an operating system that truly kicks butt.  All 3 together means awesomeness, right?  Thanks to some truly impressive work, they all come together for your creative music creation pleasure.

This tutorial assumes you know the basic concepts behind Processing and Pure Data.  If you don’t know these, I promise if you have half an hour, you’ll enjoy spending it learning about each.  I assume you know a fair bit of programming, or at least have the ability to copy-paste like a champ.  In addition, you’ll need to do some git and command line work, as there’s really no escaping it.

Prerequisites (this is a fair amount to grab, especially the android stuff) -

Eclipse - http://eclipse.org/ 

Processing - http://processing.org/ 

Pure Data - http://puredata.info/ 

Android SDK + Eclipse ADT - http://developer.android.com/sdk/installing.html 

My Processing+PD example app - https://github.com/rjmarsan/YayProcessingPD 

Git (or be lazy and grab the Zip file, but I seriously recommend git) - http://git-scm.com/ 

First, grab the stuff above. seriously.  Unfortunately, Pure Data and Processing, when it comes to Android, don’t get along the greatest (at least for the time being), so you’re stuck with moving to the next common platform, which is Eclipse.  Luckily, you can still do all the work separately in Pure Data and Processing, and bring it quickly together in eclipse.

Eclipse.  Did you download the SDK and Eclipse ADT? Seriously do it.

Processing for Android is a straight port: http://wiki.processing.org/w/Android.  It actually works really well, not quite as fast (for obvious reasons), but most of your sketches should port over untouched.  In recent versions of Processing.app, you can just export straight to Android.  That’s great and all, but not for us.

To obtain Processing for Eclipse, don’t do anything.  It’s included as a library in the example project.  That being said, if you want to be at the latest-and-greatest processing, you’ll have to obtain that jar file elsewhere.

Pure Data comes to Android in the form of LibPD.  Obviously, Pure Data and its Graphical Programming doesn’t work so great on a 4” screen, so you program the code on your computer, save it, and open up the patch (without the UI) on the device.

To obtain LibPD, check out the repository (or zip) http://gitorious.org/pdlib/pd-for-android and follow the build instructions here: http://gitorious.org/pdlib/pages/Eclipse

or if you feel like following the link, here’s the code:

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

Then go into Eclipse and go to File->New Project...  Then select Android Project.  Select “Create project from existing source”, and below it where is says Browse... navigate to where you just ran git (or unzipped), and select PdCore and hit OK.  

So now it’s time to fire up the example project.  Go to File -> New Project... Again select Android Project, “Create project from existing source” and select Browse.  Select the folder YayProcessingPD and hit OK.  You’ll probably notice plenty of errors.  Right click the project and go to Properties. On the left, click on Android, and you’ll notice to the right you’ll see Library, and probably a red X next to PdCore.  Remove it and then hit add, selecting Your version of it.  Then again it might work just fine.  If so, cool.

So that’s it.  The project is set up.  Now Right-Click it and select Run As... Android Application.  Wait a bit and either an emulator will show up and 10-15 years later your sketch will run, or just plug in your phone and watch it automatically upload it and run (as long as you enabled Development Mode).  Woo hoo!  Take a moment to enjoy.

So what’s going on here?  Let’s take a step back from this creation and look at the two parts of it.  The Processing part of it is easy.  You’ll recognize lines like

        public void draw() {

                background(0);

                fill(200,0,0);

                stroke(255,0,0);

                ellipseMode(CENTER);

                ellipse(mouseX,mouseY,100,100);

but the lines

        public int sketchWidth() { return this.screenWidth; }

        public int sketchHeight() { return this.screenHeight; }

        public String sketchRenderer() { return PApplet.OPENGL; }

are new.  Those are Processing for Android’s alternate to setup().  Other than that, it’s pure processing.  Other classes work similar.  Pass the PApplet around, call it something short like ‘p’ for your sanity.  Much more information can be found on their wiki, http://wiki.processing.org/w/Android

The LibPD stuff is obviously trickier.  First off, notice where I open the patch:

                openPatch("test1.pd");

here’s that patch when opened in the full Pure Data application on the PC (it has none of this UI in libPD):

You’ll see notice two key boxes right away, [r pitch] and [r volume] (those are shorthand for [receive pitch] and [receive volume]) Those are the equivalent to [inlet], or [oscrecieve].  Message passing is your communication line between Android and Pure Data.  The code shows just how simple it is.  Data comes in through the [recieve] object, and into your patch.  On the java side of things, you’ll notice two calls.

                PdBase.sendFloat("pitch", (float)mouseX/(float)width);

                PdBase.sendFloat("volume", (float)mouseY/(float)height);

This is how Java talks to Pure Data.  Using the PdBase class, you can send a message to any target you’d like, and along with it, any float, bang, control, or many other data types.  These calls are fast and non-blocking, meaning super easy coding!

What to do from here?  To change the patch, open up the zipfile in res/raw/patch.zip.  For sanity’s sake, just place all your .pd files inside this zipfile, and LibPD takes care of unzipping them on new phones, etc.  Be warned that libPD comes with virtually no extensions.  Basically all you have to work with is whatever objects you find when you right click an empty canvas in Pd and click “Help”.  However, they are powerful enough to create virtually every Pure Data object, so have fun!

To check out a more advanced project, check out https://github.com/rjmarsan/PlasmaSound