Video Tracking Service

Process live or pre-recorded videos. This API object handles setting up, running analytics against, and monitoring lists of video streams. More...

Data Structures
struct	roc_stream_tracker_status
	Holds camera feed processing information for a roc_stream. More...

Typedefs
typedef struct roc_video_service_type *	roc_video_service
	Handle to a private roc_video_service type.
typedef struct roc_stream_tracker_status	roc_stream_tracker_status
	Holds camera feed processing information for a roc_stream. More...
typedef roc_stream_tracker_status *	roc_stream_tracker_status_array

Functions
roc_error	roc_new_video_service (roc_video_service *video_service)
	Create a roc_video_service object. More...
roc_error	roc_video_service_start (roc_video_service video_service, roc_string global_settings)
	Configure system settings for a roc_video_service object. More...
void	roc_free_stream_tracker_status_array (roc_stream_tracker_status_array *stream_tracker_status_array, size_t status_count)
	Deallocate a roc_stream_tracker_status. More...
roc_error	roc_video_service_status (roc_video_service video_service, roc_stream_tracker_status_array *stream_tracker_statuses, size_t *num_stream_tracker_statuses, bool *done, size_t *pending_transmissions)
	Check status for a roc_video_service object. More...
roc_error	roc_video_service_add_stream (roc_video_service video_service, const char *new_stream_configuration)
	Add video-stream configuration to a roc_video_service. More...
roc_error	roc_video_service_update_stream (roc_video_service video_service, const char *updated_stream_configuration)
	Update a video-stream in a roc_video_service configuration. More...
roc_error	roc_video_service_remove_stream (roc_video_service video_service, const char *removed_stream_id)
	Remove a video-stream from a roc_video_service configuration. More...
roc_error	roc_video_service_read_configuration (roc_video_service video_service, roc_string *current_configuration)
	Read the entire Video Service Parameters configuration for a roc_video_service. More...
roc_error	roc_free_video_service (roc_video_service video_service)
	Stop processing and deallocate a roc_video_service object. More...

Detailed Description

Process live or pre-recorded videos. This API object handles setting up, running analytics against, and monitoring lists of video streams.

• Initialize a roc_video_service with roc_new_video_service, and deinitialize it with roc_free_video_service.
• Prepare and setup a roc_video_service object for processing by calling roc_video_service_start with a Global Settings Object.
• Begin processing video by adding a video-stream to the roc_video_service via roc_video_service_add_stream.
• Update an existing video-stream by passing an updated video-stream configuration to roc_video_service_update_stream.
• Disable and remove an existing video-stream in a roc_video_service by passing that video stream's stream-id to roc_video_service_remove_stream.
• Read the entire current configuration of Video Service Parameters for a roc_video_service by calling roc_video_service_read_configuration.
• Gather metrics and monitor performance by calling roc_video_service_status.
• Stop a roc_video_service by calling roc_free_video_service.

---

Data Structure Documentation

roc_stream_tracker_status

struct roc_stream_tracker_status

Holds camera feed processing information for a roc_stream.

Data Fields
bool	enabled	True if the stream is still processing frames. If false, camera is no longer part of the running roc_video_service configuration.
size_t	events	Number of roc_event detected by this stream.
char *	filename	Name of video file or camera URL.
float	fps	Average frames per second this stream is processing.
size_t	frames_queued	Number of frames the stream has decoded, buffered, and not yet processed.
size_t	frames_dropped	Number of frames the stream has dropped without processing.
size_t	frames_processed	Number of frames the stream has finished processing.
char *	stream_id	Unique identifier specific to this video stream.

Typedef Documentation

roc_stream_tracker_status

typedef struct roc_stream_tracker_status roc_stream_tracker_status

Holds camera feed processing information for a roc_stream.

roc_stream_tracker_status_array

typedef roc_stream_tracker_status* roc_stream_tracker_status_array

A dynamically allocated array of roc_stream_tracker_status.

Free after use with roc_free_stream_tracker_status_array.

Function Documentation

roc_new_video_service()

roc_error roc_new_video_service

(

roc_video_service *

video_service

)

Create a roc_video_service object.

Initialize a roc_video_service for processing.

Parameters

[in]

video_service

roc_video_service to initialize.

Remarks

This function is reentrant.

roc_video_service_start()

roc_error roc_video_service_start	(	roc_video_service	video_service,
		roc_string	global_settings
	)

Configure system settings for a roc_video_service object.

This function must be called prior to roc_video_service_add_stream. The roc_string passed to this function must be a JSON-formatted Global Settings Object configuration.

Example Global Settings Configuration

{
    "global-settings": {
        "gallery": {
            "file": {
                "enabled": true,
                "path": "gallery.t"
            }
        }
    }
}

See here for an example Video Service Parameters configuration with every setting set to it's default value. This file can also be found in the in the share folder included with the ROC SDK. See Video Service Parameters for details about each setting.

Example Usage

// Assume Global Settings JSON object loaded from file...
const char *globalSettingsJsonObject = ...
roc_string globalSettingsString;
roc_ensure(roc_set_string(globalSettingsJsonObject, &globalSettingsString));

roc_video_service video_service;
roc_ensure(roc_new_video_service(&video_service));
roc_ensure(roc_video_service_start(video_service, globalSettingsString));
roc_ensure(roc_free_string(&globalSettingsString));

// Begin adding video streams...

The video service will continue running until roc_free_video_service is called.

Parameters

[in]	video_service	roc_video_service to begin processing.
[in]	global_settings	JSON-formatted configuration string.

Remarks

This function is reentrant.

roc_free_stream_tracker_status_array()

void roc_free_stream_tracker_status_array	(	roc_stream_tracker_status_array *	stream_tracker_status_array,
		size_t	status_count
	)

Deallocate a roc_stream_tracker_status.

Parameters

[in]	stream_tracker_status_array	Array to deallocate.
[in]	status_count	Number of entries in the array.

Remarks

This function is reentrant.

roc_video_service_status()

roc_error roc_video_service_status	(	roc_video_service	video_service,
		roc_stream_tracker_status_array *	stream_tracker_statuses,
		size_t *	num_stream_tracker_statuses,
		bool *	done,
		size_t *	pending_transmissions
	)

Check status for a roc_video_service object.

Video services that have finished processing or encountered an error for all threads, will return a "done" status of true, while services that have not been started with roc_video_service_start or have at least one video still processing will return a "done" status of false. Free stream_tracker_statuses after use with roc_free_stream_tracker_status_array.

Example Usage

// Assume Global Settings JSON object loaded from file...
const char *globalSettingsJsonObject = ...
roc_string globalSettingsString;
roc_ensure(roc_set_string(globalSettingsJsonObject, &globalSettingsString));

roc_video_service video_service;
roc_ensure(roc_new_video_service(&video_service));
roc_ensure(roc_video_service_start(video_service, globalSettingsString));
roc_ensure(roc_free_string(&globalSettingsString));

// Assume Video Stream JSON object loaded from file...
const char *videoStreamObject = ...
roc_string videoStreamString;
roc_ensure(roc_set_string(videoStreamObject, &videoStreamString));

roc_ensure(roc_video_service_add_stream(video_service, videoStreamString));
roc_ensure(roc_free_string(&videoStreamString));

// Busy wait for processing to finish...
while (1)
{
    roc_stream_tracker_status_array status;
    size_t num_streams;
    bool done;
    size_t pending;
    roc_ensure(roc_video_service_status(video_service, &status, &num_streams, &done, &pending));
    roc_ensure(roc_free_stream_tracker_status_array(&status, num_streams));

    if (done)
        break;
  }

// Free video service resources...
roc_ensure(roc_free_video_service(video_service));

Parameters

[in]	video_service	roc_video_service to get status for.
[out]	stream_tracker_statuses	roc_stream_tracker_status_array object.
[out]	num_stream_tracker_statuses	Number of entries in stream_tracker_statuses.
[out]	done	All streams have finished processing or errored out.
[out]	pending_transmissions	Number of transmissions that have been queued but not sent.

Remarks

Remember to free stream_tracker_statuses after use with roc_free_stream_tracker_status_array.

This function is reentrant.

roc_video_service_add_stream()

roc_error roc_video_service_add_stream	(	roc_video_service	video_service,
		const char *	new_stream_configuration
	)

Add video-stream configuration to a roc_video_service.

stream-id

Each video-stream object added to a roc_video_service must contain a non-empty "stream-id" field. The video service uses "stream-id" for the managment and monitoring of video streams. Therefore, the value of "stream-id" must be unique.

{
    "enabled": true,
    "source": {
    },
    "stream-id": "", // This field must be set to a non-empty string by the client.
    "tracker": {
    }
}

The roc_string passed to this function must be a JSON-formatted video-stream configuration. The stream-id for the video stream configuration must be unique.

Example Video Stream Configuration

{
    "source": {
        "url": "/some/path/data/josh.mp4"
    },
    "stream-id": "driving-stream",
    "tracker": {
        "analytics-backends": [
            {
                "algorithm-id": [
                    "ROC_CAR_DETECTION"
                ],
                "event-reasons": [
                    "ROC_FINALIZED_TRACK"
                ],
                "k": 15
            }
        ],
        "context-image": {
            "enabled": true,
            "file": {
                "enabled": true,
                "path": "archive-driving"
            }
        },
        "render": {
            "color": "0,255,0",
            "detections": true,
            "timestamp": true
        }
    }
}

See here for an example Video Service Parameters configuration with every setting set to it's default value. This file can also be found in the in the share folder included with the ROC SDK. See Video Service Parameters for details about each setting.

Example Usage

// Assume Global Settings JSON object loaded from file...
const char *globalSettingsJsonObject = ...
roc_string globalSettingsString;
roc_ensure(roc_set_string(globalSettingsJsonObject, &globalSettingsString));

roc_video_service video_service;
roc_ensure(roc_new_video_service(&video_service));
roc_ensure(roc_video_service_start(video_service, globalSettingsString));
roc_ensure(roc_free_string(&globalSettingsString));

// Assume Video Stream JSON object loaded from file...
const char *videoStreamObject = ...
roc_string videoStreamString;
roc_ensure(roc_set_string(videoStreamObject, &videoStreamString));

roc_ensure(roc_video_service_add_stream(video_service, videoStreamString));
roc_ensure(roc_free_string(&videoStreamString));

// Being monitoring video service...

Parameters

[in]	video_service	roc_video_service to add stream to.
[in]	new_stream_configuration	New JSON-formatted video-stream string.

Remarks

See stream-id.

This function is reentrant.

roc_video_service_update_stream()

roc_error roc_video_service_update_stream	(	roc_video_service	video_service,
		const char *	updated_stream_configuration
	)

Update a video-stream in a roc_video_service configuration.

The roc_string passed to this function must be a JSON-formatted video-stream configuration. The stream-id for the video stream configuration must be an existing stream-id in the current roc_video_service configuration, or this function will return an error. See roc_video_service_add_stream for an example configuation.

Example Usage

// Assume Global Settings JSON object loaded from file...
const char *globalSettingsJsonObject = ...
roc_string globalSettingsString;
roc_ensure(roc_set_string(globalSettingsJsonObject, &globalSettingsString));

roc_video_service video_service;
roc_ensure(roc_new_video_service(&video_service));
roc_ensure(roc_video_service_start(video_service, globalSettingsString));
roc_ensure(roc_free_string(&globalSettingsString));

// Assume Video Stream JSON object loaded from file...
const char *videoStreamObject = ...
roc_string videoStreamString;
roc_ensure(roc_set_string(videoStreamObject, &videoStreamString));

roc_ensure(roc_video_service_add_stream(video_service, videoStreamString));
roc_ensure(roc_free_string(&videoStreamString));

// Assume updated Video Stream JSON object loaded from file...
const char *updatedVideoStreamObject = ...
roc_string updatedVideoStreamString;
roc_ensure(roc_set_string(updatedVideoStreamObject, &updatedVideoStreamString));

// This "updatedVideoStream" must have same "stream-id" as video stream it is meant to update.
roc_ensure(roc_video_service_update_stream(video_service, updatedVideoStreamString));
roc_ensure(roc_free_string(&updatedVideoStreamString));

Parameters

[in]	video_service	roc_video_service to update stream for.
[in]	updated_stream_configuration	Updated JSON-formatted video-stream string.

Remarks

See stream-id.

This function is reentrant.

roc_video_service_remove_stream()

roc_error roc_video_service_remove_stream	(	roc_video_service	video_service,
		const char *	removed_stream_id
	)

Remove a video-stream from a roc_video_service configuration.

The roc_string passed to this function must be an existing stream-id or this function will return an error.

Example Usage

// Assume Global Settings JSON object loaded from file...
const char *globalSettingsJsonObject = ...
roc_string globalSettingsString;
roc_ensure(roc_set_string(globalSettingsJsonObject, &globalSettingsString));

roc_video_service video_service;
roc_ensure(roc_new_video_service(&video_service));
roc_ensure(roc_video_service_start(video_service, globalSettingsString));
roc_ensure(roc_free_string(&globalSettingsString));

// Assume Video Stream JSON object loaded from file...
const char *videoStreamObject = ...
roc_string videoStreamString;
roc_ensure(roc_set_string(videoStreamObject, &videoStreamString));

roc_ensure(roc_video_service_add_stream(video_service, videoStreamString));
roc_ensure(roc_free_string(&videoStreamString));

// Assume the videoStreamObject had its "stream-id" set to "example-id":
roc_ensure(roc_video_service_remove_stream(video_service, "example-id"));

Parameters

[in]	video_service	roc_video_service to remove stream from.
[in]	removed_stream_id	stream-id of video-stream to remove.

Remarks

This function is reentrant.

roc_video_service_read_configuration()

roc_error roc_video_service_read_configuration	(	roc_video_service	video_service,
		roc_string *	current_configuration
	)

Read the entire Video Service Parameters configuration for a roc_video_service.

See here for an example Video Service Parameters configuration with every setting set to it's default value. This file can also be found in the in the share folder included with the ROC SDK.

Example Usage

// Assume Global Settings JSON object loaded from file...
const char *globalSettingsJsonObject = ...
roc_string globalSettingsString;
roc_ensure(roc_set_string(globalSettingsJsonObject, &globalSettingsString));

roc_video_service video_service;
roc_ensure(roc_new_video_service(&video_service));
roc_ensure(roc_video_service_start(video_service, globalSettingsString));
roc_ensure(roc_free_string(&globalSettingsString));

// Assume Video Stream JSON object loaded from file...
const char *videoStreamObject = ...
roc_string videoStreamString;
roc_ensure(roc_set_string(videoStreamObject, &videoStreamString));

roc_ensure(roc_video_service_add_stream(video_service, videoStreamString));
roc_ensure(roc_free_string(&videoStreamString));

// Read the current configuration.
roc_string configuration;
roc_ensure(roc_video_service_read_configuration(video_service, &configuration));
printf("Current roc_video_service configuration is: %s", configuration);
roc_ensure(roc_free_string(&configuration));

Parameters

[in]	video_service	roc_video_service to read configuration for.
[in]	current_configuration	Returned configuration string.

Remarks

Remember to free current_configuration after use.

This function is reentrant.

roc_free_video_service()

roc_error roc_free_video_service

(

roc_video_service

video_service

)

Stop processing and deallocate a roc_video_service object.

This function should be called once and only once for any roc_video_service that has been initialized with roc_new_video_service. A video service can be freed even if it has not finished processing.

Parameters

[in]

video_service

roc_video_service to stop processing for.

Remarks

This function is reentrant.