PipeWire  0.3.59
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
 

Macros

#define PW_VERSION_STREAM_EVENTS   2
 

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)
}
 Extra flags that can be used in pw_stream_connect() More...
 

Functions

const char * pw_stream_state_as_string (enum pw_stream_state state)
 Convert a stream state to a readable string. More...
 
struct pw_streampw_stream_new (struct pw_core *core, const char *name, struct pw_properties *props)
 Create a new unconneced Stream. More...
 
struct pw_streampw_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. More...
 
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_corepw_stream_get_core (struct pw_stream *stream)
 
const struct pw_propertiespw_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. More...
 
uint32_t pw_stream_get_node_id (struct pw_stream *stream)
 Get the node ID of the stream. More...
 
int pw_stream_disconnect (struct pw_stream *stream)
 Disconnect stream
More...
 
int pw_stream_set_error (struct pw_stream *stream, int res, const char *error,...) 1(3
 Set the stream in error state. More...
 
int int pw_stream_update_params (struct pw_stream *stream, const struct spa_pod **params, uint32_t n_params)
 Complete the negotiation process with result code res. More...
 
const struct pw_stream_controlpw_stream_get_control (struct pw_stream *stream, uint32_t id)
 Get control values. More...
 
int pw_stream_set_control (struct pw_stream *stream, uint32_t id, uint32_t n_values, float *values,...)
 Set control values. More...
 
int pw_stream_get_time_n (struct pw_stream *stream, struct pw_time *time, size_t size)
 Query the time on the stream. More...
 
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. More...
 
struct pw_bufferpw_stream_dequeue_buffer (struct pw_stream *stream)
 Get a buffer that can be filled for playback streams or consumed for capture streams. More...
 
int pw_stream_queue_buffer (struct pw_stream *stream, struct pw_buffer *buffer)
 Submit a buffer for playback or recycle a buffer for capture. More...
 
int pw_stream_set_active (struct pw_stream *stream, bool active)
 Activate or deactivate the stream. More...
 
int pw_stream_flush (struct pw_stream *stream, bool drain)
 Flush a stream. More...
 
bool pw_stream_is_driving (struct pw_stream *stream)
 Check if the stream is driving. More...
 
int pw_stream_trigger_process (struct pw_stream *stream)
 Trigger a push/pull on the stream. More...
 

Detailed Description

PipeWire stream objects.

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

See also Streams and Core API

Macro Definition Documentation

◆ PW_VERSION_STREAM_EVENTS

Enumeration Type Documentation

◆ 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

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

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.

Function Documentation

◆ pw_stream_state_as_string()

const char* pw_stream_state_as_string ( enum pw_stream_state  state)

◆ 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
corea Core
namea stream media name
propsstream 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
loopa Loop to use
namea stream media name
propsstream properties, ownership is taken
eventsstream events
datadata 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()

◆ 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
streama Stream
directionthe stream direction
target_idshould 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.
flagsstream flags
paramsan array with params. The params should ideally contain supported formats.
n_paramsnumber 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
streama Stream
resa result code
erroran error message
Examples
video-play-fixate.c, video-play-pull.c, video-play-reneg.c, and video-play.c.

◆ pw_stream_update_params()

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

Complete the negotiation process with result code res.

This function should be called after notification of the format.

When res indicates success, params contain the parameters for the allocation state.

Parameters
streama Stream
paramsan array of params. The params should ideally contain parameters for doing buffer allocation.
n_paramsnumber 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_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_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 
)

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