Player V4 FAQ

Player V4 Overview

Q: What is Player V4?

A: Ooyala's next generation video player for HTML5 is designed to provide an engaging, personalized, content aware, and robust video playback experience that is consistent across devices and platforms. See Player V4 for a full list of features.

Q: How does Player V4 differ from earlier Ooyala players?

A: Player V4 has a new responsive and customizable UI that you can use out-of-the-box or customize to your branding needs. Modify a simple JSON file or the player CSS to make branding and UI customizations.

Player V3 is a Flash-first player by default, whereas Player V4 prefers HTML5 playback by default (it is built with HTML5). The Player V4 plugin has Flash support via the bit_wrapper.js (recommended) or OSMF plugins. See Flash Video Rendering for details on Flash video rendering.

Player V4 is a modular player consisting of plugins, which means that you can add or remove certain functionality depending on which plugins you load on your HTML page. The modular architecture of Player V4 allows for faster load times (V4 is at least 4x smaller and 3x faster than V3) and increased customizability.

Player V4 features a new Ad Manager Framework Ad with robust ad support, and an Analytics Framework that allows you to integrate third-party analytics providers with the player. See Player V4 for a full list of features.

Q: How does Player V4 look to users?

A: Player V4 has a completely rebuilt user interface that is optimized to run in many environments. See User Interface for the Player V4 Skin for descriptions of the Player V4 UI components.

Supported Features

Q: What features are supported in this version of Player V4?

A: See Ooyala Player V4 Release Notes for a list of features released in the latest version of Player V4.

Q: Does Player V4 integrate with social networks?

Q: Yes, Player V4 supports integrations with Facebook, Twitter, and Google Plus.

Q: Can Player V4 controls be translated (localized)?

A: Yes. We offer localization files for English, Spanish, and Simplified Chinese, but you can also add your own localization files.

Q: What closed caption languages does Player V4 support?

A: You can upload your own closed caption languages. Supported languages are listed at Supported Closed Caption Languages.

Q: Is QoS with NPAW's YOUBORA supported in Player V4?

A: Yes. For details, see YOUBORA Analytics Plugin.

Is a comScore integration supported for Player V4?

A: Yes, Player V4 supports an out-of-the-box integration with comScore. Please contact your Ooyala account manager to use the Player V4 comScore integration. For details, see comScore Analytics Plugin

Q: What is Ooyala's ID3 detection capability?

A: The Ooyala Player V4 will recognize ID3 tag information embedded in an HLS stream.When an HLS stream is embedded with ID3, the Ooyala Player will automatically raise an event VC_TAG_FOUND with the value videoTagFound to indicate that the ID3 cues have been encountered. With this capability, the Ooyala Player ensures that ID3 cues are easily detectable by web applications for a variety of use cases.

Getting Started with Player V4

Q: Once I am up set up with Player V4, do I need to do continuous developer work to keep up with Ooyala monthly releases?

A: No. Every new release will not affect the previous ones. Ooyala hosts two release paths (production and latest, as described in Ooyala-hosted Player V4 Resources) so that you are automatically upgraded to the latest version. If you are self-hosting (Hosting Player V4 Resources), all you need to do is pull/clone the latest versions of the plugins and player files.

Q: Can I mix and match files from different release versions (for example, skin.json from 1.0.0 and ad_manager_vast.js from 1.4.1)?

A: We strongly recommend using all files from the same release version. You can attempt to mix and match files from different release versions, but if you have bugs caused by this mix and match that are fixed by using files from the same release version, we will not implement fixes for those bugs.

Q: What does Player V4 have to do with the video mobile SDKs for iOS and Android?

A: Player V4 and the mobile SDKs for iOS and Android share the same look and feel (skin). When we refer to the Player V4 skin, we are referring typically to the skin.json file that can be used to apply player UX to the HTML5 Player V4 and the mobile SDK players.

Q: Are there any special cases where Player V4 will be forced to load Flash instead of HTML5? In case the player is handling VPAID ads what would be the behavior? Will a Flash player be loaded at the beginning or only when serving the Ad? Would the actual content still be played in HTML5 player?

A: The core player will always be HTML5-based in Player V4. If the selected encoding is not supported in HTML5 on a certain browser and if Flash is supported, the main video will render in Flash. The rest of the player including the UI will remain HTML5-based. For VPAID 1.0, the VPAID ad will render in a Flash-based element, but the rest of the player will remain HTML5-based, including the main video, assuming the main video wasn't already playing in a Flash renderer. See Flash Video Rendering for details on Flash video rendering.

Q: Which browsers and browser versions work with Player V4?

A: See Supported Environments for the Player V4 Skin for a full list of browsers to use with Player V4.

Q: How do I embed Player V4 into my website?

A: See Embedding Player V4 on a Web Page for detailed developer documentation on how to embed Player V4 into your website. See Embedding an Asset for documentation on how to copy the Player V4 embed code from Backlot.

Q: Can I use a JavaScript package manager to self-host my JavaScript dependencies for using Player V4, and what are the hosting requirements?

A: You can use a JavaScript package manager to host your Player V4 files. All resources that you host (JS, static files, and other resources) must be CORS-enabled. See Cross-Origin Resource Sharing (CORS) for details on CORS. You can include all player plugins and core code in a single JavaScript file if you wish. Please ensure that the core player is included before any other plugins. CSS files should be loaded separately.

Q: Why should I host player resources (plugins, images, and so on) myself? What are the advantages of doing this?


Ooyala hosts default Player V4 resources that are updated automatically. You have the option to host Player V4 resources yourself, including plugins, your HTML skin configuration file, images, and other resources. Advantages to hosting the plugins and files yourself include:
  • You can optimize fast downloads for your personal routes.
  • You can optimize even more by downloading these files and then concatenating all of your plugins and core into a single file which allows everything to download at once. This is faster and more reliable.
  • If you are making any player look and feel customizations you will need to host skin configuration files anyway, so it will not be much more effort to host more files at the same endpoint.

Customizing Player V4

Q: What can I configure in the new player?
A: Player V4 is highly customizable. You can:
  • Enable Discovery content recommendation.
  • Configure the player look and feel (skin) using a JSON config file, by specifying player settings directly in HTML pages, or by modifying the Player CSS and resources (see Customizing the Player V4 Appearance) .
  • Use the message bus to make additional event-driven customizations.
  • Localize player controls and error messages.
  • Configure HTML5 or Flash video rendering. Note that all of the plugins, ad logic, UI, Player APIs, etc. are always in HTML5. The only Flash component is video decoding and rendering for HDS and DASH. See Flash Video Rendering for details on Flash video rendering.

Q: Can I customize the Player V4 UI with Backlot

A: Yes - see Configuring a Player in Backlot. You can also make customizations to the player by customizing the player CSS or the skin.json config file (see Configuring a Player in Backlot).

Q: How can I add another social sharing option to the player (beyond the default Facebook, Twitter, Google Plus)?

A: You can add additional social sharing options by altering the skin code directly. The code associated with social sharing is located in the html5-skin repository at html5-skin/js/views/shareScreen.js.

Q: How can I add a watermark image clickthrough URL?

A: You can specify a watermark image clickthrough URL in Backlot (PUBLISH > Player Branding > Branding), or in skin.json (specifically with controlBar.watermark.clickUrl). See Customizing the Player V4 Skin with skin.json for details on how to modify skin.json.

Q: How do I configure autoplay with embedded parameters?

A: See the player embedded parameter documentation for details on how to use the autoplay parameter. Set autoplay to true to enable autoplay behavior.

Q: How can I remove items from the control bar?

A: You can delete unneeded items from the buttons array in the skin.json config file.

Q: What are best practices for setting my video container size?

A: If you know your video aspect ratio, set the video container size to a size that corresponds to the aspect ratio of the video.

Q: If I customize the player, will Ooyala Technical Support help me debug my code?

A: Ooyala will support any pre-defined and valid modifications to the skin.json file. If you fork the skin-config repository and make non-valid modifications, or if you fork the html5-skin repository and make changes, we will not offer technical support for these changes.

Q: I'm using the same skin.json file for my webpages and mobile apps, but the player skins are not exactly the same. Why is this happening?

A: This is a known issue. You can use the same skin.json file for your web players and mobile apps - the same file is used for both, but at some points in time parts of skin.json might not work on the both platforms (for example, the icon color for the replay button is not supported for mobile yet). We will eventually reach full parity here.

Using Video Plugins to Decode and Render Video Streams

See Loading Video Plugins for details.

Q: Does “encodingPriority": ["hls", "mp4", "dash”] mean that first the player will try to load an HLS stream, then if it is not available, it will try to load an MP4 stream, then if it is not available, it will try to load a dash stream, and so on?

A: The video controller will only attempt to select a single stream. Encoding priority is a way to set the stream preference order. Internally the player will look at what stream type is available and what stream type is playable by the video plugins you’ve loaded on the page and will try to play the first available stream.

Q: Why are the video plugins (like main_html5.min.js) separate from the core player (core.min.js) if at least one is always required?

A: Player V4 is build in a modular way to allow for maximum customization. The file core.min.js gives you the platform with which to integrate the other plugins. The video plugins are kept separate from core.min.js so you can customize which video playback engine you want to use and selectively playback video formats.

Q: Can I specify the starting bitrate for adaptive bitrate (ABR)?

A: Yes, see Programming Bitrates and Buffering for Player V4 Using JavaScript for details on how to do this.

Q: Should I use DASH?

A: DASH is a type of encode that you can add to your processing profile. To playback on Android devices, people generally use MP4. MP4 does not have adaptive streaming technology. If you want to have support for ABR in Android, then add DASH encoding to your processing profile by contacting Ooyala Technical Support. DASH is recommended if you would like to provide an HLS streaming using the v4 HTML5 player. DASH DRM is not supported for this release.

If DASH encoding is added to your processing profile, you might have to re-process your assets in order to leverage DASH encoding for your existing assets. Please note that DASH migration is not mandatory.

Q: Why does HLS need to be rendered in Flash for all browsers when using the Bitmovin plugin?

A: Player V4 supports MPEG-DASH and HLS across most browsers and devices. See Player V4 Stream Support for a breakdown of which streams are supported with which browser versions and devices. Certain browsers still rely on Flash plugins for certain stream types. For example, HLS only works with Safari for native HTML5, and is not officially supported anywhere else on desktop browsers (for example, Chrome and Firefox).

Ooyala understands that most of the open web is moving away from Flash and towards HTML5, and we are committed to adopt emerging and (still) maturing W3C standards like Media Source Extensions to eventually achieve a Flash-free player. While MSE is the underlying framework to support ISO MPEG-DASH across browsers without the use of Flash plugins, there are still significant efforts being done to make it compatible and standardize towards Apple HLS with various solutions still being market-vetted. This said, Ooyala are now in the process of scoping its Flash-free solution to render HLS with the use of MSE. This allows our customers to more broadly cover Android devices as well, attaining a single stream format that works across devices with HLS being the primary streaming choice. While MPEG-DASH is getting mainstream, we think the adoption rate is slow enough that it doesn't (yet) force publishers to demand support - this will eventually happen, but the pace is slow. The good news is that our Player V4 supports both providing our customers guaranteed flexibility to support as many browser-device permutation possible. Note that our MPEG-DASH support uses MSE, and our customers are free to start using the format with our player!

As the drive to end Flash continues, we are aggressively exerting efforts to start leveraging HTML5's Media Source Extension, as it matures, to render HLS without the Flash plugin on web browsers, and it's a priority for Ooyala to completely move away from Flash. As the trend continues, Ooyala will eventually consolidate OTT playback on HTML-MSE going forward.

Q: Why do some of the video plugins (Bitmovin and OSMF Flash) still have the ability to render video in Flash? I thought the industry was moving away from Flash?

A: Despite industry and market-wide calls for Flash's demise, majority of websites and browsers still use the aging browser plugin. Maybe the demise of Flash has been well positioned, but since October last year Adobe has continuously rolled out a significant number of security patches on Flash to resolve critical vulnerabilities. Flash is still present on desktop mainly due to the still maturing HTML5 media playback to achieve feature parity across browsers (e.g. ads monetization, streaming formats and required functionality required for premium DRM content).

Existing Flash ad creatives in the market today is also still significant, a reason why browsers are still unable to completely remove the Flash plugin. In terms of fragmentation, Flash-based rich media ad campaigns have been slow to move to HTML5. In 2015, blocking Flash resulted to 5 billion ads impressions wasted on mobile, this means that the same number of impressions would've loaded on desktop/laptops through Flash plugins. Market data also indicates that only 45% of rich media ads delivered to mobile devices were in HTML5 format, with the remaining 55% being Flash-based creatives. At Ooyala, we made sure that our player is able to cater to both Flash and HTML5 ads creatives, allowing our ads ecosystem to support both IAB standards VPAID 1.0 (Flash-based ads) and 2.0 (HTML5-JS based ads) on our HTML5 player. All indications point to a slow process of browsers completely removing the Flash plugin, but we are convinced that it will eventually happen and are well prepared with our full-HTML5 player control for a consistent player frameworks and UI/UX look and feel.

Using Ad Plugins to Play Ads

See Ads in Player V4 for details.

Q: Do I need to ask Ooyala Technical Support to enable anything for Player V4 ad plugins to work?

A: If you are creating ad sets in Backlot, you need to ask Ooyala Technical Support to enable ad managers for your account, but other than that, all you need to do is load the plugins on your page.

How do the ad plugins interact with the player?

A: Ad plugins interact with the V4 player through the Ad Manager Framework, a unified framework that handles basic ad functionality, which allows ad managers to plug into Ooyala with less effort.

Q: How is integrating with ad managers different in Player V4 compared to Player V3?

A: Player V4 is built in a modular way, where ad functionality is implemented using different plugins. See Player V4 Plugins for the full list of plugins available. With the new Ad Manager Framework for Player V4, configuration parameters and some page level settings are different from Player V3. If you don't have any page level overrides to Backlot settings, your ads will have full backwards compatibility. See Migrating to Player V4 for full details on what configuration parameters and page level settings have changed.

Q: Does Player V4 integrate with Pulse?

A: Yes. There is a Pulse plugin for Player V4 (HTML5). Pulse also currently integrates with the iOS and Android video SDKs. See Ooyala Pulse Ad Plugin for details.

Q: What happened to the showInAdControlBar and showAdMarquee parameters from Player V3?

A: The showInAdControlBar and showAdMarquee parameters are deprecated in Player V4.
  • For the FreeWheel ad plugin and the VAST and VPAID ad plugin rendering VAST 2.0/3.0 ads, you can customize control bar and ad marquee settings by modifying the skin.json file.
  • For the Google IMA ad plugin and the VAST and VPAID plugin rendering VPAID 2.0 ads, the ad control bar and ad marquee configurations in skin.json are ignored (and are forcibly set to off) because both of these render ads and the UI, which can have interactivity at various locations unknown to the plugins themselves. Rather than risk blocking any interactivity with our ad marquee or ad control bar, we made sure to hide them.

Q: Does Player V4 support Ooyala Ads (Backlot content served as video ads)?

A: No, Player V4 does not support Ooyala Ads. Use VAST ads or Ooyala Pulse instead.

Troubleshooting Player V4

Q: I'm seeing the player frame expand to an extremely large size. What's happening?

A: Player V4 has new responsive design features. By default, as long as the container 's width is bounded, the height will dynamically adjust according to the video's aspect ratio. If you already know the aspect ratio of the video, you can also try to override the skin.json setting to fix the skin's aspect ratio. Change the value of aspectRatio (shown below) in skin.json to your video's aspect ratio. You can calculate the aspect ratio using height / width * 100. For a 4:3 video, 3 / 4 * 100 = 75, and for a 16:9 video, 9 / 16 * 100 = 56.25.
"responsive": {
    "breakpoints": {
    "aspectRatio": "auto"  

Q: I copied from your example on GitHub but I'm getting 404 errors related to the page referencing local files. Why is this happening?

A: Our example on GitHub uses the default skin.json file (see Ooyala-hosted Player V4 Resources), which references 3 files: config/es.json, config/en.json, and config/zh.json, which are our default localization files for the player. If you want to use our example out of the box, you'll need to get those files to resolve. You can either download and modify skin.json to point to absolute file paths, or copy the three language files into your website's file structure (such as

Q: My Player was working in December of 2015, but now I'm getting an error that says I need to add a video plugin. What is happening?

A: As of the January 2016 Player V4 release, you must load at least one video plugin when loading your player. For example, you could load the Main Video Plugin in the page header after you load core.min.js.
Note: Wherever you see url_where_hosted in sample code, replace this (in your code) with the URL that points to where the resource is hosted. For a list of Ooyala-hosted paths, see Ooyala-hosted Player V4 Resources. The URL can point to a location on the same host (internal link) or on a separate host (prefixed with http:// or https://). If you host resources yourself (see Hosting Player V4 Resources), be sure to check for any path dependencies within the files.
<script type="text/javascript" src="url_where_hosted/main_html5.min.js"></script>

Q: My control bar and ad marquee settings in skin.json are being ignored. Why is this happening?

A: For the Google IMA ad plugin and the VAST and VPAID plugin rendering VPAID 2.0 ads, the ad control bar and ad marquee configurations in skin.json are ignored (and are forcibly set to off) because both of these render ads and the UI, which can have interactivity at various locations unknown to the plugins themselves. Rather than risk blocking any interactivity with our ad marquee or ad control bar, we made sure to hide them.

Q: I'm using Player V4 in an iframe, but when my video is shared on other pages (syndicated), my pre-roll ads don't appear with the assets as expected. What is happening?

A: If you self-host your player resources, you can include the necessary ad plugins in the iframe as well so that if your content is syndicated, the associated ads will be shared as well as the video and video player.

Q: I'm seeing poor video quality when the player starts up. How can I improve the video quality?

A: You can use the initialBitrate parameter to set the initial minimum bitrate level (immediately after video playback) and to sustain that level for a specific period of time. For details, see Page-level Parameters for Player V4).

Q: Why are the player buttons now appearing as letters?

A: If you are customizing the player and are now seeing the play button appear as an 'h', then you likely have made reference to the new location of the html5-skin.css file but not the necessary assets directory (particularly the font files within the assets directory). By hosting the assets directory in the same location as your html5-skin.css file, you can resolve the missing icons and even update the icons file with new icons of your own.

Was this article helpful?