Managing the video jitter buffer

You can do all of the following to manage the video jitter buffer:

• Set the jitter buffer latency

• Query the jitter buffer state

• Remove excess video packets from the jitter buffer

• Purge the jitter buffer

• Respond to an MSPEVN_REACH_VIDEOLATENCY_LIMIT event

Setting the video jitter buffer latency

Note: This feature is for MPEG-4, H.263, and H.264 channels. The example shown is for H.263.

You can set the video jitter buffer latency to any value less than 2000 ms (2 seconds). To set the video jitter buffer latency, send the MSP_CMD_JITTER_CHG_VIDEO_LATENCY the CG board.

The MSP_CMD_JITTER_CHG_VIDEO_LATENCY command uses the msp_FILTER_JITTER_VID_LATENCY structure to set the jitter buffer latency value.

For more information, see Creating and sending MSPP commands. and msp_FILTER_JITTER_VID_LATENCY.

The following event can be returned:

Example

The following example shows how to change the jitter video latency:

msp_FILTER_JITTER_VID_LATENCY  jitter_vid_latncy;
MSPHD hObject;
jitter_vid_latncy.value = H2NMS_DWORD(vid_latency); //vid_latency is the value in mSec
if((ret = mspSendCommand( hObject, mspBuildCommand(MSP_FILTER_JITTER_VIDEO_H263,
    MSP_CMD_JITTER_CHG_VIDEO_LATENCY),(void*)&jitter_vid_latncy, sizeof(jitter_vid_latncy) ))
    != SUCCESS )
{
printf("mspSendCommand() failed with  ret=%x", ret);
return FAILURE;
}
expectedEvent = (MSPEVN_SENDCOMMAND_DONE |
    MSP_CMD_JITTER_CHG_VIDEO_LATENCY);
if (WaitForSpecificEvent(gw,  CtaQueueHd, expectedEvent, &event) != 0)
printf("\n\tERROR: mspSendCommand failed to send valid completion event\n");

Querying the video jitter buffer state

Note: This feature is for MPEG-4, H.263, and H.264 channels. The example shown is for H.263.

You can query the video jitter buffer filter, before or after you change the latency value.

To query the video jitter buffer, create the MSP_QRY_JITTER_VIDEO_GET_STATE query, and send it to the CG board. The MSP_QRY_JITTER_VIDEO_GET_STATE query uses the msp_FILTER_JITTER_VIDEO_STATE structure to display parameters for the jitter buffer.

For more information, see Creating and sending MSPP queries and msp_FILTER_JITTER_VIDEO_STATE.

The following events can be returned:

Example

The following example shows how to query the video jitter filter:

DWORD l_nVideoFilterType;
DWORD query 
l_nVideoFilterType = MSP_FILTER_JITTER_VIDEO_H263;
query = mspBuildQuery(l_nVideoFilterType, MSP_QRY_JITTER_VIDEO_GET_STATE);
if (mspSendQuery(ephd, query) != SUCCESS)
    printf("\n\t ERROR: mspSendQuery failed.\n");
expectedEvent = (MSPEVN_QUERY_DONE | MSP_QRY_JITTER_VIDEO_GET_STATE);
if (WaitForSpecificEvent(gw, ctaQueueHd, expectedEvent, &pevent) != 0)
    printf("\n\tERROR: mspSendQuery failed to send valid completion event\n");     
printf("\n pktsReceived = %8d, pktsAccepted = %8d, pktsRejected = %8d,
lates  = %8d, pktsLost = %8d, pktsCurrent  = %8d,  overflows    = %8d,
underflows   = %8d, duplicates = %8d, reorders  = %8d, jitterBufDelay  = %8d milliSec,
configuredLatency = %8d milliSec, h264AggPkts  = %8d, h264FragPkts = %8d, pktsDiscarded = %8d",
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->pktsReceived  ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->pktsAccepted  ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->pktsRejected  ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->lates         ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->pktsLost      ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->pktsCurrent   ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->overflows     ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->underflows    ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->duplicates    ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->reorders      ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->jitterBufDelay),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))->configuredLatency),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))-> h264AggPkts  ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))-> h264FragPkts ),
NMS2H_DWORD(((msp_FILTER_JITTER_VIDEO_STATE*)(pevent->buffer))-> pktsDiscarded ));
mspReleaseBuffer(ctaQueueHd, pevent.buffer);

Removing excess video packets from the video jitter buffer

Note: This feature is for MPEG-4, H.263, and H.264 channels. The example shown is for H.263.

You can remove the excess video packets that accumulate above the configured latency in the video jitter buffer. The data for the configured latency duration remains in the video jitter buffer after you remove the excess video packets.

Procedure

To remove excess video packets from the video jitter buffer, create the MSP_CMD_JITTER_NORMALIZE_VIDEO_LATENCY_BUF command, and send it to the CG board.

For more information, see Creating and sending MSPP commands.

The following event can be returned:

Example

The following example shows how to remove excess video packets from the video jitter buffer:

MSPHD hObject;
if((ret = mspSendCommand( hObject, mspBuildCommand(MSP_FILTER_JITTER_VIDEO_H263,
MSP_CMD_JITTER_NORMALIZE_VIDEO_LATENCY_BUF ),
(void*)0, 0 )) != SUCCESS )
{
printf("mspSendCommand() failed with  ret=%x", ret);
return FAILURE;
}
expectedEvent = (MSPEVN_SENDCOMMAND_DONE |
    MSP_CMD_JITTER_NORMALIZE_VIDEO_LATENCY_BUF);
if (WaitForSpecificEvent(gw,  CtaQueueHd, expectedEvent, &event) != 0)
printf("\n\tERROR: mspSendCommand failed to send valid completion event\n");

Purging the video jitter buffer

Note: This feature is for MPEG-4, H.263, and H.264 channels. The example shown is for H.263.

Purging the video jitter buffer removes all data regardless of the configured video jitter buffer latency value.

To purge the video jitter buffer, create the MSP_CMD_JITTER_PURGE_VIDEO_LATENCY_BUF command, and send it to the CG board.

For more information, see Creating and sending MSPP commands.

The following events can be returned:

Example

The following example shows how to purge the video jitter buffer:

MSPHD hObject
if((ret = mspSendCommand( hObject, mspBuildCommand(MSP_FILTER_JITTER_VIDEO_H263,
MSP_CMD_JITTER_PURGE_VIDEO_LATENCY_BUF ),
(void*)0, 0 )) != SUCCESS )
{
printf("mspSendCommand() failed with  ret=%x", ret);
return FAILURE;
}
expectedEvent = (MSPEVN_SENDCOMMAND_DONE |
    MSP_CMD_JITTER_PURGE_VIDEO_LATENCY_BUF);
if (WaitForSpecificEvent(gw,  CtaQueueHd, expectedEvent, &event) != 0)
printf("\n\tERROR: mspSendCommand failed to send valid completion event\n");

Responding to an MSPEVN_REACH_VIDEOLATENCY_LIMIT event

Note: This feature is for MPEG-4, H.263, and H.264 channels.

When the total accumulated jitter buffer delay exceeds the allowed threshold for latency, the jitter buffer automatically sends an MSPEVN_REACH_VIDEOLATENCY_LIMIT unsolicited event to the application. The time-delay threshold for MSPEVN_REACH_VIDEOLATENCY_LIMIT events is 500 ms. Therefore, if the commanded latency is 300 ms, the jitter buffer generates an MSPEVN_REACH_VIDEOLATENCY_LIMIT event when the total delay in the jitter buffer is 800 ms.

MSPEVN_REACH_VIDEOLATENCY_LIMIT events notify the application that there may be enough delay in the jitter buffer to affect media synchronization. In response to these events, applications can:

• Monitor the overall delay with occasional queries to the jitter buffer using the MSP_QRY_JITTER_VIDEO_GET_STATE query.

• Remove excess packets with the MSP_CMD_JITTER_NORMALIZE_VIDEO_LATENCY_BUF command.

• Purge the jitter buffer with the MSP_CMD_JITTER_PURGE_VIDEO_LATENCY_BUF command.

• Take no action at all.

After the jitter buffer generates an MSPEVN_REACH_VIDEOLATENCY_LIMIT event, it cannot generate another MSPEVN_REACH_VIDEOLATENCY_LIMIT event until one of the following conditions occurs:

• Application issues a purge command for the jitter buffer

• Jitter buffer detects a source change in the incoming bit stream

• Jitter buffer encounters an overflow condition

Any of these conditions enables the jitter buffer to send another MSPEVN_REACH_VIDEOLATENCY_LIMIT event to the application when the delay threshold is exceeded.