Group PJSUA_LIB_MEDIA
- group PJSUA_LIB_MEDIA
Media manipulation.
PJSUA has rather powerful media features, which are built around the PJMEDIA conference bridge. Basically, all media “ports” (such as calls, WAV players, WAV playlist, file recorders, sound device, tone generators, etc) are terminated in the conference bridge, and application can manipulate the interconnection between these terminations freely.
The conference bridge provides powerful switching and mixing functionality for application. With the conference bridge, each conference slot (e.g. a call) can transmit to multiple destinations, and one destination can receive from multiple sources. If more than one media terminations are terminated in the same slot, the conference bridge will mix the signal automatically.
Application connects one media termination/slot to another by calling pjsua_conf_connect() function. This will establish unidirectional media flow from the source termination to the sink termination. To establish bidirectional media flow, application would need to make another call to pjsua_conf_connect(), this time inverting the source and destination slots in the parameter.
For example, to stream a WAV file to remote call, application may use the following steps:
pj_status_t stream_to_call( pjsua_call_id call_id ) { pjsua_player_id player_id; status = pjsua_player_create("mysong.wav", 0, &player_id); if (status != PJ_SUCCESS) return status; status = pjsua_conf_connect( pjsua_player_get_conf_port(), pjsua_call_get_conf_port() ); }
Other features of PJSUA media:
efficient N to M interconnections between media terminations.
media termination can be connected to itself to create loopback media.
the media termination may have different clock rates, and resampling will be done automatically by conference bridge.
media terminations may also have different frame time; the conference bridge will perform the necessary bufferring to adjust the difference between terminations.
interconnections are removed automatically when media termination is removed from the bridge.
sound device may be changed even when there are active media interconnections.
correctly report call’s media quality (in pjsua_call_dump()) from RTCP packet exchange.
Defines
-
PJSUA_MEDIA_HAS_PJMEDIA
Use PJMEDIA for media? Set this to zero when using third party media stack.
-
PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO
Specify whether the third party stream has the capability of retrieving the stream info, i.e: pjmedia_stream_get_info() and pjmedia_vid_stream_get_info(). Currently this capability is required by smart media update and call dump.
-
PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT
Specify whether the third party stream has the capability of retrieving the stream statistics, i.e: pjmedia_stream_get_stat() and pjmedia_vid_stream_get_stat(). Currently this capability is required by call dump.
-
PJSUA_MAX_CONF_PORTS
Max ports in the conference bridge. This setting is the default value for pjsua_media_config.max_media_ports.
-
PJSUA_DEFAULT_CLOCK_RATE
The default clock rate to be used by the conference bridge. This setting is the default value for pjsua_media_config.clock_rate.
-
PJSUA_DEFAULT_AUDIO_FRAME_PTIME
Default frame length in the conference bridge. This setting is the default value for pjsua_media_config.audio_frame_ptime.
-
PJSUA_DEFAULT_CODEC_QUALITY
Default codec quality settings. This setting is the default value for pjsua_media_config.quality.
-
PJSUA_DEFAULT_ILBC_MODE
Default iLBC mode. This setting is the default value for pjsua_media_config.ilbc_mode.
-
PJSUA_DEFAULT_EC_TAIL_LEN
The default echo canceller tail length. This setting is the default value for pjsua_media_config.ec_tail_len.
-
PJSUA_MAX_PLAYERS
The maximum file player.
-
PJSUA_MAX_RECORDERS
The maximum file player.
-
PJSUA_SDP_SESS_HAS_CONN
Enable/disable “c=” line in SDP session level. Set to zero to disable it.
-
PJSUA_TRANSPORT_RESTART_DELAY_TIME
Specify the delay needed when restarting the transport/listener. e.g: 10 msec on Linux or Android, and 0 on the other platforms.
Typedefs
-
typedef struct pjsua_ext_snd_dev pjsua_ext_snd_dev
Opaque type of extra sound device, an additional sound device beside the primary sound device (the one instantiated via pjsua_set_snd_dev() or pjsua_set_snd_dev2()). This sound device is also registered to conference bridge so it can be used as a normal conference bridge port, e.g: connect it to/from other ports, adjust/check audio level, etc. The conference bridge port ID can be queried using pjsua_ext_snd_dev_get_conf_port().
Application may also use this API to improve media clock. Normally media clock is driven by sound device in master port, but unfortunately some sound devices may produce jittery clock. To improve media clock, application can install Null Sound Device (i.e: using pjsua_set_null_snd_dev()), which will act as a master port, and instantiate the sound device as extra sound device.
Note that extra sound device will not have auto-close upon idle feature. Also note that currently extra sound device only supports mono channel.
Enums
-
enum pjsua_snd_dev_id
Sound device index constants.
Values:
-
enumerator PJSUA_SND_DEFAULT_CAPTURE_DEV
Constant to denote default capture device.
-
enumerator PJSUA_SND_DEFAULT_PLAYBACK_DEV
Constant to denote default playback device.
-
enumerator PJSUA_SND_NO_DEV
Constant to denote that no sound device is being used.
-
enumerator PJSUA_SND_NULL_DEV
Constant to denote null sound device.
-
enumerator PJSUA_SND_DEFAULT_CAPTURE_DEV
Functions
-
void pjsua_media_config_default(pjsua_media_config *cfg)
Use this function to initialize media config.
- Parameters:
cfg – The media config to be initialized.
-
void pjsua_snd_dev_param_default(pjsua_snd_dev_param *prm)
Initialize pjsua_snd_dev_param with default values.
- Parameters:
prm – The parameter.
-
void pjsua_conf_connect_param_default(pjsua_conf_connect_param *prm)
Initialize pjsua_conf_connect_param with default values.
- Parameters:
prm – The parameter.
-
unsigned pjsua_conf_get_max_ports(void)
Get maxinum number of conference ports.
- Returns:
Maximum number of ports in the conference bridge.
-
unsigned pjsua_conf_get_active_ports(void)
Get current number of active ports in the bridge.
- Returns:
The number.
-
pj_status_t pjsua_enum_conf_ports(pjsua_conf_port_id id[], unsigned *count)
Enumerate all 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_conf_get_port_info(pjsua_conf_port_id port_id, pjsua_conf_port_info *info)
Get information about the specified 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_conf_add_port(pj_pool_t *pool, pjmedia_port *port, pjsua_conf_port_id *p_id)
Add arbitrary media port to PJSUA’s 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, file player, or file recorder), PJSUA-LIB will automatically add the port to the bridge.
- Parameters:
pool – Pool to use.
port – Media port to be added to the bridge.
p_id – Optional pointer to receive the conference slot id.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_conf_remove_port(pjsua_conf_port_id port_id)
Remove arbitrary slot from the conference bridge. Application should only call this function if it registered the port manually with previous call to pjsua_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_conf_connect(pjsua_conf_port_id source, pjsua_conf_port_id sink)
Establish unidirectional media flow from souce to sink. One source may transmit to multiple destinations/sink. And if multiple sources are transmitting to the same sink, the media will be mixed together. 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.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_conf_connect2(pjsua_conf_port_id source, pjsua_conf_port_id sink, const pjsua_conf_connect_param *prm)
Establish unidirectional media flow from source to sink. One source may transmit to multiple destinations/sink. And if multiple sources are transmitting to the same sink, the media will be mixed together. Source and sink may refer to the same ID, effectively looping the media.
Signal level from the source to the sink can be adjusted by making it louder or quieter via the parameter param. The level adjustment will apply to a specific connection only (i.e. only for the signal from the source to the sink), as compared to pjsua_conf_adjust_tx_level()/pjsua_conf_adjust_rx_level() which applies to all signals from/to that port. The signal adjustment will be cumulative, in this following order: signal from the source will be adjusted with the level specified in pjsua_conf_adjust_rx_level(), then with the level specified via this API, and finally with the level specified to the sink’s pjsua_conf_adjust_tx_level().
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.
prm – Conference port connection param. If set to NULL, default values will be used.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_conf_disconnect(pjsua_conf_port_id source, pjsua_conf_port_id sink)
Disconnect media 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_conf_adjust_tx_level(pjsua_conf_port_id slot, float level)
Adjust the signal level to be transmitted from the bridge to the specified port by making it louder or quieter.
- Parameters:
slot – The conference bridge slot number.
level – Signal level adjustment. Value 1.0 means no level adjustment, while value 0 means to mute the port.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_conf_adjust_rx_level(pjsua_conf_port_id slot, float level)
Adjust the signal level to be received from the specified port (to the bridge) by making it louder or quieter.
- Parameters:
slot – The conference bridge slot number.
level – Signal level adjustment. Value 1.0 means no level adjustment, while value 0 means to mute the port.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_conf_get_signal_level(pjsua_conf_port_id slot, unsigned *tx_level, unsigned *rx_level)
Get last signal level transmitted to or received from the specified port. The signal level is an integer value in zero to 255, with zero indicates no signal, and 255 indicates the loudest signal level.
- Parameters:
slot – The conference bridge slot number.
tx_level – Optional argument to receive the level of signal transmitted to the specified port (i.e. the direction is from the bridge to the port).
rx_level – Optional argument to receive the level of signal received from the port (i.e. the direction is from the port to the bridge).
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjsua_player_create(const pj_str_t *filename, unsigned options, pjsua_player_id *p_id)
Create a file player, and automatically add this player to the conference bridge.
- Parameters:
filename – The filename to be played. Currently only WAV files are supported, and the WAV file MUST be formatted as 16bit PCM mono/single channel (any clock rate is supported). Filename’s length must be smaller than PJ_MAXPATH.
options – Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent playback loop.
p_id – Pointer to receive player ID.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_playlist_create(const pj_str_t file_names[], unsigned file_count, const pj_str_t *label, unsigned options, pjsua_player_id *p_id)
Create a file playlist media port, and automatically add the port to the conference bridge.
- Parameters:
file_names – Array of file names to be added to the play list. Note that the files must have the same clock rate, number of channels, and number of bits per sample. Each filename’s length must be smaller than PJ_MAXPATH.
file_count – Number of files in the array.
label – Optional label to be set for the media port.
options – Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent looping.
p_id – Optional pointer to receive player ID.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pjsua_conf_port_id pjsua_player_get_conf_port(pjsua_player_id id)
Get conference port ID associated with player or playlist.
- Parameters:
id – The file player ID.
- Returns:
Conference port ID associated with this player.
-
pj_status_t pjsua_player_get_port(pjsua_player_id id, pjmedia_port **p_port)
Get the media port for the player or playlist.
- Parameters:
id – The player ID.
p_port – The media port associated with the player.
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjsua_player_get_info(pjsua_player_id id, pjmedia_wav_player_info *info)
Get additional info about the file player. This operation is not valid for playlist.
- Parameters:
id – The file player ID.
info – The info.
- Returns:
PJ_SUCCESS on success or the appropriate error code.
-
pj_ssize_t pjsua_player_get_pos(pjsua_player_id id)
Get playback position. This operation is not valid for playlist.
- Parameters:
id – The file player ID.
- Returns:
The current playback position, in samples. On error, return the error code as negative value.
-
pj_status_t pjsua_player_set_pos(pjsua_player_id id, pj_uint32_t samples)
Set playback position. This operation is not valid for playlist.
- Parameters:
id – The file player ID.
samples – The playback position, in samples. Application can specify zero to re-start the playback.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_player_destroy(pjsua_player_id id)
Close the file of playlist, remove the player from the bridge, and free resources associated with the file player or playlist.
- Parameters:
id – The file player ID.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_recorder_create(const pj_str_t *filename, unsigned enc_type, void *enc_param, pj_ssize_t max_size, unsigned options, pjsua_recorder_id *p_id)
Create a file recorder, and automatically connect this recorder to the conference bridge. The recorder currently supports recording WAV file. The type of the recorder to use is determined by the extension of the file (e.g. “.wav”).
- Parameters:
filename – Output file name. The function will determine the default format to be used based on the file extension. Currently “.wav” is supported on all platforms. Filename’s length must be smaller than PJ_MAXPATH.
enc_type – Optionally specify the type of encoder to be used to compress the media, if the file can support different encodings. This value must be zero for now.
enc_param – Optionally specify codec specific parameter to be passed to the file writer. For .WAV recorder, this value must be NULL.
max_size – Maximum file size. Specify zero or -1 to remove size limitation. This value must be zero or -1 for now.
options – Optional options.
p_id – Pointer to receive the recorder instance.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pjsua_conf_port_id pjsua_recorder_get_conf_port(pjsua_recorder_id id)
Get conference port associated with recorder.
- Parameters:
id – The recorder ID.
- Returns:
Conference port ID associated with this recorder.
-
pj_status_t pjsua_recorder_get_port(pjsua_recorder_id id, pjmedia_port **p_port)
Get the media port for the recorder.
- Parameters:
id – The recorder ID.
p_port – The media port associated with the recorder.
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjsua_recorder_destroy(pjsua_recorder_id id)
Destroy recorder (this will complete recording).
- Parameters:
id – The recorder ID.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_enum_aud_devs(pjmedia_aud_dev_info info[], unsigned *count)
Enum all audio 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.
-
pj_status_t pjsua_enum_snd_devs(pjmedia_snd_dev_info info[], unsigned *count)
Enum all sound devices installed in the system (old API).
- 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.
-
pj_status_t pjsua_get_snd_dev(int *capture_dev, int *playback_dev)
Get currently active sound devices. If sound devices has not been created (for example when pjsua_start() is not called), it is possible that the function returns PJ_SUCCESS with -1 as device IDs. See also pjsua_snd_dev_id constants.
- Parameters:
capture_dev – On return it will be filled with device ID of the capture device.
playback_dev – On return it will be filled with device ID of the device ID of the playback device.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_set_snd_dev(int capture_dev, int playback_dev)
Select or change sound device. Application may call this function at any time to replace current sound device.
Note that this function will always try to open the sound device immediately. If immediate open is not preferred, use pjsua_set_snd_dev2() with PJSUA_SND_DEV_NO_IMMEDIATE_OPEN flag.
- Parameters:
capture_dev – Device ID of the capture device.
playback_dev – Device ID of the playback device.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_get_snd_dev2(pjsua_snd_dev_param *snd_param)
Get sound device parameters such as playback & capture device IDs and mode.
- Parameters:
snd_param – On return, it is set with sound device param.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_set_snd_dev2(const pjsua_snd_dev_param *snd_param)
Select or change sound device according to the specified param.
- Parameters:
snd_param – Sound device param.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_set_null_snd_dev(void)
Set pjsua to use null sound device. The null sound device only provides the timing needed by the conference bridge, and will not interract with any hardware.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pjmedia_port *pjsua_set_no_snd_dev(void)
Disconnect the main conference bridge from any sound devices, and let application connect the bridge to it’s own sound device/master port.
- Returns:
The port interface of the conference bridge, so that application can connect this to it’s own sound device or master port.
-
pj_status_t pjsua_set_ec(unsigned tail_ms, unsigned options)
Change the echo cancellation settings.
The behavior of this function depends on whether the sound device is currently active, and if it is, whether device or software AEC is being used.
If the sound device is currently active, and if the device supports AEC, this function will forward the change request to the device and it will be up to the device on whether support the request. If software AEC is being used (the software EC will be used if the device does not support AEC), this function will change the software EC settings. In all cases, the setting will be saved for future opening of the sound device.
If the sound device is not currently active, this will only change the default AEC settings and the setting will be applied next time the sound device is opened.
- Parameters:
tail_ms – The tail length, in miliseconds. Set to zero to disable AEC.
options – Options to be passed to pjmedia_echo_create(). Normally the value should be zero.
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjsua_get_ec_tail(unsigned *p_tail_ms)
Get current echo canceller tail length.
- Parameters:
p_tail_ms – Pointer to receive the tail length, in miliseconds. If AEC is disabled, the value will be zero.
- Returns:
PJ_SUCCESS on success.
-
pj_status_t pjsua_get_ec_stat(pjmedia_echo_stat *p_stat)
Get echo canceller statistics.
- Parameters:
p_stat – Pointer to receive the stat.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_bool_t pjsua_snd_is_active(void)
Check whether the sound device is currently active. The sound device may be inactive if the application has set the auto close feature to non-zero (the snd_auto_close_time setting in pjsua_media_config), or if null sound device or no sound device has been configured via the pjsua_set_no_snd_dev() function.
-
pj_status_t pjsua_snd_set_setting(pjmedia_aud_dev_cap cap, const void *pval, pj_bool_t keep)
Configure sound device setting to the sound device being used. If sound device is currently active, the function will forward the setting to the sound device instance to be applied immediately, if it supports it.
The setting will be saved for future opening of the sound device, if the “keep” argument is set to non-zero. If the sound device is currently inactive, and the “keep” argument is false, this function will return error.
Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used. To reset the setting, application can call pjsua_set_snd_dev2() with use_default_settings set to PJ_TRUE.
Note also that the echo cancellation setting should be set with pjsua_set_ec() API instead.
See also pjmedia_aud_stream_set_cap() for more information about setting an audio device capability.
- Parameters:
cap – The sound device setting to change.
pval – Pointer to value. Please see pjmedia_aud_dev_cap documentation about the type of value to be supplied for each setting.
keep – Specify whether the setting is to be kept for future use.
- Returns:
PJ_SUCCESS on success or the appropriate error code.
-
pj_status_t pjsua_snd_get_setting(pjmedia_aud_dev_cap cap, void *pval)
Retrieve a sound device setting. If sound device is currently active, the function will forward the request to the sound device. If sound 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.
Note that echo cancellation settings should be retrieved with pjsua_get_ec_tail() API instead.
- Parameters:
cap – The sound device setting to retrieve.
pval – Pointer to receive the value. Please see pjmedia_aud_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_ext_snd_dev_create(pjmedia_snd_port_param *param, pjsua_ext_snd_dev **p_snd)
Create an extra sound device and register it to conference bridge.
- Parameters:
param – Sound device port param. Currently this only supports mono channel, so channel count must be set to 1.
p_snd – The extra sound device instance.
- Returns:
PJ_SUCCESS on success or the appropriate error code.
-
pj_status_t pjsua_ext_snd_dev_destroy(pjsua_ext_snd_dev *snd)
Destroy an extra sound device and unregister it from conference bridge.
- Parameters:
snd – The extra sound device instance.
- Returns:
PJ_SUCCESS on success or the appropriate error code.
-
pjmedia_snd_port *pjsua_ext_snd_dev_get_snd_port(pjsua_ext_snd_dev *snd)
Get sound port instance of an extra sound device.
- Parameters:
snd – The extra sound device instance.
- Returns:
The sound port instance.
-
pjsua_conf_port_id pjsua_ext_snd_dev_get_conf_port(pjsua_ext_snd_dev *snd)
Get conference port ID of an extra sound device.
- Parameters:
snd – The extra sound device instance.
- Returns:
The conference port ID.
-
pj_status_t pjsua_enum_codecs(pjsua_codec_info id[], unsigned *count)
Enum all supported 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_codec_set_priority(const pj_str_t *codec_id, pj_uint8_t priority)
Change codec priority.
- Parameters:
codec_id – Codec ID, which is a string that uniquely identify the codec (such as “speex/8000”). 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_codec_get_param(const pj_str_t *codec_id, pjmedia_codec_param *param)
Get codec parameters.
- Parameters:
codec_id – Codec ID.
param – Structure to receive codec parameters.
- Returns:
PJ_SUCCESS on success, or the appropriate error code.
-
pj_status_t pjsua_codec_set_param(const pj_str_t *codec_id, const pjmedia_codec_param *param)
Set 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.
-
struct pjsua_media_config
- #include <pjsua.h>
This structure describes media configuration, which will be specified when calling pjsua_init(). Application MUST initialize this structure by calling pjsua_media_config_default().
Forward declaration
Public Members
-
unsigned clock_rate
Clock rate to be applied to the conference bridge. If value is zero, default clock rate will be used (PJSUA_DEFAULT_CLOCK_RATE, which by default is 16KHz).
-
unsigned snd_clock_rate
Clock rate to be applied when opening the sound device. If value is zero, conference bridge clock rate will be used.
-
unsigned channel_count
Channel count be applied when opening the sound device and conference bridge.
-
unsigned audio_frame_ptime
Specify audio frame ptime. The value here will affect the samples per frame of both the sound device and the conference bridge. Specifying lower ptime will normally reduce the latency.
Default value: PJSUA_DEFAULT_AUDIO_FRAME_PTIME
-
unsigned max_media_ports
Specify maximum number of media ports to be created in the conference bridge. Since all media terminate in the bridge (calls, file player, file recorder, etc), the value must be large enough to support all of them. However, the larger the value, the more computations are performed.
Default value: PJSUA_MAX_CONF_PORTS
-
pj_bool_t has_ioqueue
Specify whether the media manager should manage its own ioqueue for the RTP/RTCP sockets. If yes, ioqueue will be created and at least one worker thread will be created too. If no, the RTP/RTCP sockets will share the same ioqueue as SIP sockets, and no worker thread is needed.
Normally application would say yes here, unless it wants to run everything from a single thread.
-
unsigned thread_cnt
Specify the number of worker threads to handle incoming RTP packets. A value of one is recommended for most applications.
-
unsigned quality
Media quality, 0-10, according to this table: 5-10: resampling use large filter, 3-4: resampling use small filter, 1-2: resampling use linear. The media quality also sets speex codec quality/complexity to the number.
Default: PJSUA_DEFAULT_CODEC_QUALITY.
-
unsigned ptime
Specify default codec ptime.
Default: 0 (codec specific)
-
unsigned ilbc_mode
iLBC mode (20 or 30).
Default: 30 (PJSUA_DEFAULT_ILBC_MODE)
-
unsigned tx_drop_pct
Percentage of RTP packet to drop in TX direction (to simulate packet lost).
Default: 0
-
unsigned rx_drop_pct
Percentage of RTP packet to drop in RX direction (to simulate packet lost).
Default: 0
-
unsigned ec_options
Echo canceller options (see pjmedia_echo_create()). Specify PJMEDIA_ECHO_USE_SW_ECHO here if application wishes to use software echo canceller instead of device EC.
Default: 0.
-
unsigned ec_tail_len
Echo canceller tail length, in miliseconds.
Default: PJSUA_DEFAULT_EC_TAIL_LEN
-
unsigned snd_rec_latency
Audio capture buffer length, in milliseconds.
Default: PJMEDIA_SND_DEFAULT_REC_LATENCY
-
unsigned snd_play_latency
Audio playback buffer length, in milliseconds.
Default: PJMEDIA_SND_DEFAULT_PLAY_LATENCY
-
int jb_init
Jitter buffer initial prefetch delay in msec. The value must be between jb_min_pre and jb_max_pre below. If the value is 0, prefetching will be disabled.
Default: -1 (to use default stream settings, currently 0)
-
int jb_min_pre
Jitter buffer minimum prefetch delay in msec.
Default: -1 (to use default stream settings, currently codec ptime)
-
int jb_max_pre
Jitter buffer maximum prefetch delay in msec.
Default: -1 (to use default stream settings, currently 80% of jb_max)
-
int jb_max
Set maximum delay that can be accomodated by the jitter buffer msec.
Default: -1 (to use default stream settings, currently 500 msec)
-
pjmedia_jb_discard_algo jb_discard_algo
Set the algorithm the jitter buffer uses to discard frames in order to adjust the latency.
Default: PJMEDIA_JB_DISCARD_PROGRESSIVE
-
int ice_max_host_cands
Set the maximum number of host candidates.
Default: -1 (maximum not set)
-
pj_ice_sess_options ice_opt
ICE session options.
-
pj_bool_t ice_always_update
Send re-INVITE/UPDATE every after ICE connectivity check regardless the default ICE transport address is changed or not. When this is set to PJ_FALSE, re-INVITE/UPDATE will be sent only when the default ICE transport address is changed.
Default: yes
-
pj_str_t turn_server
Specify TURN domain name or host name, in in “DOMAIN:PORT” or “HOST:PORT” format.
-
pj_turn_tp_type turn_conn_type
Specify the connection type to be used to the TURN server. Valid values are PJ_TURN_TP_UDP, PJ_TURN_TP_TCP or PJ_TURN_TP_TLS.
Default: PJ_TURN_TP_UDP
-
pj_stun_auth_cred turn_auth_cred
Specify the credential to authenticate with the TURN server.
-
pj_turn_sock_tls_cfg turn_tls_setting
This specifies TLS settings for TLS transport. It’s only applicable when TLS is used to connect to the TURN server.
-
int snd_auto_close_time
Specify idle time of sound device before it is automatically closed, in seconds. Use value -1 to disable the auto-close feature of sound device
Default : 1
-
pj_bool_t vid_preview_enable_native
Specify whether built-in/native preview should be used if available. In some systems, video input devices have built-in capability to show preview window of the device. Using this built-in preview is preferable as it consumes less CPU power. If built-in preview is not available, the library will perform software rendering of the input. If this field is set to PJ_FALSE, software preview will always be used.
Default: PJ_TRUE
-
pj_bool_t no_smart_media_update
Disable smart media update (ticket #1568). The smart media update will check for any changes in the media properties after a successful SDP negotiation and the media will only be reinitialized when any change is found. When it is disabled, media streams will always be reinitialized after a successful SDP negotiation.
Note for third party media, the smart media update requires stream info retrieval capability, see PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO.
Default: PJ_FALSE
-
pj_bool_t no_rtcp_sdes_bye
Omit RTCP SDES and BYE in outgoing RTCP packet, this setting will be applied for both audio and video streams. Note that, when RTCP SDES and BYE are set to be omitted, RTCP SDES will still be sent once when the stream starts/stops and RTCP BYE will be sent once when the stream stops.
Default: PJ_FALSE
-
void (*on_aud_prev_play_frame)(pjmedia_frame *frame)
Optional callback for audio frame preview right before queued to the speaker. Notes:
application MUST NOT block or perform long operation in the callback as the callback may be executed in sound device thread
when using software echo cancellation, application MUST NOT modify the audio data from within the callback, otherwise the echo canceller will not work properly.
-
void (*on_aud_prev_rec_frame)(pjmedia_frame *frame)
Optional callback for audio frame preview recorded from the microphone before being processed by any media component such as software echo canceller. Notes:
application MUST NOT block or perform long operation in the callback as the callback may be executed in sound device thread
when using software echo cancellation, application MUST NOT modify the audio data from within the callback, otherwise the echo canceller will not work properly.
-
unsigned clock_rate
-
struct pjsua_codec_info
- #include <pjsua.h>
This structure describes codec information, which can be retrieved by calling pjsua_enum_codecs().
-
struct pjsua_conf_port_info
- #include <pjsua.h>
This structure describes information about a particular media port that has been registered into the conference bridge. Application can query this info by calling pjsua_conf_get_port_info().
Public Members
-
pjsua_conf_port_id slot_id
Conference port number.
-
pjmedia_format format
Format.
-
unsigned clock_rate
Clock rate.
-
unsigned channel_count
Number of channels.
-
unsigned samples_per_frame
Samples per frame
-
unsigned bits_per_sample
Bits per sample
-
float tx_level_adj
Tx level adjustment.
-
float rx_level_adj
Rx level adjustment.
-
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).
-
pjsua_conf_port_id slot_id
-
struct pjsua_media_transport
- #include <pjsua.h>
This structure holds information about custom media transport to be registered to pjsua.
Public Members
-
pjmedia_sock_info skinfo
Media socket information containing the address information of the RTP and RTCP socket.
-
pjmedia_transport *transport
The media transport instance.
-
pjmedia_sock_info skinfo
-
struct pjsua_snd_dev_param
- #include <pjsua.h>
This structure specifies the parameters to set the sound device. Use pjsua_snd_dev_param_default() to initialize this structure with default values.
Public Members
-
int capture_dev
Capture dev id.
Default: PJMEDIA_AUD_DEFAULT_CAPTURE_DEV
-
int playback_dev
Playback dev id.
Default: PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV
-
unsigned mode
Sound device mode, refer to pjsua_snd_dev_mode.
Default: 0
-
pj_bool_t use_default_settings
The library will maintain the global sound device settings set when opening the sound device for the first time and later can be modified using pjsua_snd_set_setting(). These setings are then applied to any sound device when opening. This might be undesirable, e.g: output volume changes when switching sound device due to the use of previously set volume settings.
To avoid such case, application can set this to PJ_TRUE and let the sound device use default settings when opening. This will also reset the global sound device settings.
Default: PJ_FALSE
-
int capture_dev
-
struct pjsua_conf_connect_param
- #include <pjsua.h>
This structure specifies the parameters for conference ports connection. Use pjsua_conf_connect_param_default() to initialize this structure with default values.
Public Members
-
float level
Signal level adjustment from the source to the sink to make it louder or quieter. Value 1.0 means no level adjustment, while value 0 means to mute the port.
Default: 1.0
-
float level