Page tree
Skip to end of metadata
Go to start of metadata

ON THIS PAGE

This page covers the content requirements, abilities, and restrictions of the HTML rendering engine on BrightSign players.

Content Restrictions

The following are content restrictions associated with HTML pages:

Web Browsing

BrightSign players are not intended for use as general-purpose web browsers. It is best to think of BrightSign units as HTML players with interactive capabilities, not web-surfing tools: Each page should be thoroughly tested before being used as digital signage.

Flash Content

BrightSign players do not support Flash content. Any HTML pages that have embedded flash content will not display correctly. Most Flash authoring applications, including the Adobe Creative Suite, have tools that allow you to export flash content as HTML.

Multiple Video Elements

By default, XT, 4K, and XD players support a maximum of two active <video> elements at any time (HD/LS models only support one). You can have more than this amount of <video> elements on a page as long as additional <video> elements have their src attribute set to an empty string. By modifying the src string, you can enable and disable <video> elements on the page.

You can enable Mosiac Mode (using the SetDecoderMode()  JavaScript method) to increase the minimum allowed number of <video> elements.

Small Videos

BrightSign players do not support videos that are less than 64 pixels in width or height. However, a video can be scaled down beyond this limit by making the <video> element smaller than 64x64. To get the desired downscaling behavior, ensure that the <video> element does not have the viewmode="scale-to-fill-and-crop" attribute.

4K Graphics

XTx44, XTx43, XTx34, XDx33, and 4Kx42 models can display HTML pages using 4K video modes (3840x2160 or 4096x2160).

XTx44, XTx43

The XTx44 and XTx43 supports a native 4K HTML graphics plane (see this page for more details). Note the following performance restrictions when using native 4K HTML graphics:

  • Animations will not exceed 20 FPS (and intensive animations may exhibit very low framerates).
  • Non-HWZ video is likewise limited to 20 FPS, so HWZ should be enabled for video elements in native 4K.
  • We recommend displaying only one or two 4K images at a time (for example, a slideshow with a current image and next image preloaded). Images should not exceed 4096x2160 in size. 
  • We recommend using swap memory if possible. 
  • Pages that use many layers may run out of memory in native 4K. Enabling the  gfxmemlarge setting may help mitigate this issue.

4Kx42, XDx34, XDx33

The 4Kx42, XDx34, and XDx33 support graphics up to 1920x1200 (see this page for more details), which can then be upscaled to a 4K video mode. For the 4Kx42 and XDx33 models, pages must be specified as 1920x1080 (or 2048x1080 for DCI 4K); they can then be upscaled to 4K.

Pixel Sizes and Coordinates with 4K Modes

As noted above, webpages are often upscaled when outputting a 4K video mode. Relative CSS property values will scale automatically, but pixel values may need to be modified to account differences between 4K video and graphics. See here for more information about using coordinates with upscaled video modes.

Image Sizes

Images larger than 2048x1280x32bpp (or 4096x2160x32bpp for XT, 4K, XTx34, and XDx33 players) will not be displayed by default. If a 4K video mode is used, the player will upscale images from HD resolution accordingly (though native 4K graphics can be enabled on the XTx43). The default limit can be increased in BrightScript using the roVideoMode.SetImageSizeThreshold() method.

Without altering the default maximum resolution, you can increase the maximum width of images by sacrificing height (e.g. using a 4096x640x32bpp image on non-4K players is allowed). You can also increase the maximum width/height by reducing the bpp value (e.g. using a 4096x1280x16bpp on non-4K players is allowed).

Note

For performance reasons, we recommend against downscaling images. This consumes considerably more resources than either displaying images at their native size or upscaling them.

Memory and Performance

The amount of memory available for HTML applications varies by model:

  • XTx43, XTx44: 512MB for graphics; 512MB for JavaSript

  • XDx33, XDx34: 256MB for graphics; 512MB for JavaScript
  • HDx23/LS243/HO523: 256MB for graphics; 128MB for JavaScript

Notes

  • The memory available for graphics can be reduced by a number of factors, including the number of CSS layers, the complexity of animations, and the use of WebGL.
  • The JavaScript memory is subject to a hard limit: If there is no JavaScript memory after garbage collection, Chromium will terminate the active process.
  • Each HTML widget has its own JavaScript heap, so it's possible to overcommit JavaScript memory if multiple HTML widgets are active.

Tip

Often, the best way to improve graphics performance is to ensure that images are scaled to the desired output resoultion before they are rendered in HTML.

Note

Use the Chromium Web Inspector to determine the amount of resources being used by a webpage.

Web Fonts

If a font file is not included and referenced by the HTML page, text will be rendered using a default system font. While functional, the default font has little aesthetic appeal, so we recommend including font files for most digital-signage applications. Supported font types include TrueType Font files (.ttf), OpenType Font (.otf), and Web Open Font files (.woff.woff2).

DOM Manipulation

We recommend using setAttribute() to manipulate the DOM, rather than using "x.value=y":

	document.getElementById('input-id').setAttribute("value", "name"); //preferred
	document.getElementById('input-id').value = name; //not preferred

Creating HTML Pages

Follow these steps when creating HTML pages:

  1. Make sure the HTML page has the same aspect ratio as your signage display. If you are using HTML content in a BrightAuthor zone that is smaller than the screen, fit the page to the same aspect ratio as the zone.
  2. Use a master Div aligned to 0,0 when building an HTML page. This will ensure correct alignment.
  3. When creating an HTML site, make sure that all webpage assets (image files, video files, etc.) are contained within the same folder on your local disk. This folder is a “site folder,” meaning that all assets in this folder and its subfolders will be used in the production of the webpage. If these assets are not in the folder, they will not display when the project is published.
  4. You can test the layout and appearance of a page locally by opening it with Google Chrome, which has similar rendering capabilities to BrightSign players.
  5. If you want to publish resource-intensive presentations (e.g. <video> elements or multiple transforms) using HTML, we recommend using a Class 10 (10Mb/s) SD card.

BrightSign Extensions

The BrightSign implementation of the Chromium engine includes several platform-specific extensions. Extensions for <video> elements are covered on the HTML Video page.

GPU Rasterization

GPU rasterization is enabled by default in firmware versions 6.2.x and later. 

Optimized Image Rendering

The image-rendering CSS property can be assigned the optimizeSpeedBS value. Using this value ensures that Chromium uses lower-quality but faster bilinear filtering when scaling images to 50% or less. We recommend using this value with pages that scale a lot of images at runtime.

Renderer Versions and Support

The following table describes which version of web-rendering engine is used in each version of BrightSign firmware:

Rendering EngineVersionBrightSign FW Versions
Chromium457.1.x, 7.0.x, 6.2.x
Chromium376.1.x, 6.0.x
WebKit--5.1.x, 5.0.x, 4.8.x, 4.7.x

Tip

You can use this page to determine if specific function calls and extensions are supported in a corresponding version of Chrome.

Animations and Add-on Libraries

This section outlines support for animations and add-on libraries for the Chromium engine on BrightSign players.

JavaScript Animations

Animations that use JavaScript timers, including the JQuery .animate() library, do not make efficient use of GPU resources and are not accurate enough to achieve smooth animations. For this reason, we recommend using CSS animations whenever possible. The JQuery Transit library uses CSS animations and provides an API similar to the .animate() library.

Note

For best results when animating images, we recommend using images at their original size instead of scaling them first. For example, a 480x270 icon will rotate more smoothly if you use an image that is originally 480x270, rather than scaling down a 1280x720 image and then attempting to rotate it.

WebGL

BrightSign players support the OpenGL API for JavaScript (i.e. WebGL). 

Note

Textures will sometimes fail to load in WebGL because they exceed the maximum allowed image size on BrightSign Players. In these cases, you can use roVideoMode.SetImageSizeThreshold() BrightScript method to increase the maximum size for textures.

Vector Animations

The SVG protocol should be used to specify vector animations.

Canvas Animations

Bitmap animations display smoothly when they are 1/3 or less of a 1080p HTML canvas. Setting the canvas size to 720p allows for larger high-quality animations to occupy the screen.

Push Technology

The long polling technique has been tested and proven to work on BrightSign players.

The Websocket protocol is fully supported via the Node.js implementation on the BrightSign Chromium instance. In production environments, we recommend using HTTPS to initiate Websocket connections with a server (i.e using a WSS connection rather than a WS connection).

An example Websocket application is available on the BrightSign Github page.

File Storage

BrightSign players support several file storage/indexing technologies, including Web SQL, IndexedDB, the HTML Filesystem API, and the JavaScript storage class. The location and size of the web storage database should be set during initialization of the roHtmlWidget .

File Downloads

If you're using JavaScript to download files, we reccomend using the Fetch API and Node.js File System module to perform downloads. See here for more details

CSS Transforms

All CSS transforms should be specified as WebKit transforms. When performing a transform on a <div> or graphics element, you should not specify the transform in-line.

The following code shows an example of an effective CSS transform for a BrightSign player:

Example
<style>
 
                .flipme{
                -webkit-animation-name:flipon;
                -webkit-animation-fill-mode:forwards;
                -webkit-animation-iteration-count:1;
                -webkit-animation-duration:2s;
                }
 
 
@-webkit-keyframes flipon
{
0% {-webkit-transform:rotateY(0deg);}
30% {-webkit-transform:rotateY(-90deg);}
100% {-webkit-transform: rotateY(360deg);}
}
 
</style>

Touchscreen Support

BrightSign players are compatible with touchscreens that use standard HID drivers. Note that some manufacturers claim support for HID but still use custom drivers. See this FAQ for further discussion and a list of touchscreen models that have been tested with BrightSign players.

Debugging Webpages 

Web Inspector

You can use the Web Inspector to debug webpages over the local network. The Web Inspector can be enabled using BrightAuthor or BrightScript:

  • BrightAuthor: In your BrightAuthor presentation, navigate to File > Presentation Properties > HTML and check the Enable Javascript console box. Once the presentation with HTML content has been published, use Chrome to access the following URL: http://playerIPAddress:2999 (e.g. http://192.168.1.62:2999/ ).
  • BrightScript: When creating the roHtmlWidget instance, include the inspector_server initialization parameter and specify a port number. You can then use Chrome to access the Web Inspector at http://playerIPAddress:<port>

    If you don't know the player IP address, power on the player with the SD/microSD card (and other storage devices) removed. After a few moments, the IP address will be displayed on screen.

Important

The Web Inspector creates a security vulnerability on the BrightSign player and should be disabled in production environments.

Because BrightSign players use an older version of Chromium than recent desktop versions, newer desktop Chrome releases may not work with the Web Inspector. If you're having trouble using the Web Inspector with your version of Chrome, download and install one of these versions:

Note

If you're using the Web Inspector to manually step through JavaScript code, encountering an uncaught error in the debugger may cause the player to crash. This is a known bug with the Web Inspector.

Trace Events

The Chromium TraceEvent system allows you to debug JavaScript memory leaks, performance issues, and rendering problems. This feature is available in firmware versions 7.0.82 and later. Unlike PCs, where the trace/debugger is run in the same browser as the content, BrightSign players write JSON trace files to the local storage, which you can then import to Chrome on your PC.

When trace events are enabled on a BrightSign player, Chromium captures trace messages to a circular buffer. The player takes regular snapshots of this buffer and writes them to the root directory of the microSD card or SSD as JSON files. 

Important

The TraceEvent system can easily generate gigabytes of log data on local storage, so we recommend disabling it in production environments.

Creating a TraceEvent Directory

Before enabling the TraceEvent system, create a directory named "brightsign-webinspector" in the root directory of the microSD card or SSD on the player. If this directory is missing, the player will not record trace events when they are enabled in the registry. Conversely, you can disable trace events by deleting the "brightsign-webinspector" directory from the storage device.

Enabling the TraceEvent System

The TraceEvent system is enabled and configured by writing to the BrightSign player registry (via BrightScript or JavaScript). To enable the TraceEvent system, write the following keys to the html section of the registry:

  • [string] tracecategories: A comma-separated list of trace event categories to enable. The category names are documented in the link below.
  • [int] tracemaxsnapshots: The maximum number of JSON-trace snapshot files in the "brightsign-webinspector" directory. When the limit is reached, the counter wraps around and begins writing over the oldest trace file.
  • [int] tracemonitorinterval: The frequency (in seconds) with which the player will take snapshots of the TraceEvent buffer. We recommend 60 seconds as a default value.
Example (JavaScript)
var registryClass = require("@brightsign/registry");
var registry = new registryClass();
registry.write("html", {
    "tracecategories": "toplevel,blink_gc,disabled-by-default-memory-infra,disabled-by-default-blink_gc,disabled-by-default.skia.gpu.cache",
    "tracemaxsnapshots": "25",
    "tracemonitorinterval": "60"
}).then(
    function() {
        console.log("Write Successful");
    });

Viewing Trace Events

Follow these steps to view the trace events:

  1. Transfer the JSON trace files from the "brightsign-webinspector" directory to your PC.
  2. Open  chrome://tracing  on your PC Chromium instance.
  3. Import the JSON trace files.

You can merge multiple trace files; however, in a long trace capture, there will be too many trace events to view at once (you'll likely need to write a script to process them).

Additional Documentation

See the following links for further explanation of trace events:

Disabling Staged ES6 Features

Some ES6 features have not been finalized and may still contain bugs in the Chromium version(s) used by BrightSign. A crash may occur if your JavaScript application (or the framework code used to build the application) uses one of these features: For example, this is a known issue in Chromium version 45 that will cause a crash on BrightSign XTx44 and XDx34 players. 

To bypass such issues, you can disable all staged (i.e. experimental) ES6 features using the disable-javascript-harmony-shipping registry flag (which requires firmware version 7.1.49 or later). The following example shows how to set this registry flag using the  registry JavaScript module (you can also use the  roRegistry BrightScript object).

var registryClass = require("@brightsign/registry");
var registry = new registryClass();


var systemClass = require("@brightsign/system");
var system = new systemClass();


registry.write("html", {js-disable-harmony-shipping:"1"}).then(
    function(){console.log("Write Successful");});


system.reboot()

Enabling this registry flag will limit the available JavaScript syntax. However, for ES6 features to be available, an application must be written to be compatible with both ES5 and ES6, so enabling this flag should not cause syntax errors or similar issues.


  • No labels