Voice encoder channel filter

Encodes voice data according to a particular encoding algorithm. Parameters within the encoder filter, such as payload ID, IP format, volume/gain, and DTMF/CED filter controls can be altered though filter commands. Encoder filter status information can be obtained through a filter query. For information about voice decoder filter parameters, refer to Voice channel parameter structures.

Filter ID

The following table lists some of the Fusion encoder filters:

Filter ID	Description	Frame size
MSP_FILTER_G711_ENCODER	G.711 64 kbit/s mu-law or A-law encoder with or without VAD	10 ms
MSP_FILTER_G723_ENCODER	G.723.1/A 6.4/5.3 kbit/s encoder with or without VAD	30 ms
MSP_FILTER_G726_ENCODER	G.726 32 kbit/s encoder without VAD	10 ms
MSP_FILTER_G729A_ENCODER	G.729A/B 8.0 kbit/s encoder with or without VAD	10 ms

Initialization structure

MSP_VOICE_CHANNEL_PARMS

Restrictions

Used in the full duplex voice or simplex voice encoder channels.

Filter connections

Allowable connections for voice encoder filters include:

Input

Output

MSP_ENDPOINT_DS0

MSP_ENDPOINT_PKTMEDIA

MSP_ENDPOINT_MONITOR

MSP_ENDPOINT_RTPFDX

MSP_ENDPOINT_RTPOUT

MSP_ENDPOINT_RTPFDX_V6

MSP_ENDPOINT_RTPOUT_V6

Commands

Voice encoder filters respond to the following commands when the associated channel is enabled:

Command ID	Description
MSP_CMD_ENCODE_DTMF_MODE	Specifies the mode in which the filter processes DTMF tones. The application concatenates a control value and a payload value to determine how this works. Defined values for control include: DTMF_DISABLED Inband DTMF carriage is not supported for the channel. The following values can be combined using the OR operator to specify encoder functionality: DTMF_INBAND_ENABLED (default) MSPP channel detects DTMF tones and transfers DTMF information though RFC 2833 compliant packets. DTMF_EVENTS_ENABLED MSPP channel detects DTMF tones and transfers DTMF information through MSPEVN_DPF_DTMF_REPORT events. DTMF_SHIFT_ENABLED If set, shifts the timestamp of associated DTMF RTP packets back to better align with the actual start of the DTMF detection. This allows for more synchronized decoder playout of RFC 2833 DTMF digits with respect to the actual DTMF occurrence. VOICE_ENABLED If DTMF_INBAND_ENABLED is set, the filter sends voice RTP packets as well as RFC 2833 compliant packets for the duration of the DTMF digit. The payload value (range 96-127, default 96) sets the payload ID for inband DTMF packets.
MSP_CMD_ENCODE_DTMFDETECT_PARMS	Modifies the DTMF detection parameters. Requires a pointer to msp_FILTER_ENCODE_DTMFDETECT_PARMS_CMD structure. For more information, refer to DTMF detection parameters.
MSP_CMD_ENCODE_PLAY_RFC2833	Plays RFC 2833 RTP packets as specified in the following fields: Event (WORD) : RFC 2833 event (0 - 255, refer to the RFC 2833 specification for details). Duration (WORD): Duration of the RFC 2833 event, in milliseconds.
MSP_CMD_ENCODE_MODE	Vocoding mode. Offline means that the encoder produces null media packet frames. Valid entries include: 0x0000: offline 0x0001: online Default is online.
MSP_CMD_ENCODE_GAIN	Gain value applied to the encoder filter input in S5.10 format. Default is 0 dB gain (refer to Calculating vocoder filter gain and loss for a table showing gain decibel values and the corresponding linear gain/loss values).
MSP_CMD_ENCODE_VAD	Enables or disables voice activity detection (VAD): 0x0000: VAD disabled 0x0001: VAD enabled Default is disabled.
MSP_CMD_ENCODE_SUPPRESS _FILTERS	Enables and/or disables DTMF/CED tone suppression filters. Valid values include: 0x0000: DTMF and CED notch filters disabled 0x0001: DTMF notch enabled, CED notch disabled 0x0002: DTMF notch disabled, CED notch enabled 0x0003: DTMF and CED notch filters enabled Default is 0x0000 (DTMF/CED suppression disabled).
MSP_CMD_ENCODE_IP_FORMAT	Specifies the companding algorithm applied to the IP payload (applies to G.711 encoder only): 0x0000: mu-law (for T1 systems) 0x0001: A-law (for E1 systems) Default matches system settings.
MSP_CMD_ENCODE_RATE	Vocoding rate. Legal values depend on the encoder. Currently, only G.723.1 supports variable rates. 0 specifies the highest bit rate setting. The bit rate decreases as settings are incremented by one. Therefore for G.723.1, 0 specifies 6.4 kbit/s and 1 specifies 5.3 kbit/s. If a 2 value is defined, it would specify a lower bit rate than 5.3 kbit/s.
MSP_CMD_ENCODE_PAYLOAD_ID	Assigns a payload ID for outgoing media frames. Valid range is 96 - 127. Refer to Vocoder filter attributes for default payload IDs.
MSP_CMD_ENCODE_ALL	Resets any or all of the encoder filter parameters.

Note: Voice encoder filters must be enabled when you send them commands.

Caution:

When you change the payload ID of the voice encoder filter, the receiving gateway must also change the payload ID for the associated voice decoder filter and RTP endpoint.

When sending commands to encoder filters, include a pointer to the following structure:

typedef struct tag_msp_FILTER_ENCODE_CMD {
WORD value;
} msp_FILTER_ENCODE_CMD;

Use the value field to specify a value for the specified command.

When sending MSP_CMD_ENCODE_ALL encoder commands, applications provide a pointer to an msp_FILTER_ENCODE_ALL_CMD structure. This structure contains all the parameters used to configure the encoder filter when the application created the voice channel.

When using the MSP_CMD_ENCODE_ALL command, applications can specify a value of 0xFFFF for 16-bit parameters or 0xFFFFFFFF for 32-bit parameters (or -1 in decimal format) to retain the existing settings for any voice encoder parameter. Otherwise, the MSPP service expects a new value for every parameter in the msp_FILTER_ENCODE_ALL_CMD structure.

The following table shows commands supported by available encoder filter (x = supported):

Encoder	Mode	Gain	VAD	Rate	DTMF/ CED control	Payload ID	IP format	DTMF mode
G.711	x	x	x	x	x	x	x	x
G.723.1	x	x	x	x	x	x		x
G.726	x	x			x	x	x	x
G.729A	x	x	x		x	x		x

For more information about MSPP service channel initialization and command parameters, refer to the mspcmd.h header file.

For a list of command IDs and their associated structures, refer to the mspinit.h header file.

Queries

Encoder filters respond to the following query when the associated channel is enabled:

Query ID	Description
MSP_QRY_ENCODE_STATUS	Returns information about the voice encoder filter state in an msp_FILTER_ENCODE_STATE structure.

Sending an MSP_QRY_ENCODE_STATUS query returns the following structure:

typedef struct tag_msp_FILTER_ENCODE_STATE
{
   DWORD  FilterId;
   WORD   CommandEcho;
   WORD   State;
   WORD   Gain;
   WORD   VadControl;
   WORD   Rate;
   WORD   PayloadID;
   WORD   IPFormat;
   WORD   NotchControl;
   WORD   DtmfMode;
   WORD   DSPId;
   WORD   ActiveCnt;
   WORD   SIDCnt;
   WORD   NullCnt;
   WORD   DtmfCnt;
   WORD   DSOutQFullCnt;
} msp_FILTER_ENCODE_STATE;

The returned query structure provides the following information:

Field	Description
Filterid	Filter ID of the encoder filter.
CommandEcho	Returns the filter command to the encoder filter (0x10).
State	Encoder filter state (online/offline).
Gain	Encoder filter gain.
VadControl	VAD control parameter (enabled or disabled).
Rate	Rate of encoded speech (valid only for encoders that support multiple rates). Vocoding rate. Legal values depend on the encoder. Currently, only G.723.1 supports variable rates (where the default is 0 or 6.4 kbit/s). 0 specifies the highest bit rate setting. The bit rate decreases as settings are incremented by one. Therefore for G.723.1, 0 specifies 6.4 kbit/s and 1 specifies 5.3 kbit/s. If a 2 value is defined, it specifies a lower bit rate than 5.3 kbit/s.
PayloadID	Payload ID of outgoing media.
IPFormat	IP format of outgoing G.711 or G.726 media (A-law/mu-law).
NotchControl	DTMF/CED suppression filter parameters.
DtmfMode	Specifies whether or not the encoder is sending DTMF tone information in RFC 2833 compliant packets.
DSPId	DSP number where encode filter resides.
ActiveCnt	Number of active data packets sent.
SIDCnt	Number of SID data packets sent.
NullCnt	Number of null data packets sent.
DtmfCnt	Number of RFC 2833 compliant packets sent.
DSOutQFullCnt	Number of times the encoder filter had no place to output data.

Not all fields are applicable to all encoder filters. Fields that do not apply to a particular filter will return a value that indicates that they do not support it.

Unsolicited events

Voice encoder filters generate the following unsolicited event when the DtmfMode parameter is set:

Event	Description
MSPEVN_DPF_DTMF_REPORT	Returned when the encoder detects a DTMF tone on an incoming data stream.

Details

To create a full-duplex vocoded voice path for a given channel, applications combine voice encoder filters and voice decoder filters within individual channels. The encoder types and the decoder types do not have to match. Applications can also create simplex channels by using decoders without encoders or vice versa.

Voice encoder filters accept PCM signal data and produce a compressed representation of that data. The compressed data is prefixed by a header and sent to a packet engine (RTP endpoint). On CG boards, the packet engine forms an Ethernet/IP/UDP packet from one or more payloads and transmits the fully formed packet to the Ethernet.

The following frequency suppression functions are available for voice encoder filters (these are enabled and disabled through the MSP_CMD_ENCODE_SUPPRESS_FILTERS filter command):

Function	Description
DTMF suppression	Eliminates the high group of DTMF frequencies to help implement DTMF carriage in voice over IP applications.
CED tone suppression	Eliminates the facsimile CED 2100 Hz tone for fax over IP applications. This filter is designed to prevent the 2100 Hz CED tone from reaching the originating end fax machine.

Both tone detection functions are disabled by default, but can be enabled or disabled on the fly. Because the DTMF suppression function suppresses only the high group of DTMF frequencies, callers can still hear the low group of DTMF frequencies on the line.

When using G.723 voice encoder filters, it may be desirable to set the RTP assembler filter's frames-per-packet to 1 to reduce latency. Since G.723 vocoder filters produce frames in 30 ms intervals, setting frames-per-packet to 1 reduces latency by 30 ms.

Caution:

Avoid setting the RTP endpoint frames-per-packet quota to less than 2 when using any encoder filter but G.723.1. Setting the frame quota to less than 2 can exceed the CG board's processing abilities and cause dropped packets. This is because all Fusion encoder filters except G.723.1 produce frames in 10 ms intervals.

Applications can load any mix of encoders and decoders on a CG board within the constraints of CG resource management.

The following illustration shows a voice encoder filter:

DTMF detection parameters

When an encoder is enabled, its dtmf detector parameters are set to default values. The values can be modified by sending an MSP_CMD_ENCODE_DTMFDETECT_PARMS command to the filter while it is enabled. The command must be accompanied by a pointer to the msp_FILTER_ENCODE_DTMFDETECT_PARMS_CMD structure.

All values must be set. Note that there is no capability to query the settings. The initial values that are set when the filter is enabled are shown below.

typedef struct tag_msp_FILTER_ENCODE_DTMFDETECT_PARMS_CMD
{
  WORD columnfour;    // 1=detect DTMFs A,B,C,D; 0=don't
  WORD onqualampl;    // min input lev to qual tone
  WORD onthreshold;   // Talkoff versus Cutthrough qualify level
  WORD onqualtime;    // qualify time of DTMF
  WORD offqualampl;   // min input lev of valid DTMF
  WORD offthreshold; // Hysteresis for talkoff versus cutthrough
  WORD offqualtime;   // disqualify time for tone (ms)
} msp_FILTER_ENCODE_DTMFDETECT_PARMS_CMD;

Field values are in proprietary units. The following table describes the conversion from dB or milliseconds, and the useful range of values for each field.

Field	Default	Min	Max	Equivalent	Min	Max	Notes
columnfour	1	0	1
onqualampl	504	128	16000	-39 dBm0	-51	-9	Linear scale where 0 dBm0 is 45632.
onthreshold	276	173	347	-2.0 dB	-6.0	0	Linear scale where 0 dB is 347.
onqualtime	28	0	32767	50 ms	22	32789	Time in milliseconds minus 22.
offqualampl	252	128	16000	-45 dBm0	-51	-9	Linear scale where 0 dBm0 is 45632.
offthreshold	200	173	347	-4.8 dB	-6.0	0	Linear scale where 0 dB is 347.
offqualtime	35	0	32767	40 ms	5	32772	Time in milliseconds minus 5.

Use the following formula to convert dB input values to linear:

linear= 10**(dB/20) * <0 dB value>

For example, using 'C' code:

    int dBm0 = -39;
    unsigned onqualampl = pow (10, (double)dBm0/20) * 45632;

    double dB = -2.0
    unsigned onthreshold = pow (10, dB/20) * 347;

    int msec = 50;
    unsigned onqualtime = msec - 22;

By comparison, the ADI dtmf detector API (adiStartDTMF) performs the above conversions for qualification amplitude and time, but not for the threshold values. You can convert ADI values for offthreshold and onthreshold by dividing by 188.

Example

The default value of ADI.DTMFDETECT.onthreshold is 0xcab0 or 51888. The equivalent encoder value is 51888/188 = 276.