README.md
1# Rust bindings for Oboe library
2
3[](https://github.com/katyo/oboe-rs)
4[](https://crates.io/crates/oboe)
5[](https://docs.rs/oboe)
6[](https://opensource.org/licenses/Apache-2.0)
7[](https://github.com/katyo/oboe-rs/actions?query=workflow%3ARust)
8
9Safe Rust interface for [Oboe](https://github.com/google/oboe) High-Performance Audio library for Android.
10Also it provides interface for some platform APIs significant to Audio IO.
11
12__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).
13
14## Crate features
15
16- __java-interface__ Add interface for some Android platform APIs.
17- __generate-bindings__ Generate bindings at compile-time. By default the pregenerated bindings will be used.
18- __compile-library__ Compile _oboe_ C++ library at compile-time using __cmake__. By default the precompiled library will be used.
19- __shared-link__ Use shared linking. By default the static Oboe libarary will be used.
20
21The crate already has pregenerated bindings and precompiled static libraries for the following Android targets:
22
23- __armv7__
24- __aarch64__
25- __i686__
26- __x86_64__
27
28## Build issues
29
30The **[clang-sys](https://crates.io/crates/clang-sys)** crate uses **[llvm-config](http://llvm.org/docs/CommandGuide/llvm-config.html)** for searching [libclang](https://clang.llvm.org/docs/Tooling.html) library and preparing _C_/_C++_ compiler configuration. In order to get proper setup you should add *llvm-config* to your executables search path.
31
32In 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.
33
34To build applications you need recent version of __cargo-apk__, which supports latest Android [SDK](https://developer.android.com/studio#command-tools) (28+) and [NDK](https://developer.android.com/ndk) (20+). Don't forget to set ANDROID_SDK_ROOT environment variable with paths to installed SDK.
35
36For building host crates which requires C-compiler you may also set __HOST_CC__ environment variable with path to your C-compiler.
37
38## Usage example
39
40Playing sine wave in asynchronous (callback-driven) mode:
41
42```rust
43use oboe::{
44 AudioOutputCallback,
45 AudioOutputStream,
46 AudioStreamBuilder,
47 DataCallbackResult,
48 PerformanceMode,
49 SharingMode,
50 Mono,
51};
52
53// Structure for sound generator
54pub struct SineWave {
55 frequency: f32,
56 gain: f32,
57 phase: f32,
58 delta: Option<f32>,
59}
60
61// Default constructor for sound generator
62impl Default for SineWave {
63 fn default() -> Self {
64 Self {
65 frequency: 440.0,
66 gain: 0.5,
67 phase: 0.0,
68 delta: None,
69 }
70 }
71}
72
73// Audio output callback trait implementation
74impl AudioOutputCallback for SineWave {
75 // Define type for frames which we would like to process
76 type FrameType = (f32, Mono);
77
78 // Implement sound data output callback
79 fn on_audio_ready(&mut self, stream: &mut dyn AudioOutputStream, frames: &mut [f32]) -> DataCallbackResult {
80 // Configure out wave generator
81 if self.delta.is_none() {
82 let sample_rate = stream.get_sample_rate() as f32;
83 self.delta = (self.frequency * 2.0 * PI / sample_rate).into();
84 println!("Prepare sine wave generator: samplerate={}, time delta={}", sample_rate, self.delta.unwrap());
85 }
86
87 let delta = self.delta.unwrap();
88
89 // Generate audio frames to fill the output buffer
90 for frame in frames {
91 *frame = self.gain * self.phase.sin();
92 self.phase += delta;
93 while self.phase > 2.0 * PI {
94 self.phase -= 2.0 * PI;
95 }
96 }
97
98 // Notify the oboe that stream is continued
99 DataCallbackResult::Continue
100 }
101}
102
103// ...
104
105// Create playback stream
106let mut sine = AudioStreamBuilder::default()
107 // select desired performance mode
108 .set_performance_mode(PerformanceMode::LowLatency)
109 // select desired sharing mode
110 .set_sharing_mode(SharingMode::Shared)
111 // select sound sample format
112 .set_format::<f32>()
113 // select channels configuration
114 .set_channel_count::<Mono>()
115 // set our generator as callback
116 .set_callback(SineWave::default())
117 // open the output stream
118 .open_stream()
119 .unwrap();
120
121// Start playback
122sine.start().unwrap();
123
124// ...
125```
126
){kind=link}
){kind=link}
){kind=link}