Network Speed Testing

Introduction

ZEGO provides network speed testing functionality, which can be used to detect whether the network environment is suitable for publishing/playing streams with specified bitrates.

When the uplink speed test result shows a high packet loss rate, it is recommended to use methods such as lowering resolution or reducing frame rate to lower the publishing bitrate to ensure normal publishing; when the current speed test result shows a high packet loss rate, it is recommended to use the Video Encoding - Tiered Video Encoding feature provided by the SDK to pull streams with lower bitrate to ensure normal playing.

Developers may encounter the following situations in their business, for which ZEGO recommends using the SDK's network speed testing functionality:

• In call scenarios, network quality assessment is required.
• In education scenarios, pre-class network testing is required.
• In live streaming scenarios, network connection speed testing is required.

Prerequisites

Before implementing network speed testing functionality, please ensure:

• The ZEGO Express SDK has been integrated in your project and basic real-time voice functionality has been implemented. For details, please refer to Quick Start - Integration and Quick Start - Implementing Flow.
• A project has been created in the ZEGOCLOUD Console and a valid AppID and AppSign have been obtained.

Usage Steps

Listen for Network Speed Test Callbacks

Before starting the speed test, relevant speed test callbacks can be set first.

During the speed test, when an error occurs, the onNetworkSpeedTestError callback will be triggered. In normal speed test cases, network speed quality update will trigger the onNetworkSpeedTestQualityUpdate callback.

• Interface prototype:

virtual void onNetworkSpeedTestError(int errorCode, ZegoNetworkSpeedTestType type)
{
    printf("onNetworkSpeedTestError errorCode=%d type=%d", errorCode, type);
}

virtual void onNetworkSpeedTestQualityUpdate(const ZegoNetworkSpeedTestQuality& quality, ZegoNetworkSpeedTestType type)
{
    printf("onNetworkSpeedTestQualityUpdate rtt=%d packetLostRate=%f connectCost=%d type=%d", quality.rtt, quality.packetLostRate, quality.connectCost, type);
}

virtual void onNetworkSpeedTestError(int errorCode, ZegoNetworkSpeedTestType type)
{
    printf("onNetworkSpeedTestError errorCode=%d type=%d", errorCode, type);
}

virtual void onNetworkSpeedTestQualityUpdate(const ZegoNetworkSpeedTestQuality& quality, ZegoNetworkSpeedTestType type)
{
    printf("onNetworkSpeedTestQualityUpdate rtt=%d packetLostRate=%f connectCost=%d type=%d", quality.rtt, quality.packetLostRate, quality.connectCost, type);
}

• Usage example:

class MyEventHandler : public IZegoEventHandler
{
    void onNetworkSpeedTestError(int errorCode, ZegoNetworkSpeedTestType type) {
        // Handle error scenarios
    }
    void onNetworkSpeedTestQualityUpdate(const ZegoNetworkSpeedTestQuality& quality, ZegoNetworkSpeedTestType type) {
        // Handle quality update
    }
};

class MyEventHandler : public IZegoEventHandler
{
    void onNetworkSpeedTestError(int errorCode, ZegoNetworkSpeedTestType type) {
        // Handle error scenarios
    }
    void onNetworkSpeedTestQualityUpdate(const ZegoNetworkSpeedTestQuality& quality, ZegoNetworkSpeedTestType type) {
        // Handle quality update
    }
};

Start Speed Test

Create a ZegoNetworkSpeedTestConfig instance for network speed test configuration. Set whether to perform uplink and downlink speed tests and expected bitrate based on the actual situation, and call the startNetworkSpeedTest interface to start network speed testing.

ZegoNetworkSpeedTestConfig config;

// Perform uplink speed test, expect to publish stream with specified bitrate
config.testUplink = true;
config.expectedUplinkBitrate = videoConfig.bitrate;

// Perform downlink speed test, expect to play stream with specified bitrate
config.testDownlink = true;
config.expectedDownlinkBitrate = videoConfig.bitrate;

// Start speed test, default callback interval is 3 seconds
engine->startNetworkSpeedTest(config);

ZegoNetworkSpeedTestConfig config;

// Perform uplink speed test, expect to publish stream with specified bitrate
config.testUplink = true;
config.expectedUplinkBitrate = videoConfig.bitrate;

// Perform downlink speed test, expect to play stream with specified bitrate
config.testDownlink = true;
config.expectedDownlinkBitrate = videoConfig.bitrate;

// Start speed test, default callback interval is 3 seconds
engine->startNetworkSpeedTest(config);

Stop Speed Test

Call the stopNetworkSpeedTest interface to stop network speed testing.

After stopping speed test, you will no longer receive the onNetworkSpeedTestError or onNetworkSpeedTestQualityUpdate callbacks.

engine->stopNetworkSpeedTest();

engine->stopNetworkSpeedTest();

API Reference List