XMMS2

XForm API More...

Data Structures

struct  xmms_xform_metadata_basic_mapping_St
 Mapping between format specific and internal metadata naming. More...
 
struct  xmms_xform_metadata_mapping_St
 
struct  xmms_xform_methods_St
 Methods provided by an xform plugin. More...
 

Macros

#define XMMS_XFORM_API_VERSION   7
 
#define XMMS_XFORM_PLUGIN_DEFINE(shname, name, ver, desc, setupfunc)   XMMS_PLUGIN_DEFINE(XMMS_PLUGIN_TYPE_XFORM, XMMS_XFORM_API_VERSION, shname, name, ver, desc, (gboolean (*)(gpointer))setupfunc)
 Declare an xform plugin.
 
#define XMMS_XFORM_METHODS_INIT(m)   memset (&m, 0, sizeof (xmms_xform_methods_t))
 
#define xmms_xform_auxdata_get_int   xmms_xform_auxdata_get_int32
 
#define XMMS_XFORM_BROWSE_FLAG_DIR   (1 << 0)
 
#define XMMS_XFORM_MAX_LINE_SIZE   1024
 

Typedefs

typedef struct xmms_xform_plugin_St xmms_xform_plugin_t
 Xform plugin.
 
typedef struct xmms_xform_St xmms_xform_t
 
typedef struct xmms_xform_metadata_basic_mapping_St xmms_xform_metadata_basic_mapping_t
 Mapping between format specific and internal metadata naming.
 
typedef gboolean(* xmms_xform_metadata_mapper_func_t) (xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)
 Mapping function that recieves a metadata key and value pair.
 
typedef struct xmms_xform_metadata_mapping_St xmms_xform_metadata_mapping_t
 
typedef enum xmms_xform_seek_mode_E xmms_xform_seek_mode_t
 Seek direction argument.
 
typedef struct xmms_xform_methods_St xmms_xform_methods_t
 Methods provided by an xform plugin.
 

Enumerations

enum  xmms_xform_seek_mode_E { XMMS_XFORM_SEEK_CUR = 1 , XMMS_XFORM_SEEK_SET = 2 , XMMS_XFORM_SEEK_END = 3 }
 Seek direction argument. More...
 

Functions

void xmms_xform_plugin_methods_set (xmms_xform_plugin_t *plugin, xmms_xform_methods_t *methods)
 Should be called once from the plugin's setupfunc.
 
void xmms_xform_plugin_metadata_basic_mapper_init (xmms_xform_plugin_t *xform_plugin, const xmms_xform_metadata_basic_mapping_t *mappings, gint count)
 Configure automatic metadata mapping.
 
void xmms_xform_plugin_metadata_mapper_init (xmms_xform_plugin_t *xform_plugin, const xmms_xform_metadata_basic_mapping_t *basic_mappings, gint basic_count, const xmms_xform_metadata_mapping_t *mappings, gint count)
 Configure automatic metadata mapping.
 
void xmms_xform_plugin_indata_add (xmms_xform_plugin_t *plugin,...)
 Add a valid input type to the plugin.
 
void xmms_xform_plugin_set_out_stream_type (xmms_xform_plugin_t *plugin,...)
 Set a static output type to the plugin.
 
gpointer xmms_xform_private_data_get (xmms_xform_t *xform)
 Get private data for this xform.
 
void xmms_xform_private_data_set (xmms_xform_t *xform, gpointer data)
 Set private data for this xform.
 
void xmms_xform_outdata_type_add (xmms_xform_t *xform,...)
 
void xmms_xform_outdata_type_copy (xmms_xform_t *xform)
 
gboolean xmms_xform_metadata_set_int (xmms_xform_t *xform, const gchar *key, int val)
 Set numeric metadata for the media transformed by this xform.
 
gboolean xmms_xform_metadata_set_str (xmms_xform_t *xform, const gchar *key, const char *val)
 Set string metadata for the media transformed by this xform.
 
gboolean xmms_xform_metadata_has_val (xmms_xform_t *xform, const gchar *key)
 
gboolean xmms_xform_metadata_get_int (xmms_xform_t *xform, const gchar *key, gint *val)
 
gboolean xmms_xform_metadata_get_str (xmms_xform_t *xform, const gchar *key, const gchar **val)
 
gboolean xmms_xform_metadata_parse_number (xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)
 Set numeric metadata for the media by parsing a string value.
 
gboolean xmms_xform_metadata_parse_compilation (xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)
 Set compliation status by performing a number of probes on a value.
 
gboolean xmms_xform_metadata_parse_replay_gain (xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)
 Set string metadata represesting replay gain for the media by parsing a string value.
 
gboolean xmms_xform_metadata_mapper_match (xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)
 Attempt to automatically set a metadata property.
 
void xmms_xform_auxdata_barrier (xmms_xform_t *xform)
 
void xmms_xform_auxdata_set_int (xmms_xform_t *xform, const gchar *key, gint64 val)
 
void xmms_xform_auxdata_set_str (xmms_xform_t *xform, const gchar *key, const gchar *val)
 
void xmms_xform_auxdata_set_bin (xmms_xform_t *xform, const gchar *key, gpointer data, gssize len)
 
gboolean xmms_xform_auxdata_has_val (xmms_xform_t *xform, const gchar *key)
 
gboolean xmms_xform_auxdata_get_int32 (xmms_xform_t *xform, const gchar *key, gint32 *val)
 
gboolean xmms_xform_auxdata_get_int64 (xmms_xform_t *xform, const gchar *key, gint64 *val)
 
gboolean xmms_xform_auxdata_get_str (xmms_xform_t *xform, const gchar *key, const gchar **val)
 
gboolean xmms_xform_auxdata_get_bin (xmms_xform_t *xform, const gchar *key, const guchar **data, gsize *datalen)
 
const char * xmms_xform_indata_get_str (xmms_xform_t *xform, xmms_stream_type_key_t key)
 
gint xmms_xform_indata_get_int (xmms_xform_t *xform, xmms_stream_type_key_t key)
 
gint xmms_xform_peek (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err)
 Preview data from previous xform.
 
gchar * xmms_xform_read_line (xmms_xform_t *xform, gchar *buf, xmms_error_t *err)
 Read one line from previous xform.
 
gint xmms_xform_read (xmms_xform_t *xform, gpointer buf, gint siz, xmms_error_t *err)
 Read data from previous xform.
 
gint64 xmms_xform_seek (xmms_xform_t *xform, gint64 offset, xmms_xform_seek_mode_t whence, xmms_error_t *err)
 Change offset in stream.
 
gboolean xmms_xform_iseos (xmms_xform_t *xform)
 
gboolean xmms_magic_add (const gchar *desc, const gchar *mime,...)
 
gboolean xmms_magic_extension_add (const gchar *mime, const gchar *ext)
 
xmms_config_property_txmms_xform_plugin_config_property_register (xmms_xform_plugin_t *xform_plugin, const gchar *name, const gchar *default_value, xmms_object_handler_t cb, gpointer userdata)
 
xmms_config_property_txmms_xform_plugin_config_lookup (xmms_xform_plugin_t *xform_plugin, const gchar *path)
 
xmms_config_property_txmms_xform_config_lookup (xmms_xform_t *xform, const gchar *path)
 
xmms_medialib_entry_t xmms_xform_entry_get (xmms_xform_t *xform)
 Get the medialib entry played by this xform.
 
const gchar * xmms_xform_get_url (xmms_xform_t *xform)
 
void xmms_xform_browse_add_entry (xmms_xform_t *xform, const gchar *path, guint32 flags)
 
void xmms_xform_browse_add_entry_property (xmms_xform_t *xform, const gchar *key, xmmsv_t *val)
 
void xmms_xform_browse_add_entry_property_str (xmms_xform_t *xform, const gchar *key, const gchar *value)
 
void xmms_xform_browse_add_entry_property_int (xmms_xform_t *xform, const gchar *key, gint value)
 
void xmms_xform_browse_add_symlink (xmms_xform_t *xform, const gchar *basename, const gchar *url)
 
void xmms_xform_browse_add_symlink_args (xmms_xform_t *xform, const gchar *basename, const gchar *url, gint nargs, char **args)
 

Detailed Description

XForm API

An xform (transform) is something that reads data and applies some kind of transformation to it such as decoding or demuxing or applying an effect.

The xform api is designed to allow xforms to be connected in a chain where each xform does a different transformation step. Each xform provides a "read" method, which should return transformed data and when it needs more input data, it should call the read method of the previous xform in the chain.

The type of the data flowing from one xform to another is described by an xmms_stream_type_t. So an xform registers which xmms_stream_type_t it wants as input and when initialised it tells what type the output data is. This allows the chain of xforms to easily be built.

Macro Definition Documentation

◆ XMMS_XFORM_API_VERSION

#define XMMS_XFORM_API_VERSION   7

Referenced by xmms_plugin_load().

◆ xmms_xform_auxdata_get_int

#define xmms_xform_auxdata_get_int   xmms_xform_auxdata_get_int32

◆ XMMS_XFORM_BROWSE_FLAG_DIR

#define XMMS_XFORM_BROWSE_FLAG_DIR   (1 << 0)

◆ XMMS_XFORM_MAX_LINE_SIZE

#define XMMS_XFORM_MAX_LINE_SIZE   1024

Referenced by xmms_xform_read_line().

◆ XMMS_XFORM_METHODS_INIT

#define XMMS_XFORM_METHODS_INIT ( m)    memset (&m, 0, sizeof (xmms_xform_methods_t))

◆ XMMS_XFORM_PLUGIN_DEFINE

#define XMMS_XFORM_PLUGIN_DEFINE ( shname,
name,
ver,
desc,
setupfunc )   XMMS_PLUGIN_DEFINE(XMMS_PLUGIN_TYPE_XFORM, XMMS_XFORM_API_VERSION, shname, name, ver, desc, (gboolean (*)(gpointer))setupfunc)

Declare an xform plugin.

Use this macro ONCE for each plugin.

Parameters
shnameShort name of the plugin, should not contain any special characters, just a-z A-Z 0-9 and _.
nameFull name, display name for plugin.
verVersion of plugin, as string.
descDescription of plugin and its uses.
setupfuncFunction to be called when initializing plugin.

example: XMMS_XFORM_PLUGIN_DEFINE("example", "Example decoder", "1.3.37-beta", "Decoder for playing example files", xmms_example_setup);

Typedef Documentation

◆ xmms_xform_metadata_basic_mapping_t

Mapping between format specific and internal metadata naming.

◆ xmms_xform_metadata_mapper_func_t

typedef gboolean(* xmms_xform_metadata_mapper_func_t) (xmms_xform_t *xform, const gchar *key, const gchar *value, gsize length)

Mapping function that recieves a metadata key and value pair.

◆ xmms_xform_metadata_mapping_t

◆ xmms_xform_methods_t

Methods provided by an xform plugin.

◆ xmms_xform_plugin_t

typedef struct xmms_xform_plugin_St xmms_xform_plugin_t

Xform plugin.

◆ xmms_xform_seek_mode_t

Seek direction argument.

◆ xmms_xform_t

typedef struct xmms_xform_St xmms_xform_t

Enumeration Type Documentation

◆ xmms_xform_seek_mode_E

Seek direction argument.

Enumerator
XMMS_XFORM_SEEK_CUR 
XMMS_XFORM_SEEK_SET 
XMMS_XFORM_SEEK_END 

Function Documentation

◆ xmms_magic_add()

gboolean xmms_magic_add ( const gchar * desc,
const gchar * mime,
... )

◆ xmms_magic_extension_add()

gboolean xmms_magic_extension_add ( const gchar * mime,
const gchar * ext )

◆ xmms_xform_auxdata_barrier()

void xmms_xform_auxdata_barrier ( xmms_xform_t * xform)

◆ xmms_xform_auxdata_get_bin()

gboolean xmms_xform_auxdata_get_bin ( xmms_xform_t * xform,
const gchar * key,
const guchar ** data,
gsize * datalen )

◆ xmms_xform_auxdata_get_int32()

gboolean xmms_xform_auxdata_get_int32 ( xmms_xform_t * xform,
const gchar * key,
gint32 * val )

◆ xmms_xform_auxdata_get_int64()

gboolean xmms_xform_auxdata_get_int64 ( xmms_xform_t * xform,
const gchar * key,
gint64 * val )

◆ xmms_xform_auxdata_get_str()

gboolean xmms_xform_auxdata_get_str ( xmms_xform_t * xform,
const gchar * key,
const gchar ** val )

◆ xmms_xform_auxdata_has_val()

gboolean xmms_xform_auxdata_has_val ( xmms_xform_t * xform,
const gchar * key )

◆ xmms_xform_auxdata_set_bin()

void xmms_xform_auxdata_set_bin ( xmms_xform_t * xform,
const gchar * key,
gpointer data,
gssize len )

◆ xmms_xform_auxdata_set_int()

void xmms_xform_auxdata_set_int ( xmms_xform_t * xform,
const gchar * key,
gint64 val )

◆ xmms_xform_auxdata_set_str()

void xmms_xform_auxdata_set_str ( xmms_xform_t * xform,
const gchar * key,
const gchar * val )

◆ xmms_xform_browse_add_entry()

void xmms_xform_browse_add_entry ( xmms_xform_t * xform,
const gchar * path,
guint32 flags )

◆ xmms_xform_browse_add_entry_property()

void xmms_xform_browse_add_entry_property ( xmms_xform_t * xform,
const gchar * key,
xmmsv_t * val )

◆ xmms_xform_browse_add_entry_property_int()

void xmms_xform_browse_add_entry_property_int ( xmms_xform_t * xform,
const gchar * key,
gint value )

◆ xmms_xform_browse_add_entry_property_str()

void xmms_xform_browse_add_entry_property_str ( xmms_xform_t * xform,
const gchar * key,
const gchar * value )

◆ xmms_xform_browse_add_symlink()

void xmms_xform_browse_add_symlink ( xmms_xform_t * xform,
const gchar * basename,
const gchar * url )

◆ xmms_xform_browse_add_symlink_args()

void xmms_xform_browse_add_symlink_args ( xmms_xform_t * xform,
const gchar * basename,
const gchar * url,
gint nargs,
char ** args )

◆ xmms_xform_config_lookup()

xmms_config_property_t * xmms_xform_config_lookup ( xmms_xform_t * xform,
const gchar * path )

◆ xmms_xform_entry_get()

xmms_medialib_entry_t xmms_xform_entry_get ( xmms_xform_t * xform)

Get the medialib entry played by this xform.

Parameters
xform
Returns

◆ xmms_xform_get_url()

const gchar * xmms_xform_get_url ( xmms_xform_t * xform)

◆ xmms_xform_indata_get_int()

gint xmms_xform_indata_get_int ( xmms_xform_t * xform,
xmms_stream_type_key_t key )

◆ xmms_xform_indata_get_str()

const char * xmms_xform_indata_get_str ( xmms_xform_t * xform,
xmms_stream_type_key_t key )

◆ xmms_xform_iseos()

gboolean xmms_xform_iseos ( xmms_xform_t * xform)

◆ xmms_xform_metadata_get_int()

gboolean xmms_xform_metadata_get_int ( xmms_xform_t * xform,
const gchar * key,
gint * val )

◆ xmms_xform_metadata_get_str()

gboolean xmms_xform_metadata_get_str ( xmms_xform_t * xform,
const gchar * key,
const gchar ** val )

◆ xmms_xform_metadata_has_val()

gboolean xmms_xform_metadata_has_val ( xmms_xform_t * xform,
const gchar * key )

◆ xmms_xform_metadata_mapper_match()

gboolean xmms_xform_metadata_mapper_match ( xmms_xform_t * xform,
const gchar * key,
const gchar * value,
gsize length )

Attempt to automatically set a metadata property.

Parameters
xformcurrent xform
keythe name of a key found by the xform
valuethe corresponding value found by the xform
lengththe length of the value, optional for NULL terminated values
Returns
TRUE if the configured metadata mapper marshalled the key/value into a property

◆ xmms_xform_metadata_parse_compilation()

gboolean xmms_xform_metadata_parse_compilation ( xmms_xform_t * xform,
const gchar * key,
const gchar * value,
gsize length )

Set compliation status by performing a number of probes on a value.

First check if the value is an integer (0 or 1), next check if the string matches the MusicBrainz Artist ID for various artists, and then finally see if the string equals 'Various Artists' which is usually the albumartist in the case of compilations.

Parameters
xformcurrent xform
keyMetadatum key to set. Should preferably be XMMS_MEDIALIB_ENTRY_PROPERTY_COMPILATION.
valThe value to interpret as compliation or not.
Returns
TRUE if the key now maps to the suggested value, otherwise FALSE.

◆ xmms_xform_metadata_parse_number()

gboolean xmms_xform_metadata_parse_number ( xmms_xform_t * xform,
const gchar * key,
const gchar * value,
gsize length )

Set numeric metadata for the media by parsing a string value.

Parameters
xformcurrent xform
keyMetadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
valThe value to parse to an integer.
Returns
TRUE if the key now maps to the suggested value, otherwise FALSE.

◆ xmms_xform_metadata_parse_replay_gain()

gboolean xmms_xform_metadata_parse_replay_gain ( xmms_xform_t * xform,
const gchar * key,
const gchar * value,
gsize length )

Set string metadata represesting replay gain for the media by parsing a string value.

Parameters
xformcurrent xform
keyMetadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
valThe value to interpret as replay gain.
Returns
TRUE if the key now maps to the suggested value, otherwise FALSE.

◆ xmms_xform_metadata_set_int()

gboolean xmms_xform_metadata_set_int ( xmms_xform_t * xform,
const gchar * key,
int val )

Set numeric metadata for the media transformed by this xform.

Parameters
xform
keyMetadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val
Returns
TRUE if the key now maps to the suggested value, otherwise FALSE.

◆ xmms_xform_metadata_set_str()

gboolean xmms_xform_metadata_set_str ( xmms_xform_t * xform,
const gchar * key,
const char * val )

Set string metadata for the media transformed by this xform.

Parameters
xform
keyMetadatum key to set. Should preferably be one of the XMMS_MEDIALIB_ENTRY_PROPERTY_* values.
val
Returns
TRUE if the key now maps to the suggested value, otherwise FALSE.

◆ xmms_xform_outdata_type_add()

void xmms_xform_outdata_type_add ( xmms_xform_t * xform,
... )

Referenced by xmms_xform_browse().

◆ xmms_xform_outdata_type_copy()

void xmms_xform_outdata_type_copy ( xmms_xform_t * xform)

◆ xmms_xform_peek()

gint xmms_xform_peek ( xmms_xform_t * xform,
gpointer buf,
gint siz,
xmms_error_t * err )

Preview data from previous xform.

Allows an xform to look at its input data without consuming it so that a subsequent call to xmms_xform_read will get the same data. Up to siz bytes are read into the supplied buffer starting at buf. If siz is less than one xmms_xform_read just returns zero. On error -1 is returned and the error is stored in the supplied xmms_error_t. On end of stream zero is returned.

Parameters
xform
bufbuffer to read data into
sizsize of buffer
errerror container which is filled in if error occours.
Returns
the number of bytes read or -1 to indicate error and 0 when end of stream.

◆ xmms_xform_plugin_config_lookup()

xmms_config_property_t * xmms_xform_plugin_config_lookup ( xmms_xform_plugin_t * xform_plugin,
const gchar * path )

◆ xmms_xform_plugin_config_property_register()

xmms_config_property_t * xmms_xform_plugin_config_property_register ( xmms_xform_plugin_t * xform_plugin,
const gchar * name,
const gchar * default_value,
xmms_object_handler_t cb,
gpointer userdata )

◆ xmms_xform_plugin_indata_add()

void xmms_xform_plugin_indata_add ( xmms_xform_plugin_t * plugin,
... )

Add a valid input type to the plugin.

The varargs should contain key-value pairs terminated with XMMS_STREAM_TYPE_END.

Should be called from the plugin's setupfunc.

Parameters
pluginthe plugin
...variable length arguments, terminated with XMMS_STREAM_TYPE_END

example: xmms_xform_plugin_indata_add (plugin, XMMS_STREAM_TYPE_MIMETYPE, "application/example", XMMS_STREAM_TYPE_END);

◆ xmms_xform_plugin_metadata_basic_mapper_init()

void xmms_xform_plugin_metadata_basic_mapper_init ( xmms_xform_plugin_t * xform_plugin,
const xmms_xform_metadata_basic_mapping_t * mappings,
gint count )

Configure automatic metadata mapping.

Parameters
xform_pluginthe plugin
mappingsmapping from format specific naming to internal naming.
countthe number of properties

◆ xmms_xform_plugin_metadata_mapper_init()

void xmms_xform_plugin_metadata_mapper_init ( xmms_xform_plugin_t * xform_plugin,
const xmms_xform_metadata_basic_mapping_t * basic_mappings,
gint basic_count,
const xmms_xform_metadata_mapping_t * mappings,
gint count )

Configure automatic metadata mapping.

Parameters
xform_pluginthe plugin
basic_mappingsmapping from format specific naming to internal naming.
basic_countthe number of properties
mappingscustom mapping from format specific naming to a function that will marshall the property.
countthe number of custom properties

◆ xmms_xform_plugin_methods_set()

void xmms_xform_plugin_methods_set ( xmms_xform_plugin_t * plugin,
xmms_xform_methods_t * methods )

Should be called once from the plugin's setupfunc.

◆ xmms_xform_plugin_set_out_stream_type()

void xmms_xform_plugin_set_out_stream_type ( xmms_xform_plugin_t * plugin,
... )

Set a static output type to the plugin.

The output stream type is used as a default if the plugin doesn't override this at runtime.

Should be called from the plugin's setupfunc.

Parameters
pluginthe plugin
...variable length arguments, terminated with XMMS_STREAM_TYPE_END

example: xmms_xform_plugin_set_out_stream_type (plugin, XMMS_STREAM_TYPE_MIMETYPE, "application/x-xmms2-playlist-entries", XMMS_STREAM_TYPE_END);

◆ xmms_xform_private_data_get()

gpointer xmms_xform_private_data_get ( xmms_xform_t * xform)

Get private data for this xform.

Parameters
xformcurrent xform
Returns
the data set with xmms_xform_private_data_set

◆ xmms_xform_private_data_set()

void xmms_xform_private_data_set ( xmms_xform_t * xform,
gpointer data )

Set private data for this xform.

Allows keeping information across calls to methods of the xform. Usually set from init method and accessed with xmms_xform_private_data_get in read, seek and destroy methods.

Parameters
xformcurrent xform
data

◆ xmms_xform_read()

gint xmms_xform_read ( xmms_xform_t * xform,
gpointer buf,
gint siz,
xmms_error_t * err )

Read data from previous xform.

Reads up to siz bytes into the supplied buffer starting at buf. If siz is less than one xmms_xform_read just returns zero. On error -1 is returned and the error is stored in the supplied xmms_error_t. On end of stream zero is returned.

Parameters
xform
bufbuffer to read data into
sizsize of buffer
errerror container which is filled in if error occours.
Returns
the number of bytes read or -1 to indicate error and 0 when end of stream.

Referenced by xmms_xform_read_line().

◆ xmms_xform_read_line()

gchar * xmms_xform_read_line ( xmms_xform_t * xform,
gchar * buf,
xmms_error_t * err )

Read one line from previous xform.

Reads a line from the prev xform into buf.

Parameters
xform
bufbuffer to write the line to, should be at least XMMS_XFORM_MAX_LINE_SIZE
errerror container which is filled in if error occours.
Returns
the line read from the parent or NULL to indicate error.

◆ xmms_xform_seek()

gint64 xmms_xform_seek ( xmms_xform_t * xform,
gint64 offset,
xmms_xform_seek_mode_t whence,
xmms_error_t * err )

Change offset in stream.

Tries to change the offset from which data is read.

Parameters
xform
offsetoffset to seek to, measured in "natural" units
whenceone of XMMS_XFORM_SEEK_{CUR,END,SET}
errerror container which is filled in if error occours.
Returns
new offset in stream, or -1 on error.