This article describes how the VXG Cloud API relates to the built-in SDK functionality. You can use the VXG Cloud Agent documentation to build a simple application that contains callback function stubs. We recommend starting with a minimal app and check video streaming using the VXG Cloud. In the next step, you need to implement all the callback functions and adapt this source code for your awesome solution.
The integration process includes the following steps:
Build an application and check video streaming from a local IP camera to VXG Cloud
Camera capabilities
Video streaming
Integration with the settings API
Integrating PTZ commands
Integration of motion and sound events
Integration of the backward audio channel
1. Build an application and check video streaming from a local IP camera to VXG Cloud
VXG Cloud Agent documentation describes how to build samples. After successful building and installation, you can find the compiled application in the folder: install/bin.
Before running the application you should go to the VXG dashboard and create a new camera and get a VXG access token:
1.1 Go to Video Management and click Add New Camera:
1.2 Select Cloud Camera and click Next:
1.3 Enter the camera name, set up recording and the timezone, and click Next:
1.4 Now the camera is created, please go to the Settings tab:
1.5 Scroll down to find the Streaming access token:
After obtaining the access token, you can run the following command and watch the video in the VXG dashboard:
./cloud-agent-minimal VXG_ACCESS_TOKEN RTSP_URL
for example:
./cloud-agent-minimal eyJjYW1pZCI6IDIzNDQzMiwgImNtbmdyaWQiOiAyMzQ4NTcsICJhY2Nlc3MiOiAiYWxsIiwgInRva2VuIjogInNoYXJlLmV5SnphU0k2SURJd016YzJOSDAuNjA1YjA2MjJ0YmMxZmFiMDAuR0F5QmxaUDF4eXp5SXo4ZDdIOEtLOUxkLUNRIiwgImFwaSI6ICJ3ZWIuc2t5dnIudmlkZW9leHBlcnRzZ3JvdXAuY29tIiwgImNhbSI6ICJjYW0uc2t5dnIudmlkZW9leHBlcnRzZ3JvdXAuY29tIn0= "rtsp://192.168.0.1"
When you start it for the first time, you may see warnings and even errors in the logs. This is fine and means that some stubs are not properly implemented and you need to focus on implementing these callback's functions.
For example, you may see the following messages in the log:
error Cloud reported a problem: Cam 234432 '_update_video_stream_caps' exception IndexError: list index out of range at camera.py:1475
warning get_stream_config not implemented
warning set_steam_by_event not implemented
warning Failed to configure stream {} for pre/post recording.
2. Camera capabilities
The VXG Cloud requests all camera capabilities and current camera settings when the camera connects to the VXG Cloud for the first time or the app version is changed, so the camera app should provide camera capabilities to VXG Cloud. In order to do this, the following commands in your callbacks should be implemented.
Here is a list of callbacks classes and functions that must be implemented using your platform capabilities:
Callback class | Function name | Description |
vxg::cloud::agent::media::stream | get_supported_stream get_stream_caps get_stream_config | caps_video_object caps_audio_object motion_detection_caps |
vxg::cloud::agent::callback | on_get_cam_video_config on_get_cam_audio_config on_get_ptz_config on_get_osd_config on_get_wifi_config on_get_motion_detection_ on_set_cam_events_config on_get_timezone on_get_memorycard_info | audio_config video_config ptz_config osd_config wifi_config motion_detection_config memorycard_info_object |
3. Video streaming
The camera agent application broadcasts the video stream to VXG Cloud and uploads images and video files to the VXG storage directly. VXG Cloud sends "start" and "stop" commands to the camera, and the VXG agent starts or stops streaming.
The agent::media::stream class is an abstract class for media streams, the library provides basic media::rtsp_stream implementation which retransmits RTSP source stream to the endpoint of the VXG Cloud, all settings-related callbacks are stubbed. A developer should implement their own class derived from the media::stream with their own media::Streamer::ISource implementation, or implement their own class derived from the media::rtsp_stream but with callbacks implemented.
4. Integration with the settings API
The list below shows the relationship between the VXG Cloud API and the callback functions in the VXG agent library that the application should handle:
Description | API | Callback class | Parameters |
Returns basic video settings and capabilities | GET | on_get_cam_video_config | vertical flip horizontal flip tdn (true day/night) IR light for night conditions brightness contrast saturation sharpness noise reduce types level of noise reduce white balance types power line frequency |
Changes basic video settings of the camera | PUT | on_set_cam_video_config | vertical flip horizontal flip tdn IR light for night conditions brightness contrast saturation sharpness noise reduce types level of noise reduce white balance types power line frequency |
Returns basic audio settings and capabilities | GET | on_get_cam_audio_config | microphone gain microphone mute speaker volume mute speaker echo cancellation |
Changes basic audio settings of the camera | PUT | on_set_cam_audio_config | microphone gain microphone mute speaker volume mute speaker echo cancellation |
Returns OSD settings and capabilities | GET | on_get_osd_config | static content of OSD enable/disable time part of OSD enable/disable date part of OSD one of predefined values from caps one of predefined font sizes from caps name of one of predefined font colors from name of one of predefined background colors enable/disable OSD background transparency one of predefined positions from caps |
Changes OSD settings of the camera | PUT | on_set_osd_config | static content of OSD enable/disable time part of OSD enable/disable date part of OSD one of predefined values from caps one of predefined font sizes from caps name of one of predefined font colors from name of one of predefined background colors enable/disable OSD background transparency one of predefined positions from caps |
| GET | on_get_motion_detection | rows - number of detection cells by Y columns - number of detection cells by X List of motion regions |
| PUT | on_set_motion_detection | rows - number of detection cells by Y columns - number of detection cells by X List of motion regions |
5. Integrating PTZ commands
The developer should implement the following callback functions if the camera supports PTZ controls:
vxg::cloud::agent::proto::ptz_command
vxg::cloud::agent::proto::ptz_config
vxg::cloud::agent::proto::ptz_preset
All supported PTZ actions are described in the enum ptz_action.
6. Integration of motion and sound events
The developer should implement their own class based on the event stream class and whether the camera supports any events. The number of supported events is specified in the vxg::cloud::agent::proto::event_type enumeration. It is recommended to prepare the event generating module in the vxg::cloud::agent::event_stream::start function and clean or stop this module in the vxg::cloud::agent::event_stream::stop function.
The camera application should call the function notify(event_object event) if the event occurs on the camera side. The developer can send the image in the parameters of the function notify.
The video downloading must be done in the callback function proto::video_clip_info record_export. The video is uploaded to the storage directly. It is best to upload videos a few seconds before the event and a few seconds after the event.
7. Integration of the backward audio channel
If any client initiates a backward audio session using the VXG Cloud, the VXG agent library calls the vxg::cloud::agent::callback::on_start_backward_audio callback function. The camera app gets the RTMP or RTMP URL in this callback.
The application must launch the RTMP client on its own. The RTMP stream contains only one audio track. Supported formats are G711 and AAC.
The final implementation is also responsible for demultiplexing, decoding, and rendering the audio stream.
The VXG agent invokes the following callback if the VXG client stops - vxg::cloud::agent::callback::on_stop_backward_audio.