Skip to main content
Skip table of contents

Event timeline

To test this feature and view the example code, please see the (5.33.x) Android SDK 5 Example Code Quick Start guide.

Performance metrics are provided for the measurement of key playback and network actions. At different levels, three classes provide the performance measurement functionality:

  • An OTVEvent instance is generated for each key event. It contains:

    • A timestamp for when the event occurred

    • The type/group to which the event belongs

    • The command - a more specific description of the event

    • Extra - additional information (if available) in stringified JSON format

  • The OTVEventTimeline is a singleton object containing the list of all OTVEvent captured, and functionality to retrieve a filtered selection of that list. It also provides methods for enabling/disabling the capture of events and discard accrued data.

  • The OTVTimelineAnalyzer is an optional addition that provides a basic analysis of the data retrieved from the OTVEventTimeline instance. You can implement analysers based on the same data.

Click here to the list of events.

Event Type

Command

Extra

PLAYBACK

prepared
firstframe
seturl
start
stop
seek_start
seek_complete

none
none
url
none
none
msec (time in ms of the target position)

MANIFEST_DL
SEGMENT_DL

network_start
network_complete
network_cancel
network_error

url
url
url
url, error

LICENCE_REQUEST

provision_request_start
provision_request_success
provision_request_failure
key_request_start
key_request_success
key_request_failure

url (of the request, not the stream)
url
url, error
url (of the request, not the stream)
url
url, error

SESSION_MANAGEMENT

ssm_setup_start
ssm_setup_success
ssm_setup_failure
ssm_teardown_start
ssm_teardown_success
ssm_teardown_failure
ssm_renewal_startup
ssm_renewal_success
ssm_renewal_failure

contentToken
contentToken, sessionToken
contentToken, error
contentToken, sessionToken
contentToken, sessionToken
contentToken, sessionToken, error
contentToken, sessionToken
contentToken, sessionToken
contentToken, sessionToken, error

Process

Start capturing

Enabling and disabling the event timeline captures can take place at any time. As some events occur before the player is instantiated, NAGRA advises you to enable captures in the first activity of the app.

JAVA
...
OTVSDK.load()
...
OTVEventTimeline.instance().enable(true);

Fetch event list

Once capturing is enabled, and after some playback, events will have been captured. You can use one of the available getTimelineList() method variants to retrieve a list of events to analyse. For example:

JAVA
Date startTime;
String url = "";
List<OTVEvent> events = OTVEventTimeline.instance().getTimelineList(OTVEvent.TYPE_PLAYBACK);
for (OTVEvent event : events) {
  if (event.getCommand().equals(OTVEvent.PLAYBACK_COMMAND_SETURL)) {
    startTime = event.getTimestamp();
    try {
      url = (new JSONObject(event.getExtra()).get(OTVEvent.EXTRA_KEY_URL);
    } catch (JSONException e) {
...
    }
  } else if (event.getCommand().equals(OTVEvent.PLAYBACK_COMMAND_FIRSTFRAME)) {
    if (startTime != null) {
      long startUpTime = event.getTimestamp().getTime() - startTime.getTime();
      Log.d(TAG, "Startup time for stream " + url + " was " + startUpTime + " milliseconds");
      break;
    }
  }
}

Using OTVTimelineAnalyzer

The OTVTimelineAnalyzer helper class provides an analysis of common aspects of the captured list in static query methods. It uses the information it retrieves from the OTVEventTimeline class, and you can implement queries similar to OTVTimelineAnalyzer or more complex ones.

For example, to retrieve start-up time (in milliseconds) for each stream played (since events capturing was enabled), use the following code:

JAVA
...
OTVSDK.load()
...
OTVEventTimeline.instance().enable(true);
...
// Play some streams and then...
List<Pair<String,Long>> startupTimes = OTVTimelineAnalyzer.getStartupTimeDurations();
for (Pair<String,Long> streamInfo : startupTimes) {
  Log.d("Info", "Start-up time for stream " + streamInfo.first + " was " + sream.Info.second + " milliseconds");
}

Other queries provided by this class:

  • getStartupTimeDurations(String xUrl) is a list of start-up time long integers (milliseconds) for a given stream’s URL. Start-up time is defined as the time measured from the moment the path is set until the first frame is rendered.

  • getStreamEventDetails(String xUrl) for a given stream’s URL fetches all events associated with that stream.

  • getZapDuration(String xUrlFrom, String xUrlTo) returns the measured zapping time for the last zap from one given stream to another (from the moment ‘stop’ was called on stream one until the first frame of stream two is rendered).

Adding events to the list

In most cases, the application does not need to add events to the existing timeline list. It is still possible for the DRM callback handlers to capture DRM key requests. The default callback classes provided by NAGRA already register the necessary events (see list above); if you choose to implement your own callback classes, you might want to add your own event.

There is one static method that adds an event to the timeline list, OTVEventTimeline.addToTimeline(String xType, String xCommand, String xExtra). For example:

JAVA
JSONObject json = new JSONObject();
try {
  json.put(OTVEvent.EXTRA_KEY_URL, url);
} catch (JSONException e) {
...
}
OTVEventTimeline.addToTimeline(OTVEvent.TYPE_LICENCE_REQUEST, OTVEvent.KEY_REQUEST_START, json);
JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.