How to Develop Kurento Modules

You can expand the Kurento Media Server developing your own modules. There are two flavors of Kurento modules:

  • Modules based on OpenCV. This kind of modules are recommended if you would like to develop a computer vision filter.
  • Modules based on GStreamer. This kind of modules are more powerful but also they are more difficult to develop. Skills in GStreamer development are necessary.

The starting point to develop a filter is create the filter structure. For this task, you can use the kurento-module-scaffold tool. This tool is distributed with the kurento-media-server-6.0-dev package. To install this tool run this command in the shell:

sudo apt-get install kurento-media-server-6.0-dev

The tool usage is different depending on the chosen flavor:

  1. OpenCV module:
kurento-module-scaffold.sh <module_name> <output_directory> opencv_filter
  1. Gstreamer module:
kurento-module-scaffold.sh <module_name> <output_directory>

The tool generates the folder tree, all the CmakeLists.txt files necessaries and example files of Kurento module descriptor files (.kmd). These files describe our modules, the constructor, the methods, the properties, the events and the complex types defined by the developer.

Once, kmd files are completed we can generate code. The tool kurento-module-creator generates glue code to server-side. From the root directory:

cd build
cmake ..

The following section details how to create your module depending on the filter type you chose (OpenCV or GStreamer):

OpenCV module

We have four files in src/server/implementation:

ModuleNameImpl.cpp
ModuleNameImpl.hpp
ModuleNameOpenCVImpl.cpp
ModuleNameOpenCVImpl.hpp

The first two files should not be modified. The last two files will contain the logic of your module. The file ModuleNameOpenCVImpl.cpp contains functions to deal with the methods and the parameters (you must implement the logic). Also, this file contains a function called process. This function will be called with each new frame, thus you must implement the logic of your filter inside this function.

GStreamer module

In this case, we have two directories inside the src folder. The gst-plugins folder contains the implementation of your GStreamer element (the kurento-module-scaffold generates a dummy filter). Inside the server/objects folder you have two files:

ModuleNameImpl.cpp
ModuleNameImpl.hpp

In the file ModuleNameImpl.cpp you have to invoke the methods of your GStreamer element. The module logic will be implemented in the GStreamer element.

For both kind of modules

If you need extra compilation dependencies you can add compilation rules to the kurento-module-creator using the function generate_code in the CmakeLists.txt file in src/server. The following parameters are available:

  • MODELS (required): This parameter receives the folders where the models (.kmd files) are located.

  • INTERFACE_LIB_EXTRA_SOURCES, INTERFACE_LIB_EXTRA_HEADERS, INTERFACE_LIB_EXTRA_INCLUDE_DIRS, INTERFACE_LIB_EXTRA_LIBRARIES: These parameters allow to add additional source code to the static library. Files included in INTERFACE_LIB_EXTRA_HEADERS will be installed in the system as headers for this library. All the parameters accept a list as input.

  • SERVER_IMPL_LIB_EXTRA_SOURCES, SERVER_IMPL_LIB_EXTRA_HEADERS, SERVER_IMPL_LIB_EXTRA_INCLUDE_DIRS, SERVER_IMPL_LIB_EXTRA_LIBRARIES: These parameters allows to add additional source code to the interface library. Files included in SERVER_IMPL_LIB_EXTRA_HEADERS will be installed in the system as headers for this library. All the parameters accept a list as input.

  • MODULE_EXTRA_INCLUDE_DIRS, MODULE_EXTRA_LIBRARIES: These parameters allows to add extra include directories and libraries to the module.

  • SERVER_IMPL_LIB_FIND_CMAKE_EXTRA_LIBRARIES: This parameter receives a list of strings, each string has this format libname[ libversion range] (possible ranges can use symbols AND OR < <= > >= ^ and ~):

    ^ indicates a version compatible using Semantic Versioning

    ~ Indicates a version similar, that can change just last indicated version character

  • SERVER_STUB_DESTINATION (required): The generated code that you may need to modify will be generated on the folder indicated by this parameter.

Once the module logic is implemented and the compilation process is finished, you need to install your module in your system. You can follow two different ways:

You can generate the Debian package (debuild -us -uc) and install it (dpkg -i) or you can define the following environment variables in the file /etc/default/kurento: KURENTO_MODULES_PATH=<module_path>/build/src GST_PLUGIN_PATH=<module_path>/build/src.

Now, you need to generate code for Java or JavaScript to use your module from the client-side.

  • For Java, from the build directory you have to execute cmake .. -DGENERATE_JAVA_CLIENT_PROJECT=TRUE command generates a Java folder with client code. You can run make java_install and your module will be installed in your Maven local repository. To use the module in your Maven project, you have to add the dependency to the pom.xml file:
<dependency>
   <groupId>org.kurento.module</groupId>
   <artifactId>modulename</artifactId>
   <version>moduleversion</version>
</dependency>
  • For JavaScript, you should to execute cmake .. -DGENERATE_JS_CLIENT_PROJECT=TRUE. This command generates a js folder with client code. Now you can add the JavaScript library to use your module in your application manually. Alternatively, you can use Bower (for JavaScript for browser) or NPM (for JavaScript for Node.js). To do that, you should add your JavaScript module as a dependency in your bower.json or package.json file respectively, as follows:
"dependencies": {
   "modulename": "moduleversion"
}

Examples

Simple examples for both kind of modules are available in GitHub:

There are a lot of examples of how to define methods, parameters or events in all our public built-in modules:

Moreover, all our modules are developed using this methodology, for that reason you can take a look to our main modules: