PipeWire Filter

PipeWire filter object class. More...

Data Structures
struct	pw_filter_events
	Events for a filter. More...

Enumerations
enum	pw_filter_state {   PW_FILTER_STATE_ERROR = -1, PW_FILTER_STATE_UNCONNECTED = 0, PW_FILTER_STATE_CONNECTING = 1, PW_FILTER_STATE_PAUSED = 2,   PW_FILTER_STATE_STREAMING = 3 }
	The state of a filter More...
enum	pw_filter_flags {   PW_FILTER_FLAG_NONE = 0, PW_FILTER_FLAG_INACTIVE = (1 << 0), PW_FILTER_FLAG_DRIVER = (1 << 1), PW_FILTER_FLAG_RT_PROCESS = (1 << 2),   PW_FILTER_FLAG_CUSTOM_LATENCY = (1 << 3) }
	Extra flags that can be used in pw_filter_connect() More...
enum	pw_filter_port_flags { PW_FILTER_PORT_FLAG_NONE = 0, PW_FILTER_PORT_FLAG_MAP_BUFFERS = (1 << 0), PW_FILTER_PORT_FLAG_ALLOC_BUFFERS = (1 << 1) }

Functions
const char *	pw_filter_state_as_string (enum pw_filter_state state)
	Convert a filter state to a readable string More...
struct pw_filter *	pw_filter_new (struct pw_core *core, const char *name, struct pw_properties *props)
	Create a new unconneced PipeWire Filter. More...
struct pw_filter *	pw_filter_new_simple (struct pw_loop *loop, const char *name, struct pw_properties *props, const struct pw_filter_events *events, void *data)
void	pw_filter_destroy (struct pw_filter *filter)
	Destroy a filter More...
void	pw_filter_add_listener (struct pw_filter *filter, struct spa_hook *listener, const struct pw_filter_events *events, void *data)
enum pw_filter_state	pw_filter_get_state (struct pw_filter *filter, const char **error)
const char *	pw_filter_get_name (struct pw_filter *filter)
struct pw_core *	pw_filter_get_core (struct pw_filter *filter)
int	pw_filter_connect (struct pw_filter *filter, enum pw_filter_flags flags, const struct spa_pod **params, uint32_t n_params)
	Connect a filter for processing. More...
uint32_t	pw_filter_get_node_id (struct pw_filter *filter)
	Get the node ID of the filter. More...
int	pw_filter_disconnect (struct pw_filter *filter)
	Disconnect filter More...
void *	pw_filter_add_port (struct pw_filter *filter, enum pw_direction direction, enum pw_filter_port_flags flags, size_t port_data_size, struct pw_properties *props, const struct spa_pod **params, uint32_t n_params)
	add a port to the filter, returns user data of port_data_size. More...
int	pw_filter_remove_port (void *port_data)
	remove a port from the filter More...
const struct pw_properties *	pw_filter_get_properties (struct pw_filter *filter, void *port_data)
	get properties, port_data of NULL will give global properties More...
int	pw_filter_update_properties (struct pw_filter *filter, void *port_data, const struct spa_dict *dict)
	Update properties, use NULL port_data for global filter properties. More...
int	pw_filter_set_error (struct pw_filter *filter, int res, const char *error,...) 1(3
	Set the filter in error state. More...
int int	pw_filter_update_params (struct pw_filter *filter, void *port_data, const struct spa_pod **params, uint32_t n_params)
	Update params, use NULL port_data for global filter params. More...
int	pw_filter_get_time (struct pw_filter *filter, struct pw_time *time)
	Query the time on the filter More...
struct pw_buffer *	pw_filter_dequeue_buffer (void *port_data)
	Get a buffer that can be filled for output ports or consumed for input ports. More...
int	pw_filter_queue_buffer (void *port_data, struct pw_buffer *buffer)
	Submit a buffer for playback or recycle a buffer for capture. More...
void *	pw_filter_get_dsp_buffer (void *port_data, uint32_t n_samples)
	Get a data pointer to the buffer data. More...
int	pw_filter_set_active (struct pw_filter *filter, bool active)
	Activate or deactivate the filter More...
int	pw_filter_flush (struct pw_filter *filter, bool drain)
	Flush a filter. More...

Detailed Description

PipeWire filter object class.

The filter object provides a convenient way to implement processing filters.

See also Core API

Enumeration Type Documentation

pw_filter_flags

enum pw_filter_flags

Extra flags that can be used in pw_filter_connect()

Enumerator
PW_FILTER_FLAG_NONE	no flags
PW_FILTER_FLAG_INACTIVE	start the filter inactive, pw_filter_set_active() needs to be called explicitly
PW_FILTER_FLAG_DRIVER	be a driver
PW_FILTER_FLAG_RT_PROCESS	call process from the realtime thread
PW_FILTER_FLAG_CUSTOM_LATENCY	don't call the default latency algorithm but emit the param_changed event for the ports when Latency params are received.

pw_filter_port_flags

enum pw_filter_port_flags

Enumerator
PW_FILTER_PORT_FLAG_NONE	no flags
PW_FILTER_PORT_FLAG_MAP_BUFFERS	mmap the buffers except DmaBuf
PW_FILTER_PORT_FLAG_ALLOC_BUFFERS	the application will allocate buffer memory. In the add_buffer event, the data of the buffer should be set

pw_filter_state

enum pw_filter_state

The state of a filter

Enumerator
PW_FILTER_STATE_ERROR	the stream is in error
PW_FILTER_STATE_UNCONNECTED	unconnected
PW_FILTER_STATE_CONNECTING	connection is in progress
PW_FILTER_STATE_PAUSED	filter is connected and paused
PW_FILTER_STATE_STREAMING	filter is streaming

Function Documentation

pw_filter_add_listener()

void pw_filter_add_listener	(	struct pw_filter *	filter,
		struct spa_hook *	listener,
		const struct pw_filter_events *	events,
		void *	data
	)

pw_filter_add_port()

void* pw_filter_add_port	(	struct pw_filter *	filter,
		enum pw_direction	direction,
		enum pw_filter_port_flags	flags,
		size_t	port_data_size,
		struct pw_properties *	props,
		const struct spa_pod **	params,
		uint32_t	n_params
	)

add a port to the filter, returns user data of port_data_size.

Parameters

filter	a PipeWire Filter
direction	port direction
flags	port flags
port_data_size	allocated and given to the user as port_data
props	port properties, ownership is taken
params	an array of params. The params should ideally contain the supported formats
n_params	number of elements in params

References port::p, props, pw_properties_new(), and SPA_CONTAINER_OF.

pw_filter_connect()

int pw_filter_connect	(	struct pw_filter *	filter,
		enum pw_filter_flags	flags,
		const struct spa_pod **	params,
		uint32_t	n_params
	)

Connect a filter for processing.

Returns

0 on success < 0 on error.

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

Parameters

filter	a PipeWire Filter
flags	filter flags
params	an array with params.
n_params	number of items in params

References NAME, PW_FILTER_FLAG_RT_PROCESS, pw_log_debug, pw_properties_get(), SPA_CONTAINER_OF, and SPA_FLAG_IS_SET.

pw_filter_dequeue_buffer()

struct pw_buffer* pw_filter_dequeue_buffer

(

void *

port_data

)

Get a buffer that can be filled for output ports or consumed for input ports.

References port::filter, port::p, SPA_CONTAINER_OF, and port::user_data.

Referenced by pw_filter_get_dsp_buffer().

pw_filter_destroy()

void pw_filter_destroy

(

struct pw_filter *

filter

)

Destroy a filter

References NAME, port::p, pw_filter_disconnect(), pw_filter_remove_port(), pw_log_debug, SPA_CONTAINER_OF, spa_hook_remove(), spa_list_consume, and spa_list_remove().

pw_filter_disconnect()

int pw_filter_disconnect

(

struct pw_filter *

filter

)

Disconnect filter

References NAME, pw_core_disconnect(), pw_log_debug, pw_proxy_destroy(), SPA_CONTAINER_OF, spa_hook_remove(), and spa_list_remove().

Referenced by pw_filter_destroy().

pw_filter_flush()

int pw_filter_flush	(	struct pw_filter *	filter,
		bool	drain
	)

Flush a filter.

When drain is true, the drained callback will be called when all data is played or recorded

References impl::context, pw_loop_invoke, and SPA_CONTAINER_OF.

pw_filter_get_core()

struct pw_core* pw_filter_get_core

(

struct pw_filter *

filter

)

pw_filter_get_dsp_buffer()

void* pw_filter_get_dsp_buffer	(	void *	port_data,
		uint32_t	n_samples
	)

Get a data pointer to the buffer data.

References port::p, pw_filter_dequeue_buffer(), SPA_CONTAINER_OF, and port::user_data.

pw_filter_get_name()

const char* pw_filter_get_name

(

struct pw_filter *

filter

)

pw_filter_get_node_id()

uint32_t pw_filter_get_node_id

(

struct pw_filter *

filter

)

Get the node ID of the filter.

Returns

node ID.

pw_filter_get_properties()

const struct pw_properties* pw_filter_get_properties	(	struct pw_filter *	filter,
		void *	port_data
	)

get properties, port_data of NULL will give global properties

References port::props, SPA_CONTAINER_OF, and port::user_data.

pw_filter_get_state()

enum pw_filter_state pw_filter_get_state	(	struct pw_filter *	filter,
		const char **	error
	)

References pw_filter_events::process, spa_hook::removed, SPA_CALLBACKS_INIT, SPA_CONTAINER_OF, and spa_hook_list_append().

pw_filter_get_time()

int pw_filter_get_time	(	struct pw_filter *	filter,
		struct pw_time *	time
	)

Query the time on the filter

References pw_time::delay, spa_fraction::denom, NAME, pw_time::now, spa_fraction::num, pw_log_trace, pw_time::rate, impl::seq, SPA_CONTAINER_OF, pw_time::ticks, and filter::time.

pw_filter_new()

struct pw_filter* pw_filter_new	(	struct pw_core *	core,
		const char *	name,
		struct pw_properties *	props
	)

Create a new unconneced PipeWire Filter.

Returns

a newly allocated PipeWire Filter

Parameters

core	a The PipeWire Core Global Object
name	a filter media name
props	filter properties, ownership is taken

References impl::context.

pw_filter_new_simple()

struct pw_filter* pw_filter_new_simple	(	struct pw_loop *	loop,
		const char *	name,
		struct pw_properties *	props,
		const struct pw_filter_events *	events,
		void *	data
	)

Parameters

loop	a PipeWire Loop to use
name	a filter media name
props	filter properties, ownership is taken
events	filter events
data	data passed to events

References props, pw_context_new(), and pw_properties_new().

pw_filter_queue_buffer()

int pw_filter_queue_buffer	(	void *	port_data,
		struct pw_buffer *	buffer
	)

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

References port::filter, buffer::id, NAME, port::p, pw_log_trace, SPA_CONTAINER_OF, and port::user_data.

pw_filter_remove_port()

int pw_filter_remove_port

(

void *

port_data

)

remove a port from the filter

Parameters

port_data

data associated with port

References port::direction, port::filter, impl::hooks, port::id, port::link, SPA_CONTAINER_OF, spa_list_remove(), spa_node_emit_port_info, and port::user_data.

Referenced by pw_filter_destroy().

pw_filter_set_active()

int pw_filter_set_active	(	struct pw_filter *	filter,
		bool	active
	)

Activate or deactivate the filter

References NAME, and pw_log_debug.

pw_filter_set_error()

int pw_filter_set_error	(	struct pw_filter *	filter,
		int	res,
		const char *	error,
			...
	)

Set the filter in error state.

Parameters

filter	a PipeWire Filter
res	a result code
error	an error message

References pw_time::now, pw_time::rate, and pw_time::ticks.

pw_filter_state_as_string()

const char* pw_filter_state_as_string

(

enum pw_filter_state

state

)

Convert a filter state to a readable string

References PW_FILTER_STATE_CONNECTING, PW_FILTER_STATE_ERROR, PW_FILTER_STATE_PAUSED, PW_FILTER_STATE_STREAMING, and PW_FILTER_STATE_UNCONNECTED.

pw_filter_update_params()

int int pw_filter_update_params	(	struct pw_filter *	filter,
		void *	port_data,
		const struct spa_pod **	params,
		uint32_t	n_params
	)

Update params, use NULL port_data for global filter params.

Parameters

filter	a PipeWire Filter
port_data	data associated with port
params	an array of params.
n_params	number of elements in params

References NAME, port::port, pw_log_debug, SPA_CONTAINER_OF, and port::user_data.

pw_filter_update_properties()

int pw_filter_update_properties	(	struct pw_filter *	filter,
		void *	port_data,
		const struct spa_dict *	dict
	)

Update properties, use NULL port_data for global filter properties.

References spa_port_info::change_mask, pw_properties::dict, port::info, spa_port_info::props, port::props, pw_properties_update(), SPA_CONTAINER_OF, SPA_PORT_CHANGE_MASK_PROPS, and port::user_data.