Building with Cricket Audio

ARM instruction sets

All iOS and WP8 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

Most recent iOS devices currently use the armv7, armv7s, or arm64 instruction set.  The Cricket Audio library for iOS contains code for all three instruction sets plus the x86_64 code for the iPhone simulator, 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 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.)

Cricket Audio is not yet supported for x86 and MIPS builds of Android; if you are targeting these architectures, please contact Cricket Audio support for more information.

Windows Phone 8

All WP8 devices currently in use support the armv7 instruction set.

Building for iOS or OS X

(Note: these instructions are for Xcode 5.0; the steps required for earlier versions of Xcode may 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, CoreMedia, and MediaPlayer frameworks.

For an example using Objective-C, take a look at the hellocricket sample, in src/samples/hellocricket/ios-objc.  (There is an analogous OS X project in osx-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 OS X project in osx-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 4.2 and version 22 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:
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.

Cricket Audio does not currently have official support x86 and MIPS for Android; if you are developing for those architectures, please contact Cricket Technology support.

Building for Windows

(Note: these instructions are for Visual Studio 2012; the steps required for other versions 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 relative to the Cricket Audio distribution is:

lib/win/VisualStudioVersion/Platform/Configuration

where

VisualStudioVersion is one of:
Platform is one of:
and Configuration is one of:
If your program is linking to the Microsoft runtime statically (i.e. is compiled with /MT or /MTd), then use one of the "Static" configurations; if it is linking to the Microsoft runtime dynamically (i.e. is compiled with /MD or /MDd), then use one of the "Dynamic" configurations.

On Windows 8.0 and later, Cricket Audio will use XAudio2 2.8, which comes preinstalled with Windows.  In earlier versions of Windows, it will use XAudio2 2.7; the DirectX runtime may need to be installed separately on the target system.

If your program is a Windows Store app (formerly called a Metro app), you must use either the DebugDynamic or ReleaseDynamic library.

You can use the Visual Studio macros $(Configuration)$(VisualStudioVersion), and $(PlatformShortName) 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)/$(PlatformShortName)/$(Configuration)Static.

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

Building for Windows Phone 8

If you are building for Windows Phone 8 using native code rather than managed code, the process is very similar to that described above in Building for Windows

The library path for Windows Phone 8 projects is

lib/wp8/VisualStudioVersion/Platform/Configuration

where

VisualStudioVersion is one of:
Platform is one of:
and Configuration is one of:

If you are using managed code, you instead only need to add a reference to the Cricket Audio runtime component. In the Solution Explorer, right-click on the References folder for your app's project, and choose Add Reference.  In the Reference Manager window that appears, click the Browse tab on the left side, then the Browse button on the bottom right, and select the CricketTechnology.Audio.winmd file.

Note, however, that this reference is for a specific file, and will use the same library for all platforms and configurations; there is no way that we know of to set the path based on the $(Platform) or $(Configuration) macros.  However, we have found this workaround.  Instead of adding the explicit reference as described above, define a pre-build command to copy the appropriate version of the file to the project's directory, then add a reference to that copy of the file:
  1. In the Solution Explorer, right-click on the project file for your app, and choose Properties.
  2. Click the Build Events tab on the left side of the properties page.
  3. In the Pre-Build Event field, add commands to copy the appropriate versions of the files to the project's directory.
  4. Build your project, so the pre-build step you just defined is performed.
  5. Add a reference to the copied version of the CricketTechnology.Audio.winmd file.
For an example, take a look at the hellocricket sample, in src/samples/hellocricket/wp8-dotnet. It uses this pre-build step to copy the necessary files:

copy "$(ProjectDir)..\..\..\..\lib\wp8\vs$(VisualStudioVersion)\$(PlatformName)\$(Configuration)\CricketTechnology.Audio.winmd" "$(ProjectDir)"
copy "$(ProjectDir)..\..\..\..\lib\wp8\vs$(VisualStudioVersion)\$(PlatformName)\$(Configuration)\CricketTechnology.Audio.dll" "$(ProjectDir)"
copy "$(ProjectDir)..\..\..\..\lib\wp8\vs$(VisualStudioVersion)\$(PlatformName)\$(Configuration)\CricketTechnology.Audio.pdb" "$(ProjectDir)"

Building for Linux

Make sure you add the path to the Cricket Audio header files to the list of include directories, and the path to the Cricket Audio libraries to the list of library directories.  In addition to the Cricket Audio library (libck.a), you will need to link to the ALSA shared library (libasound.so). 

For example, to build the 64-bit debug version of the hellocricket sample, the command line is:

g++ hellocricket.cpp -o hellocricket -I../../../../inc -L../../../../lib/linux/x64/debug -L/usr/lib/x86_64-linux-gnu -lck -lasound