PipeWire: Stream

PipeWire 1.4.7

Loading...
Searching...
No Matches
Stream

PipeWire stream objects. More...

## Files
file | stream.h
| pipewire/stream.h

## Data Structures
struct | pw_buffer
| a buffer structure obtained from pw_stream_dequeue_buffer(). More...
struct | pw_stream_control
struct | pw_time
| A time structure. More...
struct | pw_stream_events
| Events for a stream. More...
struct | pw_stream

## Enumerations
enum | pw_stream_state { PW_STREAM_STATE_ERROR = -1 , PW_STREAM_STATE_UNCONNECTED = 0 , PW_STREAM_STATE_CONNECTING = 1 , PW_STREAM_STATE_PAUSED = 2 , PW_STREAM_STATE_STREAMING = 3 }
| The state of a stream. More...
enum | pw_stream_flags { PW_STREAM_FLAG_NONE = 0 , PW_STREAM_FLAG_AUTOCONNECT = (1 << 0) , PW_STREAM_FLAG_INACTIVE = (1 << 1) , PW_STREAM_FLAG_MAP_BUFFERS = (1 << 2) , PW_STREAM_FLAG_DRIVER = (1 << 3) , PW_STREAM_FLAG_RT_PROCESS = (1 << 4) , PW_STREAM_FLAG_NO_CONVERT = (1 << 5) , PW_STREAM_FLAG_EXCLUSIVE = (1 << 6) , PW_STREAM_FLAG_DONT_RECONNECT = (1 << 7) , PW_STREAM_FLAG_ALLOC_BUFFERS = (1 << 8) , PW_STREAM_FLAG_TRIGGER = (1 << 9) , PW_STREAM_FLAG_ASYNC = (1 << 10) , PW_STREAM_FLAG_EARLY_PROCESS = (1 << 11) , PW_STREAM_FLAG_RT_TRIGGER_DONE = (1 << 12) }
| Extra flags that can be used in pw_stream_connect() More...

## Macros
#define | PW_VERSION_STREAM_EVENTS 2

## Functions
const char * | pw_stream_state_as_string (enum pw_stream_state state)
| Convert a stream state to a readable string.
struct pw_stream * | pw_stream_new (struct pw_core *core, const char *name, struct pw_properties *props)
| Create a new unconnected Stream.
struct pw_stream * | pw_stream_new_simple (struct pw_loop *loop, const char *name, struct pw_properties *props, const struct pw_stream_events *events, void *data)
void | pw_stream_destroy (struct pw_stream *stream)
| Destroy a stream.
void | pw_stream_add_listener (struct pw_stream *stream, struct spa_hook *listener, const struct pw_stream_events *events, void *data)
enum pw_stream_state | pw_stream_get_state (struct pw_stream *stream, const char **error)
| Get the current stream state.
const char * | pw_stream_get_name (struct pw_stream *stream)
struct pw_core * | pw_stream_get_core (struct pw_stream *stream)
const struct pw_properties * | pw_stream_get_properties (struct pw_stream *stream)
int | pw_stream_update_properties (struct pw_stream *stream, const struct spa_dict *dict)
int | pw_stream_connect (struct pw_stream *stream, enum pw_direction direction, uint32_t target_id, enum pw_stream_flags flags, const struct spa_pod **params, uint32_t n_params)
| Connect a stream for input or output on port_path.
uint32_t | pw_stream_get_node_id (struct pw_stream *stream)
| Get the node ID of the stream.
int | pw_stream_disconnect (struct pw_stream *stream)
| Disconnect stream.
int | pw_stream_set_error (struct pw_stream *stream, int res, const char *error,...)
| Set the stream in error state.
int | pw_stream_update_params (struct pw_stream *stream, const struct spa_pod **params, uint32_t n_params)
| Update the param exposed on the stream.
int | pw_stream_set_param (struct pw_stream *stream, uint32_t id, const struct spa_pod *param)
| Set a parameter on the stream.
const struct pw_stream_control * | pw_stream_get_control (struct pw_stream *stream, uint32_t id)
| Get control values.
int | pw_stream_set_control (struct pw_stream *stream, uint32_t id, uint32_t n_values, float *values,...)
| Set control values.
int | pw_stream_get_time_n (struct pw_stream *stream, struct pw_time *time, size_t size)
| Query the time on the stream, RT safe.
uint64_t | pw_stream_get_nsec (struct pw_stream *stream)
| Get the current time in nanoseconds.
struct pw_loop * | pw_stream_get_data_loop (struct pw_stream *stream)
| Get the data loop that is doing the processing of this stream.
int | pw_stream_get_time (struct pw_stream *stream, struct pw_time *time)
| Query the time on the stream, deprecated since 0.3.50, use pw_stream_get_time_n() to get the fields added since 0.3.50.
struct pw_buffer * | pw_stream_dequeue_buffer (struct pw_stream *stream)
| Get a buffer that can be filled for playback streams or consumed for capture streams.
int | pw_stream_queue_buffer (struct pw_stream *stream, struct pw_buffer *buffer)
| Submit a buffer for playback or recycle a buffer for capture.
int | pw_stream_return_buffer (struct pw_stream *stream, struct pw_buffer *buffer)
| Return a buffer to the queue without using it.
int | pw_stream_set_active (struct pw_stream *stream, bool active)
| Activate or deactivate the stream.
int | pw_stream_flush (struct pw_stream *stream, bool drain)
| Flush a stream.
bool | pw_stream_is_driving (struct pw_stream *stream)
| Check if the stream is driving.
bool | pw_stream_is_lazy (struct pw_stream *stream)
| Check if the graph is using lazy scheduling.
int | pw_stream_trigger_process (struct pw_stream *stream)
| Trigger a push/pull on the stream.
int | pw_stream_emit_event (struct pw_stream *stream, const struct spa_event *event)
| Emit an event from this stream.
int | pw_stream_set_rate (struct pw_stream *stream, double rate)
| Adjust the rate of the stream.

## Detailed Description

PipeWire stream objects.

The stream object provides a convenient way to send and receive data streams from/to PipeWire.

See also
  Streams, Core API

## Enumeration Type Documentation

## ◆ pw_stream_state

enum pw_stream_state

The state of a stream.

Enumerator
PW_STREAM_STATE_ERROR | the stream is in error
PW_STREAM_STATE_UNCONNECTED | unconnected
PW_STREAM_STATE_CONNECTING | connection is in progress
PW_STREAM_STATE_PAUSED | paused
PW_STREAM_STATE_STREAMING | streaming

Examples
  video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_flags

enum pw_stream_flags

Extra flags that can be used in pw_stream_connect()

Enumerator
PW_STREAM_FLAG_NONE | no flags
PW_STREAM_FLAG_AUTOCONNECT | try to automatically connect this stream
PW_STREAM_FLAG_INACTIVE | start the stream inactive, pw_stream_set_active() needs to be called explicitly
PW_STREAM_FLAG_MAP_BUFFERS | mmap the buffers except DmaBuf that is not explicitly marked as mappable.
PW_STREAM_FLAG_DRIVER | be a driver
PW_STREAM_FLAG_RT_PROCESS | call process from the realtime thread. You MUST use RT safe functions in the process callback.
PW_STREAM_FLAG_NO_CONVERT | don't convert format
PW_STREAM_FLAG_EXCLUSIVE | require exclusive access to the device
PW_STREAM_FLAG_DONT_RECONNECT | don't try to reconnect this stream when the sink/source is removed
PW_STREAM_FLAG_ALLOC_BUFFERS | the application will allocate buffer memory. In the add_buffer event, the data of the buffer should be set
PW_STREAM_FLAG_TRIGGER | the output stream will not be scheduled automatically but _trigger_process() needs to be called. This can be used when the output of the stream depends on input from other streams.
PW_STREAM_FLAG_ASYNC | Buffers will not be dequeued/queued from the realtime process() function. This is assumed when RT_PROCESS is unset but can also be the case when the process() function does a trigger_process() that will then dequeue/queue a buffer from another process() function. since 0.3.73
PW_STREAM_FLAG_EARLY_PROCESS | Call process as soon as there is a buffer to dequeue. This is only relevant for playback and when not using RT_PROCESS. It can be used to keep the maximum number of buffers queued. Since 0.3.81
PW_STREAM_FLAG_RT_TRIGGER_DONE | Call trigger_done from the realtime thread. You MUST use RT safe functions in the trigger_done callback. Since 1.1.0

## Macro Definition Documentation

## ◆ PW_VERSION_STREAM_EVENTS

#define PW_VERSION_STREAM_EVENTS 2

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, tutorial4.c, tutorial5.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## Function Documentation

## ◆ pw_stream_state_as_string()

const char * pw_stream_state_as_string | ( | enum pw_stream_state | state | ) |

Convert a stream state to a readable string.

Examples
  video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_new()

struct pw_stream * pw_stream_new | ( | struct pw_core * | core,
|  | const char * | name,
|  | struct pw_properties * | props )

Create a new unconnected Stream.

Returns
  a newly allocated Stream

Parameters

  core | a Core
  name | a stream media name
  props | stream properties, ownership is taken

Examples
  video-dsp-src.c, and video-src.c.

## ◆ pw_stream_new_simple()

struct pw_stream * pw_stream_new_simple | ( | struct pw_loop * | loop,
|  | const char * | name,
|  | struct pw_properties * | props,
|  | const struct pw_stream_events * | events,
|  | void * | data )

Parameters

  loop | a Loop to use as the main loop
  name | a stream media name
  props | stream properties, ownership is taken
  events | stream events
  data | data passed to events

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, tutorial4.c, tutorial5.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## ◆ pw_stream_destroy()

void pw_stream_destroy | ( | struct pw_stream * | stream | ) |

Destroy a stream.

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, tutorial4.c, tutorial5.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, and video-src-reneg.c.

## ◆ pw_stream_add_listener()

void pw_stream_add_listener | ( | struct pw_stream * | stream,
|  | struct spa_hook * | listener,
|  | const struct pw_stream_events * | events,
|  | void * | data )

Examples
  video-dsp-src.c, and video-src.c.

## ◆ pw_stream_get_state()

enum pw_stream_state pw_stream_get_state | ( | struct pw_stream * | stream,
|  | const char ** | error )

Get the current stream state.

Since 1.4 this also sets errno when the state is PW_STREAM_STATE_ERROR

## ◆ pw_stream_get_name()

const char * pw_stream_get_name | ( | struct pw_stream * | stream | ) |

## ◆ pw_stream_get_core()

struct pw_core * pw_stream_get_core | ( | struct pw_stream * | stream | ) |

## ◆ pw_stream_get_properties()

const struct pw_properties * pw_stream_get_properties | ( | struct pw_stream * | stream | ) |

## ◆ pw_stream_update_properties()

int pw_stream_update_properties | ( | struct pw_stream * | stream,
|  | const struct spa_dict * | dict )

## ◆ pw_stream_connect()

int pw_stream_connect | ( | struct pw_stream * | stream,
|  | enum pw_direction | direction,
|  | uint32_t | target_id,
|  | enum pw_stream_flags | flags,
|  | const struct spa_pod ** | params,
|  | uint32_t | n_params )

Connect a stream for input or output on port_path.

Returns
  0 on success < 0 on error.

You should connect to the process event and use pw_stream_dequeue_buffer() to get the latest metadata and data.

Parameters

  stream | a Stream
  direction | the stream direction
  target_id | should have the value PW_ID_ANY. To select a specific target node, specify the PW_KEY_OBJECT_SERIAL or the PW_KEY_NODE_NAME value of the target node in the PW_KEY_TARGET_OBJECT property of the stream. Specifying target nodes by their id is deprecated.
  flags | stream flags
  params | an array with params. The params should ideally contain supported formats.
  n_params | number of items in params

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, tutorial4.c, tutorial5.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_get_node_id()

uint32_t pw_stream_get_node_id | ( | struct pw_stream * | stream | ) |

Get the node ID of the stream.

Returns
  node ID.

Examples
  video-dsp-src.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_disconnect()

int pw_stream_disconnect | ( | struct pw_stream * | stream | ) |

Disconnect stream.

## ◆ pw_stream_set_error()

int pw_stream_set_error | ( | struct pw_stream * | stream,
|  | int | res,
|  | const char * | error,
|  |  | ... )

Set the stream in error state.

Parameters

  stream | a Stream
  res | a result code
  error | an error message

Examples
  video-play-fixate.c, video-play-pull.c, video-play-reneg.c, and video-play.c.

## ◆ pw_stream_update_params()

int pw_stream_update_params | ( | struct pw_stream * | stream,
|  | const struct spa_pod ** | params,
|  | uint32_t | n_params )

Update the param exposed on the stream.

Parameters

  stream | a Stream
  params | an array of params.
  n_params | number of elements in params

Examples
  video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_set_param()

int pw_stream_set_param | ( | struct pw_stream * | stream,
|  | uint32_t | id,
|  | const struct spa_pod * | param )

Set a parameter on the stream.

This is like pw_stream_set_control() but with a complete spa_pod param. It can also be called from the param_changed event handler to intercept and modify the param for the adapter. Since 0.3.70

Parameters

  stream | a Stream
  id | the id of the param
  param | the params to set

## ◆ pw_stream_get_control()

const struct pw_stream_control * pw_stream_get_control | ( | struct pw_stream * | stream,
|  | uint32_t | id )

Get control values.

## ◆ pw_stream_set_control()

int pw_stream_set_control | ( | struct pw_stream * | stream,
|  | uint32_t | id,
|  | uint32_t | n_values,
|  | float * | values,
|  |  | ... )

Set control values.

## ◆ pw_stream_get_time_n()

int pw_stream_get_time_n | ( | struct pw_stream * | stream,
|  | struct pw_time * | time,
|  | size_t | size )

Query the time on the stream, RT safe.

## ◆ pw_stream_get_nsec()

uint64_t pw_stream_get_nsec | ( | struct pw_stream * | stream | ) |

Get the current time in nanoseconds.

This value can be compared with the pw_time::now value. RT safe. Since 1.1.0

Examples
  video-dsp-src.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_get_data_loop()

struct pw_loop * pw_stream_get_data_loop | ( | struct pw_stream * | stream | ) |

Get the data loop that is doing the processing of this stream.

This loop is assigned after pw_stream_connect(). * Since 1.1.0

## ◆ pw_stream_get_time()

int pw_stream_get_time | ( | struct pw_stream * | stream,
|  | struct pw_time * | time )

Query the time on the stream, deprecated since 0.3.50, use pw_stream_get_time_n() to get the fields added since 0.3.50.

RT safe.

## ◆ pw_stream_dequeue_buffer()

struct pw_buffer * pw_stream_dequeue_buffer | ( | struct pw_stream * | stream | ) |

Get a buffer that can be filled for playback streams or consumed for capture streams.

RT safe.

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, tutorial4.c, tutorial5.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_queue_buffer()

int pw_stream_queue_buffer | ( | struct pw_stream * | stream,
|  | struct pw_buffer * | buffer )

Submit a buffer for playback or recycle a buffer for capture.

RT safe.

Examples
  audio-capture.c, audio-src-ring.c, audio-src-ring2.c, audio-src.c, tutorial4.c, tutorial5.c, video-dsp-src.c, video-play-fixate.c, video-play-pull.c, video-play-reneg.c, video-play.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_return_buffer()

int pw_stream_return_buffer | ( | struct pw_stream * | stream,
|  | struct pw_buffer * | buffer )

Return a buffer to the queue without using it.

This makes the buffer immediately available to dequeue again. RT safe.

## ◆ pw_stream_set_active()

int pw_stream_set_active | ( | struct pw_stream * | stream,
|  | bool | active )

Activate or deactivate the stream.

Examples
  video-play.c.

## ◆ pw_stream_flush()

int pw_stream_flush | ( | struct pw_stream * | stream,
|  | bool | drain )

Flush a stream.

When drain is true, the drained callback will be called when all data is played or recorded. The stream can be resumed after the drain by setting it active again with pw_stream_set_active(). A flush without a drain is mostly useful afer a state change to PAUSED, to flush any remaining data from the queues and the converters. RT safe.

## ◆ pw_stream_is_driving()

bool pw_stream_is_driving | ( | struct pw_stream * | stream | ) |

Check if the stream is driving.

The stream needs to have the PW_STREAM_FLAG_DRIVER set. When the stream is driving, pw_stream_trigger_process() needs to be called when data is available (output) or needed (input). Since 0.3.34

Examples
  video-play-pull.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_is_lazy()

bool pw_stream_is_lazy | ( | struct pw_stream * | stream | ) |

Check if the graph is using lazy scheduling.

If the stream is driving according to pw_stream_is_driving(), then it should consider taking into account the RequestProcess commands when driving the graph.

If the stream is not driving, it should send out RequestProcess events with pw_stream_emit_event() or indirectly with pw_stream_trigger_process() to suggest a new graph cycle to the driver.

It is not a requirement that all RequestProcess events/commands need to start a graph cycle. Since 1.4.0

Examples
  video-play-pull.c, and video-src.c.

## ◆ pw_stream_trigger_process()

int pw_stream_trigger_process | ( | struct pw_stream * | stream | ) |

Trigger a push/pull on the stream.

One iteration of the graph will be scheduled when the stream is driving according to pw_stream_is_driving(). If it successfully finishes, process() will be called and the trigger_done event will be emitted. It is possible for the graph iteration to not finish, so pw_stream_trigger_process() needs to be called again even if process() and trigger_done is not called.

If there is a deadline after which the stream will have xrun, pw_stream_trigger_process() should be called then, whether or not process()/trigger_done has been called. Sound hardware will xrun if there is any delay in audio processing, so the ALSA plugin triggers the graph every quantum to ensure audio keeps flowing. Drivers that do not have a deadline, such as the freewheel driver, should use a timeout to ensure that forward progress keeps being made. A reasonable choice of deadline is three times the quantum: if the graph is taking 3x longer than normal, it is likely that it is hung and should be retriggered.

Streams that are not drivers according to pw_stream_is_driving() can also call this method. The result is that a RequestProcess event is sent to the driver. If the graph is lazy scheduling according to pw_stream_is_lazy(), this might result in a graph cycle by the driver. If the graph is not lazy scheduling and the stream is not a driver, this method will have no effect.

RT safe.

Since 0.3.34

Examples
  video-dsp-src.c, video-play-pull.c, video-src-alloc.c, video-src-fixate.c, video-src-reneg.c, and video-src.c.

## ◆ pw_stream_emit_event()

int pw_stream_emit_event | ( | struct pw_stream * | stream,
|  | const struct spa_event * | event )

Emit an event from this stream.

RT safe. Since 1.2.6

## ◆ pw_stream_set_rate()

int pw_stream_set_rate | ( | struct pw_stream * | stream,
|  | double | rate )

Adjust the rate of the stream.

When the stream is using an adaptive resampler, adjust the resampler rate. When there is no resampler, -ENOTSUP is returned. Activating the adaptive resampler will add a small amount of delay to the samples, you can deactivate it again by setting a value <= 0.0. RT safe. Since 1.4.0