VStreamerMediaMtx C++ library

v2.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
  • setMediaMtxPath method
  • sendFrame method
  • closeVStreamer method
  • decodeAndExecuteCommand method of VStreamer interface
  • encodeSetParamCommand method of VStreamer interface
  • encodeCommand method of VStreamer interface
  • decodeCommand 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
• Simple example
• Test application
• Build and connect to your project

Overview

The VStreamerMediaMtx C++ library provides RTSP, WebRTC, SRT (optional, not tested in version 2.0.0), RTMP and HLS video streaming without audio. The library enables multiple video streams (different protocols simultaneously) compatible with all popular video clients. The library is based on the mediamtx video proxy server (run as an external process by the library). The library provides all necessary capabilities for video streaming devices: one video source → one/multiple video streams (RTSP, WebRTC, SRT, RTMP, HLS), multiple video sources → multiple video streams with different protocols. Work principle: the user feeds each video frame (frame-by-frame) in RAW or compressed format to the library, the library resizes the video and applies video overlay (if VOverlay implementation is provided by the user), encodes and then streams video to the mediamtx process with RTP protocol, the mediamtx process receives RTP streams and creates several streams with different protocols (RTSP, WebRTC, SRT, RTMP, HLS). The library will stream video frames as-is in the case of H264, H265 or JPEG input frames. If the user provides RAW frames (not encoded), a VCodec implementation must be provided to the initVStreamer(…) method for video encoding. The library runs an external mediamtx process and restarts it when changing parameters. The library allows users to create multiple streams from different cameras. When the user creates multiple instances of the VStreamerMediaMtx C++ class, only one mediamtx process will be run. The library provides a simple interface and supports different platforms (x86, ARM, etc.). To support video encoding on a particular platform, the user must provide a video codec implementation according to the VCodec interface. The library provides easy integration of mediamtx server capabilities into C++ code. It is compatible with Linux operating systems only.

The library inherits its interface from VStreamer. The library depends on: OpenCV (version >= 4.5) library (video scaling, linked, Apache 2.0 license), mediamtx (provides video server, run as an external process, not included in code, MIT license), VCodec (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), ChildProcess (provides functions to run child processes, source code included) , RtpPusher (provides RTP pushing function to mediamtx process, source code included) and Logger (provides logging functions, source code included).

The library supports all necessary video streaming parameters. Additionally, mediamtx has a config file which includes many additional parameters that can be changed if necessary. The library works frame-by-frame and accepts video frames in the following formats: RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12, YV12, H264 (video resize and overlay not supported), H265 (video resize and overlay not supported) and JPEG (video resize and overlay not supported). The following figure shows the workflow inside the library:

The user must provide the path to the mediamtx executable file (files for different platforms are included in the repository). The library reads the config file, runs the mediamtx external process, and controls it (restarting if necessary to implement necessary parameters). By default, the library runs only one mediamtx process (single mode), but some RTSP clients require a unique strict multicast IP address for each video stream which is not supported by mediamtx. To provide necessary functionality, the library can work in multiple mode (run several mediamtx processes). In case of single mediamtx process mode, all instances of the VStreamerMediaMtx class use the same port for all video streams for external clients. If the user changes one of these parameters in one instance, all other VStreamerMediaMtx instances in the user application will be restarted automatically with new parameters. The mediamtx process provides an 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. In case of multiple mediamtx process mode, each instance of the VStreamerMediaMtx class uses its own port for external clients. If the user changes one of these parameters in one instance, only this instance will be restarted automatically with new parameters. The library provides automatic mediamtx configuration (creates config file) if the user provides a path to the mediamtx executable file. If the user doesn’t provide a path to the mediamtx executable file, the necessary parameters must be changed in the mediamtx configuration file (mediamtx.yml). To change any of them, the user must stop the mediamtx process, change the mediamtx.yml file, and run the mediamtx process again. The following figure shows the main difference between single mediamtx process mode and multiple mediamtx process mode:

Versions

Table 2 - Library versions.

Version	Release date	What’s new
1.0.0	15.12.2024	- First version.
1.1.0	14.01.2025	- Add support of Nvidia Jetson platform. - Add start/stop control for mediamtx.
1.1.1	28.01.2025	- Fix resolution settings and restart issue of mediamtx.
1.1.2	10.02.2025	- Add streamer params to overlay engine.
1.1.3	13.02.2025	- Add check for odd multicast port value.
1.1.4	18.02.2025	- Fix encoding params table in documentation.
1.1.5	27.03.2025	- Fix mutex block according to FPS.
1.1.6	23.06.2025	- Add mtu size to rtspclientsink.
1.1.7	29.06.2025	- Add additional pipeline parameters to reduce latency.
1.1.8	01.07.2025	- Implement checking mediamtx’s RTSP ready status before running pipeline.
1.1.9	17.07.2025	- Set strict multicast IP.
1.1.10	24.07.2025	- Implement detection of multicast ip mask.
1.2.0	08.08.2025	- Add support for unique mediamtx for each stream.
1.3.0	26.09.2025	- Fix resolution change issue. - Add imx platform support.
2.0.0	07.11.2025	- Add support for WebRTC, SRT, RTMP and HLS streaming. - Exclude gstreamer dependency from library. - Implement rtp streaming to mediamtx. - Update VStreamer interface. - Implement metadata support.

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 to include third-party libraries.
    FormatConverterOpenCv ---------- Folder with FormatConverterOpenCv library source code.
    VStreamer ---------------------- Folder with VStreamer library source code.
    ChildProcess ------------------- Folder with ChildProcess library source code.
    RtpPusher ---------------------- Folder with RtpPusher library source code.
    Logger ------------------------- Folder with Logger 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 example application files.
    CMakeLists.txt ----------------- CMake file of example application.
    main.cpp ----------------------- Source C++ file of example application.
test ------------------------------- Folder for test application files.
    CMakeLists.txt ----------------- CMake file of test application.
    main.cpp ----------------------- Source C++ file of test application.
static ----------------------------- Folder for static files.
	linux_amd64 -------------------- MediaMtx folder files for amd64 platforms.
	linux_arm64 -------------------- MediaMtx folder files for arm64 platforms.

VStreamerMediaMtx class description

VStreamerMediaMtx class declaration

The VStreamerMediaMtx class is declared in the VStreamerMediaMtx.h file. Class declaration:

namespace cr
{
namespace video
{
/// Video streamer.
class VStreamerMediaMtx : public cr::video::VStreamer
{
public:

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

    /// 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, uint8_t* userData, int userDataSize) 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;

    /// Set media mtx path.
    static void setMediaMtxPath(std::string path, bool isSingleMediaMTX = true);

};
}
}

getVersion method

The getVersion() method returns a string of the 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: 2.0.0

initVStreamer method

The initVStreamer(…) method initializes the video server. If the server is already initialized, the method will reinitialize the server. If video server parameters are changed, the user does not need to call the initVStreamer(…) method to reinitialize the server (use the 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	VCodec object pointer. It must be provided for video encoding if input video frames are raw frames (not encoded).
overlay	VOverlay object pointer for video overlay function. It should implement overlay in YUV format.

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 a parameter with a string value. Some parameters require modification of the mediamtx.yml file as well. If the path that contains mediamtx is set by using the setMediaMtxPath method, the library will handle creating the required config file/files and all required modifications internally and restart mediamtx properly. If multiple mediamtx is set, mediamtx configuration files will be created in the form mediamtx-<stream_id>.yml where <stream_id> is the index of the instance from 0. For example, if there are two instances of mediamtx, the configuration files will be mediamtx-0.yml and mediamtx-1.yml. If this path is not set, the user is responsible for the configuration of mediamtx.yml and restarting mediamtx.

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 sets a parameter with a float value. Some parameters require modification of the mediamtx.yml file as well. If the path that contains mediamtx and mediamtx.yml is set by using the setMediaMtxPath method, the library will handle all required modifications internally and restart mediamtx properly. If this path is not set, the user is responsible for the configuration of mediamtx.yml and restarting mediamtx. For the list of parameters that require this modification, see Table 2. Also see Table 5 for more information about changing parameters and the behavior of streams. 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 gets all parameters that are defined in the 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.

setMediaMtxPath method

The setMediaMtxPath(…) is a static method to set the path to the mediamtx executable. The method must be called before the first instance of the VStreamerMediaMtx class is initialized. The library will run mediamtx as an additional process and handle all required modifications internally. If path is not set, library shall not perform any operations that require mediamtx process management (for example, changing ports, enabling/disabling streaming protocols, etc.). Method declaration:

static void setMediaMtxPath(std::string path, bool isSingleMediaMTX = true);

Parameter	Value
path	Path that contains the mediamtx executable and mediamtx.yml configuration file. For example, if mediamtx and mediamtx.yml are located in the home folder of user pi, the path should be set as “/home/pi”.
isSingleMediaMTX	If true, the library will run a single instance of mediamtx for all streams. If false, the library will run a separate instance of mediamtx for each stream. Default value is true.

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, uint8_t* userData, int userDataSize) override;

Parameter	Value
frame	Frame object. The method accepts video frames in formats: RGB24, BGR24, YUYV, UYVY, GRAY, YUV24, NV12, NV21, YU12, YV12, H264, HEVC and JPEG.
userData	Pointer to user data buffer. This buffer will be sent along with the video frame.
userDataSize	Size of user data buffer in bytes in case userData is not null.

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

closeVStreamer method

The closeVStreamer() method closes the video server if it is open. Method declaration:

void closeVStreamer() override;

decodeAndExecuteCommand method of VStreamer interface

The decodeAndExecuteCommand(…) method decodes and executes a command encoded by the encodeSetParamCommand(…) and encodeCommand(…) methods on the video streamer side. It is a virtual method which means if the implementation does not define it, the default definition from the VStreamer class will be used. Each implementation of the video streamer must provide thread-safe setParam(…) and executeCommand(…) method calls to make the 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 param.
    OFF,
    /// Generate key frame command.
    GENERATE_KEYFRAME
};

Table 3 - 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.
GENERATE_KEYFRAME	Generate a key frame for the current stream.

VStreamerParam enum

Enum declaration:

namespace cr
{
namespace video
{
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,
    /// RTSP port.
    RTSP_PORT,
    /// RTSPS port.
    RTSPS_PORT,
    /// RTP port.
    RTP_PORT,
    /// WebRTC port.
    WEBRTC_PORT,
    /// HLS port.
    HLS_PORT,
    /// SRT port.
    SRT_PORT,
    /// RTMP port.
    RTMP_PORT,
    /// RTMPS port.
    RTMPS_PORT,
    /// Metadata port.
    METADATA_PORT,
    /// RTSP protocol enable / disable.
    RTSP_MODE,
    /// RTP protocol enable / disable.
    RTP_MODE,
    /// WebRTC protocol enable / disable.
    WEBRTC_MODE,
    /// HLS protocol enable / disable.
    HLS_MODE,
    /// SRT protocol enable / disable.
    SRT_MODE,
    /// RTMP protocol enable / disable.
    RTMP_MODE,
    /// Metadata protocol enable / disable.
    METADATA_MODE,
    /// RTSP multicast IP.
    RTSP_MULTICAST_IP,
    /// RTSP multicast port.
    RTSP_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,
    /// Metadata suffix (stream name).
    METADATA_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 - fill.
    FIT_MODE,
    /// Cycle time, mksec. Calculated by RTSP server.
    CYCLE_TIME_MKSEC,
    /// Overlay mode: false - off, true - on.
    OVERLAY_MODE,
    /// Type of the streamer. Depends on implementation.
    TYPE,
    /// Custom parameter 1.
    CUSTOM1,
    /// Custom parameter 2.
    CUSTOM2,
    /// Custom parameter 3, float.
    CUSTOM3,
    /// Path to openssl key for RTSP, string.
    RTSP_KEY,
    /// Path to openssl certificate for RTSP, string.
    RTSP_CERT,
    /// Path to openssl key for WebRTC, string.
    WEBRTC_KEY,
    /// Path to openssl certificate for WebRTC, string.
    WEBRTC_CERT,
    /// Path to openssl key for HLS, string.
    HLS_KEY,
    /// Path to openssl certificate for HLS, string.
    HLS_CERT,
    /// Path to openssl key for RTMP, string.
    RTMP_KEY,
    /// Path to openssl certificate for RTMP, string.
    RTMP_CERT,
    /// RTSP encryption type, string: "no", "strict", "optional".
    RTSP_ENCRYPTION,
    /// WebRTC encryption type, string: "no", "yes".
    WEBRTC_ENCRYPTION,
    /// RTMP encryption type, string: "no", "strict", "optional".
    RTMP_ENCRYPTION,
    /// HLS encryption type, string: "no", "yes".
    HLS_ENCRYPTION,
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal, 3 - File and terminal.
    LOG_LEVEL
};
}
}

Table 4 - Video streamer params description.

Parameter	Description
MODE	Enable / disable streamer: 0 - disable, 1 - enabled.
WIDTH	Frame width from 8 to 8192. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
HEIGHT	Frame height from 8 to 8192. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
IP	Streamer IP address.
RTSP_PORT	RTSP server port. If port has been changed the mediamtx process will be restarted by the library automatically.
RTSPS_PORT	RTSPS server port. If port has been changed the mediamtx process will be restarted by the library automatically.
RTP_PORT	RTP port. Not directly configurable in mediamtx, handled internally.
WEBRTC_PORT	WebRTC server port. If port has been changed the mediamtx process will be restarted by the library automatically.
HLS_PORT	HLS server port. If port has been changed the mediamtx process will be restarted by the library automatically.
SRT_PORT	SRT server port. If port has been changed the mediamtx process will be restarted by the library automatically.
RTMP_PORT	RTMP server port. If port has been changed the mediamtx process will be restarted by the library automatically.
RTMPS_PORT	RTMPS server port. If port has been changed the mediamtx process will be restarted by the library automatically.
METADATA_PORT	Metadata server port for metadata streaming.
RTSP_MODE	Enable / disable RTSP protocol: 0 - disable, 1 - enable.
RTP_MODE	Enable / disable RTP protocol: 0 - disable, 1 - enable.
WEBRTC_MODE	Enable / disable WebRTC protocol: 0 - disable, 1 - enable.
HLS_MODE	Enable / disable HLS protocol: 0 - disable, 1 - enable.
SRT_MODE	Enable / disable SRT protocol: 0 - disable, 1 - enable.
RTMP_MODE	Enable / disable RTMP protocol: 0 - disable, 1 - enable.
METADATA_MODE	Enable / disable metadata streaming: 0 - disable, 1 - enable.
RTSP_MULTICAST_IP	RTSP server multicast IP. Multicast RTSP streaming is enabled by default in mediamtx. Ip can be set with mask or without mask. If mask is not set, default mask /16 will be used. Example of multicast IP: 239.255.0.1 (in this case /16 will be added by default) or 239.255.0.1/24. The library uses unique multicast port for each stream from IP range set by user.
RTSP_MULTICAST_PORT	RTSP server multicast port. Multicast RTSP streaming is enabled by default in mediamtx. If multicast port has been changed the mediamtx process will be restarted by the library automatically. The library uses one multicast port for all streams.
USER	User name for auth. If user name has been changed the mediamtx process will be restarted by the library automatically.
PASSWORD	Password for auth. If password has been changed the mediamtx process will be restarted by the library automatically.
SUFFIX	Stream name for RTSP server.
METADATA_SUFFIX	Metadata stream name for metadata streaming.
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, HEVC or JPEG.
FIT_MODE	Scaling mode: 0 - fit, 1 - fill.
OVERLAY_MODE	Overlay enable / disable: 0 - disable, 1 - enable.
CYCLE_TIME_MKSEC	Read only Cycle timeout, microseconds.
TYPE	Not supported by VStreamerMediaMtx library.
CUSTOM1	Not supported by VStreamerMediaMtx library.
CUSTOM2	Not supported by VStreamerMediaMtx library.
CUSTOM3	Read only variable that holds the status of mediamtx running. Values: 0 - Single mediamtx for all streams, 1 - Unique mediamtx for each stream.
RTSP_KEY	Path to openssl key for RTSP, string: ”“ for no key.
RTSP_CERT	Path to openssl certificate for RTSP, string: ”“ for no certificate.
WEBRTC_KEY	Path to openssl key for WebRTC, string: ”“ for no key.
WEBRTC_CERT	Path to openssl certificate for WebRTC, string: ”“ for no certificate.
HLS_KEY	Path to openssl key for HLS, string: ”“ for no key.
HLS_CERT	Path to openssl certificate for HLS, string: ”“ for no certificate.
RTMP_KEY	Path to openssl key for RTMP, string: ”“ for no key.
RTMP_CERT	Path to openssl certificate for RTMP, string: ”“ for no certificate.
RTSP_ENCRYPTION	RTSP encryption type, string: “no”, “strict”, “optional”.
WEBRTC_ENCRYPTION	WebRTC encryption type, string: “no”, “yes”.
RTMP_ENCRYPTION	RTMP encryption type, string: “no”, “strict”, “optional”.
HLS_ENCRYPTION	HLS encryption type, string: “no”, “yes”.
LOG_LEVEL	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal, 3 - File and terminal.

All parameters can be updated in VStreamerMediaMtx via overloaded setParam methods that accept float or string values. However, the behavior of VStreamerMediaMtx depends on the parameter being updated and mediamtx instance (see setMediaMtxPath). For single mediamtx instance mode, some parameters are common across all instances, so updating these parameters will restart all instances. Others are unique to each instance and will only restart the current instance, while some parameters are unique to each instance and can be updated without restarting the instance. The following table shows the groups of parameters based on their update behavior:

Table 5 - Parameter Groups

Update Behavior	Parameters
All instances will be restarted automatically	All video server ports related parameters (RTSP, RTMP, WebRTC, HLS, SRT, metadata)
Only the current instance will be restarted	width, height, fps, GOP, H264 profile, JPEG quality, codec, bitrate, suffix, metadata suffix, custom1 (selection of hardware/software codec type)
Update without restart	overlay enable, fit mode, mode, protocol enable flags (RTSP_MODE, RTMP_MODE, WEBRTC_MODE, HLS_MODE, SRT_MODE, METADATA_MODE)

If restart of the related instance is required, all clients should also reconnect to the related stream.

If multiple mediamtx instances are used, each instance will have its own set of parameters, and updating any parameter will only affect the current instance. The behavior of the parameters remains the same as described above, but the changes will not affect other instances. In this case, the user should be aware that the same RTSP port and multicast port are not allowed for different instances, so the user should set a unique RTSP port and multicast port for each instance. If the same ports are set, the initVStreamer(…) method will adjust them automatically. However, the setParam method will not adjust them automatically and the user should handle this manually.

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 video
{
class VStreamerParams
{
public:
    /// Streamer enable / disable (for all protocols): 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"};
    /// RTSP port.
    int rtspPort{8554};
    /// RTSPS port.
    int rtspsPort{8555};
    /// RTP port.
    int rtpPort{5004};
    /// WebRTC port.
    int webRtcPort{7000};
    /// HLS port.
    int hlsPort{8080};
    /// SRT port.
    int srtPort{6000};
    /// RTMP port.
    int rtmpPort{1935};
    /// RTMPS port.
    int rtmpsPort{1936};
    /// Metadata port.
    int metadataPort{9000};
    /// RTSP protocol enable / disable.
    bool rtspEnable{true};
    /// RTP protocol enable / disable.
    bool rtpEnable{true};
    /// WebRTC protocol enable / disable.
    bool webRtcEnable{true};
    /// HLS protocol enable / disable.
    bool hlsEnable{true};
    /// SRT protocol enable / disable.
    bool srtEnable{true};
    /// RTMP protocol enable / disable.
    bool rtmpEnable{true};
    /// Metadata protocol enable / disable.
    bool metadataEnable{false};
    /// RTSP multicast IP.
    std::string rtspMulticastIp{"224.1.0.1"};
    /// RTSP multicast port.
    int rtspMulticastPort{18000};
    /// Streamer user (for rtsp streaming): "" - no user.
    std::string user{""};
    /// Streamer password (for rtsp streaming): "" - no password.
    std::string password{""};
    /// Stream suffix (for rtsp streaming) (stream name).
    std::string suffix{"live"};
    /// Metadata suffix (stream name).
    std::string metadataSuffix{"metadata"};
    /// 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 - fill.
    int fitMode{0};
    /// Cycle time, mksec. Calculated by RTSP server.
    int cycleTimeMksec{0};
    /// Overlay enable / disable: false - off, true - on.
    bool overlayEnable{true};
    /// Type of the streamer. Depends on implementation.
    int type{0};
    /// Custom parameter 1.
    float custom1{0.0f};
    /// Custom parameter 2.
    float custom2{0.0f};
    /// Custom parameter 3.
    float custom3{0.0f};
    /// Path to openssl key for RTSP, string.
    std::string rtspKey{"no"};
    /// Path to openssl certificate for RTSP, string.
    std::string rtspCert{"no"};
    /// Path to openssl key for WebRTC, string.
    std::string webRtcKey{"no"};
    /// Path to openssl certificate for WebRTC, string.
    std::string webRtcCert{"no"};
    /// Path to openssl key for HLS, string.
    std::string hlsKey{"no"};
    /// Path to openssl certificate for HLS, string.
    std::string hlsCert{"no"};
    /// Path to openssl key for RTMP, string.
    std::string rtmpKey{"no"};
    /// Path to openssl certificate for RTMP, string.
    std::string rtmpCert{"no"};
    /// RTSP encryption type, string: "" or "no", "strict", "optional".
    std::string rtspEncryption{"no"};
    /// WebRTC encryption type, string: "" or "no", "yes".
    std::string webRtcEncryption{"no"};
    /// RTMP encryption type, string: "" or "no", "strict", "optional".
    std::string rtmpEncryption{"no"};
    /// HLS encryption type, string: "" or "no", "yes".
    std::string hlsEncryption{"no"};
    /// Logging mode. Values: 0 - Disable, 1 - Only file,
    /// 2 - Only terminal, 3 - File and terminal.
    int logLevel{0};

    JSON_READABLE(VStreamerParams, enable, width, height, ip, rtspPort, rtspsPort, rtpPort,
                  webRtcPort, hlsPort, srtPort, rtmpPort, rtmpsPort, metadataPort,
                  rtspEnable, rtpEnable, webRtcEnable, hlsEnable, srtEnable,
                  rtmpEnable, metadataEnable, rtspMulticastIp,
                  rtspMulticastPort, user, password, suffix, metadataSuffix,
                  minBitrateKbps, maxBitrateKbps, bitrateKbps, bitrateMode, fps,
                  gop, h264Profile, jpegQuality, codec, fitMode, overlayEnable,
                  type, custom1, custom2, custom3, rtspKey, rtspCert, webRtcKey, webRtcCert,
                  hlsKey, hlsCert, rtmpKey, rtmpCert, rtspEncryption,
                  webRtcEncryption, rtmpEncryption, hlsEncryption, logLevel)

    /// 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 may be unsupported by particular video streamer class.

Parameter	Description
enable	Enable/disable streamer: false - disable, true - enabled.
width	Frame width from 8 to 4096. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
height	Frame height from 8 to 4096. Regardless of the resolution of the input video, the streamer will scale the images according to this parameter.
ip	Streamer IP address.
rtspPort	RTSP server port. If port has been changed the mediamtx process will be restarted by the library automatically.
rtspsPort	RTSPS server port. If port has been changed the mediamtx process will be restarted by the library automatically.
rtpPort	RTP port. Not directly configurable in mediamtx, handled internally.
webRtcPort	WebRTC server port. If port has been changed the mediamtx process will be restarted by the library automatically.
hlsPort	HLS server port. If port has been changed the mediamtx process will be restarted by the library automatically.
srtPort	SRT server port. If port has been changed the mediamtx process will be restarted by the library automatically.
rtmpPort	RTMP server port. If port has been changed the mediamtx process will be restarted by the library automatically.
rtmpsPort	RTMPS server port. If port has been changed the mediamtx process will be restarted by the library automatically.
metadataPort	Metadata server port for metadata streaming.
rtspEnable	RTSP protocol enable / disable: false - disable, true - enable.
rtpEnable	RTP protocol enable / disable: false - disable, true - enable.
webRtcEnable	WebRTC protocol enable / disable: false - disable, true - enable.
hlsEnable	HLS protocol enable / disable: false - disable, true - enable.
srtEnable	SRT protocol enable / disable: false - disable, true - enable.
rtmpEnable	RTMP protocol enable / disable: false - disable, true - enable.
metadataEnable	Metadata streaming enable / disable: false - disable, true - enable.
rtspMulticastIp	RTSP server multicast IP. Multicast RTSP streaming is enabled by default in mediamtx. If multicast IP has been changed the mediamtx process will be restarted by the library automatically. Ip can be set with mask or without mask. If mask is not set, default mask /16 will be used. Example of multicast IP: 239.255.0.1 (in this case /16 will be added by default) or 239.255.0.1/24.
rtspMulticastPort	RTSP server multicast port. Multicast RTSP streaming is enabled by default in mediamtx. If multicast port has been changed the mediamtx process will be restarted by the library automatically.
user	User name for auth. If user name has been changed the mediamtx process will be restarted by the library automatically.
password	Password for auth. If password has been changed the mediamtx process will be restarted by the library automatically.
suffix	Stream name for RTSP server.
metadataSuffix	Metadata stream name for metadata streaming.
minBitrateKbps	Minimum bitrate for VBR mode (100..100000 kbps). Adjusts maxBitrateKbps if higher. Applied to codec if present.
maxBitrateKbps	Maximum bitrate for VBR mode (100..100000 kbps). Adjusts minBitrateKbps if lower. Applied to codec if present.
bitrateKbps	Bitrate for H264 and H265 codecs, kbps.
bitrateMode	Bitrate mode: 0 CBR, 1 VBR. Passed to codec when available.
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, HEVC or JPEG.
fitMode	Scaling mode: 0 - fit, 1 - fill in case RAW input video frames.
overlayEnable	Overlay enable / disable: false - disable, true - enable.
cycleTimeMksec	Read only Cycle timeout, microseconds.
type	Not supported by VStreamerMediaMtx library.
custom1	Codec implementation selector (software / hardware). See Table 7.
custom2	Not supported by VStreamerMediaMtx library.
custom3	Read only variable that holds the status of mediamtx running. Values: 0 - Single mediamtx for all streams, 1 - Unique mediamtx for each stream.
rtspKey	Path to openssl key for RTSP, string: ”“ for no key.
rtspCert	Path to openssl certificate for RTSP, string: ”“ for no certificate.
webRtcKey	Path to openssl key for WebRTC, string: ”“ for no key.
webRtcCert	Path to openssl certificate for WebRTC, string: ”“ for no certificate.
hlsKey	Path to openssl key for HLS, string: ”“ for no key.
hlsCert	Path to openssl certificate for HLS, string: ”“ for no certificate.
rtmpKey	Path to openssl key for RTMP, string: ”“ for no key.
rtmpCert	Path to openssl certificate for RTMP, string: ”“ for no certificate.
rtspEncryption	RTSP encryption type, string: “no”, “strict”, “optional”.
webRtcEncryption	WebRTC encryption type, string: “no”, “yes”.
rtmpEncryption	RTMP encryption type, string: “no”, “strict”, “optional”.
hlsEncryption	HLS encryption type, string: “no”, “yes”.
logLevel	Logging mode. Values: 0 - Disable, 1 - Only file, 2 - Only terminal, 3 - File and terminal.

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 rtspPort{true};
    bool rtspsPort{true};
    bool rtpPort{true};
    bool webRtcPort{true};
    bool hlsPort{true};
    bool srtPort{true};
    bool rtmpPort{true};
    bool rtmpsPort{true};
    bool metadataPort{true};
    bool rtspEnable{true};
    bool rtpEnable{true};
    bool webRtcEnable{true};
    bool hlsEnable{true};
    bool srtEnable{true};
    bool rtmpEnable{true};
    bool metadataEnable{true};
    bool rtspMulticastIp{true};
    bool rtspMulticastPort{true};
    bool user{true};
    bool password{true};
    bool suffix{true};
    bool metadataSuffix{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 overlayEnable{true};
    bool type{true};
    bool custom1{true};
    bool custom2{true};
    bool custom3{true};
    bool rtspKey{true};
    bool rtspCert{true};
    bool webRtcKey{true};
    bool webRtcCert{true};
    bool hlsKey{true};
    bool hlsCert{true};
    bool rtmpKey{true};
    bool rtmpCert{true};
    bool rtspEncryption{true};
    bool webRtcEncryption{true};
    bool rtmpEncryption{true};
    bool hlsEncryption{true};
    bool logLevel{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.rtspPort = false; // Exclude RTSP port only. Others included.

// 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": 45157,
        "bitrateMode": 53395,
        "codec": "dkgvmkrnjv",
        "custom1": 16353.0,
        "custom2": 30513.0,
        "custom3": 16213.0,
        "enable": false,
        "fitMode": 14594,
        "fps": 12255.0,
        "gop": 32446,
        "h264Profile": 17051,
        "height": 44304,
        "hlsCert": "24kjcnnv",
        "hlsEnable": false,
        "hlsEncryption": "wieufjpowkf",
        "hlsKey": "wqlovf;qb",
        "hlsPort": 9365,
        "ip": "sfspfo9jbjnbjhklvllks",
        "jpegQuality": 22605,
        "logLevel": 0,
        "maxBitrateKbps": 11267,
        "metadataEnable": false,
        "metadataPort": 35074,
        "metadataSuffix": "z.,nfpowe",
        "minBitrateKbps": 6818,
        "overlayEnable": true,
        "password": "sddgoihw,",
        "rtmpCert": "wfpomv",
        "rtmpEnable": true,
        "rtmpEncryption": "skldfjdf",
        "rtmpKey": "dkkkkjfkjdkjfkj2134",
        "rtmpPort": 55981,
        "rtmpsPort": 1936,
        "rtpEnable": true,
        "rtpPort": 31062,
        "rtspCert": "lkjrkjg",
        "rtspEnable": true,
        "rtspEncryption": "quyen",
        "rtspKey": "dh;skcsf",
        "rtspMulticastIp": "wpofuihifo",
        "rtspMulticastPort": 47135,
        "rtspPort": 42745,
        "rtspsPort": 56847,
        "srtEnable": true,
        "srtPort": 1963,
        "suffix": "pisfhcowmfv",
        "type": 5617,
        "user": "slfljkv",
        "webRtcCert": "erghshiAJ",
        "webRtcEnable": false,
        "webRtcEncryption": "l;uoykh",
        "webRtcKey": "WERUHUHFE",
        "webRtcPort": 50955,
        "width": 48849
    }
}

Simple example

The application below 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 "VStreamerMediaMtx.h"
#include "VSourceFile.h"



int main(int argc, char **argv)
{
    std::cout << "------------------------------------------" << std::endl;
    std::cout << "VStreamerMediaMtx v" << cr::video::VStreamerMediaMtx::getVersion() << " example" << 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;

    // Set mediamtx path
    cr::video::VStreamerMediaMtx::setMediaMtxPath("/home/pi/Downloads/MediaMtx");

    // Init video streamer params.
    cr::video::VStreamerParams params;
    params.enable = true;
    params.rtspPort = port;
    params.rtpEnable = true;

    cr::video::VStreamerMediaMtx streamer;
    if (!streamer.initVStreamer(params))
    {
        std::cout << "Video streamer init failed" << std::endl;
        return -1;
    }

    // Create frame.
    cr::video::Frame frame;

    // Open video source.
    cr::video::VSourceFile videoSource;
    std::string initString = "test.h264;1280;720;30";
    if (!videoSource.openVSource(initString))
    {
        std::cout << "Open video source failed" << std::endl;
        return -1;
    }

    // Main loop.
    while (true)
    {
        // Get frame from video source.
        if (!videoSource.getFrame(frame, 1000))
        {
            std::cout << "Get frame failed" << std::endl;
            break;
        }

        // Add frame to streamer.
        if (!streamer.sendFrame(frame))
        {
            std::cout << "Send frame failed" << std::endl;
            break;
        }
    }

    return 0;
}

Test application

VStreamerMediamtx/test folder contains test application which demonstrates VStreamerMediaMtx library usage with multiple instances. The application creates two VStreamerMediaMtx objects and initializes them. The application generates artificial video frames and feeds VStreamerMediaMtx video streamers. Also application allows user to change parameters of streamers from terminal. Output of the application will be like:

------------------------------------------
VStreamerMediaMtx v1.3.0 test
------------------------------------------
Set number of instances: 2
Set path to MediaMTX: /home/pi
Is single MediaMTX instance? (0 - Single, 1 - Multiple): 0
Set RTSP port: 7031
Stream 0: rtsp://127.0.0.1:7031/live0
Stream 1: rtsp://127.0.0.1:7031/live1
----------------------------------
Enter stream number (0-1): 0

after entering streamer number user will choose the operation:

-1 - Exit
0 - Set RTSP port
1 - Set resolution
2 - Set suffix
3 - Set bitrate
4 - Set user name and password
5 - Set fit mode
Choose option:

User can change parameters of streamers

Enter RTSP port: 7031

Build and connect to your project

The VStreamerMediaMtx library supports only Linux. Before compiling user must install 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 libopencv-dev

Typical commands to build VStreamerMediaMtx library:

cd VStreamerMediaMtx
mkdir build
cd build
cmake ..
make

If you want connect VStreamerMediaMtx 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
    VStreamerMediaMtx

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)

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
add_subdirectory(VStreamerMediaMtx)

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 VStreamerMediaMtx library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} VStreamerMediaMtx)

Done!

MediaMTX v1.15.0 Included

This library includes a MediaMTX v1.15.0 executable file in the static folder for compatibility and convenience for each system architecture. The following files are included:

• static/linux_amd64/mediamtx - MediaMTX v1.15.0 Linux AMD64 executable
• static/linux_arm64/mediamtx - Default MediaMTX configuration file

MediaMTX v1.15.0 is the latest stable version and is fully compatible with this library version. You can use this included executable directly or download it from the official MediaMTX releases page.

The mediamtx application can be obtained from mediamtx releases. Follow the instructions from mediamtx.

---

Table of contents