Frequently asked questions (FAQ)
In this section we will list all the frequently asked questions we received over the years.
For our customers with a support plan package, if you have additional questions or can't find your answer here please contact our Service Desk for further support.
ποΈ How to add CSS or JavaScript files to an Android/iOS project (legacy mobile SDKs)
This guide describes how to add CSS or JavaScript files to an Android or iOS project, and manipulate the player using CSS and/or JavaScript.
ποΈ How to combat autoplay policies
This short article explains what autoplay is, where autoplay is restricted, and what THEOplayer does to facilitate working with autoplay.
ποΈ Why does fullscreen not behave as expected on iOS
One of the most frequently encountered issues on iOS devices is unexpected behavior concerning fullscreen playback.
ποΈ Why does the Network API not work on iOS devices
Most Network API capabilities are not available on iOS devices. Generally speaking, video playback on iOS behaves like a black box. This black box handles the requests (and responses) related to video manifests and segments, which makes them impossible to intercept. This limits the possible uses of the Network API on such devices.
ποΈ Why does Chromecast not work on iOS Chrome?
iOS Chrome used to support Chromecast. However, Google silently removed support for it at some point. It is also documented on their Web Sender guide here that:
ποΈ Why can't I select another video quality on iOS/tvOS?
In short: Apple technically restricts video players from doing this, and there is no workaround.
ποΈ Is YouTube supported
This question above is typically asked by customers who have experience with the YouTube embedded player. It's also related to the following questions:
ποΈ Why does the player load only one audio track (even though there are several in the manifest)
You may be asking this question if you notice a discrepancy in the number of audio tracks present in the manifest and the audio tracks that you can select from the player UI.
ποΈ Is it possible to see 360 degrees photo with THEOplayer
This question is asked by those users and developers that are wondering if the player 360 degree functionality can be used to view also images.
ποΈ Why the Visibility API does not work through an iframe on Safari and IE11
This question may be asked when you observe a different behavior of the Visibility API on different browsers.
ποΈ What is an impression
This article explains what an impression is and how THEOplayer calculates impressions.
ποΈ How to know whether a live stream is playing
You can check if a stream being played is live or VOD by checking its duration. If the duration returns Infinity, the stream would be live. Examples:
ποΈ Which error related events does the player expose
THEOplayer exposes different types of errors. Refer to "How to do error handling"
ποΈ Why did my subtitles stop working
This question is occasionally asked by developers who've configured the latest release of THEOplayer.
ποΈ How does Media Engagement Index (MEI) affect Autoplay on Chrome
The question above is related to the following questions:
ποΈ What does the error message 'Unknown CDM error' mean
If you got to see this page, you probably know that CDM stands for Content Decryption Module, which is a component in the DRM pipeline, a part of the content protection process.
ποΈ What does the error message 'Something went wrong with Native playback' mean
This error, "Something went wrong with Native playback", occurs whenever the player struggles on the native rendering pipeline of the browser in use. The error code itself can be different, and it reflects the HTML5 MediaError interface.
ποΈ Why are not all response headers exposed
You may ask this question if, for example, you are trying to intercept a certain XHR response to use data contained in custom headers but you don't find these among the exposed headers (see documentation below regarding network interceptors).
ποΈ Why does the currentTime seem off in my livestream & what can I do about it
THEOplayer has a currentTime property, which returns you the current playback position in the video (in seconds). For VOD this works as you would expect. If you have a video, let it play for 30 seconds and query the currentTime, the player will report 30 seconds. However, if you start watching a livestream and query the currentTime after 30 seconds, you won't get 30 seconds reported. Nor will you get the time that would have elapsed if you watched the segments in the most recent manifest file until the point where you queried the currentTime. This might seem odd, but there's a very good reason for this, which we'll explain in a bit, along with some workarounds if you do want to use one of the aforementioned definitions of currentTime in a live streaming context.
ποΈ How to remove CORS restrictions from a reproduction stream
A "CORS-issue" is a common cause of a stream not starting. In a nutshell, a CORS issue implies that the origin is not allowed to fetch the resource. This issue has to be resolved from the server-side.
ποΈ Which network calls (or requests) does THEOplayer do
The question above is related to the following questions:
ποΈ Why does the playback not work when using the Chrome iPhone/iPad simulator
You might need an answer to this question if you are testing your page using the Chrome iPhone/iPad simulator and notice that, reloading the page, the video player stops working (even though the ads, if any, are displayed correctly) and some errors are displayed in the console.
ποΈ What does the error message 'can only be initiated by a user gesture' imply? Can I still force the desired action
You may get this error if you are trying to have the player execute an action without it being initiated by the user. A typical example is going fullscreen or automatically starting playback (often on mobile).
ποΈ How to remove unwanted CC track in iOS or Safari
This article is intended to show how to remove any unwanted CC tracks that might be showing up in iOS or Safari. This can be done by editing the HLS master playlist.
ποΈ Why do I get a gray play button in my Android WebView and how to remove it?
You may ask this question if a gray play button is showed by default in your Android WebView.
ποΈ MediaTek limitations
This page overviews a list of known issues caused by the MediaTek chipset.
ποΈ How to use ProGuard with THEOplayer Android SDK
ProGuard is a popular tool to obfuscate and optimize Java code in Android projects. Depending on the settings, this tool can clash with the THEOplayer Android SDK.
ποΈ Self-hosting and versioning of THEOplayer
Your licensed THEOplayer can also be hosted on your own servers or CDN.
ποΈ Does THEOplayer support EXT-X-DATERANGE
Yes, the HLS tag #EXT-X-DATERANGE is supported in THEOplayer as of 2.61.0. To enable it, hlsDateRange needs to be added to either the player configuration or the source description and be set to true. The date range metadata will be made available through the TextTrack API.
ποΈ Can clipping be used on a playlist
Yes. This is in principle not different from using it on a single video: a startTime and an endTime must be given for each video and applied when the video is loaded/played.
ποΈ Can timeline thumbnails be made available before playback start
Yes, this is possible using the preload feature, provided your timeline is already visible. Both βmetadataβ and βautoβ will be effective values to this end.
ποΈ What are the benefits of preloading
Choosing whether to preload parts of the video before it starts playing will help you considerably improve the user experience.
ποΈ What are the player seeking and seeked events and when are they fired
They are events related to the playback of media files. seeking is fired when the user starts seeking/moving to a new position. seeked is fired when the user is finished seeking/moving to a new position and the player has buffered a video portion, being therefore ready to play.
ποΈ Can we use HLS or DASH ads
Yes, we support HLS and DASH ads through a THEOAdDescription for the THEOplayer Web SDK 2.84.0 and up. HLS and DASH ads are currently not supported on any other SDKs. Our Google IMA integration does not support HLS or DASH ads.
ποΈ How to change text in THEOplayer
Using language localization, you should be able to change any text in the player to the one you desire.
ποΈ Change text when Airplaying
You will need to add the 'metadata' parameter to the SourceDescription with the 'title' property filled with the title to be displayed.
ποΈ ITP2.1 problems using THEOplayer
Appleβs Intelligent Tracking Prevention 2.1 causes cookies to be only saved for 7 days unless the Safari user directly interacts with the website again.
ποΈ Removing context menu/'Powered by THEOplayer v2...'
The context menu can be removed while building your player by disabling the "contextmenu" feature or by adding a CSS rule on your page.
ποΈ What aspects of THEOplayer do we need to take into account to deploy a proper Content Security Policy (CSP)
The script-src 'self' and 'inline' should be allowed. The player also requires doing calls to \*.theoplayer.com and to wherever the JavaScript files and workers are located. Additionally, depending on your active features, you may need to add some other source (e.g.//www.gstatic.com/, as its library is hosted there).
ποΈ How can we avoid that the player keeps looking for chunks/segments if they are not found
You can use the Network API events to detect whether the stream is offline and implement the behavior you prefer. This is working for HLS and is being implemented (2020) for DASH as well.
ποΈ Can we show a custom message on 403 on mp4
Yes, this is possible, but not as easy as for DASH and HLS. To address this specific use case no internal THEOplayer tool exists yet (2019) and a separate XHR call needs to be done to determine the exact status of the request. Custom texts, overlays and buttons can be showed on the player following the instructions from the related linked resource.
ποΈ Can we prevent UpNext feature from redirecting
Yes, this is possible. You need to modify the countdownDuration value in your UpNextPanel to Infinity.
ποΈ Is it possible to preload VOD content while the pre-roll is playing
Yes, it is done with the preload feature. Before setting your source, you need to activate preload on your player. We advise to use the value βautoβ: this allows the first segments of the stream to be downloaded during the ad, reducing the start-up time of the video content.
ποΈ Why is my video not playing automatically
There is a wide variety of possible causes that bring to a video not being automatically played. These may have to do with autoplay policies, iframes, Media Engagement Index and more. Please read the full answer in this article for more information. Also, please keep in mind that this is not an extensive list of causes for autoplay failure and that, as time goes by, browsers autoplay management and autoplay policies may change.
ποΈ Is it possible to have multiple player instances play at the same time
Yes, this is possible, provided there are enough bandwidth and RAM for this to work (considering both server and client side). Although we donβt explicitly advise against this, we see how this could not be an ideal solution for the viewers. Please also keep in mind that this incurs into some limitations.
ποΈ Is it a problem if the viewer pauses a live stream for longer than the DVR window
In general, this is no problem as the player will continue playback, once exhausted the current buffer, from the nearest point available, in this case the end of the sliding window.
ποΈ THEOplayer Features & Modules
The THEOplayer SDK consists of modular features.
ποΈ Chromecast on my webplayer does not work any longer despite no change in my implementation
This or a similar question may be asked in case your Chromecast stops working. There may indeed be different causes why your Chromecast is not working, especially if
ποΈ How to track network errors
THEOplayer currently doesn't throw an error event for all network request errors on all platforms. Sometimes you might want an event to listen for to track network related issues in your QoS/QoE dashboards. To enable this, you can use our Network API.
ποΈ What is the support for Wowza
Wowza and THEOplayer are partners in the streaming industry. When developers use both products,
ποΈ How to use the CDN fallback/backup stream feature
THEOplayer offers a feature to detect more sources of content in manifest or playlist, so that the player can automatically switch to a fallback URL, in case any of the main content source is unavailable or not reachable. This feature works for both MPEG-DASH and HLS streams out of the box, and does not require any additional configuration to the player.
ποΈ How to apply accurate buffering strategy
By default, THEOplayer buffers 20 seconds of video including audio/subtitles in order to guarantee smooth playout.
ποΈ How can I distribute 4K content?
The ability to play 4k mostly depends on hardware.
ποΈ What is the collaboration between Azure Media Services and THEOplayer
Azure Media Services has a rich ecosystem of partners that provide their customers with the flexibility of choosing the best solution for their needs.
ποΈ Is Portrait mode supported
Yes. THEOplayer supports vertical video playback, which is also known as portrait mode.
ποΈ How to prevent screen recording
This article explains what screen recording is, and how to counter it.
ποΈ The provided video source is incompatible with the license for this player
The player throws this error when the source of the player is incompatible with the license. This occurs when the domain of the source is not in the list of source domains of the license. For example, when you have yourfirstcdn.com and yoursecondcdn.com as source domains, but you use a video stream (i.e. source) from https://yourthirdcdn.com/video.m3u8, then the player will throw the above error because yourthirdcdn.com is not included in the source domains (yourfirstcdn.com and yoursecondcdn.com).
ποΈ Page and Source domains
Page and Source domains prevent unauthorized users from embedding your SDK on their website.
ποΈ What does the error message βSomething went wrong determining the initial period of the provided MPEG-DASH streamβ mean
This error, "Something went wrong determining the initial period of the provided MPEG-DASH stream", occurs whenever the player struggles to play a DASH stream due to problems determining the availability of the segments for that stream. The recommended solution for this is to make sure that the segments result available, based on the data provided in the manifest, at the time at which the manifest is requested.
ποΈ Why is my PlayReady stream not working in Chromium Edge?
If you are having problems playing PlayReady streams in Chromium Edge, this may be due to a conflict between player and browser, regarding the DRM system to use. If this is the case, you may solve the issue indicating Playready as your first option with the preferredKeySystems property.
ποΈ Which subtitle and CC formats are supported on native Safari
The Safari browser on iOS uses the native Safari video player.
ποΈ How to navigate through the documentation and resources
THEOplayer offers documentation and resources through a number of channels.
ποΈ How to create a (great) ticket
Customers can create tickets through our Jira Service Desk at https://servicedesk.theoplayer.com.
ποΈ 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.
ποΈ What are the limitations of AirPlay
When casting through AirPlay your viewer is relying on the native Apple video player.
ποΈ What are the Edgio challenges
The purpose of this article is to group common challenges application developers might encounter when using Edgio (formerly known as Verizon Media and Edgecast) as the back-end.
ποΈ How to use the Media Session API
Developers who implement the Media Session API give viewers the option to control and monitor media playback outside their web page.
ποΈ How to use THEOplayer iOS SDK on an M1 mac
The iPhone simulators on M1 MacBooks use the arm64 architecture, therefore any binaries linked during compilation time that do not support the architecture will result in compilation error. Many third party frameworks lack the support for this particular architecture, and this causes unfortunate limitations for development.
ποΈ Widevine CDM deprecation notice for old browser versions
Google announced that the current version of the Widevine Content Decryption Module (CDM), which is a closed environment responsible for handling the DRM restrictions and decryption of media, will stop working on 6 December 2022.
ποΈ Which source is the one being played
In THEOplayer, player.source.sources can be used to provide alternative sources for playback, for cross-platform support. What is the actual source being played, if more than one is provided that is supported on the current platform/browser?
ποΈ What is the "WebAssembly.compileStreaming failed" warning and what does it mean?
When starting playback in THEOplayer, you might be seeing a warning in console that reads
ποΈ What PiP options to use to make the video stay visible while browsing or on other applications
When it comes to Picture-in-Picture (PiP), there are different options, each with its advantages and disadvantages. To have the floating video remain visible during browsing, you need an out-of-app PiP, but not all features are available (or the same) everywhere.
ποΈ Why are the FairPlay license and certificate being requested again on iOS after ads?
The DRM license and certificate are retrieved when a DRM-protected stream starts to be played. This is usually enough for a full playback session since in most cases the DRM context can be maintained.
ποΈ How to detect if the user changes the video quality
It is possible to distinguish between when the quality is changed by ABR or by the user and, in the latter case, which quality has been selected.