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

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
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.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 unconneced 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
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-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
	)

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

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

Examples: audio-capture.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_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 be scheduled. If it successfully finishes, process() will be called. It is possible for the graph iteration to not finish, so pw_stream_trigger_process() needs to be called again even if process() 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() 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.

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.

Files

Data Structures

Enumerations

Macros

Functions

Detailed Description

Enumeration Type Documentation

◆ pw_stream_state

◆ pw_stream_flags

Macro Definition Documentation

◆ PW_VERSION_STREAM_EVENTS

Function Documentation

◆ pw_stream_state_as_string()

◆ pw_stream_new()

◆ pw_stream_new_simple()

◆ pw_stream_destroy()

◆ pw_stream_add_listener()

◆ pw_stream_get_state()

◆ pw_stream_get_name()

◆ pw_stream_get_core()

◆ pw_stream_get_properties()

◆ pw_stream_update_properties()

◆ pw_stream_connect()

◆ pw_stream_get_node_id()

◆ pw_stream_disconnect()

◆ pw_stream_set_error()

◆ pw_stream_update_params()

◆ pw_stream_set_param()

◆ pw_stream_get_control()

◆ pw_stream_set_control()

◆ pw_stream_get_time_n()

◆ pw_stream_get_time()

◆ pw_stream_dequeue_buffer()

◆ pw_stream_queue_buffer()

◆ pw_stream_set_active()

◆ pw_stream_flush()

◆ pw_stream_is_driving()

◆ pw_stream_trigger_process()