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 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. You can attach user_data to these buffers.

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 process event is emited for each new buffer that can can be consumed.

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

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

## Produce data

pw_stream_dequeue_buffer() gives an empty buffer that can be filled.

Filled buffers should be queued with pw_stream_queue_buffer().

The process event is emited when PipeWire has emptied a buffer that can now be refilled.

# Disconnect

Use pw_stream_disconnect() to disconnect a stream after use.