@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.
@@ -1,5 +1,13 @@
1
1
  (() => {
2
2
  // src/js/utils.js
3
+ var DEFAULT_SAMPLES = 1800;
4
+ function maxOf(values) {
5
+ let max = -Infinity;
6
+ for (let i = 0; i < values.length; i++) {
7
+ if (values[i] > max) max = values[i];
8
+ }
9
+ return max;
10
+ }
3
11
  function escapeHtml(str) {
4
12
  return String(str == null ? "" : str).replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
5
13
  }
@@ -56,6 +64,7 @@
56
64
  if (element.dataset.audioMode) options.audioMode = element.dataset.audioMode;
57
65
  if (element.dataset.style) options.waveformStyle = element.dataset.style;
58
66
  if (element.dataset.waveformStyle) options.waveformStyle = element.dataset.waveformStyle;
67
+ if (element.dataset.waveformGradient) options.waveformGradient = element.dataset.waveformGradient;
59
68
  setNum("barWidth");
60
69
  setNum("barSpacing");
61
70
  setNum("barRadius");
@@ -69,12 +78,6 @@
69
78
  if (element.dataset.colorPreset) options.colorPreset = element.dataset.colorPreset;
70
79
  if (element.dataset.waveformColor) options.waveformColor = parseColorValue(element.dataset.waveformColor);
71
80
  if (element.dataset.progressColor) options.progressColor = parseColorValue(element.dataset.progressColor);
72
- if (element.dataset.buttonColor) options.buttonColor = element.dataset.buttonColor;
73
- if (element.dataset.buttonHoverColor) options.buttonHoverColor = element.dataset.buttonHoverColor;
74
- if (element.dataset.textColor) options.textColor = element.dataset.textColor;
75
- if (element.dataset.textSecondaryColor) options.textSecondaryColor = element.dataset.textSecondaryColor;
76
- if (element.dataset.backgroundColor) options.backgroundColor = element.dataset.backgroundColor;
77
- if (element.dataset.borderColor) options.borderColor = element.dataset.borderColor;
78
81
  if (element.dataset.color) options.waveformColor = element.dataset.color;
79
82
  if (element.dataset.theme) options.colorPreset = element.dataset.theme;
80
83
  setBool("autoplay");
@@ -82,12 +85,13 @@
82
85
  setBool("showInfo");
83
86
  setBool("showTime");
84
87
  setBool("showHoverTime");
88
+ setBool("seekHandle");
85
89
  setBool("showBPM", "showBpm");
86
90
  setNum("bpm");
87
91
  setBool("singlePlay");
88
92
  setBool("playOnSeek");
89
93
  if (element.dataset.title) options.title = element.dataset.title;
90
- if (element.dataset.subtitle) options.subtitle = element.dataset.subtitle;
94
+ if (element.dataset.artist) options.artist = element.dataset.artist;
91
95
  if (element.dataset.album) options.album = element.dataset.album;
92
96
  if (element.dataset.artwork) options.artwork = element.dataset.artwork;
93
97
  if (element.dataset.waveform) options.waveform = element.dataset.waveform;
@@ -202,12 +206,20 @@
202
206
  }
203
207
 
204
208
  // src/js/drawing.js
205
- function makeFill(ctx, value, height) {
209
+ function makeFill(ctx, value, canvas, options) {
206
210
  if (!Array.isArray(value)) return value;
207
- if (value.length === 1) return value[0];
208
- const grad = ctx.createLinearGradient(0, 0, 0, height);
209
- value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
210
- return grad;
211
+ if (value.length < 2) return value[0];
212
+ const w = canvas.width;
213
+ const h = canvas.height;
214
+ const dir = options && options.waveformGradient;
215
+ const [x0, y0, x1, y1] = dir === "horizontal" ? [0, 0, w, 0] : dir === "diagonal" ? [0, 0, w, h] : [0, 0, 0, h];
216
+ try {
217
+ const grad = ctx.createLinearGradient(x0, y0, x1, y1);
218
+ value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
219
+ return grad;
220
+ } catch (e) {
221
+ return value[0];
222
+ }
211
223
  }
212
224
  function fillBar(ctx, x, y, w, h, radii) {
213
225
  const any = Array.isArray(radii) ? radii.some((r) => r > 0) : radii > 0;
@@ -247,8 +259,8 @@
247
259
  const height = canvas.height;
248
260
  const progressWidth = progress * canvas.width;
249
261
  const radii = barRadii(options, dpr);
250
- const baseFill = makeFill(ctx, options.color, height);
251
- const progFill = makeFill(ctx, options.progressColor, height);
262
+ const baseFill = makeFill(ctx, options.color, canvas, options);
263
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
252
264
  ctx.clearRect(0, 0, canvas.width, canvas.height);
253
265
  ctx.fillStyle = baseFill;
254
266
  for (let i = 0; i < resampledPeaks.length; i++) {
@@ -284,8 +296,8 @@
284
296
  const r = barRadiusPx(options, dpr);
285
297
  const topRadii = [r, r, 0, 0];
286
298
  const botRadii = [0, 0, r, r];
287
- const baseFill = makeFill(ctx, options.color, height);
288
- const progFill = makeFill(ctx, options.progressColor, height);
299
+ const baseFill = makeFill(ctx, options.color, canvas, options);
300
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
289
301
  ctx.clearRect(0, 0, canvas.width, canvas.height);
290
302
  ctx.fillStyle = baseFill;
291
303
  for (let i = 0; i < resampledPeaks.length; i++) {
@@ -316,11 +328,13 @@
316
328
  const amplitude = height * 0.35;
317
329
  ctx.clearRect(0, 0, width, height);
318
330
  const drawCurve = (color, lineWidth, endProgress = 1, addGlow = false) => {
331
+ const stroke = makeFill(ctx, color, canvas, options);
332
+ const solid = Array.isArray(color) ? color[color.length - 1] : color;
319
333
  if (addGlow) {
320
334
  ctx.shadowBlur = 12;
321
- ctx.shadowColor = color;
335
+ ctx.shadowColor = solid;
322
336
  }
323
- ctx.strokeStyle = color;
337
+ ctx.strokeStyle = stroke;
324
338
  ctx.lineWidth = lineWidth;
325
339
  ctx.lineCap = "round";
326
340
  ctx.lineJoin = "round";
@@ -376,8 +390,8 @@
376
390
  const blockGap = 2 * dpr;
377
391
  const progressWidth = progress * canvas.width;
378
392
  const centerY = height / 2;
379
- const baseFill = makeFill(ctx, options.color, height);
380
- const progFill = makeFill(ctx, options.progressColor, height);
393
+ const baseFill = makeFill(ctx, options.color, canvas, options);
394
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
381
395
  ctx.clearRect(0, 0, canvas.width, canvas.height);
382
396
  for (let i = 0; i < resampledPeaks.length; i++) {
383
397
  const x = i * (barWidth + barSpacing);
@@ -404,8 +418,8 @@
404
418
  const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
405
419
  const progressWidth = progress * canvas.width;
406
420
  const centerY = height / 2;
407
- const baseFill = makeFill(ctx, options.color, height);
408
- const progFill = makeFill(ctx, options.progressColor, height);
421
+ const baseFill = makeFill(ctx, options.color, canvas, options);
422
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
409
423
  ctx.clearRect(0, 0, canvas.width, canvas.height);
410
424
  for (let i = 0; i < resampledPeaks.length; i++) {
411
425
  const x = i * (barWidth + barSpacing) + barWidth / 2;
@@ -426,33 +440,19 @@
426
440
  const centerY = height / 2;
427
441
  const barHeight = 4;
428
442
  const borderRadius = barHeight / 2;
443
+ const active = !!options.seekActive;
429
444
  ctx.clearRect(0, 0, width, height);
430
- ctx.fillStyle = options.color || "rgba(255, 255, 255, 0.2)";
445
+ ctx.fillStyle = makeFill(ctx, options.color, canvas, options) || "rgba(255, 255, 255, 0.2)";
431
446
  capsulePath(ctx, borderRadius, width, centerY, barHeight);
432
447
  ctx.fill();
433
448
  if (progress > 0) {
434
449
  const progressWidth = Math.max(borderRadius * 2, progress * width);
435
- ctx.shadowBlur = 8;
436
- ctx.shadowColor = options.progressColor;
437
- ctx.fillStyle = options.progressColor || "rgba(255, 255, 255, 0.9)";
450
+ ctx.save();
451
+ ctx.globalAlpha = options.seekHandle && !active ? 0.7 : 1;
452
+ ctx.fillStyle = makeFill(ctx, options.progressColor, canvas, options) || "rgba(255, 255, 255, 0.9)";
438
453
  capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
439
454
  ctx.fill();
440
- ctx.shadowBlur = 0;
441
- const handleRadius = 8;
442
- const handleX = progressWidth;
443
- ctx.shadowBlur = 4;
444
- ctx.shadowColor = "rgba(0, 0, 0, 0.3)";
445
- ctx.shadowOffsetY = 2;
446
- ctx.fillStyle = "#ffffff";
447
- ctx.beginPath();
448
- ctx.arc(handleX, centerY, handleRadius, 0, Math.PI * 2);
449
- ctx.fill();
450
- ctx.shadowBlur = 0;
451
- ctx.shadowOffsetY = 0;
452
- ctx.fillStyle = options.progressColor || "rgba(255, 255, 255, 0.9)";
453
- ctx.beginPath();
454
- ctx.arc(handleX, centerY, handleRadius * 0.4, 0, Math.PI * 2);
455
- ctx.fill();
455
+ ctx.restore();
456
456
  }
457
457
  }
458
458
  var DRAWING_STYLES = {
@@ -541,7 +541,7 @@
541
541
  }
542
542
 
543
543
  // src/js/audio.js
544
- function extractPeaks(buffer, samples = 200) {
544
+ function extractPeaks(buffer, samples = DEFAULT_SAMPLES) {
545
545
  const sampleSize = buffer.length / samples;
546
546
  const channels = buffer.numberOfChannels;
547
547
  const peaks = [];
@@ -563,10 +563,10 @@
563
563
  }
564
564
  }
565
565
  }
566
- const maxPeak = Math.max(...peaks);
566
+ const maxPeak = maxOf(peaks);
567
567
  return maxPeak > 0 ? peaks.map((peak) => peak / maxPeak) : peaks;
568
568
  }
569
- async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
569
+ async function generateWaveform(url, samples = DEFAULT_SAMPLES, shouldDetectBPM = false) {
570
570
  let audioContext;
571
571
  try {
572
572
  const AudioCtx = window.AudioContext || /** @type {any} */
@@ -586,7 +586,7 @@
586
586
  if (audioContext) audioContext.close();
587
587
  }
588
588
  }
589
- function generatePlaceholderWaveform(samples = 200) {
589
+ function generatePlaceholderWaveform(samples = DEFAULT_SAMPLES) {
590
590
  const data = [];
591
591
  for (let i = 0; i < samples; i++) {
592
592
  const base = Math.random() * 0.5 + 0.3;
@@ -596,7 +596,7 @@
596
596
  return data;
597
597
  }
598
598
  function normalizePeaks(peaks, targetMax = 0.95) {
599
- const maxPeak = Math.max(...peaks);
599
+ const maxPeak = maxOf(peaks);
600
600
  if (maxPeak === 0 || maxPeak > targetMax) return peaks;
601
601
  const scaleFactor = targetMax / maxPeak;
602
602
  return peaks.map((peak) => peak * scaleFactor);
@@ -633,23 +633,11 @@
633
633
  var COLOR_PRESETS = {
634
634
  dark: {
635
635
  waveformColor: "rgba(255, 255, 255, 0.3)",
636
- progressColor: "rgba(255, 255, 255, 0.9)",
637
- buttonColor: "rgba(255, 255, 255, 0.9)",
638
- buttonHoverColor: "rgba(255, 255, 255, 1)",
639
- textColor: "#ffffff",
640
- textSecondaryColor: "rgba(255, 255, 255, 0.6)",
641
- backgroundColor: "rgba(255, 255, 255, 0.03)",
642
- borderColor: "rgba(255, 255, 255, 0.1)"
636
+ progressColor: "rgba(255, 255, 255, 0.9)"
643
637
  },
644
638
  light: {
645
639
  waveformColor: "rgba(0, 0, 0, 0.2)",
646
- progressColor: "rgba(0, 0, 0, 0.8)",
647
- buttonColor: "rgba(0, 0, 0, 0.8)",
648
- buttonHoverColor: "rgba(0, 0, 0, 0.9)",
649
- textColor: "#333333",
650
- textSecondaryColor: "rgba(0, 0, 0, 0.6)",
651
- backgroundColor: "rgba(0, 0, 0, 0.02)",
652
- borderColor: "rgba(0, 0, 0, 0.1)"
640
+ progressColor: "rgba(0, 0, 0, 0.8)"
653
641
  }
654
642
  };
655
643
  function getColorPreset(presetName) {
@@ -668,7 +656,7 @@
668
656
  // bars, so this is fidelity headroom, not the visible bar count. 1800 (the
669
657
  // SoundCloud/WaveformGen figure) keeps wide / high-DPI waveforms crisp; the
670
658
  // every-frame scan means a higher value costs no extra extraction time.
671
- samples: 1800,
659
+ samples: DEFAULT_SAMPLES,
672
660
  preload: "metadata",
673
661
  // Audio mode — 'self' = player owns the <audio> element (default, current
674
662
  // behavior). 'external' = player is a visualization-only surface; no audio
@@ -702,23 +690,29 @@
702
690
  barSpacing: 0,
703
691
  // Rounded bar caps (px). 0 = square; 1 = soft caps (default). Applies to bars/mirror.
704
692
  barRadius: 1,
693
+ // Gradient axis when waveformColor/progressColor is an array of stops:
694
+ // 'vertical' (top->bottom canvas gradient), 'horizontal' (hue sweep across the
695
+ // waveform) or 'diagonal'. Ignored for single colours.
696
+ waveformGradient: "vertical",
705
697
  // Color preset: null = auto-detect, 'dark' = force dark, 'light' = force light
706
698
  colorPreset: null,
707
- // Individual color overrides (null means use preset)
699
+ // Canvas colours (null = inherit the resolved preset; arrays = gradient
700
+ // stops, see waveformGradient). The DOM chrome (button, title, meta) is
701
+ // themed via CSS variables (--wfp-button-color / --wfp-text-color /
702
+ // --wfp-text-secondary-color), not JS options.
708
703
  waveformColor: null,
709
704
  progressColor: null,
710
- buttonColor: null,
711
- buttonHoverColor: null,
712
- textColor: null,
713
- textSecondaryColor: null,
714
- backgroundColor: null,
715
- borderColor: null,
716
705
  // Features
717
706
  autoplay: false,
718
707
  showControls: true,
719
708
  showInfo: true,
720
709
  showTime: true,
721
710
  showHoverTime: false,
711
+ // Show a draggable circle handle + hover brightness-lift on the SEEKBAR
712
+ // style only (it's meaningless on a waveform, where the fill-edge is the
713
+ // playhead). Off by default; the bar turns it on. Drag-to-scrub works
714
+ // regardless of this.
715
+ seekHandle: false,
722
716
  showBPM: false,
723
717
  // Known BPM to display in the badge (with showBPM). Wins over auto-detection
724
718
  // — set it when peaks are pre-generated so the tempo still shows. null = auto.
@@ -737,7 +731,7 @@
737
731
  seekLabel: null,
738
732
  // Content
739
733
  title: null,
740
- subtitle: null,
734
+ artist: null,
741
735
  artwork: null,
742
736
  album: "",
743
737
  // Message shown in the error state when audio fails to load.
@@ -768,6 +762,7 @@
768
762
  );
769
763
  var SEEK_STEP_SECONDS = 5;
770
764
  var SEEK_PAGE_SECONDS = 10;
765
+ var INTERACTIVE_ELEMENTS = 'button, a[href], input, [role="slider"]';
771
766
  var WaveformPlayer = class _WaveformPlayer {
772
767
  /** @type {Map<string, WaveformPlayer>} */
773
768
  static instances = /* @__PURE__ */ new Map();
@@ -803,6 +798,7 @@
803
798
  const preset = getColorPreset(this.options.colorPreset);
804
799
  this._autoTheme = this.options.colorPreset == null || !COLOR_PRESETS[this.options.colorPreset];
805
800
  this._presetKeys = [];
801
+ this._scheme = this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset] ? this.options.colorPreset : detectColorScheme();
806
802
  for (const [key, value] of Object.entries(preset)) {
807
803
  if (this.options[key] === null || this.options[key] === void 0) {
808
804
  this.options[key] = value;
@@ -909,7 +905,7 @@
909
905
  *
910
906
  * Clears the container, resolves button alignment (`auto` → `bottom` for
911
907
  * the `bars` style, `center` otherwise), and conditionally renders the play
912
- * button, info row (artwork/title/subtitle), BPM badge, playback-speed
908
+ * button, info row (artwork/title/artist), BPM badge, playback-speed
913
909
  * menu, and time display based on the relevant `show*` options. Caches the
914
910
  * canvas, controls, and text elements onto `this`, then sizes the canvas.
915
911
  * @private
@@ -930,12 +926,9 @@
930
926
  if (isPreview) {
931
927
  this.container.classList.add("waveform-layout-preview");
932
928
  }
929
+ this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
933
930
  const buttonHTML = this.options.showControls ? `
934
- <button class="waveform-btn${this.options.buttonStyle === "minimal" ? " waveform-btn-minimal" : ""}" aria-label="Play/Pause" style="
935
- border-color: ${this.options.buttonColor};
936
- color: ${this.options.buttonColor};
937
- ${this.options.buttonSize != null ? `--wfp-btn-size: ${typeof this.options.buttonSize === "number" ? `${this.options.buttonSize}px` : this.options.buttonSize};` : ""}
938
- ">
931
+ <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};"` : ""}>
939
932
  <span class="waveform-icon-play">${this.options.playIcon}</span>
940
933
  <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
941
934
  </button>
@@ -952,18 +945,18 @@
952
945
  ">
953
946
  ` : ""}
954
947
  <div class="waveform-text">
955
- <span class="waveform-title" style="color: ${this.options.textColor};"></span>
956
- ${this.options.subtitle ? `<span class="waveform-subtitle" style="color: ${this.options.textSecondaryColor};">${this.options.subtitle}</span>` : ""}
948
+ <span class="waveform-title"></span>
949
+ ${this.options.artist ? `<span class="waveform-artist">${this.options.artist}</span>` : ""}
957
950
  </div>
958
951
  <div class="waveform-meta" style="display: flex; align-items: center; gap: 1rem;">
959
952
  ${this.options.showBPM ? `
960
- <span class="waveform-bpm" style="color: ${this.options.textSecondaryColor}; display: none;">
953
+ <span class="waveform-bpm" style="display: none;">
961
954
  <span class="bpm-value">--</span> BPM
962
955
  </span>
963
956
  ` : ""}
964
957
  ${this.options.showPlaybackSpeed ? `
965
958
  <div class="waveform-speed">
966
- <button class="speed-btn" aria-label="Playback speed">
959
+ <button class="speed-btn" aria-label="Playback speed" aria-haspopup="true" aria-expanded="false">
967
960
  <span class="speed-value">1x</span>
968
961
  </button>
969
962
  <div class="speed-menu" style="display: none;">
@@ -974,7 +967,7 @@
974
967
  </div>
975
968
  ` : ""}
976
969
  ${this.options.showTime ? `
977
- <span class="waveform-time" style="color: ${this.options.textSecondaryColor};">
970
+ <span class="waveform-time">
978
971
  <span class="time-current">0:00</span> / <span class="time-total">0:00</span>
979
972
  </span>
980
973
  ` : ""}
@@ -1005,7 +998,7 @@
1005
998
  this.canvas = this.container.querySelector("canvas");
1006
999
  this.ctx = this.canvas.getContext("2d");
1007
1000
  this.titleEl = this.container.querySelector(".waveform-title");
1008
- this.subtitleEl = this.container.querySelector(".waveform-subtitle");
1001
+ this.artistEl = this.container.querySelector(".waveform-artist");
1009
1002
  this.artworkEl = this.container.querySelector(".waveform-artwork");
1010
1003
  if (this.artworkEl) {
1011
1004
  this.artworkEl.addEventListener("error", () => {
@@ -1062,8 +1055,9 @@
1062
1055
  }
1063
1056
  /**
1064
1057
  * Wire up the playback-speed menu: toggle it open on the speed button,
1065
- * close it on any outside click, and apply the chosen rate when a
1066
- * `.speed-option` is clicked. All listeners are registered against the
1058
+ * close it on outside click or Escape (keeping `aria-expanded` on the
1059
+ * trigger in sync), and apply the chosen rate when a `.speed-option` is
1060
+ * clicked, returning focus to the trigger. All listeners are registered against the
1067
1061
  * instance `AbortController` signal so {@link WaveformPlayer#destroy} tears
1068
1062
  * them down. No-op if the speed elements are absent.
1069
1063
  * @private
@@ -1072,19 +1066,27 @@
1072
1066
  const speedBtn = this.container.querySelector(".speed-btn");
1073
1067
  const speedMenu = this.container.querySelector(".speed-menu");
1074
1068
  if (!speedBtn || !speedMenu) return;
1069
+ const setSpeedMenu = (open) => {
1070
+ speedMenu.style.display = open ? "block" : "none";
1071
+ speedBtn.setAttribute("aria-expanded", open ? "true" : "false");
1072
+ };
1075
1073
  speedBtn.addEventListener("click", (e) => {
1076
1074
  e.stopPropagation();
1077
- speedMenu.style.display = speedMenu.style.display === "none" ? "block" : "none";
1078
- }, { signal: this._ac.signal });
1079
- document.addEventListener("click", () => {
1080
- speedMenu.style.display = "none";
1075
+ setSpeedMenu(speedMenu.style.display === "none");
1081
1076
  }, { signal: this._ac.signal });
1077
+ document.addEventListener("click", () => setSpeedMenu(false), { signal: this._ac.signal });
1082
1078
  speedMenu.addEventListener("click", (e) => {
1083
1079
  e.stopPropagation();
1084
1080
  if (e.target.classList.contains("speed-option")) {
1085
- const rate = parseFloat(e.target.dataset.rate);
1086
- this.setPlaybackRate(rate);
1087
- speedMenu.style.display = "none";
1081
+ this.setPlaybackRate(parseFloat(e.target.dataset.rate));
1082
+ setSpeedMenu(false);
1083
+ speedBtn.focus();
1084
+ }
1085
+ }, { signal: this._ac.signal });
1086
+ speedBtn.closest(".waveform-speed")?.addEventListener("keydown", (e) => {
1087
+ if (e.key === "Escape" && speedMenu.style.display !== "none") {
1088
+ setSpeedMenu(false);
1089
+ speedBtn.focus();
1088
1090
  }
1089
1091
  }, { signal: this._ac.signal });
1090
1092
  this.updateSpeedUI();
@@ -1102,7 +1104,8 @@
1102
1104
  */
1103
1105
  initKeyboardControls() {
1104
1106
  this.container.setAttribute("tabindex", "-1");
1105
- this.container.addEventListener("click", () => {
1107
+ this.container.addEventListener("click", (e) => {
1108
+ if (e.target.closest(INTERACTIVE_ELEMENTS)) return;
1106
1109
  _WaveformPlayer.getAllInstances().forEach((player) => {
1107
1110
  if (player !== this) {
1108
1111
  player.container.setAttribute("tabindex", "-1");
@@ -1270,7 +1273,7 @@
1270
1273
  if (!this.audio) return;
1271
1274
  navigator.mediaSession.metadata = new MediaMetadata({
1272
1275
  title: this.options.title || "Unknown Track",
1273
- artist: this.options.subtitle || "",
1276
+ artist: this.options.artist || "",
1274
1277
  album: this.options.album || "",
1275
1278
  artwork: this.options.artwork ? [
1276
1279
  { src: this.options.artwork, sizes: "512x512", type: "image/jpeg" }
@@ -1314,7 +1317,56 @@
1314
1317
  this.audio.addEventListener("error", (e) => this.onError(e));
1315
1318
  }
1316
1319
  this.canvas.addEventListener("click", (e) => this.handleCanvasClick(e));
1320
+ this._dragging = false;
1321
+ this._seekHover = false;
1322
+ this._handleNear = false;
1323
+ this.canvas.addEventListener("pointerenter", () => {
1324
+ this._seekHover = true;
1325
+ this.drawWaveform();
1326
+ this._updateSeekHandle();
1327
+ });
1328
+ this.canvas.addEventListener("pointerleave", () => {
1329
+ this._seekHover = false;
1330
+ this._handleNear = false;
1331
+ if (!this._dragging) this._hideHoverTip();
1332
+ this.drawWaveform();
1333
+ this._updateSeekHandle();
1334
+ });
1335
+ this.canvas.addEventListener("pointerdown", (e) => {
1336
+ if (e.pointerType === "mouse" && e.button !== 0) return;
1337
+ this._dragging = true;
1338
+ try {
1339
+ this.canvas.setPointerCapture(e.pointerId);
1340
+ } catch (err) {
1341
+ }
1342
+ this._scrubTo(e.clientX);
1343
+ });
1344
+ this.canvas.addEventListener("pointermove", (e) => {
1345
+ if (this._dragging) {
1346
+ this._scrubTo(e.clientX);
1347
+ return;
1348
+ }
1349
+ const rect = this.canvas.getBoundingClientRect();
1350
+ if (rect.width) {
1351
+ this._handleNear = Math.abs(e.clientX - rect.left - this.progress * rect.width) <= 10;
1352
+ this._updateSeekHandle();
1353
+ }
1354
+ });
1355
+ const endDrag = (e) => {
1356
+ if (!this._dragging) return;
1357
+ this._dragging = false;
1358
+ try {
1359
+ this.canvas.releasePointerCapture(e.pointerId);
1360
+ } catch (err) {
1361
+ }
1362
+ this._seekFromPointer(e.clientX);
1363
+ if (!this._seekHover && !this.options.showHoverTime) this._hideHoverTip();
1364
+ this._updateSeekHandle();
1365
+ };
1366
+ this.canvas.addEventListener("pointerup", endDrag);
1367
+ this.canvas.addEventListener("pointercancel", endDrag);
1317
1368
  this.setupHoverTime();
1369
+ this.setupSeekHandle();
1318
1370
  this.resizeHandler = debounce(() => this.resizeCanvas(), 100);
1319
1371
  window.addEventListener("resize", this.resizeHandler);
1320
1372
  }
@@ -1411,19 +1463,19 @@
1411
1463
  *
1412
1464
  * Pauses any current playback, fully resets the audio element (self mode),
1413
1465
  * clears error/marker/progress state, merges the new metadata into
1414
- * `this.options`, updates the subtitle/artwork DOM, then calls
1466
+ * `this.options`, updates the artist/artwork DOM, then calls
1415
1467
  * {@link WaveformPlayer#load}. Auto-plays the new track unless
1416
1468
  * `options.autoplay === false`.
1417
1469
  * @param {string} url - Audio URL.
1418
1470
  * @param {string|null} [title=null] - Track title; keeps the existing
1419
1471
  * title when null.
1420
- * @param {string|null} [subtitle=null] - Track subtitle; pass `''` to hide
1421
- * the subtitle row, or null to keep the existing one.
1472
+ * @param {string|null} [artist=null] - Track artist; pass `''` to hide
1473
+ * the artist row, or null to keep the existing one.
1422
1474
  * @param {Object} [options={}] - Additional options to merge (e.g.
1423
1475
  * `preload`, `artwork`, `markers`, `autoplay`).
1424
1476
  * @returns {Promise<void>}
1425
1477
  */
1426
- async loadTrack(url, title = null, subtitle = null, options = {}) {
1478
+ async loadTrack(url, title = null, artist = null, options = {}) {
1427
1479
  if (this.isPlaying) {
1428
1480
  this.pause();
1429
1481
  }
@@ -1446,18 +1498,18 @@
1446
1498
  this.options = mergeOptions(this.options, {
1447
1499
  url,
1448
1500
  title: title || this.options.title,
1449
- subtitle: subtitle || this.options.subtitle,
1501
+ artist: artist || this.options.artist,
1450
1502
  ...options
1451
1503
  });
1452
1504
  if (options.preload && this.audio) {
1453
1505
  this.audio.preload = options.preload;
1454
1506
  }
1455
- if (this.subtitleEl) {
1456
- if (subtitle) {
1457
- this.subtitleEl.textContent = subtitle;
1458
- this.subtitleEl.style.display = "";
1459
- } else if (subtitle === "") {
1460
- this.subtitleEl.style.display = "none";
1507
+ if (this.artistEl) {
1508
+ if (artist) {
1509
+ this.artistEl.textContent = artist;
1510
+ this.artistEl.style.display = "";
1511
+ } else if (artist === "") {
1512
+ this.artistEl.style.display = "none";
1461
1513
  }
1462
1514
  }
1463
1515
  if (options.artwork && this.artworkEl) {
@@ -1523,7 +1575,8 @@
1523
1575
  ...this.options,
1524
1576
  waveformStyle: this.options.waveformStyle || "bars",
1525
1577
  color: this.options.waveformColor,
1526
- progressColor: this.options.progressColor
1578
+ progressColor: this.options.progressColor,
1579
+ seekActive: this._seekHover || this._dragging
1527
1580
  });
1528
1581
  }
1529
1582
  /**
@@ -1639,35 +1692,97 @@
1639
1692
  }
1640
1693
  }
1641
1694
  /**
1642
- * Build a tooltip that follows the pointer over the waveform and shows the
1643
- * time at that position. Enabled by the `showHoverTime` option; works in both
1695
+ * Build the time tooltip that follows the pointer over the waveform. The
1696
+ * element is always created so **drag-scrub** can show the time you're
1697
+ * dragging to; the *hover* reveal is gated on `showHoverTime`. Works in both
1644
1698
  * self and external modes (it only needs {@link WaveformPlayer#getSeekDuration}).
1645
- * Uses the same pointer-X → percentage math as seeking.
1646
1699
  * @private
1647
1700
  */
1648
1701
  setupHoverTime() {
1649
- if (!this.options.showHoverTime || !this.seekEl) return;
1702
+ if (!this.seekEl) return;
1650
1703
  const tip = document.createElement("div");
1651
1704
  tip.className = "waveform-hover-time";
1652
1705
  tip.setAttribute("aria-hidden", "true");
1653
1706
  this.seekEl.appendChild(tip);
1654
1707
  this.hoverTimeEl = tip;
1708
+ if (!this.options.showHoverTime) return;
1655
1709
  this.seekEl.addEventListener("pointermove", (e) => {
1656
- const dur = this.getSeekDuration();
1657
- if (!dur) {
1658
- tip.style.opacity = "0";
1659
- return;
1660
- }
1661
- const rect = this.canvas.getBoundingClientRect();
1662
- const pct = clamp((e.clientX - rect.left) / rect.width);
1663
- tip.textContent = formatTime(pct * dur);
1664
- tip.style.left = pct * 100 + "%";
1665
- tip.style.opacity = "1";
1710
+ if (!this._dragging) this._updateHoverTip(e.clientX);
1666
1711
  });
1667
1712
  this.seekEl.addEventListener("pointerleave", () => {
1668
- tip.style.opacity = "0";
1713
+ if (!this._dragging) this._hideHoverTip();
1669
1714
  });
1670
1715
  }
1716
+ /**
1717
+ * Position + fill the hover-time tooltip for a given client-X. Shared by
1718
+ * hover and drag-scrub. No-op when the tooltip isn't enabled
1719
+ * (`showHoverTime` off).
1720
+ * @param {number} clientX - Pointer client-X coordinate.
1721
+ * @private
1722
+ */
1723
+ _updateHoverTip(clientX) {
1724
+ const tip = this.hoverTimeEl;
1725
+ if (!tip) return;
1726
+ const dur = this.getSeekDuration();
1727
+ if (!dur) {
1728
+ tip.style.opacity = "0";
1729
+ return;
1730
+ }
1731
+ const rect = this.canvas.getBoundingClientRect();
1732
+ const pct = clamp((clientX - rect.left) / rect.width);
1733
+ tip.textContent = formatTime(pct * dur);
1734
+ tip.style.left = pct * 100 + "%";
1735
+ tip.style.opacity = "1";
1736
+ }
1737
+ /** Hide the hover-time tooltip. @private */
1738
+ _hideHoverTip() {
1739
+ if (this.hoverTimeEl) this.hoverTimeEl.style.opacity = "0";
1740
+ }
1741
+ /**
1742
+ * Visually preview a seek during a drag — moves the playhead + handle +
1743
+ * tooltip to the cursor WITHOUT touching the audio (playback continues; the
1744
+ * real seek is committed on release).
1745
+ * @param {number} clientX - Pointer client-X coordinate.
1746
+ * @private
1747
+ */
1748
+ _scrubTo(clientX) {
1749
+ const rect = this.canvas.getBoundingClientRect();
1750
+ if (!rect.width) return;
1751
+ this.progress = clamp((clientX - rect.left) / rect.width);
1752
+ this.drawWaveform();
1753
+ this._updateSeekHandle();
1754
+ this._updateHoverTip(clientX);
1755
+ const dur = this.getSeekDuration();
1756
+ if (dur && this.currentTimeEl) {
1757
+ this.currentTimeEl.textContent = formatTime(this.progress * dur);
1758
+ }
1759
+ }
1760
+ /**
1761
+ * Create the draggable seek handle — a DOM circle over the playhead, shown
1762
+ * only on hover / drag (Spotify-style). Pointer-events are off so it never
1763
+ * blocks the canvas scrub; size + visibility are CSS.
1764
+ * @private
1765
+ */
1766
+ setupSeekHandle() {
1767
+ if (!this.options.seekHandle || this.options.waveformStyle !== "seekbar" || !this.seekEl) return;
1768
+ const h = document.createElement("div");
1769
+ h.className = "waveform-seek-handle";
1770
+ h.setAttribute("aria-hidden", "true");
1771
+ this.seekEl.appendChild(h);
1772
+ this.seekHandleEl = h;
1773
+ }
1774
+ /**
1775
+ * Position the seek handle at the current progress and toggle its
1776
+ * visibility (hover / drag) + expanded (drag / direct-hover) classes.
1777
+ * @private
1778
+ */
1779
+ _updateSeekHandle() {
1780
+ const h = this.seekHandleEl;
1781
+ if (!h) return;
1782
+ h.style.left = this.progress * 100 + "%";
1783
+ h.classList.toggle("is-visible", this._seekHover || this._dragging);
1784
+ h.classList.toggle("is-active", this._dragging || this._handleNear);
1785
+ }
1671
1786
  // ============================================
1672
1787
  // Event Handlers
1673
1788
  // ============================================
@@ -1684,9 +1799,23 @@
1684
1799
  * @fires WaveformPlayer#waveformplayer:request-seek
1685
1800
  */
1686
1801
  handleCanvasClick(event) {
1802
+ this._seekFromPointer(event.clientX);
1803
+ }
1804
+ /**
1805
+ * Seek to a horizontal client-X position over the canvas — shared by
1806
+ * click and drag. In external mode the player has no audio of its own,
1807
+ * so it dispatches a cancelable `waveformplayer:request-seek` with the
1808
+ * target percentage (updating the local visual optimistically); in self
1809
+ * mode it seeks the owned `<audio>` via
1810
+ * {@link WaveformPlayer#seekToPercent}.
1811
+ * @param {number} clientX - Pointer client-X coordinate.
1812
+ * @private
1813
+ * @fires WaveformPlayer#waveformplayer:request-seek
1814
+ */
1815
+ _seekFromPointer(clientX) {
1687
1816
  const rect = this.canvas.getBoundingClientRect();
1688
- const x = event.clientX - rect.left;
1689
- const targetPercent = clamp(x / rect.width);
1817
+ if (!rect.width) return;
1818
+ const targetPercent = clamp((clientX - rect.left) / rect.width);
1690
1819
  if (this.options.audioMode === "external") {
1691
1820
  this._requestSeek(targetPercent);
1692
1821
  return;
@@ -1868,10 +1997,12 @@
1868
1997
  */
1869
1998
  updateProgress() {
1870
1999
  if (!this.audio || !this.audio.duration) return;
2000
+ if (this._dragging) return;
1871
2001
  const newProgress = this.audio.currentTime / this.audio.duration;
1872
2002
  if (Math.abs(newProgress - this.progress) > 1e-3) {
1873
2003
  this.progress = newProgress;
1874
2004
  this.drawWaveform();
2005
+ this._updateSeekHandle();
1875
2006
  }
1876
2007
  if (this.currentTimeEl) {
1877
2008
  this.currentTimeEl.textContent = formatTime(this.audio.currentTime);
@@ -1911,33 +2042,21 @@
1911
2042
  * @public
1912
2043
  */
1913
2044
  refreshTheme() {
1914
- if (!this._autoTheme || !this._presetKeys || !this._presetKeys.length) return;
2045
+ if (!this._autoTheme) return;
2046
+ this._scheme = detectColorScheme();
1915
2047
  const preset = getColorPreset(this.options.colorPreset);
1916
- let changed = false;
1917
- for (const key of this._presetKeys) {
1918
- if (this.options[key] !== preset[key]) {
1919
- this.options[key] = preset[key];
1920
- changed = true;
1921
- }
2048
+ for (const key of this._presetKeys || []) {
2049
+ if (key in preset) this.options[key] = preset[key];
1922
2050
  }
1923
- if (changed) this._applyThemeColors();
2051
+ this._applyThemeColors();
1924
2052
  }
1925
2053
  /**
1926
- * Push the current resolved colours onto the live DOM (button border/icon,
1927
- * title, subtitle, time, BPM) and redraw the waveform.
2054
+ * Sync the theme class (CSS drives the DOM chrome colours via `--wfp-*`
2055
+ * variables) and redraw the canvas with the resolved waveform colours.
1928
2056
  * @private
1929
2057
  */
1930
2058
  _applyThemeColors() {
1931
- const o = this.options;
1932
- if (this.playBtn) {
1933
- this.playBtn.style.borderColor = o.buttonColor;
1934
- this.playBtn.style.color = o.buttonColor;
1935
- }
1936
- if (this.titleEl) this.titleEl.style.color = o.textColor;
1937
- if (this.subtitleEl) this.subtitleEl.style.color = o.textSecondaryColor;
1938
- this.container.querySelectorAll(".waveform-time, .waveform-bpm").forEach((el) => {
1939
- el.style.color = o.textSecondaryColor;
1940
- });
2059
+ this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
1941
2060
  if (this.canvas) this.drawWaveform();
1942
2061
  }
1943
2062
  /**
@@ -2051,16 +2170,13 @@
2051
2170
  * directly: `WaveformBar.play(event.detail)`.
2052
2171
  *
2053
2172
  * @private
2054
- * @return {{url:string,title:?string,subtitle:?string,artist:?string,artwork:?string,player:WaveformPlayer}}
2173
+ * @return {{url:string,title:?string,artist:?string,artwork:?string,player:WaveformPlayer}}
2055
2174
  */
2056
2175
  _buildTrackDetail() {
2057
2176
  return {
2058
2177
  url: this.options.url,
2059
2178
  title: this.options.title,
2060
- subtitle: this.options.subtitle,
2061
- // Core has no separate `artist` option; mirror subtitle so the
2062
- // published event detail is self-consistent for controllers.
2063
- artist: this.options.artist || this.options.subtitle,
2179
+ artist: this.options.artist,
2064
2180
  artwork: this.options.artwork,
2065
2181
  markers: this.options.markers,
2066
2182
  waveform: this.options.waveform,
@@ -2283,7 +2399,7 @@
2283
2399
  * @param {number} samples - Number of samples
2284
2400
  * @returns {Promise<number[]>} Waveform peak data
2285
2401
  */
2286
- static async generateWaveformData(url, samples = 200) {
2402
+ static async generateWaveformData(url, samples = DEFAULT_SAMPLES) {
2287
2403
  try {
2288
2404
  const result = await generateWaveform(url, samples);
2289
2405
  return result.peaks;