Crate libpulse_simple_binding
source ·Expand description
A binding for the PulseAudio binding ‘simple’ interface (libpulse-simple
system library).
About
This binding enables Rust projects to make use of the ‘simple’ interface of the PulseAudio client system library. It builds upon the separate raw FFI crate to provide a more “Rusty” interface.
The ‘simple’ interface provides a simple but limited synchronous playback and recording API. It is a synchronous, simplified wrapper around the standard asynchronous API.
Note that you will need components of the primary libpulse-binding
crate to make use of
this.
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
Start by adding a dependency on the crate, along with the main binding crate, in your program’s
Cargo.toml
file. Note that it is recommended that you rename the crates such that you can
refer to them by shorter names within your code (such as pulse
and psimple
as used below).
Such renaming can be done within your Cargo.toml
file with cargo version 1.31 or
newer, or otherwise with extern crate
statements.
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;
use pulse::sample::{Spec, Format};
let spec = Spec {
format: Format::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 Simple::read()
and
Simple::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 Simple
object is dropped.
Structs
- An opaque simple connection object.