VStreamerMediaMtx C++ library

v1.0.0

Table of contents

• Overview
• Versions
• Library files
• VStreamerMediaMtx class description
  • VStreamerMediaMtx class declaration
  • getVersion method
  • initVStreamer method
  • isVStreamerInit method
  • setParam (float) method
  • setParam (string) method
  • getParams method
  • executeCommand method
  • sendFrame method
  • closeVStreamer method
  • decodeAndExecuteCommand method method of VStreamer interface
  • encodeSetParamCommand method method of VStreamer interface
  • encodeCommand method method of VStreamer interface
  • decodeCommand method method of VStreamer interface
• Data structures
  • VStreamerCommand enum
  • VStreamerParam enum
• VStreamerParams class description
  • VStreamerParams class declaration
  • Serialize video streamer params
  • Deserialize video streamer params
  • Read params from JSON file and write to JSON file
• Example
• Build and connect to your project
• Run MediaMTX

Overview

The VStreamerMediaMtx C++ library provides RTSP, WebRTC, SRT (optional, not tested in version 1.0.0), RTPM (optional, not tested in version 1.0.0) and HLS (optional, not tested in version 1.0.0) video streaming without audio. The library inherits interface from VStreamer. The library depends on: OpenCV (version >= 4.5) library (running GStreamer pipeline and video scaling, linked, Apache 2.0 license), GStreamer (video encoding and streaming to MediaMTX, run as external process, not included in code), MediaMTX (provides video server, run as external process, not included in code, MIT license), VCodec (not used, defines video codec interface, source code included, Apache 2.0 license), VOverlay (defines video overlay interface, source code included, Apache 2.0 license), FormatConverterOpenCv (provides methods to convert pixel formats, source code included) and ConfigReader (provides functions to read / write JSON files, source code included). The library supports changing RTSP parameters such as: RTSP server port, IP, stream name, user name, password etc. The library works frame-by-frame and accepts video frames in formats: RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12 and YV12. Principle of operation: when user sends frame (call sendFrame(…) function) the library copies video frame to internal buffer. After initialization the library runs internal thread. Internal thread is taking new frame according to FPS (set by user in parameters). After taking new frame the library does frame scaling (according to scaling mode if input frame size different from video stream size) and put overlay information (if overlay engine is initialized by user). After preparing frame the library runs (once) GStreamer pipeline and sends video frame to it. GStreamer pipeline includes video encoder (software or hardware, set by user). GStreamer pipeline streams data to external process MediaMTX (user should run it in advance) which provides video server service for clients. All instances of the library should use the same RTSP port, user name and password, RTSP multicast IP and port. Bellow the working principle:

Key features:

1. All instances of VStreamerMediaMtx class must use the same RTSP server port, user name, password, multicast port and multicast IP. The MediaMTX process provides RTSP server on the same port for all streams (Difference only in stream name). For example: rtsp://127.0.0.1:7031/Camera1Stream1 (first instance of VStreamerMediaMtx), rtsp://127.0.0.1:7031/Camera1Stream2 (second instance of VStreamerMediaMtx) etc.
2. RTSP server port, user name, password, multicast IP and multicast port are configurable in MediaMTX configuration file (mediamtx.yml). To change RTSP server port, user name, password, multicast IP or multicast port user must stop MediaMTX process, change mediamtx.yml file and run MediaMTX process again.
3. The VStreamerMediaMtx supports video overlay (user must initialize VOverlay object if overlay required).
4. VCodec interface not used. The library compatible with Linux operating systems only. The video server compatible with all popular RTSP clients: ffmpeg, gstreamer, VLC, Milestone etc.
5. IMPORTANT: the library uses GStreamer pipeline for video encoding. The library can use software encoders or hardware encoders. Type of codec set by user in parameters. Version 1.0.0 of the library supports following GStreamer software codecs (on CPU): x264enc for H264 video encoding, x265enc for H265 video encoding and jpegenc for JPEG video encoding. The library supports following software codecs: vaapih264enc for H264 video encoding and vaapih265enc for H265 video encoding. JPEG encoding always software (on CPU).

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	15.12.2024	First version.

Library files

The library is supplied only by source code. The user is given a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ---------------------- Main CMake file of the library.
3rdparty ---------------------------- Folder with third-party libraries.
    CMakeLists.txt ------------------ CMake file for to include third-party libraries.
    FormatConverterOpenCv ----------- Folder with FormatConverterOpenCv library source code.
    VStreamer ----------------------- Folder with VStreamer library source code.
src --------------------------------- Folder with library source code.
    CMakeLists.txt ------------------ CMake file of the library.
    VStreamerMediaMtx.cpp ---------- C++ implementation file.
    VStreamerMediaMtx.h ------------ Main library header file.
    VStreamerMediaMtxVersion.h ----- Header file with library version.
    VStreamerMediaMtxVersion.h.in -- CMake service file to generate version file.
example ----------------------------- Folder for test application files.
    CMakeLists.txt ------------------ CMake file of example application.
    main.cpp ------------------------ Source C++ file of example application.

VStreamerMediaMtx class description

VStreamerMediaMtx class declaration

VStreamerMediaMtx class declared in VStreamerMediaMtx.h file. Class declaration:

namespace cr
{
namespace video
{
/// Video streamer based on GStreamer and OpenCv.
class VStreamerMediaMtx : public cr::video::VStreamer
{
public:

    /// Get string of current library version.
    static std::string getVersion();

    /// Class constructor.
    VStreamerMediaMtx();

    /// Class destructor.
    ~VStreamerMediaMtx();

    /// Init video streamer by set of parameters.
    bool initVStreamer(cr::video::VStreamerParams &params,
                       cr::video::VCodec *codec = nullptr,
                       cr::video::VOverlay *overlay = nullptr) override;

    /// Get init status.
    bool isVStreamerInit() override;

    /// Close video streamer.
    void closeVStreamer() override;

    /// Send frame to video streamer.
    bool sendFrame(cr::video::Frame& frame) override;

    /// Set video streamer parameter.
    bool setParam(cr::video::VStreamerParam id, float value) override;

    /// Set video streamer parameter.
    bool setParam(cr::video::VStreamerParam id, std::string value) override;

    /// Get all video streamer parameters.
    void getParams(cr::video::VStreamerParams& params) override;

    /// Execute action command.
    bool executeCommand(cr::video::VStreamerCommand id) override;
};
}
}

getVersion method

The getVersion() method return string of current class version. Method declaration:

static std::string getVersion();

Method can be used without VStreamerMediaMtx class instance:

cout << "VStreamerMediaMtx version: " << VStreamerMediaMtx::getVersion();

Console output:

VStreamerMediaMtx version: 1.0.0

initVStreamer method

The initVStreamer(…) method initializes video server. If server already initialized the method will reinitialize server. If video server parameters changed user does not need to call initVStreamer(…) method to reinitialize server (use setParam(…) method). Method declaration:

bool initVStreamer(cr::video::VStreamerParams &params,
                   cr::video::VCodec *codec = nullptr,
                   cr::video::VOverlay *overlay = nullptr) override;

Parameter	Value
params	VStreamerParams object which includes all parameters for initialization.
codec	Not used. VCodec object pointer.
overlay	VOverlay object pointer for video overlay function.

Returns: TRUE if initialization is done or FALSE if not.

isVStreamerInit method

The isVStreamerInit() method returns video streamer initialization status. Method declaration:

bool isVStreamerInit() override;

Returns: TRUE if the video streamer initialized or FALSE if not.

setParam (string parameter) method

The setParam(…) method sets parameter with string value. Method declaration:

bool setParam(cr::video::VStreamerParam id, std::string value) override;

Parameter	Value
id	Parameter ID according to VStreamerParam enum.
value	Parameter value with string type.

Returns: TRUE if parameter is set or FALSE if not.

setParam (float parameter) method

The setParam(…) method to set parameter with float value. Method declaration:

bool setParam(cr::video::VStreamerParam id, float value) override;

Parameter	Value
id	Parameter ID according to VStreamerParam enum.
value	Parameter value with float type.

Returns: TRUE if parameter is set or FALSE if not.

getParams method

The getParams(…) method to get all parameters that are defined in form of VStreamerParams. Method declaration:

void getParams(cr::video::VStreamerParams& params) override;

Parameter	Value
params	Reference to VStreamerParams object to store all video server parameters.

executeCommand method

The executeCommand(…) method to execute command. Method declaration:

bool executeCommand(cr::video::VStreamerCommand id) override;

Parameter	Value
id	Command ID according to VStreamerCommand enum.

Returns: TRUE if command is executed or FALSE if not.

sendFrame method

The sendFrame(…) method sends video frame to video server for streaming. The method copies frame data to internal buffer. Method declaration:

bool sendFrame(cr::video::Frame& frame) override;

Parameter	Value
frame	Frame object. The method accepts video frames in formats: RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12 and YV12

Returns: TRUE if frame is sent or FALSE if not.

closeVStreamer method

The closeVStreamer() method to close video server if it is open. Method declaration:

void closeVStreamer() override;

decodeAndExecuteCommand method of VStreamer interface

The decodeAndExecuteCommand(…) method decodes and executes command encoded by encodeSetParamCommand(…) and encodeCommand(…) methods on video streamer side. It is a virtual method which means if implementation does not define it, default definition from VStreamer class will be used. Each implementation of the video streamer must provide thread-safe setParam(…) and executeCommand(…) method calls to make default definition of decodeAndExecuteCommand(…) thread-safe. This means that the decodeAndExecuteCommand(…) method can be safely called from any thread. Method declaration:

virtual bool decodeAndExecuteCommand(uint8_t* data, int size);

Parameter	Description
data	Pointer to input command.
size	Size of command.

Returns: TRUE if command decoded (SET_PARAM or COMMAND) and executed (action command or set param command).

encodeSetParamCommand method of VStreamer interface

The encodeSetParamCommand(…) static method to encode command to change any parameter in remote video streamer. To control video streamer remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the VStreamer class contains static methods for encoding the control command. The VStreamer class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) designed to encode SET_PARAM command. Method has two overlays: one for numeric parameters and one for string parameters. Method declaration:

static void encodeSetParamCommand(uint8_t* data, int& size, VStreamerParam id, std::string value);

static void encodeSetParamCommand(uint8_t *data, int &size,  VStreamerParam id, float value);

Parameter	Description
data	Pointer to data buffer for output command. Must have size >= 11.
size	Size of encoded data. Will be minimum 11 bytes.
id	Parameter ID according to VStreamerParam enum.
value	Numeral video streamer parameter value. Only for non string parameters. For string parameters (see VStreamerParam enum) this parameters may have any values.
value	String parameter value (see VStreamerParam enum).

encodeSetParamCommand(…) is static method and used without VStreamer class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Random parameter value.
float outValue = (float)(rand() % 20);
// Encode command.
VStreamer::encodeSetParamCommand(data, size, VStreamerParam::CUSTOM1, outValue);

encodeCommand method of VStreamer interface

The encodeCommand(…) static method to encode command for remote video streamer. To control a video streamer remotely, the developer has to design his own protocol and according to it encode the command and deliver it over the communication channel. To simplify this, the VStreamer class contains static methods for encoding the control command. The VStreamer class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) designed to encode COMMAND (action command). Method declaration:

static void encodeCommand(uint8_t* data, int& size, VStreamerCommand id);

Parameter	Description
data	Pointer to data buffer for output command. Must have size >= 7 bytes.
size	Size of encoded data. Will be 7 bytes.
id	Command ID according to VStreamerCommand enum.

encodeCommand(…) is static method and used without VStreamer class instance. This method used on client side (control system). Command encoding example:

// Buffer for encoded data.
uint8_t data[11];
// Size of encoded data.
int size = 0;
// Encode command.
VStreamer::encodeCommand(data, size, VStreamerCommand::RESTART);

decodeCommand method of VStreamer interface

The decodeCommand(…) static method to decode command on video streamer side (edge device). Method declaration:

static int decodeCommand(uint8_t* data, int size, VStreamerParam& paramId,
                         VStreamerCommand& commandId, float& value,
                         std::string& strValue);

Parameter	Description
data	Pointer to input command.
size	Size of command. Should be minimum 11 bytes for SET_PARAM and 7 bytes for COMMAND.
paramId	Parameter ID according to VStreamerParam enum. After decoding SET_PARAM command the method will return parameter ID.
commandId	Command ID according to VStreamerCommand enum. After decoding COMMAND the method will return command ID.
value	Numeral video streamer parameter value. Only for non string parameters. For string parameters (see VStreamerParam enum) this parameters may have any values.
strValue	String parameter value (see VStreamerParam enum).

Returns: 0 - in case decoding COMMAND, 1 - in case decoding SET_PARAM command or -1 in case errors.

Data structures

VStreamer.h file defines IDs for parameters (VStreamerParam enum) and IDs for commands (VStreamerCommand enum).

VStreamerCommand enum

Enum declaration:

enum class VStreamerCommand
{
    /// Restart.
    RESTART = 1,
    /// Enable. Equal to MODE param.
    ON,
    /// Disable. Equal to MODE params.
    OFF
};

Table 4 - Video stream commands description.

Command	Description
RESTART	Restarts streamer with last VStreamerParams.
ON	Enables streamer if it is disabled.
OFF	Disables streamer if it is enabled.

VStreamerParam enum

Enum declaration:

namespace cr
{
namespace rtsp
{
enum class VStreamerParam
{
    /// Mode: 0 - disabled, 1 - enabled.
    MODE = 1,
    /// Video stream width from 8 to 8192.
    WIDTH,
    /// Video stream height from 8 to 8192.
    HEIGHT,
    /// Streamer IP.
    IP,
    /// Streamer port.
    PORT,
    /// Streamer multicast IP.
    MULTICAST_IP,
    /// Streamer multicast port.
    MULTICAST_PORT,
    /// Streamer user (for rtsp streaming): "" - no user.
    USER,
    /// Streamer password (for rtsp streaming): "" - no password.
    PASSWORD,
    /// Streamer suffix(for rtsp streaming, stream name).
    SUFFIX,
    /// Minimum bitrate for variable bitrate mode, kbps.
    MIN_BITRATE_KBPS,
    /// Maximum bitrate for variable bitrate mode, kbps.
    MAX_BITRATE_KBPS,
    /// Current bitrate, kbps.
    BITRATE_KBPS,
    /// Bitrate mode: 0 - constant bitrate, 1 - variable bitrate.
    BITRATE_MODE,
    /// FPS.
    FPS,
    /// GOP size for H264 and H265 codecs.
    GOP,
    /// H264 profile: 0 - baseline, 1 - main, 2 - high.
    H264_PROFILE,
    /// JPEG quality from 1 to 100% for JPEG codec.
    JPEG_QUALITY,
    /// Codec type: "H264", "HEVC" or "JPEG".
    CODEC,
    /// Scaling mode: 0 - fit, 1 - cut.
    FIT_MODE,
    /// Cycle time, mksec. Calculated by RTSP server.
    CYCLE_TIME_MKSEC,
    /// Overlay mode: false - off, true - on.
    OVERLAY_MODE,
    /// Type of the streamer
    TYPE,
    /// Custom parameter 1.
    CUSTOM1,
    /// Custom parameter 2.
    CUSTOM2,
    /// Custom parameter 3. 
    CUSTOM3
};
}
}

Table 5 - Video streamer params description.

Parameter	Description
MODE	Enable / disable streamer: 0 - disable, 1 - enabled.
WIDTH	Frame width. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
HEIGHT	Frame height. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
IP	RTSP server IP.
PORT	RTSP server port.
MULTICAST_IP	RTSP server multicast IP. Multicast RTSP streaming is enabled by default in MediaMTX. If multicast IP has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
MULTICAST_PORT	RTSP server multicast port. Multicast RTSP streaming is enabled by default in MediaMTX. If multicast port has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
USER	User name for auth. If user name has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
PASSWORD	Password for auth. If password has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
SUFFIX	Stream name for RTSP server.
MIN_BITRATE_KBPS	Not supported by VStreamerMediaMtx library.
MAX_BITRATE_KBPS	Not supported by VStreamerMediaMtx library.
BITRATE_KBPS	Bitrate for H264 and H265 codecs, kbps.
BITRATE_MODE	Not supported by VStreamerMediaMtx library.
FPS	Streamer’s FPS and also encoding FPS. Regardless of the input video frame rate, the streamer will provide the specified FPS.
GOP	H264 or H265 codec GOP size.
H264_PROFILE	H264 encoding profile: 0 - baseline, 1 - main, 2 - high.
JPEG_QUALITY	JPEG encoding quality from 1 to 100.
CODEC	Codec type: H264, H255 or JPEG.
FIT_MODE	Scaling mode: 0 - fit, 1 - crop.
OVERLAY_MODE	Overlay enable / disable: 0 - disable, 1 - enable.
CYCLE_TIME_MKSEC	Read only Cycle timeout, microseconds.
TYPE	Not supported by VStreamerMediaMtx library.
CUSTOM1	Type of codec: 0 - Gstreamer hardware codec vaapih264enc (for H264) or vaapih265enc (for H265), 1 - Gstreamer software codec x264enc (for H264) or vaapih264enc (for H265). For JPEG encoding the library uses always software encoder.
CUSTOM2	Not supported by VStreamerMediaMtx library.
CUSTOM3	Not supported by VStreamerMediaMtx library.

VStreamerParams class description

VStreamerParams class declaration

VStreamerParams class used for video stream initialization (initVStreamer(…) method) or to get all actual params (getParams(…) method). Also VStreamerParams provides structure to write/read params from JSON files (JSON_READABLE macro, see ConfigReader class description) and provide methods to encode and decode params. Class declaration:

namespace cr
{
namespace rtsp
{
class VStreamerParams
{
public:
    /// Streamer mode: false - Off, true - On.
    bool enable{true};
    /// Video stream width from 8 to 8192.
    int width{1280};
    /// Video stream height from 8 to 8192.
    int height{720};
    /// Streamer IP.
    std::string ip{"127.0.0.1"};
    /// Streamer port.
    int port{8554};
    /// Streamer multicast IP.
    std::string multicastIp{"224.1.0.1"};
    /// Streamer multicast port.
    unsigned int multicastPort{18000};
    /// Streamer user (for rtsp streaming): "" - no user.
    std::string user{""};
    /// Streamer password (for rtsp streaming): "" - no password.
    std::string password{""};
    /// Streamer suffix (for rtsp streaming) (stream name).
    std::string suffix{"live"};
    /// Minimum bitrate for variable bitrate mode, kbps.
    int minBitrateKbps{1000};
    /// Maximum bitrate for variable bitrate mode, kbps.
    int maxBitrateKbps{5000};
    /// Current bitrate, kbps.
    int bitrateKbps{3000};
    /// Bitrate mode: 0 - constant bitrate, 1 - variable bitrate.
    int bitrateMode{0};
    /// FPS.
    float fps{30.0f};
    /// GOP size for H264 and H265 codecs.
    int gop{30};
    /// H264 profile: 0 - baseline, 1 - main, 2 - high.
    int h264Profile{0};
    /// JPEG quality from 1 to 100% for JPEG codec.
    int jpegQuality{80};
    /// Codec type: "H264", "HEVC" or "JPEG".
    std::string codec{"H264"};
    /// Scaling mode: 0 - fit, 1 - cut.
    int fitMode{0};
    /// Cycle time, mksec. Calculated by RTSP server.
    int cycleTimeMksec{0};
    /// Overlay mode: false - off, true - on.
    bool overlayMode{true};
    /// type of the streamer
    int type{0};
    /// Custom parameter 1.
    float custom1{0.0f};
    /// Custom parameter 2.
    float custom2{0.0f};
    /// Custom parameter 3.
    float custom3{0.0f};

    JSON_READABLE(VStreamerParams, enable, width, height, ip, port, multicastIp,
                  multicastPort, user, password, suffix, minBitrateKbps,
                  maxBitrateKbps, bitrateKbps, bitrateMode, fps, gop, h264Profile,
                  jpegQuality, codec, fitMode, overlayMode, type, custom1, custom2, custom3)

    /// operator =
    VStreamerParams& operator= (const VStreamerParams& src);

    /// Encode params.
    bool encode(uint8_t* data, int bufferSize, int& size,
                VStreamerParamsMask* mask = nullptr);

    /// Decode params.
    bool decode(uint8_t* data, int dataSize);
};
}
}

Table 6 - Video streamer params description. Some params maybe unsupported by particular video streamer class.

Parameter	Description
enable	Enable/disable streamer: false - disable, true - enabled.
width	Frame width. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
height	Frame height. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
ip	RTSP server IP.
port	RTSP server port.
multicastIp	RTSP server multicast IP. Multicast RTSP streaming is enabled by default in MediaMTX. If multicast IP has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
multicastPort	RTSP server multicast port. Multicast RTSP streaming is enabled by default in MediaMTX. If multicast port has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
user	User name for auth. If user name has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
password	Password for auth. If password has been changed the MediaMTX process must be stepped, mediamtx.yml changed and MediaMTX restarted.
suffix	Stream name for RTSP server.
minBitrateKbps	Not supported by VStreamerMediaMtx library.
maxBitrateKbps	Not supported by VStreamerMediaMtx library.
bitrateKbps	Bitrate for H264 and H265 codecs, kbps.
bitrateMode	Not supported by VStreamerMediaMtx library.
fps	Streamer’s FPS and also encoding FPS. Regardless of the input video frame rate, the streamer will provide the specified FPS.
gop	H264 or H265 codec GOP size.
h264Profile	H264 encoding profile: 0 - baseline, 1 - main, 2 - high.
jpegQuality	JPEG encoding quality from 1 to 100.
codec	Codec type for encoding RAW frames: H264 or HEVC.
fitMode	Scaling mode: 0 - fit, 1 - crop. in case RAW input video frames.
overlayMode	Overlay enable / disable: false - disable, true - enable.
cycleTimeMksec	Read only Cycle timeout, microseconds.
type	Codec type for encoding RAW frames: H264, H255 or JPEG.
custom1	Type of codec: 0 - Gstreamer hardware codec vaapih264enc (for H264) or vaapih265enc (for H265), 1 - Gstreamer software codec x264enc (for H264) or vaapih264enc (for H265). For JPEG encoding the library uses always software encoder.
custom2	Not supported by VStreamerMediaMtx library.
custom3	Not supported by VStreamerMediaMtx library.

Serialize video streamer params

VStreamerParams class provides method encode(…) to serialize video streamer params (fields of VStreamerParams class). Serialization of video streamer params necessary in case when you need to send video streamer params via communication channels. Method provides options to exclude particular parameters from serialization. To do this method inserts binary mask (4 bytes) where each bit represents particular parameter and decode(…) method recognizes it. Method declaration:

bool encode(uint8_t* data, int bufferSize, int& size, VStreamerParamsMask* mask = nullptr);

Parameter	Value
data	Pointer to data buffer.
size	Size of encoded data.
bufferSize	Data buffer size. If buffer size smaller than required, buffer will be filled with fewer parameters.
mask	Parameters mask - pointer to VStreamerParamsMask structure. VStreamerParamsMask (declared in VStreamer.h file) determines flags for each field (parameter) declared in VStreamerParams class. If the user wants to exclude any parameters from serialization, he can put a pointer to the mask. If the user wants to exclude a particular parameter from serialization, he should set the corresponding flag in the VStreamerParams structure.

VStreamerParamsMask structure declaration:

struct VStreamerParamsMask
{
    bool enable{true};
    bool width{true};
    bool height{true};
    bool ip{true};
    bool port{true};
    bool multicastIp{true};
    bool multicastPort{true};
    bool user{true};
    bool password{true};
    bool suffix{true};
    bool minBitrateKbps{true};
    bool maxBitrateKbps{true};
    bool bitrateKbps{true};
    bool bitrateMode{true};
    bool fps{true};
    bool gop{true};
    bool h264Profile{true};
    bool jpegQuality{true};
    bool codec{true};
    bool fitMode{true};
    bool cycleTimeMksec{true};
    bool overlayMode{true};
    bool type{true};
    bool custom1{true};
    bool custom2{true};
    bool custom3{true};
};

Example without parameters mask:

// Prepare random params.
VStreamerParams in;
in.ip = "alsfghljb";
in.port = 0;

// Encode data.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);
cout << "Encoded data size: " << size << " bytes" << endl;

Example without parameters mask:

// Prepare random params.
VStreamerParams in;
in.ip = "alsfghljb";
in.port = 0;

// Prepare params mask.
VStreamerParamsMask mask;
mask.port = false; // Exclude port. Others by default.

// Encode data.
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size, &mask);
cout << "Encoded data size: " << size << " bytes" << endl;

Deserialize video stream params

VStreamerParams class provides method decode(…) to deserialize video streamer params (fields of VStreamerParams class). Deserialization of video streamer params necessary in case when you need to receive video streamer params via communication channels. Method automatically recognizes which parameters were serialized by encode(…) method. Method declaration:

bool decode(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to encode data buffer.
dataSize	Size of data.

Returns: TRUE if data decoded (deserialized) or FALSE if not.

Example:

// Encode data.
VStreamerParams in;
uint8_t data[1024];
int size = 0;
in.encode(data, 1024, size);

cout << "Encoded data size: " << size << " bytes" << endl;

// Decode data.
VStreamerParams out;
if (!out.decode(data, size))
    cout << "Can't decode data" << endl;

Read params from JSON file and write to JSON file

VStreamer library depends on ConfigReader library which provides method to read params from JSON file and to write params to JSON file. Example of writing and reading params to JSON file:

// Write params to file.
VStreamerParams in;
cr::utils::ConfigReader inConfig;
inConfig.set(in, "vStreamerParams");
inConfig.writeToFile("TestVStreamerParams.json");

// Read params from file.
cr::utils::ConfigReader outConfig;
if(!outConfig.readFromFile("TestVStreamerParams.json"))
{
    cout << "Can't open config file" << endl;
    return false;
}

TestVStreamerParams.json will look like:

{
    "vStreamerParams": {
        "bitrateKbps": 207,
        "bitrateMode": 206,
        "codec": "eydiucnksa",
        "custom1": 249.0,
        "custom2": 150.0,
        "custom3": 252.0,
        "enable": false,
        "fitMode": 39,
        "fps": 35.0,
        "gop": 1,
        "h264Profile": 61,
        "height": 61,
        "ip": "afhjaskdm",
        "jpegQuality": 80,
        "maxBitrateKbps": 89,
        "minBitrateKbps": 180,
        "multicastIp": "afhjaskdmasd",
        "multicastPort": 180,
        "overlayMode": true,
        "password": "adafsodjf",
        "port": 226,
        "suffix": "asdasdasd",
        "type": 167,
        "user": "afhidsjfnm",
        "width": 50
    }
}

Example

The application bellow shows VStreamerMediaMtx usage. The application create VStreamerMediaMtx object and initialize it. After the application generates artificial video frames and feeds VStreamerMediaMtx video streamer.

#include <iostream>
#include <chrono>
#include <opencv2/opencv.hpp>
#include "VStreamerMediaMtx.h"

int main(int argc, char **argv)
{
    std::cout << "VStreamerMediaMtx v" <<
    cr::video::VStreamerMediaMtx::getVersion() << " test" << std::endl;
    std::cout << std::endl;
    std::cout << "------------------------------------------" << std::endl;
    std::cout << "Run MediaMTX process in advance" << std::endl;
    std::cout << "------------------------------------------" << std::endl;

    // Set suffix (stream name).
    std::string suffix = "live";
    std::cout << "Set suffix: ";
    std::cin >> suffix;

    // Set RTSP server port.
    int port = 8554;
    std::cout << "Set RTSP server port: ";
    std::cin >> port;

    // Init video streamer params.
    cr::video::VStreamerParams params;
    params.enable = true;
    params.width = 640;
    params.height = 480;
    params.fps = 30.0f;
    params.bitrateKbps = 7000;
    params.gop = 30;
    params.suffix = suffix;
    params.port = port;
    params.codec = "H264";
    params.custom1 = 1.0f; // Software encoder.
    
    // Create video streamer object.
    cr::video::VStreamerMediaMtx *streamer = new cr::video::VStreamerMediaMtx();
    if (!streamer->initVStreamer(params))
    {
        std::cout << "Video streamer init failed" << std::endl;
        return -1;
    }

    // Create frame.
    cr::video::Frame frame =
    cr::video::Frame(params.width, params.height, cr::video::Fourcc::YUV24);

    // Moving object parameters.
    int objectX = 200;
    int objectY = 200;
    int objectVx = 1;
    int objectVy = 1;
    int border = 100;
    int objectSize = 50;
    uint8_t color = 0;

    // Main loop.
    while (true)
    {
        // Move object.
        objectX += objectVx;
        objectY += objectVy;
        if (objectX < border || objectX > params.width - border - objectSize)
            objectVx = -objectVx;
        if (objectY < border || objectY > params.height - border - objectSize)
            objectVy = -objectVy;
    
        // Draw object.
        memset(frame.data, color++, frame.size);
        cv::Mat image(params.height, params.width, CV_8UC3, frame.data);
        cv::rectangle(image, cv::Rect(objectX, objectY, objectSize, objectSize),
                      cv::Scalar(0, 0, 255), -1);        

        // Add frame to streamer.
        streamer->sendFrame(frame);

        // Wait.
        std::this_thread::sleep_for(std::chrono::milliseconds(30));
    }

    return 1;
}

Build and connect to your project

The VStreamerMediaMtx library supports only Linux. Before compiling user must install GStreamer and OpenCV libraries. The library is working together with MediaMTX which is external process (user must run it in advance before using VStreamerMediaMtx library). Commands to install necessary libraries in Linux (Ubuntu or Debian example):

sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev libgstreamer-plugins-bad1.0-dev gstreamer1.0-plugins-base gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly gstreamer1.0-libav gstreamer1.0-tools gstreamer1.0-x gstreamer1.0-alsa gstreamer1.0-gl gstreamer1.0-gtk3 gstreamer1.0-qt5 gstreamer1.0-pulseaudio
sudo apt install gstreamer1.0-rtsp
sudo apt-get install gstreamer1.0-vaapi
sudo apt-get install libopencv-dev

Typical commands to build VStreamerMediaMtx library:

cd VStreamerMediaMtx
mkdir build
cd build
cmake ..
make

If you want connect RtspServer library to your CMake project as source code you can make follow. For example, if your repository has structure:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp

Create 3rdparty folder in your repository VStreamerMediaMtx repository folder there. New structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    RtspServer

Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_VSTREAMER_GST_OPENCV            ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VSTREAMER_GST_OPENCV)
    SET(${PARENT}_VSTREAMER_GST_OPENCV                  ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_VSTREAMER_GST_OPENCV_EXAMPLE          OFF CACHE BOOL "" FORCE)
endif()

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_VSTREAMER_GST_OPENCV)
    add_subdirectory(VStreamerMediaMtx)
endif()

File 3rdparty/CMakeLists.txt adds folder VStreamerMediaMtx to your project and excludes test application and examples from compiling (by default test application and examples excluded from compiling if VStreamerMediaMtx included as sub-repository). Your repository new structure will be:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    VStreamerMediaMtx

Next you need include folder 3rdparty in main CMakeLists.txt file of your repository. Add string at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next you have to include RtspServer library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} RtspServer)

Done!

Run MediaMTX

To use VStreamerMediaMtx library user must run MediaMTX application. To run MediaMTX for C++ code the ChildProcess library can be used. The MediaMTX application uses mediamtx.yml config file. Parameters: RTSP port, multicast port, multicast IP, user name and password are using for all camera streams. If user’s application includes few VStreamerMediaMtx class instances this parameters must be changes for all instances. If user changes multicast port, multicast IP, user name or password the MediaMTX processes mst be stopper, mediamtx.yml config file changed and MediaMTX process launched again. C++ code example to change mediamtx.yml config file:

void modifyMediaMtxConfig(VStreamerParams& params)
{
    // Read MediaMtx config file.
    ifstream inputFile("/home/pi/mediamtx.yml");
    if (!inputFile.is_open())
    {
        g_logger.print(PrintColor::RED, PrintFlag::CONSOLE_AND_FILE) <<
        "[" << __LOGFILENAME__ << "][" << __LINE__ << "] ERROR: " <<
        "Can't read /home/pi/mediamtx.yml" << endl;
        return;
    }

    // Read file line by line.
    string line;
    string fileContent;
    bool userFound = false;
    bool passwordFound = false;
    while (getline(inputFile, line))
    {
        if (line.find("rtspAddress: :") != string::npos)
            line = "rtspAddress: :" + to_string(params.port);
        if (line.find("multicastIPRange:") != string::npos)
            line = "multicastIPRange: " + params.multicastIp + "/16";
        if (line.find("multicastRTPPort:") != string::npos)
            line = "multicastRTPPort: " + to_string(params.multicastPort);
        if (line.find("multicastRTCPPort:") != string::npos)
            line = "multicastRTCPPort: " + to_string(params.multicastPort + 1);
        if (line.find("- user:") != string::npos && !userFound)
        {
            if (params.user != "" && params.password != "")
                line = "- user: " + params.user;
            else
                line = "- user: any";
            userFound = true;
        }
        if (line.find("pass:") != string::npos && !passwordFound)
        {
            if (params.user != "" && params.password != "")
                line = "  pass: " + params.password;
            else
                line = "  pass: ";
            passwordFound = true;
        }
        fileContent += line + "\n";
    }
    inputFile.close();

    // Write new content to file.
    ofstream outputFile("/home/pi/mediamtx.yml");
    if (!outputFile.is_open())
    {
        g_logger.print(PrintColor::RED, PrintFlag::CONSOLE_AND_FILE) <<
        "[" << __LOGFILENAME__ << "][" << __LINE__ << "] ERROR: " <<
        "Can't open /home/pi/mediamtx.yml" << endl;
        return;
    }
    outputFile << fileContent;
    outputFile.close();
}

MediaMTX application can be obtained from MediaMTX releases. Follow instructins from MediaMTX.