Clone this wiki locally
This page explains how to compile, install, and use
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!
To launch the Java demo, enter the
ZenGarden directory and run the following from the root directory:
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.
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.
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 (
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
src/directory with the alias of
ln -s <ZenGarden src/ directory> libzengarden
- Similarly, create a symbolic link from the NDK’s
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
- Do the same from the NDK’s
GNU/LinuxOS X &
From the src directory, run
Note that you will need to have a development copy of
libsndfilealready 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.
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.
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:
A simple oscillator patch can be run with:
And any patch can be run with:
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
- Attach the
- The graph is now a part of the context. Process the context in order to generate output samples!