PipeWire: Media Streams

PipeWire 0.1.8

Media Streams

# Overview

Media streams are used to exchange data with the PipeWire server. A stream is a wrapper around a proxy for a pw_client_node with just one port.

Streams can be used to:

- Consume a stream from PipeWire. This is a PW_DIRECTION_INPUT stream.
- Produce a stream to PipeWire. This is a PW_DIRECTION_OUTPUT stream

You can connect the stream port to a specific server port or let PipeWire choose a port for you.

For more complicated nodes such as filters or ports with multiple inputs and/or outputs you will need to create a pw_node yourself and export it with pw_remote_export.

# Create

Make a new stream with pw_stream_new(). You will need to specify a name for the stream and extra properties. You can use pw_fill_stream_properties() to get a basic set of properties for the stream.

Once the stream is created, the state_changed event should be used to track the state of the stream.

# Connect

The stream is initially unconnected. To connect the stream, use pw_stream_connect(). Pass the desired direction as an argument.

## Stream modes

The stream mode specifies how the data will be exchanged with PipeWire. The following stream modes are available

- PW_STREAM_MODE_BUFFER: data is exchanged with fixed size buffers. This is ideal for video frames or equal sized audio frames.
- PW_STREAM_MODE_RINGBUFFER: data is exhanged with a fixed size ringbuffer. This is ideal for variable sized audio packets or compressed media.

## Stream target

To make the newly connected stream automatically connect to an existing PipeWire node, use the PW_STREAM_FLAG_AUTOCONNECT and the port_path argument while connecting.

## Stream formats

An array of possible formats that this stream can consume or provide must be specified.

# Format negotiation

After connecting the stream, it will transition to the PW_STREAM_STATE_CONFIGURE state. In this state the format will be negotiated by the PipeWire server.

Once the format has been selected, the format_changed event is emited with the configured format as a parameter.

The client should now prepare itself to deal with the format and complete the negotiation procedure with a call to pw_stream_finish_format().

As arguments to pw_stream_finish_format() an array of spa_param structures must be given. They contain parameters such as buffer size, number of buffers, required metadata and other parameters for the media buffers.

# Buffer negotiation

After completing the format negotiation, PipeWire will allocate and notify the stream of the buffers that will be used to exchange data between client and server.

With the add_buffer event, a stream will be notified of a new buffer that can be used for data transport.

Afer the buffers are negotiated, the stream will transition to the PW_STREAM_STATE_PAUSED state.

# Streaming

From the PW_STREAM_STATE_PAUSED state, the stream can be set to the PW_STREAM_STATE_STREAMING state by the PipeWire server when data transport is started.

Depending on how the stream was connected it will need to Produce or Consume data for/from PipeWire as explained in the following subsections.

## Consume data

The new_buffer event is emited for each new buffer can can be consumed.

pw_stream_peek_buffer() should be used to get the data and metadata of the buffer.

When the buffer is no longer in use, call pw_stream_recycle_buffer() to let PipeWire reuse the buffer.

## Produce data

The need_buffer event is emited when PipeWire needs a new buffer for this stream.

pw_stream_get_empty_buffer() gives the id of an empty buffer. Use pw_stream_peek_buffer() to get the data and metadata that should be filled.

To send the filled buffer, use pw_stream_send_buffer().

The new_buffer event is emited when PipeWire no longer uses the buffer and it can be safely reused.

# Disconnect

Use pw_stream_disconnect() to disconnect a stream after use.