Expand description
This library provides a Rust-native API to the PipeWire audio server. This includes a native implementation of the protocol, and FFI wrappers around the lower-level SPA libraries used by PipeWire itself (which we try not to expose in the public API).
The API is expected to change. Notably, performing audio/video processing is not yet implemented, and the mechanism for setting up proxy events and defining closures can definitely be improved.
We will follow semantic versioning in order to avoid breaking existing API users.
§Usage
A typical client would use the following steps:
- Create a MainLoop, and run it
- Configure and create a Context, optionally specifying client-specific configuration
- Connect to the server, which provides a Core
- Request a Registry via the core
- Listen for global events
- Bind to the global objects you wish to interact with
- For each object you bind to, you will get a proxy object which has methods you can call on
the object, as well as events you can subscribe to with an
add_listener()call.
§Examples
Example usage of the library can be found in the source repository. The simple client test in
tests/lib.rs is a good starting point. The pw-browse utility in tools/browse can also
serve as a guide for writing clients.
Modules§
- context
- The Context holds local client configuration and support libraries. It is the entry point to all other API.
- core
- The Core object is the top-level singleton representing a connection to the PipeWire server. The Core can be used to query objects known to the PipeWire server via the Registry. It can also be used to create objects on the server on behalf of this client (this functionality has not yet been implemented).
- keys
- Contains a number of well-known keys used in properties (such as application name, language, process ID, etc.).
- main_
loop - Provides an event loop for the library to communicate with the PipeWire server, as well as primitives to managed mutually exclusive access to shared data structures.
- permission
- Sructures for representing permissions.
- properties
- Properties represent a key-value structure for various object properties. While the internal representation is String pairs, helper methods are provided for interpreting values as various primitives.
- proxy
- Proxy objects that represent objects exposed by the PipeWire server. This is the primary means by which clients can interact with server-side objects.
- thread_
loop - Provides an event loop that runs in a separate thread.
- types
- List of well-known types and interfaces shared by PipeWire server and clients.
Macros§
- closure
- Utility macro to reduce closure-related boilerplate.
- refcounted
- This macro simplifies the creation of structs using the refcounted inner pattern. The rough structure of such a struct is:
- some_
closure - Similar to closure!, but returns a
Some(...)for use with event callbacks.
Traits§
- Refcounted
- A helper trait for refcounted objects. Reccounted items can more easily be lifted into closures without leaking data. This is accomplished by distinguising between “strong references” (cause the object to exist) and “weak referenes” (which do not prevent the object from being freed).
Functions§
- init
- Must be called before using any other API from this crate. Initialises global support libraries and sets up logging.