BLOG | DOCUMENTATION | TRAC

Home --> Documentations --> PJSIP Reference

Media manipulation. More...

Data Structures

struct  pjsua_media_config
 
struct  pjsua_codec_info
 
struct  pjsua_conf_port_info
 
struct  pjsua_media_transport
 

Macros

#define PJSUA_MEDIA_HAS_PJMEDIA   1
 
#define PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO   0
 
#define PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT   0
 
#define PJSUA_MAX_CONF_PORTS   254
 
#define PJSUA_DEFAULT_CLOCK_RATE   16000
 
#define PJSUA_DEFAULT_AUDIO_FRAME_PTIME   20
 
#define PJSUA_DEFAULT_CODEC_QUALITY   8
 
#define PJSUA_DEFAULT_ILBC_MODE   30
 
#define PJSUA_DEFAULT_EC_TAIL_LEN   200
 
#define PJSUA_MAX_PLAYERS   32
 
#define PJSUA_MAX_RECORDERS   32
 
#define PJSUA_SDP_SESS_HAS_CONN   0
 

Functions

void pjsua_media_config_default (pjsua_media_config *cfg)
 
unsigned pjsua_conf_get_max_ports (void)
 
unsigned pjsua_conf_get_active_ports (void)
 
pj_status_t pjsua_enum_conf_ports (pjsua_conf_port_id id[], unsigned *count)
 
pj_status_t pjsua_conf_get_port_info (pjsua_conf_port_id port_id, pjsua_conf_port_info *info)
 
pj_status_t pjsua_conf_add_port (pj_pool_t *pool, pjmedia_port *port, pjsua_conf_port_id *p_id)
 
pj_status_t pjsua_conf_remove_port (pjsua_conf_port_id port_id)
 
pj_status_t pjsua_conf_connect (pjsua_conf_port_id source, pjsua_conf_port_id sink)
 
pj_status_t pjsua_conf_disconnect (pjsua_conf_port_id source, pjsua_conf_port_id sink)
 
pj_status_t pjsua_conf_adjust_tx_level (pjsua_conf_port_id slot, float level)
 
pj_status_t pjsua_conf_adjust_rx_level (pjsua_conf_port_id slot, float level)
 
pj_status_t pjsua_conf_get_signal_level (pjsua_conf_port_id slot, unsigned *tx_level, unsigned *rx_level)
 
pj_status_t pjsua_player_create (const pj_str_t *filename, unsigned options, pjsua_player_id *p_id)
 
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)
 
pjsua_conf_port_id pjsua_player_get_conf_port (pjsua_player_id id)
 
pj_status_t pjsua_player_get_port (pjsua_player_id id, pjmedia_port **p_port)
 
pj_status_t pjsua_player_get_info (pjsua_player_id id, pjmedia_wav_player_info *info)
 
pj_ssize_t pjsua_player_get_pos (pjsua_player_id id)
 
pj_status_t pjsua_player_set_pos (pjsua_player_id id, pj_uint32_t samples)
 
pj_status_t pjsua_player_destroy (pjsua_player_id id)
 
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)
 
pjsua_conf_port_id pjsua_recorder_get_conf_port (pjsua_recorder_id id)
 
pj_status_t pjsua_recorder_get_port (pjsua_recorder_id id, pjmedia_port **p_port)
 
pj_status_t pjsua_recorder_destroy (pjsua_recorder_id id)
 
pj_status_t pjsua_enum_aud_devs (pjmedia_aud_dev_info info[], unsigned *count)
 
pj_status_t pjsua_enum_snd_devs (pjmedia_snd_dev_info info[], unsigned *count)
 
pj_status_t pjsua_get_snd_dev (int *capture_dev, int *playback_dev)
 
pj_status_t pjsua_set_snd_dev (int capture_dev, int playback_dev)
 
pj_status_t pjsua_set_null_snd_dev (void)
 
pjmedia_portpjsua_set_no_snd_dev (void)
 
pj_status_t pjsua_set_ec (unsigned tail_ms, unsigned options)
 
pj_status_t pjsua_get_ec_tail (unsigned *p_tail_ms)
 
pj_bool_t pjsua_snd_is_active (void)
 
pj_status_t pjsua_snd_set_setting (pjmedia_aud_dev_cap cap, const void *pval, pj_bool_t keep)
 
pj_status_t pjsua_snd_get_setting (pjmedia_aud_dev_cap cap, void *pval)
 
pj_status_t pjsua_enum_codecs (pjsua_codec_info id[], unsigned *count)
 
pj_status_t pjsua_codec_set_priority (const pj_str_t *codec_id, pj_uint8_t priority)
 
pj_status_t pjsua_codec_get_param (const pj_str_t *codec_id, pjmedia_codec_param *param)
 
pj_status_t pjsua_codec_set_param (const pj_str_t *codec_id, const pjmedia_codec_param *param)
 

Detailed Description

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 wound 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;
}

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.

Macro Definition Documentation

#define PJSUA_MEDIA_HAS_PJMEDIA   1

Use PJMEDIA for media? Set this to zero when using third party media stack.

#define PJSUA_THIRD_PARTY_STREAM_HAS_GET_INFO   0

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.

#define PJSUA_THIRD_PARTY_STREAM_HAS_GET_STAT   0

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.

#define PJSUA_MAX_CONF_PORTS   254

Max ports in the conference bridge. This setting is the default value for pjsua_media_config.max_media_ports.

#define PJSUA_DEFAULT_CLOCK_RATE   16000

The default clock rate to be used by the conference bridge. This setting is the default value for pjsua_media_config.clock_rate.

#define PJSUA_DEFAULT_AUDIO_FRAME_PTIME   20

Default frame length in the conference bridge. This setting is the default value for pjsua_media_config.audio_frame_ptime.

#define PJSUA_DEFAULT_CODEC_QUALITY   8

Default codec quality settings. This setting is the default value for pjsua_media_config.quality.

#define PJSUA_DEFAULT_ILBC_MODE   30

Default iLBC mode. This setting is the default value for pjsua_media_config.ilbc_mode.

#define PJSUA_DEFAULT_EC_TAIL_LEN   200

The default echo canceller tail length. This setting is the default value for pjsua_media_config.ec_tail_len.

#define PJSUA_MAX_PLAYERS   32

The maximum file player.

#define PJSUA_MAX_RECORDERS   32

The maximum file player.

#define PJSUA_SDP_SESS_HAS_CONN   0

Enable/disable "c=" line in SDP session level. Set to zero to disable it.

Function Documentation

void pjsua_media_config_default ( pjsua_media_config cfg)

Use this function to initialize media config.

Parameters
cfgThe media config to be initialized.
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
idArray of conference port ID to be initialized.
countOn 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_idPort identification.
infoPointer 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
poolPool to use.
portMedia port to be added to the bridge.
p_idOptional 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_idThe 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
sourcePort ID of the source media/transmitter.
sinkPort ID of the destination media/received.
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
sourcePort ID of the source media/transmitter.
sinkPort 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
slotThe conference bridge slot number.
levelSignal 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
slotThe conference bridge slot number.
levelSignal 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
slotThe conference bridge slot number.
tx_levelOptional argument to receive the level of signal transmitted to the specified port (i.e. the direction is from the bridge to the port).
rx_levelOptional 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
filenameThe 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).
optionsOptional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent playback loop.
p_idPointer 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_namesArray 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.
file_countNumber of files in the array.
labelOptional label to be set for the media port.
optionsOptional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent looping.
p_idOptional 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
idThe 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
idThe player ID.
p_portThe 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
portThe file player ID.
infoThe 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
idThe 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
idThe file player ID.
samplesThe 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
idThe 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
filenameOutput file name. The function will determine the default format to be used based on the file extension. Currently ".wav" is supported on all platforms.
enc_typeOptionally 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_paramOptionally specify codec specific parameter to be passed to the file writer. For .WAV recorder, this value must be NULL.
max_sizeMaximum file size. Specify zero or -1 to remove size limitation. This value must be zero or -1 for now.
optionsOptional options.
p_idPointer 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
idThe 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
idThe recorder ID.
p_portThe 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
idThe 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
infoArray of info to be initialized.
countOn 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
infoArray of info to be initialized.
countOn 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.

Parameters
capture_devOn return it will be filled with device ID of the capture device.
playback_devOn 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.

Parameters
capture_devDevice ID of the capture device.
playback_devDevice ID of the playback device.
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_msThe tail length, in miliseconds. Set to zero to disable AEC.
optionsOptions 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_msPointer to receive the tail length, in miliseconds. If AEC is disabled, the value will be zero.
Returns
PJ_SUCCESS on success.
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.

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
capThe sound device setting to change.
pvalPointer to value. Please see pjmedia_aud_dev_cap documentation about the type of value to be supplied for each setting.
keepSpecify 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
capThe sound device setting to retrieve.
pvalPointer 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_enum_codecs ( pjsua_codec_info  id[],
unsigned *  count 
)

Enum all supported codecs in the system.

Parameters
idArray of ID to be initialized.
countOn 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_idCodec ID, which is a string that uniquely identify the codec (such as "speex/8000"). Please see pjsua manual or pjmedia codec reference for details.
priorityCodec 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_idCodec ID.
paramStructure 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_idCodec ID.
paramCodec parameter to set. Set to NULL to reset codec parameter to library default settings.
Returns
PJ_SUCCESS on success, or the appropriate error code.

 


PJSIP Open Source, high performance, small footprint, and very very portable SIP stack
Copyright (C) 2006-2008 Teluu Inc.