View source for 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''' [[Documentation:Hacker%27s_Guide/Core#VLC_Pipeline_and_Modularity|VLC Core and Modules ]] and [[Documentation:VLC_Modules_Loading|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 [[Git |the git introduction]] and check the [[Git#Submitting_patches_to_the_vlc-devel_or_x264-devel|send patches part]].

=== Compiling your module ===

==== Modules.am ====
First, find the right place under [[Modules_source_tree| 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 {{VLCSourceFile|name=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 {{VLCSourceFile|name=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 {{VLCSourceFile|name=configure.ac}}, you will always need to rerun 
 ./bootstrap && ./configure

=== Troubleshooting ===

Sometimes, it doesn't work, because of some libtool 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)

<pre>find . -name .deps -exec rm -rf \{\} \;</pre>
<pre>./bootstrap</pre>
<pre>./configure</pre>

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:
<pre>./compile</pre>

And finally:
<pre>./vlc --reset-plugins-cache</pre>

'''Mild version'''

Sometimes ''config.status'' is enough:

<pre>find . -name .deps -exec rm -rf \{\} \;</pre>
<pre>./config.status</pre>
<pre>./compile</pre>
<pre>./vlc --reset-plugins-cache</pre>

...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:

<pre>find . -name .deps -exec rm -rf \{\} \;</pre>
<pre>find . -name .libs -exec rm -rf \{\} \;</pre>
<pre>./bootstrap</pre>
<pre>./configure</pre>
<pre>./compile</pre>
<pre>./vlc --reset-plugins-cache</pre>

...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 [[OutOfTreeCompile|out of tree compilation]].

=== 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. 
<pre>/*****************************************************************************
 * Preamble
 *****************************************************************************/

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

#include &lt;vlc_common.h&gt;
#include &lt;vlc_plugin.h&gt;

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

== How to write the module, aka Explanations about the empty module ==

=== Module Descriptor  ===

A {{VLC}} module '''must''' include a ''description'' of itself, and the ''parameters'' it accepts. 

The module descriptor begins with: 
<pre>vlc_module_begin();
</pre> 
You should set some basic information about your module: 
<pre>    set_shortname( _("DVD without menus") );
    set_description( _("DVDRead Input") );
    set_category( CAT_INPUT );
    set_subcategory( SUBCAT_INPUT_ACCESS );
</pre> 
''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 [[Documentation:VLC Modules Loading#How_does_the_loading_of_modules_happens|how VLC loads modules]]'''. 

<br> 

*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 [[Documentation:VLC Modules Loading#Major_Capabilities_of_Modules|capabilities of VLC]]. 

'''Score''' should be an integer, and related to other scores in the same category. Score 0 is a [[Documentation:VLC_Modules_Loading#Score_of_0|special case]].

Definition '''Example''': 
<pre>   set_capability( "testing", 10 )
</pre> 
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 {{VLCSourceFile|name=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: 
<pre> add_integer(name, value, text, longtext, advanced) </pre> 
*'''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.

<br> 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 {{VLCSourceFile|name=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.

=== Open(vlc_object_t *)  ===

The most important function of a module, is the opening: the usually-named Open() function. 
<pre>static int  Open ( vlc_object_t * );</pre> 
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.
<pre>static int  Close ( vlc_object_t * );</pre>

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:
* [[Documentation:Hacker's_Guide/Access|Access]]
* [[Documentation:Hacker's_Guide/Demux|Demux]]
* [[Documentation:Hacker's_Guide/Access_Demux|Access_Demux]]
* Decoder
* Interface
* [[Documentation:Hacker's_Guide/Video_Filters|Video Filter]]
* [[Documentation:Hacker's_Guide/Audio_Filters|Audio Filter]]


{{Documentation}} 

[[Category:Coding]]