GIPS VoiceEngine – API Specification
GIPS VoiceEngine – API Specification
Feb, 2005
TABLE OF CONTENTS
Table Of Contents ........................................................................................................................... 2
1
Overview ................................................................................................................................. 4
2
Product Version ....................................................................................................................... 4
3
Interface Description ............................................................................................................... 4
3.1
Structures/Classes ............................................................................................................ 4
3.2
Initialization..................................................................................................................... 5
3.3
General Settings............................................................................................................... 6
3.4
Channel functions ............................................................................................................ 6
3.5
Codec setting functions ................................................................................................... 7
3.5.1
Standard Settings ..................................................................................................... 7
3.5.2
Optional Settings ..................................................................................................... 7
3.6
Port and IP address setting functions............................................................................... 8
3.6.1
Standard Settings ..................................................................................................... 8
3.6.2
Optional Settings ..................................................................................................... 9
3.7
Start and stop functions ................................................................................................. 10
3.8
Various other functions ................................................................................................. 11
3.8.1
Error handling........................................................................................................ 11
3.8.2
Run time Error handling and monitoring .............................................................. 11
3.8.3
Version handling ................................................................................................... 12
3.8.4
Mic/Speaker setting functions ............................................................................... 12
3.8.5
Automatic Gain Control ........................................................................................ 13
3.8.6
Noise Suppression ................................................................................................. 13
3.8.7
Video synchronization ........................................................................................... 14
3.8.8
DTMF .................................................................................................................... 14
3.8.9
Playback of file ...................................................................................................... 15
3.8.10
Recording of files .................................................................................................. 17
3.8.11
File Conversion calls ............................................................................................. 18
3.8.12
RTP and RTCP Functions ..................................................................................... 18
3.8.13
Push-to-talk functions ............................................................................................ 19
3.8.14
Speech level indicator............................................................................................ 20
3.8.15
External Media Processing .................................................................................... 20
3.8.16
Forward Error Correction ...................................................................................... 21
3.8.17
Trace settings ......................................................................................................... 21
GIPS VoiceEngine – API Specification
Feb, 2005
3.8.18
External Recording Source .................................................................................... 21
3.8.19
External Playout Source ........................................................................................ 22
3.8.20
Non real-time RTP to file conversion.................................................................... 22
3.8.21
Handling of optional products ............................................................................... 23
3.9
Secure RTP .................................................................................................................... 24
3.10
Telchemy VQMon support ............................................................................................ 25
3.11
Encryption ..................................................................................................................... 26
3.12
External Transport Protocol .......................................................................................... 27
3.13
Sending raw data ........................................................................................................... 28
3.14
Termination functions ................................................................................................... 28
3.15
Example code ................................................................................................................ 28
3.16
Change of codec settings ............................................................................................... 29
3.16.1
3.17
Change of sending settings .................................................................................... 30
Error handling................................................................................................................ 31
3.17.1
Recommended handling of the error codes ........................................................... 31
Appendix A ................................................................................................................................... 33
Appendix B.................................................................................................................................... 36
GIPS VoiceEngine – API Specification
Feb, 2005
1 OVERVIEW
This document describes the interface of the GIPS VoiceEngine, which is delivered as a C++
library or as a dll.
The VoiceEngine has the following main functionalities:
1. Soundcard handling
2. Speech processing
3. RTP protocol
The GIPS VoiceEngine API enables a correct call-setup by allowing the user to check what
capabilities that are available and to set call-setup information. It is however important to notice
that the GIPS VoiceEngine does NOT handle call setup. Also, the user can set numerous other
options such as mute, volume control, and acoustic echo cancelling.
2 PRODUCT VERSION
This GIPS VoiceEngine API description corresponds to the GIPS VoiceEngine product version
2.0.
3 INTERFACE DESCRIPTION
This chapter will describe the VoiceEngine API thoroughly. Section 3.1 to 3.9 covers the
available function calls to the GIPS VoiceEngine. Sections named “Optional Settings” contain
function calls that do not have to be used in a standard call but might useful in advanced call
scenarios. Section 3.15 describes an example SIP call setup scenario and what calls that needs to
be made to the GIPS VE. The order of the function calls in the example is recommended.
Moreover section 3.16 describes the change of codec settings more in depth and what settings that
are allowed and section 3.17 describes the recommended error handling. For customers that want
to use another transport protocol than the default one, RTP/UDP/IP, section 3.12 is very
important. All other users can ignore that section.
Calls marked with Optional Feature marks that this call relies on an GIPS product that
might not be included in your VoiceEngine configuration.
3.1
Structures/Classes
struct GIPSVE_CodecInst {
int pltype;
char plname[16];
int plfreq;
int pacsize;
int channels;
int rate;};
GIPS VoiceEngine – API Specification
Feb, 2005
The GIPS VoiceEngine holds information about each codec it supports in this format. The pltype
is the payload type, plname the MIME name, plfreq the sampling-frequency of the codec, pacsize
the number of samples to be sent in each packet and channels is the number of audio channels
(1=mono, 2=stereo and so forth), rate is the codec bit rate in bits per second. That is a codec
which is defined as follows in the SDP header a=rtpmap:97 iPCMWB/16000/1 has pltype=97,
plname=iPCMWB, plfreq=16000 and channels=1. The channels parameter may be omitted in the
SDP message if the number of channels is one provided no additional parameters are needed1.
The codec structure also holds a default packet size value, in samples, even though most of the
supported codecs can handle other sizes as well. A different packet size than the default one can
be set in the structure before being passed to GIPSVE_SetSendCodec(). The same applies to the
payload type. If another dynamic payload type is going to be used than the default one this can
also be set in the structure before it is being passed to GIPSVE_SetSendCodec().The topic of
using other settings than the default ones is explained further in section 3.11.
InStream
class InStream {
virtual int Read(void *buf, int len) = 0;
};
This is a parent class for reading data from somewhere (i.e. a file). It is up to the VoiceEngine
user to implement a child class with the read function present. The Read function should read len
bytes and put these in buf. If less than len bytes remain when the function is called, all the
remaining bytes should be put into buf. The return value specifies the number of bytes that were
put into buf and –1 is used to indicate an error.
class OutStream {
virtual bool Write(void *buf, int len) = 0;
};
This is a parent class for writing data to somewhere (i.e. a file). It is up to the VoiceEngine user to
implement a child class with the read function present. The Write function should write len bytes
from buf to the desired location. The return value should be true if call was successful and false if
it failed.
3.2
Initialization
int GIPSVE_Authenticate(char *auth_string, int len);
If VoiceEngine is delivered as a dll, the dll needs to be unlocked before any call to VoiceEngine
can be made. The purpose of this to avoid any unauthorized usage of the VoiceEngine dll. A
password string as delivered together with the dll and this string is used to unlock the dll.
auth_string should contain a pointer to the string, and len is the string length (number of
chars).
The password string should be embedded in the calling exe-file, and not stored in any resourcefile or registry key. This call only applies to the Windows version of VoiceEngine.
1
http://www.ietf.org/rfc/rfc2327.txt
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_Init();
This functions initiates all encoders/decoders supported by the VoiceEngine, NetEq and the
default sending channel. The function returns 0 if the initialization was successful and –1
otherwise. During initialization VoiceEngine might occur non-fatal errors, for example if there is
no sound card available for the moment. If so happens, GIPSVE_GetLastError will return
an error code that is non-zero. So it might be worth calling GetLastError after initialization.
The error codes are explained in Appendix A.
3.3
General Settings
int GIPSVE_SetNetworkStatus(int networktype);
networktype
Description
0
>= 1.5 Mbps, E1/T1/LAN
1
768kbps-1.5Mbps, ADSL/Cable
2
128-768kbps, ADSL/Cable/ISDN
3
< 64kbps, Dial-up
Used to set the network conditions. This information is used by the VoiceEngine to setup a
preferred order for the supported codecs.
The function returns 0 if it was successful and -1 if the specified network type is not supported.
int GIPSVE_GetNetworkStatus();
This function returns the network-type number set, if no network-type has been set the function
returns –1.
3.4
Channel functions
The GIPS VoiceEngine supports several channels i.e. it can send, receive, mix and play out
several audio streams. This enables functionality such as multiple-party conferencing, call
waiting, call hold etc. The following function calls are used for creating and deleting a channel as
well as retrieving the maximum number of channels supported in that particular version.
int GIPSVE_CreateChannel();
The return value is the channel ID that can be used in all function calls requiring channel ID as
input. If the channel is correctly created a positive value is returned (channel ID) or –1 if an error
occurred.
int GIPSVE_DeleteChannel(int channel);
The return value is 0 if the channel was successfully deleted or –1 if an error occurred.
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_GetNoOfChannels();
The return value is the maximum number of channels supported in this particular version of GIPS
VoiceEngine.
3.5
Codec setting functions
This section is divided into two subsections of which the first contains function calls necessary to
perform call setup and to make a call whereas the second subsection contains more advanced
settings that are optional to set.
3.5.1
Standard Settings
int GIPSVE_GetCodec
(int listnr, GIPSVE_CodecInst* codecinst);
Returns 0 if the codec information was successfully inserted to the given space. Returns –1 if
some error occurred. The entry listnr is the requested codec in the internal prioritized codec list
(0=highest priority). To get the length of the list use the function
GIPSVE_GetNofCodecs().
int GIPSVE_GetNofCodecs();
The function returns the number of supported codecs or –1 if an error has occurred at
initialization.
int GIPSVE_SetSendCodec
(int channel, GIPSVE_CodecInst * codecinfo);
Sets the codec for the given channel that is to be used for sending. The codec information is part
of the input arguments since the payload type and packet size (given in samples) can vary. The
MIME information (payload name and sampling frequency) must be the same as those types
supported by the GIPS VoiceEngine. Returns 0 if the codec and the settings are supported and –1
otherwise. Note that the function will return –1 if an invalid packet size or payload type is used.
The topic of using other settings than the default ones is explained further in section 3.11.
int GIPSVE_GetCurrentSendCodec
(int channel, GIPSVE_CodecInst * codecinfo);
The return value is 0 if the current send codec information for that channel was successfully
copied to the given address space and –1 if an error occurred.
3.5.2
Optional Settings
The GIPS VoiceEngine provides a list of supported codecs and their recommended settings such
as payload type number. For codecs using a dynamic payload type it may happen that another
SIP-based client has chosen another dynamic payload type corresponding to the same codec. In
the case of receiving an INVITE from such a client the GIPS VoiceEngine default payload type
GIPS VoiceEngine – API Specification
Feb, 2005
corresponding to the codec can be changed to the same dynamic payload type number as was
stated in the INVITE SDP-message. This is done using the following function call:
int
GIPSVE_SetRecPayloadType(short
*gipsve_inst);
channel,
GIPSVE_CodecInst
The return value is 0 if the payload type corresponding to the specific codec, for a specific
channel, was successfully changed and –1 if an error occurred.
3.6
Port and IP address setting functions
This section is divided into two subsections of which the first contains function calls necessary to
make a call whereas the second subsection contains more advanced settings that are optional to
set.
3.6.1
Standard Settings
int
GIPSVE_SetRecPort(int
channel,
*multiCastAddr = NULL, char *ip = NULL);
int
portnr,
char
The port number to receive on is set for that specific channel. Also the source port for sending
from is set to the same port number as default. The function returns 0 if it the port was set
successfully and –1 otherwise. If another port is desired as source port the function
GIPSVE_SetSrcPort() should be called.
There are two optional parameters to this call. To join a multicast group, set MultiCastAddr
to the desired multicast address. To listen on a specific interface, if you have several NICs, set ip
to the desired IP address to listen on.
int GIPSVE_GetRecPort(int channel);
The port number to receive on is returned for the channel. The function returns -1 if an error
occurred i.e. the channel does not exist.
int GIPSVE_SetSendPort(int channel, int portnr);
The port number to send to is set for that specific channel. The function returns 0 if the port was
set successfully and –1 otherwise.
int GIPSVE_GetSendPort(int channel);
The port number to send to is returned for the channel. The function returns -1 if an error
occurred i.e. the channel does not exist.
int GIPSVE_SetSendIP(int channel, char *ipadr);
The IP address that packets are going to be sent to is set for that specific channel, nothing else.
The function returns 0 if the address was set successfully and –1 otherwise.
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_GetSendIP(int channel, char *ipadr, int bufsize);
The IP address of the channel is copied into the buffer ipadr with length bufsize. The return value
is equal to 0 if successful, -1 otherwise.
3.6.2
Optional Settings
int GIPSVE_SetSrcPort(int channel, int portnr);
The port number to send from (source port) is set for that specific channel. The function returns 0
if the port was set successfully and –1 otherwise. Note that this function call must be made after
GIPSVE_SetRecPort() since otherwise the default source port will be used (the default
source port is the same as the receiving source port).
int GIPSVE_SetFilterPort(int channel,unsigned short filter);
Sets a port number to filter the incoming packets. Only packets with the defined source port will
be allowed. To disable the filter, set the port number to 0.
int GIPSVE_SetFilterIP(int channel,char *IPaddress);
Sets an IP address to filter the incoming packets. Only packets with the defined source IP address
will be allowed. To disable the filter use the IP address “0.0.0.0” or a NULL pointer.
unsigned short GIPSVE_GetFromPort(int channel);
Retrieves the current filter setting, a 0 return value indicates that there is no filter.
unsigned short GIPSVE_GetFilterPort(int channel);
Returns the source port of the incoming packets on a channel. If no packets has arrived on that
channel this call will return 0.
int GIPSVE_SetSendTOS(int channel, int TOS);
Sets the Type Of Service field in the IP header in the outgoing stream. Must be called before
GIPSVE_StartSend. For this setting to work on Windows 2000/XP a registry key must be
set. Under:
HKEY_LOCAL_MACHINE/SYSTEM/CurrentControlSet/Services/Tcpip/Parame
ters
There should be a DWORD value DisableUserTOSSetting set to 0.
Note: this call is not supported for the Mac and Linux platforms
int GIPSVE_GetSendTOS(int channel);
Returns the current set TOS value for a channel.
Note: this call is not supported for the Mac and Linux platforms
GIPS VoiceEngine – API Specification
int
GIPSVE_SetSendGQOS(int
servicetype);
channel,
bool
enable,
Feb, 2005
int
Since TOS setting is not supported in Windows 2000 and Windows XP, it is possible to instead
use the Windows GQoS API to modify the Diffserv codepoint and also the 802.1p marker bits,
when supported. This is done by setting a GQoS service level that the Windows operating system
will map to a Diffserv codepoint and to a 802.1p setting. These are the default values, copied
from http://msdn.microsoft.com.
Service Type
DSCP
802.1p
Network Control
30 (6)
7
Guaranteed Service
28 (5)
5
Controlled Load
18 (3)
3
Qualitative
0 (0)
0
All other traffic
0 (0)
0
Note: this call is not supported for the Mac and Linux platforms
int GIPSVE_GetSendGQOS(int channel) ;
Returns the currently set GQoS service level for a channel.
Note: this call is not supported for the Mac and Linux platforms
3.7
Start and stop functions
int GIPSVE_StartListen(int channel);
The GIPS VoiceEngine is initialized to listen for incoming RTP packets for the specified channel.
Before this call is made the port should have been set using the GIPSVE_SetRecPort()
function. Returns 0 if successful and –1 otherwise. This function must be called before
GIPSVE_StartSend() for a specific channel.
int GIPSVE_StartPlayout(int channel);
The packets are forwarded to the mixer/soundcard for that specific channel. If mixing of several
channels is desired then start playout should be called for all those channels. The VoiceEngine
automatically mixes all channels that are set to play out the incoming data. The function returns 0
if playout was started successfully and –1 otherwise.
int GIPSVE_StartSend(int channel);
The channel starts sending packets to the pre-specified IP address and port number. Returns 0 if
successful and –1 otherwise. This function should be called after GIPSVE_StartListen for
a specific channel.
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_StopListen(int channel);
Closes the listening socket for that channel. Returns 0 if successful and –1 otherwise. This
function should be called after GIPSVE_StopSend for a specific channel.
int GIPSVE_StopPlayout(int channel);
Stops sending data from the specified channel to the mixer/soundcard. However, packets are still
received as long as the VoiceEnigne is listening to the port! The function returns 0 if it is
successful and –1 otherwise.
int GIPSVE_StopSend(int channel);
Stops sending packets from that channel. The function returns 0 if the stop was made successfully
and -1 otherwise. This function should be called before GIPSVE_StopListen for a specific
channel.
3.8
Various other functions
3.8.1
Error handling
int GIPSVE_GetLastError();
Returns an integer corresponding to the last error that occurred in the GIPS VoiceEngine. –1 is
returned if no error has occurred since the VoiceEngine was initialized.
int
GIPSVE_SetPacketTimeout(int
time_sec);
channel,
bool
enable,
int
Enables or disables warnings if no packets are received in time_sec seconds for a specific
channel. –1 is returned if the function fails.
3.8.2
Run time Error handling and monitoring
To enable run time error handling, so VoiceEngine can report about real time error, there is a
public callback class. To get notified about runtime errors the error_callback class should be
overloaded:
class error_callback
{
public:
virtual void error_handler(int errCode, int channel);
};
The overloaded class is installed with:
int SetObserver (error_callback &observer);
GIPS VoiceEngine – API Specification
Feb, 2005
Refer to Appendix B for possible run time errors. –1 is used as channel number where no specific
channel is referred.
int GIPSVE_GetCPULoad();
Note: this call is not supported for the Mac and Linux platforms
Returns the VoiceEngine’s current CPU consumption in percent of what’s totally available. If this
value is higher than 70 % it is not recommended to add any more channels to a conference.
3.8.3
Version handling
int GIPSVE_GetVersion(char *version, int buflen);
Copies the version into the given buffer with length buflen. The function returns 0 if the copy was
performed successfully and –1 otherwise. A buffer size of 1024 characters is sufficient for this
call.
3.8.4
Mic/Speaker setting functions
int GIPSVE_SetSpeakerVolume(int level);
Sets the speaker volume level. The volume level range is 0-255. The function returns 0 if the
speaker volume was set successfully and –1 otherwise.
int GIPSVE_GetSpeakerVolume();
Returns the current speaker volume or –1 if an error occurred. The volume level range is 0-255.
int GIPSVE_SetMicVolume(int level);
Sets the microphone volume level. The volume level range is 0-255. The function returns 0 if the
mic volume was set successfully and –1 otherwise.
int GIPSVE_GetMicVolume();
Returns the current microphone volume or –1 if an error occurred. The volume level range is 0255.
int GIPSVE_SetChannelOutputVolumeScale(int channel, float level);
Normally the volume should be properly set by the sending side, but if there for some reason is a
known scaling problem it can be adjusted by this function. Default is to scale a channel with 1.0
but with the above function the interval 0..2.0 is allowed. Function returns 0 if successful and –1
if it failed. The level only affects the call volume, not the volume of files played on the channel.
float GIPSVE_GetChannelOutputVolumeScale(int channel);
Returns current scale factor for specified channel. If call was unsuccessful function returns –1.0.
GIPS VoiceEngine – API Specification
int GIPSVE_SetSoundDevices(unsigned int WaveInDevice,
int WaveOutDevice, bool disableMicBoost = false);
Feb, 2005
unsigned
Sets the sound device to be used during the call. If device is set to –1 the default device is used.
The function returns 0 if the sound device was set successfully and –1 otherwise.
Windows: Default sound device is the one selected as preferred device in Windows
(WAVE_MAPPER). If disableMicBoost is set the Microphone boost will be disabled. This
works on most of the sound cards, but not all of them, since mic boost is presented differently on
different sound cards.
Linux: Default sound device is /dev/dsp/. Setting the sound device to other value will select
/dev/dspXXX. The WaveInDevice and WaveOutDevice must be the same on this platform.
The disableMicBoost parameter is ignored on this platform.
Mac OSX: Default device is determined by calls
disableMicBoost parameter is ignored on this platform.
to
CoreAudio
library.
The
int GIPSVE_MuteMic(int channel,int Mute);
If Mute is set this call mutes the mic input signal completely without affecting the sound device
volume, the signal is replaced by zeros and data is still being transmitted. To un-mute, call with
Mute set to zero.
int GIPSVE_CheckIfAudioIsAvailable(int checkPlay, int checkRec);
Checks if the sound card is available to be opened for playout or recording (or both). Returns 0, if
the selected directions are available, otherwise -1. To check if playout is available:
GIPSVE_CheckIfAudioIsAvailable(1,0);
To check if playout and recording are available:
GIPSVE_CheckIfAudioIsAvailable(1,1);
3.8.5
Automatic Gain Control
int GIPSVE_SetAGCStatus(int mode);
Enables automatic gain control if mode equals 1 and disables it if mode equals 0. The function
returns 0 if it was successful and –1 otherwise.
int GIPSVE_GetAGCStatus();
This call returns 1 if automatic gain control is enabled. The value is 0 if disabled and –1 if an
error occurred.
3.8.6
Noise Suppression
Optional Feature
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_SetNRStatus(int mode);
Turns on or off Noise Suppression by setting mode to 0 (OFF) or non-zero (ON). Noise
Suppression is performed on the microphone signal for all channels.
int GIPSVE_GetNRStatus();
Returns whether the Noise Suppression is enabled (1) or disabled (0). By default Noise
Suppression is turned off.
int GIPSVE_SetNRpolicy(int mode);
Sets the aggressiveness of the Noise Suppression. There are three levels of aggressiveness, 0-2,
where 0 is the least aggressive, and 2 the most. The default value is 0.
3.8.7
Video synchronization
unsigned long int GIPSVE_GetPlayoutTimeStamp(int channel);
Returns the RTP timestamp of the audio that currently is played out. This function can be used to
synchronize video with the voice stream.
GIPSVE_SetMinDelay(int channel,int msDelay)
Sets a minimum delay for the playout jitter buffer. By default this value is zero. By setting this
value you increase the playout delay, to make it possible to synchronize the voice with video.
GIPSVE_getRemoteRTCPData(int channel, unsigned long * NTP_high,
unsigned long * NTP_low, unsigned long * timeStamp , unsigned
long * playoutTimeStamp)
This call obtains RTCP data from incoming RTCP Sender Reports. The NTP time and the
corresponding RTP time stamp can be used for video synchronization. These parameters are
further explained in RFC 3550, section 6.4.1. RTCP needs to be enabled for the channel for this
call. If no RTCP packets have been received, all parameters will be 0. An NTP time stamp that is
zero is always invalid.
The last parameter, playoutTimeStamp , is a locally obtained parameter. This is the playout
timestamp at the time of the last RTCP packet arrival. This values is stored to facilitate video
synchronization.
int GIPSVE_GetDelayEstimate(int channel) = 0;
Returns the sum of the algorithmic delay, jitter buffer delay, and the playout buffer delay for a
channel. This value does not include the transmission delay. The value returned is in
milliseconds.
int GIPSVE_InitTimeStamp(int channel, bool setManually, unsigned
long timestamp = 0) = 0;
Allows manual initialization of the RTP timestamp. If setManually is set to 1 the timestamp
will be set to timestamp, if set to 0 the timestamp will be automatically generated.
3.8.8
DTMF
int GIPSVE_SetDTMFPayload(int channel, int payload_nr);
Sets the dynamic payload number that should be used for DTMF events. This call is only relevant
when sending DTMF tones out-of-band (RFC 2833). It should only be used for setting the
GIPS VoiceEngine – API Specification
Feb, 2005
payload type of DTMF on the sending side. For setting the payload type on the receiving side use
GIPSVE_SetRecPayloadType(short channel, GIPSVE_CodecInst
*gipsve_inst);
int GIPSVE_SendDTMF(int channel, int eventnr, int inBand);
Sends DTMF tones either inband or out of band according to RFC 2833 if inBand is 1 or 0
respectively. The DTMF tone to be sent is specified with the eventnr (according to RFC 2833).
The function returns 0 if the DTMF tone is sent and –1 otherwise. Note that two function calls
should be spaced at least 120ms apart (more frequent calls could cause problems for a DTMF
detector).
int GIPSVE_SetDTMFFeedbackStatus(int mode);
Enables DTMF feedback if mode equals 1 and disables it if mode equals 0. That is when a DTMF
tone is sent the same DTMF tone is played out on the speaker. DTMF feedback is enabled by
default. The function returns 0 if the mode is correctly set and –1 otherwise.
int GIPSVE_GetDTMFFeedbackStatus();
Returns 1 if DTMF feedback is enabled, 0 if disabled and –1 if an error occurred.
int GIPSVE_PlayDTMFTone(int eventnr);
Plays a DTMF feedback tone locally only. This call is normally used if DTMF tones are
transmitted using SIP/NOTIFY method.
3.8.9
Playback of file
The VoiceEngine has support for playing files and mixing these with the signal from the
conversation. This is especially useful for platforms where the soundcard does not support more
than one channel of playback.
int GIPSVE_PlayPCM(int channel, InStream *pcm, int file_format =
FILE_FORMAT_PCM_FILE, float volume_scaling = 1.0);
int GIPSVE_PlayPCM(int channel, char * filename, bool loop =
false,
int
file_format
=
FILE_FORMAT_PCM_FILE,
float
volume_scaling = 1.0);
Either of these two interfaces can be used to read data from a file (or other location) and mix it
with the playback. The data can be in three different formats, and what format that is used is
specified by the parameter file_format:
FILE_FORMAT_PCM_FILE - The file is 16 kHz, 16 bit/sample mono, no header.
FILE_FORMAT_WAV_FILE - The file is a wav file, VoiceEngine supports PCM and u/A-law
format, 8/16 bits per sample, mono/stero, 8,11,16,22,32,44,or 48 kHz sampling rate.
FILE_FORMAT_COMPRESSED_FILE – The file is compressed with either iLBC or AMR
codec. The specification of the file formats can be found in RFC 3267 for AMR and in draft-ietf-
GIPS VoiceEngine – API Specification
Feb, 2005
avt-rtp-ilbc-05.txt for the iLBC codec. Note that the codec must be enabled in VoiceEngine to be
used for file compression.
The sound is played until the end unless StopPlayingFile or StopListen are called. If
loop is set the file will be played over and over until a stop call is being made.
The volume_scaling parameter gives the option to don-scale the amplitude of the signal, to avoid
too high volume of a played filed. This parameter must be between 0 and 1.0 where 1.0 is no
down-scaling at all.
One channel can be used both for a call and for playback of a file at the same time. The
channel needs to be opened for listening when making this function call and a channel can only
handle one playback at a time; so one channel per file/other input is needed. Returns 0 for ok and
–1 for error.
int GIPSVE_IsPlayingFile(int channel);
Returns 1 if the channel is currently playing a file, otherwise it returns –1.
int GIPSVE_StopPlayingFile(int channel);
Call this function to stop the playback of a file the specified channel. Returns 0 for ok and –1 for
error.
GIPSVE_PlayPCMAsMicrophone(int
channel,
InStream
*pcm,
bool
mixWithMic = false, int file_format = FILE_FORMAT_PCM_FILE, float
volume_scaling = 1.0);
int GIPSVE_PlayPCMAsMicrophone(int channel, char * fileName, bool
loop = false , bool mixWithMic = false, int file_format =
FILE_FORMAT_PCM_FILE, float volume_scaling = 1.0);
Either of these two interfaces can be used to read data from a file (or other location) and transmit
the data instead of the microphone. The file_format parameter specifies the file type used, refer to
the GIPSVE_PlayPCM description for a more detailed description regarding the formats.
The volume_scaling parameter gives the option to don-scale the amplitude of the signal, to avoid
too high volume of a played filed. This parameter must be between 0 and 1.0 where 1.0 is no
down-scaling at all. The sound will be played until the end unless
StopPlayingFileAsMicrophone or StopSend are called. If loop is set the file will be
played over and over until a stop call is being made. If mixWithMic is true the file will be
mixed with the local microphone instead of replacing the microphone signal.
int GIPSVE_IsPlayingFileAsMicrophone(int channel);
Returns 1 if the channel is currently playing a file as microphone signal, otherwise it returns –1.
int GIPSVE_StopPlayingFileAsMicrophone(int channel);
Call this function to stop the playback of a file as microphone signal for the specified channel.
Returns 0 for ok and –1 for error.
GIPS VoiceEngine – API Specification
3.8.10
Feb, 2005
Recording of files
Recording can be done from three different sources:

The microphone, regardless of a call is started or not

The playout of a specific channel. If the channel is currently not playing, nothing
will be recorded.

The entire call. At least one channel must be sending to be able to do this. For a
multi-party call all sources are mixed with the microphone signal.
Recording data can be outputted to either a file or to an OutStream object. Wav files can only be
outputted to files directly, since the header needs to be updated after the recording is finished.
Different sorts of compression can be applied to the file recording; the kind of compression used
is determined by the codecs_inst parameter:

No compression, 16 kHz PCM samples:
i. Let the codec_inst be NULL, or omit the parameter.

ILBC compression, as specified in draft-ietf-avt-rtp-ilbc-05.txt.
i. Set the plname member in codec_inst to “ilbc”. The sampling frequency
must be 8000 and the frame size can either 160 or 240 samples.

AMR compression, as specified in RFC 3267
i. Set plname to “amr”, rate to the desired value, sampling frequency to
8000 and the frame size to 160. Note that AMR must be included in
VoiceEngine for this mode to be supported.

WAV files
i. Uncompressed, plname “L16”, sampling frequency 8000 or 16000.
ii. G.711 u-law, plname “pcmu”, sampling frequency 8000.
iii. G.711 A-law, plname “pcma”, sampling frequency 8000.
Members of codec_inst that are not specified above do not matter for the recording.
Recording of playout:
int
GIPSVE_StartRecording(int
channel,
GIPSVE_CodecInst *codec_inst = NULL);
int
GIPSVE_StartRecording(int
channel,
GIPSVE_CodecInst *codec_inst = NULL);
char
*
fileName,
OutStream
*pcm,
int GIPSVE_StopRecording(int channel);
Recording of microphone:
int
GIPSVE_StartRecordingMicrophone(char
GIPSVE_CodecInst *codec_inst = NULL);
*
int
GIPSVE_StartRecordingMicrophone(OutStream
GIPSVE_CodecInst *codec_inst = NULL);
fileName,
*pcm,
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_StopRecordingMicrophone();
Recording of Call:
Optional Feature
int GIPSVE_StartRecordingCall(char * fileName, GIPSVE_CodecInst
*codec_inst = NULL);
int GIPSVE_StartRecordingCall(OutStream
*codec_inst = NULL);
*pcm,
GIPSVE_CodecInst
int GIPSVE_StopRecordingCall();
int GIPSVE_PauseRecordingCall(bool isPaused)
3.8.11
File Conversion calls
int GIPSVE_ConvertWavToPCM(char *InfileName, char *OutfileName);
int GIPSVE_ConvertWavToPCM(InStream *wav, OutStream *pcm);
These interfaces can be used to convert a .wav file of arbitrary PCM format to a file with PCM 16
kHz 16bit/sample. The converted file can be used when calling GIPSVE_PlayPCM. The
function returns 0 for ok and –1 for error.
GIPSVE_ConvertPCMToCompressed(char
*InfileName,
*OutfileName,GIPSVE_CodecInst *gipsve_inst)
GIPSVE_ConvertPCMToCompressed(InStream
*out,GIPSVE_CodecInst *gipsve_inst)
*in,
char
OutStream
Compresses a PCM 16 khz 16 bits/samples file or Instream to compressed format. The format to
be used is specified by the codec instance. The currently supported formats are either iLBC or
AMR codec. The specification of the file formats can be found in RFC 3267 for AMR and in
draft-ietf-avt-rtp-ilbc-05.txt for the iLBC codec. Note that the codec must be enabled in
VoiceEngine to be used for file compression.
int
GIPSVE_ConvertCompressedToPCM(char
*OutfileName)
*InfileName,
char
int GIPSVE_ConvertCompressedToPCM(InStream *in, OutStream *out)
Decompresses a compressed file to 16 kHz 16 bits/sample format. The currently supported
formats are either iLBC or AMR codec. The input file format must follow RFC 3267 for AMR
and in draft-ietf-avt-rtp-ilbc-05.txt for the iLBC codec. For AMR only single channel mode is
supported. Note that the codec must be enabled in VoiceEngine to be used for file decompression.
3.8.12
RTP and RTCP Functions
int GIPSVE_SetSendSSRC(int channel, unsigned long int ssrc) ;
GIPS VoiceEngine – API Specification
Feb, 2005
According to the RFC the SSRC field in the RTP header is generated as a random number.
VoiceEngine usually generates this value. However, through this function call it is possible to
specify the SSRC explicitly. This should be done before GIPSVE_StartSend() is called.
unsigned long int GIPSVE_GetSendSSRC(int channel) ;
Extract the RTP SSRC of the channel. The SSRC value corresponds to what was explicitly set by
GIPSVE_SetSendSSRC () or automatically generated by VoiceEngine. If VoiceEngine
generated the value is unspecified before GIPSVE_StartSend() is called.
int GIPSVE_RTCPStat(int channel, unsigned short *fraction_lost,
unsigned long *cum_lost, unsigned long *ext_max, unsigned long
*jitter , int *RTT);
int GIPSVE_RTCPStat(int channel, GIPSVE_CallStatistics * stats);
Retrieve the RTCP statistics computed by the GIPS VoiceEngine. The statistics are computed
according to RFC 3550. The function returns 0 if the information was retrieved successfully and –
1 otherwise.
int GIPSVE_EnableRTCP(int channel, int enable);
Enables the transmission of RTCP sender report (See RFC 3550 for details). The UDP port used
will send port + 1. The following fields are supported: Sender Reports, SDES:CNAME and BYE.
BYE is send automatically when GIPSVE_StopSend is called. For the moment, RTCP
transmission is NOT supported when using the external transport protocol.
int GIPSVE_SetRTCPCNAME(int channel, char * str);
Sets the CNAME parameter for RTCP reports. Default name is user1@undefined. This string can
not be longer than 255 bytes.
int GIPSVE_getRemoteRTCPCNAME(int channel, char * str);
Retrieves the CNAME parameter from the remote party RTCP report. If no RTCP report has been
received, or if the report does not contain any CNAME field, this will be an empty string. The
returned string can be up to 255 bytes long.
int GIPSVE_GetRemoteSSRC( int channel, unsigned int *SSRC,
unsigned char *CSRCBlock = NULL, int * CSRCLen = NULL, unsigned
char *energy = NULL) = 0;
Returns the SSRC of the incoming RTP packets. If CSRCBlock and CSRCLen is specified that
will contain the CSRCs for the incoming channel, and the length in bytes of that block. Refer to
RFC 3550 for more details. energy should always be set to NULL.
3.8.13
Push-to-talk functions
Optional Feature
int GIPSVE_StartPTTPlayout(int channel);
This method enables Push to Talk playout mode for the specified channel. Once this function has
been called, start and stop of sound playout is done automatically by the VoiceEngine (no calls to
GIPSVE_Start/StopPlayout are required). Start is triggered by incoming packets (someone in the
GIPS VoiceEngine – API Specification
Feb, 2005
sessions is talking) and stop is called automatically as soon as the remote talker is silent.
Currently, no mixing takes place, i.e., each person can only hear one other person talk.
int GIPSVE_GetPTTActivity(int channel);
Returns 1 if a PTT talk session is currently ongoing for the specified channel, and 0 otherwise.
int GIPSVE_GetPTTSession(int channel, GIPSVE_PTTState *state);
Retrieves details about the currently ongoing PTT session for the specified channel. The output
structure contains information about the remote side (port, IP address and SSRC), which is being
played out.
3.8.14
Speech level indicator
int GIPSVE_GetInputLevel() = 0;
Returns the microphone speech level filtered to be suited for display with a progress bar or
similar. The return value is in the range 0 to 9 and the progress bar is recommended to be divided
into different color fields like the following bar
. Note that the bar has ten different fields,
that is one for each possible output value. It is recommended to call this function every 100ms but
basically any interval is fine.
int GIPSVE_GetOutputLevel(int channel = -1) = 0;
Returns the speaker speech level filtered to be suited for display with a progress bar or similar. If
channel = -1 the level is for all channels combined including file playout, otherwise it indicates
the level for the specified voice channel. The return value is in the range 0 to 9 and the progress
bar is recommended to be divided into different color fields like the following bar
. Note
that the bar has ten different fields, that is one for each possible output value. It is recommended
to call this function every 100ms but basically any interval is fine.
3.8.15
External Media Processing
It is possible to add your custom media processing to the audio in VoiceEngine. To do that you
need to implement a class that does the actual processing:
class VOICEENGINE_DLLEXPORT GIPS_media_process
{
public:
virtual void process(int channel_no, short* audio_10ms_16kHz,
int len, int sampfreq) = 0;
virtual ~GIPS_media_process();
};
The processing is then activated with the following VoiceEngine call:
int GIPSVE_EnableExternalMediaProcessing(bool enable, int where,
int channel, GIPS_media_process &procObj)
The processing can be added to four different places, specified with the where argument:
PLAYBACK_PER_CHANNEL – The received audio for one channel, before it’s played out
GIPS VoiceEngine – API Specification
Feb, 2005
PLAYBACK_ALL_CHANNELS_MIXED --The audio that is played out, all channels and files
included. The channel argument is not relevant for this case.
RECORDING_PER_CHANNEL – The microphone signal for one specific channel.
RECORDING_ALL_CHANNELS_MIXED – The microphone signal for all channels. The
channel argument is not relevant for this case.
Every 10 ms the process callback will be called, with 160 samples of 16 kHz audio (len and
sampreq arguments). The number of samples in the frame cannot be changed. The
audio_10ms_16kHz vector contains the original data, and the modified data should be written
back to the same vector.
3.8.16
Forward Error Correction
VoiceEngine supports forward error correction according to RFC 2198. Note that it’s always
preferred to use one of GIPS robust codecs instead of FEC, since FEC adds end-to-end delay.
When a low bit-rate standard codec are use (G.729, G.723.1 etc) is used, FEC might be
beneficial. FEC can only be used with the same codec as redundant payload as the primary codec.
When enabled RTP data is sent with the RED payload instead of the codec payload. For more
details, and SDP information, refer to RFC 2198.
int GIPSVE_EnableFEC(int channel, bool enable, int REDpayloadtype
= -1)
If REDpayloadtype is omitted, or set to –1, the default payload type for RED is used.
3.8.17
Trace settings
int GIPSVE_SetTrace(int mode) ;
VoiceEngine can generate a trace file to facilitate debugging and trouble shooting. To enable this
feature call GIPSVE_SetTrace with mode = 2. To disable the file tracing call with mode = 0.
The default file name is trace.txt and the file is generated in the same directory as the executable
is started from. By default this file is encrypted.
int GIPSVE_SetTraceFileName(char * fileName);
To specify another trace file name and location than the default. This call must be made before
the tracing is enabled with GIPSVE_SetTrace.
int
GIPSVE_SetTraceCallback(void
int));
(*callbackFunction)(char
*,
With this call you can enable a callback function for the trace information instead of the default
file handling. The callback will be called for every text line that would be added to the trace file.
3.8.18
External Recording Source
In some cases it’s desirable to use another audio source than a sound card for the recorded signal,
for example a DV camera. In such cases the API for external recording source can be used:
int GIPSVE_Enable_External_Recording(bool enable);
int GIPSVE_External_Recording_SendData(short * speech_10ms, int
sampFreq, int currentRecordingDelayinMS, int length = -1) = 0;
GIPS VoiceEngine – API Specification
Feb, 2005
External recording must be enabled before transmission is started for any channel, otherwise the
sound card will be used as recording source. External recording can’t be disabled as long as a
channel is sending. During transmission GIPSVE_External_Recording_SendData
should be called regularly with a block of audio. The length of the block is specified in the
parameter length (samples) and must be a multiple of 10 ms. The allowed sampling
frequencies are 16000 and 48000 Hz. The block length must thus be a multiple of 160 and 480
respectively. CurrendRecordingDelayinMS should be an estimate of the delay in ms from
that the audio is recorded until it’s handed to VoiceEngine. This estimate is important to the echo
canceller.
3.8.19
External Playout Source
In some cases it’s desirable to use another audio playout source. In such cases the API for
external playout can be used:
int GIPSVE_Enable_External_Playout (bool enable);
int GIPSVE_GetPlayData(short
currentPlayDelayinMS)
*
speech_10ms,
int
sampFreq,
int
External playout must be enabled before transmission is started for any channel, otherwise the
sound card will be used for playout. External playout can not be disabled as long as a channel is
sending. During transmission GIPSVE_GetPlayData should be called every 10 ms to obtain
an new 10 ms-block of audio. The allowed sampling frequencies are 16000 and 48000 Hz. The
length of the block is either 160 or 480 samples. currentPlayDelayinMS should be an
estimate of the delay in ms from that the function call until the audio is played out (playout buffer
size). This estimate is important to the echo canceller.
3.8.20
Non real-time RTP to file conversion
If you have stored RTP-packets that you want to convert to a file you can do this faster than realtime with the following functions. Note that you need the timestamp for each packet to reproduce
the call.
Initiate the conversion by calling GIPSVE_InitRTPToPCMConversion, you can choose to store
the output to a file or to an OutStream. Argument conversionDelay is the number of ms that the
VoiceEngine delays the mixing of all the channels to make sure that all packet are received before
doing the actual mixing and file storage. Argument codecs_inst works as described in section
3.8.10.
int GIPSVE_InitRTPToPCMConversion(const char* fileName, unsigned int conversionDelay,
GIPSVE_CodecInst *gipsve_inst);
int GIPSVE_InitRTPToPCMConversion(OutStream *out, unsigned int conversionDelay,
GIPSVE_CodecInst *gipsve_inst);
Start and stop adds/removes a channel from the mix.
int GIPSVE_StartRTPToPCMConversion(int channel);
int GIPSVE_StopRTPToPCMConversion(int channel);
For each RTP-packet call GIPSVE_ConvertRTPToPCM, rtpPacketBuffer is a pointer to the
stored RTP-packet, length is the length of the RTP-packet and incomingTimeStamp is the time in
ms when the packet was originally received. To flush the internal buffers in VE, i.e. the
conversionDelay call GIPSVE_ConvertRTPToPCM with rtpPacketBuffer and length with 0 and
incomingTimeStamp to the last timestamp.
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_ConvertRTPToPCM( int channel, char *rtpPacketBuffer, int length, unsigned long
incomingTimeStamp);
3.8.21
Handling of optional products
int GIPSVE_SetVADStatus(int enable, int mode = 0, bool disableDTX
= 0);
Optional Feature
Enables the VAD/DTX (silence suppression) functionality if enable equals 1 and disables it if
enable equals 0. mode determines the aggressiveness (0-2), where 0 is the least aggressive, and 2
the most. If the optional parameter disableDTX is enabled (and the VAD/DTX is enabled) the
DTX will be disabled while the VAD still is enabled. The VAD/DTX will then detect silent
frames but let all sound through unaffected. This is useful for getting information on the VAD
decisions without affecting the sound. The VAD decision can be extracted with
GIPSVE_GetVoiceActivityIndicator(). The return value is 0 if successful and –1
otherwise. In the unsuccessful case it can be assumed the VAD/DTX (silence suppression) is
disabled or cannot be set.
int GIPSVE_GetVADStatus();
Optional Feature
The return value is 1 if VAD/DTX (silence suppression) is enabled, 0 if it is not enabled, and –1
if the function capability is not supported.
int GIPSVE_GetVoiceActivityIndicator(int channel) = 0;
Optional Feature
Returns 1 if the VAD/DTX is disabled or the VAD decision (1 for voice detected, 0 for voice not
detected) if the VAD/DTX is enabled. If an error occurred, -1 is returned.
GIPSVE_SetSendCNPayloadType(int channel,short payloadType);
Optional Feature
Sets the payload type for the sending of SID-frames with background noise estimation during
silence periods detected by the VAD (Voice Activity Detection). The return value is 0 if the
payload type was successfully set or –1 if an error occurred.
int GIPSVE_SetECStatus(int mode);
Optional Feature
Mode = 1 enables the acoustic echo cancellation functionality. Mode = 2 set the acoustic echo
cancellation functionality in automatic mode, where it will enter an inactive mode if it detects that
it is not needed. Mode = 0 disables the acoustic echo cancellation functionality. The return value
GIPS VoiceEngine – API Specification
Feb, 2005
is 0 if successful and –1 otherwise. In the unsuccessful case it can be assumed that the acoustic
echo cancellation is disabled or cannot be set.
int GIPSVE_GetECStatus();
Optional Feature
The return value is 1 if acoustic echo cancellation is enabled, 0 if it is not enabled and –1 if the
function capability is not supported.
int GIPSVE_SetECType(int type) = 0;
Optional Feature
Type = 0 enables the acoustic echo cancellation functionality and type = 1 enables the acoustic
echo suppression functionality. Once either of them is enabled the other is automatically disabled.
The return value is 0 if successful and –1 otherwise.
int GIPSVE_GetECType() = 0;
Optional Feature
The return value is 0 if acoustic echo cancellation is enabled, 1 if acoustic echo suppression is
enabled and –1 if the capability is not supported.
int GIPSVE_GetECActivity ();
Optional Feature
The return value is only relevant if the acoustic echo canceller is set in automatic mode
(GIPSVE_SetECStatus(2)). The return value is 0 if acoustic echo cancellation is inactive,
and 1 if acoustic echo suppression is active. This functionality is not available for the echo
suppression type.
int GIPSVE_AddToConference (int channel, bool enable,
includeCSRCs = false, bool includeVoiceLevel = false);
bool
Optional Feature
After calling this function with enable set, the received audio from this channel will be mixed into
the mic signal that is transmitted to all other channels, thus enable a three or four party call. The
optional includeCSRCs parameter specifies whether CSRCs should be included in the RTP
header (see RFC 3550). Enabling this parameter will make the RTP header correct, but consume
more bandwidth. The parameter includeVoiceLevel should always be set to false.
3.9
Secure RTP
Optional Feature
VoiceEngine can be delivered with a reference implementation of Secure RTP (SRTP) using an
open source implementation available at http://srtp.sourceforge.net/.
There are two kinds of cipher available (cipher_type)
#define CIPHER_NULL 0
#define CIPHER_AES_128_COUNTER_MODE 1
GIPS VoiceEngine – API Specification
Feb, 2005
There are two types of authentication available (auth_type)
#define AUTH_NULL 0
#define AUTH_HMAC_SHA1 3
There are four levels of protection (security)
#define NO_PROTECTION 0
#define ENCRYPTION 1
#define AUTHENTICATION 2
#define ENCRYPTION_AND_AUTHENTICATION 3
For more details, please refer
http://srtp.sourceforge.net/
to
the
documentation
of
libSRTP
at
int
GIPSVE_EnableSRTPSend(int
channel,int
cipher_type,int
cipher_key_len,int auth_type, int auth_key_len,int auth_tag_len,
int security, const unsigned char key[16])
Enables SRTP on the transmitted data for a given channel.
GIPSVE_DisableSRTPSend(int channel)
Disables SRTP on the transmitted data for a given channel.
intGIPSVE_EnableSRTPReceive(int
channel,int
cipher_type,int
cipher_key_len,int auth_type, int auth_key_len,int auth_tag_len,
int security, const unsigned char key[16])
Enables SRTP on the received data for a given channel.
int GIPSVE_DisableSRTPReceive(int channel)
Disables SRTP on the received data for a given channel.
3.10 Telchemy VQMon support
GIPS VoiceEngine can integrate Telchemy VQMon-EP into a simple high-level API. The
VQMon software needs to be licensed from Telchemy for this. The following calls are available
to control VQMon:
int GIPSVE_EnableVQMon(int channel, bool enable);
Enables VQMon for a channel.
int GIPSVE_EnableRTCP_XR(int channel, bool enable);
Enables RTCP-XR (RFC 3611) for a channel. RTCP must be enabled for this channel.
int GIPSVE_GetVoIPMetrics(int
unsigned int bufSize);
channel,
unsigned
char
*dst,
Returns a VoIP Metrics block for the specified channel, for details refer to RC 3611 section 4.7.
int GIPSVE_InstallAlertHandler(vqmon_alert alert_callback);
GIPS VoiceEngine – API Specification
Feb, 2005
typedef void (*vqmon_alert)(int channel,void* pAlertDesc);
Installs a VQMon alert handler. When an alert is triggered the specified function will be called.
Refer for Telchemy VQMon documentation for more details about alert settings.
int GIPSVE_SetAlert(int
param2, int param3);
channel,
int
type,
int
param1,
int
Sets an alert type for a certain condition for a channel. Refer for Telchemy VQMon
documentation for more details about alert settings.
int GIPSVE_RemoveAlert(int channel, int type);
Sets an alert type for a certain condition for a channel. Refer for Telchemy VQMon
documentation for more details about alert settings.
3.11 Encryption
VoiceEngine provides an interface that enables the user to add their own encryption scheme to
the RTP stream. What needs to be done is to implement a C++ class that overloads the
GIPS_encryption class defined in the API header file:
class GIPS_encryption
{
public:
virtual void encrypt(int channel_no, unsigned char * in_data,
unsigned char * out_data, int bytes_in, int * bytes_out) = 0;
virtual void decrypt(int channel_no, unsigned char * in_data,
unsigned char * out_data, int bytes_in, int * bytes_out) = 0;
virtual void encrypt_rtcp(int channel_no, unsigned char * in_data,
unsigned char * out_data, int bytes_in, int * bytes_out) = 0;
virtual void decrypt_rtcp(int channel_no, unsigned char * in_data,
unsigned char * out_data, int bytes_in, int * bytes_out) = 0;
};
The encrypt call will be called for every RTP packet that is sent with the whole RTP packet as
argument in_data including the RTP header. If the RTP header should not be encrypted the first
12 bytes should be left un-touched. For every call the function must set the value pointed to by
bytes_out to the number of bytes to be sent. If the packet does not change its size by the
encryption bytes_out should be set to bytes_in.
The same methology is used for the decrypt call that will be called for every incoming RTP
packet. Besides implementing the encryption class the following calls are used to enable the
encryption:
encrypt_rtcp
packets.
and
decrypt_rtcp
are
the
corresponding
calls
for
RTCP
GIPS VoiceEngine – API Specification
Feb, 2005
int GIPSVE_InitEncryption (GIPS_encryption &encr_obj)
This call initializes VoiceEninge with the encryption object that should be used for the
encryption.
int GIPSVE_EnableEncryption(int channel)
This call turns on the encryption and the decryption for the specified channel.
int GIPSVE_DisableEncryption(int channel)
This call turns off the encryption and the decryption for the specified channel.
3.12 External Transport Protocol
The standard configuration of GIPS VoiceEngine uses RTP/UDP/IP to transmit data over the
network, but it does also support usage of an external transport protocol, if configured in that
particular mode. In the external transportation-mode, sending and receiving packets from the
network must be handled by the user outside of the VoiceEngine. Therefore an additional
interface is needed so that the VoiceEngine can call a send-function once a block of speech has
been recorded, encoded and packetized and a call to pass the packet received from the network to
the VoiceEngine. Note that the VoiceEngine will deliver RTP/RTCP packets to the send-function
and expects to receive the RTP/RTCP packets from the network. The information is packetized in
RTP/RTCP-format because information such as payload type and sequence number is vital to
make a correct decoding of the data. The following class and function calls enable an external
transport protocol:
class GIPS_transport
{
public:
virtual void SendPacket(int channel, const void *data, int len)
virtual void SendRTCPPacket(int channel, const void*data,int len)
};
This class must be implemented by the user, which then will allow VoiceEngine to call the send
function once a block of data is recorded, encoded and packetized. The following function should
be called with the “GIPS_transport”-object so that VoiceEngine has access to the object and thus
is able to call the “SendPacket()”-function:
int
GIPSVE_SetSendTransport(int
&transport);
channel,
GIPS_transport
The packets received from the network should be passed to the following functions:
int GIPSVE_ReceivedRTPPacket(int channel, const void *data, int
len);
int GIPSVE_ReceivedRTCPPacket(int channel, const void *data, int
len)
Note that the data including the RTP/RTCP-header should be given to the VoiceEngine.
GIPS VoiceEngine – API Specification
Feb, 2005
3.13 Sending raw data
Two calls are available to send raw data over the RTP channel and the RTCP channel:
int sendExtraPacket_RTP(int
nbytes);
channel,
unsigned
char*
data,
int
int sendExtraPacket_RTCP(int channel, unsigned char* data, int
nbytes);
Sending must be active for these calls to be valid. No RTP/RTCP headers are added to the data,
only UDP/IP headers. The actual number of bytes transmitted is returned, -1 for error.
3.14 Termination functions
int GIPSVE_Terminate();
Kills the instance of the GIPS VoiceEngine. The function returns 0 if the application was killed
successfully and –1 otherwise.
3.15 Example code
The following example illustrates how the above functions should be used during a SIP call setup.
The main program needs to take care of all SIP messages and to call the GIPS VoiceEngine when
appropriate. The left column in the matrix shows what is being done in the main program and the
right column shows what calls the main program should make to the GIPS VoiceEngine. The
main program starts the call-setup by sending an INVITE and it ends with receiving 200 OK for
the sent BYE!
What happens in the main program?
What calls needs to be made to the
GIPS VoiceEngine?
The application is started
Initiation of the VoiceEngine
GIPSVE_Init()
The VoiceEngine has now initiated all codecs, NetEq
etc
Create a channel
Start without
cancellation
GIPSVE_CreateChannel()
silence
suppression
and
echo GIPSVE_SetVADStatus(0)
GIPSVE_SetECStatus(0)
Set the network status to ADSL/Cable modem
GIPSVE_SetNetworkStatus(1)
Want to send an INVITE for a new call.
GIPSVE_GetNofCodecs()
Ask for the preferred and available codecs.
GIPSVE_GetCodecInfo(0,&codecinfo0)
Get the preferred one and one more!
GIPSVE_GetCodecInfo(1,&codecinfo1)
Send the INVITE
GIPSVE_SetRecPort(0, 22002)
Set the listening port number to 22002 and start GIPSVE_StartListen(0)
GIPS VoiceEngine – API Specification
Feb, 2005
listening
Receive 180 Ringing, 200 OK
GIPSVE_SetSendPort(0, 15080)
User can start sending traffic
GIPSVE_SetSendIP(0, 143.12.12.13)
GIPSVE_SetSendCodec(0, codecinfo)
GIPSVE_StartSend(0)
Send ACK
GIPSVE_StartPlayout(0)
User starts playing out to speakers
User increases speaker volume
GIPSVE_SetSpeakerVolume(
GIPSVE_GetSpeakerVolume() + 10)
Conversation is going on
User ends call with BYE
GIPSVE_StopSend(0)
Stops transmitting packets
User receives 200 OK for BYE
Stops listening for packets
GIPSVE_StopListen(0)
Stops playing out on speaker
GIPSVE_StopPlayout(0)
3.16 Change of codec settings
As stated previously the GIPS VoiceEngine holds information about each codec it supports in the
following format:
struct GIPSVE_CodecInst {
int pltype;
char plname[16];
int plfreq;
int pacsize;
int channels;
int rate;};
The pltype is the payload type, plname the MIME name, plfreq the sampling-frequency of the
codec, pacsize the number of samples to be sent in each packet and channels is the number of
audio channels (1=mono, 2=stereo and so forth). The rate member contains the codec bit rate in
bits per second. The user can retrieve information about the supported codecs from GIPS VE by
first calling
int GIPSVE_GetNofCodecs();
that returns how many codecs that are supported and secondly
int GIPSVE_GetCodec
(int listnr, GIPSVE_CodecInst* codecinst);
GIPS VoiceEngine – API Specification
Feb, 2005
that writes the actual information in the GIPSVE_CodecInst-structure. The structure will
contain the default settings that are recommended to use.
3.16.1
Change of sending settings
As mentioned above the GIPSVE_CodecInst-structure will contain the default codec settings
after a GIPSVE_GetCodec()-call has been made. This information consists of five variables
out of which two, the payload type and the packet size, can be changed and three, the payload
name, the sampling frequency and the number of channels, cannot. To use a codec for sending
with non-default settings the structure member variable in question must be set to the desired new
value. Next the structure should be used in the following call to make the change:
int GIPSVE_SetSendCodec
(int channel, GIPSVE_CodecInst * codecinfo);
For example when network status has been set to 0 (see section 4.1.3) and the
GIPSVE_GetCodec( listnr, codecinst)-function call is made with “listnr” equal to 0, the following
information can be extracted from the codecinst-structure.
pltype
= 97
plname
= ipcmwb
plfreq
= 16000
pacsize
= 320
channels
= 1
rate
= 80000
These values are the recommended settings for the iPCM-wb codec. Two of them, the pltype and
the pacsize, can be changed. It is important to notice that different codecs have different
flexibility in terms of settings, but plname, plfreq and channels can never be changed. pltype
(payload type) on the other hand can always be changed no matter what codec is being used.
Allowed payload types are all values in the dynamic payload range, 96-127, and the static
payload type if one is assigned to the codec. The other changeable variable pacsize (packet size),
can be changed for some codecs. Below is a short list of codecs with corresponding allowed
packet sizes:
IPCM-wb
(samples): 160, 320, 480 and 640
EG711
(samples): 80, 160, 240 and 320
PCMU/A
(samples): 80, 160, 240 and 320
ILBC
(samples): 240
Note that iPCM-wb uses 16kHz sampling frequency and the other uses 8kHz sampling frequency.
That is 160 samples at 16kHz corresponds to 10ms of audio but at the same time 80 samples at
8kHz also corresponds to 10ms of audio.
The rate parameter is only relevant when setting a codec for two codecs: AMR and iSAC. For
AMR it is possible to select what rate that should be used. Possible settings are: 4750, 5150,
5900, 6700, 7400, 7950, 10200, and 12200. The rate can also be set to an integer 0-7, for the
corresponding bit rate 4750- 12200.
GIPS VoiceEngine – API Specification
Feb, 2005
For iSAC either adaptive bit rate or a specified rate between 10000 and 32000 kbit/s is allowed.
By default iSAC bandwidth is set to adaptive mode and then the rate parameter is –1. To specify
a bit rate, change the parameter to the desired value in bits per second. It is recommended to use
the adaptive mode for iSAC.
3.17 Error handling
All functions return 0 if the task was successfully performed and –1 otherwise2. So when a
function returns –1 it does not necessarily mean that there is a major error but rather that the
specific task could not be performed. For example the function
int GIPSVE_StartPlayout(int channel);
will return –1 if the input value, channel, contains a negative number. But it will also return –1 if
the computer does not have a sound card installed. To find out the specific reason to why the
function returned –1 the following function must be called
int GIPSVE_GetLastError();
This function returns a positive integer corresponding to the last error that occurred in the GIPS
VoiceEngine or –1 if no error has occurred. These values are referred to as error codes. The error
codes are divided into the following threes categories:
Error code:
The severity of the error:
Example error:
100xx
VoIP call cannot be performed
No sound card installed on the PC
90xx
There is limited functionality
The sound card does not support
volume changes
80xx
The task of the function is not VoiceEngine functions are called with
performed
invalid parameters
For a description of specific error codes please see appendix A.
3.17.1
Recommended handling of the error codes
The following table shows how the error codes are categorized according to the severity of the
error and according to what action that we recommend are to be taken.
Error code:
Recommended action:
Example error:
100xx
Message-box displaying the specific error No sound card installed on the PC
code and a request that the user should check
the
specific
hardware/software
not
functioning properly
90xx
Disable the feature not functioning properly
The sound card does not support
The only function not following this rule is “int GIPSVE_Init();” which only returns –1 if the
error is of the kind that a call cannot be performed. Errors that limits functionality will cause a 0 to be
returned but will generate an error code that can be extracted by calling
“int
GIPSVE_GetLastError();”.
2
GIPS VoiceEngine – API Specification
Feb, 2005
volume changes
80xx
Nothing to be communicated to the end-user
VoiceEngine functions are called
with invalid parameters
Appendix A shows the error code and gives a possible reason to why the problem occurs. This
table can be used to create the proper message-box to inform the end-user of the problem and
request him/her to check the specific hardware/software not functioning.
GIPS VoiceEngine – API Specification
Feb, 2005
APPENDIX A
The table in appendix A describes all the possible error codes that can be returned when calling
int GIPSVE_GetLastError();
Please see section 3.12.1 for recommended handling of the error codes.
Error Code Function Name/s
GIPSVE_StartListen
8001 GIPSVE_StartSend
Problem Description
No
port
has
listening/sending
Possible Reason
been
set
for
All functions with channel as
8002 input
Invalid channel number as function input
8003 Version dependent
This functionality is not included in this
version
8004 GIPSVE_GetCodec
The input list number is larger/smaller
than list size
8005 GIPSVE_SetNetworkStatus
The input variable is outside of the
allowed range
GIPSVE_SetRecPort
GIPSVE_SetSendPort
GIPSVE_StartListen
GIPSVE_StartSend
8006 GIPSVE_SetSrcPort
8007 GIPSVE_SetSendCodec
8008 GIPSVE_SetSendCodec
8009 GIPSVE_SetSendCodec
8010 GIPSVE_SetSendCodec
8011 GIPSVE_SetSendCodec
GIPSVE_SetRecPort
8012 GIPSVE_StartListen
These errors are
usually caused by
invalid input
The input port number is outside of the arguments to the
function calls or if
allowed range
parameters needed
The input payload name is not correct
for performing the
task has not been
The input frequency is not allowed
set. For example a
The input payload type is outside of the channel needs to be
allowed range or belongs to a codec not
created before
supported
starting to play out
on speaker. If that
The input packet size is not supported
has not been done
Change of packet size during call is not then error code
8013 will be
supported
returned.
VoiceEngine is already listening
8013 GIPSVE_StartPlayout
The channel is not created yet
8014 GIPSVE_StartPlayout
Conferencing is not supported in this
version
8015 GIPSVE_StartSend
Failed to prepare header for recording
buffer
8016 GIPSVE_StartSend
Failed to add buffer for recording
8017 GIPSVE_StartPlayout
Failed to prepare header for playback
buffer
GIPS VoiceEngine – API Specification
GIPSVE_StartSend
GIPSVE_SetSrcPort
8018 GIPSVE_SetSendTOS
VoiceEngine is already sending
GIPSVE_SetSendIP
8019 GIPSVE_StartSend
The input IP address is invalid
8020 GIPSVE_StartPlayout
VoiceEngine is already playing
8021 GIPSVE_GetVersion
The input buffer is to small to hold all
version info
8022 GIPSVE_SendDTMF
The input DTMF tone number is invalid
8023 GIPSVE_SetSendCodec
The input channels is not correct (codec
parameter)
Feb, 2005
Setting a new payload type for receiving
8024 GIPSVE_SetRecPayloadType failed
8025 GIPSVE_DisableEncryption
Encryption has not been initialized. That
is an object to an encryption algorithm
has not been passed to the VoiceEngine
8026 GIPSVE_CreateChannel
VoiceEngine has not been initialized yet.
8027 GIPSVE_SendDTMF
DTMF tones cannot be sent until the
VoiceEngine has started sending media
GIPSVE_EnableEncryption
VoiceEngine is not compiled to support
8028 GIPSVE_SetSendTransport external transport protocol
GIPSVE_SetRecPort
GIPSVE_SetSendPort
8029 GIPSVE_StartListen
VoiceEngine is compiled to support
external transport protocol and these
calls have no meaning.
8030 GIPSVE_StopSend
Sound card failure
8031 GIPSVE_SetSendCodec
Rate is not valid
GIPSVE_ReceivedRTPPacket
8032 GIPSVE_ConvertRTPToPCM RTP packet seems to be corrupt.
Incoming timestamp parameter is out of
8034 GIPSVE_ConvertRTPToPCM sequence
8036 GIPSVE_SendDTMF
Error Code Function Name/s
Previous DTMF tone is still ongoing.
Wait 100ms and try again
Problem Description
Possible Reason
9001 GIPSVE_SetRecPort
Network
card
Cannot bind the socket for receiving hardware/software
RTCP packets
problem
9002 GIPSVE_SetMicVolume
Cannot set microphone level
9003 GIPSVE_SetSpeakerVolume Cannot set speaker volume
Sound card problem
Sound card problem
GIPS VoiceEngine – API Specification
Feb, 2005
9004 GIPSVE_Init
Cannot access sound card to change or
retrieve recording level
Sound card problem
9005 GIPSVE_Init
Cannot access sound card to change or
retrieve speaker volume
Sound card problem
9006 GIPSVE_GetSpeakerVolume Cannot retrieve speaker volume
Sound card problem
9007 GIPSVE_StartListen
Cannot create thread for receiving RTCP
packets
9008 GIPSVE_Init
Cannot init AEC
9009 GIPSVE_Init
Cannot init AES
9010 GIPSVE_StartSend
Cannot set TOS for outgoing stream. Forgot to set registry
Everything else will work.
key?
GIPSVE_GetVoIPMetrics
GIPSVE_SetAlert
9011 GIPSVE_RemoveAlert
Vqmon call fails enabled
Faulty parameters
GIPSVE_EnableRTCP_XR
9012 GIPSVE_GetVoIPMetrics
Error Code Function Name/s
VQMon must be enabled first
Problem Description
Possible Reason
10001 GIPSVE_StartPlayout
Undefined sound card error
Sound card problem
10002 GIPSVE_StartSend
Cannot open sound card for recording
Sound card problem
10003 GIPSVE_SetRecPort
Network
card
Cannot bind the socket for receiving RTP hardware/software
packets
problem
10004 GIPSVE_StartPlayout
Write to sound card failed (invalid
handle)
Sound card problem
10005 GIPSVE_StartPlayout
Write to sound card failed (no driver)
Sound card problem
10006 GIPSVE_StartPlayout
Write to sound card failed (no memory)
Sound card problem
10007 GIPSVE_StartPlayout
Write to sound card failed (header not
prepared)
Sound card problem
10008 GIPSVE_StartPlayout
Write to sound card failed (still playing)
10009 GIPSVE_StartPlayout
Write to sound card failed (undefined
error)
Sound card problem
10010 GIPSVE_StartSend
Read from sound card failed (undefined
error)
Sound card problem
10011 GIPSVE_StartListen
Network
card
Cannot create thread for receiving RTP hardware/software
packets
problem
Sound card problem
GIPS VoiceEngine – API Specification
Feb, 2005
10012 GIPSVE_StartSend
Cannot start recording from sound card
Sound card problem
10013 GIPSVE_StartPlayout
Cannot open sound card for play back
Sound card problem
10014 GIPSVE_Init
Cannot start up windows sockets
Winsock 2 is not
supported
10015 GIPSVE_StartSend
Network
card
Cannot bind the socket for sending RTP hardware/software
packets
problem
GIPSVE_SetInputFile
GIPSVE_StartRecording
10016 GIPSVE_PlayPCM
The file does not
This is not a valid file, or the file cannot exist, or I locked by
be opened for reading.
another application.
10017 Any call
This is a time limited version of
VoiceEngine and the time has expired.
1018 Any call
You
must
first
call
GIPSVE_GIPSVE_Authenticate with a
valid password.
GIPSVE_ConvertWavToPCM
APPENDIX B
The table in appendix B describes all the possible runtime error codes.
Error Code Error name
Problem Description
Possible Reason
VE_RECEIVE_PACKET_TIME No packet received during the
8035 OUT
time specified in section 3.8.1.
USB port overload.
9013 VE_RUNTIME_REC_PROBLEM The recorded audio is distorted. overloaded.
10020 VE_RUNTIME_REC_ERROR
Recording fails.
10019 VE_RUNTIME_PLAY_ERROR Playout fails
CPU
USB sound card is unplugged
during a call.
USB sound card is unplugged
during a call.