mServe Documentation

mServe Filters

mServe Filters

The mServe Filters API is planned for mServe 0.2 and currently in the design stage.
Contents

  1. Basics
  2. API for Decoders
  3. API for Filter Chain Modifiers
  4. API for Filter Plug-ins

Basics
Top
The basic structure is the filter_chain, which is a linked list. Each filter in the list does its stuff (optionally using a buffer), and then calls the next filter in the chain. The last link in the chain is always the output plugin (or, rather an adapter that buffers the data for output by the output thread).

API for Decoders
Top

void filter_push_data(decode_ctx *, const void *data, uint length);
void filter_set_format(decode_ctx *, int freq, SampleFormat fmt, int channels);
The decoder should call filter_set_format and filter_push_data to send data to the output thread. The data traverses the chain and ends up in a buffer for playback by the output thread. set_format should have been called before calling push_data (There is no default format).

API for Filter Chain Modifiers
Top

void filter_lock();
void filter_unlock();
All filter chain modifying functions should (must) call filter_lock before altering the filter chains, and filter_unlock when done with them.
filter_info *get_filter_info(const char *name);
filter_chain *filter_chain_create(filter_info *, const char *arg);
To add a filter into the chain, first you must retrieve the filter_info pointer for the filter. Then, you must create a filter_chain structure for insertion into the chain.
void filter_chain_insert_after(filter_chain *old, filter_chain *new_chain);
void filter_chain_insert_before(filter_chain *old, filter_chain *new_chain);
filter_chain *filter_chain_get_first();
filter_chain *filter_chain_get_last();
When the filter chain has been created, call an insert function to insert it into the chain. To insert a chain at the end or beginning of the chain, either take the return from get_first/last and give it to insert_*, or pass a NULL argument. To insert the chain at any other position, traverse the chain returned from get_first/last and call insert when you have found the one you want.
void filter_chain_remove(filter_chain *);
void filter_chain_destroy(filter_chain *);
Call remove to remove the reference to the chain link from the chain. All its resources will remain, so that the filter_chain can be inserted at another location in the chain. Call destroy to free all associated resources and the filter_chain. The pointer is no longer valid. The filter's deinit function is called for the filter_chain.
API for Filter Plug-ins
Top
The plugin file is a .so file, with one symbol exported:
extern filter_info *filter_get_info();
The function should return a filled filter_info structure for the plugin. The name field of the filter_info must correspond to the filename of the plugin.