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.

Namespace:  LanScape
Assembly:  LMEVoipManaged (in LMEVoipManaged.dll) Version: 6.0.5226.26700

Syntax

C#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetSpeexCodecParameters(
	int PhoneLine,
	int Bandwidth,
	int DefaultEncoderMode,
	int EncoderComplexity,
	string DecodingModes
)
Visual Basic (Declaration)
Public Function SetSpeexCodecParameters ( _
	PhoneLine As Integer, _
	Bandwidth As Integer, _
	DefaultEncoderMode As Integer, _
	EncoderComplexity As Integer, _
	DecodingModes As String _
) As VoipMediaEngine..::.TELEPHONY_RETURN_VALUE
Visual C++
public:
VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetSpeexCodecParameters(
	int PhoneLine, 
	int Bandwidth, 
	int DefaultEncoderMode, 
	int EncoderComplexity, 
	String^ DecodingModes
)
J#
public VoipMediaEngine..::.TELEPHONY_RETURN_VALUE SetSpeexCodecParameters(
	int PhoneLine,
	int Bandwidth,
	int DefaultEncoderMode,
	int EncoderComplexity,
	String DecodingModes
)

Parameters

PhoneLine
Type: System..::.Int32
The zero based telephony engine phone line that will have its settings changed.
Bandwidth
Type: System..::.Int32
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
Type: System..::.Int32
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:


ModeSpeex QualityBit-Rate (8kHz Narrow Band)
1 0 2.15 kbit/s
2 2 5.95 kbit/s
3 3 or 4 8.00 kbit/s
4 5 or 6 11.0 kbit/s
5 7 or 8 15.0 kbit/s
6 9 18.2 kbit/s
7 10 24.6 kbit/s
8 1 3.95 kbit/s


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:

ModeSpeex QualityBit-Rate(16kHz Wide Band)Bit-Rate (32kHz Ultra Wide Band)
0 0 3.95 kbit/s 5.75 kbit/s
1 1 5.75 kbit/s 7.55 kbit/s
2 2 7.75 kbit/s 9.55 kbit/s
3 3 9.80 kbit/s 11.6 kbit/s
4 4 12.8 kbit/s 14.6 kbit/s
5 5 16.8 kbit/s 18.6 kbit/s
6 6 20.6 kbit/s 22.4 kbit/s
7 7 23.8 kbit/s 25.6 kbit/s
8 8 27.8 kbit/s 29.6 kbit/s
9 9 34.2 kbit/s 36.0 kbit/s
10 10 42.2 kbit/s 44.0 kbit/s


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



EncoderComplexity
Type: System..::.Int32
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.


DecodingModes
Type: System..::.String
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 VoipMediaEngine..::.TELEPHONY_RETURN_VALUE data type.

Return ValueDescription
SipCallFailure
This value is returned by telephony API procedures to indicate general API failure. This error value is used as a "catch all error". If you receive this error, check to make sure that all parameters specified in the API procedure call are correct. Particularly, verify that pointers to memory regions are valid. This error return value is only used if a mapping to another specific error value does not exist.

(API return value)

SipInvalidHandle
Application software specified an invalid telephony handle in one of the API procedures. This usually indicates memory corruption on the part of application software.

(API return value)

SipBadPhoneLine
Application software called a telephony API procedure and specified an invalid phone line. Phone lines are numbered starting from zero. This error is most commonly returned when attempting to access phone lines in excess of the max number of lines supported by the telephony engine.

(API return value)

SipBadParameter
One of the telephony API procedures was called by application software and was passed a pointer to an invalid memory address. Normally this error will occur when application software passes NULL pointer values to the telephony API. For managed code applications, you should never see this error unless your process space has exhausted memory.

(API return value)

Remarks

None.

See Also