@arraypress/waveform-player 1.16.1 → 1.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -25,6 +25,14 @@ __export(index_exports, {
25
25
  module.exports = __toCommonJS(index_exports);
26
26
 
27
27
  // src/js/utils.js
28
+ var DEFAULT_SAMPLES = 1800;
29
+ function maxOf(values) {
30
+ let max = -Infinity;
31
+ for (let i = 0; i < values.length; i++) {
32
+ if (values[i] > max) max = values[i];
33
+ }
34
+ return max;
35
+ }
28
36
  function escapeHtml(str) {
29
37
  return String(str == null ? "" : str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
30
38
  }
@@ -81,6 +89,7 @@ function parseDataAttributes(element) {
81
89
  if (element.dataset.audioMode) options.audioMode = element.dataset.audioMode;
82
90
  if (element.dataset.style) options.waveformStyle = element.dataset.style;
83
91
  if (element.dataset.waveformStyle) options.waveformStyle = element.dataset.waveformStyle;
92
+ if (element.dataset.waveformGradient) options.waveformGradient = element.dataset.waveformGradient;
84
93
  setNum("barWidth");
85
94
  setNum("barSpacing");
86
95
  setNum("barRadius");
@@ -94,12 +103,6 @@ function parseDataAttributes(element) {
94
103
  if (element.dataset.colorPreset) options.colorPreset = element.dataset.colorPreset;
95
104
  if (element.dataset.waveformColor) options.waveformColor = parseColorValue(element.dataset.waveformColor);
96
105
  if (element.dataset.progressColor) options.progressColor = parseColorValue(element.dataset.progressColor);
97
- if (element.dataset.buttonColor) options.buttonColor = element.dataset.buttonColor;
98
- if (element.dataset.buttonHoverColor) options.buttonHoverColor = element.dataset.buttonHoverColor;
99
- if (element.dataset.textColor) options.textColor = element.dataset.textColor;
100
- if (element.dataset.textSecondaryColor) options.textSecondaryColor = element.dataset.textSecondaryColor;
101
- if (element.dataset.backgroundColor) options.backgroundColor = element.dataset.backgroundColor;
102
- if (element.dataset.borderColor) options.borderColor = element.dataset.borderColor;
103
106
  if (element.dataset.color) options.waveformColor = element.dataset.color;
104
107
  if (element.dataset.theme) options.colorPreset = element.dataset.theme;
105
108
  setBool("autoplay");
@@ -107,12 +110,13 @@ function parseDataAttributes(element) {
107
110
  setBool("showInfo");
108
111
  setBool("showTime");
109
112
  setBool("showHoverTime");
113
+ setBool("seekHandle");
110
114
  setBool("showBPM", "showBpm");
111
115
  setNum("bpm");
112
116
  setBool("singlePlay");
113
117
  setBool("playOnSeek");
114
118
  if (element.dataset.title) options.title = element.dataset.title;
115
- if (element.dataset.subtitle) options.subtitle = element.dataset.subtitle;
119
+ if (element.dataset.artist) options.artist = element.dataset.artist;
116
120
  if (element.dataset.album) options.album = element.dataset.album;
117
121
  if (element.dataset.artwork) options.artwork = element.dataset.artwork;
118
122
  if (element.dataset.waveform) options.waveform = element.dataset.waveform;
@@ -227,12 +231,20 @@ function resampleData(data, targetLength) {
227
231
  }
228
232
 
229
233
  // src/js/drawing.js
230
- function makeFill(ctx, value, height) {
234
+ function makeFill(ctx, value, canvas, options) {
231
235
  if (!Array.isArray(value)) return value;
232
- if (value.length === 1) return value[0];
233
- const grad = ctx.createLinearGradient(0, 0, 0, height);
234
- value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
235
- return grad;
236
+ if (value.length < 2) return value[0];
237
+ const w = canvas.width;
238
+ const h = canvas.height;
239
+ const dir = options && options.waveformGradient;
240
+ const [x0, y0, x1, y1] = dir === "horizontal" ? [0, 0, w, 0] : dir === "diagonal" ? [0, 0, w, h] : [0, 0, 0, h];
241
+ try {
242
+ const grad = ctx.createLinearGradient(x0, y0, x1, y1);
243
+ value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
244
+ return grad;
245
+ } catch (e) {
246
+ return value[0];
247
+ }
236
248
  }
237
249
  function fillBar(ctx, x, y, w, h, radii) {
238
250
  const any = Array.isArray(radii) ? radii.some((r) => r > 0) : radii > 0;
@@ -272,8 +284,8 @@ function drawBars(ctx, canvas, peaks, progress, options) {
272
284
  const height = canvas.height;
273
285
  const progressWidth = progress * canvas.width;
274
286
  const radii = barRadii(options, dpr);
275
- const baseFill = makeFill(ctx, options.color, height);
276
- const progFill = makeFill(ctx, options.progressColor, height);
287
+ const baseFill = makeFill(ctx, options.color, canvas, options);
288
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
277
289
  ctx.clearRect(0, 0, canvas.width, canvas.height);
278
290
  ctx.fillStyle = baseFill;
279
291
  for (let i = 0; i < resampledPeaks.length; i++) {
@@ -309,8 +321,8 @@ function drawMirror(ctx, canvas, peaks, progress, options) {
309
321
  const r = barRadiusPx(options, dpr);
310
322
  const topRadii = [r, r, 0, 0];
311
323
  const botRadii = [0, 0, r, r];
312
- const baseFill = makeFill(ctx, options.color, height);
313
- const progFill = makeFill(ctx, options.progressColor, height);
324
+ const baseFill = makeFill(ctx, options.color, canvas, options);
325
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
314
326
  ctx.clearRect(0, 0, canvas.width, canvas.height);
315
327
  ctx.fillStyle = baseFill;
316
328
  for (let i = 0; i < resampledPeaks.length; i++) {
@@ -341,11 +353,13 @@ function drawLine(ctx, canvas, peaks, progress, options) {
341
353
  const amplitude = height * 0.35;
342
354
  ctx.clearRect(0, 0, width, height);
343
355
  const drawCurve = (color, lineWidth, endProgress = 1, addGlow = false) => {
356
+ const stroke = makeFill(ctx, color, canvas, options);
357
+ const solid = Array.isArray(color) ? color[color.length - 1] : color;
344
358
  if (addGlow) {
345
359
  ctx.shadowBlur = 12;
346
- ctx.shadowColor = color;
360
+ ctx.shadowColor = solid;
347
361
  }
348
- ctx.strokeStyle = color;
362
+ ctx.strokeStyle = stroke;
349
363
  ctx.lineWidth = lineWidth;
350
364
  ctx.lineCap = "round";
351
365
  ctx.lineJoin = "round";
@@ -401,8 +415,8 @@ function drawBlocks(ctx, canvas, peaks, progress, options) {
401
415
  const blockGap = 2 * dpr;
402
416
  const progressWidth = progress * canvas.width;
403
417
  const centerY = height / 2;
404
- const baseFill = makeFill(ctx, options.color, height);
405
- const progFill = makeFill(ctx, options.progressColor, height);
418
+ const baseFill = makeFill(ctx, options.color, canvas, options);
419
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
406
420
  ctx.clearRect(0, 0, canvas.width, canvas.height);
407
421
  for (let i = 0; i < resampledPeaks.length; i++) {
408
422
  const x = i * (barWidth + barSpacing);
@@ -429,8 +443,8 @@ function drawDots(ctx, canvas, peaks, progress, options) {
429
443
  const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
430
444
  const progressWidth = progress * canvas.width;
431
445
  const centerY = height / 2;
432
- const baseFill = makeFill(ctx, options.color, height);
433
- const progFill = makeFill(ctx, options.progressColor, height);
446
+ const baseFill = makeFill(ctx, options.color, canvas, options);
447
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
434
448
  ctx.clearRect(0, 0, canvas.width, canvas.height);
435
449
  for (let i = 0; i < resampledPeaks.length; i++) {
436
450
  const x = i * (barWidth + barSpacing) + barWidth / 2;
@@ -451,33 +465,19 @@ function drawSeekbar(ctx, canvas, peaks, progress, options) {
451
465
  const centerY = height / 2;
452
466
  const barHeight = 4;
453
467
  const borderRadius = barHeight / 2;
468
+ const active = !!options.seekActive;
454
469
  ctx.clearRect(0, 0, width, height);
455
- ctx.fillStyle = options.color || "rgba(255, 255, 255, 0.2)";
470
+ ctx.fillStyle = makeFill(ctx, options.color, canvas, options) || "rgba(255, 255, 255, 0.2)";
456
471
  capsulePath(ctx, borderRadius, width, centerY, barHeight);
457
472
  ctx.fill();
458
473
  if (progress > 0) {
459
474
  const progressWidth = Math.max(borderRadius * 2, progress * width);
460
- ctx.shadowBlur = 8;
461
- ctx.shadowColor = options.progressColor;
462
- ctx.fillStyle = options.progressColor || "rgba(255, 255, 255, 0.9)";
475
+ ctx.save();
476
+ ctx.globalAlpha = options.seekHandle && !active ? 0.7 : 1;
477
+ ctx.fillStyle = makeFill(ctx, options.progressColor, canvas, options) || "rgba(255, 255, 255, 0.9)";
463
478
  capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
464
479
  ctx.fill();
465
- ctx.shadowBlur = 0;
466
- const handleRadius = 8;
467
- const handleX = progressWidth;
468
- ctx.shadowBlur = 4;
469
- ctx.shadowColor = "rgba(0, 0, 0, 0.3)";
470
- ctx.shadowOffsetY = 2;
471
- ctx.fillStyle = "#ffffff";
472
- ctx.beginPath();
473
- ctx.arc(handleX, centerY, handleRadius, 0, Math.PI * 2);
474
- ctx.fill();
475
- ctx.shadowBlur = 0;
476
- ctx.shadowOffsetY = 0;
477
- ctx.fillStyle = options.progressColor || "rgba(255, 255, 255, 0.9)";
478
- ctx.beginPath();
479
- ctx.arc(handleX, centerY, handleRadius * 0.4, 0, Math.PI * 2);
480
- ctx.fill();
480
+ ctx.restore();
481
481
  }
482
482
  }
483
483
  var DRAWING_STYLES = {
@@ -566,7 +566,7 @@ function detectOnsets(channelData, sampleRate) {
566
566
  }
567
567
 
568
568
  // src/js/audio.js
569
- function extractPeaks(buffer, samples = 200) {
569
+ function extractPeaks(buffer, samples = DEFAULT_SAMPLES) {
570
570
  const sampleSize = buffer.length / samples;
571
571
  const channels = buffer.numberOfChannels;
572
572
  const peaks = [];
@@ -588,10 +588,10 @@ function extractPeaks(buffer, samples = 200) {
588
588
  }
589
589
  }
590
590
  }
591
- const maxPeak = Math.max(...peaks);
591
+ const maxPeak = maxOf(peaks);
592
592
  return maxPeak > 0 ? peaks.map((peak) => peak / maxPeak) : peaks;
593
593
  }
594
- async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
594
+ async function generateWaveform(url, samples = DEFAULT_SAMPLES, shouldDetectBPM = false) {
595
595
  let audioContext;
596
596
  try {
597
597
  const AudioCtx = window.AudioContext || /** @type {any} */
@@ -611,7 +611,7 @@ async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
611
611
  if (audioContext) audioContext.close();
612
612
  }
613
613
  }
614
- function generatePlaceholderWaveform(samples = 200) {
614
+ function generatePlaceholderWaveform(samples = DEFAULT_SAMPLES) {
615
615
  const data = [];
616
616
  for (let i = 0; i < samples; i++) {
617
617
  const base = Math.random() * 0.5 + 0.3;
@@ -621,7 +621,7 @@ function generatePlaceholderWaveform(samples = 200) {
621
621
  return data;
622
622
  }
623
623
  function normalizePeaks(peaks, targetMax = 0.95) {
624
- const maxPeak = Math.max(...peaks);
624
+ const maxPeak = maxOf(peaks);
625
625
  if (maxPeak === 0 || maxPeak > targetMax) return peaks;
626
626
  const scaleFactor = targetMax / maxPeak;
627
627
  return peaks.map((peak) => peak * scaleFactor);
@@ -658,23 +658,11 @@ function detectColorScheme() {
658
658
  var COLOR_PRESETS = {
659
659
  dark: {
660
660
  waveformColor: "rgba(255, 255, 255, 0.3)",
661
- progressColor: "rgba(255, 255, 255, 0.9)",
662
- buttonColor: "rgba(255, 255, 255, 0.9)",
663
- buttonHoverColor: "rgba(255, 255, 255, 1)",
664
- textColor: "#ffffff",
665
- textSecondaryColor: "rgba(255, 255, 255, 0.6)",
666
- backgroundColor: "rgba(255, 255, 255, 0.03)",
667
- borderColor: "rgba(255, 255, 255, 0.1)"
661
+ progressColor: "rgba(255, 255, 255, 0.9)"
668
662
  },
669
663
  light: {
670
664
  waveformColor: "rgba(0, 0, 0, 0.2)",
671
- progressColor: "rgba(0, 0, 0, 0.8)",
672
- buttonColor: "rgba(0, 0, 0, 0.8)",
673
- buttonHoverColor: "rgba(0, 0, 0, 0.9)",
674
- textColor: "#333333",
675
- textSecondaryColor: "rgba(0, 0, 0, 0.6)",
676
- backgroundColor: "rgba(0, 0, 0, 0.02)",
677
- borderColor: "rgba(0, 0, 0, 0.1)"
665
+ progressColor: "rgba(0, 0, 0, 0.8)"
678
666
  }
679
667
  };
680
668
  function getColorPreset(presetName) {
@@ -693,7 +681,7 @@ var DEFAULT_OPTIONS = {
693
681
  // bars, so this is fidelity headroom, not the visible bar count. 1800 (the
694
682
  // SoundCloud/WaveformGen figure) keeps wide / high-DPI waveforms crisp; the
695
683
  // every-frame scan means a higher value costs no extra extraction time.
696
- samples: 1800,
684
+ samples: DEFAULT_SAMPLES,
697
685
  preload: "metadata",
698
686
  // Audio mode — 'self' = player owns the <audio> element (default, current
699
687
  // behavior). 'external' = player is a visualization-only surface; no audio
@@ -727,23 +715,29 @@ var DEFAULT_OPTIONS = {
727
715
  barSpacing: 0,
728
716
  // Rounded bar caps (px). 0 = square; 1 = soft caps (default). Applies to bars/mirror.
729
717
  barRadius: 1,
718
+ // Gradient axis when waveformColor/progressColor is an array of stops:
719
+ // 'vertical' (top->bottom canvas gradient), 'horizontal' (hue sweep across the
720
+ // waveform) or 'diagonal'. Ignored for single colours.
721
+ waveformGradient: "vertical",
730
722
  // Color preset: null = auto-detect, 'dark' = force dark, 'light' = force light
731
723
  colorPreset: null,
732
- // Individual color overrides (null means use preset)
724
+ // Canvas colours (null = inherit the resolved preset; arrays = gradient
725
+ // stops, see waveformGradient). The DOM chrome (button, title, meta) is
726
+ // themed via CSS variables (--wfp-button-color / --wfp-text-color /
727
+ // --wfp-text-secondary-color), not JS options.
733
728
  waveformColor: null,
734
729
  progressColor: null,
735
- buttonColor: null,
736
- buttonHoverColor: null,
737
- textColor: null,
738
- textSecondaryColor: null,
739
- backgroundColor: null,
740
- borderColor: null,
741
730
  // Features
742
731
  autoplay: false,
743
732
  showControls: true,
744
733
  showInfo: true,
745
734
  showTime: true,
746
735
  showHoverTime: false,
736
+ // Show a draggable circle handle + hover brightness-lift on the SEEKBAR
737
+ // style only (it's meaningless on a waveform, where the fill-edge is the
738
+ // playhead). Off by default; the bar turns it on. Drag-to-scrub works
739
+ // regardless of this.
740
+ seekHandle: false,
747
741
  showBPM: false,
748
742
  // Known BPM to display in the badge (with showBPM). Wins over auto-detection
749
743
  // — set it when peaks are pre-generated so the tempo still shows. null = auto.
@@ -762,7 +756,7 @@ var DEFAULT_OPTIONS = {
762
756
  seekLabel: null,
763
757
  // Content
764
758
  title: null,
765
- subtitle: null,
759
+ artist: null,
766
760
  artwork: null,
767
761
  album: "",
768
762
  // Message shown in the error state when audio fails to load.
@@ -793,6 +787,7 @@ var ARTWORK_FALLBACK = "data:image/svg+xml," + encodeURIComponent(
793
787
  );
794
788
  var SEEK_STEP_SECONDS = 5;
795
789
  var SEEK_PAGE_SECONDS = 10;
790
+ var INTERACTIVE_ELEMENTS = 'button, a[href], input, [role="slider"]';
796
791
  var WaveformPlayer = class _WaveformPlayer {
797
792
  /** @type {Map<string, WaveformPlayer>} */
798
793
  static instances = /* @__PURE__ */ new Map();
@@ -828,6 +823,7 @@ var WaveformPlayer = class _WaveformPlayer {
828
823
  const preset = getColorPreset(this.options.colorPreset);
829
824
  this._autoTheme = this.options.colorPreset == null || !COLOR_PRESETS[this.options.colorPreset];
830
825
  this._presetKeys = [];
826
+ this._scheme = this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset] ? this.options.colorPreset : detectColorScheme();
831
827
  for (const [key, value] of Object.entries(preset)) {
832
828
  if (this.options[key] === null || this.options[key] === void 0) {
833
829
  this.options[key] = value;
@@ -934,7 +930,7 @@ var WaveformPlayer = class _WaveformPlayer {
934
930
  *
935
931
  * Clears the container, resolves button alignment (`auto` → `bottom` for
936
932
  * the `bars` style, `center` otherwise), and conditionally renders the play
937
- * button, info row (artwork/title/subtitle), BPM badge, playback-speed
933
+ * button, info row (artwork/title/artist), BPM badge, playback-speed
938
934
  * menu, and time display based on the relevant `show*` options. Caches the
939
935
  * canvas, controls, and text elements onto `this`, then sizes the canvas.
940
936
  * @private
@@ -955,12 +951,9 @@ var WaveformPlayer = class _WaveformPlayer {
955
951
  if (isPreview) {
956
952
  this.container.classList.add("waveform-layout-preview");
957
953
  }
954
+ this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
958
955
  const buttonHTML = this.options.showControls ? `
959
- <button class="waveform-btn${this.options.buttonStyle === "minimal" ? " waveform-btn-minimal" : ""}" aria-label="Play/Pause" style="
960
- border-color: ${this.options.buttonColor};
961
- color: ${this.options.buttonColor};
962
- ${this.options.buttonSize != null ? `--wfp-btn-size: ${typeof this.options.buttonSize === "number" ? `${this.options.buttonSize}px` : this.options.buttonSize};` : ""}
963
- ">
956
+ <button class="waveform-btn${this.options.buttonStyle === "minimal" ? " waveform-btn-minimal" : ""}" aria-label="Play/Pause"${this.options.buttonSize != null ? ` style="--wfp-btn-size: ${typeof this.options.buttonSize === "number" ? `${this.options.buttonSize}px` : this.options.buttonSize};"` : ""}>
964
957
  <span class="waveform-icon-play">${this.options.playIcon}</span>
965
958
  <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
966
959
  </button>
@@ -977,18 +970,18 @@ var WaveformPlayer = class _WaveformPlayer {
977
970
  ">
978
971
  ` : ""}
979
972
  <div class="waveform-text">
980
- <span class="waveform-title" style="color: ${this.options.textColor};"></span>
981
- ${this.options.subtitle ? `<span class="waveform-subtitle" style="color: ${this.options.textSecondaryColor};">${this.options.subtitle}</span>` : ""}
973
+ <span class="waveform-title"></span>
974
+ ${this.options.artist ? `<span class="waveform-artist">${this.options.artist}</span>` : ""}
982
975
  </div>
983
976
  <div class="waveform-meta" style="display: flex; align-items: center; gap: 1rem;">
984
977
  ${this.options.showBPM ? `
985
- <span class="waveform-bpm" style="color: ${this.options.textSecondaryColor}; display: none;">
978
+ <span class="waveform-bpm" style="display: none;">
986
979
  <span class="bpm-value">--</span> BPM
987
980
  </span>
988
981
  ` : ""}
989
982
  ${this.options.showPlaybackSpeed ? `
990
983
  <div class="waveform-speed">
991
- <button class="speed-btn" aria-label="Playback speed">
984
+ <button class="speed-btn" aria-label="Playback speed" aria-haspopup="true" aria-expanded="false">
992
985
  <span class="speed-value">1x</span>
993
986
  </button>
994
987
  <div class="speed-menu" style="display: none;">
@@ -999,7 +992,7 @@ var WaveformPlayer = class _WaveformPlayer {
999
992
  </div>
1000
993
  ` : ""}
1001
994
  ${this.options.showTime ? `
1002
- <span class="waveform-time" style="color: ${this.options.textSecondaryColor};">
995
+ <span class="waveform-time">
1003
996
  <span class="time-current">0:00</span> / <span class="time-total">0:00</span>
1004
997
  </span>
1005
998
  ` : ""}
@@ -1030,7 +1023,7 @@ var WaveformPlayer = class _WaveformPlayer {
1030
1023
  this.canvas = this.container.querySelector("canvas");
1031
1024
  this.ctx = this.canvas.getContext("2d");
1032
1025
  this.titleEl = this.container.querySelector(".waveform-title");
1033
- this.subtitleEl = this.container.querySelector(".waveform-subtitle");
1026
+ this.artistEl = this.container.querySelector(".waveform-artist");
1034
1027
  this.artworkEl = this.container.querySelector(".waveform-artwork");
1035
1028
  if (this.artworkEl) {
1036
1029
  this.artworkEl.addEventListener("error", () => {
@@ -1087,8 +1080,9 @@ var WaveformPlayer = class _WaveformPlayer {
1087
1080
  }
1088
1081
  /**
1089
1082
  * Wire up the playback-speed menu: toggle it open on the speed button,
1090
- * close it on any outside click, and apply the chosen rate when a
1091
- * `.speed-option` is clicked. All listeners are registered against the
1083
+ * close it on outside click or Escape (keeping `aria-expanded` on the
1084
+ * trigger in sync), and apply the chosen rate when a `.speed-option` is
1085
+ * clicked, returning focus to the trigger. All listeners are registered against the
1092
1086
  * instance `AbortController` signal so {@link WaveformPlayer#destroy} tears
1093
1087
  * them down. No-op if the speed elements are absent.
1094
1088
  * @private
@@ -1097,19 +1091,27 @@ var WaveformPlayer = class _WaveformPlayer {
1097
1091
  const speedBtn = this.container.querySelector(".speed-btn");
1098
1092
  const speedMenu = this.container.querySelector(".speed-menu");
1099
1093
  if (!speedBtn || !speedMenu) return;
1094
+ const setSpeedMenu = (open) => {
1095
+ speedMenu.style.display = open ? "block" : "none";
1096
+ speedBtn.setAttribute("aria-expanded", open ? "true" : "false");
1097
+ };
1100
1098
  speedBtn.addEventListener("click", (e) => {
1101
1099
  e.stopPropagation();
1102
- speedMenu.style.display = speedMenu.style.display === "none" ? "block" : "none";
1103
- }, { signal: this._ac.signal });
1104
- document.addEventListener("click", () => {
1105
- speedMenu.style.display = "none";
1100
+ setSpeedMenu(speedMenu.style.display === "none");
1106
1101
  }, { signal: this._ac.signal });
1102
+ document.addEventListener("click", () => setSpeedMenu(false), { signal: this._ac.signal });
1107
1103
  speedMenu.addEventListener("click", (e) => {
1108
1104
  e.stopPropagation();
1109
1105
  if (e.target.classList.contains("speed-option")) {
1110
- const rate = parseFloat(e.target.dataset.rate);
1111
- this.setPlaybackRate(rate);
1112
- speedMenu.style.display = "none";
1106
+ this.setPlaybackRate(parseFloat(e.target.dataset.rate));
1107
+ setSpeedMenu(false);
1108
+ speedBtn.focus();
1109
+ }
1110
+ }, { signal: this._ac.signal });
1111
+ speedBtn.closest(".waveform-speed")?.addEventListener("keydown", (e) => {
1112
+ if (e.key === "Escape" && speedMenu.style.display !== "none") {
1113
+ setSpeedMenu(false);
1114
+ speedBtn.focus();
1113
1115
  }
1114
1116
  }, { signal: this._ac.signal });
1115
1117
  this.updateSpeedUI();
@@ -1127,7 +1129,8 @@ var WaveformPlayer = class _WaveformPlayer {
1127
1129
  */
1128
1130
  initKeyboardControls() {
1129
1131
  this.container.setAttribute("tabindex", "-1");
1130
- this.container.addEventListener("click", () => {
1132
+ this.container.addEventListener("click", (e) => {
1133
+ if (e.target.closest(INTERACTIVE_ELEMENTS)) return;
1131
1134
  _WaveformPlayer.getAllInstances().forEach((player) => {
1132
1135
  if (player !== this) {
1133
1136
  player.container.setAttribute("tabindex", "-1");
@@ -1295,7 +1298,7 @@ var WaveformPlayer = class _WaveformPlayer {
1295
1298
  if (!this.audio) return;
1296
1299
  navigator.mediaSession.metadata = new MediaMetadata({
1297
1300
  title: this.options.title || "Unknown Track",
1298
- artist: this.options.subtitle || "",
1301
+ artist: this.options.artist || "",
1299
1302
  album: this.options.album || "",
1300
1303
  artwork: this.options.artwork ? [
1301
1304
  { src: this.options.artwork, sizes: "512x512", type: "image/jpeg" }
@@ -1339,7 +1342,56 @@ var WaveformPlayer = class _WaveformPlayer {
1339
1342
  this.audio.addEventListener("error", (e) => this.onError(e));
1340
1343
  }
1341
1344
  this.canvas.addEventListener("click", (e) => this.handleCanvasClick(e));
1345
+ this._dragging = false;
1346
+ this._seekHover = false;
1347
+ this._handleNear = false;
1348
+ this.canvas.addEventListener("pointerenter", () => {
1349
+ this._seekHover = true;
1350
+ this.drawWaveform();
1351
+ this._updateSeekHandle();
1352
+ });
1353
+ this.canvas.addEventListener("pointerleave", () => {
1354
+ this._seekHover = false;
1355
+ this._handleNear = false;
1356
+ if (!this._dragging) this._hideHoverTip();
1357
+ this.drawWaveform();
1358
+ this._updateSeekHandle();
1359
+ });
1360
+ this.canvas.addEventListener("pointerdown", (e) => {
1361
+ if (e.pointerType === "mouse" && e.button !== 0) return;
1362
+ this._dragging = true;
1363
+ try {
1364
+ this.canvas.setPointerCapture(e.pointerId);
1365
+ } catch (err) {
1366
+ }
1367
+ this._scrubTo(e.clientX);
1368
+ });
1369
+ this.canvas.addEventListener("pointermove", (e) => {
1370
+ if (this._dragging) {
1371
+ this._scrubTo(e.clientX);
1372
+ return;
1373
+ }
1374
+ const rect = this.canvas.getBoundingClientRect();
1375
+ if (rect.width) {
1376
+ this._handleNear = Math.abs(e.clientX - rect.left - this.progress * rect.width) <= 10;
1377
+ this._updateSeekHandle();
1378
+ }
1379
+ });
1380
+ const endDrag = (e) => {
1381
+ if (!this._dragging) return;
1382
+ this._dragging = false;
1383
+ try {
1384
+ this.canvas.releasePointerCapture(e.pointerId);
1385
+ } catch (err) {
1386
+ }
1387
+ this._seekFromPointer(e.clientX);
1388
+ if (!this._seekHover && !this.options.showHoverTime) this._hideHoverTip();
1389
+ this._updateSeekHandle();
1390
+ };
1391
+ this.canvas.addEventListener("pointerup", endDrag);
1392
+ this.canvas.addEventListener("pointercancel", endDrag);
1342
1393
  this.setupHoverTime();
1394
+ this.setupSeekHandle();
1343
1395
  this.resizeHandler = debounce(() => this.resizeCanvas(), 100);
1344
1396
  window.addEventListener("resize", this.resizeHandler);
1345
1397
  }
@@ -1436,19 +1488,19 @@ var WaveformPlayer = class _WaveformPlayer {
1436
1488
  *
1437
1489
  * Pauses any current playback, fully resets the audio element (self mode),
1438
1490
  * clears error/marker/progress state, merges the new metadata into
1439
- * `this.options`, updates the subtitle/artwork DOM, then calls
1491
+ * `this.options`, updates the artist/artwork DOM, then calls
1440
1492
  * {@link WaveformPlayer#load}. Auto-plays the new track unless
1441
1493
  * `options.autoplay === false`.
1442
1494
  * @param {string} url - Audio URL.
1443
1495
  * @param {string|null} [title=null] - Track title; keeps the existing
1444
1496
  * title when null.
1445
- * @param {string|null} [subtitle=null] - Track subtitle; pass `''` to hide
1446
- * the subtitle row, or null to keep the existing one.
1497
+ * @param {string|null} [artist=null] - Track artist; pass `''` to hide
1498
+ * the artist row, or null to keep the existing one.
1447
1499
  * @param {Object} [options={}] - Additional options to merge (e.g.
1448
1500
  * `preload`, `artwork`, `markers`, `autoplay`).
1449
1501
  * @returns {Promise<void>}
1450
1502
  */
1451
- async loadTrack(url, title = null, subtitle = null, options = {}) {
1503
+ async loadTrack(url, title = null, artist = null, options = {}) {
1452
1504
  if (this.isPlaying) {
1453
1505
  this.pause();
1454
1506
  }
@@ -1471,18 +1523,18 @@ var WaveformPlayer = class _WaveformPlayer {
1471
1523
  this.options = mergeOptions(this.options, {
1472
1524
  url,
1473
1525
  title: title || this.options.title,
1474
- subtitle: subtitle || this.options.subtitle,
1526
+ artist: artist || this.options.artist,
1475
1527
  ...options
1476
1528
  });
1477
1529
  if (options.preload && this.audio) {
1478
1530
  this.audio.preload = options.preload;
1479
1531
  }
1480
- if (this.subtitleEl) {
1481
- if (subtitle) {
1482
- this.subtitleEl.textContent = subtitle;
1483
- this.subtitleEl.style.display = "";
1484
- } else if (subtitle === "") {
1485
- this.subtitleEl.style.display = "none";
1532
+ if (this.artistEl) {
1533
+ if (artist) {
1534
+ this.artistEl.textContent = artist;
1535
+ this.artistEl.style.display = "";
1536
+ } else if (artist === "") {
1537
+ this.artistEl.style.display = "none";
1486
1538
  }
1487
1539
  }
1488
1540
  if (options.artwork && this.artworkEl) {
@@ -1548,7 +1600,8 @@ var WaveformPlayer = class _WaveformPlayer {
1548
1600
  ...this.options,
1549
1601
  waveformStyle: this.options.waveformStyle || "bars",
1550
1602
  color: this.options.waveformColor,
1551
- progressColor: this.options.progressColor
1603
+ progressColor: this.options.progressColor,
1604
+ seekActive: this._seekHover || this._dragging
1552
1605
  });
1553
1606
  }
1554
1607
  /**
@@ -1664,35 +1717,97 @@ var WaveformPlayer = class _WaveformPlayer {
1664
1717
  }
1665
1718
  }
1666
1719
  /**
1667
- * Build a tooltip that follows the pointer over the waveform and shows the
1668
- * time at that position. Enabled by the `showHoverTime` option; works in both
1720
+ * Build the time tooltip that follows the pointer over the waveform. The
1721
+ * element is always created so **drag-scrub** can show the time you're
1722
+ * dragging to; the *hover* reveal is gated on `showHoverTime`. Works in both
1669
1723
  * self and external modes (it only needs {@link WaveformPlayer#getSeekDuration}).
1670
- * Uses the same pointer-X → percentage math as seeking.
1671
1724
  * @private
1672
1725
  */
1673
1726
  setupHoverTime() {
1674
- if (!this.options.showHoverTime || !this.seekEl) return;
1727
+ if (!this.seekEl) return;
1675
1728
  const tip = document.createElement("div");
1676
1729
  tip.className = "waveform-hover-time";
1677
1730
  tip.setAttribute("aria-hidden", "true");
1678
1731
  this.seekEl.appendChild(tip);
1679
1732
  this.hoverTimeEl = tip;
1733
+ if (!this.options.showHoverTime) return;
1680
1734
  this.seekEl.addEventListener("pointermove", (e) => {
1681
- const dur = this.getSeekDuration();
1682
- if (!dur) {
1683
- tip.style.opacity = "0";
1684
- return;
1685
- }
1686
- const rect = this.canvas.getBoundingClientRect();
1687
- const pct = clamp((e.clientX - rect.left) / rect.width);
1688
- tip.textContent = formatTime(pct * dur);
1689
- tip.style.left = pct * 100 + "%";
1690
- tip.style.opacity = "1";
1735
+ if (!this._dragging) this._updateHoverTip(e.clientX);
1691
1736
  });
1692
1737
  this.seekEl.addEventListener("pointerleave", () => {
1693
- tip.style.opacity = "0";
1738
+ if (!this._dragging) this._hideHoverTip();
1694
1739
  });
1695
1740
  }
1741
+ /**
1742
+ * Position + fill the hover-time tooltip for a given client-X. Shared by
1743
+ * hover and drag-scrub. No-op when the tooltip isn't enabled
1744
+ * (`showHoverTime` off).
1745
+ * @param {number} clientX - Pointer client-X coordinate.
1746
+ * @private
1747
+ */
1748
+ _updateHoverTip(clientX) {
1749
+ const tip = this.hoverTimeEl;
1750
+ if (!tip) return;
1751
+ const dur = this.getSeekDuration();
1752
+ if (!dur) {
1753
+ tip.style.opacity = "0";
1754
+ return;
1755
+ }
1756
+ const rect = this.canvas.getBoundingClientRect();
1757
+ const pct = clamp((clientX - rect.left) / rect.width);
1758
+ tip.textContent = formatTime(pct * dur);
1759
+ tip.style.left = pct * 100 + "%";
1760
+ tip.style.opacity = "1";
1761
+ }
1762
+ /** Hide the hover-time tooltip. @private */
1763
+ _hideHoverTip() {
1764
+ if (this.hoverTimeEl) this.hoverTimeEl.style.opacity = "0";
1765
+ }
1766
+ /**
1767
+ * Visually preview a seek during a drag — moves the playhead + handle +
1768
+ * tooltip to the cursor WITHOUT touching the audio (playback continues; the
1769
+ * real seek is committed on release).
1770
+ * @param {number} clientX - Pointer client-X coordinate.
1771
+ * @private
1772
+ */
1773
+ _scrubTo(clientX) {
1774
+ const rect = this.canvas.getBoundingClientRect();
1775
+ if (!rect.width) return;
1776
+ this.progress = clamp((clientX - rect.left) / rect.width);
1777
+ this.drawWaveform();
1778
+ this._updateSeekHandle();
1779
+ this._updateHoverTip(clientX);
1780
+ const dur = this.getSeekDuration();
1781
+ if (dur && this.currentTimeEl) {
1782
+ this.currentTimeEl.textContent = formatTime(this.progress * dur);
1783
+ }
1784
+ }
1785
+ /**
1786
+ * Create the draggable seek handle — a DOM circle over the playhead, shown
1787
+ * only on hover / drag (Spotify-style). Pointer-events are off so it never
1788
+ * blocks the canvas scrub; size + visibility are CSS.
1789
+ * @private
1790
+ */
1791
+ setupSeekHandle() {
1792
+ if (!this.options.seekHandle || this.options.waveformStyle !== "seekbar" || !this.seekEl) return;
1793
+ const h = document.createElement("div");
1794
+ h.className = "waveform-seek-handle";
1795
+ h.setAttribute("aria-hidden", "true");
1796
+ this.seekEl.appendChild(h);
1797
+ this.seekHandleEl = h;
1798
+ }
1799
+ /**
1800
+ * Position the seek handle at the current progress and toggle its
1801
+ * visibility (hover / drag) + expanded (drag / direct-hover) classes.
1802
+ * @private
1803
+ */
1804
+ _updateSeekHandle() {
1805
+ const h = this.seekHandleEl;
1806
+ if (!h) return;
1807
+ h.style.left = this.progress * 100 + "%";
1808
+ h.classList.toggle("is-visible", this._seekHover || this._dragging);
1809
+ h.classList.toggle("is-active", this._dragging || this._handleNear);
1810
+ }
1696
1811
  // ============================================
1697
1812
  // Event Handlers
1698
1813
  // ============================================
@@ -1709,9 +1824,23 @@ var WaveformPlayer = class _WaveformPlayer {
1709
1824
  * @fires WaveformPlayer#waveformplayer:request-seek
1710
1825
  */
1711
1826
  handleCanvasClick(event) {
1827
+ this._seekFromPointer(event.clientX);
1828
+ }
1829
+ /**
1830
+ * Seek to a horizontal client-X position over the canvas — shared by
1831
+ * click and drag. In external mode the player has no audio of its own,
1832
+ * so it dispatches a cancelable `waveformplayer:request-seek` with the
1833
+ * target percentage (updating the local visual optimistically); in self
1834
+ * mode it seeks the owned `<audio>` via
1835
+ * {@link WaveformPlayer#seekToPercent}.
1836
+ * @param {number} clientX - Pointer client-X coordinate.
1837
+ * @private
1838
+ * @fires WaveformPlayer#waveformplayer:request-seek
1839
+ */
1840
+ _seekFromPointer(clientX) {
1712
1841
  const rect = this.canvas.getBoundingClientRect();
1713
- const x = event.clientX - rect.left;
1714
- const targetPercent = clamp(x / rect.width);
1842
+ if (!rect.width) return;
1843
+ const targetPercent = clamp((clientX - rect.left) / rect.width);
1715
1844
  if (this.options.audioMode === "external") {
1716
1845
  this._requestSeek(targetPercent);
1717
1846
  return;
@@ -1893,10 +2022,12 @@ var WaveformPlayer = class _WaveformPlayer {
1893
2022
  */
1894
2023
  updateProgress() {
1895
2024
  if (!this.audio || !this.audio.duration) return;
2025
+ if (this._dragging) return;
1896
2026
  const newProgress = this.audio.currentTime / this.audio.duration;
1897
2027
  if (Math.abs(newProgress - this.progress) > 1e-3) {
1898
2028
  this.progress = newProgress;
1899
2029
  this.drawWaveform();
2030
+ this._updateSeekHandle();
1900
2031
  }
1901
2032
  if (this.currentTimeEl) {
1902
2033
  this.currentTimeEl.textContent = formatTime(this.audio.currentTime);
@@ -1936,33 +2067,21 @@ var WaveformPlayer = class _WaveformPlayer {
1936
2067
  * @public
1937
2068
  */
1938
2069
  refreshTheme() {
1939
- if (!this._autoTheme || !this._presetKeys || !this._presetKeys.length) return;
2070
+ if (!this._autoTheme) return;
2071
+ this._scheme = detectColorScheme();
1940
2072
  const preset = getColorPreset(this.options.colorPreset);
1941
- let changed = false;
1942
- for (const key of this._presetKeys) {
1943
- if (this.options[key] !== preset[key]) {
1944
- this.options[key] = preset[key];
1945
- changed = true;
1946
- }
2073
+ for (const key of this._presetKeys || []) {
2074
+ if (key in preset) this.options[key] = preset[key];
1947
2075
  }
1948
- if (changed) this._applyThemeColors();
2076
+ this._applyThemeColors();
1949
2077
  }
1950
2078
  /**
1951
- * Push the current resolved colours onto the live DOM (button border/icon,
1952
- * title, subtitle, time, BPM) and redraw the waveform.
2079
+ * Sync the theme class (CSS drives the DOM chrome colours via `--wfp-*`
2080
+ * variables) and redraw the canvas with the resolved waveform colours.
1953
2081
  * @private
1954
2082
  */
1955
2083
  _applyThemeColors() {
1956
- const o = this.options;
1957
- if (this.playBtn) {
1958
- this.playBtn.style.borderColor = o.buttonColor;
1959
- this.playBtn.style.color = o.buttonColor;
1960
- }
1961
- if (this.titleEl) this.titleEl.style.color = o.textColor;
1962
- if (this.subtitleEl) this.subtitleEl.style.color = o.textSecondaryColor;
1963
- this.container.querySelectorAll(".waveform-time, .waveform-bpm").forEach((el) => {
1964
- el.style.color = o.textSecondaryColor;
1965
- });
2084
+ this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
1966
2085
  if (this.canvas) this.drawWaveform();
1967
2086
  }
1968
2087
  /**
@@ -2076,16 +2195,13 @@ var WaveformPlayer = class _WaveformPlayer {
2076
2195
  * directly: `WaveformBar.play(event.detail)`.
2077
2196
  *
2078
2197
  * @private
2079
- * @return {{url:string,title:?string,subtitle:?string,artist:?string,artwork:?string,player:WaveformPlayer}}
2198
+ * @return {{url:string,title:?string,artist:?string,artwork:?string,player:WaveformPlayer}}
2080
2199
  */
2081
2200
  _buildTrackDetail() {
2082
2201
  return {
2083
2202
  url: this.options.url,
2084
2203
  title: this.options.title,
2085
- subtitle: this.options.subtitle,
2086
- // Core has no separate `artist` option; mirror subtitle so the
2087
- // published event detail is self-consistent for controllers.
2088
- artist: this.options.artist || this.options.subtitle,
2204
+ artist: this.options.artist,
2089
2205
  artwork: this.options.artwork,
2090
2206
  markers: this.options.markers,
2091
2207
  waveform: this.options.waveform,
@@ -2308,7 +2424,7 @@ var WaveformPlayer = class _WaveformPlayer {
2308
2424
  * @param {number} samples - Number of samples
2309
2425
  * @returns {Promise<number[]>} Waveform peak data
2310
2426
  */
2311
- static async generateWaveformData(url, samples = 200) {
2427
+ static async generateWaveformData(url, samples = DEFAULT_SAMPLES) {
2312
2428
  try {
2313
2429
  const result = await generateWaveform(url, samples);
2314
2430
  return result.peaks;