Getting Started

This page explains how to compile, install, and use ZenGarden.

HOWTO Try It Out

What is this crazy thing called ZenGarden? Its easy to try it out and get started right away. ZenGarden includes Java and Python wrappers of the library so that anyone can quickly try it out without having to add any platform specific audio code first. The Python example requires pygame.

You can run the ZenGarden demo patches with either the Java or Python examples. You should hear a simple 440 Hertz tone. You can try out other patches in the same directory, or some of your own. Remember that ZenGarden is not a perfect reproduction of the Pd interface. Many objects are missing and some syntactical elements are not yet implemented. Fortunately, you’ll know very quickly if the patch is working; hello exception!

Java

To launch the Java demo, enter the ZenGarden directory and run the following from the root directory:

$ ./runme-java.sh

Python

NOTE: The Python wrapper is outdated. The necessary files still exist in the repository and should not be difficult to repair for someone knowledgeable with Python ctypes.
To launch the Python demo, you will need to have pygame installed. Enter the ZenGarden directory and run the following:

$ LD_LIBRARY_PATH=./libs/`./src/platform`/
$ DYLD_LIBRARY_PATH=./libs/`./src/platform`/
$ python pyExampleGarden.py

Once again, if you have the shared object file in the current directory, you will not need to set the environment variables LD_LIBRARY_PATH or DYLD_LIBRARY_PATH.

HOWTO Compile ZenGarden

Install libsndfile

Regardless of platform, ZenGarden requires the use of libsndfile for audio file IO. You should get a copy of libsndfile for development, for your platform. On OS X or Linux you can run

$ ./configure
$ ./make
$ ./make install

On Mac OSX for example, you can “port install libsndfile” and on Debian GNU/Linux you can “apt-get install libsndfile1-dev”. For Android you will probably need to download and compile libsndfile in a local directory using an Android.mk.

Android

NOTE: This section is slightly outdated in that the make files were created for NDK v1.5 and have not been updated since. Active development takes place on the iPhone platform. But for someone knowledgeable of the Android NDK, it should be easy to update the files.
Android make files (Android.mk and Application.mk) are included with the ZenGarden library. The libzengarden make files are located in src/ and the make files for the JNI wrapper libjnizengarden are located in src/me/rjdj/zengarden/. In order to compile the library:

• Create a symbolic link from the Android NDK source/ directory to the ZenGarden src/ directory with the alias of libzengarden.
  ln -s <ZenGarden src/ directory> libzengarden

• Similarly, create a symbolic link from the NDK’s app/ directory.

• Optional: If you would like to build the JNI component, create another symbolic link with:
  ln -s <ZenGarden src/me/rjdj/zengarden directory> libjnizengarden
  • Do the same from the NDK’s app/ directory.

OS X & GNU/Linux

From the src directory, run

make

Note that you will need to have a development copy of libsndfile already installed for the compilation to work correctly. Also, Java (JDK) should be installed. Java is used in order to provide a platform independent sound interface which is useful for testing patches from the command line. It is not strictly necessary to compile the library.

The make command will make a static library libzengarden.a, a shared library libzengarden.so, and a JNI library libjnizengarden.so. In order to make only the static and shared libraries, run make libzengarden. In order to make only the JNI library, use make libjnizengarden. The make command also creates ZenGarden.jar which is a Java wrapper. The JAR also contains the test suite.

Xcode & iOS

The ZenGarden repository contains an Xcode project containing three targets.

• OSX Test Executable: Use this target to develop, test, and profile the library. Everything starts from main.cpp.
• iOS Library: Build the library for iOS v3.0 and up.
• OSX Library: Build the library for OS X.

Windows

It is our intention to support Windows. But do not hold your breath. We’ll get to it when we get to it. Sorry. Though, practically speaking, it should be easy enough to compile the library using cygwin and mingw.

Testing and Running

The ZenGarden test suite can be run can be tested by running the included shell script from the root directory:

./runme-test.sh

A simple oscillator patch can be run with:

./runme-java.sh

And any patch can be run with:

./runme-java.sh path/to/patch.pd

HOWTO Program with ZenGarden: The ZenGarden API

The ZenGarden API is easy to use and completely defined in ZenGarden.h. In order to work with ZenGarden, you should include not only ZenGarden.h, but also ZGCallbackFunction.h. For an example of how to use the library, see main.cpp.

The primary conceptual steps are:

• Create a PdContext. You can think of this as the Pd console. It contains global information such as block size, sample rate, and the number of input and output channels. Normally there is only on such context, but you are free to create as many as you like. Contexts are independent of each other.
• Create a PdGraph, either by instantiating an empty one, or by loading a .pd file.
• Attach the PdGraph to the PdContext.
• The graph is now a part of the context. Process the context in order to generate output samples!