New Overlay Options

Author: alphanull

CHANGELOG.md

@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](https://semver.org) and follows the [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) format.
 
 ---
+## [1.2.3] - 2026-11-09
+
+### Added
+
+- Overlays: there are new options to control when overlays are shown, by the new `show` property in the overlay item media data.
+  - `always` (default): Overlay is always shown
+  - `start`: Overlay is shown at the start of the media (playback has to be paused as well)
+  - `end`: Overlay is shown at the end of the media (playback has to be paused as well)
+  - `play`: Overlay is shown when the media is playing
+  - `paused`: Overlay is shown when the media is paused
+- Note that when `cueIn` or `cueOut` are specified, the `show` property is overridden.
+
+### Changed
+
+- Overlays: when applying `scale` to images, those are now rendered as regular images (using `object-size`) instead of background images
+- Updated dev dependencies
+
+### Fixed
+
+- Playlist: fixed error when overlays where present, but none of them was a poster image
+
 ## [1.2.2] - 2025-10-29
 
 ### Fixed
@@ -31,7 +52,7 @@ This project adheres to [Semantic Versioning](https://semver.org) and follows th
 - UI: new API `ui.resize` (which forces recalculating player width and height)
 - Overlays: added type `html` for HTML-based overlays
 - Overlays: added option `sanitizeHTML` to prevent XSS attacks from unsafe HTML (enabled by default and enforced in the secure build). This (severely) limits the allowed HTML.
-- Demo: added link on the logo to the new vision.player.io microsite
+- Demo: added link on the logo to the new visionplayer.io microsite
 - Added new default iconset
 - Added options in the UI component to change the iconset back to the filled version
 

assets/scss/ui/overlays.scss

@@ -110,7 +110,7 @@ vision-player {
             background-color: var(--vip-bg);
         }
 
-        &.is-poster {
+        &.is-start {
             background-color: var(--vip-media-bg);
         }
     }

demo/embed/index.html

@@ -109,7 +109,7 @@ <h1>Embedding Examples</h1>
                             --vip-title-viewport-distance: 0px;
                         }
                     </style>
-                    <div id="div-embed" data-vip-config='{"dom":{"shadow":"closed","className":"vip-theme-demo"},"ui":{"alwaysVisible":true}}' data-vip-media='/demo/trailer/visionplayer-trailer.json'></div>
+                    <div id="div-embed" data-vip-config='{"dom":{"shadow":"closed","className":"vip-theme-demo"},"ui":{"iconStyle":"filled","alwaysVisible":true}}' data-vip-media='/demo/trailer/visionplayer-trailer.json'></div>
                     <figcaption>Div tag embedding with simple theming via custom CSS vars in shadow mode</figcaption>
                 </figure>
 

docs/components/ui/Overlays.md

@@ -18,7 +18,7 @@ const playerConfig = {
 | Setting Name  | Type    | Description                                                  |
 | ------------- | ------- | ------------------------------------------------------------ |
 | `adaptLayout` | Boolean | Aligns overlay position with controller and title visibility state. |
-| `sanitizeHTML | Boolean | Sanitizes the HTML of the overlay to prevent XSS attacks. |
+| `sanitizeHTML` | Boolean | Sanitizes the HTML of the overlay to prevent XSS attacks. |
 
 ## Media Data
 
@@ -59,8 +59,9 @@ const mediaData = {
 | `className`          | String |          | Custom classname for this overla item.                       |
 | `alt`                | String |          | Additional `alt` text for the overlay image.                 |
 | `placement`          | String |          | Defines the placement of the image in the viewport. Currently supported are: `center`, `top`, `bottom`, `left`, `right`, `top-left`, `top-right`, `center-left`, `center-right`, `bottom-left`, `bottom-right` |
-| `scale`              | String |          | Defines how to scale the overlay image. Currently supported are: cover, contain. |
+| `scale`              | String |          | Defines how to scale the overlay image. Currently supported are: `cover`, `contain`. |
 | `margin`             | Number |          | Margin (in pixels) which defines the distance of the overlay to the players' viewport. |
+| `show`             | String |            | When the overlay is shown:<ul><li>`always` (default): Overlay is always shown</li> <li>`start`: Overlay is shown at the start of the media (playback has to be paused as well)</li> <li>`end`: Overlay is shown at the end of the media (playback has to be paused as well)</li> <li>`play`: Overlay is shown when the media is playing</li><li>`paused`: Overlay is shown when the media is paused</li></ul> Note that when `cueIn` or `cueOut` are specified, the `show` property is overridden. |
 | `cueIn`              | Number |          | Time (in seconds) at which this overlay item should be displayed. |
 | `cueOut`             | Number |          | Time (in seconds) at which this overlay item should be hidden. |