ILMUDPSnk Interface

Show in webframe

This is the interface for the LEAD MPEG2 Transport UDP Sink filter.

Use this interface to monitor the performance of the LEAD MPEG2 Transport UDP Sink filter. You can use it to identify if the network connection is not keeping up with the amount of data being sent. There is usually little you can do to increase the throughput of the UDP sink, so it is recommended that you reduce the bitrate of the data being sent by increasing the video and audio compression.

Interface Properties:

Type

Name

Description

long

StatisticListLength

Determines the number of elements used to calculate the statistic averages. Each element represents one second. The default is 10 (so the averages are calculated for the last 10 seconds).

This property affects the way the averages returned by the GetStatistic method are calculated.

Interface Methods:

HRESULT ResetToDefaultsEx(LMUDPSnk_APILEVEL ApiLevel)

Parameters

ApiLevel

Specifies which defaults should be used by the filter.

Description

Resets the filter to default values. The ApiLevel parameter determines which default values to use. Current applications should set ApiLevel to LMUDPSnk_APILEVEL_1 = 0.

The filter might change in the future and have different properties or default behaviour. Calling this method ensures future versions of the filter will behave the same way as when you developed your application.

It is best to call ResetToDefaultsEx(LMUDPSnk_APILEVEL_1) before you start setting properties and start calling other methods for this interface.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

E_INVALIDARG

The ApiLevel parameter is invalid

HRESULT GetStatistic(LMUDPSnk_StatisticIndex index, double *pValue)

Parameters

index	The index of the statistic to be retrieved.
pValue	The value being retrieved. Cannot be NULL.

Description

Use this method to obtain statistical information regarding the performance of the filter. Use this method to monitor how much data is being sent and whether the network connection is keeping up with the amount of data you are trying to send.

If you see the filter is constantly waiting for data to be sent and that the buffers are almost full, then you might get better performance if you reduce the throughput by increasing the compression and reducing the frame rate of the data being sent.

This is especially true for network connections with a limited bandwidth (like a VPN). Attempting to stream too much data through a limited network produces poor results on the receiving end. The symptoms on the client side are corrupted video (when the data is sent using RTP or UDP packets), or slower than normal video (when the data is sent using TCP).

If you are experiencing any of these problems, the solution is to send less data.

At the moment, you can monitor 3 types of data:

Bitrate (in bits/second) of the stream, including the mpeg2 transport packets
Wait time (as a percentage) - how much time is spent waiting for data to be sent by the network. If this value is consistently above 80%, there is a good chance the bitrate is too high for your network connection.
Buffers used (as a percentage) - how much data is currently queued up, waiting to be sent. If this value is consistently above 50%, there is a good chance the bitrate is too high for your network connection.

Each of these values can be obtained for the last second or as an average of the last StatisticListLength seconds. For example:

LMUDPSnk_StatisticIndex_LastBitrate indicates the bitrate of the data sent in the last second.
LMUDPSnk_StatisticIndex_AvgBitrate indicates the bitrate of the data sent in the last StatisticListLength seconds.

Note that the UDP sink will not drop any data - instead, you can use this information to increase the compression of the data before it gets to the UDP sink. As a general rule, you can reduce the bitrate by decreasing the video bitrate and increasing the compression ratio. In general, you will have better results decreasing the frame rate, as 10fps smooth high quality video looks better than 30fps video that is blocky or jerky.

Returns

S_OK if successful, < 0 if an error occurred.

Common error codes:

E_INVALIDARG	The index parameter is invalid
E_POINTER	The pValue parameter is invalid (NULL).

Data Types:

LMUDPSnk_APILEVEL

typedef enum
{
LMUDPSnk_APILEVEL_1 = 0, // current version
} LMUDPSnk_APILEVEL;

Lists the valid values for the ApiLevel parameter that can be passed to the ResetToDefaultsEx method.

LMUDPSnk_StatisticIndex

Lists the possible statistical values that can be retrieved using the GetStatistic method.

typedef enum
{
   LMUDPSnk_StatisticIndex_LastBitrate = 1, // the number of bits sent in the last second
   LMUDPSnk_StatisticIndex_AvgBitrate,      // the average bitrate
   LMUDPSnk_StatisticIndex_LastWaitTime,    // the percentage of time spent waiting for data to be sent
   LMUDPSnk_StatisticIndex_AvgWaitTime,     // the average percentage of time spent waiting
   LMUDPSnk_StatisticIndex_LastBuffersUsed, // the percentage of buffers queued up
   LMUDPSnk_StatisticIndex_AvgBuffersUsed   // the average percentage of buffers in use
} LMUDPSnk_StatisticIndex;

Value	Description
LMUDPSnk_StatisticIndex_LastBitrate	[1] The number of bits sent in the last second.
LMUDPSnk_StatisticIndex_AvgBitrate	[2] The average bitrate (in bits/second) of data sent in the last StatisticListLength seconds.
LMUDPSnk_StatisticIndex_LastWaitTime	[3] The percentage of time spent in the last second waiting for data to be sent.
LMUDPSnk_StatisticIndex_AvgWaitTime	[4] The average percentage of the time spent waiting for data to be sent in the last StatisticListLength seconds. A value over 90 (corresponding to 90%) indicates the network connection is barely keeping up. A value of 0 can indicate nobody is listening (especially for TCP connections).
LMUDPSnk_StatisticIndex_LastBuffersUsed	[5] The percentage of the internal buffers filled with data waiting to be sent in the last second.
LMUDPSnk_StatisticIndex_AvgBuffersUsed	[6] The average percentage of the internal buffers filled with data waiting to be sent in the last StatisticListLength seconds. A value over 70 (corresponding to 70%) indicates the network connection is barely keeping up. A value of 0 can indicate nobody is listening (especially for TCP connections).