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)
}

| 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 unconneced 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)
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.
uint64_t | pw_stream_get_nsec (struct pw_stream *stream)
| Get the current time in nanoseconds.
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_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.
int | pw_stream_trigger_process (struct pw_stream *stream)
| Trigger a push/pull on 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

## 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

## Macro Definition Documentation

## PW_VERSION_STREAM_EVENTS

#define PW_VERSION_STREAM_EVENTS 2

Examples
  audio-capture.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, 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-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 unconneced Stream.

Returns
  a newly allocated Stream

Parameters

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

Examples
  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
  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.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.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-src.c.

## pw_stream_get_state()

enum pw_stream_state pw_stream_get_state | ( | struct pw_stream * | stream,
|  | const char ** | 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.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, 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-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-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.

## 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. Since 1.0.4

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

## 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.

## 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.

Examples
  audio-capture.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, 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.

Examples
  audio-capture.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, video-src-reneg.c, and video-src.c.

## 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

## 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-src-alloc.c, video-src-fixate.c, and video-src-reneg.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 scheduled and process() will be called. 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.