Noisy Air

Introduction

About Marsyas

Marsyas (Music Analysis, Retrieval and Synthesis for Audio Signals) is best described by its creator as a "framework for developing systems for audio processing. It provides a general architecture for connecting audio, soundfiles, signal processing blocks and machine learning".

Further, Marsyas is open source and cross-platform. For developers, it serves as a static library of classes, implemented in C++. However, it is also useful to end users through its variety of commandline tools and GUI applications (GUI applications require the Qt library from Trolltech).

For the Mac developer, Marsyas can provide audio processing and analysis capabilities beyond those provided by Cocoa and Carbon. In fact, the OSX implementation of Marsyas relies on Core Audio, Core MIDI and Core Foundation, for the most primitive and low-level audio support. It is this tight integration with the OSX API's that make Marsyas an excellent choice for Mac and iPhone developers who require such functionality in their applications.

This document is intended to serve as a tutorial for the Mac/iPhone developer. While a wide range of developers will be able to make use of this document, it's primary intent is to be thorough, guiding the developer from acquiring and building the framework, to running a "Hello World" application and beyond. Excellent documentation for the framework already exists. This tutorial is meant to complement the existing documentation by (1) being as thorough and cumulative as possible, and (2) providing specific instructions for the Mac OS platform. The briefest foray into OSX programming reveals certain idiosyncrasies, tools, paradigms and conventions specific to the environment. As such, this document will attempt to demonstrate how one integrates Marsyas into the OSX development environment.

Requirements and Assumptions

Marsyas is distributed as sourcecode, thus requiring compilation. Later sections of this tutorial will elaborate on the tools needed to install the framework. The following general assumptions are made by the author:

• Marsyas requires a C++ compiler. Mac OS comes with the GCC compiler as part of its developer tools. If XCode and the developer tools have not yet been installed, they can either be download them from the Apple developer website, or installed directly from the CD that came with the machine.
• XCode will be used for development. Xcode uses its own build system to compile and link projects. If usinge the commandline and UNIX are prefered, the Marsyas documentation elaborates on using qmake to build projects.
• An independent understanding of audio processing. This guide may be followed sequentially to build a "Hello World" application, however the primary purpose is to install Marsyas and integrate with the Mac development environment. This document does not cover detailed / rudimentary topics in audio programming. One should refer to the Core Audio Programming Guide for that.
• Independent familiarity with C++ / Objective-C. This probably goes without saying, but this tutorial is not a language guide. Marsyas is implemented in C++, and current Cocoa applications are implemented in Objective-C. Brush up on these two languages as required.

Building Marsyas

Install MacPorts

MacPorts is a tool that automates the acquisition, compilation and installation of common UNIX software. The project has a repository of sourcecode ported to the Mac, and makes the process of installing this software simple by handling dependancies and the build envioronment. Marsyas requires a few pieces of software to help with its own install, and this is the easiest way to get them.

Begin by downloading MacPorts. The download includes a simple point-and-click installer.

Once installed, open a terminal and issue the command:

sudo port -v selfupdate

This will update the MacPorts repository, completing the installation of MacPorts. On a sidenote, a variety of software can be found using the command:

sudo port search softwareName

It can then be installed by:

sudo port install softwareName

Install cmake

cmake is a cross-platform tool used to control the build process of a project. Marsyas uses cmake to build on multiple platforms including Windows, Linux and OSX. cmake can also generate specific build configurations for XCode. Marsyas typically only needs to be built once, so using XCode may be overkill here. Subsequent projects in this tutorial will require XCode however.

Install cmake using Macports. Open a terminal and execute:

sudo port install cmake

Once complete, the components of cmake are installed. For development libraries, this usually includes putting the compiled lib file in a lib directory, the header files in an include directory, and the documentation files in a man directory. On a typical OSX install, system libraries are located in /usr/lib and headers are in /usr/include. However, MacPorts creates its own directory for the software it manages. The cmake lib will likely be placed in /opt/local/lib and the headers in /opt/local/include. The system should be able to find these files because MacPorts adds these new directories to the $PATH variable. This can be verified by opening a terminal and typing:

echo $PATH

The MacPorts directories should be among the entries in this list. In future cases, if the system cannot find libraries or headers, this may be the source of the problems. These files may need to be moved to a place where the system can find them.

Install libmad (Optional)

If mp3 support is required, the libmad library must also be installed. This can be done the same way cmake was installed:

sudo port install libmad

When building Marsyas, the build system needs to find this library, so copy these files into a place where they can be found:

sudo cp /opt/local/lib/libmad.* /usr/lib/.
sudo cp /opt/local/include/mad.h /usr/include/.

Install Qt (Optional)

Qt is a cross-platform framework for building graphical user interfaces (GUI's). If the Marsyas graphical applications will be installed, then Qt is a required dependancy. Download the OSX version of the sourcecode from the Trolltech Qt website.

Create a subdirectory under the home directory to hold Qt, Marsyas and any other future software:

cd ~
mkdir compiledSoftware

The path to this directory ~/compiledSoftware will be referred to as \$MYLIBS throughout the tutorial.

Place the downloaded Qt archive in a subdirectory of \$MYLIBS:

cd $MYLIBS
mkdir qt

Unpack the archive by double clicking it from the finder window. From here, the build process is pretty straight forward. Issue the three usual commands:

./configure
make
sudo make install

Go grab a coffee, because this is going to take a while.

Install Marsyas

Marsyas is now ready to be built. Detailed installation instructions can be found in the Marsyas User Manual. Download the sourcecode from the Marsyas project page. Create a new subdirectory in the $MYLIBS directory and unpack it there.

Enter the newly created marsyas directory and create a new directory that will hold the build files:

cd $MYLIBS/marsyas
mkdir build
cd build

Next, use cmake to generate the needed makefiles. Note, we are using make to control the build process, but cmake can be made to generate XCode project files as well. See the Marsyas User Manual if this is preferable. Invoke cmake by issuing:

ccmake ../src/

The ccmake terminal program will begin with the manual configuration of Marsyas. If libmad and Qt are installed, navigate to the appropriate row and enable them:

Press "c" several times to configure any changes. Once the configuration is complete, press "g" to generate the makefiles and exit ccmake.

Next, build Marsyas:

make

Issuing make install will put the Marsyas files into various standard directories on the system (/usr/bin etc). However, it's probably better to just leave the files where they are. This makes it easier to remove them if Marsyas needs to be removed. Once built, the commandline tools are located in $MYLIBS/marsyas/build/bin, and the static library is located in $MYLIBS/marsyas/build/lib.

Building Marsyas with XCode Instead of make

Instead of generating Makefiles to control the build process, cmake may alternately generate an XCode project. XCode can then be used to build the project's several targets. The command to generate an XCode project is:

cmake -G Xcode ../src/

This will create a .xcodeproj file that can be opened with XCode and built with the IDE. One note to remember: if mp3 support is included via libmad, or any other external library, be sure to link against them by adding them to the XCode project.