rtsp_server_web_logo

RtspServer C++ library

v3.0.0

Overview
Versions
Library files
RtspServer class description
Data structures
- VStreamerCommand enum
- VStreamerParam enum
VStreamerParams class description
Examples
Build and connect to your project

Overview

The RtspServer C++ library implements an RTSP server. The RtspServer library inherits from the VStreamer interface. The library supports H264 and HEVC(H265) video streams via TCP / UDP / UDP multicast. Users can set general RTSP server parameters such as: RTSP server port, IP, stream name, user name, password etc. The 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 the input frame size differs from the video stream resolution). Second, video overlay is applied if a pointer to a video overlay engine is provided by the user (as defined by the VOverlay interface). Finally, the frame is encoded into a compressed format (H264 or HEVC) before being transmitted to clients (to use these functions the user must define a video codec as defined by the 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 addition, the test application depends on the VSourceFile library (provides functions to capture compressed data from video files, source code included). The library is compatible with Linux and Windows operating systems. The RTSP server is compatible with all popular RTSP clients: ffmpeg, gstreamer, VLC, Milestone etc. The library uses parts 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.
2.1.3	03.04.2025	- Multiple submodules update.
2.1.4	26.07.2025	- VSourceFile submodule update.
2.1.5	26.10.2025	- VSourceFile submodule update.
3.0.0	11.11.2025	- VStreamer interface changed.

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.
    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 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 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 is 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, uint8_t* userData = nullptr, int userDataSize = 0) 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 returns a string of the current class version. Method declaration:

static std::string getVersion();

The method can be used without an RtspServer class instance:

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

Console output:

RtspServer version: 3.0.0

initVStreamer method

The initVStreamer(…) method initializes the video streamer. If the streamer is already initialized, the method will reinitialize it. If video streamer parameters are changed, the user does not need to call the initVStreamer(…) method to reinitialize the streamer (use the setParam(…) method). After initialization, the library starts internal processing threads. 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 YUV24 format.

Important note: The VCodec (video codec) 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 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 the video streamer initialization status. This method is thread-safe. Method declaration:

bool isVStreamerInit() override;

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

setParam (string parameter) method

The setParam(…) method sets a parameter with a string value. This method is thread-safe. 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. This method is thread-safe. 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. This method is thread-safe. 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 executes an action command. This method is thread-safe. 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 a video frame to the video streamer for streaming. The method copies frame data to an internal buffer. This method is thread-safe. Method declaration:

bool sendFrame(cr::video::Frame& frame, uint8_t* userData = nullptr, int userDataSize = 0) override;

Parameter	Value
frame	Frame object. H264, HEVC and RAW frame formats are supported. In case of a RAW frame, a VCodec object must be provided to the initVStreamer method. Also, in case of RAW frame format, scaling will be performed by the server (based on the fit mode) if the provided frame has different dimensions than those defined by VStreamerParams. If the provided frame is not RAW, video overlay cannot be applied even if the user provides a VOverlay instance to the initVStreamer method.
userData	Pointer to user data buffer. Not used in the library.
userDataSize	Size of user data buffer in bytes if userData is not null. Not used in the library.

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

closeVStreamer method

The closeVStreamer() method closes the video streamer if it is open. This method stops all internal threads. 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 of VStreamer interface class 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 encodes a command to change any parameter in a remote video streamer. To control a video streamer remotely, the developer has to design their 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 control commands. The VStreamer class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeSetParamCommand(…) is designed to encode the SET_PARAM command. The method has two overloads: one for numeric parameters and one for string parameters. Method declaration:

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

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

Parameter	Description
data	Pointer to data buffer for encoded command. Must have size >= 11 bytes or in case of string parameters must be large enough to hold the string + 12 bytes.
size	Size of encoded data. Will be at least 11 bytes.
id	Parameter ID according to VStreamerParam enum.
value	Numeric video streamer parameter value. Only for non-string parameters. For string parameters (see VStreamerParam enum) this parameter may have any value.
value	String parameter value (see VStreamerParam enum).

encodeSetParamCommand(…) is a static method and is used without a VStreamer class instance. This method is used on the client side (control system). Example of command encoding:

// 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 encodes a command for a remote video streamer. To control a video streamer remotely, the developer has to design their 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 control commands. The VStreamer class provides two types of commands: a parameter change command (SET_PARAM) and an action command (COMMAND). encodeCommand(…) is designed to encode the 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 a static method and is used without a VStreamer class instance. This method is used on the client side (control system). Example of command encoding:

// 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 decodes a command on the 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 a SET_PARAM command the method will return the parameter ID.
commandId	Command ID according to VStreamerCommand enum. After decoding a COMMAND the method will return the command ID.
value	Numeric video streamer parameter value. Only for non-string parameters. For string parameters (see VStreamerParam enum) this parameter may have any value.
strValue	String parameter value (see VStreamerParam enum).

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

Data structures

The VStreamer.h file of the VStreamer interface class 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 4 - Video stream action commands description. Some commands may be unsupported by a particular video streamer class.

Command	Description
RESTART	Restarts the streamer with the last VStreamerParams.
ON	Enables the streamer if it is disabled.
OFF	Disables the streamer if it is enabled.
GENERATE_KEYFRAME	Action command to generate a key frame by the video codec in case of H264/HEVC video encoding. This function is required in some cases. The VCodec implementation provided by the user should support this function.

VStreamerParam enum

Enum declaration:

namespace cr
{
namespace video
{
enum class VStreamerParam
{
    /// Streamer enable / disable, integer: 0 - disabled, 1 - enabled.
    MODE = 1,
    /// Video stream width, integer [0:8192].
    WIDTH,
    /// Video stream height, integer [0:8192].
    HEIGHT,
    /// Streamer IP, string.
    IP,
    /// RTSP port, integer [0:65535].
    RTSP_PORT,
    /// RTSPS port, integer [0:65535].
    RTSPS_PORT,
    /// RTP port, integer [0:65535].
    RTP_PORT,
    /// WebRTC port, integer [0:65535].
    WEBRTC_PORT,
    /// HLS port, integer [0:65535].
    HLS_PORT,
    /// SRT port, integer [0:65535].
    SRT_PORT,
    /// RTMP port, integer [0:65535].
    RTMP_PORT,
    /// RTMPS port, integer [0:65535].
    RTMPS_PORT,
    /// Metadata port, integer [0:65535].
    METADATA_PORT,
    /// RTSP protocol enable / disable, integer: 0 - disable, 1 - enable.
    RTSP_MODE,
    /// RTP protocol enable / disable, integer: 0 - disable, 1 - enable.
    RTP_MODE,
    /// WebRTC protocol enable / disable, integer: 0 - disable, 1 - enable.
    WEBRTC_MODE,
    /// HLS protocol enable / disable, integer: 0 - disable, 1 - enable.
    HLS_MODE,
    /// SRT protocol enable / disable, integer: 0 - disable, 1 - enable.
    SRT_MODE,
    /// RTMP protocol enable / disable, integer: 0 - disable, 1 - enable.
    RTMP_MODE,
    /// Metadata protocol enable / disable, integer: 0 - disable, 1 - enable.
    METADATA_MODE,
    /// RTSP multicast IP, string.
    RTSP_MULTICAST_IP,
    /// RTSP multicast port, integer [0:65535].
    RTSP_MULTICAST_PORT,
    /// Streamer user (for RTSP streaming), string: "" - no user.
    USER,
    /// Streamer password (for RTSP streaming), string: "" - no password.
    PASSWORD,
    /// Streamer suffix for RTSP streaming (stream name), string: "" - no suffix.
    SUFFIX,
    /// Metadata suffix (stream name), string: "" - no suffix.
    METADATA_SUFFIX,
    /// Minimum bitrate for variable bitrate mode, integer kbps.
    MIN_BITRATE_KBPS,
    /// Maximum bitrate for variable bitrate mode, integer kbps.
    MAX_BITRATE_KBPS,
    /// Current bitrate, integer kbps.
    BITRATE_KBPS,
    /// Bitrate mode, integer: 0 - constant bitrate, 1 - variable bitrate.
    BITRATE_MODE,
    /// FPS, float.
    FPS,
    /// GOP size for H264 and H265 codecs, integer [1:65535].
    GOP,
    /// H264 profile, integer: 0 - baseline, 1 - main, 2 - high.
    H264_PROFILE,
    /// JPEG quality, integer: [1:100]% for JPEG codec.
    JPEG_QUALITY,
    /// Codec type, string: "H264", "HEVC" or "JPEG".
    CODEC,
    /// Scaling mode, integer: 0 - fit, 1 - fill.
    FIT_MODE,
    /// Cycle time, integer μsec (microseconds). Calculated by video streamer.
    CYCLE_TIME_USEC,
    /// Overlay enable / disable, integer: 0 - disable, 1 - enable.
    OVERLAY_MODE,
    /// Type of the streamer, integer. Depends on implementation.
    TYPE,
    /// Custom parameter 1, float.
    CUSTOM1,
    /// Custom parameter 2, float.
    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 5 - Video streamer params description.

Parameter	Description
MODE	Enable/disable streamer, integer: 0 - disable, 1 - enabled. If the video streamer is disabled it will not stream video to clients by any protocol.
WIDTH	Frame width from 64 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	Video server IP, string. Default value is 0.0.0.0 which is a universal IP to receive client connections from any IP.
RTSP_PORT	Streamer’s RTSP port, integer [0:65535]. If port has been changed the video server will be restarted.
RTSPS_PORT	Not supported by RtspServer library.
RTP_PORT	Not supported by RtspServer library.
WEBRTC_PORT	Not supported by RtspServer library.
HLS_PORT	Not supported by RtspServer library.
SRT_PORT	Not supported by RtspServer library.
RTMP_PORT	Not supported by RtspServer library.
RTMPS_PORT	Not supported by RtspServer library.
METADATA_PORT	Not supported by RtspServer library.
RTSP_MODE	Not supported by RtspServer library.
RTP_MODE	Not supported by RtspServer library.
WEBRTC_MODE	Not supported by RtspServer library.
HLS_MODE	Not supported by RtspServer library.
SRT_MODE	Not supported by RtspServer library.
RTMP_MODE	Not supported by RtspServer library.
METADATA_MODE	Not supported by RtspServer library.
RTSP_MULTICAST_IP	RTSP server multicast IP. The library uses a unique multicast port for each stream from the IP range set by the user.
RTSP_MULTICAST_PORT	RTSP multicast port, integer [0:65535].
USER	Streamer user (for RTSP streaming), string: ”“ - no user. If the user name has been changed, the video server will be restarted.
PASSWORD	Streamer password (for RTSP streaming), string: ”“ - no password. If the password has been changed, the video server will be restarted.
SUFFIX	Streamer suffix for RTSP streaming (stream name), string: ”“ - no suffix.
METADATA_SUFFIX	Not supported by RtspServer library.
MIN_BITRATE_KBPS	Not supported by RtspServer library.
MAX_BITRATE_KBPS	Not supported by RtspServer library.
BITRATE_KBPS	Bitrate for H264 and H265 codecs, kbps.
BITRATE_MODE	Bitrate mode: 0 CBR, 1 VBR. Passed to codec when available.
FPS	Streamer’s FPS and also encoding FPS, float. 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	Not supported by RtspServer library.
CODEC	Codec type: H264 or HEVC.
FIT_MODE	Scaling mode: 0 - fit, 1 - fill.
OVERLAY_MODE	Overlay enable / disable: 0 - disable, 1 - enable.
CYCLE_TIME_USEC	Read only. Cycle timeout, microseconds.
TYPE	Determines the streamer type: 0 for unicast, 1 for multicast. For multicast streaming, the RtspServer utilizes RTSP_MULTICAST_IP and RTSP_MULTICAST_PORT when RTSP_MULTICAST_IP is specified. If RTSP_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 RTSP_MULTICAST_IP and RTSP_MULTICAST_PORT. If your client does not require a specific IP, leaving RTSP_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.
RTSP_KEY	Not supported by RtspServer library.
RTSP_CERT	Not supported by RtspServer library.
WEBRTC_KEY	Not supported by RtspServer library.
WEBRTC_CERT	Not supported by RtspServer library.
HLS_KEY	Not supported by RtspServer library.
HLS_CERT	Not supported by RtspServer library.
RTMP_KEY	Not supported by RtspServer library.
RTMP_CERT	Not supported by RtspServer library.
RTSP_ENCRYPTION	Not supported by RtspServer library.
WEBRTC_ENCRYPTION	Not supported by RtspServer library.
RTMP_ENCRYPTION	Not supported by RtspServer library.
HLS_ENCRYPTION	Not supported by RtspServer library.
LOG_LEVEL	Not supported by RtspServer library.

VStreamerParams class description

VStreamerParams class declaration

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

namespace cr
{
namespace video
{
class VStreamerParams
{
public:
    /// Mode, boolean: false - disabled, true - enabled.
    bool enable{true};
    /// Video stream width, integer [0:8192].
    int width{1280};
    /// Video stream height, integer [0:8192].
    int height{720};
    /// Streamer IP, string.
    std::string ip{"0.0.0.0"};
    /// RTSP port, integer [0:65535].
    int rtspPort{8554};
    /// RTSPS port, integer [0:65535].
    int rtspsPort{8555};
    /// RTP port, integer [0:65535].
    int rtpPort{5004};
    /// WebRTC port, integer [0:65535].
    int webRtcPort{7000};
    /// HLS port, integer [0:65535].
    int hlsPort{8080};
    /// SRT port, integer [0:65535].
    int srtPort{6000};
    /// RTMP port, integer [0:65535].
    int rtmpPort{1935};
    /// RTMPS port, integer [0:65535].
    int rtmpsPort{1936};
    /// Metadata port, integer [0:65535].
    int metadataPort{9000};
    /// RTSP protocol enable / disable, boolean: false - disable, true - enable.
    bool rtspEnable{true};
    /// RTP protocol enable / disable, boolean: false - disable, true - enable.
    bool rtpEnable{true};
    /// WebRTC protocol enable / disable, boolean: false - disable, true - enable.
    bool webRtcEnable{true};
    /// HLS protocol enable / disable, boolean: false - disable, true - enable.
    bool hlsEnable{true};
    /// SRT protocol enable / disable, boolean: false - disable, true - enable.
    bool srtEnable{true};
    /// RTMP protocol enable / disable, boolean: false - disable, true - enable.
    bool rtmpEnable{true};
    /// Metadata protocol enable / disable, boolean: false - disable, true - enable.
    bool metadataEnable{false};
    /// RTSP multicast IP, string.
    std::string rtspMulticastIp{"224.1.0.1/16"};
    /// RTSP multicast port, integer [0:65535].
    int rtspMulticastPort{18000};
    /// Streamer user (for RTSP streaming), string: "" or "no" - no user.
    std::string user{"no"};
    /// Streamer password (for RTSP streaming), string: "" or "no" - no password.
    std::string password{"no"};
    /// Streamer suffix for RTSP streaming (stream name), string: "" - no suffix.
    std::string suffix{"live"};
    /// Metadata suffix (stream name), string: "" - no suffix.
    std::string metadataSuffix{"metadata"};
    /// Minimum bitrate for variable bitrate mode, integer kbps.
    int minBitrateKbps{1000};
    /// Maximum bitrate for variable bitrate mode, integer kbps.
    int maxBitrateKbps{5000};
    /// Current bitrate, integer kbps.
    int bitrateKbps{3000};
    /// Bitrate mode, integer: 0 - constant bitrate, 1 - variable bitrate.
    int bitrateMode{0};
    /// FPS, float.
    float fps{30.0f};
    /// GOP size for H264 and H265 codecs, integer [1:65535].
    int gop{30};
    /// H264 profile, integer: 0 - baseline, 1 - main, 2 - high.
    int h264Profile{0};
    /// JPEG quality, integer: [1:100]% for JPEG codec.
    int jpegQuality{80};
    /// Codec type, string: "H264", "HEVC" or "JPEG".
    std::string codec{"H264"};
    /// Scaling mode, integer: 0 - fit, 1 - fill.
    int fitMode{0};
    /// Cycle time, integer μsec (microseconds). Calculated by video streamer.
    int cycleTimeUs{0};
    /// Overlay mode, boolean: false - off, true - on.
    bool overlayEnable{true};
    /// Type of the streamer, integer. Depends on implementation.
    int type{0};
    /// Custom parameter 1, float.
    float custom1{0.0f};
    /// Custom parameter 2, float.
    float custom2{0.0f};
    /// Custom parameter 3, float.
    float custom3{0.0f};
    /// Path to openssl key for RTSP, string: "" or "no" - no key.
    std::string rtspKey{"no"};
    /// Path to openssl certificate for RTSP, string: "" or "no" - no certificate.
    std::string rtspCert{"no"};
    /// Path to openssl key for WebRTC, string: "" or "no" - no key.
    std::string webRtcKey{"no"};
    /// Path to openssl certificate for WebRTC, string: "" or "no" - no certificate.
    std::string webRtcCert{"no"};
    /// Path to openssl key for HLS, string: "" or "no" - no key.
    std::string hlsKey{"no"};
    /// Path to openssl certificate for HLS, string: "" or "no" - no certificate.
    std::string hlsCert{"no"};
    /// Path to openssl key for RTMP, string: "" or "no" - no key.
    std::string rtmpKey{"no"};
    /// Path to openssl certificate for RTMP, string: "" or "no" - no certificate.
    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)

    /// Serialize parameters.
    bool serialize(uint8_t* data, int bufferSize, int& size,
                   VStreamerParamsMask* mask = nullptr);

    /// Deserialize parameters.
    bool deserialize(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 64 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	Video server IP, string. Default value is 0.0.0.0 which is a universal IP to receive client connections from any IP.
rtspPort	Streamer’s RTSP port, integer [0:65535]. If port has been changed the video server will be restarted.
rtspsPort	Streamer’s RTSPS port, integer [0:65535]. If port has been changed the video server will be restarted.
rtpPort	Not supported by RtspServer library.
webRtcPort	Not supported by RtspServer library.
hlsPort	Not supported by RtspServer library.
srtPort	Not supported by RtspServer library.
rtmpPort	Not supported by RtspServer library.
rtmpsPort	Not supported by RtspServer library.
metadataPort	Not supported by RtspServer library.
rtspEnable	Not supported by RtspServer library.
rtpEnable	Not supported by RtspServer library.
webRtcEnable	Not supported by RtspServer library.
hlsEnable	Not supported by RtspServer library.
srtEnable	Not supported by RtspServer library.
rtmpEnable	Not supported by RtspServer library.
metadataEnable	Not supported by RtspServer library.
rtspMulticastIp	RTSP server multicast IP. The library uses a unique multicast port for each stream from the IP range set by the user.
rtspMulticastPort	RTSP multicast port, integer [0:65535].
user	Streamer user (for RTSP streaming), string: ”“ - no user. If the user name has been changed, the video server will be restarted.
password	Streamer password (for RTSP streaming), string: ”“ - no password. If the password has been changed, the video server will be restarted.
suffix	Streamer suffix for RTSP streaming (stream name), string: ”“ - no suffix.
metadataSuffix	Not supported by RtspServer library.
minBitrateKbps	Minimum bitrate for VBR mode (100..100000 kbps). Adjusts `maxBitrateKbps` if higher than `maxBitrateKbps`. Applied to codec if present. Should be supported by the codec library.
maxBitrateKbps	Maximum bitrate for VBR mode (100..100000 kbps). Adjusts `minBitrateKbps` if lower than `minBitrateKbps`. Applied to codec if present. Should be supported by the codec library.
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	Not supported by RtspServer library.
codec	Codec type for encoding RAW frames: H264 or HEVC.
fitMode	Scaling mode: 0 - fit, 1 - fill for RAW input video frames.
overlayEnable	Overlay enable / disable: false - disable, true - enable.
cycleTimeUs	Read only. Cycle timeout, microseconds.
type	Determines the streamer type: 0 for unicast, 1 for multicast. For multicast streaming, the RtspServer utilizes rtspMulticastIp and rtspMulticastPort when rtspMulticastIp is specified. If rtspMulticastIp 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 rtspMulticastIp and rtspMulticastPort. If your client does not require a specific IP, leaving rtspMulticastIp 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.
rtspKey	Not supported by RtspServer library.
rtspCert	Not supported by RtspServer library.
webRtcKey	Not supported by RtspServer library.
webRtcCert	Not supported by RtspServer library.
hlsKey	Not supported by RtspServer library.
hlsCert	Not supported by RtspServer library.
rtmpKey	Not supported by RtspServer library.
rtmpCert	Not supported by RtspServer library.
rtspEncryption	Not supported by RtspServer library.
webRtcEncryption	Not supported by RtspServer library.
rtmpEncryption	Not supported by RtspServer library.
hlsEncryption	Not supported by RtspServer library.
logLevel	Not supported by RtspServer library.

Serialize video streamer params

The VStreamerParams class provides a method serialize(…) to serialize video streamer parameters (fields of the VStreamerParams class). Serialization of video streamer parameters is necessary when you need to send video streamer parameters via communication channels. The method provides options to exclude particular parameters from serialization. To do this, the method inserts a binary mask (5 bytes) where each bit represents a particular parameter and the deserialize(…) method recognizes it. Method declaration:

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

Parameter	Value
data	Pointer to data buffer.
bufferSize	Data buffer size. If the buffer size is smaller than required, the buffer will be filled with fewer parameters.
size	Size of serialized data.
mask	Parameters mask - pointer to VStreamerParamsMask structure. VStreamerParamsMask (declared in VStreamer.h file) determines flags for each field (parameter) declared in the VStreamerParams class. If the user wants to exclude any parameters from serialization, they can provide a pointer to the mask. If the user wants to exclude a particular parameter from serialization, they should set the corresponding flag in the VStreamerParamsMask 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 cycleTimeUs{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.rtspPort = 8554;

// Serialize parameters.
uint8_t data[1024];
int size = 0;
in.serialize(data, 1024, size);
cout << "Serialized data size: " << size << " bytes" << endl;

Example with parameters mask:

// Prepare random parameters.
VStreamerParams in;
in.ip = "alsfghljb";
in.rtspPort = 8554;

// Prepare parameters mask.
VStreamerParamsMask mask;
mask.rtspEnable = false; // Exclude RTSP stream. Others by default.

// Serialize parameters.
uint8_t data[1024];
int size = 0;
in.serialize(data, 1024, size, &mask);
cout << "Serialized data size: " << size << " bytes" << endl;

Deserialize video streamer params

The VStreamerParams class provides a method deserialize(…) to deserialize video streamer parameters (fields of the VStreamerParams class). Deserialization of video streamer parameters is necessary when you need to receive video streamer parameters via communication channels. The method automatically recognizes which parameters were serialized by the serialize(…) method. Method declaration:

bool deserialize(uint8_t* data, int dataSize);

Parameter	Value
data	Pointer to serialized data buffer.
dataSize	Size of data in bytes.

Returns: TRUE if data is deserialized or FALSE if not.

Example:

// Serialize parameters.
VStreamerParams in;
uint8_t data[1024];
int size = 0;
in.serialize(data, 1024, size);

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

// Deserialize parameters.
VStreamerParams out;
if (!out.deserialize(data, size))
    cout << "Can't deserialize data" << endl;

Read params from JSON file and write to JSON file

The VStreamer library depends on the ConfigReader library which provides methods to read parameters from JSON files and to write parameters to JSON files. Example of writing and reading parameters to/from a 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 (random values):

{
    "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
    }
}

Examples

The first application shows how to open a video file (compressed video) with the VSourceFile library, capture video and send it to the 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 with default params.
    VStreamerParams params;
    params.rtspPort = 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.h264;1920;1080;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 << "Cannot send frame to RTSP server" << endl;
        
    }

    return 1;
}

The second application shows how to work with RAW video frames. This application includes custom implementation of video codec 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.rtspPort = 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 approximately 30 fps.
        this_thread::sleep_for(milliseconds(33));
    }

    return 1;
}

Build and connect to your project

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

sudo apt-get install libopencv-dev

Typical commands to build RtspServer library:

cd RtspServer
mkdir build
cd build
cmake ..
make

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

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

Create a 3rdparty folder in your repository and copy the RtspServer repository folder there. New structure of your repository:

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

Create a CMakeLists.txt file in the 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(RtspServer)

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

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

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

add_subdirectory(3rdparty)

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

target_link_libraries(${PROJECT_NAME} RtspServer)

Done!

RtspServer C++ library

Table of contents

Overview

Versions

Library files

RtspServer class description

RtspServer class declaration

getVersion method

initVStreamer method

isVStreamerInit method

setParam (string parameter) method

setParam (float parameter) method

getParams method

executeCommand 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

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

Table of contents