v1.1.3
- Overview
- Versions
- Library files
- Video streamer interface class description
- Data structures
- VStreamerParams class description
- Build and connect to your project
- How to make custom implementation
VStreamer C++ library provides standard interface as well defines data structures and rules for different video stream classes. VStreamer interface class does nothing, just provides interface and methods to encode/decode commands and encode/decode params. Also VStreamer class provides data structures for video stream parameters. Different video stream classes inherit interface form VStreamer C++ class. VStreamer.h file contains list of data structures (VStreamCommand enum, VStreamerParam enum and VStreamerParams class). VStreamerParams class contains all streamer params and includes methods to encode and decode params. VStreamCommand enum contains IDs of commands supported by VStreamer class. VStreamerParam enum contains IDs of params supported by VStreamer class. All video streamers should include params and commands listed in VStreamer.h file. VStreamer interface class depends on: ConfigReader library (provides methods to read/write JSON config files, source code included, Apache 2.0 license), VCodec library (provides interface for video codecs, source code included, Apache 2.0 license), VOverlay library (provides interface for overlay engines, source code included, Apache 2.0 license). The library is licensed under the Apache 2.0 license.
Table 1 - Library versions.
Version | Release date | What's new |
---|---|---|
1.0.0 | 15.02.2024 | First version of the library. |
1.1.0 | 26.02.2024 | - New parameters added for multicast streaming. |
1.1.1 | 20.03.2024 | - VCodec class updated. - VOverlay class updated. - Frame subrepository excluded. - Documentation updated. |
1.1.2 | 21.05.2024 | - Submodules updated. - Documentation updated. |
1.1.3 | 10.07.2024 | - Submodules updated. - CMake updated. |
The library supplied by source code only. The user would be 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.
ConfigReader ----------------- Folder with ConfigReader library source code.
VCodec ----------------------- Folder with VCodec library source code.
VOverlay --------------------- Folder with VOverlay library source code.
example -------------------------- Folder with simple example of VStreamer implementation.
CMakeLists.txt --------------- CMake file for example custom video streamer class.
CustomVStreamer.cpp ---------- C++ implementation file.
CustomVStreamer.h ------------ Header with CustomVStreamer class declaration.
CustomVStreamerVersion.h ----- Header file which includes CustomVStreamer version.
CustomVStreamerVersion.h.in -- CMake service file to generate version file.
test ----------------------------- Folder with VStreamer test application.
CMakeLists.txt --------------- CMake file for VStreamer test application.
main.cpp --------------------- Source code file of VStreamer class test application.
src ------------------------------ Folder with source code of the library.
CMakeLists.txt --------------- CMake file of the library.
VStreamer.cpp ---------------- Source code file of the library.
VStreamer.h ------------------ Main library header file.
VStreamerVersion.h ----------- Header file which includes version of the library.
VStreamerVersion.h.in -------- CMake service file to generate version file.
VStreamer interface class declared in VStreamer.h file. Class declaration:
namespace cr
{
namespace video
{
/// VStreamer interface class.
class VStreamer
{
public:
/// Class destructor.
virtual ~VStreamer();
/// Get string of current library version.
static std::string getVersion();
/// Init video streamer.
virtual bool initVStreamer(VStreamerParams ¶ms,
VCodec *codec = nullptr,
VOverlay *overlay = nullptr) = 0;
/// Get init status.
virtual bool isVStreamerInit() = 0;
/// Close video streamer.
virtual void closeVStreamer() = 0;
/// Send frame to video streamer.
virtual bool sendFrame(Frame& frame) = 0;
/// Set video streamer param.
virtual bool setParam(VStreamerParam id, float value) = 0;
/// Set video streamer param.
virtual bool setParam(VStreamerParam id, std::string value) = 0;
/// Get video streamer params structure.
virtual void getParams(VStreamerParams& params) = 0;
/// Execute command.
virtual bool executeCommand(VStreamerCommand id) = 0;
/// Decode and execute command.
virtual bool decodeAndExecuteCommand(uint8_t* data, int size);
/// Encode set param command.
static void encodeSetParamCommand(uint8_t *data, int &size,
VStreamerParam id, float value);
/// Encode set param command.
static void encodeSetParamCommand(uint8_t* data, int& size,
VStreamerParam id, std::string value);
/// Encode command.
static void encodeCommand(uint8_t* data, int& size, VStreamerCommand id);
/// Decode command.
static int decodeCommand(uint8_t* data,
int size,
VStreamerParam& paramId,
VStreamerCommand& commandId,
float& value,
std::string& strValue);
};
}
}
The getVersion() method returns string of current version of VStreamer class. Particular video streamer class can have it's own getVersion() method. Method declaration:
static std::string getVersion();
Method can be used without VStreamer class instance:
std::cout << "VStreamer class version: " << VStreamer::getVersion() << std::endl;
Console output:
VStreamer class version: 1.1.3
The initVStreamer(...) method initializes video streamer by set of parameters. Method declaration:
virtual bool initVStreamer(VStreamerParams ¶ms,
VCodec *codec = nullptr,
VOverlay *overlay = nullptr) = 0;
Parameter | Value |
---|---|
params | VStreamerParams class object. The video streamer should set parameters according to params structure. Particular video streamer might not support all parameters listed in VStreamerParams class. |
codec | Pinter VCodec object. Used for encoding video in case RAW input frame data. If user set pointer to nullptr the video streamer can process only compressed input video frames (H264, HEVC or JPEG). |
overlay | Pointer to VOverlay object. Used to overlay information on video in case if user put RAW input frame data to the streamer. If user set pointer to nullptr the video streamer will not be able overlay any information on video. |
Returns: TRUE if the video streamer initialized or FALSE if not.
The isVStreamerInit() method returns video streamer initialization status. Method declaration:
virtual bool isVStreamerInit() = 0;
Returns: TRUE if the video streamer initialized or FALSE if not.
The closeVStreamer() method closes video streamer. Method stops all thread and releases memory. Method declaration:
virtual void closeVStreamer() = 0;
The sendFrame(...) method intended to send frame to clients. To provide video stream the user must call this method for every video frame coming from video source. In case processing RAW video frames streamer must resize video (if necessary) and overlay information (if pointer to video overlay class set in initVStreamer(...) method). Method declaration:
virtual bool sendFrame(Frame& frame) = 0;
Parameter | Value |
---|---|
frame | Frame class object. Particular streamers can support RAW video frames or(and) compressed video frames. |
Returns: TRUE if frame sent (accepted by streamer) or FALSE if not.
The setParam(...) method sets new value of video stream parameter. Each implementation of the video streamer must provide thread-safe setParam(...) method call. This means that the setParam(...) method can be safely called from any thread. Also, method has two overloaded version that depends on type of value. Method declaration:
virtual bool setParam(VStreamerParam id, float value) = 0;
virtual bool setParam(VStreamerParam id, std::string value) = 0;
Parameter | Description |
---|---|
id | Video stream parameter ID according to VStreamerParam enum. |
value | Value of parameter. It can be either string or float type. It depends on parameter. |
Returns: TRUE is the parameter is set or FALSE if not.
The getParams(...) method disigned to obtain video streamer params class (VStreamerParams). Each implementation of the video streamer must provide thread-safe getParams(...) method call. This means that the getParams(...) method can be safely called from any thread. Method declaration:
virtual void getParams(VStreamerParams& params) = 0;
Parameter | Description |
---|---|
params | VStreamerParams class object. |
The executeCommand(...) method to execute video stream command. The particular implementation of the video stream must provide thread-safe executeCommand(...) method call. This means that the executeCommand(...) method can be safely called from any thread. Method declaration:
virtual bool executeCommand(VStreamerCommand id) = 0;
Parameter | Description |
---|---|
id | Video stream command ID according to VStreamCommand enum. |
Returns: TRUE is the command was executed or FALSE if not.
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).
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);
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);
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.
VStreamer.h file defines IDs for parameters (VStreamerParam enum) and IDs for commands (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. Some commands maybe unsupported by particular video stream class.
Command | Description |
---|---|
RESTART | Restarts streamer with last VStreamerParams. |
ON | Enables streamer if it is disabled. |
OFF | Disables streamer if it is enabled. |
Enum declaration:
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. Some params maybe unsupported by particular video streamer class.
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 should 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 should scale the images according to this parameter. |
IP | Streamer's ip. It can be, for example, RTSP server IP or destination IP. |
PORT | Streamer's port. It can be TCP or UDP port depends on implementation. |
MULTICAST_IP | Streamer's multicast ip. |
MULTICAST_PORT | Streamer's multicast port. It can be UDP port in case RTSP server. |
USER | User name for auth (for example, in case RTSP server). |
PASSWORD | Password name for auth (for example, in case RTSP server). |
SUFFIX | Stream name in case RTSP server. |
MIN_BITRATE_KBPS | Minimum bitrate for variable bitrate encoding in case RAW input video frames. |
MAX_BITRATE_KBPS | Maximum bitrate for variable bitrate encoding in case RAW input video frames. |
BITRATE_KBPS | Bitrate for constant bitrate encoding in case RAW input video frames. |
BITRATE_MODE | Enable/disable variable bitrate. Values depends on implementation but it is recommended to use default values: 0 - constant bitrate, 1 - variable bitrate. |
FPS | Streamer's fps and also encoding fps in case RAW input video frames. Regardless of the input video frame rate, the streamer must provide the specified FPS. If the FPS value is 0, the streamer must provide FPS equal to the input video frame rate. |
GOP | Codec gop size in case 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 | JPEG encoding quality in case RAW input video frames: 0-100%. |
CODEC | Codec type for encoding RAW frames: H264, HEVC or JPEG. |
FIT_MODE | Scaling mode. Values depends on implementation but it is recommended to use default values: 0 - fit, 1 - crop. in case RAW input video frames. |
OVERLAY_MODE | Overlay enable/disable in case RAW input video frames. Values depends on implementation but it is recommended to use default values: 0 - disable, 1 - enable. |
CYCLE_TIME_MKSEC | Read only Cycle timeout, microseconds. |
TYPE | Type of streamer. Depends on implementation. |
CUSTOM1 | Custom parameter. Depends on implementation. |
CUSTOM2 | Custom parameter. Depends on implementation. |
CUSTOM3 | Custom parameter. Depends on implementation. |
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:
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 should 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 should scale the images according to this parameter. |
ip | Streamer's ip. It can be, for example, RTSP server IP or destination IP. |
port | Streamer's port. It can be TCP or UDP port depends on implementation. |
multicastIp | Streamer's multicast ip. |
multicastPort | Streamer's multicast port. It can be UDP port in case RTSP server. |
user | User name for auth (for example, in case RTSP server). |
password | Password for auth (for example, in case RTSP server). |
suffix | Stream name in case RTSP server. |
minBitrateKbps | Minimum bitrate for variable bitrate encoding in case RAW input video frames. |
maxBitrateKbps | Maximum bitrate for variable bitrate encoding in case RAW input video frames. |
bitrateKbps | Bitrate for constant bitrate encoding in case RAW input video frames. |
bitrateMode | Enable/disable variable bitrate. Values depends on implementation but it is recommended to use default values: 0 - constant bitrate, 1 - variable bitrate. |
fps | Streamer's fps and also encoding fps in case RAW input video frames. Regardless of the input video frame rate, the streamer must provide the specified FPS. If the FPS value is 0, the streamer must provide FPS equal to the input video frame rate. |
gop | Codec gop size in case in case RAW input video frames. |
h264Profile | H264 encoding profile in case RAW input video frames: 0 - baseline, 1 - main, 2 - high. |
jpegQuality | JPEG encoding quality in case RAW input video frames: 0-100%. |
codec | Codec type for encoding RAW frames: H264, HEVC or JPEG. |
fitMode | Scaling mode. Values depends on implementation but it is recommended to use default values: 0 - fit, 1 - crop. in case RAW input video frames. |
overlayMode | Overlay enable/disable in case RAW input video frames. Values depends on implementation but it is recommended to use default values: 0 - disable, 1 - enable. |
cycleTimeMksec | Read only Cycle timeout, microseconds. |
type | Type of streamer. Depends on implementation. |
custom1 | Custom parameter. Depends on implementation. |
custom2 | Custom parameter. Depends on implementation. |
custom3 | Custom parameter. Depends on implementation. |
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;
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;
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
}
}
Typical commands to build VStreamer library:
git clone https://github.com/ConstantRobotics-Ltd/VStreamer.git
cd VStreamer
git submodule update --init --recursive
mkdir build
cd build
cmake ..
make
If you want connect VStreamer 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
You can add repository VStreamer as submodule by commands:
cd <your respository folder>
git submodule add https://github.com/ConstantRobotics-Ltd/VStreamer.git 3rdparty/VStreamer
git submodule update --init --recursive
In you repository folder will be created folder 3rdparty/VStreamer which contains files of VStreamer repository with subrepositories Frame, ConfigReader, VCodec and VOverlay. Also you can copy VStreamer repository folder to 3rdparty folder of your repository. New structure of your repository:
CMakeLists.txt
src
CMakeList.txt
yourLib.h
yourLib.cpp
3rdparty
VStreamer
Create CMakeLists.txt file in 3rdparty folder. CMakeLists.txt should contain:
cmake_minimum_required(VERSION 3.13)
################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)
################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)
################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_VSTREAMER ON CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_VSTREAMER)
SET(${PARENT}_VSTREAMER ON CACHE BOOL "" FORCE)
SET(${PARENT}_VSTREAMER_TEST OFF CACHE BOOL "" FORCE)
SET(${PARENT}_VSTREAMER_EXAMPLE OFF CACHE BOOL "" FORCE)
endif()
################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_VSTREAMER)
add_subdirectory(VStreamer)
endif()
File 3rdparty/CMakeLists.txt adds folder VStreamer to your project and excludes test application and example (VStreamer class test applications and example of custom video streamer class implementation) from compiling (by default test application and example excluded from compiling if VStreamer included as sub-repository). Your repository new structure will be:
CMakeLists.txt
src
CMakeList.txt
yourLib.h
yourLib.cpp
3rdparty
CMakeLists.txt
VStreamer
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 VStreamer library in your src/CMakeLists.txt file:
target_link_libraries(${PROJECT_NAME} VStreamer)
Done!
The VStreamer class provides only an interface, data structures, and methods for encoding and decoding commands and params. To create your own implementation of the video streamer, you must include the VStreamer repository in your project (see Build and connect to your project section). The catalogue example (see Library files section) includes an example of the design of the custom video streamer. You must implement all the methods of the VStreamer interface class. Custom video streamer class declaration:
namespace cr
{
namespace video
{
/// Custom video streamer class.
class CustomVStreamer: public VStreamer
{
public:
/**
* @brief Class destructor.
*/
~CustomVStreamer();
/**
* @brief Get string of current library version.
* @return String of current library version.
*/
static std::string getVersion();
/**
* @brief Init video streamer. All params will be set according to structure.
* @param params Video streamer parameters structure.
* @param overlay Pointer to overlay object (in case raw frame streaming).
* @param codec Pointer to codec object (in case raw frame streaming).
* @return TRUE if the video streamer init or FALSE if not.
*/
bool initVStreamer(VStreamerParams ¶ms,
VCodec *codec = nullptr,
VOverlay *overlay = nullptr) override;
/**
* @brief Get open status.
* @return TRUE if video streamer init or FALSE if not.
*/
bool isVStreamerInit() override;
/**
* @brief Close video streamer.
*/
void closeVStreamer() override;
/**
* @brief Send frame to video streamer.
* @param frame Pointer to frame object.
*/
bool sendFrame(Frame& frame) override;
/**
* @brief Set video streamer param.
* @param id Parameter ID.
* @param value Parameter value to set.
* @return TRUE if property was set of FALSE.
*/
bool setParam(VStreamerParam id, float value) override;
/**
* @brief Set video streamer param.
* @param id Parameter ID.
* @param value Parameter value to set.
* @return TRUE if property was set of FALSE.
*/
bool setParam(VStreamerParam id, std::string value) override;
/**
* @brief Get video streamer params structure.
* @param params Video streamer params class object.
*/
void getParams(VStreamerParams& params) override;
/**
* @brief Execute command.
* @param id Command ID.
* @return TRUE if the command accepted or FALSE if not.
*/
bool executeCommand(VStreamerCommand id) override;
private:
/// Video source params.
VStreamerParams m_params;
};
}
}