Basic Usage

To use the SDK, you have to register the software and then call the respective API for the test you want to start.

Demo Activity

A demo activity is attached to the SDK. Unzip the file quality-sdk_demo_$version.zip, and check out the MainActivity.java file, which in turn launches three different tests:

• ExoPlayerQualityTest
• VideoQualityTest
• WebQualityTest

The main activity is MainActivity.java, and it is responsbile for getting permissions and registering the client. We are requesting some permissions to get detailed connection information and geolocation. These are not strictly required but can be useful for debugging and analysis.

You can place these demo activities inside your existing app, or a new app. Just make sure you set up the dependencies on our SDK correctly per our installation instructions.

The demo activity is a good starting point to see how the SDK can be used, as it includes permission checking and a registration on startup, as well as the entire test lifecycle.

Registration Example

This is how you would perform registration in your app if you were doing it from your own activity. Use the provided Registry class, and call the registerClientAsync method with your license key.

Registry registry = new Registry(this);
if (registry.isClientRegistered()) {
    return;
}

registry.registerClientAsync("REPLACE_WITH_YOUR_REGISTRATION_KEY", null, null, new Registry.OnClientRegisteredListener() {
    @Override
    public void onClientRegistered() {
        // store the state that the client is registered
    }

    @Override
    public void onClientRegistrationFailed(RuntimeException e) {
        // log or display an error
    }
});

Note that registration is a one-time process, and the registration key is provided by AVEQ. The registration must be done asynchronously, and ideally your implementing client application should store the state that the client is registered.

ExoPlayer Quality Test Example

Once registered, you can create a Builder for the respective QualityTest which can also be launched in the onCreate method of your activity. In our example we will be using the ExoPlayerQualityTest builder. Have a look at the ExoplayerTestActivity in the demo app for more info.

Note

Do not instantiate the builder before the registration is complete, as you will receive an exception. Make sure your application is checking the registration before starting the test.

For our ExoPlayerQualityTest, we will play a DASH stream with a known manifest URL. The playback duration is 30 seconds in the below example, and the maximum test duration is a timeout for the test in case of network problems. The analysis duration is a timeout for the actual analysis of the results on the remote server.

Here is how you can start the test:

ExoPlayerQualityTest mQTest;

ExoPlayerQualityTest.Builder builder = new ExoPlayerQualityTest.Builder(
    this,
    Uri.parse("https://example.com/manifest.mpd")
)
.setMaxPlaybackDuration(30 * 1000)
.setMaxTestDuration(60 * 1000)
.setMaxAnalysisDuration(10 * 1000)
.setResultListener(this)
.setProgressInterval(1000);

mQTest = builder.build();
mQTest.start();

Tip

You can get other test URLs from the hls.js demo or the dash.js demo. All of these should work fine with the ExoPlayerQualityTest.

You can then receive the results in the onTestResult method that you will need to implement in your activity:

@Override
public void onTestResult(@NonNull Map<String, Object> result) {
    // convert the result to a JSON string, pretty-printed
    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String result = gson.toJson(result);
}

Find out more about the result format in the measurement data reference.

Instrumented Usage

You can also call the demo activity for the ExoPlayerQualityTest with adb using the following example command:

adb shell am start -n "com.aveq.qualitytestlibdemo/.ExoplayerTestActivity" \
  --ez autoRunTest true \
  --el maxPlaybackDuration 30000 \
  --el maxTestDuration 45000 \
  --ez displayPlayer true

Note that these intent parameters are directly passed to the ExoPlayer quality test; check the demo app source code for more info on how they are handled.

This requires a registered instance, so you must manually do the registration before running the test.

We provide a shell script to run the quality test using the above call, which extracts the test results directly from the Android log. See ./run_exoplayer_quality_test.sh for more info.

Video Quality Test Example

For testing video playback quality on web-based streaming platforms like YouTube or Netflix, you can use the VideoQualityTest. This test allows you to analyze video quality metrics for various streaming services. Have a look at the VideoTestActivity in the demo app for more info.

Here is a breakdown of the essential parts of the test. Note that in contrast to the ExoPlayer quality test, the VideoQualityTest requires a FrameLayout to be attached to the test, to display the video.

// attach the FrameLayout to the test --> see the demo app, `activity_video.xml` layout for more info
FrameLayout videoFrame = findViewById(R.id.videoFrame);

VideoQualityTest.Builder builder = new VideoQualityTest.Builder(
    this,
    "netflix_trailer",  // the subject identifier, can be "youtube" or "netflix_trailer"
    Uri.parse("https://www.netflix.com/tudum/videos/your-trailer-url"),
    10 * 1000  // 10 seconds playback duration
)
.setTimeout(30 * 1000)  // 30 seconds timeout
.setVideoQualityTestResultListener(this)
.attachToView(videoFrame);  // attach to a FrameLayout in your layout

mQTest = builder.build();
mQTest.start();

Note

For Netflix content, currently only trailer URLs from Netflix's Tudum site are supported.

You can receive the test results by implementing the VideoQualityTestResultListener interface as shown above.

@Override
public void onTestResult(@NonNull Map<String, Object> result) {
    // handle the test results
    Gson gson = new GsonBuilder().setPrettyPrinting().create();
    String resultJson = gson.toJson(result);
}

You can also receive periodic statistics updates by implementing the VideoStatisticsListener interface in your class, then setting it in the builder:

.setVideoStatisticsListener(this)

This will trigger the onStatisticsUpdate method in your class, which you can use to update your UI or store the statistics in a database.