vidply 1.0.8 → 1.0.10

package/src/core/Player.js

@@ -16,6 +16,7 @@ import {HLSRenderer} from '../renderers/HLSRenderer.js';
 import {createPlayOverlay} from '../icons/Icons.js';
 import {i18n} from '../i18n/i18n.js';
 import {StorageManager} from '../utils/StorageManager.js';
+import {DraggableResizable} from '../utils/DraggableResizable.js';
 
 export class Player extends EventEmitter {
     constructor(element, options = {}) {
@@ -143,6 +144,8 @@ export class Player extends EventEmitter {
             screenReaderAnnouncements: true,
             highContrast: false,
             focusHighlight: true,
+            metadataAlerts: {},
+            metadataHashtags: {},
 
             // Languages
             language: 'en',
@@ -166,6 +169,9 @@ export class Player extends EventEmitter {
             ...options
         };
 
+        this.options.metadataAlerts = this.options.metadataAlerts || {};
+        this.options.metadataHashtags = this.options.metadataHashtags || {};
+
         // Storage manager
         this.storage = new StorageManager('vidply');
         
@@ -209,6 +215,18 @@ export class Player extends EventEmitter {
         this.originalAudioDescriptionSource = null;
         // Store caption tracks that should be swapped for audio description
         this.audioDescriptionCaptionTracks = [];
+        this._audioDescriptionDesiredState = false;
+
+        // DOM query cache (for performance optimization)
+        this._textTracksCache = null;
+        this._textTracksDirty = true;
+        this._sourceElementsCache = null;
+        this._sourceElementsDirty = true;
+        this._trackElementsCache = null;
+        this._trackElementsDirty = true;
+
+        // Timeout management (for cleanup)
+        this.timeouts = new Set();
 
         // Components
         this.container = null;
@@ -217,6 +235,10 @@ export class Player extends EventEmitter {
         this.captionManager = null;
         this.keyboardManager = null;
         this.settingsDialog = null;
+        
+        // Metadata handling
+        this.metadataCueChangeHandler = null;
+        this.metadataAlertHandlers = new Map();
 
         // Initialize
         this.init();
@@ -264,6 +286,9 @@ export class Player extends EventEmitter {
             if (this.options.transcript || this.options.transcriptButton) {
                 this.transcriptManager = new TranscriptManager(this);
             }
+            
+            // Always set up metadata track handling (independent of transcript)
+            this.setupMetadataHandling();
 
             // Initialize keyboard controls
             if (this.options.keyboard) {
@@ -373,7 +398,6 @@ export class Player extends EventEmitter {
         // This allows custom controls to work on iOS devices
         if (this.element.tagName === 'VIDEO' && this.options.playsInline) {
             this.element.setAttribute('playsinline', '');
-            this.element.setAttribute('webkit-playsinline', ''); // For older iOS versions
             this.element.playsInline = true; // Property version
         }
 
@@ -399,6 +423,12 @@ export class Player extends EventEmitter {
         if (this.element.tagName === 'VIDEO') {
             this.createPlayButtonOverlay();
         }
+        
+        // Store reference to player on element for easy access
+        this.element.vidply = this;
+        
+        // Add to static instances array
+        Player.instances.push(this);
 
         // Make video/audio element clickable to toggle play/pause
         this.element.style.cursor = 'pointer';
@@ -408,6 +438,16 @@ export class Player extends EventEmitter {
                 this.toggle();
             }
         });
+
+        this.on('play', () => {
+            this.hidePosterOverlay();
+        });
+
+        this.on('timeupdate', () => {
+            if (this.state.currentTime > 0) {
+                this.hidePosterOverlay();
+            }
+        });
     }
 
     createPlayButtonOverlay() {
@@ -447,7 +487,7 @@ export class Player extends EventEmitter {
         }
 
         // Check for source elements with audio description attributes
-        const sourceElements = this.element.querySelectorAll('source');
+        const sourceElements = this.sourceElements;
         for (const sourceEl of sourceElements) {
             const descSrc = sourceEl.getAttribute('data-desc-src');
             const origSrc = sourceEl.getAttribute('data-orig-src');
@@ -490,7 +530,7 @@ export class Player extends EventEmitter {
         // Check for caption/subtitle tracks with audio description versions
         // Only tracks with explicit data-desc-src attribute are swapped (no auto-detection to avoid 404 errors)
         // Description tracks (kind="descriptions") are NOT swapped - they're for transcripts
-        const trackElements = this.element.querySelectorAll('track');
+        const trackElements = this.trackElements;
         trackElements.forEach(trackEl => {
             const trackKind = trackEl.getAttribute('kind');
             const trackDescSrc = trackEl.getAttribute('data-desc-src');
@@ -537,6 +577,144 @@ export class Player extends EventEmitter {
         this.log(`Using ${renderer.name} renderer`);
         this.renderer = new renderer(this);
         await this.renderer.init();
+        
+        // Invalidate cache after renderer initialization (tracks may have changed)
+        this.invalidateTrackCache();
+    }
+
+    /**
+     * Get cached text tracks array
+     * @returns {Array} Array of text tracks
+     */
+    get textTracks() {
+        if (!this._textTracksCache || this._textTracksDirty) {
+            this._textTracksCache = Array.from(this.element.textTracks || []);
+            this._textTracksDirty = false;
+        }
+        return this._textTracksCache;
+    }
+
+    /**
+     * Get cached source elements array
+     * @returns {Array} Array of source elements
+     */
+    get sourceElements() {
+        if (!this._sourceElementsCache || this._sourceElementsDirty) {
+            this._sourceElementsCache = Array.from(this.element.querySelectorAll('source'));
+            this._sourceElementsDirty = false;
+        }
+        return this._sourceElementsCache;
+    }
+
+    /**
+     * Get cached track elements array
+     * @returns {Array} Array of track elements
+     */
+    get trackElements() {
+        if (!this._trackElementsCache || this._trackElementsDirty) {
+            this._trackElementsCache = Array.from(this.element.querySelectorAll('track'));
+            this._trackElementsDirty = false;
+        }
+        return this._trackElementsCache;
+    }
+
+    /**
+     * Invalidate DOM query cache (call when tracks/sources change)
+     */
+    invalidateTrackCache() {
+        this._textTracksDirty = true;
+        this._trackElementsDirty = true;
+        this._sourceElementsDirty = true;
+    }
+
+    /**
+     * Find a text track by kind and optionally language
+     * @param {string} kind - Track kind (captions, subtitles, descriptions, chapters, metadata)
+     * @param {string} [language] - Optional language code
+     * @returns {TextTrack|null} Found track or null
+     */
+    findTextTrack(kind, language = null) {
+        const tracks = this.textTracks;
+        if (language) {
+            return tracks.find(t => t.kind === kind && t.language === language);
+        }
+        return tracks.find(t => t.kind === kind);
+    }
+
+    /**
+     * Find a source element by attribute
+     * @param {string} attribute - Attribute name (e.g., 'data-desc-src')
+     * @param {string} [value] - Optional attribute value
+     * @returns {Element|null} Found source element or null
+     */
+    findSourceElement(attribute, value = null) {
+        const sources = this.sourceElements;
+        if (value) {
+            return sources.find(el => el.getAttribute(attribute) === value);
+        }
+        return sources.find(el => el.hasAttribute(attribute));
+    }
+
+    /**
+     * Find a track element by its associated TextTrack
+     * @param {TextTrack} track - The TextTrack object
+     * @returns {Element|null} Found track element or null
+     */
+    findTrackElement(track) {
+        return this.trackElements.find(el => el.track === track);
+    }
+
+    showPosterOverlay() {
+        if (!this.videoWrapper || this.element.tagName !== 'VIDEO') {
+            return;
+        }
+
+        const poster =
+            this.element.getAttribute('poster') ||
+            this.element.poster ||
+            this.options.poster;
+
+        if (!poster) {
+            return;
+        }
+
+        this.videoWrapper.style.setProperty('--vidply-poster-image', `url("${poster}")`);
+        this.videoWrapper.classList.add('vidply-forced-poster');
+    }
+
+    hidePosterOverlay() {
+        if (!this.videoWrapper) {
+            return;
+        }
+
+        this.videoWrapper.classList.remove('vidply-forced-poster');
+        this.videoWrapper.style.removeProperty('--vidply-poster-image');
+    }
+
+    /**
+     * Set a managed timeout that will be cleaned up on destroy
+     * @param {Function} callback - Callback function
+     * @param {number} delay - Delay in milliseconds
+     * @returns {number} Timeout ID
+     */
+    setManagedTimeout(callback, delay) {
+        const timeoutId = setTimeout(() => {
+            this.timeouts.delete(timeoutId);
+            callback();
+        }, delay);
+        this.timeouts.add(timeoutId);
+        return timeoutId;
+    }
+
+    /**
+     * Clear a managed timeout
+     * @param {number} timeoutId - Timeout ID to clear
+     */
+    clearManagedTimeout(timeoutId) {
+        if (timeoutId) {
+            clearTimeout(timeoutId);
+            this.timeouts.delete(timeoutId);
+        }
     }
 
     /**
@@ -557,8 +735,9 @@ export class Player extends EventEmitter {
             }
 
             // Clear existing text tracks
-            const existingTracks = this.element.querySelectorAll('track');
+            const existingTracks = this.trackElements;
             existingTracks.forEach(track => track.remove());
+            this.invalidateTrackCache();
 
             // Update media element
             this.element.src = config.src;
@@ -586,6 +765,7 @@ export class Player extends EventEmitter {
 
                     this.element.appendChild(track);
                 });
+                this.invalidateTrackCache();
             }
 
             // Check if we need to change renderer type
@@ -895,7 +1075,7 @@ export class Player extends EventEmitter {
     // Audio Description
     async enableAudioDescription() {
         // Check if we have source elements with data-desc-src (even if audioDescriptionSrc is not set)
-        const hasSourceElementsWithDesc = Array.from(this.element.querySelectorAll('source')).some(el => el.getAttribute('data-desc-src'));
+        const hasSourceElementsWithDesc = this.sourceElements.some(el => el.getAttribute('data-desc-src'));
         const hasTracksWithDesc = this.audioDescriptionCaptionTracks.length > 0;
         
         if (!this.audioDescriptionSrc && !hasSourceElementsWithDesc && !hasTracksWithDesc) {
@@ -906,6 +1086,11 @@ export class Player extends EventEmitter {
         // Store current playback state
         const currentTime = this.state.currentTime;
         const wasPlaying = this.state.playing;
+        const shouldKeepPoster = !wasPlaying && currentTime === 0;
+
+        if (shouldKeepPoster) {
+            this.showPosterOverlay();
+        }
 
         // Store swapped tracks for transcript reload (declare at function scope)
         let swappedTracksForTranscript = [];
@@ -916,7 +1101,7 @@ export class Player extends EventEmitter {
             const currentSrc = this.element.currentSrc || this.element.src;
             
             // Find the source element that matches the currently active source
-            const sourceElements = Array.from(this.element.querySelectorAll('source'));
+            const sourceElements = this.sourceElements;
             let sourceElementToUpdate = null;
             let descSrc = this.audioDescriptionSrc;
             
@@ -1060,11 +1245,12 @@ export class Player extends EventEmitter {
                         // After all new tracks are added, force browser to reload media element again
                         // This ensures new track elements are processed and new TextTrack objects are created
                         this.element.load();
+                        this.invalidateTrackCache();
                         
                         // Wait for loadedmetadata event before accessing new TextTrack objects
                         const setupNewTracks = () => {
                             // Wait a bit more for browser to fully process the new track elements
-                            setTimeout(() => {
+                            this.setManagedTimeout(() => {
                                 swappedTracksForTranscript.forEach((trackInfo) => {
                                     const trackElement = trackInfo.trackElement;
                                     const newTextTrack = trackElement.track;
@@ -1119,7 +1305,7 @@ export class Player extends EventEmitter {
             // Update all source elements that have data-desc-src to their described versions
             // Force browser to pick up changes by removing and re-adding source elements
             // Get source elements (may have been defined in if block above, but get fresh list here)
-            const allSourceElements = Array.from(this.element.querySelectorAll('source'));
+            const allSourceElements = this.sourceElements;
             const sourcesToUpdate = [];
             
             allSourceElements.forEach((sourceEl) => {
@@ -1173,8 +1359,17 @@ export class Player extends EventEmitter {
                 if (sourceInfo.descSrc) {
                     newSource.setAttribute('data-desc-src', sourceInfo.descSrc);
                 }
-                this.element.appendChild(newSource);
+                const firstTrack = this.element.querySelector('track');
+                if (firstTrack) {
+                    this.element.insertBefore(newSource, firstTrack);
+                } else {
+                    this.element.appendChild(newSource);
+                }
             });
+
+            // Ensure cached source references are refreshed after rebuilding the list
+            this._sourceElementsDirty = true;
+            this._sourceElementsCache = null;
             
             // Force reload by calling load() on the element
             // This should pick up the new src attributes from the re-added source elements
@@ -1193,28 +1388,23 @@ export class Player extends EventEmitter {
             // Wait a bit more for tracks to be recognized and loaded after video metadata loads
             await new Promise(resolve => setTimeout(resolve, 300));
 
-            // Hide poster if video hasn't started yet (poster should hide when we seek or play)
-            if (this.element.tagName === 'VIDEO' && currentTime === 0 && !wasPlaying) {
-                // Force poster to hide by doing a minimal seek or loading first frame
-                // Setting readyState check or seeking to 0.001 seconds will hide the poster
-                if (this.element.readyState >= 1) { // HAVE_METADATA
-                    // Seek to a tiny fraction to trigger poster hiding without actually moving
-                    this.element.currentTime = 0.001;
-                    // Then seek back to 0 after a brief moment to ensure poster stays hidden
-                    setTimeout(() => {
-                        this.element.currentTime = 0;
-                    }, 10);
-                }
+            // Restore playback position (avoid forcing first frame if still at start)
+            if (currentTime > 0) {
+                this.seek(currentTime);
             }
 
-            // Restore playback position
-            this.seek(currentTime);
-
             if (wasPlaying) {
                 this.play();
             }
 
+            if (!shouldKeepPoster) {
+                this.hidePosterOverlay();
+            }
+
             // Update state and emit event
+            if (!this._audioDescriptionDesiredState) {
+                return;
+            }
             this.state.audioDescriptionEnabled = true;
             this.emit('audiodescriptionenabled');
         } else {
@@ -1374,7 +1564,7 @@ export class Player extends EventEmitter {
             }
             
             // Check if we have source elements with data-desc-src (fallback method)
-            const fallbackSourceElements = Array.from(this.element.querySelectorAll('source'));
+            const fallbackSourceElements = this.sourceElements;
             const hasSourceElementsWithDesc = fallbackSourceElements.some(el => el.getAttribute('data-desc-src'));
             
             if (hasSourceElementsWithDesc) {
@@ -1433,6 +1623,7 @@ export class Player extends EventEmitter {
                 
                 // Force reload
                 this.element.load();
+                this.invalidateTrackCache();
             } else {
                 // Fallback to updating element src directly (for videos without source elements)
                 this.element.src = this.audioDescriptionSrc;
@@ -1456,14 +1647,16 @@ export class Player extends EventEmitter {
                 // Seek to a tiny fraction to trigger poster hiding without actually moving
                 this.element.currentTime = 0.001;
                 // Then seek back to 0 after a brief moment to ensure poster stays hidden
-                setTimeout(() => {
+                this.setManagedTimeout(() => {
                     this.element.currentTime = 0;
                 }, 10);
             }
         }
 
-        // Restore playback position
-        this.seek(currentTime);
+        // Restore playback position (avoid forcing first frame if still at start)
+        if (currentTime > 0) {
+            this.seek(currentTime);
+        }
 
         if (wasPlaying) {
             this.play();
@@ -1521,7 +1714,9 @@ export class Player extends EventEmitter {
                 const onMetadataLoaded = () => {
                     // Get fresh track references from the video element's textTracks collection
                     // This ensures we get the actual textTrack objects that the browser created
-                    const allTextTracks = Array.from(this.element.textTracks);
+                    // Invalidate cache first to get fresh tracks after swap
+                    this.invalidateTrackCache();
+                    const allTextTracks = this.textTracks;
                     
                     // Find the tracks that match our swapped tracks by language and kind
                     // Match by checking the track element's src attribute
@@ -1541,9 +1736,7 @@ export class Player extends EventEmitter {
                                 if (track.language === srclang && 
                                     (track.kind === kind || (kind === 'captions' && track.kind === 'subtitles'))) {
                                     // Verify the src matches
-                                    const trackElementForTrack = Array.from(this.element.querySelectorAll('track')).find(
-                                        el => el.track === track
-                                    );
+                                    const trackElementForTrack = this.findTrackElement(track);
                                     if (trackElementForTrack) {
                                         const actualSrc = trackElementForTrack.getAttribute('src');
                                         if (actualSrc === expectedSrc) {
@@ -1557,9 +1750,7 @@ export class Player extends EventEmitter {
                         
                         // Verify the track element's src matches what we expect
                         if (foundTrack) {
-                            const trackElement = Array.from(this.element.querySelectorAll('track')).find(
-                                el => el.track === foundTrack
-                            );
+                            const trackElement = this.findTrackElement(foundTrack);
                             if (trackElement && trackElement.getAttribute('src') !== expectedSrc) {
                                 return null;
                             }
@@ -1570,7 +1761,7 @@ export class Player extends EventEmitter {
                     
                     if (freshTracks.length === 0) {
                         // Fallback: just reload after delay - transcript manager will find tracks itself
-                        setTimeout(() => {
+                        this.setManagedTimeout(() => {
                             if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
                                 this.transcriptManager.loadTranscriptData();
                             }
@@ -1591,7 +1782,7 @@ export class Player extends EventEmitter {
                         if (loadedCount >= freshTracks.length) {
                             // Give a bit more time for cues to be fully parsed
                             // Also ensure we're getting the latest TextTrack references
-                            setTimeout(() => {
+                            this.setManagedTimeout(() => {
                                 if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
                                     // Force transcript manager to get fresh track references
                                     // Clear any cached track references by forcing a fresh read
@@ -1599,12 +1790,11 @@ export class Player extends EventEmitter {
                                     // which should now have the new TextTrack objects with the described captions
                                     
                                     // Verify the tracks have the correct src before reloading transcript
-                                    const allTextTracks = Array.from(this.element.textTracks);
+                                    this.invalidateTrackCache();
+                                    const allTextTracks = this.textTracks;
                                     const swappedTrackSrcs = swappedTracks.map(t => t.describedSrc);
                                     const hasCorrectTracks = freshTracks.some(track => {
-                                        const trackEl = Array.from(this.element.querySelectorAll('track')).find(
-                                            el => el.track === track
-                                        );
+                                        const trackEl = this.findTrackElement(track);
                                         return trackEl && swappedTrackSrcs.includes(trackEl.getAttribute('src'));
                                     });
                                     
@@ -1624,9 +1814,7 @@ export class Player extends EventEmitter {
                         
                         // Check if track has cues loaded
                         // Verify the track element's src matches the expected described src
-                        const trackElementForTrack = Array.from(this.element.querySelectorAll('track')).find(
-                            el => el.track === track
-                        );
+                        const trackElementForTrack = this.findTrackElement(track);
                         const actualSrc = trackElementForTrack ? trackElementForTrack.getAttribute('src') : null;
                         
                         // Find the expected src from swappedTracks
@@ -1657,13 +1845,13 @@ export class Player extends EventEmitter {
                             // Wait for track to load
                             const onTrackLoad = () => {
                                 // Wait a bit for cues to be fully parsed
-                                setTimeout(checkLoaded, 300);
+                                this.setManagedTimeout(checkLoaded, 300);
                             };
                             
                             if (track.readyState >= 2) {
                                 // Already loaded, but might not have cues yet
                                 // Wait a bit and check again
-                                setTimeout(() => {
+                                this.setManagedTimeout(() => {
                                     if (track.cues && track.cues.length > 0) {
                                         checkLoaded();
                                     } else {
@@ -1685,16 +1873,16 @@ export class Player extends EventEmitter {
                 // Wait for loadedmetadata event which fires when browser processes track elements
                 // Also wait for the tracks to be fully processed after the second load()
                 const waitForTracks = () => {
-                    // Wait a bit more to ensure new TextTrack objects are created
-                    setTimeout(() => {
-                        if (this.element.readyState >= 1) { // HAVE_METADATA
-                            onMetadataLoaded();
-                        } else {
-                            this.element.addEventListener('loadedmetadata', onMetadataLoaded, { once: true });
-                            // Fallback timeout
-                            setTimeout(onMetadataLoaded, 2000);
-                        }
-                    }, 500); // Wait 500ms after second load() for tracks to be processed
+                        // Wait a bit more to ensure new TextTrack objects are created
+                        this.setManagedTimeout(() => {
+                            if (this.element.readyState >= 1) { // HAVE_METADATA
+                                onMetadataLoaded();
+                            } else {
+                                this.element.addEventListener('loadedmetadata', onMetadataLoaded, { once: true });
+                                // Fallback timeout
+                                this.setManagedTimeout(onMetadataLoaded, 2000);
+                            }
+                        }, 500); // Wait 500ms after second load() for tracks to be processed
                 };
                 
                 waitForTracks();
@@ -1715,6 +1903,14 @@ export class Player extends EventEmitter {
             }
         }
 
+        if (!shouldKeepPoster) {
+            this.hidePosterOverlay();
+        }
+
+        if (!this._audioDescriptionDesiredState) {
+            return;
+        }
+
         this.state.audioDescriptionEnabled = true;
         this.emit('audiodescriptionenabled');
     }
@@ -1739,7 +1935,7 @@ export class Player extends EventEmitter {
         
         // Swap source elements back to original versions
         // Check if we have source elements with data-orig-src
-        const allSourceElements = Array.from(this.element.querySelectorAll('source'));
+        const allSourceElements = this.sourceElements;
         const hasSourceElementsToSwap = allSourceElements.some(el => el.getAttribute('data-orig-src'));
         
         if (hasSourceElementsToSwap) {
@@ -1789,8 +1985,17 @@ export class Player extends EventEmitter {
                 if (sourceInfo.descSrc) {
                     newSource.setAttribute('data-desc-src', sourceInfo.descSrc);
                 }
-                this.element.appendChild(newSource);
+                const firstTrack = this.element.querySelector('track');
+                if (firstTrack) {
+                    this.element.insertBefore(newSource, firstTrack);
+                } else {
+                    this.element.appendChild(newSource);
+                }
             });
+
+            // Ensure cached source references are refreshed after rebuilding the list
+            this._sourceElementsDirty = true;
+            this._sourceElementsCache = null;
             
             // Force reload
             this.element.load();
@@ -1801,31 +2006,44 @@ export class Player extends EventEmitter {
             this.element.load();
         }
 
-        // Wait for new source to load
-        await new Promise((resolve) => {
-            const onLoadedMetadata = () => {
-                this.element.removeEventListener('loadedmetadata', onLoadedMetadata);
-                resolve();
-            };
-            this.element.addEventListener('loadedmetadata', onLoadedMetadata);
-        });
+        if (currentTime > 0 || wasPlaying) {
+            // Wait for new source to load
+            await new Promise((resolve) => {
+                const onLoadedMetadata = () => {
+                    this.element.removeEventListener('loadedmetadata', onLoadedMetadata);
+                    resolve();
+                };
+                this.element.addEventListener('loadedmetadata', onLoadedMetadata);
+            });
 
-        // Restore playback position
-        this.seek(currentTime);
+            if (currentTime > 0) {
+                this.seek(currentTime);
+            }
 
-        if (wasPlaying) {
-            this.play();
+            if (wasPlaying) {
+                this.play();
+            }
         }
 
-        // Reload transcript if visible (after video metadata loaded, tracks should be available)
-        // Reload regardless of whether caption tracks were swapped, in case tracks changed
-        if (this.transcriptManager && this.transcriptManager.isVisible) {
-            // Wait for tracks to load after source swap
-            setTimeout(() => {
-                if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
-                    this.transcriptManager.loadTranscriptData();
-                }
-            }, 500);
+        if (!wasPlaying && currentTime === 0) {
+            this.showPosterOverlay();
+        } else {
+            this.hidePosterOverlay();
+        }
+
+            // Reload transcript if visible (after video metadata loaded, tracks should be available)
+            // Reload regardless of whether caption tracks were swapped, in case tracks changed
+            if (this.transcriptManager && this.transcriptManager.isVisible) {
+                // Wait for tracks to load after source swap
+                this.setManagedTimeout(() => {
+                    if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
+                        this.transcriptManager.loadTranscriptData();
+                    }
+                }, 500);
+            }
+
+        if (this._audioDescriptionDesiredState) {
+            return;
         }
 
         this.state.audioDescriptionEnabled = false;
@@ -1834,32 +2052,63 @@ export class Player extends EventEmitter {
 
     async toggleAudioDescription() {
         // Check if we have description tracks or audio-described video
-        const textTracks = Array.from(this.element.textTracks || []);
-        const descriptionTrack = textTracks.find(track => track.kind === 'descriptions');
+        const descriptionTrack = this.findTextTrack('descriptions');
         
         // Check if we have audio-described video source (either from options or source elements with data-desc-src)
         const hasAudioDescriptionSrc = this.audioDescriptionSrc || 
-            Array.from(this.element.querySelectorAll('source')).some(el => el.getAttribute('data-desc-src'));
+            this.sourceElements.some(el => el.getAttribute('data-desc-src'));
         
         if (descriptionTrack && hasAudioDescriptionSrc) {
             // We have both: toggle description track AND swap caption tracks/sources
             if (this.state.audioDescriptionEnabled) {
+                this._audioDescriptionDesiredState = false;
                 // Disable: toggle description track off and swap captions/sources back
                 descriptionTrack.mode = 'hidden';
                 await this.disableAudioDescription();
             } else {
+                this._audioDescriptionDesiredState = true;
                 // Enable: swap caption tracks/sources and toggle description track on
                 await this.enableAudioDescription();
-                descriptionTrack.mode = 'showing';
+                // Wait for tracks to be ready after source swap, then enable description track
+                // Use a longer timeout to ensure tracks are loaded after source swap
+                const enableDescriptionTrack = () => {
+                    this.invalidateTrackCache();
+                    const descTrack = this.findTextTrack('descriptions');
+                    if (descTrack) {
+                        // Set to 'hidden' first if it's in 'disabled' mode, then to 'showing'
+                        if (descTrack.mode === 'disabled') {
+                            descTrack.mode = 'hidden';
+                            // Use setTimeout to ensure the browser processes the mode change
+                            this.setManagedTimeout(() => {
+                                descTrack.mode = 'showing';
+                            }, 50);
+                        } else {
+                            descTrack.mode = 'showing';
+                        }
+                    } else if (this.element.readyState < 2) {
+                        // Tracks not ready yet, wait a bit more
+                        this.setManagedTimeout(enableDescriptionTrack, 100);
+                    }
+                };
+                // Wait for metadata to load first
+                if (this.element.readyState >= 1) {
+                    this.setManagedTimeout(enableDescriptionTrack, 200);
+                } else {
+                    this.element.addEventListener('loadedmetadata', () => {
+                        this.setManagedTimeout(enableDescriptionTrack, 200);
+                    }, { once: true });
+                }
             }
         } else if (descriptionTrack) {
             // Only description track, no audio-described video source to swap
             // Toggle description track
             if (descriptionTrack.mode === 'showing') {
+                this._audioDescriptionDesiredState = false;
                 descriptionTrack.mode = 'hidden';
                 this.state.audioDescriptionEnabled = false;
                 this.emit('audiodescriptiondisabled');
             } else {
+                this._audioDescriptionDesiredState = true;
                 descriptionTrack.mode = 'showing';
                 this.state.audioDescriptionEnabled = true;
                 this.emit('audiodescriptionenabled');
@@ -1867,8 +2116,10 @@ export class Player extends EventEmitter {
         } else if (hasAudioDescriptionSrc) {
             // Use audio-described video source (no description track)
             if (this.state.audioDescriptionEnabled) {
+                this._audioDescriptionDesiredState = false;
                 await this.disableAudioDescription();
             } else {
+                this._audioDescriptionDesiredState = true;
                 await this.enableAudioDescription();
             }
         }
@@ -1998,235 +2249,27 @@ export class Player extends EventEmitter {
     setupSignLanguageInteraction() {
         if (!this.signLanguageWrapper) return;
 
-        let isDragging = false;
-        let isResizing = false;
-        let resizeDirection = null;
-        let startX = 0;
-        let startY = 0;
-        let startLeft = 0;
-        let startTop = 0;
-        let startWidth = 0;
-        let startHeight = 0;
-        let dragMode = false;
-        let resizeMode = false;
-
-        // Mouse drag on video element
-        const onMouseDownVideo = (e) => {
-            if (e.target !== this.signLanguageVideo) return;
-            e.preventDefault();
-            isDragging = true;
-            startX = e.clientX;
-            startY = e.clientY;
-            const rect = this.signLanguageWrapper.getBoundingClientRect();
-            startLeft = rect.left;
-            startTop = rect.top;
-            this.signLanguageWrapper.classList.add('vidply-sign-dragging');
-        };
-
-        // Mouse resize on handles
-        const onMouseDownHandle = (e) => {
-            if (!e.target.classList.contains('vidply-sign-resize-handle')) return;
-            e.preventDefault();
-            e.stopPropagation();
-            isResizing = true;
-            resizeDirection = e.target.getAttribute('data-direction');
-            startX = e.clientX;
-            startY = e.clientY;
-            const rect = this.signLanguageWrapper.getBoundingClientRect();
-            startLeft = rect.left;
-            startTop = rect.top;
-            startWidth = rect.width;
-            startHeight = rect.height;
-            this.signLanguageWrapper.classList.add('vidply-sign-resizing');
-        };
-
-        const onMouseMove = (e) => {
-            if (isDragging) {
-                const deltaX = e.clientX - startX;
-                const deltaY = e.clientY - startY;
-                
-                // Get videoWrapper and container dimensions
-                const videoWrapperRect = this.videoWrapper.getBoundingClientRect();
-                const containerRect = this.container.getBoundingClientRect();
-                const wrapperRect = this.signLanguageWrapper.getBoundingClientRect();
-                
-                // Calculate videoWrapper position relative to container
-                const videoWrapperLeft = videoWrapperRect.left - containerRect.left;
-                const videoWrapperTop = videoWrapperRect.top - containerRect.top;
-                
-                // Calculate new position (in client coordinates)
-                let newLeft = startLeft + deltaX - containerRect.left;
-                let newTop = startTop + deltaY - containerRect.top;
-                
-                const controlsHeight = 95; // Height of controls when visible
-                
-                // Constrain to videoWrapper bounds (ensuring it stays above controls)
-                newLeft = Math.max(videoWrapperLeft, Math.min(newLeft, videoWrapperLeft + videoWrapperRect.width - wrapperRect.width));
-                newTop = Math.max(videoWrapperTop, Math.min(newTop, videoWrapperTop + videoWrapperRect.height - wrapperRect.height - controlsHeight));
-                
-                this.signLanguageWrapper.style.left = `${newLeft}px`;
-                this.signLanguageWrapper.style.top = `${newTop}px`;
-                this.signLanguageWrapper.style.right = 'auto';
-                this.signLanguageWrapper.style.bottom = 'auto';
-                // Remove position classes
-                this.signLanguageWrapper.classList.remove(...Array.from(this.signLanguageWrapper.classList).filter(c => c.startsWith('vidply-sign-position-')));
-            } else if (isResizing) {
-                const deltaX = e.clientX - startX;
-                
-                // Get videoWrapper and container dimensions
-                const videoWrapperRect = this.videoWrapper.getBoundingClientRect();
-                const containerRect = this.container.getBoundingClientRect();
-                
-                let newWidth = startWidth;
-                let newLeft = startLeft - containerRect.left;
-
-                // Only resize width, let height auto-adjust to maintain aspect ratio
-                if (resizeDirection.includes('e')) {
-                    newWidth = Math.max(150, startWidth + deltaX);
-                    // Constrain width to not exceed videoWrapper right edge
-                    const maxWidth = (videoWrapperRect.right - startLeft);
-                    newWidth = Math.min(newWidth, maxWidth);
-                }
-                if (resizeDirection.includes('w')) {
-                    const proposedWidth = Math.max(150, startWidth - deltaX);
-                    const proposedLeft = startLeft + (startWidth - proposedWidth) - containerRect.left;
-                    // Constrain to not go beyond videoWrapper left edge
-                    const videoWrapperLeft = videoWrapperRect.left - containerRect.left;
-                    if (proposedLeft >= videoWrapperLeft) {
-                        newWidth = proposedWidth;
-                        newLeft = proposedLeft;
-                    }
-                }
-
-                this.signLanguageWrapper.style.width = `${newWidth}px`;
-                this.signLanguageWrapper.style.height = 'auto'; // Let video maintain aspect ratio
-                if (resizeDirection.includes('w')) {
-                    this.signLanguageWrapper.style.left = `${newLeft}px`;
-                }
-                this.signLanguageWrapper.style.right = 'auto';
-                this.signLanguageWrapper.style.bottom = 'auto';
-                // Remove position classes
-                this.signLanguageWrapper.classList.remove(...Array.from(this.signLanguageWrapper.classList).filter(c => c.startsWith('vidply-sign-position-')));
-            }
-        };
-
-        const onMouseUp = () => {
-            if (isDragging || isResizing) {
-                this.saveSignLanguagePreferences();
-            }
-            isDragging = false;
-            isResizing = false;
-            resizeDirection = null;
-            this.signLanguageWrapper.classList.remove('vidply-sign-dragging', 'vidply-sign-resizing');
-        };
-
-        // Keyboard controls
-        const onKeyDown = (e) => {
-            // Toggle drag mode with D key
-            if (e.key === 'd' || e.key === 'D') {
-                dragMode = !dragMode;
-                resizeMode = false;
-                this.signLanguageWrapper.classList.toggle('vidply-sign-keyboard-drag', dragMode);
-                this.signLanguageWrapper.classList.remove('vidply-sign-keyboard-resize');
-                e.preventDefault();
-                return;
-            }
-
-            // Toggle resize mode with R key
-            if (e.key === 'r' || e.key === 'R') {
-                resizeMode = !resizeMode;
-                dragMode = false;
-                this.signLanguageWrapper.classList.toggle('vidply-sign-keyboard-resize', resizeMode);
-                this.signLanguageWrapper.classList.remove('vidply-sign-keyboard-drag');
-                e.preventDefault();
-                return;
-            }
-
-            // Escape to exit modes
-            if (e.key === 'Escape') {
-                dragMode = false;
-                resizeMode = false;
-                this.signLanguageWrapper.classList.remove('vidply-sign-keyboard-drag', 'vidply-sign-keyboard-resize');
-                e.preventDefault();
-                return;
-            }
-
-            // Arrow keys for drag/resize
-            if (['ArrowUp', 'ArrowDown', 'ArrowLeft', 'ArrowRight'].includes(e.key)) {
-                const step = e.shiftKey ? 10 : 5;
-                const rect = this.signLanguageWrapper.getBoundingClientRect();
-                
-                // Get videoWrapper and container bounds
-                const videoWrapperRect = this.videoWrapper.getBoundingClientRect();
-                const containerRect = this.container.getBoundingClientRect();
-                
-                // Calculate videoWrapper position relative to container
-                const videoWrapperLeft = videoWrapperRect.left - containerRect.left;
-                const videoWrapperTop = videoWrapperRect.top - containerRect.top;
-
-                if (dragMode) {
-                    // Get current position relative to container
-                    let left = rect.left - containerRect.left;
-                    let top = rect.top - containerRect.top;
-
-                    if (e.key === 'ArrowLeft') left -= step;
-                    if (e.key === 'ArrowRight') left += step;
-                    if (e.key === 'ArrowUp') top -= step;
-                    if (e.key === 'ArrowDown') top += step;
-
-                    const controlsHeight = 95; // Height of controls when visible
-                    
-                    // Constrain to videoWrapper bounds (ensuring it stays above controls)
-                    left = Math.max(videoWrapperLeft, Math.min(left, videoWrapperLeft + videoWrapperRect.width - rect.width));
-                    top = Math.max(videoWrapperTop, Math.min(top, videoWrapperTop + videoWrapperRect.height - rect.height - controlsHeight));
-
-                    this.signLanguageWrapper.style.left = `${left}px`;
-                    this.signLanguageWrapper.style.top = `${top}px`;
-                    this.signLanguageWrapper.style.right = 'auto';
-                    this.signLanguageWrapper.style.bottom = 'auto';
-                    // Remove position classes
-                    this.signLanguageWrapper.classList.remove(...Array.from(this.signLanguageWrapper.classList).filter(c => c.startsWith('vidply-sign-position-')));
-                    this.saveSignLanguagePreferences();
-                    e.preventDefault();
-                } else if (resizeMode) {
-                    let width = rect.width;
-
-                    // Only adjust width, height will auto-adjust to maintain aspect ratio
-                    if (e.key === 'ArrowLeft') width -= step;
-                    if (e.key === 'ArrowRight') width += step;
-                    // Up/Down also adjusts width for simplicity
-                    if (e.key === 'ArrowUp') width += step;
-                    if (e.key === 'ArrowDown') width -= step;
-
-                    // Constrain width
-                    width = Math.max(150, width);
-                    // Don't let it exceed videoWrapper width
-                    width = Math.min(width, videoWrapperRect.width);
-
-                    this.signLanguageWrapper.style.width = `${width}px`;
-                    this.signLanguageWrapper.style.height = 'auto';
-                    this.saveSignLanguagePreferences();
-                    e.preventDefault();
-                }
-            }
-        };
-
-        // Attach event listeners
-        this.signLanguageVideo.addEventListener('mousedown', onMouseDownVideo);
-        const handles = this.signLanguageWrapper.querySelectorAll('.vidply-sign-resize-handle');
-        handles.forEach(handle => handle.addEventListener('mousedown', onMouseDownHandle));
-        document.addEventListener('mousemove', onMouseMove);
-        document.addEventListener('mouseup', onMouseUp);
-        this.signLanguageWrapper.addEventListener('keydown', onKeyDown);
+        // Get resize handles
+        const resizeHandles = Array.from(this.signLanguageWrapper.querySelectorAll('.vidply-sign-resize-handle'));
+
+        // Create DraggableResizable utility
+        this.signLanguageDraggable = new DraggableResizable(this.signLanguageWrapper, {
+            dragHandle: this.signLanguageVideo,
+            resizeHandles: resizeHandles,
+            constrainToViewport: true,
+            maintainAspectRatio: true,
+            minWidth: 150,
+            minHeight: 100,
+            classPrefix: 'vidply-sign',
+            keyboardDragKey: 'd',
+            keyboardResizeKey: 'r',
+            keyboardStep: 5,
+            keyboardStepLarge: 10
+        });
 
         // Store for cleanup
         this.signLanguageInteractionHandlers = {
-            mouseDownVideo: onMouseDownVideo,
-            mouseDownHandle: onMouseDownHandle,
-            mouseMove: onMouseMove,
-            mouseUp: onMouseUp,
-            keyDown: onKeyDown,
-            handles
+            draggable: this.signLanguageDraggable
         };
     }
 
@@ -2317,23 +2360,14 @@ export class Player extends EventEmitter {
             this.signLanguageHandlers = null;
         }
 
-        // Remove interaction handlers
-        if (this.signLanguageInteractionHandlers) {
-            if (this.signLanguageVideo) {
-                this.signLanguageVideo.removeEventListener('mousedown', this.signLanguageInteractionHandlers.mouseDownVideo);
-            }
-            if (this.signLanguageInteractionHandlers.handles) {
-                this.signLanguageInteractionHandlers.handles.forEach(handle => {
-                    handle.removeEventListener('mousedown', this.signLanguageInteractionHandlers.mouseDownHandle);
-                });
-            }
-            document.removeEventListener('mousemove', this.signLanguageInteractionHandlers.mouseMove);
-            document.removeEventListener('mouseup', this.signLanguageInteractionHandlers.mouseUp);
-            if (this.signLanguageWrapper) {
-                this.signLanguageWrapper.removeEventListener('keydown', this.signLanguageInteractionHandlers.keyDown);
-            }
-            this.signLanguageInteractionHandlers = null;
+        // Destroy draggable utility
+        if (this.signLanguageDraggable) {
+            this.signLanguageDraggable.destroy();
+            this.signLanguageDraggable = null;
         }
+        
+        // Clear interaction handlers reference
+        this.signLanguageInteractionHandlers = null;
 
         // Remove video and wrapper elements
         if (this.signLanguageWrapper && this.signLanguageWrapper.parentNode) {
@@ -2397,9 +2431,28 @@ export class Player extends EventEmitter {
     }
 
     // Logging
-    log(message, type = 'log') {
-        if (this.options.debug) {
-            console[type](`[VidPly]`, message);
+    log(...messages) {
+        if (!this.options.debug) {
+            return;
+        }
+
+        let type = 'log';
+        if (messages.length > 0) {
+            const potentialType = messages[messages.length - 1];
+            if (typeof potentialType === 'string' && console[potentialType]) {
+                type = potentialType;
+                messages = messages.slice(0, -1);
+            }
+        }
+
+        if (messages.length === 0) {
+            messages = [''];
+        }
+
+        if (typeof console[type] === 'function') {
+            console[type]('[VidPly]', ...messages);
+        } else {
+            console.log('[VidPly]', ...messages);
         }
     }
 
@@ -2434,7 +2487,10 @@ export class Player extends EventEmitter {
                 }
 
                 if (this.transcriptManager && this.transcriptManager.isVisible) {
-                    this.transcriptManager.positionTranscript();
+                    // Only auto-position if user hasn't manually moved it
+                    if (!this.transcriptManager.draggableResizable || !this.transcriptManager.draggableResizable.manuallyPositioned) {
+                        this.transcriptManager.positionTranscript();
+                    }
                 }
             };
 
@@ -2447,7 +2503,10 @@ export class Player extends EventEmitter {
                 // Wait for layout to settle
                 setTimeout(() => {
                     if (this.transcriptManager && this.transcriptManager.isVisible) {
-                        this.transcriptManager.positionTranscript();
+                        // Only auto-position if user hasn't manually moved it
+                        if (!this.transcriptManager.draggableResizable || !this.transcriptManager.draggableResizable.manuallyPositioned) {
+                            this.transcriptManager.positionTranscript();
+                        }
                     }
                 }, 100);
             };
@@ -2493,7 +2552,7 @@ export class Player extends EventEmitter {
                 if (this.signLanguageWrapper && this.signLanguageWrapper.style.display !== 'none') {
                     // Use setTimeout to ensure layout has updated after fullscreen transition
                     // Longer delay to account for CSS transition animations and layout recalculation
-                    setTimeout(() => {
+                    this.setManagedTimeout(() => {
                         // Use requestAnimationFrame to ensure the browser has fully rendered the layout
                         requestAnimationFrame(() => {
                             // Clear saved size and reset to default for the new container size
@@ -2580,6 +2639,29 @@ export class Player extends EventEmitter {
             this.fullscreenChangeHandler = null;
         }
 
+        // Cleanup all managed timeouts
+        this.timeouts.forEach(timeoutId => clearTimeout(timeoutId));
+        this.timeouts.clear();
+
+        // Cleanup metadata handling
+        if (this.metadataCueChangeHandler) {
+            const textTracks = this.textTracks;
+            const metadataTrack = textTracks.find(track => track.kind === 'metadata');
+            if (metadataTrack) {
+                metadataTrack.removeEventListener('cuechange', this.metadataCueChangeHandler);
+            }
+            this.metadataCueChangeHandler = null;
+        }
+
+        if (this.metadataAlertHandlers && this.metadataAlertHandlers.size > 0) {
+            this.metadataAlertHandlers.forEach(({ button, handler }) => {
+                if (button && handler) {
+                    button.removeEventListener('click', handler);
+                }
+            });
+            this.metadataAlertHandlers.clear();
+        }
+
         // Remove container
         if (this.container && this.container.parentNode) {
             this.container.parentNode.insertBefore(this.element, this.container);
@@ -2588,6 +2670,424 @@ export class Player extends EventEmitter {
 
         this.removeAllListeners();
     }
+
+    /**
+     * Setup metadata track handling
+     * This enables metadata tracks and listens for cue changes to trigger actions
+     */
+    setupMetadataHandling() {
+        const setupMetadata = () => {
+            const textTracks = this.textTracks;
+            const metadataTrack = textTracks.find(track => track.kind === 'metadata');
+            
+            if (metadataTrack) {
+                // Enable the metadata track so cuechange events fire
+                // Use 'hidden' mode so it doesn't display anything, but events still work
+                if (metadataTrack.mode === 'disabled') {
+                    metadataTrack.mode = 'hidden';
+                }
+                
+                // Remove existing listener if any
+                if (this.metadataCueChangeHandler) {
+                    metadataTrack.removeEventListener('cuechange', this.metadataCueChangeHandler);
+                }
+                
+                // Add event listener for cue changes
+                this.metadataCueChangeHandler = () => {
+                    const activeCues = Array.from(metadataTrack.activeCues || []);
+                    if (activeCues.length > 0) {
+                        // Debug logging
+                        if (this.options.debug) {
+                            this.log('[Metadata] Active cues:', activeCues.map(c => ({
+                                start: c.startTime,
+                                end: c.endTime,
+                                text: c.text
+                            })));
+                        }
+                    }
+                    activeCues.forEach(cue => {
+                        this.handleMetadataCue(cue);
+                    });
+                };
+                
+                metadataTrack.addEventListener('cuechange', this.metadataCueChangeHandler);
+                
+                // Debug: Log metadata track setup
+                if (this.options.debug) {
+                    const cueCount = metadataTrack.cues ? metadataTrack.cues.length : 0;
+                    this.log('[Metadata] Track enabled,', cueCount, 'cues available');
+                }
+            } else if (this.options.debug) {
+                this.log('[Metadata] No metadata track found');
+            }
+        };
+        
+        // Try immediately
+        setupMetadata();
+        
+        // Also try after loadedmetadata event (tracks might not be ready yet)
+        this.on('loadedmetadata', setupMetadata);
+    }
+
+    normalizeMetadataSelector(selector) {
+        if (!selector) {
+            return null;
+        }
+        const trimmed = selector.trim();
+        if (!trimmed) {
+            return null;
+        }
+        if (trimmed.startsWith('#') || trimmed.startsWith('.') || trimmed.startsWith('[')) {
+            return trimmed;
+        }
+        return `#${trimmed}`;
+    }
+
+    resolveMetadataConfig(map, key) {
+        if (!map || !key) {
+            return null;
+        }
+        if (Object.prototype.hasOwnProperty.call(map, key)) {
+            return map[key];
+        }
+        const withoutHash = key.replace(/^#/, '');
+        if (Object.prototype.hasOwnProperty.call(map, withoutHash)) {
+            return map[withoutHash];
+        }
+        return null;
+    }
+
+    cacheMetadataAlertContent(element, config = {}) {
+        if (!element) {
+            return;
+        }
+        const titleSelector = config.titleSelector || '[data-vidply-alert-title], h3, header';
+        const messageSelector = config.messageSelector || '[data-vidply-alert-message], p';
+
+        const titleEl = element.querySelector(titleSelector);
+        if (titleEl && !titleEl.dataset.vidplyAlertTitleOriginal) {
+            titleEl.dataset.vidplyAlertTitleOriginal = titleEl.textContent.trim();
+        }
+
+        const messageEl = element.querySelector(messageSelector);
+        if (messageEl && !messageEl.dataset.vidplyAlertMessageOriginal) {
+            messageEl.dataset.vidplyAlertMessageOriginal = messageEl.textContent.trim();
+        }
+    }
+
+    restoreMetadataAlertContent(element, config = {}) {
+        if (!element) {
+            return;
+        }
+        const titleSelector = config.titleSelector || '[data-vidply-alert-title], h3, header';
+        const messageSelector = config.messageSelector || '[data-vidply-alert-message], p';
+
+        const titleEl = element.querySelector(titleSelector);
+        if (titleEl && titleEl.dataset.vidplyAlertTitleOriginal) {
+            titleEl.textContent = titleEl.dataset.vidplyAlertTitleOriginal;
+        }
+
+        const messageEl = element.querySelector(messageSelector);
+        if (messageEl && messageEl.dataset.vidplyAlertMessageOriginal) {
+            messageEl.textContent = messageEl.dataset.vidplyAlertMessageOriginal;
+        }
+    }
+
+    focusMetadataTarget(target, fallbackElement = null) {
+        if (!target || target === 'none') {
+            return;
+        }
+
+        if (target === 'alert' && fallbackElement) {
+            fallbackElement.focus();
+            return;
+        }
+
+        if (target === 'player') {
+            if (this.container) {
+                this.container.focus();
+            }
+            return;
+        }
+
+        if (target === 'media') {
+            this.element.focus();
+            return;
+        }
+
+        if (target === 'playButton') {
+            const playButton = this.controlBar?.controls?.playPause;
+            if (playButton) {
+                playButton.focus();
+            }
+            return;
+        }
+
+        if (typeof target === 'string') {
+            const targetElement = document.querySelector(target);
+            if (targetElement) {
+                if (targetElement.tabIndex === -1 && !targetElement.hasAttribute('tabindex')) {
+                    targetElement.setAttribute('tabindex', '-1');
+                }
+                targetElement.focus();
+            }
+        }
+    }
+
+    handleMetadataAlert(selector, options = {}) {
+        if (!selector) {
+            return;
+        }
+
+        const config = this.resolveMetadataConfig(this.options.metadataAlerts, selector) || {};
+        const element = options.element || document.querySelector(selector);
+
+        if (!element) {
+            if (this.options.debug) {
+                this.log('[Metadata] Alert element not found:', selector);
+            }
+            return;
+        }
+
+        if (this.options.debug) {
+            this.log('[Metadata] Handling alert', selector, { reason: options.reason, config });
+        }
+
+        this.cacheMetadataAlertContent(element, config);
+
+        if (!element.dataset.vidplyAlertOriginalDisplay) {
+            element.dataset.vidplyAlertOriginalDisplay = element.style.display || '';
+        }
+
+        if (!element.dataset.vidplyAlertDisplay) {
+            element.dataset.vidplyAlertDisplay = config.display || 'block';
+        }
+
+        const shouldShow = options.show !== undefined ? options.show : (config.show !== false);
+        if (shouldShow) {
+            const displayValue = config.display || element.dataset.vidplyAlertDisplay || 'block';
+            element.style.display = displayValue;
+            element.hidden = false;
+            element.removeAttribute('hidden');
+            element.setAttribute('aria-hidden', 'false');
+            element.setAttribute('data-vidply-alert-active', 'true');
+        }
+
+        const shouldReset = config.resetContent !== false && options.reason === 'focus';
+        if (shouldReset) {
+            this.restoreMetadataAlertContent(element, config);
+        }
+
+        const shouldFocus = options.focus !== undefined
+            ? options.focus
+            : (config.focusOnShow ?? (options.reason !== 'focus'));
+
+        if (shouldShow && shouldFocus) {
+            if (element.tabIndex === -1 && !element.hasAttribute('tabindex')) {
+                element.setAttribute('tabindex', '-1');
+            }
+            element.focus();
+        }
+
+        if (shouldShow && config.autoScroll !== false && options.autoScroll !== false) {
+            element.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+        }
+
+        const continueSelector = config.continueButton;
+        if (continueSelector) {
+            let continueButton = null;
+            if (continueSelector === 'self') {
+                continueButton = element;
+            } else if (element.matches(continueSelector)) {
+                continueButton = element;
+            } else {
+                continueButton = element.querySelector(continueSelector) || document.querySelector(continueSelector);
+            }
+
+            if (continueButton && !this.metadataAlertHandlers.has(selector)) {
+                const handler = () => {
+                    const hideOnContinue = config.hideOnContinue !== false;
+                    if (hideOnContinue) {
+                        const originalDisplay = element.dataset.vidplyAlertOriginalDisplay || '';
+                        element.style.display = config.hideDisplay || originalDisplay || 'none';
+                        element.setAttribute('aria-hidden', 'true');
+                        element.removeAttribute('data-vidply-alert-active');
+                    }
+
+                    if (config.resume !== false && this.state.paused) {
+                        this.play();
+                    }
+
+                    const focusTarget = config.focusTarget || 'playButton';
+                    this.setManagedTimeout(() => {
+                        this.focusMetadataTarget(focusTarget, element);
+                    }, config.focusDelay ?? 100);
+                };
+
+                continueButton.addEventListener('click', handler);
+                this.metadataAlertHandlers.set(selector, { button: continueButton, handler });
+            }
+        }
+
+        return element;
+    }
+
+    handleMetadataHashtags(hashtags) {
+        if (!Array.isArray(hashtags) || hashtags.length === 0) {
+            return;
+        }
+
+        const configMap = this.options.metadataHashtags;
+        if (!configMap) {
+            return;
+        }
+
+        hashtags.forEach(tag => {
+            const config = this.resolveMetadataConfig(configMap, tag);
+            if (!config) {
+                return;
+            }
+
+            const selector = this.normalizeMetadataSelector(config.alert || config.selector || config.target);
+            if (!selector) {
+                return;
+            }
+
+            const element = document.querySelector(selector);
+            if (!element) {
+                if (this.options.debug) {
+                    this.log('[Metadata] Hashtag target not found:', selector);
+                }
+                return;
+            }
+
+        if (this.options.debug) {
+            this.log('[Metadata] Handling hashtag', tag, { selector, config });
+        }
+
+            this.cacheMetadataAlertContent(element, config);
+
+            if (config.title) {
+                const titleSelector = config.titleSelector || '[data-vidply-alert-title], h3, header';
+                const titleEl = element.querySelector(titleSelector);
+                if (titleEl) {
+                    titleEl.textContent = config.title;
+                }
+            }
+
+            if (config.message) {
+                const messageSelector = config.messageSelector || '[data-vidply-alert-message], p';
+                const messageEl = element.querySelector(messageSelector);
+                if (messageEl) {
+                    messageEl.textContent = config.message;
+                }
+            }
+
+            const show = config.show !== false;
+            const focus = config.focus !== undefined ? config.focus : false;
+
+            this.handleMetadataAlert(selector, {
+                element,
+                show,
+                focus,
+                autoScroll: config.autoScroll,
+                reason: 'hashtag'
+            });
+        });
+    }
+
+    /**
+     * Handle individual metadata cues
+     * Parses metadata text and emits events or triggers actions
+     */
+    handleMetadataCue(cue) {
+        const text = cue.text.trim();
+        
+        // Debug logging
+        if (this.options.debug) {
+            this.log('[Metadata] Processing cue:', {
+                time: cue.startTime,
+                text: text
+            });
+        }
+        
+        // Emit a generic metadata event that developers can listen to
+        this.emit('metadata', {
+            time: cue.startTime,
+            endTime: cue.endTime,
+            text: text,
+            cue: cue
+        });
+
+        // Parse for specific commands (examples based on wwa_meta.vtt format)
+        if (text.includes('PAUSE')) {
+            // Automatically pause the video
+            if (!this.state.paused) {
+                if (this.options.debug) {
+                    this.log('[Metadata] Pausing video at', cue.startTime);
+                }
+                this.pause();
+            }
+            // Also emit event for developers who want to listen
+            this.emit('metadata:pause', { time: cue.startTime, text: text });
+        }
+
+        // Parse for focus directives
+        const focusMatch = text.match(/FOCUS:([\w#-]+)/);
+        if (focusMatch) {
+            const targetSelector = focusMatch[1];
+            const normalizedSelector = this.normalizeMetadataSelector(targetSelector);
+            // Automatically focus the target element
+            const targetElement = normalizedSelector ? document.querySelector(normalizedSelector) : null;
+            if (targetElement) {
+                if (this.options.debug) {
+                    this.log('[Metadata] Focusing element:', normalizedSelector);
+                }
+                // Make element focusable if it isn't already
+                if (targetElement.tabIndex === -1 && !targetElement.hasAttribute('tabindex')) {
+                    targetElement.setAttribute('tabindex', '-1');
+                }
+                // Use setTimeout to ensure DOM is ready
+                this.setManagedTimeout(() => {
+                    targetElement.focus();
+                    // Scroll element into view if needed
+                    targetElement.scrollIntoView({ behavior: 'smooth', block: 'nearest' });
+                }, 10);
+            } else if (this.options.debug) {
+                this.log('[Metadata] Element not found:', normalizedSelector || targetSelector);
+            }
+            // Also emit event for developers who want to listen
+            this.emit('metadata:focus', { 
+                time: cue.startTime, 
+                target: targetSelector,
+                selector: normalizedSelector,
+                element: targetElement,
+                text: text 
+            });
+
+            if (normalizedSelector) {
+                this.handleMetadataAlert(normalizedSelector, {
+                    element: targetElement,
+                    reason: 'focus'
+                });
+            }
+        }
+
+        // Parse for hashtag references
+        const hashtags = text.match(/#[\w-]+/g);
+        if (hashtags) {
+            if (this.options.debug) {
+                this.log('[Metadata] Hashtags found:', hashtags);
+            }
+            this.emit('metadata:hashtags', {
+                time: cue.startTime,
+                hashtags: hashtags,
+                text: text
+            });
+
+            this.handleMetadataHashtags(hashtags);
+        }
+    }
 }
 
 // Static instances tracker for pause others functionality