High Performance Game Audio with Oboe

Posted by Dan Galpin

We’ve added the Oboe C++ audio library to the
Android Game SDK. Oboe’s support of high-performance, low-latency audio across the widest range of Android devices is the right choice for most game developers.

Single API

On Android devices running Android 8.1 (API level 27) and higher, Oboe takes advantage of the improved performance and features of AAudio while maintaining backward compatibility (using OpenSL ES) with Android 4.1 (API level 16) and higher. Oboe also adds key features on top of the platform APIs to improve the audio developer experience, such as resampling, format conversion, and dynamic latency tuning. It performs audio data transformations, such as channel count conversion, when necessary to improve performance on selected devices, and has workarounds for other device-specific behaviors that improve the robustness of your audio code. In short, Oboe is now the recommended way to write audio code in C/C++ on Android.

Integrating Oboe

There are two primary ways to incorporate Oboe library prebuilts into your project. If you’re using the Android Gradle plugin version 4.1.0 or higher along with CMake, and are using or can enable shared STL, enabling Oboe is as easy as adding Oboe to your Gradle dependencies, enabling prefabs, and adding a few lines to your CMakeLists file.

You can also integrate Oboe by statically linking using the Android Game SDK. Begin by downloading the library and checking it into your source control system. You need to be using minSdkVersion of 16 or higher with NDK release 18 or higher. Then, to specify the version of the game SDK to link in that’s been compiled for the given ABI, API level, NDK, and STL combination, add a compiler include path in this form:

gamesdk/libs/[architecture]_API[apiLevel]_NDK[ndkVersion]_[stlVersion]_Release
Example: gamesdk/libs/arm64-v8a_API24_NDK18_cpp_static_Release

Then add -loboe_static to your linker command. Since you don’t need to bundle the liboboe.so shared library, static linking gives you a smaller code footprint. If the ABI, API level, NDK, and STL combination doesn’t have a precompiled version available for your settings, you can alternately link against the shared library. We have more guidance, including how to configure CMake for static libraries, in our developer documentation.

Oboe Basics

To output audio, you begin by creating a stream with the required properties, including a callback that is used when the stream requires new data.

oboe::AudioStreamBuilder builder;
builder.setPerformanceMode(oboe::PerformanceMode::LowLatency)
  ->setSharingMode(oboe::SharingMode::Exclusive)
  ->setDataCallback(myCallback)
  ->setFormat(oboe::AudioFormat::Float);

You’ll then populate the audio data inside of the callback. If the stream creates successfully, that means you got the requested stream type. If you didn’t specify these types, you’ll have to query to see what format was returned.

class MyCallback : public oboe::AudioStreamDataCallback {
public:
    oboe::DataCallbackResult
    onAudioReady(oboe::AudioStream *audioStream, void *audioData, int32_t numFrames) {
        // We requested AudioFormat::Float
        auto *outputData = static_cast<float *>(audioData);
        // TODO: populate audioData here
        return oboe::DataCallbackResult::Continue;
    }
};

For full details on using Oboe, check out the documentation, code samples and API reference. There’s even a codelab which shows you how to build a simple rhythm-based game.

If you have any issues, please file them here. We’d love to hear from you.