RtspServer C++ library

v2.1.2

Table of contents

• Overview
• Versions
• Library files
• RtspServer class description
  • RtspServer 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
• Examples
• Build and connect to your project

Overview

The RtspServer C++ library implements RTSP server. The RtspServer library inherits interface from VStreamer. The library supports H264 and HEVC(H265) video stream via TCP / UDP / UDP multicast. User can set general RTSP server parameters such as: RTSP server port, IP, stream name, user name, password etc. Server works frame-by-frame. RtspServer accepts both RAW frame formats (such as NV12) and compressed formats H264 and HEVC(H265). If the frame is in a compressed format (H264 or HEVC), it bypasses any overlay and resizing processes and is sent directly to clients. However, if the frame is RAW, it undergoes a series of processing steps. First, resizing is performed if necessary (if input frame size differs from video stream resolution). Second, video overlay if pointer to video overlay engine is provided by user (according to VOverlay interface). Finally, the frame is encoded into a compressed format (H264 or HEVC) before being transmitted to clients (to use this functions the user must define video codec according to VCodec interface). The library relies on several dependencies: 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), ConfigReader (provides methods to work with JSON files, source code included, Apache 2.0 license) and OpenCV (version 4.5 and higher, video scaling functions). In additional the test application depends on VSourceFile library (provides function to capture compressed data from video file, source code included). The library compatible with Linux and Windows operating systems. The RTSP server compatible with all popular RTSP clients: ffmpeg, gstreamer, VLC, Milestone etc. The library uses part of source code from PHZ76/RtspServer (highly modified, source code included, MIT license).

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	20.11.2023	First version.
2.0.0	13.12.2023	- Interface is changed. - Streaming Raw frame support added. - Multicast stream support added.
2.0.1	20.03.2024	- Code reviewed. - Test application updated. - VStreamer interface updated.
2.0.2	21.05.2024	- Submodules updated. - Documentation updated.
2.1.0	01.08.2024	- Files structure updated. - CMake updated. - Description updated.
2.1.1	27.10.2024	- Add TTL 255 configuration by default for sockets. - Change max RTP payload size from 1420 to 1320 to avoid blocking by firewalls. - Add variable bitrate control for codec.
2.1.2	14.12.2024	- Fix CMake folder including.

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.
    Logger -------------------- Folder with Logger library source code.
src --------------------------- Folder with library source code.
    CMakeLists.txt ------------ CMake file of the library.
    RtspServer.cpp ------------ C++ implementation file.
    RtspServer.h -------------- Main library header file.
    RtspServerVersion.h ------- Header file with library version.
    RtspServerVersion.h.in ---- CMake service file to generate version file.
    Impl ---------------------- Folder with backend library source code.
test -------------------------- Folder for test application files.
    3rdparty ------------------ Folder with third-party libraries.
        CMakeLists.txt -------- CMake file for to include third-party libraries.
        VSourceFile ----------- Folder with VSourceFile library source code.
    CMakeLists.txt ------------ CMake file of test application.
    main.cpp ------------------ Source C++ file of test application.
examples ---------------------- Folder with examples files.
    CMakeLists.txt ------------ CMake file to include examples.
    CompressedFrameStreaming -- Folder with example for compressed video frames.
        3rdparty -------------- Folder with third-party libraries.
            CMakeLists.txt ---- CMake file for to include third-party libraries.
            VSourceFile ------- Folder with VSourceFile library source code.
        CMakeLists.txt -------- CMake file of example.
        main.cpp -------------- Source C++ file of example.

RtspServer class description

RtspServer class declaration

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

namespace cr
{
namespace rtsp
{
class RtspServer : public cr::video::VStreamer
{
public:

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

    /// Class constructor.
    RtspServer();

    /// Class destructor.
    ~RtspServer();

    /// 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 RtspServer class instance:

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

Console output:

RtspServer version: 2.1.0

initVStreamer method

The initVStreamer(…) method initializes RTSP server. If server already initialized the method will reinitialize server. If RTSP 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	VCodec object pointer in case RAW input video frames.
overlay	VOverlay object pointer for video overlay function.

Important note: The VCodec (video code) implementation must be designed to accept input frames in NV12 format. The RtspServer library feeds NV12 frames into the codec. If a custom implementation of VCodec does not support NV12 as the input format, the library will not work properly. Similarly, the VOverlay implementation must also be designed to handle input frames, but in the YUV24 format instead of NV12. This requirement is essential for the correct operation of the library.

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 RTSP 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 RTSP server for streaming. Method declaration:

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

Parameter

Value

frame

Frame object. H264, HEVC and RAW frame formats are supported. In case of RAW frame, VCodec object had to be provided to initVStreamer method. Also in case of RAW frame format, fitting-scaling will be carried out by server if provided frame has different dimensions than dimensions defined by VStreamerParams. If provided frame is not RAW, video overlay can not apply even if user provides VOverlay instance to initVStreamer method.

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

closeVStreamer method

The closeVStreamer() method to close RTSP 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 ouypu 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, if RAW data is processed, the streamer will scale the images according to this parameter.
HEIGHT	Frame height. Regardless of the resolution of the input video, if RAW data is processed, 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_PORT	RTSP server multicast port.
USER	User name for auth.
PASSWORD	Password for auth.
SUFFIX	Stream name for RTSP server.
MIN_BITRATE_KBPS	Not supported by RtspServer library.
MAX_BITRATE_KBPS	Not supported by RtspServer library.
BITRATE_KBPS	Bitrate for constant bitrate encoding in case RAW input video frames.
BITRATE_MODE	Not supported by RtspServer library.
FPS	Streamer’s FPS and also encoding FPS in case RAW input video frames. Regardless of the input video frame rate, the streamer will provide the specified FPS.
GOP	Codec GOP size in case RAW input video frames.
H264_PROFILE	H264 encoding profile in case RAW input video frames: 0 - baseline, 1 - main, 2 - high.
JPEG_QUALITY	Not supported by RtspServer library.
CODEC	Codec type for encoding RAW frames: H264 or HEVC.
FIT_MODE	Scaling mode. Values: 0 - fit, 1 - crop. In case RAW input video frames.
OVERLAY_MODE	Overlay enable / disable in case RAW input video frames. Values: 0 - disable, 1 - enable.
CYCLE_TIME_MKSEC	Read only Cycle timeout, microseconds.
TYPE	Determines the streamer type: 0 for unicast, 1 for multicast. For multicast streaming, the RtspServer utilizes MULTICAST_IP and MULTICAST_PORT when MULTICAST_IP is specified. If MULTICAST_IP is left empty, the server automatically assigns a multicast IP and port. While some clients may necessitate specific IP and port settings, these can be manually set to MULTICAST_IP and MULTICAST_PORT. If your client does not require a specific IP, leaving MULTICAST_IP as an empty string allows the RtspServer to automatically allocate an IP.
CUSTOM1	Not supported by RtspServer library.
CUSTOM2	Not supported by RtspServer library.
CUSTOM3	Not supported by RtspServer 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: 0 - disable, 1 - enabled.
width	Frame width. Regardless of the resolution of the input video, if RAW data is processed, the streamer will scale the images according to this parameter.
height	Frame height. Regardless of the resolution of the input video, if RAW data is processed, the streamer will scale the images according to this parameter.
ip	RTSP server IP.
port	RTSP server port.
multicastIp	RTSP server multicast IP.
multicastPort	RTSP server multicast port.
user	User name for auth.
password	Password for auth.
suffix	Stream name for RTSP server.
minBitrateKbps	Not supported by RtspServer library.
maxBitrateKbps	Not supported by RtspServer library.
bitrateKbps	Bitrate for constant bitrate encoding in case RAW input video frames.
bitrateMode	Not supported by RtspServer library.
fps	Streamer’s FPS and also encoding FPS in case RAW input video frames. Regardless of the input video frame rate, the streamer will provide the specified FPS.
gop	Codec GOP size in case RAW input video frames.
h264Profile	H264 encoding profile in case RAW input video frames: 0 - baseline, 1 - main, 2 - high.
jpegQuality	Not supported by RtspServer library.
codec	Codec type for encoding RAW frames: H264 or HEVC.
fitMode	Scaling mode. Values: 0 - fit, 1 - crop. in case RAW input video frames.
overlayMode	Overlay enable / disable in case RAW input video frames. Values: FALSE - disable, TRUE - enable.
cycleTimeMksec	Read only Cycle timeout, microseconds.
type	Determines the streamer type: 0 for unicast, 1 for multicast. For multicast streaming, the RtspServer utilizes multicastIp and multicastPort when multicastIp is specified. If multicastIp is left empty, the server automatically assigns a multicast IP and port. While some clients may necessitate specific IP and port settings, these can be manually set to multicastIp and multicastPort. If your client does not require a specific IP, leaving multicastIp as an empty string allows the RtspServer to automatically allocate an IP.
custom1	Not supported by RtspServer library.
custom2	Not supported by RtspServer library.
custom3	Not supported by RtspServer 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
    }
}

Examples

First application shows how to open video file (compressed video) with VSourceFile library, capture video and put to RTSP server.

#include <iostream>
#include "RtspServer.h"
#include "VSourceFile.h"

using namespace std;
using namespace cr::rtsp;
using namespace cr::video;

int main(void)
{
    cout << "RtspServer v" << RtspServer::getVersion() << endl << endl;

    // Init RTSP server params for encoded frames by default params.
    VStreamerParams params;
    params.port = 7031;
    params.ip = "0.0.0.0";
    params.suffix = "live";
    params.user = ""; // No user name.
    params.password = ""; // No password.
    params.fps = 30;

    // RTSP server.
    RtspServer server;
    if(!server.initVStreamer(params))
        return -1;
    cout << "RTSP init string: rtsp://127.0.0.1:7031/live" << endl;
    
    // Set video source init string.
    string initString = "out.264;1280;720;30";

    // Init file video source.
    VSourceFile fileSource;
    if(!fileSource.openVSource(initString))
        return -1;

    // Main thread.
    Frame sourceFrame;

    while(1)
    {
        // Get new frame from video file.
        if(!fileSource.getFrame(sourceFrame, 1000))
            continue;
        
        // Send frame to RTSP server.
        if(!server.sendFrame(sourceFrame))
            cout << "Can not send frame to rtsp server" << endl;
        
    }

    return 1;
}

Second application shows how to work with RAW video frames. This application includes custom implementation of video code and video overlay.

#include <iostream>
#include <opencv2/opencv.hpp>
#include "RtspServer.h"
#include <FormatConverterOpenCv.h>

using namespace cv;
using namespace std;
using namespace cr::rtsp;
using namespace cr::video;
using namespace std::chrono;

/// Custom video codec class.
class VCodecImplementation : public VCodec
{
public:

    /// Encode video frame.
    bool transcode(Frame& src, Frame& dst)
    {
        // Check input data.
        if (src.size == 0 || src.width == 0 || src.height == 0)
            return false;

        // This method should encode NV12 frame into H264 frame. 

        return true;
    }

    // Not used
    bool setParam(VCodecParam id, float value) { return false; }

    // Not used.
    float getParam(VCodecParam id) { return -1.0; }

    // Not used.
    bool executeCommand(VCodecCommand id) { return false; }
};

/// Custom video overlay implementation. Works with YUV pixel formats.
class VOverlayCustom : public VOverlay
{
public:

    /// Overlay the information on the video.
    bool overlay(Frame& frame, void* data = nullptr)
    {
        // Put the text on the frame.
        static int counter = 0;
        Mat yuvImg(frame.height, frame.width, CV_8UC3, frame.data);
        putText(yuvImg, to_string(counter++), Point(60, 60),
                FONT_HERSHEY_SIMPLEX, 2.5, Scalar(76, 84, 255), 2);
        return true;
    }
};

int main(void)
{
    cout << "RtspServer v" << RtspServer::getVersion() << endl;
    cout << endl;

    // Set initial RTSP server params.
    VStreamerParams params;
    params.port = 7031;
    params.ip = "0.0.0.0"; // For any IP.
    params.suffix = "live";
    params.user = "";       // No user name.
    params.password = "";   // No password.
    params.fps = 30;
    params.codec = "H264";
    params.width = 1280;
    params.height = 720;
    params.fitMode = 0;
    params.overlayMode = true;

    // Create and init RTSP server.
    RtspServer server;
    if(!server.initVStreamer(params, new VCodecImplementation(), new VOverlayCustom()))
        return -1;
    cout << "RTSP init string: rtsp://127.0.0.1:7031/live" << endl;

    // Main loop.
    cr::video::Frame sourceFrame;
    while(1)
    {
        // Prepare raw frame...

        // Send  RAW frame to RTSP server.
        if(!server.sendFrame(sourceFrame))
            continue;

        // Wait for aprox 30 fps.
        this_thread::sleep_for(milliseconds(33));
    }

    return 1;
}

Build and connect to your project

The RtspServer is a C++ library uses OpenCV library (version 4.5 and higher). To install OpenCV on Linux run command:

sudo apt-get install libopencv-dev

Typical commands to build RtspServer library:

cd RtspServer
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 RtspServer 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_RTSP_SERVER                     ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_RTSP_SERVER)
    SET(${PARENT}_RTSP_SERVER                           ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_RTSP_SERVER_TEST                      OFF CACHE BOOL "" FORCE)
    SET(${PARENT}_RTSP_SERVER_EXAMPLES                  OFF CACHE BOOL "" FORCE)
endif()

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

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

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

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!