PipeWire: Filter

PipeWire 1.4.9

Loading...
Searching...
No Matches
Filter

PipeWire filter object class. More...

## 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)
| Get the current filter state.
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.
int | pw_filter_emit_event (struct pw_filter *filter, const struct spa_event *event)
| Emit an event from this 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

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

## ◆ 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. Only call methods marked as RT safe.
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 )

Get the current filter state.

Since 1.4 this also sets errno when the state is PW_FILTER_STATE_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.

RT safe.

## ◆ 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. RT safe. 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.

RT safe.

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.

RT safe.

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.

RT safe.

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

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

## ◆ 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. RT safe. Since 0.3.66

## ◆ pw_filter_emit_event()

int pw_filter_emit_event | ( | struct pw_filter * | filter,
|  | const struct spa_event * | event )

Emit an event from this filter.

RT safe. Since 1.2.6