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:

# extern crate libpulse_binding as pulse;
# extern crate libpulse_simple_binding as psimple;
#
use psimple::Simple;
use pulse::stream::Direction;
use pulse::sample::{Spec, Format};

# fn main() {
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.