iRTcmix -- RTcmix on the iPhone/iPod

v 0.72


Brad Garton, with help from Damon Holzborn and Terry Pender

June, 2010



The Big Disclaimer:


This is still very much a work-in-progress, but the basic essentials seem all in place.  We've segregated nearly all of the RTcmix audio functionality into the RTcmixPlayer.m/h files, so hopefully anything you work on developing with this version will work in later versions.


NOTE:  I say "iPhone" below, but it also applies to the iPod and the iPad.


I think this requires OS X 10.6, but that's because the latest iPhone SDK requires 10.6.  These apps all compile and run under all the current iPhone OS 3.x releases.



What's here:


RTcmix-iPhone-SIM/ -- iRTcmix source for building the RTcmix libs

for the iPhone simulator

RTcmix-iPhone-DEV/ -- iRTcmix source for building the RTcmix libs

for the iPhone device

iRTcmix -- basic app that sends or flushes a single script

iRTcmix2 -- basic app with sliders showing the PField interface capabilities

and dynamic script-construction using values from other iPhone interface

objects (sliders, textfields); also included is the script-retriggering (MAXBANG)

capability

iRTcmix3 -- basic app showing audio input and signal-processing.

This also shows how iRTcmix can work with the RemoteIO

Audio Unit (all of the apps can work in this way).

iRTcmix4 -- basic app showing audio playback via RTcmix from a 'disk'-based

soundfile or from a pre-loaded audio buffer

iRTcmixView_additional -- another basic app showing script-triggering,

slider interface objects, from Damon Holzborn

iRTcmixUtility_additional -- a basic app showing control from different

Interface Builder panes/vies.

RTcmixPlayer-classes -- the basic RTcmixPlayer.m/h files and supporting 

RTcmixManager.m/h files.  Use these when developing your own apps.

scoralyzer/ -- directory with the source (and subsequent executable) for

the scoralyzer score-conversion utility.



Installation and initial compiling:


1.  Double-click on the _COMPILE-iRTCMIX_ executable in the top-level directory.


2. It will ask you to drag the folder (in this case the iRTcmix_0.72-src/ folder into the Terminal window that appears.


3.  Do this and then hit RETURN.  This then compiles the libraries needed in the RTcmix-iPhone-SIM/ and RTcmix-iPhone-DEV/ directories.  It should also compile the scoralyzer program in the main iRTcmix_0.72-src/ directory.


4.  This will take a few minutes, and you may see a lot of warnings about deprecated functions and casts of integers, etc.  You can ignore these. It prints the message -------> COMPILE COMPLETE! when it all finishes.


4a.  If you need to compile the RTcmix-iPhone-SIM/ or RTcmix-iPhone-DEV/ (or scoralyzer/) subdirs independently, there are similar executable scripts in each one -- you'll see them.  Or you can fire up a Terminal and go in to do a "make" by hand.



Compiling the iPhone apps:


1.  Go into one of the iRTcmix directories and double-click on the corresponding xcodeproj file.


2.  Initially the RTcmix libraries under the "Frameworks" folder will be red, saying the can't be found.  HERE IS ONE OF THE BIGGEST ANNOYANCES YOU WILL HAVE TO DO:  Unfortunately I haven't been able to figure out the XCode dependency system enough to switch between the simulator libs and the device libs.  If you have selected a compile for the Simulator (done by switching the menu button in the upper left-hand corner of the main XCode project window), you will need to rename in the Finder the RTcmix-iPhone-SIM/ folder to RTcmix-iPhone/.  The red libraries should show black (i.e. the libs are in place) once you do this.


2a.  When you switch to compiling for your device, you will need to switch the names of the RTcmix-iPhone/ folder again; i.e. change RTcmix-iPhone/ back to RTcmix-iPhone-SIM/ and then rename the RTcmix-iPhone-DEV/ to RTcmix-iPhone/.  Fun, huh?  If anyone has any clues how I can set up XCode to do this automagically, please let me know!


3.  Once you have the proper RTcmix-iPhone/ directory in place, just hit the "Build and Debug" button and off you go!


3a.  Note:  When you compile for the simulator, you will see a whopping 1364 warnings appear.  These are all the same warnings coming from the standard C++ static lib that we are including (for some reason Apple dropped it from the iPhone SDK in 3.1+).  You can collapse these into a single line in the build/debug report if you need to see other warnings as you develop your code.  Some day in the future we'll fix this...


3b.  Interestingly, these warnings do not appear when you compile for the device.


4.  Building for the device should install the app on your iPhone/iPod and start it running.  Of course, this assumes you have that TOTALLY annoying code-signing nonsense worked out.  Good luck with that.



Building and compiling your own apps:


1.  Start and create an appropriate new project in XCode.   Note:  The project no longer has to be located in the same directory structure as the RTcmix-iPhone* packages.  Previous versions of iRTcmix did have this requirement.


2.  It's probably best to start development with the iPhone simulator, so locate the RTcmix-iPhone-SIM/ directory and rename it to RTcmix-iPhone/.


3.  Click on the "Action" menu button in the upper-left of the main XCode project window (next to the "Simulator/Device" menu button) and select Add->Existing Frameworks.  You will then see a listing of all available development frameworks.  For the core operation of iRTcmix, you need to add the following three to the project (if they weren't added already by XCode when initializing the project):


AudioToolbox.framework

Foundation.framework

UIKit.framework


4.  After adding these, click on the "Frameworks" folder under the "Groups and Files" listing on the left in the main XCode project window.  Then under "Project" on the uppermost (Apple) menu select "Add to Project" (SHIFT-APPLE-A).


5.  A file dialog window will open.  Navigate to the RTcmix-iPhone/ directory and locate the iphone-libs/ subdirectory.  Use SHIFT-select to select all of the items in this directory and hit the "Add" button.  Note:  you don't have to SHIFT-select all of the files and instead do one-at-a-time, but why would you want to?


6.  These files should then show up under the "Frameworks" folder in the main XCode project window.  Note:  Because we used the renamed RTcmix-iPhone/ directory to add these, when you switch the name from RTcmix-iPhone-DEV/ to RTcmix-iPhone/ to compile for the device, it will find the corresponding RTcmix libraries compiled for the device instead of the simulator.


7.  Next you probably want to add the RTcmixPlayer.m/h and the RTcmixManager.m/h files.  Copy these from the RTcmixPlayer-classes/ directory in the distribution into your Classes/ subdirectory (or another subdir if you would prefer) and add them to the project as you would add any other source-code files.  


8.  Add whatever methods you want to control RTcmix to the RTcmixManager.m/h files and the AppDelegate files.


9.  Additional files (such as the rtcmix_sco.sco or any soundfiles used) are probably best added as "Resources" to the XCode project.


10.  Compile and go!



Using the scoralyzer program


Because Apple prohibits apps that dynamically interpret code, any RTcmix scores used in iRTcmix have to by compiled into the app.  We do this by representing the scorefile within a character buffer array, but this requires that we declare the array appropriately (a typical array declaration does not allow unescaped RETURN or quotation-mark characters).


In the iRTcmix* sample apps, this array declaration is done in various rtcmix_sco.sco or rtcmix_init.sco (etc.) files that are then #included into an RTcmixManager method that then sends the code to the RTcmix engine.  Converting a 'standard' RTcmix score into this character buffer representation can be done 'by hand', but it's a bit tedious.  The scoralyzer program automates this conversion process.


It is very simple to use:


1.  Open your RTcmix score (perhaps as a text file from standalone RTcmix, or within the script buffer using the Max/MSP [rtcmix~] object), select the entire text and Copy it.


2.  Double-click on the scoralyzer executable in the scoralyzer/ directory.  A Terminal window will open with instructions to paste-in the RTcmix score.


3.  Paste the text you had copied previously and then hit CTRL-D.  The scoralyzer window will then print the converted text, saying something like:


char *thescore = {

"

...

"};


Rename *thescore (if appropriate) and Copy/Paste this text into your iRTcmix app.



Good luck with this, and (as always) feedback and suggestions are greatly appreciated:  garton - at - columbia - dot - edu.



Brad Garton

http://music.columbia.edu/~brad