Video support. More...

Data Structures
struct	pjsua_vid_preview_param

struct	pjsua_vid_win_info

struct	pjsua_vid_conf_port_info

Macros
#define	PJSUA_DONT_INIT_VID_DEV_SUBSYS 0

Functions
unsigned	pjsua_vid_dev_count (void)

pj_status_t	pjsua_vid_dev_get_info (pjmedia_vid_dev_index id, pjmedia_vid_dev_info *vdi)

pj_bool_t	pjsua_vid_dev_is_active (pjmedia_vid_dev_index id)

pj_status_t	pjsua_vid_dev_set_setting (pjmedia_vid_dev_index id, pjmedia_vid_dev_cap cap, const void *pval, pj_bool_t keep)

pj_status_t	pjsua_vid_dev_get_setting (pjmedia_vid_dev_index id, pjmedia_vid_dev_cap cap, void *pval)

pj_status_t	pjsua_vid_enum_devs (pjmedia_vid_dev_info info[], unsigned *count)

void	pjsua_vid_preview_param_default (pjsua_vid_preview_param *p)

pj_bool_t	pjsua_vid_preview_has_native (pjmedia_vid_dev_index id)

pj_status_t	pjsua_vid_preview_start (pjmedia_vid_dev_index id, const pjsua_vid_preview_param *p)

pjsua_vid_win_id	pjsua_vid_preview_get_win (pjmedia_vid_dev_index id)

pjsua_conf_port_id	pjsua_vid_preview_get_vid_conf_port (pjmedia_vid_dev_index id)

pj_status_t	pjsua_vid_preview_stop (pjmedia_vid_dev_index id)

pj_status_t	pjsua_vid_enum_wins (pjsua_vid_win_id wids[], unsigned *count)

pj_status_t	pjsua_vid_win_get_info (pjsua_vid_win_id wid, pjsua_vid_win_info *wi)

pj_status_t	pjsua_vid_win_set_show (pjsua_vid_win_id wid, pj_bool_t show)

pj_status_t	pjsua_vid_win_set_pos (pjsua_vid_win_id wid, const pjmedia_coord *pos)

pj_status_t	pjsua_vid_win_set_size (pjsua_vid_win_id wid, const pjmedia_rect_size *size)

pj_status_t	pjsua_vid_win_set_win (pjsua_vid_win_id wid, const pjmedia_vid_dev_hwnd *win)

pj_status_t	pjsua_vid_win_rotate (pjsua_vid_win_id wid, int angle)

pj_status_t	pjsua_vid_win_set_fullscreen (pjsua_vid_win_id wid, pjmedia_vid_dev_fullscreen_flag mode)

pj_status_t	pjsua_vid_enum_codecs (pjsua_codec_info id[], unsigned *count)

pj_status_t	pjsua_vid_codec_set_priority (const pj_str_t *codec_id, pj_uint8_t priority)

pj_status_t	pjsua_vid_codec_get_param (const pj_str_t codec_id, pjmedia_vid_codec_param param)

pj_status_t	pjsua_vid_codec_set_param (const pj_str_t codec_id, const pjmedia_vid_codec_param param)

unsigned	pjsua_vid_conf_get_active_ports (void)

pj_status_t	pjsua_vid_conf_enum_ports (pjsua_conf_port_id id[], unsigned *count)

pj_status_t	pjsua_vid_conf_get_port_info (pjsua_conf_port_id port_id, pjsua_vid_conf_port_info *info)

pj_status_t	pjsua_vid_conf_add_port (pj_pool_t pool, pjmedia_port port, const void param, pjsua_conf_port_id p_id)

pj_status_t	pjsua_vid_conf_remove_port (pjsua_conf_port_id port_id)

pj_status_t	pjsua_vid_conf_connect (pjsua_conf_port_id source, pjsua_conf_port_id sink, const void *param)

pj_status_t	pjsua_vid_conf_disconnect (pjsua_conf_port_id source, pjsua_conf_port_id sink)

pj_status_t	pjsua_vid_conf_update_port (pjsua_conf_port_id port_id)

Detailed Description

Macro Definition Documentation

◆ PJSUA_DONT_INIT_VID_DEV_SUBSYS

#define PJSUA_DONT_INIT_VID_DEV_SUBSYS 0

Controls whether PJSUA-LIB should not initialize video device subsystem in the PJSUA initialization. The video device subsystem initialization may need to open cameras to enumerates available cameras and their capabilities, which may not be preferable for some applications because it may trigger privacy-alert/permission notification on application startup (e.g: on Android app).

If this is set, later application should manually initialize video device subsystem when it needs to use any video devices (camera and renderer), i.e: by invoking pjmedia_vid_dev_subsys_init() for PJSUA or VidDevManager::initSubsys() for PJSUA2.

Note that pjmedia_vid_dev_subsys_init() should not be called multiple times (unless each has corresponding pjmedia_vid_dev_subsys_shutdown()), while VidDevManager::initSubsys() is safe to be called multiple times.

Default: 0 (no)

Function Documentation

◆ pjsua_vid_dev_count()

unsigned pjsua_vid_dev_count ( void )

Get the number of video devices installed in the system.

Returns: The number of devices.

◆ pjsua_vid_dev_get_info()

pj_status_t pjsua_vid_dev_get_info	(	pjmedia_vid_dev_index	id,
		pjmedia_vid_dev_info *	vdi
	)

Retrieve the video device info for the specified device index.

Parameters

id	The device index.
vdi	Device info to be initialized.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_dev_is_active()

pj_bool_t pjsua_vid_dev_is_active ( pjmedia_vid_dev_index id )

Check whether the video capture device is currently active, i.e. if a video preview has been started or there is a video call using the device. This function will return PJ_FALSE for video renderer device.

Parameters

id	The video device index.

Returns: PJ_TRUE if active, PJ_FALSE otherwise.

◆ pjsua_vid_dev_set_setting()

pj_status_t pjsua_vid_dev_set_setting	(	pjmedia_vid_dev_index	id,
		pjmedia_vid_dev_cap	cap,
		const void *	pval,
		pj_bool_t	keep
	)

Configure the capability of a video capture device. If the device is currently active (i.e. if there is a video call using the device or a video preview has been started), the function will forward the setting to the video device instance to be applied immediately, if it supports it.

The setting will be saved for future opening of the video device, if the "keep" argument is set to non-zero. If the video device is currently inactive, and the "keep" argument is false, this function will return error.

Note: This function will only works for video capture devices. To configure the setting of video renderer device instances, use pjsua_vid_win API instead.

Warning: If application refreshes the video device list, it needs to manually update the settings to reflect the newly updated video device indexes. See pjmedia_vid_dev_refresh() for more information.

See also pjmedia_vid_stream_set_cap() for more information about setting a video device capability.

Parameters

id	The video device index.
cap	The video device capability to change.
pval	Pointer to value. Please see pjmedia_vid_dev_cap documentation about the type of value to be supplied for each setting.
keep	(see description)

Returns: PJ_SUCCESS on success or the appropriate error code.

◆ pjsua_vid_dev_get_setting()

pj_status_t pjsua_vid_dev_get_setting	(	pjmedia_vid_dev_index	id,
		pjmedia_vid_dev_cap	cap,
		void *	pval
	)

Retrieve the value of a video capture device setting. If the device is currently active (i.e. if there is a video call using the device or a video preview has been started), the function will forward the request to the video device. If video device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this function will return error. The function only works for video capture device.

Parameters

id	The video device index.
cap	The video device capability to retrieve.
pval	Pointer to receive the value. Please see pjmedia_vid_dev_cap documentation about the type of value to be supplied for each setting.

Returns: PJ_SUCCESS on success or the appropriate error code.

◆ pjsua_vid_enum_devs()

pj_status_t pjsua_vid_enum_devs	(	pjmedia_vid_dev_info	info[],
		unsigned *	count
	)

Enum all video devices installed in the system.

Parameters

info	Array of info to be initialized.
count	On input, specifies max elements in the array. On return, it contains actual number of elements that have been initialized.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_preview_param_default()

void pjsua_vid_preview_param_default ( pjsua_vid_preview_param * p )

Initialize pjsua_vid_preview_param

Parameters

p	The parameter to be initialized.

◆ pjsua_vid_preview_has_native()

pj_bool_t pjsua_vid_preview_has_native ( pjmedia_vid_dev_index id )

Determine if the specified video input device has built-in native preview capability. This is a convenience function that is equal to querying device's capability for PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW capability.

Parameters

id	The capture device ID.

Returns: PJ_TRUE if it has.

◆ pjsua_vid_preview_start()

pj_status_t pjsua_vid_preview_start	(	pjmedia_vid_dev_index	id,
		const pjsua_vid_preview_param *	p
	)

Start video preview window for the specified capture device.

Parameters

id	The capture device ID where its preview will be started.
p	Optional video preview parameters. Specify NULL to use default values.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_preview_get_win()

pjsua_vid_win_id pjsua_vid_preview_get_win ( pjmedia_vid_dev_index id )

Get the preview window handle associated with the capture device, if any.

Parameters

id	The capture device ID.

Returns: The window ID of the preview window for the specified capture device ID, or PJSUA_INVALID_ID if preview has not been started for the device.

◆ pjsua_vid_preview_get_vid_conf_port()

pjsua_conf_port_id pjsua_vid_preview_get_vid_conf_port ( pjmedia_vid_dev_index id )

Get video conference slot ID of the specified capture device, if any.

Parameters

id	The capture device ID.

Returns: The video conference slot ID of the specified capture device ID, or PJSUA_INVALID_ID if preview has not been started for the device.

◆ pjsua_vid_preview_stop()

pj_status_t pjsua_vid_preview_stop ( pjmedia_vid_dev_index id )

Stop video preview.

Parameters

id	The capture device ID.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_enum_wins()

pj_status_t pjsua_vid_enum_wins	(	pjsua_vid_win_id	wids[],
		unsigned *	count
	)

Enumerates all video windows.

Parameters

wids	Array of window ID to be initialized.
count	On input, specifies max elements in the array. On return, it contains actual number of elements that have been initialized.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_get_info()

pj_status_t pjsua_vid_win_get_info	(	pjsua_vid_win_id	wid,
		pjsua_vid_win_info *	wi
	)

Get window info.

Parameters

wid	The video window ID.
wi	The video window info to be initialized.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_set_show()

pj_status_t pjsua_vid_win_set_show	(	pjsua_vid_win_id	wid,
		pj_bool_t	show
	)

Show or hide window. This operation is not valid for native windows (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API must be used instead.

Parameters

wid	The video window ID.
show	Set to PJ_TRUE to show the window, PJ_FALSE to hide the window.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_set_pos()

pj_status_t pjsua_vid_win_set_pos	(	pjsua_vid_win_id	wid,
		const pjmedia_coord *	pos
	)

Set video window position. This operation is not valid for native windows (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API must be used instead.

Parameters

wid	The video window ID.
pos	The window position.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_set_size()

pj_status_t pjsua_vid_win_set_size	(	pjsua_vid_win_id	wid,
		const pjmedia_rect_size *	size
	)

Resize window. This operation is not valid for native windows (pjsua_vid_win_info.is_native=PJ_TRUE), on which native windowing API must be used instead.

Parameters

wid	The video window ID.
size	The new window size.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_set_win()

pj_status_t pjsua_vid_win_set_win	(	pjsua_vid_win_id	wid,
		const pjmedia_vid_dev_hwnd *	win
	)

Set output window. This operation is valid only when the underlying video device supports PJMEDIA_VIDEO_DEV_CAP_OUTPUT_WINDOW capability AND allows the output window to be changed on-the-fly. Currently it is only supported on Android.

Parameters

wid	The video window ID.
win	The new output window.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_rotate()

pj_status_t pjsua_vid_win_rotate	(	pjsua_vid_win_id	wid,
		int	angle
	)

Rotate the video window. This function will change the video orientation and also possibly the video window size (width and height get swapped). This operation is not valid for native windows (pjsua_vid_win_info.is_native =PJ_TRUE), on which native windowing API must be used instead.

Parameters

wid	The video window ID.
angle	The rotation angle in degrees, must be multiple of 90. Specify positive value for clockwise rotation or negative value for counter-clockwise rotation.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_win_set_fullscreen()

pj_status_t pjsua_vid_win_set_fullscreen	(	pjsua_vid_win_id	wid,
		pjmedia_vid_dev_fullscreen_flag	mode
	)

Set video window full-screen. This operation is valid only when the underlying video device supports PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN capability. Currently it is only supported on SDL backend.

Parameters

wid	The video window ID.
mode	Fullscreen mode, see pjmedia_vid_dev_fullscreen_flag.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_enum_codecs()

pj_status_t pjsua_vid_enum_codecs	(	pjsua_codec_info	id[],
		unsigned *	count
	)

Enum all supported video codecs in the system.

Parameters

id	Array of ID to be initialized.
count	On input, specifies max elements in the array. On return, it contains actual number of elements that have been initialized.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_codec_set_priority()

pj_status_t pjsua_vid_codec_set_priority	(	const pj_str_t *	codec_id,
		pj_uint8_t	priority
	)

Change video codec priority.

Parameters

codec_id	Codec ID, which is a string that uniquely identify the codec (such as "H263/90000"). Please see pjsua manual or pjmedia codec reference for details.
priority	Codec priority, 0-255, where zero means to disable the codec.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_codec_get_param()

pj_status_t pjsua_vid_codec_get_param	(	const pj_str_t *	codec_id,
		pjmedia_vid_codec_param *	param
	)

Get video codec parameters.

Parameters

codec_id	Codec ID.
param	Structure to receive video codec parameters.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_codec_set_param()

pj_status_t pjsua_vid_codec_set_param	(	const pj_str_t *	codec_id,
		const pjmedia_vid_codec_param *	param
	)

Set video codec parameters.

Parameters

codec_id	Codec ID.
param	Codec parameter to set. Set to NULL to reset codec parameter to library default settings.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_get_active_ports()

unsigned pjsua_vid_conf_get_active_ports ( void )

Get current number of active ports in the bridge.

Returns: The number.

◆ pjsua_vid_conf_enum_ports()

pj_status_t pjsua_vid_conf_enum_ports	(	pjsua_conf_port_id	id[],
		unsigned *	count
	)

Enumerate all video conference ports.

Parameters

id	Array of conference port ID to be initialized.
count	On input, specifies max elements in the array. On return, it contains actual number of elements that have been initialized.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_get_port_info()

pj_status_t pjsua_vid_conf_get_port_info	(	pjsua_conf_port_id	port_id,
		pjsua_vid_conf_port_info *	info
	)

Get information about the specified video conference port

Parameters

port_id	Port identification.
info	Pointer to store the port info.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_add_port()

pj_status_t pjsua_vid_conf_add_port	(	pj_pool_t *	pool,
		pjmedia_port *	port,
		const void *	param,
		pjsua_conf_port_id *	p_id
	)

Add arbitrary video media port to PJSUA's video conference bridge. Application can use this function to add the media port that it creates. For media ports that are created by PJSUA-LIB (such as calls, AVI player), PJSUA-LIB will automatically add the port to the bridge.

Parameters

pool	Pool to use.
port	Media port to be added to the bridge.
param	Currently this is not used and must be set to NULL.
p_id	Optional pointer to receive the conference slot id.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_remove_port()

pj_status_t pjsua_vid_conf_remove_port ( pjsua_conf_port_id port_id )

Remove arbitrary slot from the video conference bridge. Application should only call this function if it registered the port manually with previous call to pjsua_vid_conf_add_port().

Parameters

port_id The slot id of the port to be removed.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_connect()

pj_status_t pjsua_vid_conf_connect	(	pjsua_conf_port_id	source,
		pjsua_conf_port_id	sink,
		const void *	param
	)

Establish unidirectional video flow from souce to sink. One source may transmit to multiple destinations/sink. And if multiple sources are transmitting to the same sink, the video will be mixed together (currently, each source will be resized down so all sources will occupy the same portion in the sink video frame). Source and sink may refer to the same ID, effectively looping the media.

If bidirectional media flow is desired, application needs to call this function twice, with the second one having the arguments reversed.

Parameters

source	Port ID of the source media/transmitter.
sink	Port ID of the destination media/received.
param	Currently this is not used and must be set to NULL.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_disconnect()

pj_status_t pjsua_vid_conf_disconnect	(	pjsua_conf_port_id	source,
		pjsua_conf_port_id	sink
	)

Disconnect video flow from the source to destination port.

Parameters

source	Port ID of the source media/transmitter.
sink	Port ID of the destination media/received.

Returns: PJ_SUCCESS on success, or the appropriate error code.

◆ pjsua_vid_conf_update_port()

pj_status_t pjsua_vid_conf_update_port ( pjsua_conf_port_id port_id )

Update or refresh port states from video port info. Some port may change its port info in the middle of a session, for example when a video stream decoder learns that incoming video size or frame rate has changed, video conference needs to be informed to update its internal states.

Parameters

port_id The slot id of the port to be updated.

Returns: PJ_SUCCESS on success, or the appropriate error code.

References PJ_END_DECL.

Data Structures

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ PJSUA_DONT_INIT_VID_DEV_SUBSYS

Function Documentation

◆ pjsua_vid_dev_count()

◆ pjsua_vid_dev_get_info()

◆ pjsua_vid_dev_is_active()

◆ pjsua_vid_dev_set_setting()

◆ pjsua_vid_dev_get_setting()

◆ pjsua_vid_enum_devs()

◆ pjsua_vid_preview_param_default()

◆ pjsua_vid_preview_has_native()

◆ pjsua_vid_preview_start()

◆ pjsua_vid_preview_get_win()

◆ pjsua_vid_preview_get_vid_conf_port()

◆ pjsua_vid_preview_stop()

◆ pjsua_vid_enum_wins()

◆ pjsua_vid_win_get_info()

◆ pjsua_vid_win_set_show()

◆ pjsua_vid_win_set_pos()

◆ pjsua_vid_win_set_size()

◆ pjsua_vid_win_set_win()

◆ pjsua_vid_win_rotate()

◆ pjsua_vid_win_set_fullscreen()

◆ pjsua_vid_enum_codecs()

◆ pjsua_vid_codec_set_priority()

◆ pjsua_vid_codec_get_param()

◆ pjsua_vid_codec_set_param()

◆ pjsua_vid_conf_get_active_ports()

◆ pjsua_vid_conf_enum_ports()

◆ pjsua_vid_conf_get_port_info()

◆ pjsua_vid_conf_add_port()

◆ pjsua_vid_conf_remove_port()

◆ pjsua_vid_conf_connect()

◆ pjsua_vid_conf_disconnect()

◆ pjsua_vid_conf_update_port()