Crate libpulse_binding

A binding for the PulseAudio system library (libpulse).

About

This binding enables Rust projects to make use of the PulseAudio client system library. It builds upon the separate raw FFI crate to provide a more “Rusty” interface.

The documentation below and throughout this crate has been largely copied (under fair-use terms) from those in the PulseAudio C API header files, and adjusted where appropriate to fit any differences, thus it should not be too unfamiliar to those of you already familiar with the C API.

Warning

The PulseAudio API, even in this Rust-ified form, is not the easiest thing to understand how to make use of. Furthermore, the somewhat complex underlying C API imposes certain limitations upon just how safe and simple an interface this binding can reasonably offer. One particularly notable example is the threaded mainloop locking mechanism, which uses a perfectly legitimate design, but one that happens to conflict with what is typically used in Rust code; it does not fit perfectly with the Rust borrow checking mechanism and thus you cannot rely upon the borrow checker to prevent unsafe use as much as is typical.

Introduction

The PulseAudio API comes in two flavours to accommodate different styles of applications and different needs in complexity:

• The complete but somewhat complicated to use asynchronous API.
• The simplified, easy to use, but limited synchronous API.

Simple API

Use this if you develop your program in synchronous style and just need a way to play or record data on the sound server. This functionality is kept in the separate libpulse-simple-binding crate. See that for details.

Asynchronous API

Use this if you develop your programs in asynchronous, event loop based style or if you want to use the advanced features of the PulseAudio API. A guide can be found in the mainloop module.

By using the built-in threaded main loop, it is possible to achieve a pseudo-synchronous API, which can be useful in synchronous applications where the simple API is insufficient.

Threads

The PulseAudio client libraries are not designed to be directly thread-safe. They are however designed to be re-entrant and thread-aware.

To use the libraries in a threaded environment, you must assure that all objects are only used in one thread at a time. Normally, this means that all objects belonging to a single context must be accessed from the same thread.

The included main loop implementation is also not thread safe. Take care to make sure event objects are not manipulated when any other code is using the main loop.

Note that some objects implement the Sync trait, despite not truly being thread-safe. The reason for this is that when the threaded mainloop is used (the most common one), its lock provides the thread safety, and when such types are used behind that lock, they are then Sync safe. If you use the standard mainloop though, then you would have to add an Arc wrapper to make them safe. Not having Sync would force the threaded mainloop case to require unnecessary and undesirable Arc wrappers. This is an unfortunate compromise resulting from the complication of needing to support multiple mainloop designs, and the threaded mainloop design being built upon a non-wrapper lock that is not typical of Rust code.

Logging

You can configure different logging parameters for the PulseAudio client libraries. The following environment variables are recognized:

• PULSE_LOG: Maximum log level required. Bigger values result in a more verbose logging output. The following values are recognized:
  • 0: Error messages
  • 1: Warning messages
  • 2: Notice messages
  • 3: Info messages
  • 4: Debug messages
• PULSE_LOG_SYSLOG: If defined, force all client libraries to log their output using the syslog(3) mechanism. Default behavior is to log all output to stderr.
• PULSE_LOG_JOURNAL: If defined, force all client libraries to log their output using the systemd journal. If both PULSE_LOG_JOURNAL and PULSE_LOG_SYSLOG are defined, logging to the systemd journal takes a higher precedence. Each message originating library file name and function are included by default through the journal fields CODE_FILE, CODE_FUNC, and CODE_LINE. Any backtrace attached to the logging message is sent through the PulseAudio-specific journal field PULSE_BACKTRACE. This environment variable has no effect if PulseAudio was compiled without systemd journal support.
• PULSE_LOG_COLORS: If defined, enables colored logging output.
• PULSE_LOG_TIME: If defined, include timestamps with each message.
• PULSE_LOG_FILE: If defined, include each message originating file name.
• PULSE_LOG_META: If defined, include each message originating file name and path relative to the PulseAudio source tree root.
• PULSE_LOG_LEVEL: If defined, include a log level prefix with each message. Respectively, the prefixes “E”, “W”, “N”, “I”, “D” stands for Error, Warning, Notice, Info, and Debugging.
• PULSE_LOG_BACKTRACE: Number of functions to display in the backtrace. If this variable is not defined, or has a value of zero, no backtrace is shown.
• PULSE_LOG_BACKTRACE_SKIP: Number of backtrace levels to skip, from the function printing the log message downwards.
• PULSE_LOG_NO_RATE_LIMIT: If defined, do not rate limit the logging output. Rate limiting skips certain log messages when their frequency is considered too high.

Usage

Start by adding a dependency on the crate in your program’s Cargo.toml file. Note that it is recommended that you rename the crate such that you can refer to it by a shorter name within your code (such as pulse, as used within examples within this crate’s documentation). Such renaming can be done within your Cargo.toml file with cargo version 1.31 or newer, or otherwise with extern crate statements.

See sub-modules for further information.

Warning

It is important that you read the COMPATIBILITY.md guide available in the code repository to understand the topic of compatibility with different versions of PulseAudio.

Modules

• callbacks
  Callback handling.
• channelmap
  Constants and routines for handing channel mapping.
• context
  Connection contexts for asynchronous communication with a server.
• def
  Global definitions.
• direction
  Utilities for direction.
• error
  Error management.
• format
  Utility functions for handling a stream or sink format.
• mainloop
  Main loop abstraction layer.
• operation
  Asynchronous operations.
• proplist
  Property list constants and functions.
• sample
  Constants and routines for sample type handling.
• stream
  Audio streams for input, output and sample upload.
• time
  Time handling functionality.
• utf8
  UTF-8 validation functions.
• util
  Assorted utility functions.
• version
  Version related constants and functions.
• volume
  Constants and routines for volume handling.