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.

Return

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • id: The device index.

  • vdi: Device info to be initialized.

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.

Return

PJ_TRUE if active, PJ_FALSE otherwise.

Parameters
  • id: The video device index.

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.

Return

PJ_SUCCESS on success or the appropriate error code.

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.

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.

Return

PJ_SUCCESS on success or the appropriate error code.

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.

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

Enum all video devices installed in the system.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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.

Return

PJ_TRUE if it has.

Parameters
  • id: The capture device ID.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • id: The capture device ID where its preview will be started.

  • p: Optional video preview parameters. Specify NULL to use default values.

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.

Return

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.

Parameters
  • id: The capture device ID.

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.

Return

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

Parameters
  • id: The capture device ID.

pj_status_t pjsua_vid_preview_stop(pjmedia_vid_dev_index id)

Stop video preview.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • id: The capture device ID.

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

Enumerates all video windows.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

pj_status_t pjsua_vid_win_get_info(pjsua_vid_win_id wid, pjsua_vid_win_info *wi)

Get window info.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • wid: The video window ID.

  • wi: The video window info to be initialized.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • wid: The video window ID.

  • show: Set to PJ_TRUE to show the window, PJ_FALSE to hide the window.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • wid: The video window ID.

  • pos: The window position.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • wid: The video window ID.

  • size: The new window size.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • wid: The video window ID.

  • win: The new output window.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • wid: The video window ID.

  • enabled: Set to PJ_TRUE if full screen is desired, PJ_FALSE otherwise.

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

Enum all supported video codecs in the system.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

pj_status_t pjsua_vid_codec_set_priority(const pj_str_t *codec_id, pj_uint8_t priority)

Change video codec priority.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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

Get video codec parameters.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • codec_id: Codec ID.

  • param: Structure to receive video codec parameters.

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

Set video codec parameters.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • codec_id: Codec ID.

  • param: Codec parameter to set. Set to NULL to reset codec parameter to library default settings.

unsigned pjsua_vid_conf_get_active_ports(void)

Get current number of active ports in the bridge.

Return

The number.

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

Enumerate all video conference ports.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • port_id: Port identification.

  • info: Pointer to store the port 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)

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • port_id: The slot id of the port to be removed.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

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.

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.

Return

PJ_SUCCESS on success, or the appropriate error code.

Parameters
  • source: Port ID of the source media/transmitter.

  • sink: Port ID of the destination media/received.

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