Building with Cricket Audio

ARM instruction sets

All iOS devices, and most Android devices, run on processors that use some variant of the ARM instruction set, such as armv5TE, armv6, or armv7. Devices that support the armv7 instruction can support specialized instructions (called NEON instructions) that can significantly speed up audio processing.

iOS

All recent iOS devices currently use either the armv7 or armv7s instruction set. The Cricket Audio library for iOS contains code for both instruction sets, packed into a single library (a "fat binary"). When you link your app to the Cricket Audio library, the linker will automatically choose the correct version. (Older iOS devices, prior to the iPhone 4 and 3rd generation iPod Touch, used the armv6 instruction set; however, Cricket Audio no longer supports armv6, because Xcode 4.5 no longer generates armv6 code.)

Android

Android native code can be built for either armv5 (referred to as "armeabi") or armv7 ("armeabi-v7a"). Code built for armv5 can run on all devices; armv7 code will run only on armv7 processors, but will run faster than armv5 code on those processors. Typically you want to provide both versions in your .apk; at runtime, the operating system will load the armv7 version if the processor supports it, and will otherwise load the armv5 version.

If you are using the Android Java interface (the Android SDK), you will just need to install both versions of the native Cricket Audio library (libckjava.so) with your app. (See Building for the Android SDK below.)

If you are using the Android native interface (the Android NDK), you will want to build your native code for both instruction sets, linking each version to the appropriate version of the Cricket Audio library. By default, native code built for Android targets only the armv5 instruction set; while this will work, your code will not run as quickly as it could on armv7 devices. To build for both instruction sets, you need to specify them in the APP_ABI variable in your Application.mk file. (See Building for the Android NDK below.)

Building for iOS or Mac OS

(Note: these instructions are for Xcode 4.0; the steps required for earlier versions of Xcode will be slightly different.)

Select your project in the Project Navigator. In the Project Editor, select the Build Settings tab.

In the "Search Paths" section, add the path to the Cricket Audio inc directory to the "Header Search Paths" setting. (For example, if the Cricket Audio distribution is in ../../cricket, the header search path would be ../../cricket/inc.)

In the "Search Paths" section, add the path to the Cricket lib directory to the "Library Search Paths" setting. To specify the configuration (debug or release), you can use the ${CONFIGURATION} variable. (For example, if the Cricket Audio distribution is in ../../cricket, the library search path for iOS would be ../../cricket/lib/ios/${CONFIGURATION}.)

In the "Linking" section, add -lck to the "Other Linker Flags" setting. If you are using the Objective-C interface, and you have no C++ code in your project, you may also need to add -lstdc++ also.

You will also probably want to make sure that any data files (bank files or stream files) are added to the project and set to be added as resources to your application bundle.

If you are not already doing so, you will need to link to the AudioUnit, AudioToolbox, AVFoundation, and CoreMedia frameworks.

For an example using Objective-C, take a look at the hellocricket sample, in src/samples/hellocricket/ios-objc. (There is an analogous Mac OS project in macos-objc.) This app was generated from the Xcode template for a window-based iOS app, with just a few minor changes to play a sound using Cricket Audio. A "Run Script" build phase was added to the target, which uses the cktool utility to build the binary bank file from the bank description file. Finally, the binary bank file hellocricket.ckb was added to the project, which automatically added it to the "Copy Bundle Resources" build phase.

For an example using C++, take a look at the hellocricket sample, in src/samples/hellocricket/ios-cpp. (There is an analogous Mac OS project in macos-cpp.) This app is identical to the Objective-C version, except the app delegate class uses the C++ Cricket Audio interface instead of Objective-C. The file containing the app delegate class, hellocricketAppDelegate.mm, was renamed from hellocricketAppDelegate.m, so the Objective-C++ compiler, rather than the Objective-C compiler, would be used to build it. (Alternatively, we could have changed the type of the source file from "Objective-C source" to "Objective-C++ source" in the File Inspector.)

Building for the Android SDK

(Note: these instructions assume you are building your Java code using Eclipse 3.7 and version 17 of the Android Development Tools (ADT) plugin.)

Cricket Audio for the Android SDK consists of a Java jar file (ck.jar) and one or more native libraries (libckjava.so).

First, copy the libraries:

copy lib/android/sdk/ck.jar to the libs directory in your project (creating the directory if necessary);
copy lib/android/sdk/armeabi/libckjava.so to the libs/armeabi directory in your project; and
copy lib/android/sdk/armeabi-v7a/libckjava.so to the libs/armeabi-v7a directory in your project.

The ck.jar file contains the Java interface that calls into the Cricket Audio native library; you must add this jar to your project's build path. In Eclipse, select your project in the Project Explorer and choose "Properties" from the Project menu. Select "Java Build Path" in the sidebar, click "Add JARs...", and choose the ck.jar file.

The libckjava.so files contain the native Cricket Audio code which is called via JNI from the Java interface. The armeabi version targets the armv5TE instruction set; the armeabi-v7a version targets the armv7a instruction set. If both are installed, the correct library will be loaded based on the actual instruction set of the device.

There are also debug versions for each instruction set (libckjava_d.so). The debug versions are intended for development only, and are only loaded if you set Config.NativeDebug to true at startup. They are significantly slower than the release versions, because they contain additional run-time consistency checks, so we recommend that you install the release versions, and only use the debug version to diagnose specific problems.

For an example, look at the hellocricket sample, in src/samples/hellocricket/android-sdk. This was generated from the Android project template by choosing "New Android Project" from the File menu, with just a few changes made to play a sound using Cricket Audio. In the sample, there is a custom Ant build step that copies the jar file and the native libraries and builds the binary bank file from the bank description file using cktool.

Building for the Android NDK

(Note: these instructions assume you are building your native code using the Android build system and an Android.mk file.)

In your Android.mk file, before the lines for your shared library, specify the Cricket Audio library as a "prebuilt" static library. This is best illustrated using the file from the hellocricket sample, at src/samples/hellocricket/android-ndk/jni/Android.mk:


      LOCAL_PATH := $(call my-dir)

      

      #-------------------------------------------------------------

      # specify libck as a "prebuilt" static library

      

      include $(CLEAR_VARS)

      LOCAL_MODULE := ck

      

      ifeq ($(NDK_DEBUG),1)

      LOCAL_SRC_FILES :=
      ../../../../../lib/android/ndk/$(TARGET_ARCH_ABI)/debug/libck.a

      else

      LOCAL_SRC_FILES :=
      ../../../../../lib/android/ndk/$(TARGET_ARCH_ABI)/release/libck.a

      endif

          

      include $(PREBUILT_STATIC_LIBRARY)

          

      #-------------------------------------------------------------

          

      include $(CLEAR_VARS)

          

      LOCAL_MODULE     := hellocricket

      LOCAL_SRC_FILES  := hellocricket.cpp

          

      LOCAL_C_INCLUDES := $(LOCAL_PATH)/../../../../../inc

      LOCAL_STATIC_LIBRARIES := ck cpufeatures

      LOCAL_LDLIBS     += -llog

          

      include $(BUILD_SHARED_LIBRARY)

      

      $(call import-module,android/cpufeatures)

In the first section, the prebuilt library called "ck" is defined, pointing to the debug or release version of libck.a depending on the NDK_DEBUG setting, and to the version for the appropriate ARM instruction set.

In the second section, the include path is set to the Cricket Audio inc directory, and the prebuilt "ck" library is specified using the LOCAL_STATIC_LIBRARIES variable. Note also that liblog.a has been added to the LOCAL_LDLIBS variable, as it is required by Cricket Audio.

Note also that cpufeatures is specified in the LOCAL_STATIC_LIBRARIES variable, and is built with the $(call import-module,android/cpufeatures) line at the end of the file. This is required for the armeabi-v7a version to detect when NEON optimizations may be used.

To build your application for both ARM instruction sets, specify them both in your Application.mk file:


      APP_ABI := armeabi armeabi-v7a

In the hellocricket sample, there is also a custom Ant build step that builds the binary bank file from the bank description file using cktool. This example uses a Java activity class that calls the native Cricket Audio code using a JNI call; the build process would be the same for an app that uses a native activity. Note that you must first build the native code using ndk-build before building and running the Java activity.

Building for Windows

(Note: these instructions are for Visual Studio 2010; the steps required for other version of Visual Studio will be slightly different.)

Right-click on the project in the Solution Explorer, and choose Properties.

Under C++ » General » Additional Include Directories, add the path to the Cricket Audio inc directory. (For example, if the Cricket Audio distribution is in ../../cricket, the header search path would be ../../cricket/inc.)

Under Linker » General » Additional Library Directories, add the path to the appropriate Cricket Audio library directory. The correct path is:

VisualStudioVersion/Platform/Configuration

where

VisualStudioVersion is vs10.0 for Visual Studio 2010 and vs11.0 for Visual Studio 2012;
Platform is Win32 or x64;
and Configuration is one of:

DebugStatic or ReleaseStatic, if your program is linking to the Microsoft runtime statically (i.e. is compiled with /MT or /MTd)
DebugDynamic or ReleaseDynamic, if your program is linking to the Microsoft runtime dynamically (i.e. is compiled with /MD or /MDd)
DebugMetro or ReleaseMetro, if your program is a Metro app. (Metro apps must be built with Visual Studio 2012, link dynamically to the Microsoft runtime, and use version 2.8 of XAudio2.)

You can use the Visual Studio macros $(Configuration), $(VisualStudioVersion), and $(Platform) to specify the correct path for your program. For example, if the Cricket Audio distribution is in ../../cricket, and you are linking statically to the runtime, the library search path would be ../../cricket/lib/vs$(VisualStudioVersion)/$(Platform)/$(Configuration)Static.

Under Linker » Input » Additional Dependencies, add ck.lib to the list of libraries.

Note that Cricket Audio uses XAudio2, which is part of the DirectX SDK, for audio output; end users will need to have the DirectX runtime installed (unless your program is a Metro app).