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) , PW_STREAM_FLAG_ASYNC = (1 << 10) }
	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_stream *	pw_stream_new (struct pw_core core, const char name, struct pw_properties *props)
	Create a new unconneced Stream. More...

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. 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_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. 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)
	Update the param exposed on the stream. More...

int	pw_stream_set_param (struct pw_stream stream, uint32_t id, const struct spa_pod param)
	Set a parameter on the stream. More...

const struct pw_stream_control *	pw_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_buffer *	pw_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.

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.

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

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 pw_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 pw_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 pw_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 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 pw_stream params an array of params. The params should ideally contain parameters for doing buffer allocation.
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 pw_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-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.

Files

Data Structures

Macros

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ PW_VERSION_STREAM_EVENTS

Enumeration Type Documentation

◆ pw_stream_state

◆ pw_stream_flags

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