Group PJSUA_LIB_VIDEO¶

group PJSUA_LIB_VIDEO

Video support.

Functions

unsigned pjsua_vid_dev_count(void)¶

Get the number of video devices installed in the system.

Returns: The number of devices.

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.

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.

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.

Returns

PJ_SUCCESS on success or the appropriate error code.

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.

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.

void pjsua_vid_preview_param_default(pjsua_vid_preview_param *p)¶

Initialize pjsua_vid_preview_param

Parameters: p – The parameter to be initialized.

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.

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_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_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.

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.

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

Enumerates all video windows.

Parameters

id – 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.

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.

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.

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.

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.

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.

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.

pj_status_t pjsua_vid_win_set_fullscreen(pjsua_vid_win_id wid, pj_bool_t enabled)¶

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.
enabled – Set to PJ_TRUE if full screen is desired, PJ_FALSE otherwise.

Returns

PJ_SUCCESS on success, or the appropriate error code.

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.

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.

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.

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.

unsigned pjsua_vid_conf_get_active_ports(void)¶

Get current number of active ports in the bridge.

Returns: The number.

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.

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.

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.

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.

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.

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.

struct pjsua_vid_preview_param¶: #include <pjsua.h>

Parameters for starting video preview with pjsua_vid_preview_start(). Application should initialize this structure with pjsua_vid_preview_param_default().

struct pjsua_vid_win_info¶: #include <pjsua.h>

This structure describes video window info.

struct pjsua_vid_conf_port_info¶: #include <pjsua.h>

This structure describes information about a particular video media port that has been registered into the video conference bridge. Application can query this info by calling pjsua_vid_conf_get_port_info().