Kurento介绍

Kurento是一个基于Webrtc的音视频通讯平台，用于开发Webrtc应用，它是基于GStreamer流媒体开源框架。

Table of Contents

Installing locally
本地安装
Installing in Docker
在 Docker 安装
Java client code
客户端代码
JavaScript client code
客户端代码
OpenCV module
OpenCV 模块
GStreamer module
GStreamer 模块
For both kind of modules
对于这两种类型的模块
Scaffolding and development
脚手架和开发
Installation and usage
安装和使用
Examples
例子

You can develop your own modules to expand the features of Kurento Media Server. There are two main flavors of Kurento modules:

您可以通过开发自己的模块来扩展Kurento的功能，模块可以是基于OpenCV的计算机视觉应用，也可以是基于GStremer的多媒体应用:

Modules based on OpenCV. These are recommended if you would like to add features such as Computer Vision or Augmented Reality.
如果你想添加诸如计算机视觉或者AR之类的功能，推荐基于OpenCV。
Modules based on GStreamer. This kind of modules provide a generic entry point for media processing within the GStreamer framework. Such modules are more powerful, but also they are more difficult to develop. It is necessary to have good knowledge of GStreamer development.
基于 GStreamer 模块是更底层的扩展方式。这类模块为使用GStreamer 框架中的媒体处理作为通用的入口点。好处是你几乎可以加入任何你想要的功能，强大但也更难开发。你需要对GStreamer 的开发有很好的了解。

The starting point to develop a filter is to create a basic structure for the source code, what we’ll call the scaffolding. This is done with the kurento-module-scaffold tool, which comes included with the kurento-media-server-dev package. To install it, run this command:

类似Rails或Grails开发框架，Kurento同样也提供脚手架工具，用于生成开发扩展模块的基本源代码。这是通过 kurento-module-scaffold 工具完成的，该工具包含在 kurento-media-server-dev 包中。要安装它，运行以下命令:

sudo apt-get update && sudo apt-get install --no-install-recommends 
     kurento-media-server-dev

Now use the scaffold tool to generate code for your new module. For example:

现在可以使用手脚架工具为你的新模块生成代码。例如:

For an OpenCV module:

对于基于 OpenCV 模块:

kurento-module-scaffold MyCvModule cv-module-dir true

For a GStreamer module:

对于 GStreamer 模块:

kurento-module-scaffold MyGstModule gst-module-dir

The scaffolding tool generates a complete folder tree, with all the needed CMakeLists.txt files to build with CMake. You’ll also find empty Kurento Module Descriptor files (.kmd), which must contain a complete description of the module: constructor, methods, properties, events, and the complex types defined by the developer.

脚手架工具会生成一个完整的文件夹，包含使用 CMake所有需要的 CMakeLists.txt 文件，以及空的 Kurento 模块描述符文件(.Kmd) ，它必须包含模块的完整描述: 构造函数、方法、属性、事件和其他复杂的数据类型。

Once your .kmd files have been filled with a complete description of the module, it is time to generate the corresponding server stub code with kurento-module-creator. Run this from the root directory of your module:

一旦你的.kmd 文件已经填写模块的完整描述，就可以使用 kurento-module-creator 生成相应的服务器存根代码了。从你的模块的根目录中运行:

mkdir build/ && cd build/
 cmake ..
 make

The following sections detail how to create your module, depending on the filter type you chose (OpenCV or GStreamer).

下面的小节将详细介绍如何根据您选择的Filter类型(OpenCV 或 GStreamer)创建模块。

OpenCV module
OpenCV 模块

There are several files in src/server/implementation/objects/:

src/server/implementation/objects/中有几个文件:

Impl.cpp
 Impl.hpp
 OpenCVImpl.cpp
 OpenCVImpl.hpp

The first two files contain the server-side implementation of the JSON-RPC API, and should not be modified. The last two files will contain the logic of your module.

前两个文件包含 JSON-RPC API 的服务器端实现，不需要修改。最后两个文件将实现模块的逻辑。

The file OpenCVImpl.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 it.

< ModuleName> OpenCVImpl.cpp 包含处理方法和参数的函数(必须实现逻辑)。此外，该文件还包含一个名为 process 的函数。这个函数将在每个新帧中调用，因此您必须在其中实现Filter的逻辑。

GStreamer module
GStreamer 模块

In this case, these are the files that you’ll find under src/:

在GStreamer模式下，你可以在src/目录下看到以下文件:

src/gst-plugins/ contains the implementation of your GStreamer Element:
src/gst-plugins/包含 GStreamer 元素的实现:
```
gst.cpp
 gst.h
 .c
```
src/server/implementation/objects/ contains the server-side implementation of the JSON-RPC API:
src/server/implementation/objects/包含 JSON-RPC API 的服务器端实现:
```
Impl.cpp
 Impl.hpp
```

In the file Impl.cpp you have to invoke the methods of your GStreamer element. The actual module logic should be implemented in the GStreamer Element.

在文件 < ModuleName> Impl.cpp 中，必须调用 GStreamer 元素的方法。实际的模块逻辑应该在 GStreamer 元素中实现。

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 src/server/CMakeLists.txt file.

如果需要额外的编译依赖项，可以使用 src/server/CMakeLists.txt 文件中的 generate_ code 函数向 kurento-module-creator 添加编译规则。

The following parameters are available:

下列参数可用:

SERVER_STUB_DESTINATION (required)
SERVER_STUB_DESTINATION (必需)
The generated code that you may need to modify will be generated on the folder indicated by this parameter.
指定生成代码的目录位置。
MODELS (required)
MODELS (需要)
This parameter receives the folders where the models (.kmd files) are located.
此参数指定扩展模块描述文件(. kmd 文件)所在的文件夹路径。
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.
这些参数允许向静态库添加额外的源代码。INTERFACE_LIB_EXTRA_HEADERS 中包含的文件将作为此库的头文件安装在系统中。所有参数都接受一个列表作为输入。
SERVER_IMPL_LIB_EXTRA_SOURCES, SERVER_IMPL_LIB_EXTRA_HEADERS, SERVER_IMPL_LIB_EXTRA_INCLUDE_DIRS, SERVER_IMPL_LIB_EXTRA_LIBRARIES
These parameters allow 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.
这些参数允许向接口库添加额外的源代码。SERVER_IMPL_LIB_EXTRA_HEADERS 中包含的文件将作为此库的头安装在系统中。所有参数都接受一个列表作为输入。
MODULE_EXTRA_INCLUDE_DIRS, MODULE_EXTRA_LIBRARIES
These parameters allow 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[]
```
where can use these symbols: AND, OR, <, <=, >, >=, ^, and ~.
其中 < versionrange > 可以使用这些符号: AND、 OR、 < 、 < = 、 > = 、 ^ 和 ~ 。
Note
注意

^ indicates a “compatible” version, under the definition of Semantic Versioning.
^ 表示在语义版本控制定义下的“兼容”版本。
~ indicates a “similar” version, again according to the definition of SemVer.
~ 表示一个“相似”的版本，再次根据 sever 的定义。

Installation and usage
安装和使用

Before being able to use your new module, its binary files must be installed to the host where Kurento Media Server is running. Using a module with Kurento comprises two sides of the same coin:

在能够使用新模块之前，必须将编译的二进制文件安装部署到正在运行 Kurento Media Server 的主机上。每个模块都包含两个部分——服务器端和客户端，他们就像硬币的一体两面:

Install the module. This allows KMS to know about the module, and allows the media server to use it when clients attempt to instantiate a new object that is exported by the module code.
注册安装扩展模块。这允许 KMS 了解模块，并在客户端请求服务时实例化服务相关的处理对象。
Use the module from client applications. Technically this step is optional, but unless your application directly implements the Kurento Protocol, you will want to use the client-side module API. This is done by using client code that gets automatically generated from the Kurento Module Descriptor files (.kmd).
在客户端使用扩展模块的客户端API功能请求相应的功能。严格从技术上讲，这个步骤是可选的，但是除非您的应用程序直接实现了 Kurento 协议，否则您会需要使用扩展模块的客户端 API。这是通过使用从扩展模块描述文件生成的(.Kmd).

Installing locally
本地安装

The recommended way to distribute a module is to build it into a Debian package file (.deb). This is the easiest and most convenient method for end users of the module, as they will just have to perform a simple package installation on any system where KMS is already running. Besides, this doesn’t require the user to know anything about plugin paths or how the module files must be laid out on disk.

推荐的方法是制作 Debian 安装包文件(.deb)。对于最终用户来说，这是最简单方便的，只需要在已经运行 KMS 的系统上执行一个简单的安装命令。

To build a Debian package file, you can either use the kurento-buildpackage tool as described in Create Deb packages, or do it manually by installing and running the appropriate tools:

要构建 Debian 包文件，你可以使用 kurento-buildpackage 工具，或者通过自己手动完成:

# Install dpkg-buildpackage, the Debian package buildersudo apt-get update && sudo apt-get install --no-install-recommends 
     dpkg-dev# Run dpkg-buildpackage to build Debian packagesdpkg-buildpackage -us -uc# Copy the generated packages to their final destinationcp ../.deb /path/to/destination/

The Debian builder tool ends up generating one or more .deb package files in the parent directory from where it was called, together with some additional files that can be ignored. For example:

Debian builder 工具最终生成一个或多个.deb文件，文件被保存在调用它的父目录中，以及其他一些可以忽略的附加文件。例如:

 $ls -1 ../*.*deb../my-gst-module-dev_0.0.1~rc1_amd64.deb../my-gst-module_0.0.1~rc1_amd64.deb</pre><p>Depending on the contents of the module project, the Debian package builder can generate multiple .deb files:</p><p>根据模块项目的内容，Debian 软件包构建器可以生成多个.deb 文件:</p><ul><li><p>The file without any suffix contains the shared library code that has been compiled from our source code. This is the file that end users of the module will need to install in their systems.</p><p>没有任何后缀的文件包含从源代码编译的动态库。这是模块的最终用户需要安装到他们系统中的文件。</p></li><li><p>-dev packages contain header files and are used by other developers to build their software upon the module’s code. This is not needed by end users.</p><p>Dev 包包含头文件，被其他开发人员用来在模块代码上进行二次开发，构建他们自己的软件。最终用户不需要这样做。</p></li><li><p>-doc packages usually contain manpages and other documentation, if the module contained any.</p><p>- doc 包含 手册 和其他文档。</p></li><li><p>-dbg and -dbgsym packages contain the debug symbols that have been extracted from the compilation process. It can be used by other developers to troubleshoot crashes and provide bug reports.</p><p>- dbg 和-dbgsym 包含从编译过程中提取的调试符号。其他开发人员可以使用它来排除故障和提供错误报告。</p></li></ul><p>Now copy and install the package(s) into any Debian- or Ubuntu-based system where KMS is already installed:</p><p>现在将软件包复制并安装到已经安装了 KMS 的 Debian 或 ubuntu 系统中:</p><pre>sudo dpkg -i my-gst-module_0.0.1~rc1_amd64.deb</pre><p>For more information about the process of creating Debian packages, check these resources:</p><p>有关 Debian 软件包创建过程的更多信息，请查看以下资源:</p><ul><li><p><a>Debian Building Tutorial</a></p><p>Debian 构建教程</p></li><li><p><a>Debian Policy Manual</a></p><p>Debian 策略手册</p></li></ul><p><strong>Alternatively</strong>, it is also possible to just build the module and manually copy its binary files to the destination system. You can then define the following environment variables in the file <strong>/etc/default/kurento</strong>, to instruct KMS about where the plugin files have been copied:</p><p>或者，也可以只构建模块并将其二进制文件手动复制到目标系统。然后，您可以在/etc/default/kurento 文件中定义以下环境变量，以便告诉 KMS 插件文件的复制位置:</p><pre>KURENTO_MODULES_PATH+=" /path/to/module" GST_PLUGIN_PATH+=" /path/to/module"</pre><p>KMS will then add these paths to the path lookup it performs at startup, when looking for all available plugins.</p><p>然后 KMS 会将这些路径添加到它在启动时执行的路径查找中，启动时查找所有可用的插件。</p><p>When ready, you should <strong>verify the module installation</strong>. Run KMS twice, with the <strong>--version</strong> and <strong>--list</strong> arguments. The former shows a list of all installed modules and their versions, while the latter prints a list of all the actual MediaObject Factories that clients can invoke with the JSON-RPC API. Your own module should show up in both lists:</p><p>准备好后，您应该验证模块的安装。使用 --version 和 --list 参数运行两次 KMS。前者显示所有已安装模块及其版本的列表，而后者显示客户端可以使用 JSON-RPC API 调用的所有实际 MediaObject Factories 的列表。你自己的模块应该出现在两个列表中:</p><pre>$  /usr/bin/kurento-media-server --version
 Kurento Media Server version: 6.12.0Found modules:    'core' version 6.12.0    'elements' version 6.12.0    'filters' version 6.12.0    'mygstmodule' version 0.0.1~0.gd61e201 $/usr/bin/kurento-media-server --listAvailable factories:    [...]    MyGstModule    mygstmodule.MyGstModule</pre><p><strong><a>Installing in Docker 在 Docker 安装</a></strong></p><p>It is perfectly possible to install and use additional Kurento modules with Docker-based deployments of Kurento Media Server. To do so, first follow any of the installation methods described above, but then instead of copying files to a host server you would add them into a Docker image or container.</p><p>完全可以使用基于 docker 的 krento 媒体服务器部署来安装和使用扩展的 Kurento 模块。要做到这一点，首先要遵循上面的步骤完成扩展模块的开发，然后不要将文件复制到主机服务器，而是将它们添加到 Docker 映像或容器中。</p><p>Our recommendation is to leverage the <a>FROM</a> feature of Dockerfiles, to derive directly from a <a>Kurento Docker image</a>, and create your own fully customized image.</p><p>我们的建议是利用 Dockerfiles 的 FROM 功能，直接从 Kurento Docker 镜像中派生出来，并创建您自己的自定义镜像。</p><p>A <strong>Dockerfile</strong> such as this one would be a good enough starting point:</p><p>以下是一个 Dockerfile 文件的入门示例:</p><pre>FROM kurento/kurento-media-server:latestCOPY my-gst-module_0.0.1~rc1_amd64.deb /RUN dpkg -i /my-gst-module_0.0.1~rc1_amd64.deb</pre><p>Now build the new image:</p><p>现在建立新的镜像:</p><pre>$  docker build --tag kms-with-my-gst-module:latest .Step 1/3 : FROM kurento/kurento-media-server:latestStep 2/3 : COPY my-gst-module_0.0.1_{rc1_amd64.deb /Step 3/3 : RUN dpkg -i /my-gst-module_0.0.1}rc1_amd64.debSuccessfully built d10d3b4a8202Successfully tagged kms-with-my-gst-module:latest

And verify your module is correctly loaded by KMS:

验证您的模块是否被 KMS 正确加载:

 $docker run --rm kms-with-my-gst-module:latest --versionKurento Media Server version: 6.12.0Found modules:    'core' version 6.12.0    'elements' version 6.12.0    'filters' version 6.12.0    'mygstmodule' version 0.0.1~0.gd61e201$  docker run --rm kms-with-my-gst-module:latest --listAvailable factories:    [...]    MyGstModule    mygstmodule.MyGstModule

Java client code 客户端代码

Run this from the root directory of your module:

从扩展模块的根目录中运行:

mkdir build/ && cd build/
 cmake .. -DGENERATE_JAVA_CLIENT_PROJECT=TRUE

This generates a build/java/ directory, containing all the client code. You can now run make java (equivalent to mvn package) to build the Java code and package it, or make java_install (equivalent to mvn install) to build the package and install it into the local Maven repository (typically located at $HOME/.m2/). To use the module in your Maven project, you have to add the dependency to the pom.xml file:</p><p>执行命令会生成一个 build/java/目录，其中包含所有客户机代码。您现在可以运行 make Java (相当于 mvn 包)来构建 Java 代码并对其进行打包，或者使用make Java_install (相当于 mvn install)来构建包并将其安装到本地 Maven 存储库(通常位于$ HOME/.M2/).要在 Maven 项目中使用该模块，必须将依赖项添加到 pom.xml 文件中:


   org.kurento.module
   modulename
   0.0.1

JavaScript client code 客户端代码

Run this from the root directory of your module:

从扩展模块的根目录中运行:

mkdir build/ && cd build/
 cmake .. -DGENERATE_JS_CLIENT_PROJECT=TRUE

This generates a build/js/ directory, containing all the client code. You can now manually copy this code to your application. Alternatively, you can use Bower or NPM. To do that, you should add your JavaScript module as a dependency in your bower.json or package.json file, respectively:

这将生成一个 build/js/目录，其中包含所有客户机代码。现在可以将此代码手动复制到应用程序中，或者使用 Bower或 NPM。使用的时候，你应该分别在 bower.json 或 package.json 文件中添加 JavaScript 模块作为依赖项:

"dependencies": {  "modulename": "0.0.1"}

如何编写Kurento扩展模块

Kurento介绍

你可能感兴趣的:(如何编写Kurento扩展模块)