Filter

Files
file	filter.h
	pipewire/filter.h

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

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) , PW_FILTER_FLAG_TRIGGER = (1 << 4) , PW_FILTER_FLAG_ASYNC = (1 << 5) }
	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) }

Macros
#define	PW_VERSION_FILTER_EVENTS   1

Functions
const char *	pw_filter_state_as_string (enum pw_filter_state state)
	Convert a filter state to a readable string
struct pw_filter *	pw_filter_new (struct pw_core *core, const char *name, struct pw_properties *props)
	Create a new unconnected Filter.
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
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.
uint32_t	pw_filter_get_node_id (struct pw_filter *filter)
	Get the node ID of the filter.
int	pw_filter_disconnect (struct pw_filter *filter)
	Disconnect filter
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.
int	pw_filter_remove_port (void *port_data)
	remove a port from the filter
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
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.
int	pw_filter_set_error (struct pw_filter *filter, int res, const char *error,...)
	Set the filter in error state.
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.
int	pw_filter_get_time (struct pw_filter *filter, struct pw_time *time)
	Query the time on the filter, deprecated, use the spa_io_position in the process() method for timing information.
uint64_t	pw_filter_get_nsec (struct pw_filter *filter)
	Get the current time in nanoseconds.
struct pw_loop *	pw_filter_get_data_loop (struct pw_filter *filter)
	Get the data loop that is doing the processing of this filter.
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.
int	pw_filter_queue_buffer (void *port_data, struct pw_buffer *buffer)
	Submit a buffer for playback or recycle a buffer for capture.
void *	pw_filter_get_dsp_buffer (void *port_data, uint32_t n_samples)
	Get a data pointer to the buffer data.
int	pw_filter_set_active (struct pw_filter *filter, bool active)
	Activate or deactivate the filter
int	pw_filter_flush (struct pw_filter *filter, bool drain)
	Flush a filter.
bool	pw_filter_is_driving (struct pw_filter *filter)
	Check if the filter is driving.
bool	pw_filter_is_lazy (struct pw_filter *filter)
	Check if the graph is using lazy scheduling.
int	pw_filter_trigger_process (struct pw_filter *filter)
	Trigger a push/pull on the filter.

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

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_FLAG_TRIGGER	the filter will not be scheduled automatically but _trigger_process() needs to be called. This can be used when the filter depends on processing of other filters.
PW_FILTER_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_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 that is not explicitly marked as mappable.
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

Macro Definition Documentation

PW_VERSION_FILTER_EVENTS

#define PW_VERSION_FILTER_EVENTS   1

Examples

audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

Function Documentation

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

Examples

video-dsp-play.c.

pw_filter_new()

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

Create a new unconnected Filter.

Returns

a newly allocated Filter

Parameters

core	a Core
name	a filter media name
props	filter properties, ownership is taken

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 Loop to use
name	a filter media name
props	filter properties, ownership is taken
events	filter events
data	data passed to events

Examples

audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

pw_filter_destroy()

void pw_filter_destroy

(

struct pw_filter *

filter

)

Destroy a filter

Examples

audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

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

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

pw_filter_get_name()

const char * pw_filter_get_name

(

struct pw_filter *

filter

)

pw_filter_get_core()

struct pw_core * pw_filter_get_core

(

struct pw_filter *

filter

)

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 Filter
flags	filter flags
params	an array with params.
n_params	number of items in params

Examples

audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

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

int pw_filter_disconnect

(

struct pw_filter *

filter

)

Disconnect filter

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

Examples

audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

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

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

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.

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 Filter
res	a result code
error	an error message

Examples

video-dsp-play.c.

pw_filter_update_params()

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 Filter
port_data	data associated with port
params	an array of params.
n_params	number of elements in params

Examples

midi-src.c.

pw_filter_get_time()

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

Query the time on the filter, deprecated, use the spa_io_position in the process() method for timing information.

pw_filter_get_nsec()

uint64_t pw_filter_get_nsec

(

struct pw_filter *

filter

)

Get the current time in nanoseconds.

This value can be compared with the nsec value in the spa_io_position. Since 1.1.0

pw_filter_get_data_loop()

struct pw_loop * pw_filter_get_data_loop

(

struct pw_filter *

filter

)

Get the data loop that is doing the processing of this filter.

This loop is assigned after pw_filter_connect(). * Since 1.1.0

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.

Examples

midi-src.c, and video-dsp-play.c.

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.

Examples

midi-src.c, and video-dsp-play.c.

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.

Examples

audio-dsp-filter.c, and audio-dsp-src.c.

pw_filter_set_active()

int pw_filter_set_active	(	struct pw_filter *	filter,
		bool	active )

Activate or deactivate the filter

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. The filter can be resumed after the drain by setting it active again with pw_filter_set_active(). A flush without a drain is mostly useful afer a state change to PAUSED, to flush any remaining data from the queues.

pw_filter_is_driving()

bool pw_filter_is_driving

(

struct pw_filter *

filter

)

Check if the filter is driving.

The filter needs to have the PW_FILTER_FLAG_DRIVER set. When the filter is driving, pw_filter_trigger_process() needs to be called when data is available (output) or needed (input). Since 0.3.66

pw_filter_is_lazy()

bool pw_filter_is_lazy

(

struct pw_filter *

filter

)

Check if the graph is using lazy scheduling.

Since 1.2.7

pw_filter_trigger_process()

int pw_filter_trigger_process

(

struct pw_filter *

filter

)

Trigger a push/pull on the filter.

One iteration of the graph will be scheduled and process() will be called. Since 0.3.66