Video conference bridge

group PJMEDIA_VID_CONF

Video conference bridge implementation destination.

This describes the video conference bridge implementation in PJMEDIA. The conference bridge provides powerful and efficient mechanism to route the video flow and combine multiple video data from multiple video sources.

Typedefs

typedef struct pjmedia_vid_conf pjmedia_vid_conf

Opaque type for video conference bridge.

typedef void (*pjmedia_vid_conf_op_cb)(const pjmedia_vid_conf_op_info *info)

The callback type to be called upon the successful completion of a conference port operation.

Param param:

The conference op callback param.

Enums

enum pjmedia_vid_conf_op_type

Video conference operation type enumeration.

Values:

enumerator PJMEDIA_VID_CONF_OP_UNKNOWN

The operation is unknown.

enumerator PJMEDIA_VID_CONF_OP_ADD_PORT

The adding port operation.

enumerator PJMEDIA_VID_CONF_OP_REMOVE_PORT

The remove port operation.

enumerator PJMEDIA_VID_CONF_OP_CONNECT_PORTS

The connect ports (start transmit) operation.

enumerator PJMEDIA_VID_CONF_OP_DISCONNECT_PORTS

The disconnect ports (stop transmit) operation.

enumerator PJMEDIA_VID_CONF_OP_UPDATE_PORT

The update port operation.

enum pjmedia_vid_conf_layout

Enumeration of video conference layout mode.

Values:

enumerator PJMEDIA_VID_CONF_LAYOUT_DEFAULT

In mixing video from multiple sources, each source will occupy about the same size in the mixing result frame at all time.

enumerator PJMEDIA_VID_CONF_LAYOUT_SELECTIVE_FOCUS

Warning: this is not implemented yet.

In mixing video from multiple sources, one specified participant (or source port) will be the focus (i.e: occupy bigger portion than the others).

enumerator PJMEDIA_VID_CONF_LAYOUT_INTERVAL_FOCUS

Warning: this is not implemented yet.

In mixing video from multiple sources, one participant will be the focus at a time (i.e: occupy bigger portion than the others), and after some interval the focus will be shifted to another participant, so each participant will have the same focus duration.

enumerator PJMEDIA_VID_CONF_LAYOUT_CUSTOM

Warning: this is not implemented yet.

In mixing video from multiple sources, each participant (or source port) will have specific layout configuration.

Functions

void pjmedia_vid_conf_setting_default(pjmedia_vid_conf_setting *opt)

Initialize video conference settings with default values.

Parameters:

opt – The settings to be initialized.

pj_status_t pjmedia_vid_conf_create(pj_pool_t *pool, const pjmedia_vid_conf_setting *opt, pjmedia_vid_conf **p_vid_conf)

Create a video conference bridge.

Parameters:

  • pool – The memory pool.

  • opt – The video conference settings.

  • p_vid_conf – Pointer to receive the video conference bridge.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_vid_conf_destroy(pjmedia_vid_conf *vid_conf)

Destroy video conference bridge. This will also remove any video port, thus application might get notified from the callback set from pjmedia_vid_conf_set_op_cb().

Parameters:

vid_conf – The video conference bridge.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_conf_set_op_cb(pjmedia_vid_conf *vid_conf, pjmedia_vid_conf_op_cb cb)

Register the callback to be called when a video port operation has been completed.

The callback will most likely be called from media threads, thus application must not perform long/blocking processing in this callback.

Parameters:

  • vid_conf – The video conference.

  • cb – Callback to be called. Set this to NULL to unregister the callback.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_conf_add_port(pjmedia_vid_conf *vid_conf, pj_pool_t *pool, pjmedia_port *port, const pj_str_t *name, void *opt, unsigned *p_slot)

Add a media port to the video conference bridge.

This operation executes asynchronously, use the callback set from pjmedia_vid_conf_set_op_cb() to receive notification upon completion.

Parameters:

  • vid_conf – The video conference bridge.

  • pool – The memory pool, the brige will create new pool based on this pool factory for this media port.

  • port – The media port to be added.

  • name – Name to be assigned to the slot. If not set, it will be set to the media port name.

  • opt – The option, for future use, currently this must be NULL.

  • p_slot – Pointer to receive the slot index of the port in the conference bridge.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_vid_conf_remove_port(pjmedia_vid_conf *vid_conf, unsigned slot)

Remove a media port from the video conference bridge.

This operation executes asynchronously, use the callback set from pjmedia_vid_conf_set_op_cb() to receive notification upon completion.

Parameters:

  • vid_conf – The video conference bridge.

  • slot – The media port’s slot index to be removed.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

unsigned pjmedia_vid_conf_get_port_count(pjmedia_vid_conf *vid_conf)

Get number of ports currently registered in the video conference bridge.

Parameters:

vid_conf – The video conference bridge.

Returns:

Number of ports currently registered to the video conference bridge.

pj_status_t pjmedia_vid_conf_enum_ports(pjmedia_vid_conf *vid_conf, unsigned slots[], unsigned *count)

Enumerate occupied slots in the video conference bridge.

Parameters:

  • vid_conf – The video conference bridge.

  • slots – Array of slot to be filled in.

  • count – On input, specifies the maximum number of slot in the array. On return, it will be filled with the actual number of slot.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_conf_get_port_info(pjmedia_vid_conf *vid_conf, unsigned slot, pjmedia_vid_conf_port_info *info)

Get port info.

Parameters:

  • vid_conf – The video conference bridge.

  • slot – Slot index.

  • info – Pointer to receive the info.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_conf_connect_port(pjmedia_vid_conf *vid_conf, unsigned src_slot, unsigned sink_slot, void *opt)

Enable unidirectional video flow from the specified source slot to the specified sink slot.

This operation executes asynchronously, use the callback set from pjmedia_vid_conf_set_op_cb() to receive notification upon completion.

Parameters:

  • vid_conf – The video conference bridge.

  • src_slot – Source slot.

  • sink_slot – Sink slot.

  • opt – The option, for future use, currently this must be NULL.

Returns:

PJ_SUCCES on success.

pj_status_t pjmedia_vid_conf_disconnect_port(pjmedia_vid_conf *vid_conf, unsigned src_slot, unsigned sink_slot)

Disconnect unidirectional video flow from the specified source to the specified sink slot.

This operation executes asynchronously, use the callback set from pjmedia_vid_conf_set_op_cb() to receive notification upon completion.

Parameters:

  • vid_conf – The video conference bridge.

  • src_slot – Source slot.

  • sink_slot – Sink slot.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_conf_update_port(pjmedia_vid_conf *vid_conf, unsigned slot)

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.

This operation executes asynchronously, use the callback set from pjmedia_vid_conf_set_op_cb() to receive notification upon completion.

Parameters:

  • vid_conf – The video conference bridge.

  • slot – The media port’s slot index to be updated.

Returns:

PJ_SUCCESS on success, or the appropriate error code.

pj_status_t pjmedia_vid_conf_add_destroy_handler(pjmedia_vid_conf *vid_conf, unsigned slot, void *member, pj_grp_lock_handler handler)

Add port destructor handler.

Application can use this function to schedule resource release. Note that application cannot release any app’s resources used by the port, e.g: memory pool, database connection, immediately after removing the port from the conference bridge as port removal is asynchronous.

Usually this function is called after adding the port to the conference bridge.

Parameters:

  • vid_conf – The video conference bridge.

  • slot – The port slot index.

  • member – A pointer to be passed to the handler.

  • handler – The destroy handler.

Returns:

PJ_SUCCESS on success.

pj_status_t pjmedia_vid_conf_del_destroy_handler(pjmedia_vid_conf *vid_conf, unsigned slot, void *member, pj_grp_lock_handler handler)

Remove previously registered destructor handler.

Parameters:

  • conf – The video conference bridge.

  • slot – The port slot index.

  • member – A pointer to be passed to the handler.

  • handler – The destroy handler.

Returns:

PJ_SUCCESS on success.

union pjmedia_vid_conf_op_param
#include <vid_conf.h>

Video conference operation parameter.

Public Members

unsigned port

The port id.

struct pjmedia_vid_conf_op_param::[anonymous] add_port

The information for adding port operation.

struct pjmedia_vid_conf_op_param::[anonymous] remove_port

The information for removing port operation.

unsigned src

The source port id. For multiple port operation, this will be set to -1.

unsigned sink

The destination port id. For multiple port operation, this will be set to -1.

struct pjmedia_vid_conf_op_param::[anonymous] connect_ports

The information for connecting port operation.

struct pjmedia_vid_conf_op_param::[anonymous] disconnect_ports

The information for disconnecting port operation.

struct pjmedia_vid_conf_op_param::[anonymous] update_port

The information for updating port operation.

struct pjmedia_vid_conf_op_info
#include <vid_conf.h>

This will contain the information of the conference operation.

Public Members

pjmedia_vid_conf *vid_conf

The conference instance.

pjmedia_vid_conf_op_type op_type

The operation type.

pj_status_t status

The operation return status.

pjmedia_vid_conf_op_param op_param

The operation data.

struct pjmedia_vid_conf_setting
#include <vid_conf.h>

Video conference bridge settings.

Public Members

unsigned max_slot_cnt

Maximum number of slots or media ports can be registered to the bridge.

Default: 32

unsigned frame_rate

Frame rate the bridge will operate at. For video playback smoothness, ideally the bridge frame rate should be the common multiple of the frame rates of the ports. Otherwise, ports whose unaligned frame rates may experience jitter. For example, if the application will work with frame rates of 10, 15, and 30 fps, setting this to 30 should be okay. But if it also needs to handle 20 fps, better setting this to 60.

Default: 60 (frames per second)

unsigned layout

Layout setting, see pjmedia_vid_conf_layout.

Default: PJMEDIA_VID_CONF_LAYOUT_DEFAULT

struct pjmedia_vid_conf_port_info
#include <vid_conf.h>

Video conference bridge port info.

Public Members

unsigned slot

Slot index.

pj_str_t name

Port name.

pjmedia_format format

Format.

unsigned listener_cnt

Number of listeners.

unsigned *listener_slots

Array of listeners.

unsigned transmitter_cnt

Number of transmitter.

unsigned *transmitter_slots

Array of transmitter.