# 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.

#### See Also

Jitter, RTP IPv4 full duplex, RTP IPv4 simplex send, RTP IPv6 full duplex, RTP IPv6 simplex send, Voice decoder