Group PJSUA_LIB_VIDEO

group PJSUA_LIB_VIDEO

Video support.

Defines

PJSUA_DONT_INIT_VID_DEV_SUBSYS

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)

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.

  • keep – (see description)

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:
  • 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.

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

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.

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.

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().

Public Members

pjmedia_vid_dev_index rend_id

Device ID for the video renderer to be used for rendering the capture stream for preview. This parameter is ignored if native preview is being used.

Default: PJMEDIA_VID_DEFAULT_RENDER_DEV

pj_bool_t show

Show window initially.

Default: PJ_TRUE.

unsigned wnd_flags

Window flags. The value is a bitmask combination of pjmedia_vid_dev_wnd_flag.

Default: 0.

pjmedia_format format

Media format. Initialize this with pjmedia_format_init_video(). If left unitialized, this parameter will not be used.

pjmedia_vid_dev_hwnd wnd

Optional output window to be used to display the video preview. This parameter will only be used if the video device supports PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW capability and the capability is not read-only.

struct pjsua_vid_win_info
#include <pjsua.h>

This structure describes video window info.

Public Members

pj_bool_t is_native

Flag to indicate whether this window is a native window, such as created by built-in preview device. If this field is PJ_TRUE, only the native window handle field of this structure is valid.

pjmedia_vid_dev_hwnd hwnd

Native window handle.

pjmedia_vid_dev_index rdr_dev

Renderer device ID.

pjsua_conf_port_id slot_id

Renderer port ID in the video conference bridge.

pj_bool_t show

Window show status. The window is hidden if false.

pjmedia_coord pos

Window position.

pjmedia_rect_size size

Window size.

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().

Public Members

pjsua_conf_port_id slot_id

Conference port number.

pj_str_t name

Port name.

pjmedia_format format

Format.

unsigned listener_cnt

Number of listeners in the array.

pjsua_conf_port_id listeners[254]

Array of listeners (in other words, ports where this port is transmitting to).

unsigned transmitter_cnt

Number of transmitters in the array.

pjsua_conf_port_id transmitters[254]

Array of transmitters (in other words, ports where this port is receiving from).