IntroductionHow to add CSS or JavaScript files to an Android/iOS projectHow to combat autoplay policiesWhy does fullscreen not behave as expected on iOSWhy does the Network API not work on iOS devicesWhy does Chromecast not work on iOS Chrome?Why can't I select another video quality on iOS/tvOS?Is YouTube supportedWhy does the player load only one audio track (even though there are several in the manifest)Is it possible to see 360 degrees photo with THEOplayerWhy the Visibility API does not work through an iframe on Safari and IE11What is an impressionHow to know whether a live stream is playingWhich error related events does the player exposeWhy did my subtitles stop workingHow does Media Engagement Index (MEI) affect Autoplay on ChromeWhat does the error message 'Unknown CDM error' meanWhat does the error message 'Something went wrong with Native playback' meanWhy are not all response headers exposedWhy does the currentTime seem off in my livestream & what can I do about itHow to remove CORS restrictions from a reproduction streamWhich network calls (or requests) does THEOplayer doWhy does the playback not work when using the Chrome iPhone/iPad simulatorWhat does the error message 'can only be initiated by a user gesture' imply? Can I still force the desired actionHow to remove unwanted CC track in iOS or SafariWhy do I get a gray play button in my Android WebView and how to remove it?MediaTek limitationsHow to use ProGuard with THEOplayer Android SDKSelf-hosting and versioning of THEOplayerDoes THEOplayer support EXT-X-DATERANGECan clipping be used on a playlistCan timeline thumbnails be made available before playback startWhat are the benefits of preloadingWhat are the player seeking and seeked events and when are they firedCan we use HLS or DASH adsHow to change text in THEOplayerChange text when AirplayingITP2.1 problems using THEOplayerRemoving context menu/'Powered by THEOplayer v2...'What aspects of THEOplayer do we need to take into account to deploy a proper Content Security Policy (CSP)How can we avoid that the player keeps looking for chunks/segments if they are not foundCan we show a custom message on 403 on mp4Can we prevent UpNext feature from redirectingIs it possible to preload VOD content while the pre-roll is playingWhy is my video not playing automaticallyIs it possible to have multiple player instances play at the same timeIs it a problem if the viewer pauses a live stream for longer than the DVR windowTHEOplayer Features & ModulesChromecast on my webplayer does not work any longer despite no change in my implementationHow to track network errorsWhat is the support for WowzaHow to use the CDN fallback/backup stream featureHow to apply accurate buffering strategyHow can I distribute 4K content?What is the collaboration between Azure Media Services and THEOplayerIs Portrait mode supportedHow to prevent screen recordingThe provided video source is incompatible with the license for this playerPage and Source domainsWhat does the error message “Something went wrong determining the initial period of the provided MPEG-DASH stream” meanWhy is my PlayReady stream not working in Chromium Edge?Which subtitle and CC formats are supported on native SafariHow to navigate through the documentation and resourcesHow to create a (great) ticketHow to investigate a ticketWhat are the limitations of AirPlayWhat are the Edgio challengesHow to use the Media Session APIHow to use THEOplayer iOS SDK on an M1 macWidevine CDM deprecation notice for old browser versions

How to investigate a ticket

This article describes how our team typically investigates an issue (i.e. bug) reported to us through a Service Desk ticket. We encourage you to go through these steps before creating a ticket, and to document your findings in your ticket.

This article discusses the following topics:


  • The ticket is well-described and/or C.R.U.S.P..
  • The reported 'Current behavior' can be easily understood.

    • Illustrations, screenshots or screen recordings are provided to further elaborate on the issue.
  • The reported 'Expected behavior' can be easily understood.

    • The affected SDK(s) are correctly labelled.
    • (The affected browsers are correctly labelled.)
  • A reliable and simple reproduction page, stream or application has been shared.

    • Customer-specific application logic has been stripped when a reproduction page or application has been shared.


Investigating an issue typically consists of 4 phases:

  1. Reproducing the issue;
  2. Checking whether it can be reproduced with the latest version (or other versions) of THEOplayer;
  3. Pre-investigating the issue, and narrowing down the scope;
  4. Investigating the root cause and determine the next action item.

THEOplayer Jira Service Desk

Reproduce the issue

The first step is to reproduce the issue. Take the reproduction stream/page/application, and confirm the issue.

  • If the issue can be reproduced: continue the investigation.
  • If the issue cannot be reproduced: request more information from the reporter.

THEOplayer Jira Service Desk

Check other versions

The second step is to check if the issue can still be reproduced with the latest version (or other versions) of THEOplayer.

  • If using a more recent version fixes the issue: deploy the latest version of THEOplayer.
  • If an older version addresses the issue: investigate a potential regression.
  • If this doesn't fix the issue: continue scoping the issue.

Narrow the scope

The goal of this step is to narrow down the scope of the issue. After this phase, we want to determine the influence of the following components.

  • Affected platforms;

    • Affected browsers;
    • Affected operating systems;
    • Affected SDKs;
  • Affected THEOplayer versions;
  • Affected video players.

THEOplayer Jira Service Desk

Scope affected platforms

It's always useful to know which browsers, SDKs and operating systems are affected by the issue.

Scope affected THEOplayer versions

Whilst it's critical to share which THEOplayer versions are affected, it's even more useful to identify older (or newer) versions which are unaffected by the issue. If that's the case, THEOplayer can identify a regression, which speeds up the R&D-process.

Check which older versions are unaffected.

Scope affected video players

In case of an AV playback issue (e.g. freezes, errors, ...), comparing with other video players can help in understanding whether there's a server-side issue (e.g. encoding, packaging, CDN) or a client-side video player issue. If all video players suffer from the issue, it's possible that the stream is not optimally encoded, packaged, etc.

Tips for comparing with other video players:

  • If it's an HLS stream: Native Safari, AVPlayer, HLS.js, Shaka Player
  • If it's an MPEG-DASH stream: DASH.js, ExoPlayer, Shaka Player


The goal of this step is to identify the cause. Let's discuss causes related to the API, Playback, Advertisements, Analytics and DRM.


Developers implement THEOplayer through a specific API related to a specific feature. Sometimes, an issue is caused by using a set of API-logic which triggers an edge-case. Sometimes, a nice-to-have API might break in a new update, which in turn breaks a must-have feature.

If you can identify which API-statement causes the issue,

  • you can evaluate if you can temporarily disable the statement, and potentially identify a workaround,
  • and the R&D-team knows to what the root cause is related.

Below is a list of proposed action items:

  1. Use a near-empty THEOplayer page (or application). Don't use autoplay or preload, or poster images, or ...; limit the API to the absolute minimum.
  2. Gradually, add new statements, until the issue can be reproduced.
  3. Try alternative approaches, values and states.


Playback issues are related to video and audio freezes, start-up failures, and crashes during playback.

  1. Double-check the pre-investigation.
  2. Extract information from the reporter why the issue is surfacing just now. Often, playback issues are caused by server-side changes.
  3. Extract information from the reporter whether every asset is suffering from the issue.
  4. Check whether the issue can be reproduced with other streams:

  5. Check if the issue is related to a specific video or audio quality. Manually switch to a specific quality or track, and verify whether the issue can still be reproduced. Often, the issues are caused by glitching quality-changes, or a badly encoded quality.
  6. Check what is logged in chrome://media-internals.
  7. Check whether there are CORS-issues.
  8. In-case DRM is used, check whether the issue can also be reproduced if the asset is unprotected.


Advertisement set-ups can be quite complex, and the related issues can be quite subtle.

  1. Check whether simpler versions of your set-up suffers from the issue:

    • In-case multiple ads are scheduled, check whether single ads suffer from the issue.
    • In-case pre-rolls/mid-rolls are scheduled, check whether the issue is still present if you schedule it as a post-roll/mid-roll instead.
    • In-case multiple ad pods are used inside an ad-break, check whether the issue can be reproduced with single ad pods.
    • In-case a VPAID is scheduled, check whether a VAST works instead.
    • In-case a VMAP is scheduled, check whether an altered VMAP works instead.
  2. In-case Google IMA is used, check whether the issue can be reproduced at https://developers.google.com/interactive-media-ads/docs/sdks/html5/vastinspector.
  3. In-case a SSAI solution is used, check whether other clients also suffer from the issue.


Issues related to an analytics service usually comes in three shapes:

  1. No data is being logged in the analytics service:

    • Check whether the analytics service requires a third-party SDK. If so, check whether this has been included.
  2. Data is being logged incorrectly:

    1. Try alternative configurations. When is it working incorrectly?
    2. Identify the maintainer: is it THEOplayer or the analytics vendor?
    3. Find the reference implementation or documentation, and compare with the current implementation.


Sometimes issues are flagged as a DRM issue, whilst they are actually more generic playback issues:

  • Check whether the issue can also be reproduced with unprotected streams.

In-case the issue is related to adding DRM:

  • Double-check the pre-investigation. It's valuable information if -for example- the issue can be reproduced on Chrome, but not on Firefox, as this could imply that this is a platform-specific decoding issue.
  • Check whether the issue is related to Widevine, PlayReady, FairPlay, or all.
  • Extract information from the customer whether every DRM-protected asset is suffering from this issue.
  • Check whether the issue can be reproduced with reference DRM streams. (e.g. https://demo.theoplayer.com/drm-aes-protection-128-encryption)


Make sure to follow us on GitHub!
Copyright © 2022. All Rights Reserved.
New York