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: