vidply 1.0.7 → 1.0.9

package/dist/vidply.js

@@ -520,7 +520,8 @@ var VidPly = (() => {
         resizeWindow: "Resize Window",
         styleTranscript: "Open transcript style settings",
         closeMenu: "Close Menu",
-        styleTitle: "Transcript Style"
+        styleTitle: "Transcript Style",
+        autoscroll: "Autoscroll"
       },
       settings: {
         title: "Settings",
@@ -641,7 +642,8 @@ var VidPly = (() => {
         resizeWindow: "Fenster vergr\xF6\xDFern/verkleinern",
         styleTranscript: "Transkript-Stileinstellungen \xF6ffnen",
         closeMenu: "Men\xFC schlie\xDFen",
-        styleTitle: "Transkript-Stil"
+        styleTitle: "Transkript-Stil",
+        autoscroll: "Automatisches Scrollen"
       },
       settings: {
         title: "Einstellungen",
@@ -762,7 +764,8 @@ var VidPly = (() => {
         resizeWindow: "Cambiar tama\xF1o de ventana",
         styleTranscript: "Abrir configuraci\xF3n de estilo de transcripci\xF3n",
         closeMenu: "Cerrar men\xFA",
-        styleTitle: "Estilo de Transcripci\xF3n"
+        styleTitle: "Estilo de Transcripci\xF3n",
+        autoscroll: "Desplazamiento autom\xE1tico"
       },
       settings: {
         title: "Configuraci\xF3n",
@@ -883,7 +886,8 @@ var VidPly = (() => {
         resizeWindow: "Redimensionner la fen\xEAtre",
         styleTranscript: "Ouvrir les param\xE8tres de style de transcription",
         closeMenu: "Fermer le menu",
-        styleTitle: "Style de Transcription"
+        styleTitle: "Style de Transcription",
+        autoscroll: "D\xE9filement automatique"
       },
       settings: {
         title: "Param\xE8tres",
@@ -1004,7 +1008,8 @@ var VidPly = (() => {
         resizeWindow: "\u30A6\u30A3\u30F3\u30C9\u30A6\u306E\u30B5\u30A4\u30BA\u5909\u66F4",
         styleTranscript: "\u6587\u5B57\u8D77\u3053\u3057\u30B9\u30BF\u30A4\u30EB\u8A2D\u5B9A\u3092\u958B\u304F",
         closeMenu: "\u30E1\u30CB\u30E5\u30FC\u3092\u9589\u3058\u308B",
-        styleTitle: "\u6587\u5B57\u8D77\u3053\u3057\u30B9\u30BF\u30A4\u30EB"
+        styleTitle: "\u6587\u5B57\u8D77\u3053\u3057\u30B9\u30BF\u30A4\u30EB",
+        autoscroll: "\u81EA\u52D5\u30B9\u30AF\u30ED\u30FC\u30EB"
       },
       settings: {
         title: "\u8A2D\u5B9A",
@@ -1183,8 +1188,8 @@ var VidPly = (() => {
     language: `<path d="M11.99 2C6.47 2 2 6.48 2 12s4.47 10 9.99 10C17.52 22 22 17.52 22 12S17.52 2 11.99 2zm6.93 6h-2.95c-.32-1.25-.78-2.45-1.38-3.56 1.84.63 3.37 1.91 4.33 3.56zM12 4.04c.83 1.2 1.48 2.53 1.91 3.96h-3.82c.43-1.43 1.08-2.76 1.91-3.96zM4.26 14C4.1 13.36 4 12.69 4 12s.1-1.36.26-2h3.38c-.08.66-.14 1.32-.14 2 0 .68.06 1.34.14 2H4.26zm.82 2h2.95c.32 1.25.78 2.45 1.38 3.56-1.84-.63-3.37-1.9-4.33-3.56zm2.95-8H5.08c.96-1.66 2.49-2.93 4.33-3.56C8.81 5.55 8.35 6.75 8.03 8zM12 19.96c-.83-1.2-1.48-2.53-1.91-3.96h3.82c-.43 1.43-1.08 2.76-1.91 3.96zM14.34 14H9.66c-.09-.66-.16-1.32-.16-2 0-.68.07-1.35.16-2h4.68c.09.65.16 1.32.16 2 0 .68-.07 1.34-.16 2zm.25 5.56c.6-1.11 1.06-2.31 1.38-3.56h2.95c-.96 1.65-2.49 2.93-4.33 3.56zM16.36 14c.08-.66.14-1.32.14-2 0-.68-.06-1.34-.14-2h3.38c.16.64.26 1.31.26 2s-.1 1.36-.26 2h-3.38z"/>`,
     hd: `<path d="M19 3H5c-1.11 0-2 .9-2 2v14c0 1.1.89 2 2 2h14c1.11 0 2-.9 2-2V5c0-1.1-.89-2-2-2zm-8 12H9.5v-2h-2v2H6V9h1.5v2.5h2V9H11v6zm7-1c0 .55-.45 1-1 1h-.75v1.5h-1.5V15H14c-.55 0-1-.45-1-1v-4c0-.55.45-1 1-1h3c.55 0 1 .45 1 1v4zm-3.5-.5h2v-3h-2v3z"/>`,
     transcript: `<path d="M14 2H6c-1.1 0-1.99.9-1.99 2L4 20c0 1.1.89 2 1.99 2H18c1.1 0 2-.9 2-2V8l-6-6zm2 16H8v-2h8v2zm0-4H8v-2h8v2zm-3-5V3.5L18.5 9H13z"/>`,
-    audioDescription: `<rect x="2" y="5" width="20" height="14" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><text x="12" y="16" font-family="Arial, sans-serif" font-size="10" font-weight="bold" text-anchor="middle" fill="currentColor">AD</text>`,
-    audioDescriptionOn: `<rect x="2" y="5" width="20" height="14" rx="2" fill="#1a1a1a" stroke="#1a1a1a" stroke-width="2"/><text x="12" y="16" font-family="Arial, sans-serif" font-size="10" font-weight="bold" text-anchor="middle" fill="#ffffff">AD</text>`,
+    audioDescription: `<rect x="2" y="5" width="20" height="14" rx="2" fill="#ffffff" stroke="#ffffff" stroke-width="2"/><text x="12" y="16" font-family="Arial, sans-serif" font-size="10" font-weight="bold" text-anchor="middle" fill="#1a1a1a">AD</text>`,
+    audioDescriptionOn: `<rect x="2" y="5" width="20" height="14" rx="2" fill="none" stroke="currentColor" stroke-width="2"/><text x="12" y="16" font-family="Arial, sans-serif" font-size="10" font-weight="bold" text-anchor="middle" fill="currentColor">AD</text>`,
     signLanguage: `<g transform="scale(1.5)"><path d="M16 11.3c-.1-.9-4.8 1.3-5.4 1.1-2.6-1 5.8-1.3 5.1-2.9s-5.1 1.5-6 1.4C6.5 9.4 16.5 9.1 13.5 8c-1.9-.6-8.8 2.9-6.8.4.7-.6.7-1.9-.7-1.7-9.7 7.2-.7 12.2 8.8 7 0-1.3-3.5.4-4.1.4-2.6 0 5.6-2 5.4-3ZM3.9 7.8c3.2-4.2 3.7 1.2 6 .1s.2-.2.2-.3c.7-2.7 2.5-7.5-1.5-1.3-1.6 0 1.1-4 1-4.6C8.9-1 7.3 4.4 7.2 4.9c-1.6.7-.9-1.4-.7-1.5 3-6-.6-3.1-.9.4-2.5 1.8 0-2.8 0-3.5C2.8-.9 4 9.4 1.1 4.9S.1 4.6 0 5c-.4 2.7 2.6 7.2 3.9 2.8Z"/></g>`,
     signLanguageOn: `<g transform="scale(1.5)"><path d="M16 11.3c-.1-.9-4.8 1.3-5.4 1.1-2.6-1 5.8-1.3 5.1-2.9s-5.1 1.5-6 1.4C6.5 9.4 16.5 9.1 13.5 8c-1.9-.6-8.8 2.9-6.8.4.7-.6.7-1.9-.7-1.7-9.7 7.2-.7 12.2 8.8 7 0-1.3-3.5.4-4.1.4-2.6 0 5.6-2 5.4-3ZM3.9 7.8c3.2-4.2 3.7 1.2 6 .1s.2-.2.2-.3c.7-2.7 2.5-7.5-1.5-1.3-1.6 0 1.1-4 1-4.6C8.9-1 7.3 4.4 7.2 4.9c-1.6.7-.9-1.4-.7-1.5 3-6-.6-3.1-.9.4-2.5 1.8 0-2.8 0-3.5C2.8-.9 4 9.4 1.1 4.9S.1 4.6 0 5c-.4 2.7 2.6 7.2 3.9 2.8Z"/></g>`,
     speaker: `<path d="M3 9v6h4l5 5V4L7 9H3zm13.5 3c0-1.77-1.02-3.29-2.5-4.03v8.05c1.48-.73 2.5-2.25 2.5-4.02z"/>`,
@@ -3341,7 +3346,12 @@ var VidPly = (() => {
       this.styleDialog = null;
       this.styleDialogVisible = false;
       this.styleDialogJustOpened = false;
+      this.languageSelector = null;
+      this.currentTranscriptLanguage = null;
+      this.availableTranscriptLanguages = [];
+      this.languageSelectorHandler = null;
       const savedPreferences = this.storage.getTranscriptPreferences();
+      this.autoscrollEnabled = (savedPreferences == null ? void 0 : savedPreferences.autoscroll) !== void 0 ? savedPreferences.autoscroll : true;
       this.transcriptStyle = {
         fontSize: (savedPreferences == null ? void 0 : savedPreferences.fontSize) || this.player.options.transcriptFontSize || "100%",
         fontFamily: (savedPreferences == null ? void 0 : savedPreferences.fontFamily) || this.player.options.transcriptFontFamily || "sans-serif",
@@ -3364,13 +3374,15 @@ var VidPly = (() => {
         documentClick: null,
         styleDialogKeydown: null
       };
+      this.timeouts = /* @__PURE__ */ new Set();
       this.init();
     }
     init() {
+      this.setupMetadataHandlingOnLoad();
       this.player.on("timeupdate", this.handlers.timeupdate);
       this.player.on("fullscreenchange", () => {
         if (this.isVisible) {
-          setTimeout(() => this.positionTranscript(), 100);
+          this.setManagedTimeout(() => this.positionTranscript(), 100);
         }
       });
     }
@@ -3391,7 +3403,7 @@ var VidPly = (() => {
       if (this.transcriptWindow) {
         this.transcriptWindow.style.display = "flex";
         this.isVisible = true;
-        setTimeout(() => {
+        this.setManagedTimeout(() => {
           if (this.settingsButton) {
             this.settingsButton.focus();
           }
@@ -3402,8 +3414,8 @@ var VidPly = (() => {
       this.loadTranscriptData();
       if (this.transcriptWindow) {
         this.transcriptWindow.style.display = "flex";
-        setTimeout(() => this.positionTranscript(), 0);
-        setTimeout(() => {
+        this.setManagedTimeout(() => this.positionTranscript(), 0);
+        this.setManagedTimeout(() => {
           if (this.settingsButton) {
             this.settingsButton.focus();
           }
@@ -3480,8 +3492,41 @@ var VidPly = (() => {
       const title = DOMUtils.createElement("h3", {
         textContent: i18n.t("transcript.title")
       });
+      const autoscrollLabel = DOMUtils.createElement("label", {
+        className: `${this.player.options.classPrefix}-transcript-autoscroll-label`,
+        attributes: {
+          "title": i18n.t("transcript.autoscroll")
+        }
+      });
+      this.autoscrollCheckbox = DOMUtils.createElement("input", {
+        attributes: {
+          "type": "checkbox",
+          "checked": this.autoscrollEnabled,
+          "aria-label": i18n.t("transcript.autoscroll")
+        }
+      });
+      const autoscrollText = DOMUtils.createElement("span", {
+        textContent: i18n.t("transcript.autoscroll"),
+        className: `${this.player.options.classPrefix}-transcript-autoscroll-text`
+      });
+      autoscrollLabel.appendChild(this.autoscrollCheckbox);
+      autoscrollLabel.appendChild(autoscrollText);
+      this.autoscrollCheckbox.addEventListener("change", (e) => {
+        this.autoscrollEnabled = e.target.checked;
+        this.saveAutoscrollPreference();
+      });
       this.headerLeft.appendChild(this.settingsButton);
       this.headerLeft.appendChild(title);
+      this.headerLeft.appendChild(autoscrollLabel);
+      this.languageSelector = DOMUtils.createElement("select", {
+        className: `${this.player.options.classPrefix}-transcript-language-select`,
+        attributes: {
+          "aria-label": i18n.t("settings.language") || "Language",
+          "style": "display: none;"
+          // Hidden until we detect multiple languages
+        }
+      });
+      this.headerLeft.appendChild(this.languageSelector);
       const closeButton = DOMUtils.createElement("button", {
         className: `${this.player.options.classPrefix}-transcript-close`,
         attributes: {
@@ -3524,8 +3569,10 @@ var VidPly = (() => {
       this.documentClickHandlerAdded = false;
       let resizeTimeout;
       this.handlers.resize = () => {
-        clearTimeout(resizeTimeout);
-        resizeTimeout = setTimeout(() => this.positionTranscript(), 100);
+        if (resizeTimeout) {
+          this.clearManagedTimeout(resizeTimeout);
+        }
+        resizeTimeout = this.setManagedTimeout(() => this.positionTranscript(), 100);
       };
       window.addEventListener("resize", this.handlers.resize);
     }
@@ -3595,17 +3642,94 @@ var VidPly = (() => {
         }
       }
     }
+    /**
+     * Get available transcript languages from tracks
+     */
+    getAvailableTranscriptLanguages() {
+      const textTracks = this.player.textTracks;
+      const languages = /* @__PURE__ */ new Map();
+      textTracks.forEach((track) => {
+        if ((track.kind === "captions" || track.kind === "subtitles") && track.language) {
+          if (!languages.has(track.language)) {
+            languages.set(track.language, {
+              language: track.language,
+              label: track.label || track.language,
+              track
+            });
+          }
+        }
+      });
+      return Array.from(languages.values());
+    }
+    /**
+     * Update language selector dropdown
+     */
+    updateLanguageSelector() {
+      if (!this.languageSelector) return;
+      this.availableTranscriptLanguages = this.getAvailableTranscriptLanguages();
+      this.languageSelector.innerHTML = "";
+      if (this.availableTranscriptLanguages.length < 2) {
+        this.languageSelector.style.display = "none";
+        return;
+      }
+      this.languageSelector.style.display = "block";
+      this.availableTranscriptLanguages.forEach((langInfo, index) => {
+        const option = DOMUtils.createElement("option", {
+          textContent: langInfo.label,
+          attributes: {
+            "value": langInfo.language
+          }
+        });
+        this.languageSelector.appendChild(option);
+      });
+      if (this.currentTranscriptLanguage) {
+        this.languageSelector.value = this.currentTranscriptLanguage;
+      } else if (this.availableTranscriptLanguages.length > 0) {
+        const activeTrack = this.player.textTracks.find(
+          (track) => (track.kind === "captions" || track.kind === "subtitles") && track.mode === "showing"
+        );
+        this.currentTranscriptLanguage = activeTrack ? activeTrack.language : this.availableTranscriptLanguages[0].language;
+        this.languageSelector.value = this.currentTranscriptLanguage;
+      }
+      if (this.languageSelectorHandler) {
+        this.languageSelector.removeEventListener("change", this.languageSelectorHandler);
+      }
+      this.languageSelectorHandler = (e) => {
+        this.currentTranscriptLanguage = e.target.value;
+        this.loadTranscriptData();
+      };
+      this.languageSelector.addEventListener("change", this.languageSelectorHandler);
+    }
     /**
      * Load transcript data from caption/subtitle tracks
      */
     loadTranscriptData() {
       this.transcriptEntries = [];
       this.transcriptContent.innerHTML = "";
-      const textTracks = Array.from(this.player.element.textTracks);
-      const captionTrack = textTracks.find(
-        (track) => track.kind === "captions" || track.kind === "subtitles"
-      );
-      const descriptionTrack = textTracks.find((track) => track.kind === "descriptions");
+      const textTracks = this.player.textTracks;
+      let captionTrack = null;
+      if (this.currentTranscriptLanguage) {
+        captionTrack = textTracks.find(
+          (track) => (track.kind === "captions" || track.kind === "subtitles") && track.language === this.currentTranscriptLanguage
+        );
+      }
+      if (!captionTrack) {
+        captionTrack = textTracks.find(
+          (track) => track.kind === "captions" || track.kind === "subtitles"
+        );
+        if (captionTrack) {
+          this.currentTranscriptLanguage = captionTrack.language;
+        }
+      }
+      let descriptionTrack = null;
+      if (this.currentTranscriptLanguage) {
+        descriptionTrack = textTracks.find(
+          (track) => track.kind === "descriptions" && track.language === this.currentTranscriptLanguage
+        );
+      }
+      if (!descriptionTrack) {
+        descriptionTrack = textTracks.find((track) => track.kind === "descriptions");
+      }
       const metadataTrack = textTracks.find((track) => track.kind === "metadata");
       if (!captionTrack && !descriptionTrack && !metadataTrack) {
         this.showNoTranscriptMessage();
@@ -3634,7 +3758,7 @@ var VidPly = (() => {
         tracksToLoad.forEach((track) => {
           track.addEventListener("load", onLoad, { once: true });
         });
-        setTimeout(() => {
+        this.setManagedTimeout(() => {
           this.loadTranscriptData();
         }, 500);
         return;
@@ -3667,24 +3791,61 @@ var VidPly = (() => {
         this.transcriptContent.appendChild(entry);
       });
       this.applyTranscriptStyles();
+      this.updateLanguageSelector();
+    }
+    /**
+     * Setup metadata handling on player load
+     * This runs independently of transcript loading
+     */
+    setupMetadataHandlingOnLoad() {
+      const setupMetadata = () => {
+        const textTracks = this.player.textTracks;
+        const metadataTrack = textTracks.find((track) => track.kind === "metadata");
+        if (metadataTrack) {
+          if (metadataTrack.mode === "disabled") {
+            metadataTrack.mode = "hidden";
+          }
+          if (this.metadataCueChangeHandler) {
+            metadataTrack.removeEventListener("cuechange", this.metadataCueChangeHandler);
+          }
+          this.metadataCueChangeHandler = () => {
+            const activeCues = Array.from(metadataTrack.activeCues || []);
+            if (activeCues.length > 0) {
+              if (this.player.options.debug) {
+                console.log("[VidPly 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);
+          if (this.player.options.debug) {
+            const cueCount = metadataTrack.cues ? metadataTrack.cues.length : 0;
+            console.log("[VidPly Metadata] Track enabled,", cueCount, "cues available");
+          }
+        } else if (this.player.options.debug) {
+          console.warn("[VidPly Metadata] No metadata track found");
+        }
+      };
+      setupMetadata();
+      this.player.on("loadedmetadata", setupMetadata);
     }
     /**
      * Setup metadata handling
      * Metadata cues are not displayed but can be used programmatically
+     * This is called when transcript data is loaded (for storing cues)
      */
     setupMetadataHandling() {
       if (!this.metadataCues || this.metadataCues.length === 0) {
         return;
       }
-      const textTracks = Array.from(this.player.element.textTracks);
-      const metadataTrack = textTracks.find((track) => track.kind === "metadata");
-      if (metadataTrack) {
-        metadataTrack.addEventListener("cuechange", () => {
-          const activeCues = Array.from(metadataTrack.activeCues || []);
-          activeCues.forEach((cue) => {
-            this.handleMetadataCue(cue);
-          });
-        });
+      if (this.player.options.debug) {
+        console.log("[VidPly Metadata]", this.metadataCues.length, "cues stored from transcript load");
       }
     }
     /**
@@ -3693,6 +3854,12 @@ var VidPly = (() => {
      */
     handleMetadataCue(cue) {
       const text = cue.text.trim();
+      if (this.player.options.debug) {
+        console.log("[VidPly Metadata] Processing cue:", {
+          time: cue.startTime,
+          text
+        });
+      }
       this.player.emit("metadata", {
         time: cue.startTime,
         endTime: cue.endTime,
@@ -3700,18 +3867,40 @@ var VidPly = (() => {
         cue
       });
       if (text.includes("PAUSE")) {
+        if (!this.player.state.paused) {
+          if (this.player.options.debug) {
+            console.log("[VidPly Metadata] Pausing video at", cue.startTime);
+          }
+          this.player.pause();
+        }
         this.player.emit("metadata:pause", { time: cue.startTime, text });
       }
       const focusMatch = text.match(/FOCUS:([\w#-]+)/);
       if (focusMatch) {
+        const targetSelector = focusMatch[1];
+        const targetElement = document.querySelector(targetSelector);
+        if (targetElement) {
+          if (this.player.options.debug) {
+            console.log("[VidPly Metadata] Focusing element:", targetSelector);
+          }
+          this.setManagedTimeout(() => {
+            targetElement.focus();
+          }, 10);
+        } else if (this.player.options.debug) {
+          console.warn("[VidPly Metadata] Element not found:", targetSelector);
+        }
         this.player.emit("metadata:focus", {
           time: cue.startTime,
-          target: focusMatch[1],
+          target: targetSelector,
+          element: targetElement,
           text
         });
       }
       const hashtags = text.match(/#[\w-]+/g);
       if (hashtags) {
+        if (this.player.options.debug) {
+          console.log("[VidPly Metadata] Hashtags found:", hashtags);
+        }
         this.player.emit("metadata:hashtags", {
           time: cue.startTime,
           hashtags,
@@ -3805,7 +3994,7 @@ var VidPly = (() => {
      * Scroll transcript window to show active entry
      */
     scrollToEntry(entryElement) {
-      if (!this.transcriptContent) return;
+      if (!this.transcriptContent || !this.autoscrollEnabled) return;
       const contentRect = this.transcriptContent.getBoundingClientRect();
       const entryRect = entryElement.getBoundingClientRect();
       if (entryRect.top < contentRect.top || entryRect.bottom > contentRect.bottom) {
@@ -3816,6 +4005,14 @@ var VidPly = (() => {
         });
       }
     }
+    /**
+     * Save autoscroll preference to localStorage
+     */
+    saveAutoscrollPreference() {
+      const savedPreferences = this.storage.getTranscriptPreferences() || {};
+      savedPreferences.autoscroll = this.autoscrollEnabled;
+      this.storage.saveTranscriptPreferences(savedPreferences);
+    }
     /**
      * Setup drag and drop functionality
      */
@@ -3828,6 +4025,9 @@ var VidPly = (() => {
         if (e.target.closest(`.${this.player.options.classPrefix}-transcript-settings`)) {
           return;
         }
+        if (e.target.closest(`.${this.player.options.classPrefix}-transcript-language-select`)) {
+          return;
+        }
         if (e.target.closest(`.${this.player.options.classPrefix}-transcript-settings-menu`)) {
           return;
         }
@@ -3854,6 +4054,9 @@ var VidPly = (() => {
         if (e.target.closest(`.${this.player.options.classPrefix}-transcript-settings`)) {
           return;
         }
+        if (e.target.closest(`.${this.player.options.classPrefix}-transcript-language-select`)) {
+          return;
+        }
         if (e.target.closest(`.${this.player.options.classPrefix}-transcript-settings-menu`)) {
           return;
         }
@@ -4608,6 +4811,30 @@ var VidPly = (() => {
         entry.style.fontFamily = this.transcriptStyle.fontFamily;
       });
     }
+    /**
+     * 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);
+      }
+    }
     /**
      * Cleanup
      */
@@ -4661,6 +4888,8 @@ var VidPly = (() => {
       if (this.handlers.resize) {
         window.removeEventListener("resize", this.handlers.resize);
       }
+      this.timeouts.forEach((timeoutId) => clearTimeout(timeoutId));
+      this.timeouts.clear();
       this.handlers = null;
       if (this.transcriptWindow && this.transcriptWindow.parentNode) {
         this.transcriptWindow.parentNode.removeChild(this.transcriptWindow);
@@ -5332,7 +5561,7 @@ var VidPly = (() => {
   };
 
   // src/core/Player.js
-  var Player = class extends EventEmitter {
+  var Player = class _Player extends EventEmitter {
     constructor(element, options = {}) {
       super();
       this.element = typeof element === "string" ? document.querySelector(element) : element;
@@ -5440,6 +5669,8 @@ var VidPly = (() => {
         screenReaderAnnouncements: true,
         highContrast: false,
         focusHighlight: true,
+        metadataAlerts: {},
+        metadataHashtags: {},
         // Languages
         language: "en",
         languages: ["en"],
@@ -5458,6 +5689,8 @@ var VidPly = (() => {
         onError: null,
         ...options
       };
+      this.options.metadataAlerts = this.options.metadataAlerts || {};
+      this.options.metadataHashtags = this.options.metadataHashtags || {};
       this.storage = new StorageManager("vidply");
       const savedPrefs = this.storage.getPlayerPreferences();
       if (savedPrefs) {
@@ -5489,12 +5722,24 @@ var VidPly = (() => {
       this.audioDescriptionSrc = this.options.audioDescriptionSrc;
       this.signLanguageSrc = this.options.signLanguageSrc;
       this.signLanguageVideo = null;
+      this.audioDescriptionSourceElement = null;
+      this.originalAudioDescriptionSource = null;
+      this.audioDescriptionCaptionTracks = [];
+      this._textTracksCache = null;
+      this._textTracksDirty = true;
+      this._sourceElementsCache = null;
+      this._sourceElementsDirty = true;
+      this._trackElementsCache = null;
+      this._trackElementsDirty = true;
+      this.timeouts = /* @__PURE__ */ new Set();
       this.container = null;
       this.renderer = null;
       this.controlBar = null;
       this.captionManager = null;
       this.keyboardManager = null;
       this.settingsDialog = null;
+      this.metadataCueChangeHandler = null;
+      this.metadataAlertHandlers = /* @__PURE__ */ new Map();
       this.init();
     }
     async init() {
@@ -5526,6 +5771,7 @@ var VidPly = (() => {
         if (this.options.transcript || this.options.transcriptButton) {
           this.transcriptManager = new TranscriptManager(this);
         }
+        this.setupMetadataHandling();
         if (this.options.keyboard) {
           this.keyboardManager = new KeyboardManager(this);
         }
@@ -5611,6 +5857,8 @@ var VidPly = (() => {
       if (this.element.tagName === "VIDEO") {
         this.createPlayButtonOverlay();
       }
+      this.element.vidply = this;
+      _Player.instances.push(this);
       this.element.style.cursor = "pointer";
       this.element.addEventListener("click", (e) => {
         if (e.target === this.element) {
@@ -5643,6 +5891,53 @@ var VidPly = (() => {
       if (!src) {
         throw new Error("No media source found");
       }
+      const sourceElements = this.sourceElements;
+      for (const sourceEl of sourceElements) {
+        const descSrc = sourceEl.getAttribute("data-desc-src");
+        const origSrc = sourceEl.getAttribute("data-orig-src");
+        if (descSrc || origSrc) {
+          if (!this.audioDescriptionSourceElement) {
+            this.audioDescriptionSourceElement = sourceEl;
+          }
+          if (origSrc) {
+            if (!this.originalAudioDescriptionSource) {
+              this.originalAudioDescriptionSource = origSrc;
+            }
+            if (!this.originalSrc) {
+              this.originalSrc = origSrc;
+            }
+          } else {
+            const currentSrcAttr = sourceEl.getAttribute("src");
+            if (!this.originalAudioDescriptionSource && currentSrcAttr) {
+              this.originalAudioDescriptionSource = currentSrcAttr;
+            }
+            if (!this.originalSrc && currentSrcAttr) {
+              this.originalSrc = currentSrcAttr;
+            }
+          }
+          if (descSrc && !this.audioDescriptionSrc) {
+            this.audioDescriptionSrc = descSrc;
+          }
+        }
+      }
+      const trackElements = this.trackElements;
+      trackElements.forEach((trackEl) => {
+        const trackKind = trackEl.getAttribute("kind");
+        const trackDescSrc = trackEl.getAttribute("data-desc-src");
+        if (trackKind === "captions" || trackKind === "subtitles" || trackKind === "chapters") {
+          if (trackDescSrc) {
+            this.audioDescriptionCaptionTracks.push({
+              trackElement: trackEl,
+              originalSrc: trackEl.getAttribute("src"),
+              describedSrc: trackDescSrc,
+              originalTrackSrc: trackEl.getAttribute("data-orig-src") || trackEl.getAttribute("src"),
+              explicit: true
+              // Explicitly defined, so we should validate it
+            });
+            this.log(`Found explicit described ${trackKind} track: ${trackEl.getAttribute("src")} -> ${trackDescSrc}`);
+          }
+        }
+      });
       if (!this.originalSrc) {
         this.originalSrc = src;
       }
@@ -5659,6 +5954,106 @@ var VidPly = (() => {
       this.log(`Using ${renderer.name} renderer`);
       this.renderer = new renderer(this);
       await this.renderer.init();
+      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);
+    }
+    /**
+     * 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);
+      }
     }
     /**
      * Load new media source (for playlists)
@@ -5674,8 +6069,9 @@ var VidPly = (() => {
         if (this.renderer) {
           this.pause();
         }
-        const existingTracks = this.element.querySelectorAll("track");
+        const existingTracks = this.trackElements;
         existingTracks.forEach((track) => track.remove());
+        this.invalidateTrackCache();
         this.element.src = config.src;
         if (config.type) {
           this.element.type = config.type;
@@ -5695,6 +6091,7 @@ var VidPly = (() => {
             }
             this.element.appendChild(track);
           });
+          this.invalidateTrackCache();
         }
         const shouldChangeRenderer = this.shouldChangeRenderer(config.src);
         if (shouldChangeRenderer && this.renderer) {
@@ -5927,15 +6324,398 @@ var VidPly = (() => {
         this.enableCaptions();
       }
     }
+    /**
+     * Check if a track file exists
+     * @param {string} url - Track file URL
+     * @returns {Promise<boolean>} - True if file exists
+     */
+    async validateTrackExists(url) {
+      try {
+        const response = await fetch(url, { method: "HEAD", cache: "no-cache" });
+        return response.ok;
+      } catch (error) {
+        return false;
+      }
+    }
     // Audio Description
     async enableAudioDescription() {
-      if (!this.audioDescriptionSrc) {
-        console.warn("VidPly: No audio description source provided");
+      const hasSourceElementsWithDesc = this.sourceElements.some((el) => el.getAttribute("data-desc-src"));
+      const hasTracksWithDesc = this.audioDescriptionCaptionTracks.length > 0;
+      if (!this.audioDescriptionSrc && !hasSourceElementsWithDesc && !hasTracksWithDesc) {
+        console.warn("VidPly: No audio description source, source elements, or tracks provided");
         return;
       }
       const currentTime = this.state.currentTime;
       const wasPlaying = this.state.playing;
-      this.element.src = this.audioDescriptionSrc;
+      let swappedTracksForTranscript = [];
+      if (this.audioDescriptionSourceElement) {
+        const currentSrc = this.element.currentSrc || this.element.src;
+        const sourceElements = this.sourceElements;
+        let sourceElementToUpdate = null;
+        let descSrc = this.audioDescriptionSrc;
+        for (const sourceEl of sourceElements) {
+          const sourceSrc = sourceEl.getAttribute("src");
+          const descSrcAttr = sourceEl.getAttribute("data-desc-src");
+          const sourceFilename = sourceSrc ? sourceSrc.split("/").pop() : "";
+          const currentFilename = currentSrc ? currentSrc.split("/").pop() : "";
+          if (currentSrc && (currentSrc === sourceSrc || currentSrc.includes(sourceSrc) || currentSrc.includes(sourceFilename) || sourceFilename && currentFilename === sourceFilename)) {
+            sourceElementToUpdate = sourceEl;
+            if (descSrcAttr) {
+              descSrc = descSrcAttr;
+            } else if (sourceSrc) {
+              descSrc = this.audioDescriptionSrc || descSrc;
+            }
+            break;
+          }
+        }
+        if (!sourceElementToUpdate) {
+          sourceElementToUpdate = this.audioDescriptionSourceElement;
+          const storedDescSrc = sourceElementToUpdate.getAttribute("data-desc-src");
+          if (storedDescSrc) {
+            descSrc = storedDescSrc;
+          }
+        }
+        if (this.audioDescriptionCaptionTracks.length > 0) {
+          const validationPromises = this.audioDescriptionCaptionTracks.map(async (trackInfo) => {
+            if (trackInfo.trackElement && trackInfo.describedSrc) {
+              if (trackInfo.explicit === true) {
+                try {
+                  const exists = await this.validateTrackExists(trackInfo.describedSrc);
+                  return { trackInfo, exists };
+                } catch (error) {
+                  return { trackInfo, exists: false };
+                }
+              } else {
+                return { trackInfo, exists: false };
+              }
+            }
+            return { trackInfo, exists: false };
+          });
+          const validationResults = await Promise.all(validationPromises);
+          const tracksToSwap = validationResults.filter((result) => result.exists);
+          if (tracksToSwap.length > 0) {
+            const trackModes = /* @__PURE__ */ new Map();
+            tracksToSwap.forEach(({ trackInfo }) => {
+              const textTrack = trackInfo.trackElement.track;
+              if (textTrack) {
+                trackModes.set(trackInfo, {
+                  wasShowing: textTrack.mode === "showing",
+                  wasHidden: textTrack.mode === "hidden"
+                });
+              } else {
+                trackModes.set(trackInfo, {
+                  wasShowing: false,
+                  wasHidden: false
+                });
+              }
+            });
+            const tracksToReadd = tracksToSwap.map(({ trackInfo }) => {
+              const oldSrc = trackInfo.trackElement.getAttribute("src");
+              const parent = trackInfo.trackElement.parentNode;
+              const nextSibling = trackInfo.trackElement.nextSibling;
+              const attributes = {};
+              Array.from(trackInfo.trackElement.attributes).forEach((attr) => {
+                attributes[attr.name] = attr.value;
+              });
+              return {
+                trackInfo,
+                oldSrc,
+                parent,
+                nextSibling,
+                attributes
+              };
+            });
+            tracksToReadd.forEach(({ trackInfo }) => {
+              trackInfo.trackElement.remove();
+            });
+            this.element.load();
+            setTimeout(() => {
+              tracksToReadd.forEach(({ trackInfo, oldSrc, parent, nextSibling, attributes }) => {
+                swappedTracksForTranscript.push(trackInfo);
+                const newTrackElement = document.createElement("track");
+                newTrackElement.setAttribute("src", trackInfo.describedSrc);
+                Object.keys(attributes).forEach((attrName) => {
+                  if (attrName !== "src" && attrName !== "data-desc-src") {
+                    newTrackElement.setAttribute(attrName, attributes[attrName]);
+                  }
+                });
+                if (nextSibling && nextSibling.parentNode) {
+                  parent.insertBefore(newTrackElement, nextSibling);
+                } else {
+                  parent.appendChild(newTrackElement);
+                }
+                trackInfo.trackElement = newTrackElement;
+              });
+              this.element.load();
+              this.invalidateTrackCache();
+              const setupNewTracks = () => {
+                this.setManagedTimeout(() => {
+                  swappedTracksForTranscript.forEach((trackInfo) => {
+                    const trackElement = trackInfo.trackElement;
+                    const newTextTrack = trackElement.track;
+                    if (newTextTrack) {
+                      const modeInfo = trackModes.get(trackInfo) || { wasShowing: false, wasHidden: false };
+                      newTextTrack.mode = "hidden";
+                      const restoreMode = () => {
+                        if (modeInfo.wasShowing) {
+                          newTextTrack.mode = "hidden";
+                        } else if (modeInfo.wasHidden) {
+                          newTextTrack.mode = "hidden";
+                        } else {
+                          newTextTrack.mode = "disabled";
+                        }
+                      };
+                      if (newTextTrack.readyState >= 2) {
+                        restoreMode();
+                      } else {
+                        newTextTrack.addEventListener("load", restoreMode, { once: true });
+                        newTextTrack.addEventListener("error", restoreMode, { once: true });
+                      }
+                    }
+                  });
+                }, 300);
+              };
+              if (this.element.readyState >= 1) {
+                setTimeout(setupNewTracks, 200);
+              } else {
+                this.element.addEventListener("loadedmetadata", setupNewTracks, { once: true });
+                setTimeout(setupNewTracks, 2e3);
+              }
+            }, 100);
+            const skippedCount = validationResults.length - tracksToSwap.length;
+          }
+        }
+        const allSourceElements = this.sourceElements;
+        const sourcesToUpdate = [];
+        allSourceElements.forEach((sourceEl) => {
+          const descSrcAttr = sourceEl.getAttribute("data-desc-src");
+          const currentSrc2 = sourceEl.getAttribute("src");
+          if (descSrcAttr) {
+            const type = sourceEl.getAttribute("type");
+            let origSrc = sourceEl.getAttribute("data-orig-src");
+            if (!origSrc) {
+              origSrc = currentSrc2;
+            }
+            sourcesToUpdate.push({
+              src: descSrcAttr,
+              // Use described version
+              type,
+              origSrc,
+              descSrc: descSrcAttr
+            });
+          } else {
+            const type = sourceEl.getAttribute("type");
+            const src = sourceEl.getAttribute("src");
+            sourcesToUpdate.push({
+              src,
+              type,
+              origSrc: null,
+              descSrc: null
+            });
+          }
+        });
+        allSourceElements.forEach((sourceEl) => {
+          sourceEl.remove();
+        });
+        sourcesToUpdate.forEach((sourceInfo) => {
+          const newSource = document.createElement("source");
+          newSource.setAttribute("src", sourceInfo.src);
+          if (sourceInfo.type) {
+            newSource.setAttribute("type", sourceInfo.type);
+          }
+          if (sourceInfo.origSrc) {
+            newSource.setAttribute("data-orig-src", sourceInfo.origSrc);
+          }
+          if (sourceInfo.descSrc) {
+            newSource.setAttribute("data-desc-src", sourceInfo.descSrc);
+          }
+          this.element.appendChild(newSource);
+        });
+        this.element.load();
+        await new Promise((resolve) => {
+          const onLoadedMetadata = () => {
+            this.element.removeEventListener("loadedmetadata", onLoadedMetadata);
+            resolve();
+          };
+          this.element.addEventListener("loadedmetadata", onLoadedMetadata);
+        });
+        await new Promise((resolve) => setTimeout(resolve, 300));
+        if (this.element.tagName === "VIDEO" && currentTime === 0 && !wasPlaying) {
+          if (this.element.readyState >= 1) {
+            this.element.currentTime = 1e-3;
+            setTimeout(() => {
+              this.element.currentTime = 0;
+            }, 10);
+          }
+        }
+        this.seek(currentTime);
+        if (wasPlaying) {
+          this.play();
+        }
+        this.state.audioDescriptionEnabled = true;
+        this.emit("audiodescriptionenabled");
+      } else {
+        if (this.audioDescriptionCaptionTracks.length > 0) {
+          const validationPromises = this.audioDescriptionCaptionTracks.map(async (trackInfo) => {
+            if (trackInfo.trackElement && trackInfo.describedSrc) {
+              if (trackInfo.explicit === true) {
+                try {
+                  const exists = await this.validateTrackExists(trackInfo.describedSrc);
+                  return { trackInfo, exists };
+                } catch (error) {
+                  return { trackInfo, exists: false };
+                }
+              } else {
+                return { trackInfo, exists: false };
+              }
+            }
+            return { trackInfo, exists: false };
+          });
+          const validationResults = await Promise.all(validationPromises);
+          const tracksToSwap = validationResults.filter((result) => result.exists);
+          if (tracksToSwap.length > 0) {
+            const trackModes = /* @__PURE__ */ new Map();
+            tracksToSwap.forEach(({ trackInfo }) => {
+              const textTrack = trackInfo.trackElement.track;
+              if (textTrack) {
+                trackModes.set(trackInfo, {
+                  wasShowing: textTrack.mode === "showing",
+                  wasHidden: textTrack.mode === "hidden"
+                });
+              } else {
+                trackModes.set(trackInfo, {
+                  wasShowing: false,
+                  wasHidden: false
+                });
+              }
+            });
+            const tracksToReadd = tracksToSwap.map(({ trackInfo }) => {
+              const oldSrc = trackInfo.trackElement.getAttribute("src");
+              const parent = trackInfo.trackElement.parentNode;
+              const nextSibling = trackInfo.trackElement.nextSibling;
+              const attributes = {};
+              Array.from(trackInfo.trackElement.attributes).forEach((attr) => {
+                attributes[attr.name] = attr.value;
+              });
+              return {
+                trackInfo,
+                oldSrc,
+                parent,
+                nextSibling,
+                attributes
+              };
+            });
+            tracksToReadd.forEach(({ trackInfo }) => {
+              trackInfo.trackElement.remove();
+            });
+            this.element.load();
+            setTimeout(() => {
+              tracksToReadd.forEach(({ trackInfo, oldSrc, parent, nextSibling, attributes }) => {
+                swappedTracksForTranscript.push(trackInfo);
+                const newTrackElement = document.createElement("track");
+                newTrackElement.setAttribute("src", trackInfo.describedSrc);
+                Object.keys(attributes).forEach((attrName) => {
+                  if (attrName !== "src" && attrName !== "data-desc-src") {
+                    newTrackElement.setAttribute(attrName, attributes[attrName]);
+                  }
+                });
+                if (nextSibling && nextSibling.parentNode) {
+                  parent.insertBefore(newTrackElement, nextSibling);
+                } else {
+                  parent.appendChild(newTrackElement);
+                }
+                trackInfo.trackElement = newTrackElement;
+              });
+              this.element.load();
+              const setupNewTracks = () => {
+                setTimeout(() => {
+                  swappedTracksForTranscript.forEach((trackInfo) => {
+                    const trackElement = trackInfo.trackElement;
+                    const newTextTrack = trackElement.track;
+                    if (newTextTrack) {
+                      const modeInfo = trackModes.get(trackInfo) || { wasShowing: false, wasHidden: false };
+                      newTextTrack.mode = "hidden";
+                      const restoreMode = () => {
+                        if (modeInfo.wasShowing) {
+                          newTextTrack.mode = "hidden";
+                        } else if (modeInfo.wasHidden) {
+                          newTextTrack.mode = "hidden";
+                        } else {
+                          newTextTrack.mode = "disabled";
+                        }
+                      };
+                      if (newTextTrack.readyState >= 2) {
+                        restoreMode();
+                      } else {
+                        newTextTrack.addEventListener("load", restoreMode, { once: true });
+                        newTextTrack.addEventListener("error", restoreMode, { once: true });
+                      }
+                    }
+                  });
+                }, 300);
+              };
+              if (this.element.readyState >= 1) {
+                setTimeout(setupNewTracks, 200);
+              } else {
+                this.element.addEventListener("loadedmetadata", setupNewTracks, { once: true });
+                setTimeout(setupNewTracks, 2e3);
+              }
+            }, 100);
+          }
+        }
+        const fallbackSourceElements = this.sourceElements;
+        const hasSourceElementsWithDesc2 = fallbackSourceElements.some((el) => el.getAttribute("data-desc-src"));
+        if (hasSourceElementsWithDesc2) {
+          const fallbackSourcesToUpdate = [];
+          fallbackSourceElements.forEach((sourceEl) => {
+            const descSrcAttr = sourceEl.getAttribute("data-desc-src");
+            const currentSrc = sourceEl.getAttribute("src");
+            if (descSrcAttr) {
+              const type = sourceEl.getAttribute("type");
+              let origSrc = sourceEl.getAttribute("data-orig-src");
+              if (!origSrc) {
+                origSrc = currentSrc;
+              }
+              fallbackSourcesToUpdate.push({
+                src: descSrcAttr,
+                type,
+                origSrc,
+                descSrc: descSrcAttr
+              });
+            } else {
+              const type = sourceEl.getAttribute("type");
+              const src = sourceEl.getAttribute("src");
+              fallbackSourcesToUpdate.push({
+                src,
+                type,
+                origSrc: null,
+                descSrc: null
+              });
+            }
+          });
+          fallbackSourceElements.forEach((sourceEl) => {
+            sourceEl.remove();
+          });
+          fallbackSourcesToUpdate.forEach((sourceInfo) => {
+            const newSource = document.createElement("source");
+            newSource.setAttribute("src", sourceInfo.src);
+            if (sourceInfo.type) {
+              newSource.setAttribute("type", sourceInfo.type);
+            }
+            if (sourceInfo.origSrc) {
+              newSource.setAttribute("data-orig-src", sourceInfo.origSrc);
+            }
+            if (sourceInfo.descSrc) {
+              newSource.setAttribute("data-desc-src", sourceInfo.descSrc);
+            }
+            this.element.appendChild(newSource);
+          });
+          this.element.load();
+          this.invalidateTrackCache();
+        } else {
+          this.element.src = this.audioDescriptionSrc;
+        }
+      }
       await new Promise((resolve) => {
         const onLoadedMetadata = () => {
           this.element.removeEventListener("loadedmetadata", onLoadedMetadata);
@@ -5943,10 +6723,177 @@ var VidPly = (() => {
         };
         this.element.addEventListener("loadedmetadata", onLoadedMetadata);
       });
+      if (this.element.tagName === "VIDEO" && currentTime === 0 && !wasPlaying) {
+        if (this.element.readyState >= 1) {
+          this.element.currentTime = 1e-3;
+          this.setManagedTimeout(() => {
+            this.element.currentTime = 0;
+          }, 10);
+        }
+      }
       this.seek(currentTime);
       if (wasPlaying) {
         this.play();
       }
+      if (swappedTracksForTranscript.length > 0 && this.captionManager) {
+        const wasCaptionsEnabled = this.state.captionsEnabled;
+        let currentTrackInfo = null;
+        if (this.captionManager.currentTrack) {
+          const currentTrackIndex = this.captionManager.tracks.findIndex((t) => t.track === this.captionManager.currentTrack.track);
+          if (currentTrackIndex >= 0) {
+            currentTrackInfo = {
+              language: this.captionManager.tracks[currentTrackIndex].language,
+              kind: this.captionManager.tracks[currentTrackIndex].kind
+            };
+          }
+        }
+        setTimeout(() => {
+          this.captionManager.tracks = [];
+          this.captionManager.loadTracks();
+          if (wasCaptionsEnabled && currentTrackInfo && this.captionManager.tracks.length > 0) {
+            const matchingTrackIndex = this.captionManager.tracks.findIndex(
+              (t) => t.language === currentTrackInfo.language && t.kind === currentTrackInfo.kind
+            );
+            if (matchingTrackIndex >= 0) {
+              this.captionManager.enable(matchingTrackIndex);
+            } else if (this.captionManager.tracks.length > 0) {
+              this.captionManager.enable(0);
+            }
+          }
+        }, 600);
+      }
+      if (this.transcriptManager && this.transcriptManager.isVisible) {
+        const swappedTracks = typeof swappedTracksForTranscript !== "undefined" ? swappedTracksForTranscript : [];
+        if (swappedTracks.length > 0) {
+          const onMetadataLoaded = () => {
+            this.invalidateTrackCache();
+            const allTextTracks = this.textTracks;
+            const freshTracks = swappedTracks.map((trackInfo) => {
+              const trackEl = trackInfo.trackElement;
+              const expectedSrc = trackEl.getAttribute("src");
+              const srclang = trackEl.getAttribute("srclang");
+              const kind = trackEl.getAttribute("kind");
+              let foundTrack = allTextTracks.find((track) => trackEl.track === track);
+              if (!foundTrack) {
+                foundTrack = allTextTracks.find((track) => {
+                  if (track.language === srclang && (track.kind === kind || kind === "captions" && track.kind === "subtitles")) {
+                    const trackElementForTrack = this.findTrackElement(track);
+                    if (trackElementForTrack) {
+                      const actualSrc = trackElementForTrack.getAttribute("src");
+                      if (actualSrc === expectedSrc) {
+                        return true;
+                      }
+                    }
+                  }
+                  return false;
+                });
+              }
+              if (foundTrack) {
+                const trackElement = this.findTrackElement(foundTrack);
+                if (trackElement && trackElement.getAttribute("src") !== expectedSrc) {
+                  return null;
+                }
+              }
+              return foundTrack;
+            }).filter(Boolean);
+            if (freshTracks.length === 0) {
+              this.setManagedTimeout(() => {
+                if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
+                  this.transcriptManager.loadTranscriptData();
+                }
+              }, 1e3);
+              return;
+            }
+            freshTracks.forEach((track) => {
+              if (track.mode === "disabled") {
+                track.mode = "hidden";
+              }
+            });
+            let loadedCount = 0;
+            const checkLoaded = () => {
+              loadedCount++;
+              if (loadedCount >= freshTracks.length) {
+                this.setManagedTimeout(() => {
+                  if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
+                    this.invalidateTrackCache();
+                    const allTextTracks2 = this.textTracks;
+                    const swappedTrackSrcs = swappedTracks.map((t) => t.describedSrc);
+                    const hasCorrectTracks = freshTracks.some((track) => {
+                      const trackEl = this.findTrackElement(track);
+                      return trackEl && swappedTrackSrcs.includes(trackEl.getAttribute("src"));
+                    });
+                    if (hasCorrectTracks || freshTracks.length > 0) {
+                      this.transcriptManager.loadTranscriptData();
+                    }
+                  }
+                }, 800);
+              }
+            };
+            freshTracks.forEach((track) => {
+              if (track.mode === "disabled") {
+                track.mode = "hidden";
+              }
+              const trackElementForTrack = this.findTrackElement(track);
+              const actualSrc = trackElementForTrack ? trackElementForTrack.getAttribute("src") : null;
+              const expectedTrackInfo = swappedTracks.find((t) => {
+                const tEl = t.trackElement;
+                return tEl && (tEl.track === track || tEl.getAttribute("srclang") === track.language && tEl.getAttribute("kind") === track.kind);
+              });
+              const expectedSrc = expectedTrackInfo ? expectedTrackInfo.describedSrc : null;
+              if (expectedSrc && actualSrc && actualSrc !== expectedSrc) {
+                checkLoaded();
+                return;
+              }
+              if (track.readyState >= 2 && track.cues && track.cues.length > 0) {
+                checkLoaded();
+              } else {
+                if (track.mode === "disabled") {
+                  track.mode = "hidden";
+                }
+                const onTrackLoad = () => {
+                  this.setManagedTimeout(checkLoaded, 300);
+                };
+                if (track.readyState >= 2) {
+                  this.setManagedTimeout(() => {
+                    if (track.cues && track.cues.length > 0) {
+                      checkLoaded();
+                    } else {
+                      track.addEventListener("load", onTrackLoad, { once: true });
+                    }
+                  }, 100);
+                } else {
+                  track.addEventListener("load", onTrackLoad, { once: true });
+                  track.addEventListener("error", () => {
+                    checkLoaded();
+                  }, { once: true });
+                }
+              }
+            });
+          };
+          const waitForTracks = () => {
+            this.setManagedTimeout(() => {
+              if (this.element.readyState >= 1) {
+                onMetadataLoaded();
+              } else {
+                this.element.addEventListener("loadedmetadata", onMetadataLoaded, { once: true });
+                this.setManagedTimeout(onMetadataLoaded, 2e3);
+              }
+            }, 500);
+          };
+          waitForTracks();
+          setTimeout(() => {
+            if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
+              this.transcriptManager.loadTranscriptData();
+            }
+          }, 5e3);
+        } else {
+          setTimeout(() => {
+            if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
+              this.transcriptManager.loadTranscriptData();
+            }
+          }, 800);
+        }
+      }
       this.state.audioDescriptionEnabled = true;
       this.emit("audiodescriptionenabled");
     }
@@ -5956,7 +6903,64 @@ var VidPly = (() => {
       }
       const currentTime = this.state.currentTime;
       const wasPlaying = this.state.playing;
-      this.element.src = this.originalSrc;
+      if (this.audioDescriptionCaptionTracks.length > 0) {
+        this.audioDescriptionCaptionTracks.forEach((trackInfo) => {
+          if (trackInfo.trackElement && trackInfo.originalTrackSrc) {
+            trackInfo.trackElement.setAttribute("src", trackInfo.originalTrackSrc);
+          }
+        });
+      }
+      const allSourceElements = this.sourceElements;
+      const hasSourceElementsToSwap = allSourceElements.some((el) => el.getAttribute("data-orig-src"));
+      if (hasSourceElementsToSwap) {
+        const sourcesToRestore = [];
+        allSourceElements.forEach((sourceEl) => {
+          const origSrcAttr = sourceEl.getAttribute("data-orig-src");
+          const descSrcAttr = sourceEl.getAttribute("data-desc-src");
+          if (origSrcAttr) {
+            const type = sourceEl.getAttribute("type");
+            sourcesToRestore.push({
+              src: origSrcAttr,
+              // Use original version
+              type,
+              origSrc: origSrcAttr,
+              descSrc: descSrcAttr
+              // Keep data-desc-src for future swaps
+            });
+          } else {
+            const type = sourceEl.getAttribute("type");
+            const src = sourceEl.getAttribute("src");
+            sourcesToRestore.push({
+              src,
+              type,
+              origSrc: null,
+              descSrc: descSrcAttr
+            });
+          }
+        });
+        allSourceElements.forEach((sourceEl) => {
+          sourceEl.remove();
+        });
+        sourcesToRestore.forEach((sourceInfo) => {
+          const newSource = document.createElement("source");
+          newSource.setAttribute("src", sourceInfo.src);
+          if (sourceInfo.type) {
+            newSource.setAttribute("type", sourceInfo.type);
+          }
+          if (sourceInfo.origSrc) {
+            newSource.setAttribute("data-orig-src", sourceInfo.origSrc);
+          }
+          if (sourceInfo.descSrc) {
+            newSource.setAttribute("data-desc-src", sourceInfo.descSrc);
+          }
+          this.element.appendChild(newSource);
+        });
+        this.element.load();
+      } else {
+        const originalSrcToUse = this.originalAudioDescriptionSource || this.originalSrc;
+        this.element.src = originalSrcToUse;
+        this.element.load();
+      }
       await new Promise((resolve) => {
         const onLoadedMetadata = () => {
           this.element.removeEventListener("loadedmetadata", onLoadedMetadata);
@@ -5968,13 +6972,50 @@ var VidPly = (() => {
       if (wasPlaying) {
         this.play();
       }
+      if (this.transcriptManager && this.transcriptManager.isVisible) {
+        this.setManagedTimeout(() => {
+          if (this.transcriptManager && this.transcriptManager.loadTranscriptData) {
+            this.transcriptManager.loadTranscriptData();
+          }
+        }, 500);
+      }
       this.state.audioDescriptionEnabled = false;
       this.emit("audiodescriptiondisabled");
     }
     async toggleAudioDescription() {
-      const textTracks = Array.from(this.element.textTracks || []);
-      const descriptionTrack = textTracks.find((track) => track.kind === "descriptions");
-      if (descriptionTrack) {
+      const descriptionTrack = this.findTextTrack("descriptions");
+      const hasAudioDescriptionSrc = this.audioDescriptionSrc || this.sourceElements.some((el) => el.getAttribute("data-desc-src"));
+      if (descriptionTrack && hasAudioDescriptionSrc) {
+        if (this.state.audioDescriptionEnabled) {
+          descriptionTrack.mode = "hidden";
+          await this.disableAudioDescription();
+        } else {
+          await this.enableAudioDescription();
+          const enableDescriptionTrack = () => {
+            this.invalidateTrackCache();
+            const descTrack = this.findTextTrack("descriptions");
+            if (descTrack) {
+              if (descTrack.mode === "disabled") {
+                descTrack.mode = "hidden";
+                this.setManagedTimeout(() => {
+                  descTrack.mode = "showing";
+                }, 50);
+              } else {
+                descTrack.mode = "showing";
+              }
+            } else if (this.element.readyState < 2) {
+              this.setManagedTimeout(enableDescriptionTrack, 100);
+            }
+          };
+          if (this.element.readyState >= 1) {
+            this.setManagedTimeout(enableDescriptionTrack, 200);
+          } else {
+            this.element.addEventListener("loadedmetadata", () => {
+              this.setManagedTimeout(enableDescriptionTrack, 200);
+            }, { once: true });
+          }
+        }
+      } else if (descriptionTrack) {
         if (descriptionTrack.mode === "showing") {
           descriptionTrack.mode = "hidden";
           this.state.audioDescriptionEnabled = false;
@@ -5984,7 +7025,7 @@ var VidPly = (() => {
           this.state.audioDescriptionEnabled = true;
           this.emit("audiodescriptionenabled");
         }
-      } else if (this.audioDescriptionSrc) {
+      } else if (hasAudioDescriptionSrc) {
         if (this.state.audioDescriptionEnabled) {
           await this.disableAudioDescription();
         } else {
@@ -6385,9 +7426,25 @@ var VidPly = (() => {
       }
     }
     // 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);
       }
     }
     // Setup responsive handlers
@@ -6447,7 +7504,7 @@ var VidPly = (() => {
             this.controlBar.updateFullscreenButton();
           }
           if (this.signLanguageWrapper && this.signLanguageWrapper.style.display !== "none") {
-            setTimeout(() => {
+            this.setManagedTimeout(() => {
               requestAnimationFrame(() => {
                 this.storage.saveSignLanguagePreferences({ size: null });
                 this.signLanguageDesiredPosition = "bottom-right";
@@ -6510,12 +7567,368 @@ var VidPly = (() => {
         document.removeEventListener("MSFullscreenChange", this.fullscreenChangeHandler);
         this.fullscreenChangeHandler = null;
       }
+      this.timeouts.forEach((timeoutId) => clearTimeout(timeoutId));
+      this.timeouts.clear();
+      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();
+      }
       if (this.container && this.container.parentNode) {
         this.container.parentNode.insertBefore(this.element, this.container);
         this.container.parentNode.removeChild(this.container);
       }
       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) {
+          if (metadataTrack.mode === "disabled") {
+            metadataTrack.mode = "hidden";
+          }
+          if (this.metadataCueChangeHandler) {
+            metadataTrack.removeEventListener("cuechange", this.metadataCueChangeHandler);
+          }
+          this.metadataCueChangeHandler = () => {
+            const activeCues = Array.from(metadataTrack.activeCues || []);
+            if (activeCues.length > 0) {
+              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);
+          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");
+        }
+      };
+      setupMetadata();
+      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) {
+      var _a, _b;
+      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 = (_b = (_a = this.controlBar) == null ? void 0 : _a.controls) == null ? void 0 : _b.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 !== void 0 ? 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 !== void 0 ? 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 !== void 0 ? 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();
+      if (this.options.debug) {
+        this.log("[Metadata] Processing cue:", {
+          time: cue.startTime,
+          text
+        });
+      }
+      this.emit("metadata", {
+        time: cue.startTime,
+        endTime: cue.endTime,
+        text,
+        cue
+      });
+      if (text.includes("PAUSE")) {
+        if (!this.state.paused) {
+          if (this.options.debug) {
+            this.log("[Metadata] Pausing video at", cue.startTime);
+          }
+          this.pause();
+        }
+        this.emit("metadata:pause", { time: cue.startTime, text });
+      }
+      const focusMatch = text.match(/FOCUS:([\w#-]+)/);
+      if (focusMatch) {
+        const targetSelector = focusMatch[1];
+        const normalizedSelector = this.normalizeMetadataSelector(targetSelector);
+        const targetElement = normalizedSelector ? document.querySelector(normalizedSelector) : null;
+        if (targetElement) {
+          if (this.options.debug) {
+            this.log("[Metadata] Focusing element:", normalizedSelector);
+          }
+          if (targetElement.tabIndex === -1 && !targetElement.hasAttribute("tabindex")) {
+            targetElement.setAttribute("tabindex", "-1");
+          }
+          this.setManagedTimeout(() => {
+            targetElement.focus();
+            targetElement.scrollIntoView({ behavior: "smooth", block: "nearest" });
+          }, 10);
+        } else if (this.options.debug) {
+          this.log("[Metadata] Element not found:", normalizedSelector || targetSelector);
+        }
+        this.emit("metadata:focus", {
+          time: cue.startTime,
+          target: targetSelector,
+          selector: normalizedSelector,
+          element: targetElement,
+          text
+        });
+        if (normalizedSelector) {
+          this.handleMetadataAlert(normalizedSelector, {
+            element: targetElement,
+            reason: "focus"
+          });
+        }
+      }
+      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,
+          text
+        });
+        this.handleMetadataHashtags(hashtags);
+      }
+    }
   };
   Player.instances = [];