Player-level overlay
Overview
The player-level overlay, also known as the firmware overlay, allows the player to display an independently managed project on top of the main content. Unlike an overlay layer included within a project, a player-level overlay is configured directly on the player using the URL of an externally hosted project.
It is particularly suited to emergency alerts, evacuation instructions, corporate notifications, building-management messages, and other event-driven content that must appear independently of the project currently playing. The overlay project can be updated without modifying or republishing the main content.
The player-level overlay is rendered above all other content displayed by the player, including alerts managed through ARYA Enterprise.
Requirements:
- Player model: HMP400/W, iBX410/W, iBX440, HMP350, HMP300, and third-party DSOS players
- Firmware version: DSOS 4.8.6 or later
- Feature Set: KIOSK or SYSTEMS
- Web server for deployment
How it works
The player renders the following content:
- The main project published or scheduled on the player.
- An overlay project loaded from the URL specified in the player configuration.
The player-level overlay is rendered above the main project. It behaves as if the top-level index.svg document of the main project contained a full-screen SVG <animation> element referencing the overlay project. Although the overlay is hosted and maintained separately, it is attached to the top-level document of the main project rather than executed as a separate top-level application. This allows the overlay to receive UI events and communicate in both directions with the main content.
A typical deployment consists of:
- A main signage project published or scheduled on the player.
- A dedicated overlay project hosted on a web server.
- An overlay URL specified in the player configuration.
This separation makes it possible to maintain a single alert project centrally instead of adding and maintaining a copy of the alert layer in every main project.
Comparison with other overlay mechanisms
It is possible to create overlayed content through other means, such as:
- In a DSaaS deployment, where the player content is managed through SpinetiX ARYA Enterprise, an alert can be created in ARYA and published on the player to be displayed above the existing scheduled content.
- In a Self-Manage deployment, where the player content is usually created with Elementi, a dedicated layer can be added in the root index file of the Elementi project and positioned on top of everything else. This is referred to as an in-project overlay.
A player-level overlay encompasses both scenarios; is configured directly on the player and is displayed above all other content, including ARYA alerts.
The table below details the differences between these mechanisms:
| Characteristic | ARYA alert | In-project overlay | Player-level overlay |
|---|---|---|---|
| Configuration | Created and managed in ARYA | Added within the Elementi project | Added within the player configuration |
| Source | Alert content managed through ARYA | Part of the published project | External project referenced by URL |
| Scope | Content scheduled on the player through ARYA | The project containing the overlay | All content displayed by the player |
| Deployment | Deployed through ARYA | Published with each project | Configured on each player |
| Maintenance | Updated through ARYA | Requires modifying and republishing the project | Updated independently on the web server |
| Availability | Available to players managed through a SpinetiX cloud account with ARYA Enterprise subscription | Present only in projects that include it | Loaded independently of the existing content |
| Rendering order | Above ARYA-scheduled content | Part of the main project, should be on top of the rest of the content | Above all content, including ARYA alerts |
| Typical purpose | Centrally managed alerts in a DSaaS deployment | Project-specific visuals or interactions | Player-level alerts independent of the content-management system |
Configuration
The player-level overlay is configured through the Configuration API. See more about how to use the Configuration API.
To add or change an overlay, use the <overlay> element with a URL of the overlay project, such as:
<overlay>https://server.example.com/overlay/index.svg</overlay>
In case the server requires authentication, provide them though the <credential> element.
To remove the current player overlay, use an empty <overlay> element:
<overlay/>
The <overlay> tag requires a player reboot to become effective, so make sure to include the <reboot/> tag as well.
Behavior and limitations
The player-level overlay is rendered above the regular content and shares the execution environment of the main project. It can receive UI events and communicate with the main content in both directions.
The overlay does not have separate local storage. It shares local storage with the main project, so developers should use distinct key names to avoid collisions. When inactive, the overlay project should normally remain transparent so that the main content remains visible and usable.
The player may cache the overlay project and its referenced resources. When updating the project on the web server, avoid immediately removing or overwriting resources referenced by the previously published index.svg. A player might continue using a cached copy of that document while downloading its associated resources. If one of those resources is no longer available, playback may stop or the displayed image may freeze. Restarting the player does not necessarily resolve the problem because it does not invalidate cached content. If this situation occurs, reset the player cache to force the overlay project and its resources to be retrieved again.
Best practices
- Use a player-level overlay when content must be maintained independently of the main projects or content-management system.
- Keep the configured overlay URL stable so that updates do not require configuration changes across the player fleet.
- Keep the overlay focused on a clearly defined purpose, such as alerts or notifications.
- Host the overlay project on a reliable web server accessible to every target player.
- When updating the project, retain previously referenced resources for at least as long as players may continue using a cached version of
index.svgand its resources. - Design the overlay to remain transparent when no message is active.
- Use distinct local-storage key names to prevent conflicts with the main project.
- Test UI-event handling and communication with the different main projects used on the player.
- Consider the rendering priority when both ARYA Enterprise alerts and a player-level overlay are configured.