PipeWire Documentation

The Telephony service is a D-Bus service that enables applications to control phone calls via the HFP (Hands-Free Profile) native backend. When a mobile phone is paired, PipeWire acts as the Hands-Free device and the phone acts as the Audio Gateway.

Compatibility with ofono

The service is designed to be compatible with ofono interfaces (org.ofono.Manager, org.ofono.VoiceCallManager, and org.ofono.VoiceCall). Applications can use this service as a drop-in replacement for ofono for Bluetooth-based voice calls by:

1. Modifying the service name.
2. Updating the manager object path.
3. Adjusting the operating bus (session vs system).

Note that a runtime option exists to register the service as org.ofono on the system bus for full drop-in compatibility, though it only replaces Bluetooth-based voice call functionality.

A PipeWire module acts as a PipeWire client running within the pipewire(1) process. Modules are typically loaded via the PipeWire configuration files by adding them to the context.modules array. Each module is defined as an object containing at least a name key specifying the module library.

context.modules = [
    {
        name = libpipewire-module-protocol-native
    }
]

PipeWire configuration files use a relaxed "SPA" JSON format, which is easier to edit manually than standard JSON.

SPA JSON Syntax Rules:

• : can be replaced by = or a space to delimit keys and values.
• Quotes (") around keys and strings can be omitted if no special characters are used.
• Commas (,) used to separate objects can be replaced by whitespace.
• # can be used to start a comment until the end of the line.

Basic Structure Example:

context.properties = {  # top-level dictionary section
    key1 = value  # a simple value
    key2 = { key1 = value1 key2 = value2 }  # a dictionary with two entries
    key3 = [ value1 value2 ]  # an array with two entries
    key4 = [ { k = v1 } { k = v2 } ]  # an array of dictionaries
}

context.modules = [  # top-level array section
    value1
    value2
]

PipeWire manipulates several distinct object types via its API. Common types exported (visible in pw-dump) include:

• Node: An audio/video processing unit.
• Device: A physical or virtual hardware unit.
• Port: An endpoint on a Node.
• Link: A connection between Ports.
• Client: An application connecting to PipeWire.
• Metadata: Information manipulated via pw-metadata(1).
• Module: Components loaded via configuration or API.
• SecurityContext: Objects providing API-based security.
• Profiler: Objects providing profiling APIs.

Note: Monitors are technically Device objects and are not listed as separate exported types, but they have their own configurable properties.

A complete PipeWire setup consists of several distinct components, each with its own configuration responsibilities. To control the processing graph effectively, you must manage configuration for the following pieces:

• pipewire: The main daemon responsible for running and coordinating the processing graph.
• pipewire-pulse: The PulseAudio replacement server. It handles the properties of PulseAudio clients connecting to the system.
• wireplumber: The session manager. It is responsible for device configuration (loading ALSA/other devices, configuring profiles, port volumes, etc.) and managing how new clients are linked to targets based on session policies.
• PipeWire clients: Individual applications using the native PipeWire interface or emulated interfaces (JACK, ALSA, PulseAudio) each load their own configuration files.

Use stream.rules to match specific streams and apply property updates. This is useful for renaming nodes or changing properties based on the application name.

Rules use a matches array and an actions object. The update-props action modifies the node object of the matched stream.

Matching Syntax:

• All keys in a match block must match the value.
• Use ! to negate a match.
• Use ~ to start a regex match.

# ~/.config/pipewire/client.conf.d/custom.conf

stream.rules = [
    {
        matches = [
            {
                # all keys must match the value. ! negates. ~ starts regex.
                application.process.binary = "firefox"
            }
        ]
        actions = {
            update-props = {
                node.name = "My Name"
            }
        }
    }
]

The Opus payload consists of either a single Opus Multistream packet or a fragment of one.

• Reconstruction: When fragmentation is indicated by the RTP payload header, the full Opus Multistream packet is reconstructed by concatenating the payloads of the fragment Bluetooth packets.
• Bandwidth: The Source (SRC) is responsible for selecting encoder parameters that do not exceed Bluetooth bandwidth limitations.
• Error Correction: The SRC may include Forward Error Correction (FEC) data. The Sink (SNK) can choose to enable FEC instead of using Packet Loss Concealment (PLC).

PipeWire uses a high-quality adaptive resampler (sinc-based with linear interpolation) for source, sink, capture, and playback streams. Resampling is triggered when hardware samplerates differ from the graph samplerate, when clocks need matching, or when a stream's samplerate differs from the graph.

Most resampling and sample conversion is performed in the client (or pipewire-pulse for PulseAudio applications) to allow the server to maintain a single format for performance.

You can tune the resampler using node-prop properties to balance audio quality, CPU usage, and latency.