# Voice decoder channel filter

Decodes voice data according to a particular algorithm. Parameters within the decoder filter, such as payload ID, IP format and gain, can be altered through filter commands. Decoder filter status information can also be obtained through filter queries. For information about voice encoder filter parameters, refer to Voice channel parameter structures.

#### Filter ID

The following table lists some of the Fusion decoder filters:

Filter ID | Description | Frame size
MSP_FILTER_G711_DECODER | G.711 64 kbit/s mu-law or A-law decoder | 10 ms
MSP_FILTER_G723_DECODER | G.723.1/A 6.4/5.3 kbit/s decoder | 30 ms
MSP_FILTER_G726_DECODER | G.726 32 kbit/s decoder | 10 ms
MSP_FILTER_G729_DECODER | G.729A/B 8.0 kbit/s decoder | 10 ms

#### Initialization structure

MSP_VOICE_CHANNEL_PARMS

#### Restrictions

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

#### Filter connections

Allowed connections for voice decoder filters include:

Input | Output
MSP_FILTER_JITTER | MSP_ENDPOINT_DS0

#### Commands

Enabled voice decoder filters respond to the following commands when the associated channel is enabled:

Command ID | Description
MSP_CMD_DECODE_MODE | Vocoding mode. Off-line means that the decoder filter plays silence to the DS0 endpoint. 0x0000: off line 0x0001: online Default is online.
MSP_CMD_DECODE_DTMF_MODE | Specifies if and how the decoder filter plays DTMF tones when it receives DTMF data (only when inband DTMF carriage is enabled). The application concatenates a control value and a playout value to determine how this works. Defined values for control include: DTMF_DISABLED MSPP channel does not play a DTMF tone when it receives an RFC 2833 compliant inband DTMF carriage packet. The following values can be ORed to specify decoder functionality: DTMF_INBAND_ENABLED MSPP channel automatically plays a DTMF tone when it detects an RFC 2833 compliant inband DTMF carriage packet. This setting is enabled by default. DTMF_PLAY_ENABLED MSPP channel plays DTMF tones when the application sends an MSP_CMD_DECODE_PLAY_DTMF_DIGIT command. The playout value is an integer that specifies number of decoder frames for an ongoing tone to continue when no end-of-tone packet is received.
MSP_CMD_DECODE_PLAY_DTMF_DIGIT | Commands the voice decoder filter to play a specified DTMF digit.
MSP_CMD_DECODE_GAIN | Gain value applied to the decoder filter output in S5.10 format. Default is 0x0400 (0 dB). Refer to Calculating vocoder filter gain and loss for a mapping of decibel gain/loss values to linear gain/loss values.
MSP_CMD_DECODE_IP_FORMAT | Specifies the companding algorithm applied to the IP payload (applies to G711 decoder only): 0x0000: mu-law (for T1 systems) 0x0001: A-law (for E1 systems) Default matches system settings.
MSP_CMD_DECODE_PAYLOAD_ID | Assigns a payload ID for incoming Fusion media frames. Valid range is 96 - 127. Refer to Vocoder filter attributes for a list of default payload IDs.
MSP_CMD_DECODE_SILENCE_CODE | Specifies the silence pattern sent out by the decoder: 0 – 0xFF (X-law independent) 1 – 0x10 (X-law independent) This command is supported only by the G.711 decoder. All other decoders respond with FUNCTION_NOT_IMPLEMENTED.
MSP_CMD_DECODE_ALL | Resets any or all of the decoder filter parameters.

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

Caution: | When you change the payload ID of the voice decoder filter, you must also change the payload ID to the same value for the associated RTP endpoint. The voice encoder at the sending gateway must also match this payload ID.

The following table summarizes the commands that available decoder filters support (x = supported):

Decoder | Mode | Gain | IP format | Payload ID | Query | Play DTMF | DTMF mode | Silence code
G.711 | x | x | x | x | x | x | x | x
G.723.1 | x | x |  | x | x | x | x |
G.726 | x | x | x | x | x | x | x |
G.729A | x | x | x | x | x | x | x |

When sending commands (except for MSP_CMD_DECODE_ALL commands) to decoder filters, include a pointer the following structure:

typedef struct tag_msp_FILTER_DECODE_CMD {
WORD value;
} msp_FILTER_DECODE_CMD;

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

When sending MSP_CMD_DECODE_ALL decoder commands, applications provide a pointer to an msp_FILTER_DECODE_ALL_CMD structure. This structure contains all of the parameters used to configure the decoder filter when the application created the voice channel.

When using the MSP_CMD_DECODE_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 decoder parameter. Otherwise the MSPP service expects a new value for every parameter in the msp_FILTER_DECODE_ALL_CMD structure. For more information about decoder filter 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

Voice decoder filters respond to the following queries when the associated channel is enabled:

- MSP_QRY_SILENCE_CODE
  Returns the configured silence pattern for the decoder in an msp_FILTER_SILENCE_CODE structure.
  This query is supported only by the G.711 decoder. All other decoders respond with FUNCTION_NOT_IMPLEMENTED.
  Sending an MSP_QRY_SILENCE_CODE query returns the following structure:

typedef struct tag_msp_FILTER_SILENCE_CODE {
DWORD FilterId;
WORD CommandEcho;
WORD SilenceCode;
} msp_FILTER_SILENCE_CODE;

The returned query structure provides the following information:

Field | Description
FilterID | Filter ID of the specific decoder filter.
CommandEcho | Return of the query command (0x12).
SilenceCode | Decoder silence pattern (0xFF / 0x10).

- MSP_QRY_DECODE_STATUS
  Returns information about the decoder filter state in an msp_FILTER_DECODE_STATE structure.
  Sending an MSP_QRY_DECODE_STATUS query returns the following structure:

typedef struct tag_msp_FILTER_DECODE_STATE{
DWORD FilterId;
WORD CommandEcho;
WORD State;
WORD Gain;
WORD Rate;
WORD PayloadID;
WORD IPFormat;
WORD DtmfMode;
WORD DSPId;
WORD ActiveCnt;
WORD SIDCnt;
WORD NullCnt;
WORD DtmfCnt;
WORD InvalidPktCnt;
WORD DSInQEmptyCnt;
WORD DSInQExtraCnt;
} msp_FILTER_DECODE_STATE;

The returned query structure provides the following information:

Field | Description
FilterID | Filter ID of the specific decoder filter.
CommandEcho | Return of the query command (0x10).
State | Decoder filter state (online/off line).
Gain | Decoder filter gain.
Rate | Decoder rate.
PayloadId | Expected payload ID of incoming data.
IpFormat | Expected IP format of incoming data (G.711 and G.726 only).
DtmfMode | Whether the voice decoder plays DTMF tones as a result of RFC 2833 compliant packets.
DSPId | DSP number where decoder filter resides.
ActiveCnt | Number of active data packets received.
SIDCnt | Number of SID data packets received.
NullCnt | Number of null data packets received.
DtmfCnt | Number of inband DTMF packets received.
InvalidPktCnt | Number of invalid data packets received.
DSInQEmptyCnt | Number of times the decoder filter received no data.
DSInQExtraCnt | Number of times the decoder filter received more than one data packet.

#### Unsolicited events

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

Event | Description
MSPEVN_DPF_DTMF_PLAY_END | When the application commands the decoder to generate a DTMF tone (with the MSP_CMD_DECODE_PLAY_DTMF_DIGIT command), this event signals that the DTMF tone was generated.

#### Details

This filter accepts data from a jitter filter, decodes and expands the compressed data, and outputs the resultant PCM signal data to a DS0 endpoint.

Full-duplex voice channels combine voice encoder filters and voice decoder filters to create a two way flow of data. Simplex send channels use voice decoder filters, but without a matching voice encoder filter.

Encoder types and decoder types within a channel do not have to match. Applications can create duplex channels by creating pairs of simplex voice channels that use different vocoding algorithms. For more information about creating this kind of asymmetrical duplex connection, refer to Connecting simplex and duplex channels. Applications can load any mix of encoders and decoders on a CG board (within the constraints of CG board resource management).

The following illustration shows a decoder filter:

#### See also

DS0 full duplex, Jitter, RTP IPv4 full duplex, RTP IPv4 simplex receive, RTP IPv6 full duplex, RTP IPv6 simplex receive, Voice encoder