Hacker Guide/How To Write a Module

Introduction to modules writer guide

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

You MUST read VLC Core and Modules and How VLC loads modules before reading this howto.

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

Git and Repository integration

Git

If you plan to submit your work to VLC upstream, be sure to look at the git introduction and check the [[Git#Submitting_patches_to_the_vlc-devel_or_x264-devel|send patches part].

Compiling your module

First, find the right place under modules/ to add your new code.

1. If you are adding a one-file module to the repository, just add its sources to the Modules.am in the same folder.
2. If you are adding a bigger modules to the repository:
   • create a new directory
   • create a new Modules.am, inside that directory.
   • Add a corresponding Makefile line at the end of configure.ac for this new Modules.am.

To have the module built, you need to use VLC_ADD_PLUGIN or PKG_ENABLE_MODULES_VLC inside the 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 && ./configure

Loading your module

VLC keeps the cache of its modules (in ~/.cache/vlc/ on Linux), you'll have to delete it (or use vlc --reset-plugins-cache) so that your module gets loaded.

Then use vlc -vvv --color --list to check that your plugin is seen by VLC.

You should also see it in the plugins dialog of the Qt interface (Linux and Windows).

Example of an empty module

We will start with a small example, so you can understand it better.

/*****************************************************************************
 * 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 )
{
}

Detailed 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") );
    set_category( CAT_INPUT );
    set_subcategory( SUBCAT_INPUT_ACCESS );

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

Categories and SubCategories

You should use one of the predefined categories. The categories include:

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

You should use one of predefined sub-categories too.

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

Configuration and Parameters Options

You will need options for your module. Defining new options is easy.

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

Close(vlc_object_t *)

This page is part of official VLC media player Documentation (User Guide • Streaming HowTo • Hacker Guide • Modules)
Please read the Documentation Editing Guidelines before you edit the documentation

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.