Award Winning Company

Award Winning Company

DIAGNAL Logo

Debugging Video Playback Issues in Web based Apps

The video player is a core component of any premium OTT service as high quality video views are essential for any monetised service. To ensure a high quality of experience, video player integration requires precision in implementation. Premium video plays can be problematic, especially when dealing with complex features such as Digital Rights Management (DRM), concurrency, live video with channel switching, catchup, all of which can cause issues if not implemented carefully.

A robust debugging system for video playing is essential. This article explains Diagnal’s approach on this important topic for anyone interesting in running a large scale premium OTT service.

Local vs Production

Video errors can occur on a developer’s system, QA environment, or a customer’s system. Regardless of location, the first step is to detect the error to enable resolution.

Identifying video errors locally during development or QA is straightforward via developer or error logs. This is not the case for customers in production.

To observe production errors, we need to implement a logging system that captures all errors and warnings.

At Diagnal, we’ve tested multiple player observability systems over the years. Our current error logging strategy combines three platforms – Bugsnag, Loggly, and MUX. This three-level approach captures every production error and warning, including minor video play anomalies.

Local Debugging in TV Apps – A Painful Exception

Debugging locally is usually straightforward but can fail with TV apps. Typically, side loading the app via WebOS, Tizen Studio, or other platform-specific developer tools and inspecting it works well.

Detailed information on local debugging for Tizen and WebOS is available here.

On some devices, the debugger-device connection is unstable; it may frequently fail to connect or maintain a long-lasting connection during extended video playback debugging sessions.

If the process fails or direct local connection to the problematic TV is unavailable, use third-party tools for debugging.

For near-native debugging via Chrome Developer Tools over the internet, VorlonJs supports DOM inspection, network monitoring, and storage management.

For quick console log monitoring or remote function calls, RemoteJS: Remote Javascript Debugger provides a minimal, powerful, and easy remote console for monitoring and executing logs and functions.

Remember to always remove debugging tools after use and never ship them to production.

Monitoring Video Plays

Video play errors do not always appear in “red color” in your observability platform. Sometimes plays start a few seconds late or buffer multiple times. Technically, these are not “errors,” but OTT providers and developers should treat them as a degradation in video experience and should address them promptly.

MUX Video performance & QoE monitoring is our primary tool for monitoring video views and detecting anomalies early. A custom MUX integration with video players provides detailed information on all video view metrics.

MUX matrix from one of our customers. Any score reduction or key metrics increase requires immediate attention
Video Play Pipeline

Understanding how video streaming works helps identify potential failure points. We will examine the basic operation of video streaming using a common system configuration: Shaka HTML Video Player and with Wideveine DRM. The flow is similar for other video players and DRM systems (typically PlayReady and FairPlay).

Shaka Player DASH Widevine Video Play FlowSource code

In the diagram, besides the Shaka Video Player and common components like the Browser or Video Element, there are some other other entities. Let’s understand what they do below.

• Media Source Extensions (MSE): Browser API for appending segmented media to a <video> element, enabling dynamic buffering and switching.

• Encrypted Media Extensions (EME): Browser API interfacing with Content Decryption Modules (CDMs) for DRM handling.

• Widevine CDM: Google module (embedded in Chrome/Android) that decrypts CENC-encrypted content using AES-128 CTR.

• License Server: Backend service (e.g., Widevine proxy) that authenticates requests and issues decryption keys.

• Content Server/CDN: Hosts encrypted DASH segments and manifest.

Failure points in Video Play Pipeline

Now we understand the happy path, here is the video play pipeline with common failure points marked. Below, we explain the errors encountered at each failure point, considering Shaka player implementation.


Failure Point 1: Fetch MPD manifest

At this stage, we pass the manifest file URL to the player, which fetches the URL to obtain content details.

Common errors:

  • Invalid manifest URL format, wrong URL, URL unavailable or blocked, CORS error: NETWORK_XX_ERROR (404/403) 
  • Manifest loaded but broken XLink references in live manifest: NETWORK_MPD_INVALID_XLINK
  • Loaded manifest version is incompatible.
Failure Point 2: MSE attach MediaSource

The Video Player attempts to attach the video element to the MSE.

Common errors:

  • Browser buffer quota exceeded: MSE_STATUS_QUOTA_EXCEEDED
  • <video> element already in use or codec unsupported: MSE_STATUS_QUOTA_EXCEEDED
  • Browser does not support video/mp4; codecs=”avc1.42E01E”: MSE_TYPE_UNSUPPORTED
Failure Point 3: Fetch encrypted segments


The player begins fetching encrypted media segments, often from a CDN.

Common errors:

  • 404/503/CORS or other errors from segment file URLs: NETWORK_SEGMENT_XX_ERROR
  • Corrupted segment or codec mismatch: BUFFER_APPEND_FAILED
Failure Point 4: EME Session Creation

At this stage, the player creates an EME session for video play.

Common errors:

  • CDM not installed or activated: DRM_NOT_PROVISIONED
  • Missing PSSH in manifest ContentProtection: EME_NO_DRM_INFO
  • Widevine (or DRM in use) unavailable in browser: REQUESTED_KEY_SYSTEM_NOT_SUPPORTED
Failure point 5: CDM initialization

This stage involves the initial interaction with the CDM.

Common errors:

  • CDM creation failed (hardware issues): MEDIA_KEYERR_CREATE
  • CDM version mismatch or robustness failure (requires HW_SECURE_ALL): MEDIA_KEYERR_CLIENT
  • Browser policy blocks CDM loading
Failure point 6: Error generating the request

Common errors:

  • CDM internal error generating challenge: MEDIA_KEYERR_UNKNOWN
  • EME session already closed: INVALID_STATE_ERR
  • PSSH parsing errors: Invalid base64 initData
Failure Point 7: License Server POST

The player sends a request to the DRM licensing server, but the POST request fails.

Common errors:

  • 401/403 authorization failure: DRM_LICENSE_REQUEST_FAILED
  • License server unreachable (timeout): NETWORK_LICENSE_REQUEST_TIMEOUT
  • License response lacks provisioning certificate: DRM_SERVER_CERT_MISSING
  • Invalid JWT or token in request headers
Failure Point 8: EME update() with license

The player provide the license obtained to EME

Common error:

  • License signature verification failed : MEDIA_KEYERR_CLIENT
  • Malformed license binary : DRM_LICENSE_RESPONSE_INVALID
  • Key rotation issues in multi-period DASH
Failure Point 9: MSE append and video play

At this point, all prior steps have been successfully completed, and the video player proceeds to initiate video play using the actual video element.

Common error:

  • Stall due to bitrate switching : BUFFERING_ENDED
  • SourceBuffer decode error after decryption : PLAYER_FATAL_ERROR
  • Hardware decoder rejects decrypted frames : VIDEO_DECODE_ERROR
Listening for Errors

How do we listen for these errors at the code level? When streaming with DRM protection, we typically use an HTML5 video player. These video players wrap errors from each entity into a single callback or event listener, making error handling straightforward.

Here is example code for listening to nearly all failure cases discussed above when using the Shaka player.

const player = new shaka.Player(video);

// Listen for ALL playback errors
player.addEventListener('error', onErrorEvent);

function onErrorEvent(event) {
  const error = event.detail;  // shaka.util.Error object
  
  console.error('Error:', error.category, error.code, error.message);
  
  // Map to our failure points
  switch(error.code) {
    case shaka.util.Error.Code.DRM_LICENSE_REQUEST_FAILED:
      console.log('Failure Point 8: License server error');
      break;
    case shaka.util.Error.Code.MEDIA_ERR_SRC_NOT_SUPPORTED:
      console.log('Failure Point 5: EME/CDM issue');
      break;
  }
}

Once the callback triggers, check the error type and handle each scenario separately.

Integrate logging and monitoring services here to track production errors.

During development, we see most errors immediately in the dev tool console. Chrome offers a dedicated tab displaying useful logs, procedures, and any errors or warnings from current or past video plays in that session.

Screenshot of media tab in chrome dev tools
A Quick Debug

Often, multiple integrations, extensions, and logs run alongside the player. When an error occurs, the volume of information can be overwhelming. A dedicated test web application helps by allowing input of basic details like manifest and DRM info to test video plays. This identifies whether the issue lies within our code, a service integration the browser, the device platform, or stream. An alternative online resource is the Shaka Player Demo.

Conclusion

Successful video views are the core of an OTT app – video is the product. Therefore, monitoring performance and errors carefully and promptly addressing any deviation from the ideal experience expected by a monetised user is essential. At Diagnal, we continuously monitor, debug, and deliver reliable video plays across all our web platforms using the tools and techniques described. If you’d like to know more or share what you’re working on, feel free to reach out!