vidply 1.0.32 → 1.0.33

package/src/core/Player.js

@@ -82,6 +82,17 @@ export class Player extends EventEmitter {
             volume: 0.8,
             playbackSpeed: 1.0,
             preload: 'metadata',
+            // Optional initial duration (seconds) so UI can show duration
+            // before media metadata is loaded (useful with deferLoad/preload=none).
+            initialDuration: 0,
+            // When enabled, VidPly will not start network loading during init().
+            // - HTML5: does not call element.load() until the first user-initiated play()
+            // - HLS (hls.js): does not load manifest/segments until the first play()
+            // This is useful for pages with many players to avoid high initial bandwidth.
+            deferLoad: false,
+            // When enabled, clicking Audio Description / Sign Language before playback will show
+            // a notice instead of implicitly starting playback/loading.
+            requirePlaybackForAccessibilityToggles: false,
             startTime: 0,
             playsInline: true, // Enable inline playback on iOS (prevents native fullscreen)
 
@@ -190,6 +201,10 @@ export class Player extends EventEmitter {
         this.options.metadataAlerts = this.options.metadataAlerts || {};
         this.options.metadataHashtags = this.options.metadataHashtags || {};
 
+        // Notice UI
+        this.noticeElement = null;
+        this.noticeTimeout = null;
+
         // Storage manager
         this.storage = new StorageManager('vidply');
         
@@ -209,10 +224,11 @@ export class Player extends EventEmitter {
             ended: false,
             buffering: false,
             seeking: false,
+            hasStartedPlayback: false,
             muted: this.options.muted,
             volume: this.options.volume,
             currentTime: 0,
-            duration: 0,
+            duration: Number(this.options.initialDuration) > 0 ? Number(this.options.initialDuration) : 0,
             playbackSpeed: this.options.playbackSpeed,
             fullscreen: false,
             pip: false,
@@ -305,6 +321,59 @@ export class Player extends EventEmitter {
         this.init();
     }
 
+    /**
+     * Show a small in-player notice (non-blocking), also announced to screen readers.
+     */
+    showNotice(message, { timeout = 2500, priority = 'polite' } = {}) {
+        try {
+            if (!message) return;
+            if (!this.container) return;
+
+            // Screen reader announcement (reuse KeyboardManager announcer if available)
+            if (this.keyboardManager?.announce) {
+                this.keyboardManager.announce(message, priority);
+            }
+
+            if (!this.noticeElement) {
+                const el = document.createElement('div');
+                el.className = `${this.options.classPrefix}-notice`;
+                el.setAttribute('role', 'status');
+                el.setAttribute('aria-live', priority);
+                el.setAttribute('aria-atomic', 'true');
+                // Inline styling to avoid requiring CSS rebuilds
+                el.style.position = 'absolute';
+                el.style.left = '0.75rem';
+                el.style.right = '0.75rem';
+                el.style.top = '0.75rem';
+                el.style.zIndex = '9999';
+                el.style.padding = '0.5rem 0.75rem';
+                el.style.borderRadius = '0.5rem';
+                el.style.background = 'rgba(0, 0, 0, 0.75)';
+                el.style.color = '#fff';
+                el.style.fontSize = '0.875rem';
+                el.style.lineHeight = '1.3';
+                el.style.pointerEvents = 'none';
+                this.noticeElement = el;
+                this.container.appendChild(el);
+            }
+
+            this.noticeElement.textContent = message;
+            this.noticeElement.style.display = 'block';
+
+            if (this.noticeTimeout) {
+                clearTimeout(this.noticeTimeout);
+                this.noticeTimeout = null;
+            }
+            this.noticeTimeout = setTimeout(() => {
+                if (this.noticeElement) {
+                    this.noticeElement.style.display = 'none';
+                }
+            }, timeout);
+        } catch (e) {
+            // ignore
+        }
+    }
+
     async init() {
         try {
             this.log('Initializing VidPly player');
@@ -570,9 +639,35 @@ export class Player extends EventEmitter {
                 : this.options.height;
         }
 
+        // If no explicit height is set, ensure video players still have a stable layout box
+        // even before any media is loaded (important for deferLoad + playlists).
+        // We use the element's width/height attributes (e.g. from TYPO3) as aspect ratio.
+        if (this.element.tagName === 'VIDEO' && !this.options.height) {
+            const wAttr = parseInt(this.element.getAttribute('width') || '', 10);
+            const hAttr = parseInt(this.element.getAttribute('height') || '', 10);
+            if (Number.isFinite(wAttr) && Number.isFinite(hAttr) && wAttr > 0 && hAttr > 0) {
+                // Only set if not already defined by CSS/inline style
+                if (!this.container.style.aspectRatio) {
+                    this.container.style.aspectRatio = `${wAttr} / ${hAttr}`;
+                }
+
+                // The actual visual box is the videoWrapper (the video element is 100% height).
+                // Give the wrapper the same aspect ratio so posters render correctly before metadata is loaded.
+                if (this.videoWrapper && !this.videoWrapper.style.aspectRatio) {
+                    this.videoWrapper.style.aspectRatio = `${wAttr} / ${hAttr}`;
+                    // Override default CSS height:100% (which depends on parent having a height)
+                    this.videoWrapper.style.height = 'auto';
+                }
+            }
+        }
+
         // Set poster (convert relative paths to absolute URLs)
         if (this.options.poster && this.element.tagName === 'VIDEO') {
-            this.element.poster = this.resolvePosterPath(this.options.poster);
+            const resolvedPoster = this.resolvePosterPath(this.options.poster);
+            this.element.poster = resolvedPoster;
+            // If we intentionally have no media loaded yet (e.g. deferLoad/playlist),
+            // use poster aspect ratio to size the wrapper so the poster isn't stretched.
+            this.applyPosterAspectRatio(resolvedPoster);
         }
 
         // Create centered play button overlay (only for video)
@@ -596,6 +691,7 @@ export class Player extends EventEmitter {
         });
 
         this.on('play', () => {
+            this.state.hasStartedPlayback = true;
             // Hide poster immediately when playing
             this.hidePosterOverlay();
         });
@@ -615,6 +711,45 @@ export class Player extends EventEmitter {
         }, { once: true });
     }
 
+    /**
+     * Apply aspect ratio to the video wrapper based on the poster's intrinsic size.
+     * This helps render correct poster sizing before media metadata is available.
+     */
+    applyPosterAspectRatio(posterUrl) {
+        try {
+            if (!posterUrl) return;
+            if (this.element.tagName !== 'VIDEO') return;
+            if (!this.videoWrapper) return;
+
+            // If user explicitly configured dimensions, don't override.
+            if (this.options.width || this.options.height) return;
+
+            // Avoid repeated work
+            if (this._posterAspectAppliedFor === posterUrl) return;
+            this._posterAspectAppliedFor = posterUrl;
+
+            const img = new Image();
+            img.decoding = 'async';
+            img.onload = () => {
+                const w = img.naturalWidth;
+                const h = img.naturalHeight;
+                if (!w || !h) return;
+
+                // Apply to wrapper (the actual layout box)
+                this.videoWrapper.style.aspectRatio = `${w} / ${h}`;
+                this.videoWrapper.style.height = 'auto';
+
+                // Also apply to container if not explicitly set
+                if (this.container && !this.container.style.aspectRatio) {
+                    this.container.style.aspectRatio = `${w} / ${h}`;
+                }
+            };
+            img.src = posterUrl;
+        } catch (e) {
+            // ignore
+        }
+    }
+
     createPlayButtonOverlay() {
         // Create complete SVG play button from Icons.js
         this.playButtonOverlay = createPlayOverlay();
@@ -1174,7 +1309,30 @@ export class Player extends EventEmitter {
             } else {
                 // Just reload the current renderer with the updated element
                 this.renderer.media = this.element; // Update media reference
-                this.element.load();
+                if (this.options.deferLoad) {
+                    try {
+                        // Keep configured preload behavior; actual network load is controlled
+                        // by ensureLoaded()/play() when deferLoad is enabled.
+                        this.element.preload = this.options.preload || 'metadata';
+                    } catch (e) {
+                        // ignore
+                    }
+                    // Reset renderer-level deferred flags if present (HTML5/HLS renderers)
+                    if (this.renderer) {
+                        if (typeof this.renderer._didDeferredLoad === 'boolean') {
+                            this.renderer._didDeferredLoad = false;
+                        }
+                        if (typeof this.renderer._hlsSourceLoaded === 'boolean') {
+                            this.renderer._hlsSourceLoaded = false;
+                        }
+                        if ('_pendingSrc' in this.renderer) {
+                            // For HLS, store pending src for the first play() call
+                            this.renderer._pendingSrc = this._pendingSource || this.currentSource || null;
+                        }
+                    }
+                } else {
+                    this.element.load();
+                }
             }
             
             // Clear the renderer switching flag after a delay to catch async errors
@@ -1245,6 +1403,22 @@ export class Player extends EventEmitter {
         }
     }
 
+    /**
+     * Ensure the current renderer has started its initial load (metadata/manifest)
+     * without starting playback. This is useful for playlists to behave like
+     * single videos on selection, while still keeping autoplay off.
+     */
+    ensureLoaded() {
+        try {
+            if (!this.renderer) return;
+            if (typeof this.renderer.ensureLoaded === 'function') {
+                this.renderer.ensureLoaded();
+            }
+        } catch (e) {
+            // ignore
+        }
+    }
+
     /**
      * Check if we need to change renderer type
      * @param {string} src - New source URL
@@ -1293,6 +1467,14 @@ export class Player extends EventEmitter {
     play() {
         if (this.renderer) {
             this.renderer.play();
+            return;
+        }
+
+        // Playlist support: if no renderer exists yet (no initial src),
+        // start playback via playlist selection.
+        if (this.playlistManager && Array.isArray(this.playlistManager.tracks) && this.playlistManager.tracks.length > 0) {
+            const index = this.playlistManager.currentIndex >= 0 ? this.playlistManager.currentIndex : 0;
+            this.playlistManager.play(index, true);
         }
     }
 
@@ -3139,6 +3321,22 @@ export class Player extends EventEmitter {
     }
 
     async toggleAudioDescription() {
+        if (this.options.requirePlaybackForAccessibilityToggles && !this.renderer && this.playlistManager?.tracks?.length) {
+            this.showNotice(i18n.t('player.startPlaybackForAudioDescription'));
+            return;
+        }
+
+        // If user toggles audio description before the first track has been loaded,
+        // remember desired state and start playback so the described source is loaded.
+        if (!this.renderer && this.playlistManager && this.playlistManager.tracks?.length) {
+            this.audioDescriptionManager.desiredState = !this.audioDescriptionManager.desiredState;
+            this.state.audioDescriptionEnabled = this.audioDescriptionManager.desiredState;
+            this.emit(this.audioDescriptionManager.desiredState ? 'audiodescriptionenabled' : 'audiodescriptiondisabled');
+            // Start playback (PlaylistManager.play() will honor desiredState and load described src)
+            this.play();
+            return;
+        }
+
         return this.audioDescriptionManager.toggle();
     }
 
@@ -3488,6 +3686,22 @@ export class Player extends EventEmitter {
     }
 
     toggleSignLanguage() {
+        if (this.options.requirePlaybackForAccessibilityToggles && !this.renderer && this.playlistManager?.tracks?.length) {
+            this.showNotice(i18n.t('player.startPlaybackForSignLanguage'));
+            return;
+        }
+
+        // If user toggles sign language before the first track has been loaded,
+        // enable the overlay and start playback so sign language video sync begins.
+        if (!this.renderer && this.playlistManager && this.playlistManager.tracks?.length) {
+            const wasEnabled = this.signLanguageManager.enabled;
+            const result = this.signLanguageManager.toggle();
+            if (!wasEnabled && this.signLanguageManager.enabled) {
+                this.play();
+            }
+            return result;
+        }
+
         return this.signLanguageManager.toggle();
     }
 

package/src/features/PlaylistManager.js

@@ -128,6 +128,9 @@ export class PlaylistManager {
       this.playlistPanel.parentNode.removeChild(this.playlistPanel);
     }
     
+    // Preserve existing player options so recreated players behave consistently
+    const preservedPlayerOptions = this.player?.options ? { ...this.player.options } : {};
+
     // Remove event listeners before destroying
     if (this.player) {
       this.player.off('ended', this.handleTrackEnd);
@@ -140,7 +143,9 @@ export class PlaylistManager {
     
     // Create new media element with appropriate type
     const mediaElement = document.createElement(elementType);
-    mediaElement.setAttribute('preload', 'metadata');
+    // Respect configured preload (playlists should behave like single videos even with deferLoad)
+    const preloadValue = preservedPlayerOptions.preload || 'metadata';
+    mediaElement.setAttribute('preload', preloadValue);
     
     // For video elements with local media, set poster
     if (elementType === 'video' && track.poster && 
@@ -188,6 +193,8 @@ export class PlaylistManager {
       audioDescriptionDuration: track.audioDescriptionDuration || null,
       signLanguageSrc: track.signLanguageSrc || null
     };
+    // Merge back preserved options (so deferLoad/preload/etc remain active)
+    Object.assign(playerOptions, preservedPlayerOptions);
     
     this.player = new this.PlayerClass(mediaElement, playerOptions);
     
@@ -425,8 +432,11 @@ export class PlaylistManager {
       if (this.options.autoPlayFirst) {
         this.play(0);
       } else {
-        // Load first track without playing
-        this.loadTrack(0);
+        // Behave like a single video: load the first track (metadata/manifest)
+        // but do not start playback.
+        void this.loadTrack(0).catch(() => {
+          // ignore
+        });
       }
     }
     
@@ -436,6 +446,9 @@ export class PlaylistManager {
   
   /**
    * Load a track without playing
+   * This is the playlist equivalent of a "single video initialized but not started yet":
+   * it updates UI selection and loads the media into the player so metadata/manifests
+   * and feature managers can be ready, but it does not start playback.
    * @param {number} index - Track index
    */
   async loadTrack(index) {
@@ -446,12 +459,13 @@ export class PlaylistManager {
     
     const track = this.tracks[index];
     
+    // Always update UI immediately (poster, buttons, duration, etc.).
+    // Note: this is UI-only; actual media loading is performed by player.load() below.
+    this.selectTrack(index);
+    
     // Set guard flag to prevent cascade of next() calls during track change
     this.isChangingTrack = true;
     
-    // Update current index
-    this.currentIndex = index;
-    
     // Check if we should recreate the player for this track type
     if (this.options.recreatePlayers && this.hostElement && this.PlayerClass) {
       const currentMediaType = this.player ? 
@@ -462,9 +476,8 @@ export class PlaylistManager {
       // Recreate if element type is different
       if (currentMediaType !== newElementType) {
         await this.recreatePlayerForTrack(track, false);
-        // Update UI after recreation
-        this.updateTrackInfo(track);
-        this.updatePlaylistUI();
+        // Re-apply selection to the newly created player (poster/tracks/buttons)
+        this.selectTrack(index);
         
         // Emit event
         this.player.emit('playlisttrackchange', {
@@ -482,18 +495,25 @@ export class PlaylistManager {
     }
     
     // Load track into player (normal path)
-    this.player.load({
+    const loadPromise = this.player.load({
       src: track.src,
       type: track.type,
       poster: track.poster,
       tracks: track.tracks || [],
       audioDescriptionSrc: track.audioDescriptionSrc || null,
-      signLanguageSrc: track.signLanguageSrc || null
+      signLanguageSrc: track.signLanguageSrc || null,
+      signLanguageSources: track.signLanguageSources || {}
     });
-    
-    // Update UI
-    this.updateTrackInfo(track);
-    this.updatePlaylistUI();
+
+    // For playlist UX parity with single videos: fetch metadata/manifest now,
+    // but do not start playback.
+    if (this.player?.options?.deferLoad && typeof this.player.ensureLoaded === 'function') {
+      Promise.resolve(loadPromise)
+        .then(() => this.player?.ensureLoaded?.())
+        .catch(() => {
+          // ignore
+        });
+    }
     
     // Emit event
     this.player.emit('playlisttrackchange', {
@@ -507,6 +527,133 @@ export class PlaylistManager {
       this.isChangingTrack = false;
     }, 150);
   }
+
+  /**
+   * Select a track (UI/selection only; does NOT set the media src / does NOT initialize renderer)
+   *
+   * In "B always" playlist mode, you typically want `loadTrack()` on selection so the
+   * selected item behaves like a single video (metadata/manifest loaded, features ready)
+   * without auto-playing.
+   * @param {number} index - Track index
+   */
+  selectTrack(index) {
+    if (index < 0 || index >= this.tracks.length) {
+      console.warn('VidPly Playlist: Invalid track index', index);
+      return;
+    }
+
+    const track = this.tracks[index];
+    this.currentIndex = index;
+
+    // Apply per-track metadata without touching the media source.
+    // This ensures poster + feature buttons (chapters/captions/transcript/sign-language)
+    // can be updated instantly even before any media network activity happens.
+    try {
+      // Poster for video element
+      if (this.player?.element?.tagName === 'VIDEO') {
+        if (track.poster) {
+          const posterUrl = typeof this.player.resolvePosterPath === 'function'
+            ? this.player.resolvePosterPath(track.poster)
+            : track.poster;
+          this.player.element.poster = posterUrl;
+          this.player.applyPosterAspectRatio?.(posterUrl);
+        } else {
+          this.player.element.removeAttribute('poster');
+        }
+      }
+
+      // Update sign language / audio description sources (used for button visibility)
+      this.player.audioDescriptionSrc = track.audioDescriptionSrc || null;
+      this.player.signLanguageSrc = track.signLanguageSrc || null;
+      this.player.signLanguageSources = track.signLanguageSources || {};
+
+      // Fill duration early for UI (progress/time display) without loading media
+      if (track.duration && Number(track.duration) > 0) {
+        this.player.state.duration = Number(track.duration);
+      }
+      // Also sync feature managers (they keep their own copy of sources)
+      if (this.player.audioDescriptionManager) {
+        this.player.audioDescriptionManager.src = track.audioDescriptionSrc || null;
+        // Remember original (non-described) source for switching back later
+        this.player.audioDescriptionManager.originalSource = track.src || this.player.originalSrc || null;
+      }
+      if (this.player.signLanguageManager) {
+        this.player.signLanguageManager.src = track.signLanguageSrc || null;
+        this.player.signLanguageManager.sources = track.signLanguageSources || {};
+        this.player.signLanguageManager.currentLanguage = null;
+      }
+
+      // For audio description switching, remember original source even before first play
+      if (track.src && !this.player.originalSrc) {
+        this.player.originalSrc = track.src;
+      }
+
+      // Replace <track> elements so captions/chapters/transcript can be detected/loaded
+      const existing = Array.from(this.player.element.querySelectorAll('track'));
+      existing.forEach(t => t.remove());
+
+      if (Array.isArray(track.tracks)) {
+        track.tracks.forEach(tc => {
+          if (!tc?.src) return;
+          const el = document.createElement('track');
+          el.src = tc.src;
+          el.kind = tc.kind || 'captions';
+          el.srclang = tc.srclang || 'en';
+          el.label = tc.label || tc.srclang || 'Track';
+          if (tc.default) el.default = true;
+          if (tc.describedSrc) {
+            el.setAttribute('data-desc-src', tc.describedSrc);
+          }
+          this.player.element.appendChild(el);
+        });
+      }
+
+      if (typeof this.player.invalidateTrackCache === 'function') {
+        this.player.invalidateTrackCache();
+      }
+
+      // Re-scan described-track metadata for AudioDescriptionManager
+      if (this.player.audioDescriptionManager && typeof this.player.audioDescriptionManager.initFromSourceElements === 'function') {
+        try {
+          this.player.audioDescriptionManager.captionTracks = [];
+          this.player.audioDescriptionManager.initFromSourceElements(this.player.sourceElements, this.player.trackElements);
+        } catch (e) {
+          // ignore
+        }
+      }
+
+      // Refresh caption/transcript managers so menus reflect newly injected <track> elements
+      // (important when we defer MP4/MP3 loading but still want VTT-based UI to work).
+      if (this.player.captionManager && typeof this.player.captionManager.loadTracks === 'function') {
+        try {
+          this.player.captionManager.tracks = [];
+          this.player.captionManager.currentTrack = null;
+          this.player.captionManager.loadTracks();
+        } catch (e) {
+          // ignore
+        }
+      }
+
+      // TranscriptManager reads from TextTracks too; it will be correct after media starts.
+      // For now, we just ensure control bar is rebuilt so the button is present.
+
+      // Rebuild controls so feature buttons appear immediately
+      if (typeof this.player.updateControlBar === 'function') {
+        this.player.updateControlBar();
+      }
+    } catch (e) {
+      // ignore preview errors; selection should still work
+    }
+
+    this.updateTrackInfo(track);
+    this.updatePlaylistUI();
+
+    this.player.emit('playlisttrackselect', {
+      index,
+      item: track,
+      total: this.tracks.length
+    });
+  }
   
   /**
    * Play a specific track
@@ -557,13 +704,24 @@ export class PlaylistManager {
     }
     
     // Load track into player (normal path)
+    // If audio description was toggled before the first play, load the described source directly.
+    let srcToLoad = track.src;
+    if (this.player?.audioDescriptionManager?.desiredState && track.audioDescriptionSrc) {
+      // Preserve original for later toggling back
+      this.player.originalSrc = track.src;
+      this.player.audioDescriptionManager.originalSource = track.src;
+      this.player.audioDescriptionManager.src = track.audioDescriptionSrc;
+      srcToLoad = track.audioDescriptionSrc;
+    }
+
     this.player.load({
-      src: track.src,
+      src: srcToLoad,
       type: track.type,
       poster: track.poster,
       tracks: track.tracks || [],
       audioDescriptionSrc: track.audioDescriptionSrc || null,
-      signLanguageSrc: track.signLanguageSrc || null
+      signLanguageSrc: track.signLanguageSrc || null,
+      signLanguageSources: track.signLanguageSources || {}
     });
     
     // Update UI

package/src/i18n/languages/de.js

@@ -45,6 +45,9 @@ export const de = {
         signLanguageVideo: 'Gebärdensprache-Video',
         closeSignLanguage: 'Gebärdensprache-Video schließen',
         signLanguageSettings: 'Gebärdensprache-Einstellungen',
+        startPlaybackFirst: 'Bitte starten Sie die Wiedergabe zuerst.',
+        startPlaybackForAudioDescription: 'Bitte starten Sie die Wiedergabe zuerst, um die Audiodeskription zu nutzen.',
+        startPlaybackForSignLanguage: 'Bitte starten Sie die Wiedergabe zuerst, um das Gebärdensprache-Video zu nutzen.',
         noChapters: 'Keine Kapitel verfügbar',
         noCaptions: 'Keine Untertitel verfügbar',
         auto: 'Automatisch',

package/src/i18n/languages/en.js

@@ -45,6 +45,9 @@ export const en = {
     signLanguageVideo: 'Sign Language Video',
     closeSignLanguage: 'Close sign language video',
     signLanguageSettings: 'Sign language settings',
+    startPlaybackFirst: 'Please start playback first.',
+    startPlaybackForAudioDescription: 'Please start playback first to use audio description.',
+    startPlaybackForSignLanguage: 'Please start playback first to use sign language video.',
     noChapters: 'No chapters available',
     noCaptions: 'No captions available',
     auto: 'Auto',