Hacker Guide/How To Write a Module
Contents
Introduction to modules writer guide
VLC is based on many independent modules, like most competing multimedia frameworks. Each module introduces a new functionnality.
This article focuses an adding a new module (a.k.a. plug-in) to VLC. You will need to read VLC Core and Modules and How VLC loads modules first, otherwise you will not be able to flesh out the content of your new module.
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 send patches part.
Compiling your module
Modules.am
First, find the right place under modules/ to add your new code.
- If you are adding a one-file module to the repository, just add its sources to the Modules.am in the same folder.
- 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.
For example, the file modules/video_filter/Modules.am tells the build system which source files go into which video filter module.
Note that the indentation in Modules.am uses a tab (ASCII 0x09), not spaces.
configure.ac
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, you shouldn't need to clean it, but you can use vlc --reset-plugins-cache to force a reset.
Then use
vlc -vvv --color --list
to check that your plugin is seen by VLC media player.
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 */
add_integer( "test-angle", 1, "DVD Angle", "Default DVD Angle", false)
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 )
{
}
How to write the module, aka Explanations about the empty module
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 basic information about 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.
Capability and score
The capability is key to the module loading.
It defines the type of module we are dealing with, whether it is an access, a demux, a decoder or else...
Now is the time to re-read how VLC loads modules.
- If VLC needs to load a specific name, it will load it by its name and VLC directly opens this module
- If VLC needs a type of modules ("I need a decoder"), VLC will load all modules matching this capability by decreasing score order until one modules's Open() function (see later) returns VLC_SUCCESS.
See the major types of capabilities of VLC.
Score should be an integer, and related to other scores in the same category. Score 0 is a special case.
Definition Example:
set_capability( "testing", 10 )
This defines a module of "testing" capability and a score of 10.
Configuration Categories and SubCategories
You should use one of the predefined categories for configuration.
The Configuration Categories and Subcategories define where the module will appear in the preferences.
The configuration 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 configuration categories and sub-categories.
Configuration and Parameters Options
You will need options for your module. Defining new options is easy.
All options definitions take the following argument list:
add_integer(name, value, text, longtext, advanced)
- name is the string that identifies this parameter in the configuration. This name is used at the command prompt to set the configuration value.
- value is the default value for this parameter,
- text A short description of the parameter, use _("") to create a string that needs to be translated,
- longtext A complete description of the parameter, use _("") to create a string that needs to be translated,
- advanced Boolean, ADVanced Configuration. If TRUE, this parameter will only be displayed when using the --advanced flag. e.g.
You may add the following options/parameter types to your module:
- add_integer,
- add_string,
- add_float,
- add_bool,
- add_key,
- add_file,
- add_directory,
For complete definitions, see include/vlc_plugin.h
Callback
The opening and closing static functions, detailed afterwards, need to be defined in the descriptor, so VLC can discuss with the module.
The set_callbacks() macro allows you to define 2 parameters: the first parameter is the pf_activate callback, and the second one, pf_deactivate (though the functions are most called "Open" and "Close" respectively). VLC invokes the pf_activate callback if/when it needs a plugin instance providing the correct interface, as declared with the set_capability() macro.
Open(vlc_object_t *)
The most important function of a module, is the opening: the usually-named Open() function.
static int Open ( vlc_object_t * );
The Open() function is called when the VLC core tries to open the module, and wants to load it.
During Open(), setup of structures, devices or I/O, checks should be done. A working open should return VLC_SUCCESS. In all other cases, it will not be considered as loaded.
The Open() function is expected to allocate private data (if any), and set up the private structure.
If the Opening fails, you need to clean-up your own structures.
Close(vlc_object_t *)
The second most important function of a module, is the closing: the usually-named Close() function.
static int Close ( vlc_object_t * );
The Close() function is called when the VLC core tries to close or unload an already-loaded module.
NB: If the Open() function failed, Close() will not get called.
During Close(), close devices or I/O and cleaning of structures should be done. Do not leak memory here!
The Close() function should deallocate private data.
SubModules
Submodules, created in some modules with
add_submodule()
work exactly the same way as modules. They are useful to parent modules, and to share code between modules.
The submodules will be separated in the cache, and will be loaded by VLC in the exact same way as a module.
Modules types
Depending on the module capability, you will need more information, about the necessary functions to implement.
We will detail those here:
- Access
- Demux
- Access_Demux
- Decoder
- Interface
- Video filter
- Audio filter
- Audio output
Module load troubleshooting
Sometimes, it doesn't work, because of some libtool or system bug.
You probably need to go to the root of your VLC source tree, and do something akin to the following. The examples here assume the bash shell.
Medium version (try this first)
find . -name .deps -exec rm -rf \{\} \;
./bootstrap
./configure
The dangerous-looking recursive rm -rf deletes the dependency caches in the source tree.
This ensures that the build system finds your new files. Then you can go on as usual:
./compile
And finally:
./vlc --reset-plugins-cache
Mild version
Sometimes config.status after resetting the .deps cache is enough:
find . -name .deps -exec rm -rf \{\} \;
./config.status
./compile
./vlc --reset-plugins-cache
...but not always, so it may save some headaches to always use the "medium version" above.
Extreme version
If the above didn't help, you can use this more extreme version:
find . -name .deps -exec rm -rf \{\} \;
find . -name .libs -exec rm -rf \{\} \;
./bootstrap
./configure
./compile
./vlc --reset-plugins-cache
...which also deletes library caches. Note that when you do this, you must run configure and not just config.status, because config.status runs configure in --no-create mode, which will not re-create the .libs caches.
Out of Tree Compile
If you need to compile just a module, please read out of tree compilation.
Please read the Documentation Editing Guidelines before you edit the documentation
