Crate libpulse_simple_binding
source ·Expand description
PulseAudio Rust language binding library for the ‘simple’ component
PulseAudio ‘simple’ provides a simple but limited synchronous playback and recording API. This is a synchronous, simplified wrapper around the standard asynchronous API.
About
This library is a binding that allows Rust code to connect to the PulseAudio sound server via
PulseAudio’s existing C API. This binding provides a safe(r) Rust interface which might be
preferred over the raw C API provided by the underlying sys
linking crate.
This crate provides an interface to PulseAudio’s ‘simple’ component, and should be used in
addition to the general libpulse_binding
crate.
Introduction
The simple API is designed for applications with very basic sound playback or capture needs. It can only support a single stream per connection and has no support for handling of complex features like events, channel mappings and volume control. It is, however, very simple to use and quite sufficient for many programs.
Usage
Firstly, add a dependency on the crate in your program’s Cargo.toml
file. Secondly, import the
crate along with the general libpulse_binding
crate to the root of your program:
extern crate libpulse_binding as pulse;
extern crate libpulse_simple_binding as psimple;
Finally, establish a connection, as below.
Connecting
The first step before using the sound system is to connect to the server. This is normally done this way:
use psimple::Simple;
use pulse::stream::Direction;
let spec = pulse::sample::Spec {
format: pulse::sample::SAMPLE_S16NE,
channels: 2,
rate: 44100,
};
assert!(spec.is_valid());
let s = Simple::new(
None, // Use the default server
"FooApp", // Our application's name
Direction::Playback, // We want a playback stream
None, // Use the default device
"Music", // Description of our stream
&spec, // Our sample format
None, // Use default channel map
None // Use default buffering attributes
).unwrap();
Transferring data
Once the connection is established to the server, data can start flowing. Using the connection
is very similar to the normal read() and write() system calls using read
and write
methods of the Simple
object. Note that these operations always block.
Buffer control
Simple::get_latency
: Will return the total latency of the playback or record pipeline, respectively.Simple::flush
: Will throw away all data currently in buffers.
If a playback stream is used then the following operation is available:
Simple::drain
: Will wait for all sent data to finish playing.
Cleanup
Once playback or capture is complete, the connection should be closed and resources freed. This is done automatically once the object is dropped.