Crate libpulse_simple_binding[−][src]

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:

ⓘThis example is not tested
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:

Cleanup

Once playback or capture is complete, the connection should be closed and resources freed. This is done automatically once the object is dropped.

Structs

Simple

An opaque simple connection object. This acts as a safe Rust wrapper for the actual C object.