SetSpeexCodecParameters

The SetSpeexCodecParameters API procedure is used to set optional speex codec settings for each phone line. The VOIP Media Engine supports both 8kHz narrow band and 16kHz wide band speex encoding and decoding. All speex encoder/decoder modes are supported in addition to full support for the encoder complexity.

Your VOIP application can use both narrow band and wide band speex codecs at the same time (in addition to the other supported codecs) when initiating or receiving a call.

 

Parameters:

hStateMachine

[in] The handle to the telephony engine. This is the handle that was returned by a previous call to the StartSipTelephony procedure.

PhoneLine

[in] The zero based phone line to use when updating the speex codec parameters. Application software can modify speex codec parameters individually for each phone line.

Bandwidth

[in] Specify 8000 to set speex narrow band codec parameters for the phone line. Specify 16000 to set speex wide band codec parameters for the phone line. Narrow band and wide band parameters are separately maintained for each phone line.

DefaultEncoderMode

[in] When calls are established, the encoder mode that is used by the phone line depends on what the far end of the call specified in the call setup via sdp values in the SIP. The phone line will use the far end's highest priority specified "mode" that was contained in the SIP. For the speex codec however, the far end could simply specify that "any" codec mode be used. In this ambiguous case, this parameter will be used to select the encoder mode that will be used when sending speex media to the far end.

This value must be in the range of 1 to 8 for narrow band and between 1 and 10 for wide band. The following table shows how the DefaultEncoderMode setting affects the speex encoder quality and transmit bit-rate for narrow band encoding:


 

The following table shows how the DefaultEncoderMode setting affects the speex encoder quality and transmit bit-rate for wide band and ultra wide band encoding:
 

Note: Ultra wide band currently not supported.
 

The internal default value of DefaultEncoderMode is 3 for narrow band 8kHz encoders and 8 for wide band 16kHz encoders.
 

EncoderComplexity

[in] This value controls the computation requirements of the encoder. This value must be in the range of 1 to 10 inclusive. The following text is quoted from the published speex user manual:

"With Speex, it is possible to vary the complexity allowed for the encoder. This is done by controlling how the search is performed with an integer ranging from 1 to 10 in a way that’s similar to the -1 to -9 options to gzip and bzip2 compression utilities. For normal use, the noise level at complexity 1 is between 1 and 2 dB higher than at complexity 10, but the CPU requirements for complexity 10 is about 5 times higher than for complexity 1. In practice, the best trade-off is between complexity 2 and 4, though higher settings are often useful when encoding non-speech sounds like DTMF tones."

The internal default value of EncoderComplexity is 2. Higher values require more CPU.
 

pDecoderModes

[in] This value allows you to specify what speex decoder modes are supported by your application. The modes listed are in order of preference. Modes are different for narrowband and wideband, and are defined as follows:

"1,2,3,4,5,6,7,8,any" for narrowband
 

"0,1,2,3,4,5,6,7,8,9,10,any" for wideband and ultra-wideband

The internal default values are "3,any" for 8kHz narrow band and "8,any" for 16kHz wide band.


 

Return Value:

If the function succeeds, the return value will be SipSuccess.

If the function fails, the return value will be one of the following values as specified by the TELEPHONY_RETURN_VALUE data type.