A class representing a stream session. More...

#include "vdo-types.h"
#include "vdo-frame.h"
#include "vdo-buffer.h"
#include "vdo-map.h"
#include <glib-object.h>

Include dependency graph for vdo-stream.h:

Go to the source code of this file.

Functions
VdoStream *	vdo_stream_new (VdoMap settings, VdoBufferFinalizer fin, GError *error)
	Create a new VdoStream. More...

VdoStream *	vdo_stream_get (guint id, GError **error)
	Get an existing video stream. More...

GList *	vdo_stream_get_all (GError **error)
	Gets all existing video streams. More...

guint	vdo_stream_get_id (VdoStream *self)
	Returns the id of this video stream. More...

gint	vdo_stream_get_fd (VdoStream self, GError *error)
	Returns a file descriptor representing the underlying socket connection. More...

gint	vdo_stream_get_event_fd (VdoStream self, GError *error)
	Returns a file descriptor for prioritized events. More...

VdoMap *	vdo_stream_get_info (VdoStream self, GError *error)
	Get the info for this video stream. More...

VdoMap *	vdo_stream_get_settings (VdoStream self, GError *error)
	Get the settings for this video stream. More...

gboolean	vdo_stream_set_settings (VdoStream self, VdoMap settings, GError **error)
	Update the settings for this video stream. More...

gboolean	vdo_stream_set_framerate (VdoStream self, gdouble framerate, GError *error)
	Update the framerate for this video stream. More...

gboolean	vdo_stream_attach (VdoStream self, VdoMap intent, GError **error)
	Attach to a Stream. More...

gboolean	vdo_stream_start (VdoStream self, GError *error)
	Start this video stream. More...

gboolean	vdo_stream_play (VdoStream self, VdoMap settings, GError **error)
	Play all buffered video and continue streaming live. More...

void	vdo_stream_stop (VdoStream *self)
	Stop this video stream. More...

gboolean	vdo_stream_force_key_frame (VdoStream self, GError *error)
	Forces this video stream to insert a key frame. More...

VdoBuffer *	vdo_stream_buffer_alloc (VdoStream self, gpointer opaque, GError *error)
	Allocates a new buffer for this stream. More...

gboolean	vdo_stream_buffer_unref (VdoStream self, VdoBuffer buffer, GError *error)
	Decreases the reference count for the specified buffer. More...

gboolean	vdo_stream_buffer_enqueue (VdoStream self, VdoBuffer buffer, GError **error)
	Enqueue a buffer for this video stream. More...

VdoBuffer *	vdo_stream_get_buffer (VdoStream self, GError *error)
	Fetches a VdoBuffer containing a frame. More...

VdoStream *	vdo_stream_to_fd (VdoMap settings, int data_fd, int meta_fd, GError *error)
	Create and start a new stream to already existing file descriptors. More...

VdoBuffer *	vdo_stream_snapshot (VdoMap settings, GError *error)
	Fetches a single VdoBuffer containing a frame. More...

VdoMap *	vdo_stream_get_event (VdoStream self, GError *error)
	Fetches the next Event. More...

Detailed Description

A class representing a stream session.

A VdoStream object is created in order to retrieve, control or monitor a video stream from the Vdo video service.

A VdoStream represents video stream or a sequence of images.

A VdoStream supports the following settings in vdo_stream_new(), they are also available in vdo_stream_get_settings() and vdo_stream_set_settings().

When one of the values below is set in the settings map it may appear in the info map as well, to reflect that they have been updated internally in vdo. The info value will differ if it has been clamped to within allowed values. Always refer to the info map to see what values are currently used.

Name	Type	Description
"format"	uint32	Video stream format as VdoFormat.
"buffer.access"	uint32	Access type as VdoBufferAccess
"buffer.count"	uint32	Hint how many in-flight buffers are desired.
"buffer.strategy"	uint32	Buffering Strategy as VdoBufferStrategy.
"input"	uint32	Video input, 1 ... inmax. 0 is invalid. No view areas.
"channel"	uint32	Video channel, 0 is overview, 1, 2, ... are view areas.
"width"	uint32	Video stream horizontal resolution.
"height"	uint32	Video stream vertical resolution.
"framerate"	double	Video stream frame rate.
"compression"	uint32	Video stream compression, Axis standard range [0:100].
"rotation"	uint32	Video stream rotation, normally [0,90,180,270].
"horizontal_flip"	boolean	Video stream horizontal flip (mirroring).
"monochrome"	boolean	Video stream monochrome encoding.
"dynamic.gop"	boolean	Enable dynamic gop
"dynamic.bitrate"	boolean	Enable dynamic bitrate
"dynamic.framerate"	boolean	Enable dynamic framerate
"dynamic.compression"	boolean	Enable dynamic compression
"qp.i"	uint32	QP value for I-frames.
"qp.p"	uint32	QP value for P-frames.
"bitrate"	uint32	Video stream bitrate (bps)
"rc.mode"	uint32	Bitrate control mode as VdoRateControlMode.
"rc.prio"	uint32	Bitrate control priority as VdoRateControlPriority.
"gop_length"	uint32	Video stream GOP length.
"overlays"	string	Enable/disable overlays (off text image application all)

H.264 Specific Settings

Name	Type	Description
"h264.profile"	uint32	H.264 profile as VdoH264Profile.

H.265 Specific Settings

Name	Type	Description
"h265.profile"	uint32	H.265 profile as VdoH265Profile.

Zipstream Specific Settings

The following Zipstream specific settings are supported for H.264 and H.265 streams.

Name	Type	Description
"zip.strength"	uint32	Zipstream strength. (AXIS OS 11.8) [0,10,20,30,40,50]
"zip.strength"	uint32	Zipstream strength. [0,1,2,4,5,6]->[0,10,20,30,40,50]
"zip.max_gop_length"	uint32	Zipstream maximum GOP length.
"zip.gop_mode"	uint32	Zipstream GOP mode [0 = fixed, 1 = dynamic]
"zip.fps_mode"	uint32	Zipstream framerate control mode: [0 = fixed, 1 = dynamic]
"zip.skip_mode"	uint32	Zipstream frame skip mode: [0 = drop, 1 = empty]
"zip.min_fps_num"	uint32	Zipstream minimum framerate numerator
"zip.min_fps_den"	uint32	Zipstream minimum framerate denominator
"zip.profile"	uint32	Zipstream profile as VdoZipStreamProfile.

ABR Specific Settings

The following ABR specific settings are supported with VDO_RATE_CONTROL_MODE_ABR.

Name	Type	Description
"abr.target_bitrate"	uint32	Stream target bitrate (bps)
"abr.retention_time"	uint32	Retention time in seconds

A VdoStream provides the following info. Info is obtained by calling vdo_stream_get_info().

Name	Type	Description
"statistics.duration"	int64	The duration of the stream in usec.
"statistics.framerate"	uint32	The framerate of the stream.
"statistics.bitrate"	uint32	The bitrate of the stream.
"statistics.frame_count"	uint32	The number of frames read.
"statistics.idrframe_count"	uint32	The number of IDR-frames read.
"statistics.bit_count"	uint32	The number of bits read.
"statistics.failed_frames"	uint32	The number of frames failed to read.
"statistics.accumulated_bytes"	uint64	The number of bytes read since stream start
"statistics.accumulated_idrbytes"	uint64	The number of bytes read from IDR-frames since stream start
"subformat"	string	The subformat for streams in YUV or raw format.
"pitch"	uint32	The row stride pitch for streams in YUV or raw format.
"width"	uint32	Actual width of the stream, for yuv and raw streams.
"height"	uint32	Actual height of the stream, for yuv and raw streams.
"scale_factor"	uint32	The scaling between the main buffer and the stream for me0/me1/zipstream streams. Ambarella only.
"initial.q.i"	uint32	Initial QP value for I-frames when the stream started
"initial.q.p"	uint32	Initial QP value for P-frames when the stream started

Function Documentation

◆ vdo_stream_attach()

gboolean vdo_stream_attach	(	VdoStream *	self,
		VdoMap *	intent,
		GError **	error
	)

Attach to a Stream.

This function is intended to be used with vdo_stream_get, it is redundant to attach to a stream which was created by vdo_stream_new, see vdo_stream_get_event for an example using "intent" with vdo_stream_new.

Parameters

self	A VdoStream.
intent	A VdoMap specifying intent or `NULL` for VDO_INTENT_DEFAULT.
error	A location to return an error.

Name	Description
VDO_INTENT_CONTROL	Grants start, stop, info, settings, keyframe
VDO_INTENT_CONSUME	The client intends to stream
VDO_INTENT_PRODUCE	The client intends to inject frames
VDO_INTENT_DEFAULT	Grants CONSUME and CONTROL
VDO_INTENT_EVENTFD	Monitor events using file descriptors
VDO_INTENT_UNIVERSE	Everything except VDO_INTENT_EVENTFD

In order to save resources enable as few intents as possible.

g_autoptr(VdoMap)    intent = vdo_map_new();
g_autoptr(VdoStream) stream = vdo_stream_get(id, NULL);
 
vdo_map_set_uint32(intent, "intent", VDO_INTENT_EVENTFD);
 
if (!vdo_stream_attach(stream, intent, &error))
    g_error("Error: %s", error->message);

Returns: TRUE on success, FALSE is error is set.

◆ vdo_stream_buffer_alloc()

VdoBuffer* vdo_stream_buffer_alloc	(	VdoStream *	self,
		gpointer	opaque,
		GError **	error
	)

Allocates a new buffer for this stream.

Invoke this function in order to allocate a new buffer for this video stream. The vdo service performs the actual memory allocation and owns the buffer. A handle to the allocated buffer is returned in the form of a VdoBuffer.

Note

This function is synchronous and will block until a response from the vdo service is received.
This function can only be invoked for non-encoded video streams.

Parameters

self	A VdoStream.
opaque	A user data pointer.
error	A location to return an error.

Returns: A VdoBuffer on success, NULL if error is set.

◆ vdo_stream_buffer_enqueue()

gboolean vdo_stream_buffer_enqueue	(	VdoStream *	self,
		VdoBuffer *	buffer,
		GError **	error
	)

Enqueue a buffer for this video stream.

Invoking this function equeues the specified VdoBuffer in the internal queue of this video stream in order to be subsequently filled with frame data.

Parameters

self	A VdoStream.
buffer	A VdoBuffer.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_buffer_unref()

gboolean vdo_stream_buffer_unref	(	VdoStream *	self,
		VdoBuffer **	buffer,
		GError **	error
	)

Decreases the reference count for the specified buffer.

The buffer is freed by the vdo service when the reference count reaches 0.

Note

This function is synchronous and will block until a response from the vdo service is received.

Parameters

self	A VdoStream.
buffer	A pointer to a VdoBuffer pointer.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_force_key_frame()

gboolean vdo_stream_force_key_frame	(	VdoStream *	self,
		GError **	error
	)

Forces this video stream to insert a key frame.

This function is invoked in order to force a key frame into a video stream. Invoking this functionon a video stream with a format that is not a video format (e.g. H.264 or H.265) will have no effect.

Parameters

self	A VdoStream.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_get()

VdoStream* vdo_stream_get	(	guint	id,
		GError **	error
	)

Get an existing video stream.

Create a new VdoStream object representing an existing video stream session with the specified id.

Parameters

id	A video stream id
error	A location to return an error.

Returns: A VdoStream or NULL on error. Free with g_object_unref().

◆ vdo_stream_get_all()

GList* vdo_stream_get_all ( GError ** error )

Gets all existing video streams.

Create new VdoStream objects representing each existing video stream session and return those in a GList.

Parameters

error A location to return an error.

Returns: A GList containing VdoStream objects or NULL on error. Free with g_list_free_full(list, g_object_unref).

◆ vdo_stream_get_buffer()

VdoBuffer* vdo_stream_get_buffer	(	VdoStream *	self,
		GError **	error
	)

Fetches a VdoBuffer containing a frame.

Stream global settings which control the behavior of this function: "socket.blocking" (default: TRUE) "socket.timeout_ms"

The following errors are transient: VDO_ERROR_NO_DATA Recover by fetching the next buffer. The following errors are expected to occur during maintenance: VDO_ERROR_INTERFACE_DOWN Recover by waiting for the service to restart. Complete VdoStream reinitialization is necessary. All remaining errors are fatal: Complete VdoStream reinitialization is necessary.

Parameters

self	A VdoStream
error	Location to store an error or `NULL`

Returns: A VdoBuffer, or NULL if error is set. Free with vdo_stream_buffer_unref().

◆ vdo_stream_get_event()

VdoMap* vdo_stream_get_event	(	VdoStream *	self,
		GError **	error
	)

Fetches the next Event.

This function is always non-blocking, it is intended to be used together with vdo_stream_get_event_fd and poll to detect when new events occur.

See VdoStreamEvent for the list of possible events, the current event is returned in the VdoMap "event" field.

The following errors are transient: VDO_ERROR_NO_EVENT The equivalent of EAGAIN, i.e. there's currently no event. The following errors are expected to occur during maintenance: VDO_ERROR_INTERFACE_DOWN Recover by waiting for the service to restart. Complete VdoStream reinitialization is necessary. All remaining errors are fatal: Complete VdoStream reinitialization is necessary.

g_autoptr(VdoMap) settings = vdo_map_new();
vdo_map_set_uint32(settings, "intent", VDO_INTENT_DEFAULT | VDO_INTENT_EVENTFD);
 
g_autoptr(VdoStream) stream = vdo_stream_new(settings, NULL, &error);
if (!stream)
  return;
 
if (!vdo_stream_start(stream, &error))
  return;
 
int fd = vdo_stream_get_fd(stream, &error);
if (fd < 0)
  return;
 
struct pollfd fds = {
  .fd = fd,
  .events = POLL_IN,
 };
 
while (1) {
  if (poll(&fds, 1, -1) < 1)
    return;
 
  g_autoptr(VdoMap) event = vdo_stream_get_event(stream, &error);
  if (!event)
    return;
  switch(vdo_map_get_uint32(event, "event", VDO_STREAM_EVENT_NONE)) {
  case VDO_STREAM_EVENT_STARTED: break;
  case VDO_STREAM_EVENT_STOPPED: break;
  default: break;
  }
}

Parameters

self	A VdoStream
error	Location to store an error or `NULL`

Returns: A VdoMap, or NULL if error is set. Free with g_object_unref().

◆ vdo_stream_get_event_fd()

gint vdo_stream_get_event_fd	(	VdoStream *	self,
		GError **	error
	)

Returns a file descriptor for prioritized events.

This requires VDO_INTENT_EVENTFD and is intended to be used together with the vdo_stream_get_event function.

Parameters

self	A VdoStream.
error	A location to return an error.

Returns: A file descriptor or -1 on error.

◆ vdo_stream_get_fd()

gint vdo_stream_get_fd	(	VdoStream *	self,
		GError **	error
	)

Returns a file descriptor representing the underlying socket connection.

The file descriptor returned by this function represents the underlying socket based connection to the vdo service. The returned file descriptor can by used as an event source in an event loop to handle asynchronous I/O events.

Parameters

self	A VdoStream.
error	A location to return an error.

Returns: A file descriptor or -1 on error.

◆ vdo_stream_get_id()

guint vdo_stream_get_id ( VdoStream * self )

Returns the id of this video stream.

Parameters

self	A VdoStream

Returns: A video stream id.

◆ vdo_stream_get_info()

VdoMap* vdo_stream_get_info	(	VdoStream *	self,
		GError **	error
	)

Get the info for this video stream.

This function is called in order to get a pointer to the info map for this video stream. The returned pointer is a pointer to a newly allocated VdoMap owned by the caller of this function. For example:

VdoMap *info = vdo_stream_get_info(stream, &error);
guint value = vdo_map_get_uint32(info, "name", 0);
g_object_unref(info);

Parameters

self	A VdoStream.
error	A location to return an error.

Returns: A pointer to a VdoMap owned by this video stream, or NULL if error is set. Free with g_object_unref().

◆ vdo_stream_get_settings()

VdoMap* vdo_stream_get_settings	(	VdoStream *	self,
		GError **	error
	)

Get the settings for this video stream.

This function is called in order to get a pointer to the settings map for this video stream. The returned pointer is a pointer to a newly allocated VdoMap owned by the caller of this function. For example:

VdoMap *settings = vdo_stream_get_settings(stream, &error);
guint value = vdo_map_get_uint32(settings, "name", 0);
g_object_unref(settings);

Parameters

self	A VdoStream.
error	A location to return an error.

Returns: A pointer to a VdoMap owned by this video stream, or NULL if error is set. Free with g_object_unref().

◆ vdo_stream_new()

VdoStream* vdo_stream_new	(	VdoMap *	settings,
		VdoBufferFinalizer	fin,
		GError **	error
	)

Create a new VdoStream.

Create a new VdoStream object representing a video stream session.

Parameters

settings	A VdoMap containing settings for the new video stream.
fin	The VdoBufferFinalizer is called before buffers are finalized.
error	A location to return an error.

Returns: A VdoStream or NULL on error. Free with g_object_unref().

◆ vdo_stream_play()

gboolean vdo_stream_play	(	VdoStream *	self,
		VdoMap *	settings,
		GError **	error
	)

Play all buffered video and continue streaming live.

This function is invoked in order to play buffered video, it requires an already started buffering stream.

Parameters

self	A VdoStream.
settings	A VdoMap controlling play or `NULL` for default.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_set_framerate()

gboolean vdo_stream_set_framerate	(	VdoStream *	self,
		gdouble	framerate,
		GError **	error
	)

Update the framerate for this video stream.

This function is invoked in order to update the framerate of a video stream. For this API to be used, the stream needs one or more of the following stream settings to be applied before the stream is started:

1) Dynamic framerate is enabled (dynamic.framerate = TRUE) 2) Zipstream fps mode is set to dynamic (zip.fps_mode = 1)

gdouble framerate = 30.0;
if (!vdo_stream_set_framerate(stream, framerate, &error)) {
    g_error("Error: %s", error->message);
}

Parameters

self	A VdoStream.
framerate	A framerate.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_set_settings()

gboolean vdo_stream_set_settings	(	VdoStream *	self,
		VdoMap *	settings,
		GError **	error
	)

Update the settings for this video stream.

This function is invoked in order to update the settings of a video stream. The caller owns the VdoMap containing the new/updated settings.

VdoMap *settings = vdo_map_new();
vdo_map_set_uint32(settings, "name", value);
if (!vdo_stream_set_settings(stream, settings, &error)) {
    g_error("Error: %s", error->message);
}
g_object_unref(settings);

Parameters

self	A VdoStream.
settings	A VdoMap containing new/updated settings.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_snapshot()

VdoBuffer* vdo_stream_snapshot	(	VdoMap *	settings,
		GError **	error
	)

Fetches a single VdoBuffer containing a frame.

Convenience function for fetching a single frame. The setup and teardown overhead is too high for continuous streaming.

Free the buffer with g_autoptr, g_object_unref or g_clear_object.

g_autoptr(VdoMap)  settings = vdo_map_new();
vdo_map_set_uint32(settings, "format", VDO_FORMAT_JPEG);
 
g_autoptr(VdoBuffer) buffer = vdo_stream_snapshot(settings, NULL);

Parameters

settings	A map of stream settings
error	Location to store an error or `NULL`

Returns: A VdoBuffer, or NULL if error is set. Free with g_object_unref().

◆ vdo_stream_start()

gboolean vdo_stream_start	(	VdoStream *	self,
		GError **	error
	)

Start this video stream.

This function is invoked in order to start a video stream.

Parameters

self	A VdoStream.
error	A location to return an error.

Returns: TRUE on success, FALSE if error is set.

◆ vdo_stream_stop()

void vdo_stream_stop ( VdoStream * self )

Stop this video stream.

This function is invoked in order to stop a video stream.

Parameters

self	A VdoStream.

◆ vdo_stream_to_fd()

VdoStream* vdo_stream_to_fd	(	VdoMap *	settings,
		int	data_fd,
		int	meta_fd,
		GError **	error
	)

Create and start a new stream to already existing file descriptors.

This is a convenience function without VdoBuffer support, instead the stream will output data and metadata to two separate file descriptors.

NOTE: metadata is not implemented yet, set meta_fd to -1.

When done with the stream, free it with g_object_unref before closing the file descriptors.

Parameters

settings	A map of stream settings
data_fd	An fd to send stream data
meta_fd	An fd to send stream metadata
error	Location to store an error or `NULL`

Returns: A VdoStream or NULL on error. Free with g_object_unref().

Functions

Detailed Description

Function Documentation

◆ vdo_stream_attach()

◆ vdo_stream_buffer_alloc()

◆ vdo_stream_buffer_enqueue()

◆ vdo_stream_buffer_unref()

◆ vdo_stream_force_key_frame()

◆ vdo_stream_get()

◆ vdo_stream_get_all()

◆ vdo_stream_get_buffer()

◆ vdo_stream_get_event()

◆ vdo_stream_get_event_fd()

◆ vdo_stream_get_fd()

◆ vdo_stream_get_id()

◆ vdo_stream_get_info()

◆ vdo_stream_get_settings()

◆ vdo_stream_new()

◆ vdo_stream_play()

◆ vdo_stream_set_framerate()

◆ vdo_stream_set_settings()

◆ vdo_stream_snapshot()

◆ vdo_stream_start()

◆ vdo_stream_stop()

◆ vdo_stream_to_fd()