[−][src]Crate oboe

Safe Rust interface for Oboe High-Performance Audio library for Android.

Also it provides interface for some platform APIs significant to Audio IO.

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).

Crate features

java-interface Add interface for some Android platform APIs.
generate-bindings Generate bindings at compile-time. By default the pregenerated bindings will be used.
compile-library Compile oboe C++ library at compile-time using cmake. By default the precompiled library will be used.
shared-link Use shared linking. By default the static Oboe libarary will be used.

The crate already has pregenerated bindings and precompiled static libraries for the following Android targets:

armv7
aarch64
i686
x86_64

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 an errors related to missing headers or definitions.

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

For building host crates which requires C-compiler you may 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.frequency * 2.0 * PI / 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.gain * self.phase.sin();
            self.phase += delta;
            while self.phase > 2.0 * PI {
                self.phase -= 2.0 * PI;
            }
        }

        // 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();

// ...

Structs

AudioDeviceInfo	The Android audio device info
AudioStreamAsync	The audio stream for asynchronous (callback-driven) mode
AudioStreamBuilder	Factory for an audio stream.
AudioStreamBuilderAsync	Factory for an audio stream.
AudioStreamRef	Reference to the audio stream for passing to callbacks
AudioStreamSync	The audio stream for synchronous (blocking) mode
DefaultStreamValues	The default (optimal) audio streaming values.
FrameTimestamp	The time at which the frame at `position` was presented
Input	The input direction marker
Mono	The single mono channel configuration marker
Output	The output direction marker
Stereo	The dual stereo channels configuration marker
Unspecified	Unspecified marker type for use everywhere
Version	The version info

Enums

AltFrame
AudioApi	The underlying audio API used by the audio stream.
AudioDeviceDirection	The direction of audio device
AudioDeviceType	The type of audio device
AudioFeature	The Android audio features
AudioFormat	The format of audio samples.
ChannelCount	The channel count of the audio stream. Use of this enum is convenient to avoid "magic" numbers when specifying the channel count.
ContentType	The ContentType attribute describes what you are playing. It expresses the general category of the content. This information is optional. But in case it is known (for instance {@link Movie} for a movie streaming service or {@link Speech} for an audio book application) this information might be used by the audio framework to enforce audio focus.
DataCallbackResult	The result of an audio callback.
Direction	The direction of the stream.
Error	The error of an operation.
InputPreset	Defines the audio source. An audio source defines both a default physical source of audio signal, and a recording configuration.
PerformanceMode	The performance mode of the audio stream.
SampleRateConversionQuality	Specifies the quality of the sample rate conversion performed by Oboe. Higher quality will require more CPU load. Higher quality conversion will probably be implemented using a sinc based resampler.
SessionId	This attribute can be used to allocate a session ID to the audio stream.
SharingMode	The sharing mode of the audio stream.
StreamState	The state of the audio stream.
Usage	The Usage attribute expresses why you are playing a sound, what is this sound used for. This information is used by certain platforms or routing policies to make more refined volume or routing decisions.

Constants

DEFAULT_TIMEOUT_NANOS	The default number of nanoseconds to wait for when performing state change operations on the stream, such as `start` and `stop`.
MILLIS_PER_SECOND	The number of milliseconds in a second. 1,000.
NANOS_PER_MICROSECOND	The number of nanoseconds in a microsecond. 1,000.
NANOS_PER_MILLISECOND	The number of nanoseconds in a millisecond. 1,000,000.
NANOS_PER_SECOND	The number of nanoseconds in a second. 1,000,000,000.

Traits

AudioInputCallback	This trait defines a callback interface for:
AudioInputStream	The stream which can be used for audio input
AudioInputStreamSync	The stream which can be used for audio input in synchronous mode
AudioOutputCallback	This trait defines a callback interface for:
AudioOutputStream	The stream which can be used for audio output
AudioOutputStreamSync	The stream which can be used for audio output in synchronous mode
AudioStream	Base trait for Oboe audio stream.
AudioStreamBase	Base trait containing parameters for audio streams and builders.
IsChannelCount	The trait for channel count marker types
IsDirection	The trait for direction marker types
IsFormat	The traint for format marker types
IsFrameType	The trait for frame type marker types

Type Definitions

Result	The result of an operation with value
Status	The result of operation without value