Reading videos. More...

Data Structures
struct	roc_video_metadata
	Video metadata. More...

Typedefs
typedef struct roc_video_type *	roc_video
	Handle to a private video decoding type.

typedef struct roc_video_metadata	roc_video_metadata
	Video metadata.

typedef enum roc_video_log_level	roc_video_log_level
	Video decoder log levels.

Enumerations
enum	roc_video_log_level { ROC_VIDEO_QUIET = -8, ROC_VIDEO_PANIC = 0, ROC_VIDEO_FATAL = 8, ROC_VIDEO_ERROR = 16, ROC_VIDEO_WARNING = 24, ROC_VIDEO_INFO = 32, ROC_VIDEO_VERBOSE = 40 }
	Video decoder log levels. More...

Functions
roc_error	roc_set_video_logging (roc_video_log_level log_level)
	Set video decoder log level. More...

roc_error	roc_open_video (const char file_name, roc_color_space color_space, roc_video video, roc_video_metadata *metadata)
	Open a video for reading. More...

roc_error	roc_open_video_w (const wchar_t file_name, roc_color_space color_space, roc_video video, roc_video_metadata *metadata)
	Open a video from a wide character file path. More...

roc_error	roc_open_gst_video (const char video_url, roc_color_space color_space, bool gpu_decoding, roc_video video)
	Open a live video stream via GStreamer. More...

roc_error	roc_video_set_camera_id (roc_video video, roc_camera_id camera_id)
	Set roc_camera_id for frames read from the video. More...

roc_error	roc_video_set_start_time (roc_video video, roc_time timestamp)
	Set the start time for pre-recorded videos. More...

roc_error	roc_open_spinnaker (int index, roc_color_space color_space, roc_video *camera)
	Connect to a Spinnaker USB3 Vision camera. More...

roc_error	roc_is_live (roc_video video, bool *is_live)
	Determine if a video is live or recorded. More...

roc_error	roc_seek_keyframe (roc_video video, roc_time timestamp, bool backwards)
	Seek to the nearest keyframe for the given roc_time timestamp. More...

roc_error	roc_seek_frame (roc_video video, roc_time timestamp)
	Seek to the nearest frame for the given roc_time timestamp. More...

roc_error	roc_read_frame (roc_video video, roc_image *frame)
	Read the current frame and advance the video to the next frame. More...

roc_error	roc_close_video (roc_video video)
	Close an open video. More...

Detailed Description

Reading videos.

Open a roc_video with roc_open_video or roc_open_spinnaker. On Linux, open a live stream for CPU or GPU-accelerated decoding with roc_open_gst_video. Read frames sequentially with roc_read_frame, seek to a frame or keyframe with roc_seek_frame or roc_seek_keyframe and close a video with roc_close_video.

Data Structure Documentation

◆ roc_video_metadata

struct roc_video_metadata

Video metadata.

Data Fields
size_t	width	Width of the video's picture.
size_t	height	Height of the video's picture.
roc_time	duration	Length of the opened video in milliseconds. Defaults to 0 for videos of unknown duration such as webcam and IP camera video streams.
roc_time	keyframe_interval	Approximate milliseconds between keyframes. Defaults to 0 for webcam and IP camera video streams.
double	frame_rate	Average frame rate of the video in seconds.
int	bit_rate	Number of bits per second. Equal to. (video_bytes*8) / duration .
roc_media_id	media_id	See roc_media_id.
roc_camera_id	camera_id	See roc_camera_id.
bool	is_live	Indicates whether the video is live or pre-recorded.

Enumeration Type Documentation

◆ roc_video_log_level

enum roc_video_log_level

Video decoder log levels.

Enumerator
ROC_VIDEO_QUIET	Suppresss video decoder logging.
ROC_VIDEO_PANIC	Messages indicating something went really wrong and we will crash now.
ROC_VIDEO_FATAL	Messages indicating something went wrong and recovery is not possible.
ROC_VIDEO_ERROR	Messages indicating something went wrong and cannot losslessly be recovered.
ROC_VIDEO_WARNING	Messages indicating something somehow does not look correct.
ROC_VIDEO_INFO	Informational messages not indicating erroneous behavior.
ROC_VIDEO_VERBOSE	Most detailed video decoder information.

Function Documentation

◆ roc_set_video_logging()

roc_error roc_set_video_logging ( roc_video_log_level log_level )

Set video decoder log level.

Example: roc_set_video_logging(ROC_VIDEO_VERBOSE);
roc_video video;
// Decoding logs will be printed to `stderr`
roc_open_video("0", ROC_BGR24, &webcam, NULL);

roc_set_video_logging

Parameters

[in] log_level Desired decoder log level.

Remarks: This function is thread-safe.

◆ roc_open_video()

roc_error roc_open_video	(	const char *	file_name,
		roc_color_space	color_space,
		roc_video *	video,
		roc_video_metadata *	metadata
	)

Open a video for reading.

In addition to files on disk, this function supports capture devices such as a webcam by specifying the device index as the file name, as well as streaming videos over network protocols including RTSP and HTTP/HTTPS. For file_name where a hash of the file contents isn't possible, roc_media_id will be a hash of the file_name value itself.

Close a video after use with roc_close_video. Remember to close the video even if roc_open_video fails.

Note: This function is only available for x64-based versions of the SDK as well as x86 on Windows.; Be sure to read and follow Video Decoding Dependencies.; To open IP Cameras on Windows you may need to add your application to Control Panel > System and Security > Windows Defender Firewall > Allowed apps.; Some Linux systems may have their default network buffers set insufficiently low for high bandwidth streams. If you observe packet loss for live streams try adjusting these buffers as described here.

Supported Video Formats

ROC SDK makes use of the system's FFmpeg / libAV library so supported file formats may vary slightly by installation. The standard list of supported formats is available here.

Passing Parameters to FFmpeg

roc_open_video supports passing parameters to FFmpeg via a query string in the file_name. Please consult the FFmpeg documentation for a list of valid parameters. For live streams it may be the case network downtime causes temporary connectivity issues. In this case you may pass reconnect_timeout as a query parameter.

If reconnect_timeout is -1, attempt reconnection indefinitely.
If reconnect_timeout is 0, do not attempt reconnection.
If reconnect_timeout is >0, attempt reconnection for reconnect_timeout milliseconds.

Example: // Open a video on disk and request basic metadata.
roc_video video;
roc_video_metadata video_metadata;
roc_open_video("gangnam-style.mp4", ROC_BGR24, &video, &video_metadata);
// Open a webcam with default parameters.
roc_video webcam;
roc_open_video("0", ROC_BGR24, &webcam, NULL);
// Open a webcam while specifying framerate and size in the query string.
roc_video webcam;
roc_open_video("0?framerate=30&video_size=1280x720", ROC_BGR24, &webcam,
NULL);
// Open an IP camera and attempt recconection on network failure for
for 5 minutes.
roc_video ip_camera;
roc_open_video(
"http://204.248.124.202/mjpg/video.mjpg?reconnect_timeout=300000",
ROC_BGR24, &ip_camera, NULL);
// Stream a video over RTSP. Specify internal TCP buffer size through
// the query string.
roc_video rtsp_video
roc_open_video("rtsp://admin:pass@example.com/live/ch0?buffer_size=6220800",
ROC_BGR24
&rtsp_video, NULL);

Parameters

[in]	file_name	Path to video file.
[in]	color_space	Desired color space, see Color Space Considerations.
[out]	video	Address to store the opened video.
[out]	metadata	Address to metadata associated with the opened video, or `NULL`.

Remarks: This function is reentrant.

See also: roc_close_video roc_open_video_w

◆ roc_open_video_w()

roc_error roc_open_video_w	(	const wchar_t *	file_name,
		roc_color_space	color_space,
		roc_video *	video,
		roc_video_metadata *	metadata
	)

Open a video from a wide character file path.

See roc_open_video for details.

Parameters

[in]	file_name	Path to video file.
[in]	color_space	Desired color space, see Color Space Considerations.
[out]	video	Address to store the opened video.
[out]	metadata	Address to metadata associated with the opened video, or `NULL`.

Remarks: This function is reentrant.

See also: roc_open_video

◆ roc_open_gst_video()

roc_error roc_open_gst_video	(	const char *	video_url,
		roc_color_space	color_space,
		bool	gpu_decoding,
		roc_video *	video
	)

Open a live video stream via GStreamer.

This function supports opening live streams for decoding via the GStreamer backend. The live stream is retrieved via the video source's URI. See official URI schemes at https://en.wikipedia.org/wiki/List_of_URI_schemes. Supported URI's include rtsp, http, https, and udp. By default, GStreamer performs video decoding on the CPU. GPU-accelerated video decoding can be enabled by following the steps in Video Decoding Dependencies, and setting the gpu_decoding flag to true. As this function only supports live video streams, seeking is not supported.

With the exception of seek functions, videos opened with this function are compatible with the same functions as videos opened with roc_open_video. Close a video after use with roc_close_video. Remember to close the video even if roc_open_video fails.

Note: This function is only available on Linux.

Example: roc_video video;
// Open a live stream with GStreamer CPU decoding
roc_open_gst_video("rtsp://user:password@192.168.1.16/axis-media/media.amp",
ROC_BGR24,
false,
&video);
// Open a live stream with GStreamer GPU-accelerated decoding
roc_open_gst_video("rtsp://user:password@192.168.1.16/axis-media/media.amp",
ROC_BGR24,
true,
&video);

Parameters

[in]	video_url	URI for video live stream.
[in]	color_space	Desired color space, see Color Space Considerations.
[in]	gpu_decoding	Enable GPU-accelerated decoding.
[out]	video	Address to store the opened video.

Remarks: This function is reentrant.

See also: roc_close_video

◆ roc_video_set_camera_id()

roc_error roc_video_set_camera_id	(	roc_video	video,
		roc_camera_id	camera_id
	)

Set roc_camera_id for frames read from the video.

Parameters

[in]	video	Video to set the CameraID of.
[in]	camera_id	CameraID to assign to frames read from the video.

Remarks: This function is reentrant.

◆ roc_video_set_start_time()

roc_error roc_video_set_start_time	(	roc_video	video,
		roc_time	timestamp
	)

Set the start time for pre-recorded videos.

Only valid for pre-recorded videos. Start time can be given as milliseconds since epoch, or as an ISO 8601 formatted date time. Pre-recorded videos start at time 0 by default if this function is not called. This function must be called before roc_read_frame, roc_seek_keyframe, or roc_seek_frame if it will be called at all.

Parameters

[in]	video	Video to set the start time for.
[in]	timestamp	Start time, given as milliseconds since epoch.

Remarks: This function is reentrant.

◆ roc_open_spinnaker()

roc_error roc_open_spinnaker	(	int	index,
		roc_color_space	color_space,
		roc_video *	camera
	)

Connect to a Spinnaker USB3 Vision camera.

About the Spinnaker Software Development Kit.

Note: This function is currently only supported on Windows x64.; The use of this function requires an installation of the Spinnaker SDK, available for download here.

Example: roc_video video;
roc_open_spinnaker(0, ROC_BGR24, &video);

Parameters

[in]	index	Camera to open (default is `0`).
[in]	color_space	Desired color space, see Color Space Considerations.
[out]	camera	Address to store the opened camera.

Remarks: This function is reentrant.

◆ roc_is_live()

roc_error roc_is_live	(	roc_video	video,
		bool *	is_live
	)

Determine if a video is live or recorded.

Example: roc_video video = ...;
bool is_live;
roc_is_live(video, &is_live);

Parameters

[in]	video	Video to query.
[out]	is_live	Live status of `video`.

Remarks: This function is thread-safe.

◆ roc_seek_keyframe()

roc_error roc_seek_keyframe	(	roc_video	video,
		roc_time	timestamp,
		bool	backwards
	)

Seek to the nearest keyframe for the given roc_time timestamp.

If timestamp does not correspond to a keyframe then backwards will determine whether the video is advanced forwards to the next keyframe or backwards to the previous keyframe.

If timestamp is set to ROC_NO_TIMESTAMP, the function will seek to the next keyframe or backwards to the previous keyframe from the current position in the video.

If timestamp is beyond the duration of the video, the function will seek to the end of the video and return without error.

Iterating Over Keyframes

Iterate forward over keyframes.: roc_video video = ...;
while (true) {
roc_image frame;
roc_time timestamp;
roc_read_frame(video, &frame, &timestamp);
if (!frame.data)
break;
// Process the frame
roc_free_image(frame);
roc_seek_keyframe(video, ROC_NO_TIMESTAMP, false);
}

Seek to the nearest keyframe for the given timestamp.: roc_video video = ...;
roc_time timestamp = ...;
roc_seek_keyframe(video, timestamp, false);

Parameters

[in]	video	Video to perform keyframe seek on.
[in]	timestamp	Timestamp to seek to.
[in]	backwards	Seek to the nearest keyframe before `timestamp`.

Remarks: This function is reentrant.

◆ roc_seek_frame()

roc_error roc_seek_frame	(	roc_video	video,
		roc_time	timestamp
	)

Seek to the nearest frame for the given roc_time timestamp.

If timestamp is beyond the duration of the video, the function will seek to the end of the video and return without error.

Iterating Over Frames

Process a frame every second.: roc_video video = ...;
roc_time timestamp_of_interest = 0;
while (true) {
roc_image frame;
roc_time timestamp;
roc_read_frame(video, &frame, &timestamp);
if (!frame.data)
break;
// Process the frame
roc_free_image(frame);
timestamp_of_interest += 1000;
roc_seek_frame(video, timestamp_of_interest, false);
}

Seek to the nearest frame for the given timestamp.: roc_video video = ...;
roc_time timestamp = ...;
roc_seek_frame(video, timestamp, false);

Parameters

[in]	video	Video to perform frame seek on.
[in]	timestamp	Timestamp to seek to.

Remarks: This function is reentrant.

◆ roc_read_frame()

roc_error roc_read_frame	(	roc_video	video,
		roc_image *	frame
	)

Read the current frame and advance the video to the next frame.

If no frames are left in video, frame.data will be NULL, frame.timestamp will be ROC_NO_TIMESTAMP, and the function will return without error.

Free frame after use with roc_free_image.

Example: roc_video video = ...;
roc_image frame;
roc_read_frame(video, &frame);

Parameters

[in]	video	Video to decode.
[out]	frame	Address to store the decoded frame.

Remarks: This function is reentrant.

◆ roc_close_video()

roc_error roc_close_video ( roc_video video )

Close an open video.

This will free memory associated with video. If video is NULL this operation is a no-op.

Example: roc_video video = ...;
roc_close_video(video);

Parameters

[in] video The video to close.

Remarks: This function is reentrant.

See also: roc_open_video

Data Structures

Typedefs

Enumerations

Functions

Detailed Description

Data Structure Documentation

◆ roc_video_metadata

Enumeration Type Documentation

◆ roc_video_log_level

Function Documentation

◆ roc_set_video_logging()

◆ roc_open_video()

Supported Video Formats

Passing Parameters to FFmpeg

◆ roc_open_video_w()

◆ roc_open_gst_video()

◆ roc_video_set_camera_id()

◆ roc_video_set_start_time()

◆ roc_open_spinnaker()

◆ roc_is_live()

◆ roc_seek_keyframe()

Iterating Over Keyframes

◆ roc_seek_frame()

Iterating Over Frames

◆ roc_read_frame()

◆ roc_close_video()