Major Update: multi-engine support, new providers: YouTube and Vimeo, better state preservation & system integration, new APIs and more.

Author: alphanull

.gitignore

@@ -10,3 +10,4 @@ index.dev.html
 *.zip
 .DS_Store
 .vscode
+.cursor

CHANGELOG.md

@@ -5,7 +5,59 @@ 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
+
+## [1.3.0] - 2025-12-19
+
+### Added
+
+- **Multi-Engine Architecture**: New pluggable engine system with capability-based selection and runtime switching. Engines can be registered and dynamically selected based on media type and capabilities.
+- **Engine API**: New player methods `addEngine()`, `removeEngine()`, `getEngine()`, `setEngine()`, and `canPlay()` for managing media engines.
+- **Engine Events**: New events `player/engine/set` and `player/engine/switched` for tracking engine changes.
+- **Engine Docs**: New `docs/guides/Engines.md` covering multi-engine usage, capabilities, suspend/resume, events, and namespaced APIs.
+- **YouTube Provider**: Built-in engine for YouTube video playback with full player UI integration.
+- **Vimeo Provider**: Built-in engine for Vimeo video playback with full player UI integration.
+- **Capability-aware Components**: The following components now support the engine capability system, and update themselves on engine switches: `Play`, `PlayOverlay`, `PlaybackRate`, `Loop`, `PictureInPicture`, `Time`, `Title`, `Keyboard`, `Scrubber`, `Subtitles`, `AudioChain`, `AudioControls`, `VideoControls` and `AnalyserVideo`.
+- **Data update-aware components**: the following components are reacting to the new `data/update`event: `Chapters`, `Title` and the new `SubtitlesUi`
+- **State Preservation**: Player state (playback position, paused state, volume, muted state, picture-in-picture) is now preserved (if possible) when switching between media items in playlists.
+- **Data API**: New `data.updateMediaData` API allows for partial media data updates.
+- **Media Session Component**: This new component uses the Media Session API for better support for system media controls, including artwork and playlist support.
+- **UI Wake Lock**: Optional Screen Wake Lock integration to keep the display on while playing and release it on pause/end/errors or when the tab is hidden.
+- **Orientation Lock**: A new option for the Fullscreen Conmponent that controls the screen orientation when entering FS mode.
+- **Script Loader Utility**: New centralized `scriptLoader` utility for loading external JavaScript libraries (Dash.js, Hls.js, ChromeCast API) with deduplication, cancellation support, and improved error handling.
+- **SubtitleUi**: New component which provides subtitle settings independently from the Subtitles component.
+- **Demo Page**: New demo examples for YouTube and Vimeo providers.
+- **Notifications**: New "Warning" display state supported.
+- **Automatic Workspace Folders**: Direct source editing in chrome support via `vite-plugin-devtools-json`.
+
+### Changed
+
+- **ChromeCast Refactoring**: Completely refactored ChromeCast component to work as a media engine with improved state management, better error handling, and unified API integration. In addition, ChromeCCast now also works in secure mode.
+- **Media Component**: Refactored to work as the default `video` engine with capability-based registration.
+- **Data Component**: `data.setMediaIndex` now preserves current media state when options are omitted.
+- **Subtitles Component**: Simplified subtitles component by removing internal menu system.
+- **Streaming Plugins**: Dash.js and Hls.js plugins now use the centralized script loader utility for more reliable library loading with deduplication.
+- **Playlist Navigation**: Playlist now preserves player state (playback position, paused state, volume, muted) when switching between media items.
+- **API Namespace**: Engine-specific APIs now use namespace prefix format (e.g., `video:media.load`, `chromecast:media.play`) to support multiple engines.
+- **Locale Error Messages**: Updated error messages for library loading failures to use dynamic library names and improved messaging.
+- **Enhanced Locale Messages**: Changed locale strings for script loader errors and Picture-in-Picture browser restrictions in all supported languages.
+- **CSS Library**: Updated CSS with various improvements and fixes.
+- **JSDoc Formatting**: Cleaned up JSDoc formatting across the codebase.
+- **JSDoc Configuration**: Updated to version 1.3.0, added canonical URL and sitemap configuration for better SEO.
+- **Know Issues Page**: Moved the "Known Issues" Section in the readme to a dedicated page.
+- **Dependencies**: Updated development dependencies.
+
+### Fixed
+
+- **Script Loading**: Fixed duplicate script loading issues when multiple player instances or components request the same external library.
+- **State Management**: Fixed state not being preserved correctly when switching between different media types (native video, YouTube, Vimeo, etc.).
+- **ChromeCast State**: Fixed ChromeCast state synchronization issues and improved connection handling.
+- **Picture-in-Picture**: Improved Picture-in-Picture support detection and error handling, especially for iframe-embedded videos.
+- **Playlist State**: Fixed playlist not preserving playback state when navigating between items.
+- **Subtitles Rendering**: Improved subtitle rendering when switching between engines.
+- **domSmithInputRange**: Touch interactions now properly respect the `disabled` state.
+- **Mobile UI**: Fixed problem where media would play on first touch inadvertently.
+
+## [1.2.3] - 2025-11-09
 
 ### Added
 
@@ -147,4 +199,4 @@ This project adheres to [Semantic Versioning](https://semver.org) and follows th
 - **Single, zero dependency bundle File** — VisionPlayer bundles all code, styles, SVG assets and language files into a zero-dependency single build artifact – making integration seamless.
 - **Optimized Performance** — GPU-accelerated transitions, minimal reflows, and efficient DOM updates.
 - **Security Features** — Optional Secure Mode with Shadow DOM, API protection and XSS prevention.
-- **1-Minute Setup** — Get from `npm install` to working demo in under 60 seconds with vite dev server.
+- **1-Minute Setup** — Get from `npm install` to working demo in under 60 seconds with vite dev server.

README.md

@@ -17,12 +17,18 @@ The **VisionPlayer** by **[alphanull](https://alphanull.de)** is a highly modula
 
 ## Features
 
+> 🎉 **MAJOR UPDATE** 🎉 VisionPlayer 1.3 introduces a new multi-engine architecture with added YouTube and Vimeo support, along with significant improvements including state preservation
+> when switching media, enhanced third-party script loading, a completely refactored ChromeCast component, support for the Media Session, Orientation & Wake Lock APIs and more.
+> For further information about the new engine architecture, see the [Engines documentation](docs/guides/Engines.md).
+
 - **Fully modular architecture** — Components can be easily added, removed, or replaced without modifying the core, with nearly 50 components already provided.
+- **Multi-Engine Support** — Pluggable engines with capability-based selection and runtime switching.
 - **Native HTML5 video support** — Plays MP4, WebM, and other browser-supported formats.
 - **Multi-language and multi-quality stream selection** — Each stream can offer multiple languages, resolutions, and encodings. Quality can be automatically selected depending on screen resolution.
 - **Streaming support** — DASH and HLS support, both VOD and Live Streaming, fully integrated into the player UI including subtitles, audio and quality selection.
 - **FairPlay, Widevine, and PlayReady DRM** — Encrypted media playback for premium content.
 - **Chromecast and AirPlay** — External device playback handling with full UI synchronization.
+- **External Providers** — Built-in engines for YouTube and Vimeo alongside native playback.
 - **Playback Controls** — Play/pause, scrubber, volume, playback rate, fullscreen, loop and more.
 - **Playlist Management** — Seamless navigation between multiple media items, with optional shuffle and loop modes.
 - **Subtitle support** — WebVTT rendering with support for positioning, all writing modes and built in HTML sanitiser, TTML (IMSC1/EBU-TT-D) handling, and native `<track>` integration for iOS compatibility.
@@ -32,6 +38,7 @@ The **VisionPlayer** by **[alphanull](https://alphanull.de)** is a highly modula
 - **Picture-in-Picture** — Play video in a separate overlay window.
 - **Picture and Audio Controls** — Adjust video brightness, contrast, and more, or fine-tune your audio with a multiband equalizer.
 - **Advanced Accessibility** — Comprehensive accessibility features including Picture & Audio Controls for visual/auditory impairments, keyboard navigation, and screen reader support.
+- **Advanced System Integration**: Wakelock prevents screen from dimming down while playing. Media Session support for system media controls, including artwork and playlists.
 - **Local playback** — Play local media by selecting or dragging and dropping files.
 - **Audio and Video Visualizations** — Including bar visualizer, ambient light effects, and waveform displays.
 - **Extensive Media Data Format** — With support for extensible metadata and multiple media variants, representations, and encodings.
@@ -132,22 +139,21 @@ Additional docs cover the following topics:
 - [**Configuration**](docs/guides/Configuration.md)
 - [**API**](docs/guides/API.md)
 - [**Components**](docs/guides/Components.md)
+- [**Engines**](docs/guides/Engines.md)
 - [**Accessibility**](docs/guides/Accessibility.md)
 - [**Security**](docs/guides/Security.md)
 - [**Shadow Dom**](docs/guides/ShadowDom.md)
 - [**Developing for VisionPlayer**](docs/guides/Development.md)
 
-In addition, a detailed JSDoc documentation covering all modules and their methods, members and events can be generated using `npm run doc`, which then will reside in `/docs/jsdoc`. This generated documentation can also be accessed via the microsite: [VisionPlayer JSDoc](https://visionplayer.io/docs)
+In addition, a detailed JSDoc documentation covering all modules and their methods, members and events can be generated using `npm run doc`, which then will reside in `/docs/jsdoc`. This generated documentation can also be accessed via the microsite: [VisionPlayer JSDoc](https://visionplayer.io/docs/)
 
 ## Browser Support
 
 VisionPlayer supports all major browsers on all platforms (i.e. macOS, iOS, Windows, Android & Linux) released since ~2019-2020 and later, including Chrome (v79+), Firefox (v75+) and Safari (v13+). **Note:** The [Secure Build](docs/guides/Security.md) requires native ES2022 support.
 
 ### Known Issues
 
-- Sharpen Video Filter does not work on Safari - see [https://bugs.webkit.org](https://bugs.webkit.org/show_bug.cgi?id=184601). Not solvable unless Apple gets its act together - and it is generally recommended to use a "proper" browser anyways, like Firefox or Chrome.
-
-- If the ambient visualizer is enabled (as in the demo), you may get the warning *Canvas2D: Multiple readback operations using getImageData are faster with the willReadFrequently attribute set to true.* Actually, with that setting enabled, performance gets **worse** (up to five times!) on both a windows and a mac laptop. However, an Android tablet showed better performance with this setting, while an iPad did not show much difference. Not sure why exactly this is the case - seems like different rendering pipelines are triggered - and what would be the best heuristics to select the optimal setting. So for now, `willReadFrequently` is disabled until the situation is resolved.
+Despite best efforts to make the VisionPlayer a perfect experience there are some known issues which can not be resolved (yet). For a list of current issues, see the [Know Issues Page](docs/guides/KnownIssues.md).
 
 ## License
 

assets/locale/VisionPlayer.ar.json

@@ -68,9 +68,8 @@
                 "accessError": "تعذر الوصول إلى الوسائط."
             },
             "library": {
-                "header": "خطأ في المكتبة",
-                "dashLoadError": "تعذر تحميل مكتبة ‎Dash.js‎.",
-                "hlsLoadError": "تعذر تحميل مكتبة ‎Hls.js‎."
+                "scriptLoaderErrorTitle": "خطأ في التحميل",
+                "scriptLoaderErrorMessage": "تعذر تحميل ${libraryName}. يرجى التحقق من الاتصال والمحاولة مرة أخرى."
             },
             "supportMessage": ""
         },
@@ -109,7 +108,9 @@
         "pip": {
             "title": "صورة داخل صورة",
             "placeholder": "لا يوجد فيديو للعرض",
-            "cancel": "إغلاق ‎PiP‎"
+            "cancel": "إغلاق ‎PiP‎",
+            "iFrameNotEnabled": "وضع صورة داخل صورة محظور من المتصفح.",
+            "enableIframe": "يتطلب المتصفح تفاعلاً مباشراً مع الفيديو قبل بدء وضع صورة داخل صورة. يرجى النقر على منطقة الفيديو مرة واحدة ثم المحاولة مرة أخرى."
         },
         "playlist": {
             "playlist": "قائمة التشغيل",

assets/locale/VisionPlayer.de.json

@@ -68,9 +68,8 @@
                 "accessError": "Auf das Medium konnte nicht zugegriffen werden."
             },
             "library": {
-                "header": "Bibliotheksfehler",
-                "dashLoadError": "Die Dash.js-Bibliothek konnte nicht geladen werden.",
-                "hlsLoadError": "Die Hls.js-Bibliothek konnte nicht geladen werden."
+                "scriptLoaderErrorTitle": "Ladefehler",
+                "scriptLoaderErrorMessage": "${libraryName} konnte nicht geladen werden. Bitte überprüfen Sie Ihre Verbindung und versuchen Sie es erneut."
             },
             "supportMessage": ""
         },
@@ -109,7 +108,9 @@
         "pip": {
             "title": "Bild-in-Bild-Modus",
             "placeholder": "Dieses Video wird gerade im „Bild-in-Bild“-Modus abgespielt.",
-            "cancel": "Bild-in-Bild-Modus verlassen"
+            "cancel": "Bild-in-Bild-Modus verlassen",
+            "iFrameNotEnabled": "Bild-in-Bild wird vom Browser blockiert.",
+            "enableIframe": "Ihr Browser verlangt eine direkte Interaktion mit dem Video, bevor Bild-in-Bild gestartet werden kann. Bitte klicken Sie einmal in den Videobereich und versuchen Sie es erneut."
         },
         "playlist": {
             "playlist": "Abspielliste",

assets/locale/VisionPlayer.en.json

@@ -68,9 +68,8 @@
                 "accessError": "The media could not be accessed."
             },
             "library": {
-                "header": "Library Error",
-                "dashLoadError": "The Dash.js library could not be loaded.",
-                "hlsLoadError": "The Hls.js library could not be loaded."
+                "scriptLoaderErrorTitle": "Load Error",
+                "scriptLoaderErrorMessage": "${libraryName} could not be loaded. Please check your connection and try again."
             },
             "supportMessage": ""
         },
@@ -109,7 +108,9 @@
         "pip": {
             "title": "Picture in Picture",
             "placeholder": "This video is currently playing in Picture-in-Picture mode.",
-            "cancel": "Close Picture in Picture"
+            "cancel": "Close Picture in Picture",
+            "iFrameNotEnabled": "Picture-in-Picture blocked by the browser.",
+            "enableIframe": "Your browser requires a direct user interaction with the video before Picture-in-Picture can start. Please click the video area once and then try again."
         },
         "playlist": {
             "playlist": "Playlist",

assets/locale/VisionPlayer.es.json

@@ -68,9 +68,8 @@
                 "accessError": "No se pudo acceder al medio."
             },
             "library": {
-                "header": "Error de biblioteca",
-                "dashLoadError": "No se pudo cargar la biblioteca Dash.js.",
-                "hlsLoadError": "No se pudo cargar la biblioteca Hls.js."
+                "scriptLoaderErrorTitle": "Error de carga",
+                "scriptLoaderErrorMessage": "No se pudo cargar ${libraryName}. Por favor, verifique su conexión e intente nuevamente."
             },
             "supportMessage": ""
         },
@@ -109,7 +108,9 @@
         "pip": {
             "title": "Imagen en imagen",
             "placeholder": "No hay vídeo para mostrar",
-            "cancel": "Cerrar PiP"
+            "cancel": "Cerrar PiP",
+            "iFrameNotEnabled": "El modo Imagen en imagen está bloqueado por el navegador.",
+            "enableIframe": "Tu navegador requiere una interacción directa con el vídeo antes de iniciar Imagen en imagen. Haz clic una vez en el área del vídeo y vuelve a intentarlo."
         },
         "playlist": {
             "playlist": "Lista de reproducción",

assets/locale/VisionPlayer.fr.json

@@ -68,9 +68,8 @@
                 "accessError": "Impossible d’accéder au média."
             },
             "library": {
-                "header": "Erreur de bibliothèque",
-                "dashLoadError": "La bibliothèque Dash.js n’a pas pu être chargée.",
-                "hlsLoadError": "La bibliothèque Hls.js n’a pas pu être chargée."
+                "scriptLoaderErrorTitle": "Erreur de chargement",
+                "scriptLoaderErrorMessage": "${libraryName} n'a pas pu être chargé. Veuillez vérifier votre connexion et réessayer."
             },
             "supportMessage": ""
         },
@@ -109,7 +108,9 @@
         "pip": {
             "title": "Image dans l’image",
             "placeholder": "Aucune vidéo à afficher",
-            "cancel": "Fermer le PiP"
+            "cancel": "Fermer le PiP",
+            "iFrameNotEnabled": "Le mode Image dans l’image est bloqué par le navigateur.",
+            "enableIframe": "Votre navigateur exige une interaction directe avec la vidéo avant de lancer l’Image dans l’image. Cliquez une fois sur la zone vidéo, puis réessayez."
         },
         "playlist": {
             "playlist": "Liste de lecture",
@@ -139,4 +140,4 @@
             "slider": "Ajuster l’intensité"
         }
     }
-}
+}

assets/locale/VisionPlayer.hi.json

@@ -68,9 +68,8 @@
                 "accessError": "मीडिया तक पहुँच नहीं सका।"
             },
             "library": {
-                "header": "लाइब्रेरी त्रुटि",
-                "dashLoadError": "Dash.js लाइब्रेरी लोड नहीं हो सकी.",
-                "hlsLoadError": "Hls.js लाइब्रेरी लोड नहीं हो सकी."
+                "scriptLoaderErrorTitle": "लोड त्रुटि",
+                "scriptLoaderErrorMessage": "${libraryName} लोड नहीं हो सका। कृपया अपना कनेक्शन जांचें और पुनः प्रयास करें।"
             },
             "supportMessage": ""
         },
@@ -109,7 +108,9 @@
         "pip": {
             "title": "पिक्चर‑इन‑पिक्चर",
             "placeholder": "दिखाने के लिए कोई वीडियो नहीं",
-            "cancel": "PiP बंद करें"
+            "cancel": "PiP बंद करें",
+            "iFrameNotEnabled": "पिक्चर-इन-पिक्चर ब्राउज़र द्वारा अवरुद्ध है।",
+            "enableIframe": "पिक्चर-इन-पिक्चर शुरू होने से पहले आपका ब्राउज़र वीडियो के साथ प्रत्यक्ष इंटरैक्शन चाहता है। कृपया वीडियो क्षेत्र पर एक बार क्लिक करें और फिर से प्रयास करें।"
         },
         "playlist": {
             "playlist": "प्लेलिस्ट",