# Jitter channel filter

Receives asynchronous packets and processes them to produce an ordered synchronous output. For information about jitter filter parameters, refer to Voice channel parameter structures.

#### Filter ID

MSP_FILTER_JITTER

#### Initialization structure

MSP_VOICE_CHANNEL_PARMS

#### Restrictions

Used in full duplex voice channels and simplex voice decoder channels.

#### Filter connections

Valid filter connections include:

Input filters | Output filters
MSP_ENDPOINT_RTPFDX MSP_ENDPOINT_RTPIN MSP_ENDPOINT_RTPFDX_V6 MSP_ENDPOINT_RTPIN_V6 | Voice decoder

#### Commands

Jitter filters respond to the following commands when the associated channel is created:

Command ID | Description | Units | Default
MSP_CMD_JITTER_CHG_DEPTH | Changes jitter depth (default is 2 frames). | Vocoder frames per packet | 2
MSP_CMD_JITTER_CHG_ADAPT | Enables or disables the adaptive mode for the jitter filter. Default is disabled. | 0 = disable 1 = enable | 0 (disabled)
MSP_CMD_JITTER_INIT | Changes any or all jitter filter parameters. | N/A | N/A

When sending MSP_CMD_JITTER_CHG_DEPTH or MSP_CMD_JITTER_CHG_ADAPT jitter filter commands, provide a pointer to the following structure:

typedef struct tag_msp_FILTER_JITTER_CMD {
DWORD value;
} msp_FILTER_JITTER_CMD;

The value field contains the new depth or the adaptive mode flag, according to the command. The following constant is defined for jitter commands:

Constant | Description | Value
MSP_JITTER_DEPTH_BOARD_LIMIT | Maximum jitter depth (in vocoder frames) for the jitter depth command. Note: MSP_CONST_JITTER_DEPTH_MAX (16) is the maximum recommended value for voice gateways, and is the recommended value for DCE transport. | 100

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

When using the MSP_CMD_JITTER_INIT 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 jitter parameter. Otherwise, the MSPP service expects a new value for every parameter in the msp_FILTER_JITTER_CMD_INIT structure. For more information about jitter filter parameters, refer to the mspcmd.h file.

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

Jitter filters can receive commands only after the channel has been connected.

#### Queries

Jitter filters respond to the following query when the associated channel is connected:

Query ID | Description
MSP_QRY_JITTER_GET_STATE | Retrieves information about the jitter filter state. This information is returned in an msp_FILTER_JITTER_STATE structure.

The msp_QRY_JITTER_GET_STATE query structure is defined as follows:

typedef struct tag_msp_FILTER_JITTER_STATE {
DWORD filter_id;
DWORD rx;
DWORD rx_accept;
DWORD tx;
DWORD tx_valid;
DWORD requested_depth;
DWORD actual_depth;
DWORD remote_frame_duration;
DWORD underflows;
DWORD overflows;
DWORD lost_pkts;
DWORD duplicate_frames;
DWORD reordered_frames;
DWORD rejected_frames;
DWORD dtmf_frames;
DWORD combined_frames;
DWORD adapt_enabled;
DWORD discarded_frames;
DWORD average_depth;
} msp_FILTER_JITTER_STATE;

The msp_QRY_JITTER_GET_STATE query structure returns the following information:

Field | Description
filter_id | Reserved.
rx | Number of frames received (before validation).
rx_accept | Number of validated frames received.
tx | Number of frames transmitted (before validation).
tx_valid | Number of validated frames transmitted.
requested_depth | Requested value for the nominal size of the internal queue of this filter. Units are frames. May differ from actual_depth.
actual_depth | Number of frames currently in the jitter filter's internal queue.
remote_frame_duration | Frame size (in milliseconds) of the remote encoder.
underflows | Number of times output occurred when the internal queue was empty.
overflows | Number of packets received that would not fit into the jitter filter's internal queue.
lost_pkts | Number of frames missing at time of output.
duplicate_frames | Number of duplicate frames received.
reordered_frames | Number of frames received out of order.
rejected_frames | Number of frames rejected for any reason.
dtmf_frames | Number of dtmf frames received.
combined_frames | Number of combined frames received.
adapt_enabled | Indicates whether adaptive jitter mode is enabled (1) or disabled (0).
discarded_frames | Number of frames discarded in order to minimize the average jitter depth (adaptive jitter mode only).
average_depth | Average jitter depth value over the previous 5 seconds (adaptive jitter mode only). The displayed value is 100 x the actual value. For example a value of 150 indicates an average jitter depth of 1.5 frames.

#### Unsolicited events

None.

#### Details

This filter restores frame ordering and smooths jitter in packet media streams.

Applications use the jitter filter as one part of a simplex or duplex connection (the decode path) from a unique address in an IP network (UDP) to a circuit in a PSTN network. The Jitter accepts frames as its input, which can be out-of-sequence or affected by jitter, and outputs frames in the correct order with reduced jitter. Adjacent frames in the output are spaced by an interval. This interval is determined by the voice decoder in the RTP endpoint, not the jitter filter.

Reordering occurs as the received frames are queued. This queue may underflow (go empty) or overflow because of congestion or bursts from the IP network. Packets that overflow the queue are dropped.

When a voice channel disassembles compound packets (that contain multiple frames per packet), the application must set the jitter depth to greater than or equal to the number of frames per packet. Otherwise, packets are lost and the sound quality may deteriorate.

Jitter depth refers to the number of frames held in the filter queue while the filter performs frame reordering. Applications can send commands to the jitter filter to change its jitter depth. Raising the jitter depth allows the jitter filter to reorder frames more efficiently but also increases the amount of latency introduced into the voice data stream. The application must use a jitter depth that achieves the best balance between efficiency and latency.

When the application enables adaptive mode for the jitter filter, the jitter filter automatically adjusts its jitter depth to the average number of frames required over the previous five seconds. Every five seconds the filter adjusts the jitter depth by raising or lowering the number of frames kept in the filter's internal queue.

Jitter filter commands control the following characteristics:

Jitter characteristic | Description
Jitter depth | The size (in frames) of the internal queue maintained by a jitter filter. Jitter depth represents a threshold. A jitter filter holds frames in the queue (and does not transmit them) until it accumulates the number of frames specified by the jitter depth. While holding the frames, the jitter filter transfers null frames with empty payloads. Once the number of frames specified by the jitter depth has accumulated, the output function draws from the queue at the rate defined by the vocoder type. In a network with minimal delay or no delay, the number of packets in the jitter queue remains constant. However, if a packet network experiences delays greater than the depth of the jitter queue, the jitter queue may empty. If this occurs, the jitter filter again begins producing null frames while waiting for the specified jitter depth to be reached. Null packets are also produced for missing packets. Null packets are also produced for missing packets.
Adaptive jitter | Automatically and dynamically sets the jitter filter depth according to the frequency with which the jitter filter is receiving frames. For example, if the jitter buffer is receiving an average of six frames per vocoder interval (for example, every 10 ms) over the last five seconds, it adjusts the current size of the jitter queue to 6. When the application enables adaptive jitter (disabled by default), the jitter buffer automatically increases or decreases the number of frames in the jitter depth according to the number of frames received in the previous five seconds.

The requested_depth parameter has a different meaning depending on the adapt_enabled setting. When adaptive jitter is disabled, this parameter indicates the nominal size of the internal queue of the jitter filter. When adaptive jitter is enabled, the requested_depth parameter indicates the current target depth for the jitter queue (rather than the actual number of frames in the queue).

The following illustration shows the position of a jitter filter in a voice channel:

#### See also

DS0 full duplex, RTP IPv4 full duplex, RTP IPv4 simplex receive, RTP IPv6 full duplex, RTP IPv6 simplex receive, Voice decoder