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 unconneced 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_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.
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, 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 unconneced 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, 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, 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, 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, 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

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

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

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