@arraypress/waveform-player 1.7.2 → 1.8.0

package/dist/waveform-player.js

@@ -1,20 +1,68 @@
 (() => {
   // src/js/utils.js
+  function escapeHtml(str) {
+    return String(str == null ? "" : str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+  }
+  function isSafeHref(url) {
+    if (typeof url !== "string" || url === "") return false;
+    try {
+      const u = new URL(url, "http://localhost/");
+      return u.protocol === "http:" || u.protocol === "https:";
+    } catch (e) {
+      return false;
+    }
+  }
+  function clamp(value, min = 0, max = 1) {
+    return Math.max(min, Math.min(value, max));
+  }
+  function parseBoolAttr(value) {
+    return value === void 0 ? void 0 : value === "true";
+  }
+  function parseColorValue(value) {
+    if (typeof value === "string" && value.trim().startsWith("[")) {
+      try {
+        return JSON.parse(value);
+      } catch (e) {
+      }
+    }
+    return value;
+  }
   function parseDataAttributes(element) {
     const options = {};
+    const setBool = (optKey, dataKey = optKey) => {
+      const v = parseBoolAttr(element.dataset[dataKey]);
+      if (v !== void 0) options[optKey] = v;
+    };
+    const setNum = (optKey, dataKey = optKey, float = false) => {
+      const raw = element.dataset[dataKey];
+      if (raw) options[optKey] = float ? parseFloat(raw) : parseInt(raw, 10);
+    };
+    const setJson = (optKey, dataKey = optKey) => {
+      const raw = element.dataset[dataKey];
+      if (!raw) return;
+      try {
+        options[optKey] = JSON.parse(raw);
+      } catch (e) {
+        console.warn(`[WaveformPlayer] Invalid ${dataKey} JSON:`, e);
+      }
+    };
+    if (element.dataset.src) options.url = element.dataset.src;
     if (element.dataset.url) options.url = element.dataset.url;
-    if (element.dataset.height) options.height = parseInt(element.dataset.height);
-    if (element.dataset.samples) options.samples = parseInt(element.dataset.samples);
+    setNum("height");
+    setNum("samples");
     if (element.dataset.preload) {
       options.preload = element.dataset.preload;
     }
+    if (element.dataset.audioMode) options.audioMode = element.dataset.audioMode;
+    if (element.dataset.style) options.waveformStyle = element.dataset.style;
     if (element.dataset.waveformStyle) options.waveformStyle = element.dataset.waveformStyle;
-    if (element.dataset.barWidth) options.barWidth = parseInt(element.dataset.barWidth);
-    if (element.dataset.barSpacing) options.barSpacing = parseInt(element.dataset.barSpacing);
+    setNum("barWidth");
+    setNum("barSpacing");
+    setNum("barRadius");
     if (element.dataset.buttonAlign) options.buttonAlign = element.dataset.buttonAlign;
     if (element.dataset.colorPreset) options.colorPreset = element.dataset.colorPreset;
-    if (element.dataset.waveformColor) options.waveformColor = element.dataset.waveformColor;
-    if (element.dataset.progressColor) options.progressColor = element.dataset.progressColor;
+    if (element.dataset.waveformColor) options.waveformColor = parseColorValue(element.dataset.waveformColor);
+    if (element.dataset.progressColor) options.progressColor = parseColorValue(element.dataset.progressColor);
     if (element.dataset.buttonColor) options.buttonColor = element.dataset.buttonColor;
     if (element.dataset.buttonHoverColor) options.buttonHoverColor = element.dataset.buttonHoverColor;
     if (element.dataset.textColor) options.textColor = element.dataset.textColor;
@@ -23,53 +71,50 @@
     if (element.dataset.borderColor) options.borderColor = element.dataset.borderColor;
     if (element.dataset.color) options.waveformColor = element.dataset.color;
     if (element.dataset.theme) options.colorPreset = element.dataset.theme;
-    if (element.dataset.autoplay) options.autoplay = element.dataset.autoplay === "true";
-    if (element.dataset.showControls !== void 0) options.showControls = element.dataset.showControls === "true";
-    if (element.dataset.showInfo !== void 0) options.showInfo = element.dataset.showInfo === "true";
-    if (element.dataset.showTime) options.showTime = element.dataset.showTime === "true";
-    if (element.dataset.showHoverTime) options.showHoverTime = element.dataset.showHoverTime === "true";
-    if (element.dataset.showBpm) options.showBPM = element.dataset.showBpm === "true";
-    if (element.dataset.singlePlay) options.singlePlay = element.dataset.singlePlay === "true";
-    if (element.dataset.playOnSeek) options.playOnSeek = element.dataset.playOnSeek === "true";
+    setBool("autoplay");
+    setBool("showControls");
+    setBool("showInfo");
+    setBool("showTime");
+    setBool("showHoverTime");
+    setBool("showBPM", "showBpm");
+    setBool("singlePlay");
+    setBool("playOnSeek");
     if (element.dataset.title) options.title = element.dataset.title;
     if (element.dataset.subtitle) options.subtitle = element.dataset.subtitle;
     if (element.dataset.album) options.album = element.dataset.album;
     if (element.dataset.artwork) options.artwork = element.dataset.artwork;
     if (element.dataset.waveform) options.waveform = element.dataset.waveform;
-    if (element.dataset.markers) {
-      try {
-        options.markers = JSON.parse(element.dataset.markers);
-      } catch (e) {
-        console.warn("Invalid markers JSON:", e);
-      }
-    }
-    if (element.dataset.playbackRate) {
-      options.playbackRate = parseFloat(element.dataset.playbackRate);
-    }
-    if (element.dataset.showPlaybackSpeed !== void 0) {
-      options.showPlaybackSpeed = element.dataset.showPlaybackSpeed === "true";
-    }
-    if (element.dataset.playbackRates) {
-      try {
-        options.playbackRates = JSON.parse(element.dataset.playbackRates);
-      } catch (e) {
-        console.warn("Invalid playbackRates JSON:", e);
-      }
-    }
-    if (element.dataset.enableMediaSession !== void 0) {
-      options.enableMediaSession = element.dataset.enableMediaSession === "true";
-    }
+    setJson("markers");
+    setNum("playbackRate", "playbackRate", true);
+    setBool("showPlaybackSpeed");
+    setJson("playbackRates");
+    setBool("enableMediaSession");
+    setBool("showMarkers");
+    setBool("accessibleSeek");
+    if (element.dataset.seekLabel) options.seekLabel = element.dataset.seekLabel;
+    if (element.dataset.errorText) options.errorText = element.dataset.errorText;
+    if (element.dataset.playIcon) options.playIcon = element.dataset.playIcon;
+    if (element.dataset.pauseIcon) options.pauseIcon = element.dataset.pauseIcon;
     return options;
   }
   function formatTime(seconds) {
-    if (!seconds || isNaN(seconds)) return "0:00";
-    const mins = Math.floor(seconds / 60);
+    if (!seconds || isNaN(seconds) || seconds < 0) return "0:00";
+    const hrs = Math.floor(seconds / 3600);
+    const mins = Math.floor(seconds % 3600 / 60);
     const secs = Math.floor(seconds % 60);
+    if (hrs > 0) {
+      return `${hrs}:${mins.toString().padStart(2, "0")}:${secs.toString().padStart(2, "0")}`;
+    }
     return `${mins}:${secs.toString().padStart(2, "0")}`;
   }
+  var idCounter = 0;
   function generateId(url) {
-    const str = url || Math.random().toString();
-    return btoa(str.substring(0, 10)).replace(/[^a-zA-Z0-9]/g, "");
+    const str = url || "audio";
+    let hash = 5381;
+    for (let i = 0; i < str.length; i++) {
+      hash = (hash << 5) + hash + str.charCodeAt(i) | 0;
+    }
+    return `wp_${(hash >>> 0).toString(36)}_${(idCounter++).toString(36)}`;
   }
   function extractTitleFromUrl(url) {
     if (!url) return "Audio";
@@ -78,6 +123,12 @@
     const name = filename.split(".")[0];
     return name.replace(/[-_]/g, " ").replace(/\b\w/g, (l) => l.toUpperCase());
   }
+  function perceivedBrightness(color) {
+    const rgb = typeof color === "string" ? color.match(/\d+/g) : null;
+    if (!rgb || rgb.length < 3) return null;
+    const [r, g, b] = rgb.map(Number);
+    return (r * 299 + g * 587 + b * 114) / 1e3;
+  }
   function mergeOptions(...sources) {
     const result = {};
     for (const source of sources) {
@@ -144,6 +195,42 @@
   }
 
   // src/js/drawing.js
+  function makeFill(ctx, value, height) {
+    if (!Array.isArray(value)) return value;
+    if (value.length === 1) return value[0];
+    const grad = ctx.createLinearGradient(0, 0, 0, height);
+    value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
+    return grad;
+  }
+  function fillBar(ctx, x, y, w, h, radii) {
+    const any = Array.isArray(radii) ? radii.some((r) => r > 0) : radii > 0;
+    if (any && typeof ctx.roundRect === "function") {
+      const max = Math.min(w / 2, Math.abs(h) / 2);
+      const clampR = (r) => clamp(r, 0, max);
+      ctx.beginPath();
+      ctx.roundRect(x, y, w, h, Array.isArray(radii) ? radii.map(clampR) : clampR(radii));
+      ctx.fill();
+    } else {
+      ctx.fillRect(x, y, w, h);
+    }
+  }
+  function barRadiusPx(options, dpr) {
+    return (options.barRadius || 0) * dpr;
+  }
+  function barRadii(options, dpr) {
+    const r = barRadiusPx(options, dpr);
+    return [r, r, 0, 0];
+  }
+  function capsulePath(ctx, startX, endX, centerY, barHeight) {
+    const r = barHeight / 2;
+    ctx.beginPath();
+    ctx.moveTo(startX, centerY - r);
+    ctx.lineTo(endX - r, centerY - r);
+    ctx.arc(endX - r, centerY, r, -Math.PI / 2, Math.PI / 2);
+    ctx.lineTo(startX, centerY + r);
+    ctx.arc(startX, centerY, r, Math.PI / 2, -Math.PI / 2);
+    ctx.closePath();
+  }
   function drawBars(ctx, canvas, peaks, progress, options) {
     const dpr = window.devicePixelRatio || 1;
     const barWidth = options.barWidth * dpr;
@@ -152,26 +239,29 @@
     const resampledPeaks = resampleData(peaks, barCount);
     const height = canvas.height;
     const progressWidth = progress * canvas.width;
+    const radii = barRadii(options, dpr);
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
     ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.fillStyle = baseFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
       const x = i * (barWidth + barSpacing);
       if (x + barWidth > canvas.width) break;
       const peakHeight = resampledPeaks[i] * height * 0.9;
       const y = height - peakHeight;
-      ctx.fillStyle = options.color;
-      ctx.fillRect(x, y, barWidth, peakHeight);
+      fillBar(ctx, x, y, barWidth, peakHeight, radii);
     }
     ctx.save();
     ctx.beginPath();
     ctx.rect(0, 0, progressWidth, height);
     ctx.clip();
+    ctx.fillStyle = progFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
       const x = i * (barWidth + barSpacing);
       if (x > progressWidth) break;
       const peakHeight = resampledPeaks[i] * height * 0.9;
       const y = height - peakHeight;
-      ctx.fillStyle = options.progressColor;
-      ctx.fillRect(x, y, barWidth, peakHeight);
+      fillBar(ctx, x, y, barWidth, peakHeight, radii);
     }
     ctx.restore();
   }
@@ -184,26 +274,31 @@
     const height = canvas.height;
     const centerY = height / 2;
     const progressWidth = progress * canvas.width;
+    const r = barRadiusPx(options, dpr);
+    const topRadii = [r, r, 0, 0];
+    const botRadii = [0, 0, r, r];
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
     ctx.clearRect(0, 0, canvas.width, canvas.height);
+    ctx.fillStyle = baseFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
       const x = i * (barWidth + barSpacing);
       if (x + barWidth > canvas.width) break;
       const peakHeight = resampledPeaks[i] * height * 0.45;
-      ctx.fillStyle = options.color;
-      ctx.fillRect(x, centerY - peakHeight, barWidth, peakHeight);
-      ctx.fillRect(x, centerY, barWidth, peakHeight);
+      fillBar(ctx, x, centerY - peakHeight, barWidth, peakHeight, topRadii);
+      fillBar(ctx, x, centerY, barWidth, peakHeight, botRadii);
     }
     ctx.save();
     ctx.beginPath();
     ctx.rect(0, 0, progressWidth, height);
     ctx.clip();
+    ctx.fillStyle = progFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
       const x = i * (barWidth + barSpacing);
       if (x > progressWidth) break;
       const peakHeight = resampledPeaks[i] * height * 0.45;
-      ctx.fillStyle = options.progressColor;
-      ctx.fillRect(x, centerY - peakHeight, barWidth, peakHeight);
-      ctx.fillRect(x, centerY, barWidth, peakHeight);
+      fillBar(ctx, x, centerY - peakHeight, barWidth, peakHeight, topRadii);
+      fillBar(ctx, x, centerY, barWidth, peakHeight, botRadii);
     }
     ctx.restore();
   }
@@ -274,13 +369,15 @@
     const blockGap = 2 * dpr;
     const progressWidth = progress * canvas.width;
     const centerY = height / 2;
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
     ctx.clearRect(0, 0, canvas.width, canvas.height);
     for (let i = 0; i < resampledPeaks.length; i++) {
       const x = i * (barWidth + barSpacing);
       if (x + barWidth > canvas.width) break;
       const peakHeight = resampledPeaks[i] * height * 0.9;
       const blockCount = Math.floor(peakHeight / (blockSize + blockGap));
-      ctx.fillStyle = x < progressWidth ? options.progressColor : options.color;
+      ctx.fillStyle = x < progressWidth ? progFill : baseFill;
       for (let j = 0; j < blockCount; j++) {
         const blockOffset = j * (blockSize + blockGap);
         ctx.fillRect(x, centerY - blockOffset - blockSize, barWidth, blockSize);
@@ -300,12 +397,14 @@
     const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
     const progressWidth = progress * canvas.width;
     const centerY = height / 2;
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
     ctx.clearRect(0, 0, canvas.width, canvas.height);
     for (let i = 0; i < resampledPeaks.length; i++) {
       const x = i * (barWidth + barSpacing) + barWidth / 2;
       if (x > canvas.width) break;
       const peakHeight = resampledPeaks[i] * height * 0.9;
-      ctx.fillStyle = x < progressWidth ? options.progressColor : options.color;
+      ctx.fillStyle = x < progressWidth ? progFill : baseFill;
       ctx.beginPath();
       ctx.arc(x, centerY - peakHeight / 2, dotRadius, 0, Math.PI * 2);
       ctx.fill();
@@ -322,26 +421,14 @@
     const borderRadius = barHeight / 2;
     ctx.clearRect(0, 0, width, height);
     ctx.fillStyle = options.color || "rgba(255, 255, 255, 0.2)";
-    ctx.beginPath();
-    ctx.moveTo(borderRadius, centerY - barHeight / 2);
-    ctx.lineTo(width - borderRadius, centerY - barHeight / 2);
-    ctx.arc(width - borderRadius, centerY, barHeight / 2, -Math.PI / 2, Math.PI / 2);
-    ctx.lineTo(borderRadius, centerY + barHeight / 2);
-    ctx.arc(borderRadius, centerY, barHeight / 2, Math.PI / 2, -Math.PI / 2);
-    ctx.closePath();
+    capsulePath(ctx, borderRadius, width, centerY, barHeight);
     ctx.fill();
     if (progress > 0) {
       const progressWidth = Math.max(borderRadius * 2, progress * width);
       ctx.shadowBlur = 8;
       ctx.shadowColor = options.progressColor;
       ctx.fillStyle = options.progressColor || "rgba(255, 255, 255, 0.9)";
-      ctx.beginPath();
-      ctx.moveTo(borderRadius, centerY - barHeight / 2);
-      ctx.lineTo(progressWidth - borderRadius, centerY - barHeight / 2);
-      ctx.arc(progressWidth - borderRadius, centerY, barHeight / 2, -Math.PI / 2, Math.PI / 2);
-      ctx.lineTo(borderRadius, centerY + barHeight / 2);
-      ctx.arc(borderRadius, centerY, barHeight / 2, Math.PI / 2, -Math.PI / 2);
-      ctx.closePath();
+      capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
       ctx.fill();
       ctx.shadowBlur = 0;
       const handleRadius = 8;
@@ -417,7 +504,7 @@
       }
       return detectedBPM - 1;
     } catch (e) {
-      console.warn("BPM detection failed:", e);
+      console.warn("[WaveformPlayer] BPM detection failed:", e);
       return null;
     }
   }
@@ -474,8 +561,11 @@
     return maxPeak > 0 ? peaks.map((peak) => peak / maxPeak) : peaks;
   }
   async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
+    let audioContext;
     try {
-      const audioContext = new (window.AudioContext || window.webkitAudioContext)();
+      const AudioCtx = window.AudioContext || /** @type {any} */
+      window.webkitAudioContext;
+      audioContext = new AudioCtx();
       const response = await fetch(url);
       const arrayBuffer = await response.arrayBuffer();
       const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
@@ -483,13 +573,11 @@
       peaks = normalizePeaks(peaks);
       let bpm = null;
       if (shouldDetectBPM) {
-        bpm = await detectBPM(audioBuffer);
+        bpm = detectBPM(audioBuffer);
       }
-      audioContext.close();
       return { peaks, bpm };
-    } catch (error) {
-      console.error("Failed to generate waveform:", error);
-      throw error;
+    } finally {
+      if (audioContext) audioContext.close();
     }
   }
   function generatePlaceholderWaveform(samples = 200) {
@@ -497,7 +585,7 @@
     for (let i = 0; i < samples; i++) {
       const base = Math.random() * 0.5 + 0.3;
       const variation = Math.sin(i / samples * Math.PI * 4) * 0.2;
-      data.push(Math.max(0.1, Math.min(1, base + variation)));
+      data.push(clamp(base + variation, 0.1, 1));
     }
     return data;
   }
@@ -509,26 +597,20 @@
   }
 
   // src/js/themes.js
-  function detectColorScheme() {
+  function hasThemeHint(scheme) {
     const root = document.documentElement;
     const body = document.body;
-    if (root.classList.contains("dark") || root.classList.contains("dark-mode") || root.classList.contains("theme-dark") || root.getAttribute("data-theme") === "dark" || root.getAttribute("data-color-scheme") === "dark" || body.classList.contains("dark") || body.classList.contains("dark-mode") || body.getAttribute("data-theme") === "dark") {
-      return "dark";
-    }
-    if (root.classList.contains("light") || root.classList.contains("light-mode") || root.classList.contains("theme-light") || root.getAttribute("data-theme") === "light" || root.getAttribute("data-color-scheme") === "light" || body.classList.contains("light") || body.classList.contains("light-mode") || body.getAttribute("data-theme") === "light") {
-      return "light";
-    }
+    return root.classList.contains(scheme) || root.classList.contains(`${scheme}-mode`) || root.classList.contains(`theme-${scheme}`) || root.getAttribute("data-theme") === scheme || root.getAttribute("data-color-scheme") === scheme || body.classList.contains(scheme) || body.classList.contains(`${scheme}-mode`) || body.getAttribute("data-theme") === scheme;
+  }
+  function detectColorScheme() {
+    if (hasThemeHint("dark")) return "dark";
+    if (hasThemeHint("light")) return "light";
     try {
       const bodyBg = getComputedStyle(document.body).backgroundColor;
-      const rgb = bodyBg.match(/\d+/g);
-      if (rgb && rgb.length >= 3) {
-        const [r, g, b] = rgb.map(Number);
-        const brightness = (r * 299 + g * 587 + b * 114) / 1e3;
-        if (brightness > 128) {
-          return "light";
-        } else if (brightness < 128) {
-          return "dark";
-        }
+      const brightness = perceivedBrightness(bodyBg);
+      if (brightness !== null) {
+        if (brightness > 128) return "light";
+        if (brightness < 128) return "dark";
       }
     } catch (e) {
     }
@@ -593,6 +675,8 @@
     waveformStyle: "mirror",
     barWidth: 2,
     barSpacing: 0,
+    // Rounded bar caps (px). 0 = square (default). Applies to bars/mirror.
+    barRadius: 0,
     // Color preset: null = auto-detect, 'dark' = force dark, 'light' = force light
     colorPreset: null,
     // Individual color overrides (null means use preset)
@@ -628,6 +712,8 @@
     subtitle: null,
     artwork: null,
     album: "",
+    // Message shown in the error state when audio fails to load.
+    errorText: "Unable to load audio",
     // Icons (SVG)
     playIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M8 5v14l11-7z"/></svg>',
     pauseIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M6 4h4v16H6zM14 4h4v16h-4z"/></svg>',
@@ -657,17 +743,32 @@
     /** @type {WaveformPlayer|null} */
     static currentlyPlaying = null;
     /**
-     * Create a new WaveformPlayer instance
-     * @param {string|HTMLElement} container - Container element or selector
-     * @param {Object} options - Player options
+     * Create a new WaveformPlayer instance.
+     *
+     * Resolves the container, merges options (defaults < `data-*` attributes <
+     * constructor options), applies the colour preset and style-specific
+     * defaults, registers the instance in the static map, and kicks off
+     * {@link WaveformPlayer#init}. A `waveformplayer:ready` event is dispatched
+     * ~100ms later, once initialization has settled.
+     *
+     * @param {string|HTMLElement} container - Container element, or a CSS
+     *   selector resolved with `document.querySelector`.
+     * @param {Object} [options={}] - Player options. Accepts the shorthand
+     *   aliases `style` (→ `waveformStyle`) and `src` (→ `url`); the canonical
+     *   names win if both are supplied.
+     * @throws {Error} If the container element cannot be found.
+     * @fires WaveformPlayer#waveformplayer:ready
      */
     constructor(container, options = {}) {
       this.container = typeof container === "string" ? document.querySelector(container) : container;
       if (!this.container) {
-        throw new Error("WaveformPlayer: Container element not found");
+        throw new Error("[WaveformPlayer] Container element not found");
       }
       const dataOptions = parseDataAttributes(this.container);
-      this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, options);
+      const userOptions = { ...options };
+      if (userOptions.style && !userOptions.waveformStyle) userOptions.waveformStyle = userOptions.style;
+      if (userOptions.src && !userOptions.url) userOptions.url = userOptions.src;
+      this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions);
       const preset = getColorPreset(this.options.colorPreset);
       for (const [key, value] of Object.entries(preset)) {
         if (this.options[key] === null || this.options[key] === void 0) {
@@ -693,21 +794,54 @@
       this.hasError = false;
       this.updateTimer = null;
       this.resizeObserver = null;
+      this._ac = new AbortController();
       this.id = this.container.id || generateId(this.options.url);
       _WaveformPlayer.instances.set(this.id, this);
       this.init();
       setTimeout(() => {
-        this.container.dispatchEvent(new CustomEvent("waveformplayer:ready", {
-          bubbles: true,
-          detail: { player: this, url: this.options.url }
-        }));
+        this._emit("waveformplayer:ready", { player: this, url: this.options.url });
       }, 100);
     }
+    /**
+     * Build and dispatch a bubbling `waveformplayer:*` CustomEvent on the
+     * container, returning the event so cancelable (request-*) events can have
+     * their `defaultPrevented` checked. Single source of truth for the event
+     * shape — every player event bubbles and carries the supplied detail.
+     * @param {string} type - Full event type, e.g. `'waveformplayer:play'`.
+     * @param {Object} detail - Event detail payload.
+     * @param {boolean} [cancelable=false] - Whether the event is cancelable.
+     * @returns {CustomEvent} The dispatched event.
+     * @private
+     */
+    _emit(type, detail, cancelable = false) {
+      const event = new CustomEvent(type, { bubbles: true, cancelable, detail });
+      this.container.dispatchEvent(event);
+      return event;
+    }
+    /**
+     * External-mode seek request: dispatch a cancelable
+     * `waveformplayer:request-seek` and, unless the controller calls
+     * `preventDefault()`, optimistically advance the local progress overlay so
+     * the canvas repaints at once. Shared by the keyboard slider and canvas click.
+     * @param {number} percent - Target position as a 0..1 fraction.
+     * @private
+     * @fires WaveformPlayer#waveformplayer:request-seek
+     */
+    _requestSeek(percent) {
+      const evt = this._emit("waveformplayer:request-seek", { ...this._buildTrackDetail(), percent }, true);
+      if (!evt.defaultPrevented) {
+        this.progress = percent;
+        this.drawWaveform?.();
+      }
+    }
     // ============================================
     // Initialization
     // ============================================
     /**
-     * Initialize the player
+     * Initialize the player: build the DOM, create the audio element (self
+     * mode only), wire up the feature controls (speed, keyboard, accessible
+     * seek), bind events, attach the resize observer, then size the canvas and
+     * — if a `url` option was given — load it and optionally autoplay.
      * @private
      */
     init() {
@@ -723,16 +857,24 @@
         if (this.options.url) {
           this.load(this.options.url).then(() => {
             if (this.options.autoplay) {
-              this.play();
+              this.play()?.catch(() => {
+              });
             }
           }).catch((error) => {
-            console.error("Failed to load audio:", error);
+            console.error("[WaveformPlayer] Failed to load audio:", error);
           });
         }
       });
     }
     /**
-     * Create DOM elements
+     * Build the player's DOM tree inside the container and cache element
+     * references.
+     *
+     * Clears the container, resolves button alignment (`auto` → `bottom` for
+     * the `bars` style, `center` otherwise), and conditionally renders the play
+     * button, info row (artwork/title/subtitle), BPM badge, playback-speed
+     * menu, and time display based on the relevant `show*` options. Caches the
+     * canvas, controls, and text elements onto `this`, then sizes the canvas.
      * @private
      */
     createDOM() {
@@ -807,8 +949,8 @@
           <canvas></canvas>
           <div class="waveform-markers"></div>
           <div class="waveform-loading" style="display:none;"></div>
-          <div class="waveform-error" style="display:none;">
-            <span class="waveform-error-text">Unable to load audio</span>
+          <div class="waveform-error" style="display:none;" role="alert">
+            <span class="waveform-error-text">${escapeHtml(this.options.errorText)}</span>
           </div>
         </div>
       </div>
@@ -857,7 +999,9 @@
     // Feature Initialization
     // ============================================
     /**
-     * Initialize playback speed controls
+     * Apply the configured initial playback rate to the audio element (self
+     * mode only) and, when `showPlaybackSpeed` is enabled, wire up the speed
+     * menu UI via {@link WaveformPlayer#initSpeedControls}.
      * @private
      */
     initPlaybackSpeed() {
@@ -869,7 +1013,11 @@
       }
     }
     /**
-     * Initialize speed control UI
+     * Wire up the playback-speed menu: toggle it open on the speed button,
+     * close it on any outside click, and apply the chosen rate when a
+     * `.speed-option` is clicked. All listeners are registered against the
+     * instance `AbortController` signal so {@link WaveformPlayer#destroy} tears
+     * them down. No-op if the speed elements are absent.
      * @private
      */
     initSpeedControls() {
@@ -879,10 +1027,10 @@
       speedBtn.addEventListener("click", (e) => {
         e.stopPropagation();
         speedMenu.style.display = speedMenu.style.display === "none" ? "block" : "none";
-      });
+      }, { signal: this._ac.signal });
       document.addEventListener("click", () => {
         speedMenu.style.display = "none";
-      });
+      }, { signal: this._ac.signal });
       speedMenu.addEventListener("click", (e) => {
         e.stopPropagation();
         if (e.target.classList.contains("speed-option")) {
@@ -890,11 +1038,18 @@
           this.setPlaybackRate(rate);
           speedMenu.style.display = "none";
         }
-      });
+      }, { signal: this._ac.signal });
       this.updateSpeedUI();
     }
     /**
-     * Initialize keyboard controls
+     * Enable keyboard transport controls on the container.
+     *
+     * The container is focusable only after it is clicked (it carries
+     * `tabindex="-1"` until then, and clicking steals focus from sibling
+     * players). While focused it handles: digits 0-9 (seek to that tenth of
+     * the track), Space (toggle play), and — in self mode only, since
+     * `this.audio` is null in external mode — arrow keys (seek ±5s, volume
+     * ±0.1) and `m`/`M` (mute). Listeners use the instance abort signal.
      * @private
      */
     initKeyboardControls() {
@@ -907,7 +1062,7 @@
         });
         this.container.setAttribute("tabindex", "0");
         this.container.focus();
-      });
+      }, { signal: this._ac.signal });
       this.container.addEventListener("keydown", (e) => {
         if (document.activeElement !== this.container) return;
         const key = e.key;
@@ -922,17 +1077,17 @@
           " ": () => this.togglePlay()
         };
         if (hasAudio) {
-          actions["ArrowLeft"] = () => this.seekTo(Math.max(0, currentTime - 5));
-          actions["ArrowRight"] = () => this.seekTo(Math.min(this.audio.duration, currentTime + 5));
-          actions["ArrowUp"] = () => this.setVolume(Math.min(1, this.audio.volume + 0.1));
-          actions["ArrowDown"] = () => this.setVolume(Math.max(0, this.audio.volume - 0.1));
+          actions["ArrowLeft"] = () => this.seekTo(clamp(currentTime - 5, 0, this.audio.duration));
+          actions["ArrowRight"] = () => this.seekTo(clamp(currentTime + 5, 0, this.audio.duration));
+          actions["ArrowUp"] = () => this.setVolume(clamp(this.audio.volume + 0.1));
+          actions["ArrowDown"] = () => this.setVolume(clamp(this.audio.volume - 0.1));
           actions["m"] = actions["M"] = () => this.audio.muted = !this.audio.muted;
         }
         if (actions[key]) {
           e.preventDefault();
           actions[key]();
         }
-      });
+      }, { signal: this._ac.signal });
     }
     /**
      * Expose the waveform as an accessible, keyboard-operable slider.
@@ -984,7 +1139,7 @@
         e.preventDefault();
         e.stopPropagation();
         this.seekToSeconds(target);
-      });
+      }, { signal: this._ac.signal });
     }
     /**
      * Total seekable duration in seconds, regardless of audio mode.
@@ -1010,26 +1165,22 @@
     }
     /**
      * Seek the slider to an absolute time, clamped to the track length.
-     * Routes through the external controller in external mode.
+     *
+     * In self mode this defers to {@link WaveformPlayer#seekTo}. In external
+     * mode it dispatches a cancelable `waveformplayer:request-seek` event with
+     * the target percentage; if the controller doesn't `preventDefault()`, the
+     * local progress/visual is updated optimistically. Either way the ARIA
+     * slider values are refreshed.
      * @param {number} seconds - Target time in seconds.
      * @private
+     * @fires WaveformPlayer#waveformplayer:request-seek
      */
     seekToSeconds(seconds) {
       const duration = this.getSeekDuration();
       if (!duration) return;
-      const clamped = Math.max(0, Math.min(seconds, duration));
+      const clamped = clamp(seconds, 0, duration);
       if (this.options.audioMode === "external") {
-        const percent = clamped / duration;
-        const evt = new CustomEvent("waveformplayer:request-seek", {
-          bubbles: true,
-          cancelable: true,
-          detail: { ...this._buildTrackDetail(), percent }
-        });
-        this.container.dispatchEvent(evt);
-        if (!evt.defaultPrevented) {
-          this.progress = percent;
-          this.drawWaveform?.();
-        }
+        this._requestSeek(clamped / duration);
         this.updateSeekAccessibility();
         return;
       }
@@ -1037,7 +1188,9 @@
     }
     /**
      * Set the slider's accessible name from `seekLabel`, falling back to the
-     * track title, then a generic 'Seek'.
+     * track title, then a generic 'Seek'. No-op if the slider isn't present.
+     * @param {string} [title=this.options.title] - Track title to fall back to
+     *   when `seekLabel` is not set.
      * @private
      */
     applySeekLabel(title = this.options.title) {
@@ -1078,10 +1231,10 @@
       navigator.mediaSession.setActionHandler("play", () => this.play());
       navigator.mediaSession.setActionHandler("pause", () => this.pause());
       navigator.mediaSession.setActionHandler("seekbackward", () => {
-        this.seekTo(Math.max(0, this.audio.currentTime - 10));
+        this.seekTo(clamp(this.audio.currentTime - 10, 0, this.audio.duration));
       });
       navigator.mediaSession.setActionHandler("seekforward", () => {
-        this.seekTo(Math.min(this.audio.duration, this.audio.currentTime + 10));
+        this.seekTo(clamp(this.audio.currentTime + 10, 0, this.audio.duration));
       });
       navigator.mediaSession.setActionHandler("seekto", (details) => {
         if (details.seekTime !== null) {
@@ -1093,7 +1246,10 @@
     // Event Binding
     // ============================================
     /**
-     * Bind event listeners
+     * Bind the core interaction listeners: play-button click, the `<audio>`
+     * media events (self mode only — external mode is fed state via
+     * {@link WaveformPlayer#setPlayingState}/{@link WaveformPlayer#setProgress}),
+     * canvas click-to-seek, and a debounced window-resize redraw.
      * @private
      */
     bindEvents() {
@@ -1114,7 +1270,8 @@
       window.addEventListener("resize", this.resizeHandler);
     }
     /**
-     * Setup resize observer
+     * Observe the canvas's parent element for size changes and re-fit the
+     * canvas on each one. No-op where `ResizeObserver` is unavailable.
      * @private
      */
     setupResizeObserver() {
@@ -1131,9 +1288,20 @@
     // Audio Loading
     // ============================================
     /**
-     * Load audio file
-     * @param {string} url - Audio URL
-     * @returns {Promise<void>}
+     * Load an audio source: set the title, fetch/generate the waveform peaks,
+     * draw them, render markers, and initialise Media Session.
+     *
+     * In self mode the `<audio>` src is assigned and the method awaits
+     * `loadedmetadata` before proceeding. In external mode there is no audio
+     * element, so the src/metadata step is skipped and only the visualization
+     * is built (duration/time come from the controller via
+     * {@link WaveformPlayer#setProgress}). Peaks come from the `waveform`
+     * option when provided, otherwise they are decoded from the audio; a
+     * decode failure falls back to a placeholder waveform. The `onLoad`
+     * callback fires on success.
+     * @param {string} url - Audio URL.
+     * @returns {Promise<void>} Resolves once loading settles (errors are caught
+     *   internally and surfaced through {@link WaveformPlayer#onError}).
      */
     async load(url) {
       try {
@@ -1173,7 +1341,7 @@
               this.updateBPMDisplay();
             }
           } catch (error) {
-            console.warn("Using placeholder waveform:", error);
+            console.warn("[WaveformPlayer] Using placeholder waveform:", error);
             this.waveformData = generatePlaceholderWaveform(this.options.samples);
           }
         }
@@ -1184,18 +1352,26 @@
           this.options.onLoad(this);
         }
       } catch (error) {
-        console.error("Failed to load audio:", error);
         this.onError(error);
       } finally {
         this.setLoading(false);
       }
     }
     /**
-     * Load a new track
-     * @param {string} url - Audio URL
-     * @param {string} [title] - Track title
-     * @param {string} [subtitle] - Track subtitle
-     * @param {Object} [options] - Additional options
+     * Swap the player to a new track at runtime.
+     *
+     * Pauses any current playback, fully resets the audio element (self mode),
+     * clears error/marker/progress state, merges the new metadata into
+     * `this.options`, updates the subtitle/artwork DOM, then calls
+     * {@link WaveformPlayer#load}. Auto-plays the new track unless
+     * `options.autoplay === false`.
+     * @param {string} url - Audio URL.
+     * @param {string|null} [title=null] - Track title; keeps the existing
+     *   title when null.
+     * @param {string|null} [subtitle=null] - Track subtitle; pass `''` to hide
+     *   the subtitle row, or null to keep the existing one.
+     * @param {Object} [options={}] - Additional options to merge (e.g.
+     *   `preload`, `artwork`, `markers`, `autoplay`).
      * @returns {Promise<void>}
      */
     async loadTrack(url, title = null, subtitle = null, options = {}) {
@@ -1240,14 +1416,24 @@
       }
       this.options.markers = options.markers || [];
       await this.load(url);
-      this.play().catch(() => {
-      });
+      if (options.autoplay !== false) {
+        this.play()?.catch(() => {
+        });
+      }
     }
     // ============================================
     // Visualization
     // ============================================
     /**
-     * Set waveform data
+     * Normalise externally-supplied waveform data into `this.waveformData` and
+     * redraw.
+     *
+     * Accepts several shapes: a `.json` URL (fetched async; peaks and any
+     * embedded `markers` are applied on resolve), a JSON-encoded array string,
+     * a comma-separated number string, or a plain number array. Malformed
+     * input degrades to an empty array rather than throwing.
+     * @param {string|number[]} data - Peaks as an array, a JSON/CSV string, or
+     *   a URL to a `.json` peaks file.
      * @private
      */
     setWaveformData(data) {
@@ -1276,7 +1462,9 @@
       this.drawWaveform();
     }
     /**
-     * Draw waveform
+     * Render the current waveform + progress to the canvas via the shared
+     * {@link draw} routine, passing the resolved style and colours. No-op
+     * before the context exists or while there is no peak data.
      * @private
      */
     drawWaveform() {
@@ -1289,7 +1477,9 @@
       });
     }
     /**
-     * Resize canvas
+     * Re-fit the canvas backing store to its parent's width and the configured
+     * height, scaled by the device pixel ratio for crisp rendering, then
+     * redraw. Guards against running after destruction.
      * @private
      */
     resizeCanvas() {
@@ -1304,22 +1494,31 @@
       this.drawWaveform();
     }
     /**
-     * Render markers on the waveform
+     * Render the configured cue markers as positioned, clickable buttons over
+     * the waveform.
+     *
+     * Clears any existing markers first, then bails out unless `showMarkers` is
+     * on, markers exist, and a duration is known (via the mode-agnostic
+     * {@link WaveformPlayer#getSeekDuration}). Each marker is placed by its
+     * time-as-percentage, carries a tooltip and ARIA label, and seeks on click
+     * (also starting playback when `playOnSeek` is set and currently paused).
+     * Markers past the track duration are skipped with a warning.
      * @private
      */
     renderMarkers() {
       if (!this.markersContainer) return;
       this.markersContainer.innerHTML = "";
       if (!this.options.showMarkers || !this.options.markers?.length) return;
-      if (!this.audio || !this.audio.duration || this.audio.duration === 0) {
+      const duration = this.getSeekDuration();
+      if (!duration) {
         return;
       }
       this.options.markers.forEach((marker, index) => {
-        if (marker.time > this.audio.duration) {
-          console.warn(`Marker "${marker.label}" at ${marker.time}s exceeds audio duration of ${this.audio.duration}s`);
+        if (marker.time > duration) {
+          console.warn(`[WaveformPlayer] Marker "${marker.label}" at ${marker.time}s exceeds audio duration of ${duration}s`);
           return;
         }
-        const position = marker.time / this.audio.duration * 100;
+        const position = marker.time / duration * 100;
         const markerEl = document.createElement("button");
         markerEl.className = "waveform-marker";
         markerEl.style.left = `${position}%`;
@@ -1340,35 +1539,49 @@
         this.markersContainer.appendChild(markerEl);
       });
     }
+    /**
+     * Highlight the marker at `index` (toggling an `active` class) and clear
+     * the rest. Pass `null` to clear all. Lets an external controller (e.g. a
+     * DJ bar) reflect the current section without reaching into the player's
+     * private marker DOM.
+     * @param {number|null} index - Marker index to activate, or `null` to clear.
+     */
+    setActiveMarker(index) {
+      if (!this.markersContainer) return;
+      const markers = this.markersContainer.querySelectorAll(".waveform-marker");
+      markers.forEach((el, i) => el.classList.toggle("active", i === index));
+    }
     // ============================================
     // Event Handlers
     // ============================================
     /**
-     * Handle canvas click
+     * Seek to the clicked horizontal position on the waveform canvas.
+     *
+     * Converts the click X into a 0..1 percentage. In external mode it
+     * dispatches a cancelable `waveformplayer:request-seek` event (updating the
+     * local visual optimistically unless the controller vetoes it); in self
+     * mode it seeks the owned `<audio>` via
+     * {@link WaveformPlayer#seekToPercent}.
+     * @param {MouseEvent} event - The canvas click event.
      * @private
+     * @fires WaveformPlayer#waveformplayer:request-seek
      */
     handleCanvasClick(event) {
       const rect = this.canvas.getBoundingClientRect();
       const x = event.clientX - rect.left;
-      const targetPercent = Math.max(0, Math.min(1, x / rect.width));
+      const targetPercent = clamp(x / rect.width);
       if (this.options.audioMode === "external") {
-        const evt = new CustomEvent("waveformplayer:request-seek", {
-          bubbles: true,
-          cancelable: true,
-          detail: { ...this._buildTrackDetail(), percent: targetPercent }
-        });
-        this.container.dispatchEvent(evt);
-        if (!evt.defaultPrevented) {
-          this.progress = targetPercent;
-          this.drawWaveform?.();
-        }
+        this._requestSeek(targetPercent);
         return;
       }
       if (!this.audio || !this.audio.duration) return;
       this.seekToPercent(targetPercent);
     }
     /**
-     * Set loading state
+     * Toggle the loading state: show/hide the spinner overlay and set
+     * `aria-busy` on the accessible seek slider so assistive tech knows the
+     * player is fetching/decoding.
+     * @param {boolean} loading - True while audio is loading.
      * @private
      */
     setLoading(loading) {
@@ -1376,9 +1589,14 @@
       if (this.loadingEl) {
         this.loadingEl.style.display = loading ? "block" : "none";
       }
+      if (this.seekEl) {
+        this.seekEl.setAttribute("aria-busy", loading ? "true" : "false");
+      }
     }
     /**
-     * Handle metadata loaded
+     * `loadedmetadata` handler (self mode): write the total-time display, now
+     * that duration is known re-render markers, and publish duration to the
+     * accessible seek slider. No-op during destruction.
      * @private
      */
     onMetadataLoaded() {
@@ -1390,79 +1608,91 @@
       this.updateSeekAccessibility();
     }
     /**
-     * Handle play event
+     * Reflect play/pause state on the transport button: toggle the `playing`
+     * class and swap the play/pause icon visibility. The single source of
+     * truth shared by `onPlay`, `onPause`, and the external-mode
+     * `setPlayingState` pump so they can't drift. No-op without a button.
+     * @param {boolean} isPlaying - Whether playback is active.
      * @private
      */
+    setPlayButtonState(isPlaying) {
+      if (!this.playBtn) return;
+      this.playBtn.classList.toggle("playing", isPlaying);
+      const playIcon = this.playBtn.querySelector(".waveform-icon-play");
+      const pauseIcon = this.playBtn.querySelector(".waveform-icon-pause");
+      if (playIcon) playIcon.style.display = isPlaying ? "none" : "flex";
+      if (pauseIcon) pauseIcon.style.display = isPlaying ? "flex" : "none";
+    }
+    /**
+     * `play` handler (self mode): set the playing flag, swap the button to its
+     * pause icon, start the smooth progress loop, dispatch
+     * `waveformplayer:play`, and fire the `onPlay` callback. No-op during
+     * destruction.
+     * @private
+     * @fires WaveformPlayer#waveformplayer:play
+     */
     onPlay() {
       if (this.isDestroying) return;
       this.isPlaying = true;
-      if (this.playBtn) {
-        this.playBtn.classList.add("playing");
-        const playIcon = this.playBtn.querySelector(".waveform-icon-play");
-        const pauseIcon = this.playBtn.querySelector(".waveform-icon-pause");
-        if (playIcon) playIcon.style.display = "none";
-        if (pauseIcon) pauseIcon.style.display = "flex";
-      }
+      this.setPlayButtonState(true);
       this.startSmoothUpdate();
-      this.container.dispatchEvent(new CustomEvent("waveformplayer:play", {
-        bubbles: true,
-        detail: { player: this, url: this.options.url }
-      }));
+      this._emit("waveformplayer:play", { player: this, url: this.options.url });
       if (this.options.onPlay) {
         this.options.onPlay(this);
       }
     }
     /**
-     * Handle pause event
+     * `pause` handler (self mode): clear the playing flag, swap the button back
+     * to its play icon, stop the smooth progress loop, dispatch
+     * `waveformplayer:pause`, and fire the `onPause` callback. No-op during
+     * destruction.
      * @private
+     * @fires WaveformPlayer#waveformplayer:pause
      */
     onPause() {
       if (this.isDestroying) return;
       this.isPlaying = false;
-      if (this.playBtn) {
-        this.playBtn.classList.remove("playing");
-        const playIcon = this.playBtn.querySelector(".waveform-icon-play");
-        const pauseIcon = this.playBtn.querySelector(".waveform-icon-pause");
-        if (playIcon) playIcon.style.display = "flex";
-        if (pauseIcon) pauseIcon.style.display = "none";
-      }
+      this.setPlayButtonState(false);
       this.stopSmoothUpdate();
-      this.container.dispatchEvent(new CustomEvent("waveformplayer:pause", {
-        bubbles: true,
-        detail: { player: this, url: this.options.url }
-      }));
+      this._emit("waveformplayer:pause", { player: this, url: this.options.url });
       if (this.options.onPause) {
         this.options.onPause(this);
       }
     }
     /**
-     * Handle ended event
+     * `ended` handler (self mode): reset progress and `currentTime` to the
+     * start, redraw, reset the time display, dispatch `waveformplayer:ended`
+     * (carrying the final time), run {@link WaveformPlayer#onPause}, and fire
+     * the `onEnd` callback. No-op during destruction.
      * @private
+     * @fires WaveformPlayer#waveformplayer:ended
      */
     onEnded() {
       if (this.isDestroying) return;
+      const duration = this.audio.duration;
       this.progress = 0;
       this.audio.currentTime = 0;
       this.drawWaveform();
       if (this.currentTimeEl) {
         this.currentTimeEl.textContent = "0:00";
       }
-      this.container.dispatchEvent(new CustomEvent("waveformplayer:ended", {
-        bubbles: true,
-        detail: { player: this, url: this.options.url }
-      }));
+      this._emit("waveformplayer:ended", { player: this, url: this.options.url, currentTime: duration, duration });
       this.onPause();
       if (this.options.onEnd) {
         this.options.onEnd(this);
       }
     }
     /**
-     * Handle error event
+     * `error` handler: set the error flag, hide the spinner, reveal the error
+     * overlay, dim the canvas, disable the play button, and fire the `onError`
+     * callback. No-op during destruction.
+     * @param {Event|Error} error - The audio error event, or an Error thrown
+     *   during loading.
      * @private
      */
     onError(error) {
       if (this.isDestroying) return;
-      console.error("Audio error:", error);
+      console.error("[WaveformPlayer] Audio error:", error);
       this.hasError = true;
       this.setLoading(false);
       if (this.errorEl) {
@@ -1482,7 +1712,10 @@
     // Progress Updates
     // ============================================
     /**
-     * Start smooth update animation
+     * Start the `requestAnimationFrame` loop that drives smooth progress
+     * updates while playing (self mode only — external mode is redrawn by
+     * controller {@link WaveformPlayer#setProgress} pushes). Cancels any
+     * existing loop first so it's safe to call repeatedly.
      * @private
      */
     startSmoothUpdate() {
@@ -1496,7 +1729,7 @@
       this.updateTimer = requestAnimationFrame(update);
     }
     /**
-     * Stop smooth update animation
+     * Cancel the smooth-update animation frame, if one is scheduled.
      * @private
      */
     stopSmoothUpdate() {
@@ -1506,8 +1739,15 @@
       }
     }
     /**
-     * Update progress
+     * Recompute progress from the owned `<audio>` clock and reflect it
+     * everywhere (self mode only — external mode uses
+     * {@link WaveformPlayer#setProgress}).
+     *
+     * Redraws the canvas when progress moves meaningfully, updates the
+     * current-time display, dispatches `waveformplayer:timeupdate`, fires the
+     * `onTimeUpdate` callback, and refreshes the accessible slider values.
      * @private
+     * @fires WaveformPlayer#waveformplayer:timeupdate
      */
     updateProgress() {
       if (!this.audio || !this.audio.duration) return;
@@ -1519,15 +1759,13 @@
       if (this.currentTimeEl) {
         this.currentTimeEl.textContent = formatTime(this.audio.currentTime);
       }
-      this.container.dispatchEvent(new CustomEvent("waveformplayer:timeupdate", {
-        bubbles: true,
-        detail: {
-          player: this,
-          currentTime: this.audio.currentTime,
-          duration: this.audio.duration,
-          url: this.options.url
-        }
-      }));
+      this._emit("waveformplayer:timeupdate", {
+        player: this,
+        currentTime: this.audio.currentTime,
+        duration: this.audio.duration,
+        progress: this.progress,
+        url: this.options.url
+      });
       if (this.options.onTimeUpdate) {
         this.options.onTimeUpdate(this.audio.currentTime, this.audio.duration, this);
       }
@@ -1537,7 +1775,7 @@
     // UI Updates
     // ============================================
     /**
-     * Update BPM display
+     * Show the detected BPM in the badge, once a value has been detected.
      * @private
      */
     updateBPMDisplay() {
@@ -1547,10 +1785,14 @@
       }
     }
     /**
-     * Update speed UI to reflect current rate
+     * Sync the speed control's label and the menu's active-option highlight to
+     * the audio element's current `playbackRate`. No-op in external mode (no
+     * owned `<audio>`), which also avoids reading `playbackRate` before the
+     * element exists.
      * @private
      */
     updateSpeedUI() {
+      if (!this.audio) return;
       const speedValue = this.container.querySelector(".speed-value");
       if (speedValue) {
         const rate = this.audio.playbackRate;
@@ -1577,19 +1819,19 @@
      * setPlayingState() / setProgress(). Calling preventDefault() on
      * the event lets the controller veto the play (state is unchanged).
      *
-     * @return {Promise|undefined}
+     * When `singlePlay` is enabled, any other currently-playing instance is
+     * paused first.
+     *
+     * @return {Promise|undefined} The promise from `HTMLMediaElement.play()` in
+     *   self mode; `undefined` in external mode.
+     * @fires WaveformPlayer#waveformplayer:request-play
      */
     play() {
       if (this.options.singlePlay && _WaveformPlayer.currentlyPlaying && _WaveformPlayer.currentlyPlaying !== this) {
         _WaveformPlayer.currentlyPlaying.pause();
       }
       if (this.options.audioMode === "external") {
-        const evt = new CustomEvent("waveformplayer:request-play", {
-          bubbles: true,
-          cancelable: true,
-          detail: this._buildTrackDetail()
-        });
-        this.container.dispatchEvent(evt);
+        const evt = this._emit("waveformplayer:request-play", this._buildTrackDetail(), true);
         if (!evt.defaultPrevented) {
           _WaveformPlayer.currentlyPlaying = this;
         }
@@ -1603,17 +1845,15 @@
      *
      * In `audioMode: 'external'`, dispatches `waveformplayer:request-pause`
      * (cancelable) and does NOT touch any audio element. See play().
+     *
+     * @fires WaveformPlayer#waveformplayer:request-pause
      */
     pause() {
       if (_WaveformPlayer.currentlyPlaying === this) {
         _WaveformPlayer.currentlyPlaying = null;
       }
       if (this.options.audioMode === "external") {
-        this.container.dispatchEvent(new CustomEvent("waveformplayer:request-pause", {
-          bubbles: true,
-          cancelable: true,
-          detail: this._buildTrackDetail()
-        }));
+        this._emit("waveformplayer:request-pause", this._buildTrackDetail(), true);
         return;
       }
       this.audio.pause();
@@ -1632,8 +1872,12 @@
         url: this.options.url,
         title: this.options.title,
         subtitle: this.options.subtitle,
-        artist: this.options.artist,
+        // Core has no separate `artist` option; mirror subtitle so the
+        // published event detail is self-consistent for controllers.
+        artist: this.options.artist || this.options.subtitle,
         artwork: this.options.artwork,
+        markers: this.options.markers,
+        waveform: this.options.waveform,
         id: this.id,
         player: this
       };
@@ -1643,31 +1887,26 @@
      * touching audio. Mirrors what onPlay()/onPause() do but skips the
      * audio-element interactions. Safe to call repeatedly — idempotent.
      *
-     * @param {boolean} playing
+     * Only dispatches `waveformplayer:play`/`waveformplayer:pause` (and runs
+     * the matching callback) on an actual transition, starting/stopping the
+     * smooth-update loop accordingly.
+     *
+     * @param {boolean} playing - True to enter the playing state, false to
+     *   enter the paused state.
+     * @fires WaveformPlayer#waveformplayer:play
+     * @fires WaveformPlayer#waveformplayer:pause
      */
     setPlayingState(playing) {
       const wasPlaying = this.isPlaying;
       this.isPlaying = !!playing;
-      if (this.playBtn) {
-        this.playBtn.classList.toggle("playing", this.isPlaying);
-        const playIcon = this.playBtn.querySelector(".waveform-icon-play");
-        const pauseIcon = this.playBtn.querySelector(".waveform-icon-pause");
-        if (playIcon) playIcon.style.display = this.isPlaying ? "none" : "flex";
-        if (pauseIcon) pauseIcon.style.display = this.isPlaying ? "flex" : "none";
-      }
+      this.setPlayButtonState(this.isPlaying);
       if (this.isPlaying && !wasPlaying) {
         this.startSmoothUpdate?.();
-        this.container.dispatchEvent(new CustomEvent("waveformplayer:play", {
-          bubbles: true,
-          detail: { player: this, url: this.options.url }
-        }));
+        this._emit("waveformplayer:play", { player: this, url: this.options.url });
         if (this.options.onPlay) this.options.onPlay(this);
       } else if (!this.isPlaying && wasPlaying) {
         this.stopSmoothUpdate?.();
-        this.container.dispatchEvent(new CustomEvent("waveformplayer:pause", {
-          bubbles: true,
-          detail: { player: this, url: this.options.url }
-        }));
+        this._emit("waveformplayer:pause", { player: this, url: this.options.url });
         if (this.options.onPause) this.options.onPause(this);
       }
     }
@@ -1676,28 +1915,45 @@
      * from an external clock (e.g. WaveformBar's audio element's
      * timeupdate). Drives the canvas redraw + the time displays.
      *
-     * @param {number} currentTime  Current playback position in seconds.
-     * @param {number} duration     Total track duration in seconds.
+     * Redraws the canvas, updates the current/total time displays, stores the
+     * external duration for the accessible slider, dispatches
+     * `waveformplayer:timeupdate`, runs `onTimeUpdate`, and synthesizes a
+     * one-shot `waveformplayer:ended` (with `onEnd`) when progress reaches the
+     * end. No-op for a non-positive duration.
+     *
+     * @param {number} currentTime - Current playback position in seconds.
+     * @param {number} duration - Total track duration in seconds.
+     * @fires WaveformPlayer#waveformplayer:timeupdate
+     * @fires WaveformPlayer#waveformplayer:ended
      */
     setProgress(currentTime, duration) {
       if (!duration || duration <= 0) return;
-      this.progress = Math.max(0, Math.min(1, currentTime / duration));
+      this.progress = clamp(currentTime / duration);
       if (this.currentTimeEl) this.currentTimeEl.textContent = formatTime(currentTime);
-      if (this.totalTimeEl && (!this.totalTimeEl.dataset._extSet || this._extDuration !== duration)) {
+      this._extDuration = duration;
+      if (this.totalTimeEl && (!this.totalTimeEl.dataset._extSet || this.totalTimeEl.dataset._extDur !== String(duration))) {
         this.totalTimeEl.textContent = formatTime(duration);
         this.totalTimeEl.dataset._extSet = "1";
-        this._extDuration = duration;
+        this.totalTimeEl.dataset._extDur = String(duration);
       }
       this.drawWaveform?.();
-      this.container.dispatchEvent(new CustomEvent("waveformplayer:timeupdate", {
-        bubbles: true,
-        detail: { player: this, currentTime, duration, progress: this.progress }
-      }));
-      if (this.options.onTimeUpdate) this.options.onTimeUpdate(this, currentTime, duration);
+      this._emit("waveformplayer:timeupdate", { player: this, currentTime, duration, progress: this.progress, url: this.options.url });
+      if (this.options.onTimeUpdate) this.options.onTimeUpdate(currentTime, duration, this);
+      if (this.progress >= 1) {
+        if (!this._extEnded) {
+          this._extEnded = true;
+          this._emit("waveformplayer:ended", { player: this, url: this.options.url, currentTime: duration, duration });
+          if (this.options.onEnd) this.options.onEnd(this);
+        }
+      } else {
+        this._extEnded = false;
+      }
       this.updateSeekAccessibility();
     }
     /**
-     * Toggle play/pause
+     * Toggle between play and pause based on the current `isPlaying` state.
+     * Works in both audio modes (in external mode it routes through the
+     * request-play/pause events).
      */
     togglePlay() {
       if (this.isPlaying) {
@@ -1707,52 +1963,71 @@
       }
     }
     /**
-     * Seek to time in seconds
-     * @param {number} seconds - Time in seconds
+     * Seek the owned `<audio>` element to an absolute time, clamped to
+     * `[0, duration]`, and refresh progress. Self mode only — a no-op when
+     * there is no audio element or duration. External-mode keyboard/click
+     * seeks go through {@link WaveformPlayer#seekToSeconds} instead.
+     * @param {number} seconds - Target time in seconds.
      */
     seekTo(seconds) {
       if (this.audio && this.audio.duration) {
-        this.audio.currentTime = Math.max(0, Math.min(seconds, this.audio.duration));
+        this.audio.currentTime = clamp(seconds, 0, this.audio.duration);
         this.updateProgress();
       }
     }
     /**
-     * Seek to percentage
-     * @param {number} percent - Percentage (0-1)
+     * Seek the owned `<audio>` element to a fraction of the track, clamped to
+     * `[0, 1]`, and refresh progress. Self mode only — a no-op without an audio
+     * element or duration.
+     * @param {number} percent - Position as a fraction from 0 to 1.
      */
     seekToPercent(percent) {
       if (this.audio && this.audio.duration) {
-        this.audio.currentTime = this.audio.duration * Math.max(0, Math.min(1, percent));
+        this.audio.currentTime = this.audio.duration * clamp(percent);
         this.updateProgress();
       }
     }
     /**
-     * Set volume
-     * @param {number} volume - Volume (0-1)
+     * Set the owned `<audio>` element's volume, clamped to `[0, 1]`. Self mode
+     * only — a no-op in external mode where the controller owns volume.
+     * @param {number} volume - Volume from 0 (silent) to 1 (full).
      */
     setVolume(volume) {
-      if (this.audio) {
-        this.audio.volume = Math.max(0, Math.min(1, volume));
+      const v = Number(volume);
+      if (this.audio && Number.isFinite(v)) {
+        this.audio.volume = clamp(v);
       }
     }
     /**
-     * Set playback rate
-     * @param {number} rate - Playback rate (0.5 to 2)
+     * Set the owned `<audio>` element's playback rate (clamped to 0.5–2),
+     * persist it onto `this.options.playbackRate`, and refresh the speed UI.
+     * Self mode only — a no-op in external mode.
+     * @param {number} rate - Desired playback rate; clamped to the 0.5–2 range.
      */
     setPlaybackRate(rate) {
       if (!this.audio) return;
-      const clampedRate = Math.max(0.5, Math.min(2, rate));
+      const clampedRate = clamp(rate, 0.5, 2);
       this.audio.playbackRate = clampedRate;
       this.options.playbackRate = clampedRate;
       this.updateSpeedUI();
     }
     /**
-     * Destroy player instance
+     * Tear down the player and release all resources.
+     *
+     * Flags destruction (so in-flight handlers bail), dispatches
+     * `waveformplayer:destroy`, stops playback and the animation loop, aborts
+     * every listener registered on the instance signal, disconnects the resize
+     * observer, removes the window-resize handler, drops the instance from the
+     * static map and `currentlyPlaying`, resets/releases the audio element, and
+     * empties the container.
+     * @fires WaveformPlayer#waveformplayer:destroy
      */
     destroy() {
       this.isDestroying = true;
+      this._emit("waveformplayer:destroy", { player: this, url: this.options.url });
       this.pause();
       this.stopSmoothUpdate();
+      this._ac?.abort();
       if (this.resizeObserver) {
         this.resizeObserver.disconnect();
         this.resizeObserver = null;
@@ -1825,7 +2100,7 @@
         const result = await generateWaveform(url, samples);
         return result.peaks;
       } catch (error) {
-        console.error("Failed to generate waveform:", error);
+        console.error("[WaveformPlayer] Failed to generate waveform:", error);
         throw error;
       }
     }
@@ -1878,8 +2153,10 @@
   };
 
   // src/js/index.js
+  WaveformPlayer.utils = { formatTime, extractTitleFromUrl, escapeHtml, isSafeHref };
+  var isBrowser = () => typeof window !== "undefined" && typeof document !== "undefined";
   function autoInit() {
-    if (typeof document === "undefined") return;
+    if (!isBrowser()) return;
     const elements = document.querySelectorAll("[data-waveform-player]");
     elements.forEach((element) => {
       if (element.dataset.waveformInitialized === "true") return;
@@ -1887,11 +2164,11 @@
         new WaveformPlayer(element);
         element.dataset.waveformInitialized = "true";
       } catch (error) {
-        console.error("Failed to initialize WaveformPlayer:", error, element);
+        console.error("[WaveformPlayer] Failed to initialize:", error, element);
       }
     });
   }
-  if (typeof document !== "undefined") {
+  if (isBrowser()) {
     if (document.readyState === "loading") {
       document.addEventListener("DOMContentLoaded", autoInit);
     } else {
@@ -1899,7 +2176,7 @@
     }
   }
   WaveformPlayer.init = autoInit;
-  if (typeof window !== "undefined") {
+  if (isBrowser()) {
     window.WaveformPlayer = WaveformPlayer;
   }
   var index_default = WaveformPlayer;