Hacker Guide/How To Write a Module

Introduction to modules

VLC is based on many independent modules, like most multimedia frameworks. Each module introduces a new functionnality.

You should read VLC Core and Modules and How VLC loads modules before anything else.

This is a description about how you can write a new module for VLC.

How to write a module

Repository integration and build

To add a module to the repository, just add its sources to a Modules.am file.

If you add a new directory you will need to create a new Modules.am,inside that directory. Do not forget to add a corresponding Makefile line at the end of configure.ac for this new Modules.am file.

To have the module built, you need to add a call to VLC_ADD_PLUGIN or VLC_ADD_BUILTINS to configure.ac with your new module name as argument. Look at other modules for guidelines on how to add build and linkage options.

After changing configure.ac you will always need to rerun bootstrap and configure.

VLC keeps a cache of its modules (in ~/.cache/vlc/ on Linux), so you'll have to delete it (or use vlc --reset-plugins-cache). Then use vlc -vvv --color --list to check that your plugin is seen by VLC.

Example of an empty module

/*****************************************************************************
 * Preamble
 *****************************************************************************/

#ifdef HAVE_CONFIG_H
# include "config.h"
#endif


#include <vlc_common.h>
#include <vlc_plugin.h>


/*****************************************************************************
* Local prototypes.
*****************************************************************************/

static int  Open           ( vlc_object_t * );
static void Close          ( vlc_object_t * );

/*****************************************************************************
 * Module descriptor
 *****************************************************************************/

vlc_module_begin()
    set_shortname( _("testmodule") )
    set_description( _("testmodle plug-in") )
    set_capability( "testing", 0 )
    set_callbacks( Open, Close )
    set_category( CAT_INTERFACE ) /* choose relevant category, default categories in vlc/include/vlc_configuration.h */
vlc_module_end ()


/*****************************************************************************
 * Open: initialize interface
 *****************************************************************************/

static int Open( vlc_object_t *p_this )
{

}

/*****************************************************************************
 * Close: destroy interface
 *****************************************************************************/

static void Close( vlc_object_t *p_this )
{

}

Explanations

Module Descriptor

A VLC media player module must include a description of itself, and the parameters it accepts.

The module descriptor begins with:

vlc_module_begin();

You should set some category information on your module:

    set_shortname( _("DVD without menus") );
    set_description( _("DVDRead Input (DVD without menu support)") );
    set_category( CAT_INPUT );

Note the use of _("") to create a string that needs to be translated.

Predefined Categories include:

• CAT_INTERFACE
• CAT_AUDIO
• CAT_VIDEO
• CAT_INPUT
• CAT_SOUT
• CAT_ADVANCED
• CAT_PLAYLIST

    set_subcategory( SUBCAT_INPUT_ACCESS );

See include/vlc_configuration.h for definition of all categories and sub-categories.

Adding Parameters

All macros take the following argument list:

 add_integer(name, value, p_callback, text, longtext, advc) 

• name is the string that identifies this parameter in the configuration. This name may be used at the command prompt to set the configuration value.
• value is the default value for this parameter,
• p_callback is a function pointer that will be called when the value of this parameter is changed.
  • p_callback is called with the following arguments:

    ( p_this, psz_name, oldval, val, p_config->p_callback_data )

    • p_this is a pointer to a vlc_object_t struct,
    • psz_name is the name of your parameter that is being changed,
    • oldval is the old value of the parameter,
    • val is the new value of the parameter,
    • p_call_back_data is void* data that you can assign for each parameter. Usually NULL.
• text A short description of the parameter,
• longtext A complete description of the parameter,
• advc Boolean, ADVanced Configuration. If TRUE, this parameter will only be displayed when using the --advanced flag. e.g.

vlc -p dvdread --advanced

e.g.

 add_integer("dvdread-angle", 1, NULL, "DVD Angle", "Default DVD Angle", NULL") 

You may add the following parameters to your module:

• add_integer,
• add_string,
• add_float,
• add_bool,
• add_key,
• add_file,
• add_directory,

For complete definitions, see include/vlc_configuration.h