A high-level interface for processing videos at a specified frame rate. More...

Typedefs
typedef struct roc_stream_type *	roc_stream
	Handle to a private streaming type.

typedef void(*	roc_stream_image_callback) (roc_stream stream, void *, roc_error, roc_image)
	Pointer to a callback function used to report video frames. More...

typedef void(*	roc_stream_encoded_image_callback) (roc_stream stream, void , roc_error, size_t, const uint8_t , roc_time)
	Pointer to a callback function used to report encoded video frames. More...

typedef void(*	roc_stream_template_callback) (roc_stream stream, void *, roc_error, roc_template)
	Pointer to a callback function used to report templates. More...

Functions
roc_error	roc_stream_load_configuration (const char stream_info, roc_stream stream)
	Configure and start a video stream and report frames to a generic callback function. More...

roc_error	roc_stream_start (roc_stream *stream, float frames_per_second, int num_worker_threads)
	Start a video stream and report frames to a generic callback function. More...

roc_error	roc_stream_set_warmup (roc_stream stream, roc_time warmup)
	Drop frames from the start of the video for the specified amount of time. More...

roc_error	roc_stream_limit (size_t *stream_limit)
	The number of streams available in the license. More...

roc_error	roc_stream_set_image_callback (roc_stream stream, roc_stream_image_callback image_callback, void *image_callback_context)
	Indicate where to send frames. More...

roc_error	roc_stream_set_encoded_image_callback (roc_stream stream, roc_stream_encoded_image_callback encoded_image_callback, void *encoded_image_callback_context)
	Indicate where to send encoded frames. More...

roc_error	roc_stream_set_video (roc_stream stream, roc_video video)
	Assign an input video to a stream. More...

roc_error	roc_stream_clear_video (roc_stream stream)
	Remove the input video from the stream previously assigned by roc_stream_set_video. More...

roc_error	roc_stream_stop (roc_stream *stream)
	Stop a video stream. More...

roc_error	roc_stream_set_frame_rate (roc_stream stream, float frames_per_second)
	Change the processing frame rate. More...

bool	roc_stream_is_paused (roc_stream stream)
	Check if a stream is paused. More...

roc_error	roc_stream_set_paused (roc_stream stream, bool paused)
	Pause or unpause a stream. More...

roc_error	roc_stream_get_true_frame_rate (roc_stream stream, float *frames_per_second)
	Obtain the real-time processing speed. More...

roc_error	roc_stream_get_frame_counts (roc_stream stream, size_t ignored, size_t queued, size_t processed, size_t dropped)
	Obtain frame count statistics. More...

roc_error	roc_stream_add_image (roc_stream stream, roc_image image)
	Manually add an image to a stream. More...

roc_error	roc_stream_add_encoded_image (roc_stream stream, size_t len, const uint8_t *input_byte_array, roc_time timestamp)
	Manually add an encoded image to a stream. More...

roc_error	roc_stream_sync (roc_stream stream, roc_time timestamp)
	Pauses the calling thread until there are no remaining roc_stream worker threads processing earlier frames. More...

Detailed Description

A high-level interface for processing videos at a specified frame rate.

Start a stream with roc_stream_start and stop it with roc_stream_stop. Control the stream with roc_stream_set_frame_rate and roc_stream_set_paused.

Typedef Documentation

◆ roc_stream_image_callback

typedef void(* roc_stream_image_callback) (roc_stream stream, void *, roc_error, roc_image)

Pointer to a callback function used to report video frames.

The function should return void and take four parameters: the origin stream, a void* callback context, a roc_error error, and a roc_image frame.

In the event of an error (non-NULL roc_error) or an end-of-stream (NULL roc_image::data) this function will not be called again by the stream.

See roc_example_track.c for an example.

Note: The roc_image is owned by the stream and will be freed automatically when this function returns.; This function must not call roc_stream_stop.; This function may call roc_stream_sync if needed.

◆ roc_stream_encoded_image_callback

typedef void(* roc_stream_encoded_image_callback) (roc_stream stream, void *, roc_error, size_t, const uint8_t *, roc_time)

Pointer to a callback function used to report encoded video frames.

The function should return void and take four parameters: the origin stream, a void* callback context, a roc_error error, size_t buffer length, a const uint8_t* encoded frame buffer, and a roc_time timestamp.

In the event of an error (non-NULL roc_error) or an end-of-stream (NULL const uint8_t* buffer) this function will not be called again by the stream.

Note: The const uint8_t* buffer is owned by the stream and will be freed automatically when this function returns.; This function must not call roc_stream_stop.; This function may call roc_stream_sync if needed.

◆ roc_stream_template_callback

typedef void(* roc_stream_template_callback) (roc_stream stream, void *, roc_error, roc_template)

Pointer to a callback function used to report templates.

The function should return void and take four parameters: the origin stream, a void* callback context, a roc_error error, and a roc_template template.

Note: The roc_template is owned by the stream and will be freed automatically when this function returns.; This function must not call roc_stream_stop.; This function may call roc_stream_sync if needed.

Function Documentation

◆ roc_stream_load_configuration()

roc_error roc_stream_load_configuration	(	const char *	stream_info,
		roc_stream *	stream
	)

Configure and start a video stream and report frames to a generic callback function.

Convenience function which calls roc_stream_start, roc_open_video, roc_video_set_camera_id and roc_stream_set_video. Please reference those functions for more information on the full details of this function.

stream_info can be either the filepath to or the contents of a JSON file.

Free a stream after use with roc_stream_stop.

roc_error roc_stream_load_configuration(const char* stream_info, roc_stream *stream)
{
    if (stream_info == nullptr || QString(stream_info).isEmpty())
        return "stream_info passed to roc_stream_load_configuration was empty!";
    // Load configuration file from a filepath or from a data pointer
    QByteArray val;
    if (QFile(stream_info).exists()) {
        QFile file;
        file.setFileName(stream_info);
        file.open(QIODevice::ReadOnly | QIODevice::Text);
        val = file.readAll();
        file.close();
    } else {
        val = stream_info;
    }
    roc_video_service_utils::source_config source(QJsonDocument::fromJson(val).object());
    if (source.url.isEmpty())
        roc_ensure("roc_stream_load_configuration called without video source url!");
    int num_worker_threads = source.threads;
    if (num_worker_threads == -1) {
        roc_ensure(roc_get_thread_limit(&num_worker_threads));
        const int ideal_thread_count = QThread::idealThreadCount();
        if ((num_worker_threads > ideal_thread_count) && (ideal_thread_count != 1))
            num_worker_threads = ideal_thread_count;
    }
    if (source.fps == 0.0f || num_worker_threads == 0)
        return "Invalid roc_stream parameters";
    roc_ensure(roc_stream_start(stream, source.fps, num_worker_threads));
    roc_ensure(roc_stream_set_warmup(*stream, source.warmup));
    return nullptr;
}

Parameters

[in]	stream_info	Filepath to or contents of configuration file.
[out]	stream	Video stream to initialize.

Remarks: This function is reentrant.

See also: roc_stream_stop

◆ roc_stream_start()

roc_error roc_stream_start	(	roc_stream *	stream,
		float	frames_per_second,
		int	num_worker_threads
	)

Start a video stream and report frames to a generic callback function.

This function spawns threads and returns immediately. A producer thread reads frames from roc_stream_set_video, and num_worker_threads consumer threads call roc_stream_set_image_callback when a new frames is available.

The stream makes a best-effort attempt to respect frames_per_second. In the case that callback can't handle frames fast enough:

For recorded videos, the producer will wait until the consumer has caught up.
For live videos (roc_is_live), the consumer will selectively drop frames so that callback is always seeing the most recent data.

You may add frames manually with roc_stream_add_image or roc_stream_add_encoded_image.

Free a stream after use with roc_stream_stop.

Use roc_stream_sync if needed to synchronize the execution of callback when num_worker_threads is greater than one.

Parameters

[out]	stream	Video stream to initialize.
[in]	frames_per_second	Desired frame rate.
[in]	num_worker_threads	Number of threads to concurrently execute `callback` with different frames.

Remarks: This function is reentrant.

See also: roc_stream_stop

◆ roc_stream_set_warmup()

roc_error roc_stream_set_warmup	(	roc_stream	stream,
		roc_time	warmup
	)

Drop frames from the start of the video for the specified amount of time.

Parameters

[in]	stream	Stream to configure.
[in]	warmup	Time in milliseconds to drop frames.

Remarks: This function is thread-safe.

◆ roc_stream_limit()

roc_error roc_stream_limit ( size_t * stream_limit )

The number of streams available in the license.

In some cases, a ROC SDK license may include a limit on the number of roc_stream that can be used at once. The number of streams in use is the sum of roc_stream_start that have not been closed by roc_stream_stop. This function returns the number of streams specified in the license file less the number of streams in use. In the license file this value is specified as "streams", and if not specified it is unlimited.

Example: size_t stream_limit;
roc_stream_limit(&stream_limit);

Parameters

[out] stream_limit The remaining number of streams available.

Remarks: This function is thread-safe.

See also: roc_template_limit

◆ roc_stream_set_image_callback()

roc_error roc_stream_set_image_callback	(	roc_stream	stream,
		roc_stream_image_callback	image_callback,
		void *	image_callback_context
	)

Indicate where to send frames.

If image_callback is NULL then roc_tracker_add_image_callback will be used, in which case callback_context must be a roc_tracker.

Parameters

[in]	stream	Stream to set image callback for.
[in]	image_callback	Function to call with frames.
[in]	image_callback_context	Pointer to arbitrary user data to provide to `image_callback`.

Remarks: This function is reentrant.

◆ roc_stream_set_encoded_image_callback()

roc_error roc_stream_set_encoded_image_callback	(	roc_stream	stream,
		roc_stream_encoded_image_callback	encoded_image_callback,
		void *	encoded_image_callback_context
	)

Indicate where to send encoded frames.

If encoded_image_callback is NULL then roc_tracker_add_encoded_image_callback will be used, in which case callback_context must be a roc_tracker.

Parameters

[in]	stream	Stream to set encoded image callback for.
[in]	encoded_image_callback	Function to call with frames.
[in]	encoded_image_callback_context	Pointer to arbitrary user data to provide to `encoded_image_callback`.

Remarks: This function is reentrant.

◆ roc_stream_set_video()

roc_error roc_stream_set_video	(	roc_stream	stream,
		roc_video	video
	)

Assign an input video to a stream.

If you don't call this function, you will be expected to provide frames manually with roc_stream_add_image or roc_stream_add_encoded_image.

Note: stream takes ownership of video and will free it automatically.

Parameters

[in]	stream	Stream to assign an input video to.
[in]	video	Video the stream will read from.

Remarks: This function is reentrant.

See also: roc_stream_clear_video

◆ roc_stream_clear_video()

roc_error roc_stream_clear_video ( roc_stream stream )

Remove the input video from the stream previously assigned by roc_stream_set_video.

Parameters

[in] stream Stream to remove the video from.

Remarks: This function is reentrant.

See also: roc_stream_set_video

◆ roc_stream_stop()

roc_error roc_stream_stop ( roc_stream * stream )

Stop a video stream.

Deallocates stream and sets it to NULL.

Parameters

[in,out] stream Stream to stop.

Remarks: This function is reentrant.

See also: roc_stream_start

◆ roc_stream_set_frame_rate()

roc_error roc_stream_set_frame_rate	(	roc_stream	stream,
		float	frames_per_second
	)

Change the processing frame rate.

Parameters

[in]	stream	Stream to change the frame rate of.
[in]	frames_per_second	Desired frame rate.

Remarks: This function is thread-safe.

See also: roc_stream_get_true_frame_rate

◆ roc_stream_is_paused()

bool roc_stream_is_paused ( roc_stream stream )

Check if a stream is paused.

For pre-recorded videos that haven't been paused with roc_stream_set_paused this can also be used to test for the end of the video.

Parameters

[in] stream Stream to check.

Returns: true if stream is paused, false otherwise.

Remarks: This function is thread-safe.

◆ roc_stream_set_paused()

roc_error roc_stream_set_paused	(	roc_stream	stream,
		bool	paused
	)

Pause or unpause a stream.

Note: When unpausing a stream corresponding to a live video it is possible that the subsequent frames read will be behind real-time. To avoid this issue, "pause" processing by calling roc_stream_clear_video instead of this function. Then resume processing by calling roc_open_video and roc_stream_set_video.

Parameters

[in]	stream	Stream to pause or unpause.
[in]	paused	Desired execution status.

Remarks: This function is reentrant.

◆ roc_stream_get_true_frame_rate()

roc_error roc_stream_get_true_frame_rate	(	roc_stream	stream,
		float *	frames_per_second
	)

Obtain the real-time processing speed.

If frames_per_second is less than roc_stream_set_frame_rate then the system can't keep up with the specified frame rate in real-time. Otherwise if frames_per_second is greater than roc_stream_set_frame_rate then the system is capable of handling frames faster than real-time.

Parameters

[in]	stream	Stream to obtain the processing speed of.
[out]	frames_per_second	Theoretical frames per second that can be processed.

Remarks: This function is reentrant.

See also: roc_stream_set_frame_rate roc_stream_get_frame_counts

◆ roc_stream_get_frame_counts()

roc_error roc_stream_get_frame_counts	(	roc_stream	stream,
		size_t *	ignored,
		size_t *	queued,
		size_t *	processed,
		size_t *	dropped
	)

Obtain frame count statistics.

Parameters

[in]	stream	Stream to obtain the frame statistics of.
[out]	ignored	Number of frames that weren't processed because they didn't meet the frame sampling rate.
[out]	queued	Number of frames in the queue for processing.
[out]	processed	Number of frames processed.
[out]	dropped	Number of frames dropped in a live video in order to keep up with real-time.

Remarks: This function is reentrant.

See also: roc_stream_get_true_frame_rate

◆ roc_stream_add_image()

roc_error roc_stream_add_image	(	roc_stream	stream,
		roc_image	image
	)

Manually add an image to a stream.

stream takes ownership of image and will free it after use.

Parameters

[in]	stream	Stream to add an image to.
[in]	image	Image to add to the stream.

Remarks: This function is thread-safe.

See also: roc_stream_add_encoded_image

◆ roc_stream_add_encoded_image()

roc_error roc_stream_add_encoded_image	(	roc_stream	stream,
		size_t	len,
		const uint8_t *	input_byte_array,
		roc_time	timestamp
	)

Manually add an encoded image to a stream.

Conceptually this function is similar to calling roc_decode_image followed by roc_stream_add_image. Unlike roc_stream_add_image, this function does not take ownership of input_byte_array.

For use cases that support streaming video in MJPEG format, this function should be preferred over roc_stream_add_image for the following reasons:

Improved speed as only images that are processed for faces will be decoded.
Decreased memory overhead from holding encoded images instead of decoded images.
When used with roc_tracker_add_encoded_image and roc_tracker_set_best_image_parameters best frames will be written to the database in their original encoding format.

Parameters

[in]	stream	Stream to add an image to.
[in]	len	Length of `input_byte_array`.
[in]	input_byte_array	Encoded image buffer.
[in]	timestamp	Image timestamp.

Remarks: This function is thread-safe.

See also: roc_stream_add_image

◆ roc_stream_sync()

roc_error roc_stream_sync	(	roc_stream	stream,
		roc_time	timestamp
	)

Pauses the calling thread until there are no remaining roc_stream worker threads processing earlier frames.

When used inside a roc_stream_image_callback or roc_stream_encoded_image_callback, this function offers a barrier that guarantees the logic that follows it is ordered with respect to the video frame timestamps.

Parameters

[in]	stream	Stream potentially processing multiple frames in parallel.
[in]	timestamp	Timestamp of the frame in question.

Remarks: This function is thread-safe.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ roc_stream_image_callback

◆ roc_stream_encoded_image_callback

◆ roc_stream_template_callback

Function Documentation

◆ roc_stream_load_configuration()

◆ roc_stream_start()

◆ roc_stream_set_warmup()

◆ roc_stream_limit()

◆ roc_stream_set_image_callback()

◆ roc_stream_set_encoded_image_callback()

◆ roc_stream_set_video()

◆ roc_stream_clear_video()

◆ roc_stream_stop()

◆ roc_stream_set_frame_rate()

◆ roc_stream_is_paused()

◆ roc_stream_set_paused()

◆ roc_stream_get_true_frame_rate()

◆ roc_stream_get_frame_counts()

◆ roc_stream_add_image()

◆ roc_stream_add_encoded_image()

◆ roc_stream_sync()