sercand/oboe-rs

Rust bindings for Oboe high-performance audio IO Android library

Safe bindings for oboe library

Oboe is a C++ library which makes it easy to build high-performance audio apps on Android. It was created primarily to allow developers to target a simplified API that works across multiple API levels back to API level 16 (Jelly Bean).

Crates structure

• oboe-sys raw unsafe bindings to library which generated using bindgen.
• oboe safe rust wrapper for library which intended to use for android applications
• oboe-demo simple usage example for library (incomplete)

Crate features

The oboe and oboe-sys already have pregenerated bindings and precompiled library for the following Android targets:

• armv7
• aarch64
• i686
• x86_64

In case when you want to generate bindings and/or compile library youself you can use features below:

• generate-bindings which runs bindgen to generate bindings
• compile-library which runs cmake to compile oboe C++ library

Build issues

The clang-sys crate uses llvm-config for searching libclang library and preparing C/C++ compiler configuration. In order to get proper setup you should add llvm-config to your executables search path.

In case of using tools with libclang under the hood like bindgen you must be sure in proper your setup. Otherwise you get errors related to missing headers or definitions.

One way to fix such errors is to find the folder containing those headers under your NDK or SDK home and set environment variable BINDGEN_EXTRA_CLANG_ARGS=-I/path/to/that/folder.

To build applications you need recent version of cargo-apk from git, which supports latest Android SDK (28+) and NDK (20+). Don't forget to set ANDROID_HOME and NDK_HOME environment variables with paths to installed SDK and NDK.

For building host crates which requires C-compiler you usually should also set HOST_CC environment variable with path to your C-compiler.

Usage example

Playing sine wave in asynchronous (callback-driven) mode:

use oboe::{
    AudioOutputCallback,
    AudioOutputStream,
    AudioStreamBuilder,
    DataCallbackResult,
    PerformanceMode,
    SharingMode,
    Mono,
};

// Structure for sound generator
pub struct SineWave {
    frequency: f32,
    gain: f32,
    phase: f32,
    delta: Option<f32>,
}

// Default constructor for sound generator
impl Default for SineWave {
    fn default() -> Self {
        Self {
            frequency: 440.0,
            gain: 0.5,
            phase: 0.0,
            delta: None,
        }
    }
}

// Audio output callback trait implementation
impl AudioOutputCallback for SineWave {
    // Define type for frames which we would like to process
    type FrameType = (f32, Mono);

    // Implement sound data output callback
    fn on_audio_ready(&mut self, stream: &mut dyn AudioOutputStream, frames: &mut [f32]) -> DataCallbackResult {
        // Configure out wave generator
        if self.delta.is_none() {
            let sample_rate = stream.get_sample_rate() as f32;
            self.delta = (self.frequency2.0PI / sample_rate).into();
            println!("Prepare sine wave generator: samplerate={}, time delta={}", sample_rate, self.delta.unwrap());
        }

        let delta = self.delta.unwrap();

        // Generate audio frames to fill the output buffer
        for frame in frames {
            *frame = self.gainself.phase.sin();
            self.phase += delta;
            while self.phase > 2.0PI {
                self.phase -= 2.0PI;
            }
        }

        // Notify the oboe that stream is continued
        DataCallbackResult::Continue
    }
}

// ...

// Create playback stream
let mut sine = AudioStreamBuilder::default()
    // select desired performance mode
    .set_performance_mode(PerformanceMode::LowLatency)
    // select desired sharing mode
    .set_sharing_mode(SharingMode::Shared)
    // select sound sample format
    .set_format::<f32>()
    // select channels configuration
    .set_channel_count::<Mono>()
    // set our generator as callback
    .set_callback(SineWave::default())
    // open the output stream
    .open_stream()
    .unwrap();

// Start playback
sine.start().unwrap();

// ...