@arraypress/waveform-player 1.17.0 → 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.
@@ -64,6 +64,7 @@
64
64
  if (element.dataset.audioMode) options.audioMode = element.dataset.audioMode;
65
65
  if (element.dataset.style) options.waveformStyle = element.dataset.style;
66
66
  if (element.dataset.waveformStyle) options.waveformStyle = element.dataset.waveformStyle;
67
+ if (element.dataset.waveformGradient) options.waveformGradient = element.dataset.waveformGradient;
67
68
  setNum("barWidth");
68
69
  setNum("barSpacing");
69
70
  setNum("barRadius");
@@ -77,12 +78,6 @@
77
78
  if (element.dataset.colorPreset) options.colorPreset = element.dataset.colorPreset;
78
79
  if (element.dataset.waveformColor) options.waveformColor = parseColorValue(element.dataset.waveformColor);
79
80
  if (element.dataset.progressColor) options.progressColor = parseColorValue(element.dataset.progressColor);
80
- if (element.dataset.buttonColor) options.buttonColor = element.dataset.buttonColor;
81
- if (element.dataset.buttonHoverColor) options.buttonHoverColor = element.dataset.buttonHoverColor;
82
- if (element.dataset.textColor) options.textColor = element.dataset.textColor;
83
- if (element.dataset.textSecondaryColor) options.textSecondaryColor = element.dataset.textSecondaryColor;
84
- if (element.dataset.backgroundColor) options.backgroundColor = element.dataset.backgroundColor;
85
- if (element.dataset.borderColor) options.borderColor = element.dataset.borderColor;
86
81
  if (element.dataset.color) options.waveformColor = element.dataset.color;
87
82
  if (element.dataset.theme) options.colorPreset = element.dataset.theme;
88
83
  setBool("autoplay");
@@ -96,7 +91,7 @@
96
91
  setBool("singlePlay");
97
92
  setBool("playOnSeek");
98
93
  if (element.dataset.title) options.title = element.dataset.title;
99
- if (element.dataset.subtitle) options.subtitle = element.dataset.subtitle;
94
+ if (element.dataset.artist) options.artist = element.dataset.artist;
100
95
  if (element.dataset.album) options.album = element.dataset.album;
101
96
  if (element.dataset.artwork) options.artwork = element.dataset.artwork;
102
97
  if (element.dataset.waveform) options.waveform = element.dataset.waveform;
@@ -211,12 +206,20 @@
211
206
  }
212
207
 
213
208
  // src/js/drawing.js
214
- function makeFill(ctx, value, height) {
209
+ function makeFill(ctx, value, canvas, options) {
215
210
  if (!Array.isArray(value)) return value;
216
- if (value.length === 1) return value[0];
217
- const grad = ctx.createLinearGradient(0, 0, 0, height);
218
- value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
219
- 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
+ }
220
223
  }
221
224
  function fillBar(ctx, x, y, w, h, radii) {
222
225
  const any = Array.isArray(radii) ? radii.some((r) => r > 0) : radii > 0;
@@ -256,8 +259,8 @@
256
259
  const height = canvas.height;
257
260
  const progressWidth = progress * canvas.width;
258
261
  const radii = barRadii(options, dpr);
259
- const baseFill = makeFill(ctx, options.color, height);
260
- 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);
261
264
  ctx.clearRect(0, 0, canvas.width, canvas.height);
262
265
  ctx.fillStyle = baseFill;
263
266
  for (let i = 0; i < resampledPeaks.length; i++) {
@@ -293,8 +296,8 @@
293
296
  const r = barRadiusPx(options, dpr);
294
297
  const topRadii = [r, r, 0, 0];
295
298
  const botRadii = [0, 0, r, r];
296
- const baseFill = makeFill(ctx, options.color, height);
297
- 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);
298
301
  ctx.clearRect(0, 0, canvas.width, canvas.height);
299
302
  ctx.fillStyle = baseFill;
300
303
  for (let i = 0; i < resampledPeaks.length; i++) {
@@ -325,11 +328,13 @@
325
328
  const amplitude = height * 0.35;
326
329
  ctx.clearRect(0, 0, width, height);
327
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;
328
333
  if (addGlow) {
329
334
  ctx.shadowBlur = 12;
330
- ctx.shadowColor = color;
335
+ ctx.shadowColor = solid;
331
336
  }
332
- ctx.strokeStyle = color;
337
+ ctx.strokeStyle = stroke;
333
338
  ctx.lineWidth = lineWidth;
334
339
  ctx.lineCap = "round";
335
340
  ctx.lineJoin = "round";
@@ -385,8 +390,8 @@
385
390
  const blockGap = 2 * dpr;
386
391
  const progressWidth = progress * canvas.width;
387
392
  const centerY = height / 2;
388
- const baseFill = makeFill(ctx, options.color, height);
389
- 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);
390
395
  ctx.clearRect(0, 0, canvas.width, canvas.height);
391
396
  for (let i = 0; i < resampledPeaks.length; i++) {
392
397
  const x = i * (barWidth + barSpacing);
@@ -413,8 +418,8 @@
413
418
  const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
414
419
  const progressWidth = progress * canvas.width;
415
420
  const centerY = height / 2;
416
- const baseFill = makeFill(ctx, options.color, height);
417
- 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);
418
423
  ctx.clearRect(0, 0, canvas.width, canvas.height);
419
424
  for (let i = 0; i < resampledPeaks.length; i++) {
420
425
  const x = i * (barWidth + barSpacing) + barWidth / 2;
@@ -437,14 +442,14 @@
437
442
  const borderRadius = barHeight / 2;
438
443
  const active = !!options.seekActive;
439
444
  ctx.clearRect(0, 0, width, height);
440
- 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)";
441
446
  capsulePath(ctx, borderRadius, width, centerY, barHeight);
442
447
  ctx.fill();
443
448
  if (progress > 0) {
444
449
  const progressWidth = Math.max(borderRadius * 2, progress * width);
445
450
  ctx.save();
446
451
  ctx.globalAlpha = options.seekHandle && !active ? 0.7 : 1;
447
- ctx.fillStyle = options.progressColor || "rgba(255, 255, 255, 0.9)";
452
+ ctx.fillStyle = makeFill(ctx, options.progressColor, canvas, options) || "rgba(255, 255, 255, 0.9)";
448
453
  capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
449
454
  ctx.fill();
450
455
  ctx.restore();
@@ -628,23 +633,11 @@
628
633
  var COLOR_PRESETS = {
629
634
  dark: {
630
635
  waveformColor: "rgba(255, 255, 255, 0.3)",
631
- progressColor: "rgba(255, 255, 255, 0.9)",
632
- buttonColor: "rgba(255, 255, 255, 0.9)",
633
- buttonHoverColor: "rgba(255, 255, 255, 1)",
634
- textColor: "#ffffff",
635
- textSecondaryColor: "rgba(255, 255, 255, 0.6)",
636
- backgroundColor: "rgba(255, 255, 255, 0.03)",
637
- borderColor: "rgba(255, 255, 255, 0.1)"
636
+ progressColor: "rgba(255, 255, 255, 0.9)"
638
637
  },
639
638
  light: {
640
639
  waveformColor: "rgba(0, 0, 0, 0.2)",
641
- progressColor: "rgba(0, 0, 0, 0.8)",
642
- buttonColor: "rgba(0, 0, 0, 0.8)",
643
- buttonHoverColor: "rgba(0, 0, 0, 0.9)",
644
- textColor: "#333333",
645
- textSecondaryColor: "rgba(0, 0, 0, 0.6)",
646
- backgroundColor: "rgba(0, 0, 0, 0.02)",
647
- borderColor: "rgba(0, 0, 0, 0.1)"
640
+ progressColor: "rgba(0, 0, 0, 0.8)"
648
641
  }
649
642
  };
650
643
  function getColorPreset(presetName) {
@@ -697,17 +690,18 @@
697
690
  barSpacing: 0,
698
691
  // Rounded bar caps (px). 0 = square; 1 = soft caps (default). Applies to bars/mirror.
699
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",
700
697
  // Color preset: null = auto-detect, 'dark' = force dark, 'light' = force light
701
698
  colorPreset: null,
702
- // 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.
703
703
  waveformColor: null,
704
704
  progressColor: null,
705
- buttonColor: null,
706
- buttonHoverColor: null,
707
- textColor: null,
708
- textSecondaryColor: null,
709
- backgroundColor: null,
710
- borderColor: null,
711
705
  // Features
712
706
  autoplay: false,
713
707
  showControls: true,
@@ -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.
@@ -804,6 +798,7 @@
804
798
  const preset = getColorPreset(this.options.colorPreset);
805
799
  this._autoTheme = this.options.colorPreset == null || !COLOR_PRESETS[this.options.colorPreset];
806
800
  this._presetKeys = [];
801
+ this._scheme = this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset] ? this.options.colorPreset : detectColorScheme();
807
802
  for (const [key, value] of Object.entries(preset)) {
808
803
  if (this.options[key] === null || this.options[key] === void 0) {
809
804
  this.options[key] = value;
@@ -910,7 +905,7 @@
910
905
  *
911
906
  * Clears the container, resolves button alignment (`auto` → `bottom` for
912
907
  * the `bars` style, `center` otherwise), and conditionally renders the play
913
- * button, info row (artwork/title/subtitle), BPM badge, playback-speed
908
+ * button, info row (artwork/title/artist), BPM badge, playback-speed
914
909
  * menu, and time display based on the relevant `show*` options. Caches the
915
910
  * canvas, controls, and text elements onto `this`, then sizes the canvas.
916
911
  * @private
@@ -931,12 +926,9 @@
931
926
  if (isPreview) {
932
927
  this.container.classList.add("waveform-layout-preview");
933
928
  }
929
+ this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
934
930
  const buttonHTML = this.options.showControls ? `
935
- <button class="waveform-btn${this.options.buttonStyle === "minimal" ? " waveform-btn-minimal" : ""}" aria-label="Play/Pause" style="
936
- border-color: ${this.options.buttonColor};
937
- color: ${this.options.buttonColor};
938
- ${this.options.buttonSize != null ? `--wfp-btn-size: ${typeof this.options.buttonSize === "number" ? `${this.options.buttonSize}px` : this.options.buttonSize};` : ""}
939
- ">
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};"` : ""}>
940
932
  <span class="waveform-icon-play">${this.options.playIcon}</span>
941
933
  <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
942
934
  </button>
@@ -953,12 +945,12 @@
953
945
  ">
954
946
  ` : ""}
955
947
  <div class="waveform-text">
956
- <span class="waveform-title" style="color: ${this.options.textColor};"></span>
957
- ${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>` : ""}
958
950
  </div>
959
951
  <div class="waveform-meta" style="display: flex; align-items: center; gap: 1rem;">
960
952
  ${this.options.showBPM ? `
961
- <span class="waveform-bpm" style="color: ${this.options.textSecondaryColor}; display: none;">
953
+ <span class="waveform-bpm" style="display: none;">
962
954
  <span class="bpm-value">--</span> BPM
963
955
  </span>
964
956
  ` : ""}
@@ -975,7 +967,7 @@
975
967
  </div>
976
968
  ` : ""}
977
969
  ${this.options.showTime ? `
978
- <span class="waveform-time" style="color: ${this.options.textSecondaryColor};">
970
+ <span class="waveform-time">
979
971
  <span class="time-current">0:00</span> / <span class="time-total">0:00</span>
980
972
  </span>
981
973
  ` : ""}
@@ -1006,7 +998,7 @@
1006
998
  this.canvas = this.container.querySelector("canvas");
1007
999
  this.ctx = this.canvas.getContext("2d");
1008
1000
  this.titleEl = this.container.querySelector(".waveform-title");
1009
- this.subtitleEl = this.container.querySelector(".waveform-subtitle");
1001
+ this.artistEl = this.container.querySelector(".waveform-artist");
1010
1002
  this.artworkEl = this.container.querySelector(".waveform-artwork");
1011
1003
  if (this.artworkEl) {
1012
1004
  this.artworkEl.addEventListener("error", () => {
@@ -1281,7 +1273,7 @@
1281
1273
  if (!this.audio) return;
1282
1274
  navigator.mediaSession.metadata = new MediaMetadata({
1283
1275
  title: this.options.title || "Unknown Track",
1284
- artist: this.options.subtitle || "",
1276
+ artist: this.options.artist || "",
1285
1277
  album: this.options.album || "",
1286
1278
  artwork: this.options.artwork ? [
1287
1279
  { src: this.options.artwork, sizes: "512x512", type: "image/jpeg" }
@@ -1368,7 +1360,7 @@
1368
1360
  } catch (err) {
1369
1361
  }
1370
1362
  this._seekFromPointer(e.clientX);
1371
- if (!this._seekHover) this._hideHoverTip();
1363
+ if (!this._seekHover && !this.options.showHoverTime) this._hideHoverTip();
1372
1364
  this._updateSeekHandle();
1373
1365
  };
1374
1366
  this.canvas.addEventListener("pointerup", endDrag);
@@ -1471,19 +1463,19 @@
1471
1463
  *
1472
1464
  * Pauses any current playback, fully resets the audio element (self mode),
1473
1465
  * clears error/marker/progress state, merges the new metadata into
1474
- * `this.options`, updates the subtitle/artwork DOM, then calls
1466
+ * `this.options`, updates the artist/artwork DOM, then calls
1475
1467
  * {@link WaveformPlayer#load}. Auto-plays the new track unless
1476
1468
  * `options.autoplay === false`.
1477
1469
  * @param {string} url - Audio URL.
1478
1470
  * @param {string|null} [title=null] - Track title; keeps the existing
1479
1471
  * title when null.
1480
- * @param {string|null} [subtitle=null] - Track subtitle; pass `''` to hide
1481
- * 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.
1482
1474
  * @param {Object} [options={}] - Additional options to merge (e.g.
1483
1475
  * `preload`, `artwork`, `markers`, `autoplay`).
1484
1476
  * @returns {Promise<void>}
1485
1477
  */
1486
- async loadTrack(url, title = null, subtitle = null, options = {}) {
1478
+ async loadTrack(url, title = null, artist = null, options = {}) {
1487
1479
  if (this.isPlaying) {
1488
1480
  this.pause();
1489
1481
  }
@@ -1506,18 +1498,18 @@
1506
1498
  this.options = mergeOptions(this.options, {
1507
1499
  url,
1508
1500
  title: title || this.options.title,
1509
- subtitle: subtitle || this.options.subtitle,
1501
+ artist: artist || this.options.artist,
1510
1502
  ...options
1511
1503
  });
1512
1504
  if (options.preload && this.audio) {
1513
1505
  this.audio.preload = options.preload;
1514
1506
  }
1515
- if (this.subtitleEl) {
1516
- if (subtitle) {
1517
- this.subtitleEl.textContent = subtitle;
1518
- this.subtitleEl.style.display = "";
1519
- } else if (subtitle === "") {
1520
- 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";
1521
1513
  }
1522
1514
  }
1523
1515
  if (options.artwork && this.artworkEl) {
@@ -1700,19 +1692,20 @@
1700
1692
  }
1701
1693
  }
1702
1694
  /**
1703
- * Build a tooltip that follows the pointer over the waveform and shows the
1704
- * 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
1705
1698
  * self and external modes (it only needs {@link WaveformPlayer#getSeekDuration}).
1706
- * Uses the same pointer-X → percentage math as seeking.
1707
1699
  * @private
1708
1700
  */
1709
1701
  setupHoverTime() {
1710
- if (!this.options.showHoverTime || !this.seekEl) return;
1702
+ if (!this.seekEl) return;
1711
1703
  const tip = document.createElement("div");
1712
1704
  tip.className = "waveform-hover-time";
1713
1705
  tip.setAttribute("aria-hidden", "true");
1714
1706
  this.seekEl.appendChild(tip);
1715
1707
  this.hoverTimeEl = tip;
1708
+ if (!this.options.showHoverTime) return;
1716
1709
  this.seekEl.addEventListener("pointermove", (e) => {
1717
1710
  if (!this._dragging) this._updateHoverTip(e.clientX);
1718
1711
  });
@@ -1759,6 +1752,10 @@
1759
1752
  this.drawWaveform();
1760
1753
  this._updateSeekHandle();
1761
1754
  this._updateHoverTip(clientX);
1755
+ const dur = this.getSeekDuration();
1756
+ if (dur && this.currentTimeEl) {
1757
+ this.currentTimeEl.textContent = formatTime(this.progress * dur);
1758
+ }
1762
1759
  }
1763
1760
  /**
1764
1761
  * Create the draggable seek handle — a DOM circle over the playhead, shown
@@ -2045,33 +2042,21 @@
2045
2042
  * @public
2046
2043
  */
2047
2044
  refreshTheme() {
2048
- if (!this._autoTheme || !this._presetKeys || !this._presetKeys.length) return;
2045
+ if (!this._autoTheme) return;
2046
+ this._scheme = detectColorScheme();
2049
2047
  const preset = getColorPreset(this.options.colorPreset);
2050
- let changed = false;
2051
- for (const key of this._presetKeys) {
2052
- if (this.options[key] !== preset[key]) {
2053
- this.options[key] = preset[key];
2054
- changed = true;
2055
- }
2048
+ for (const key of this._presetKeys || []) {
2049
+ if (key in preset) this.options[key] = preset[key];
2056
2050
  }
2057
- if (changed) this._applyThemeColors();
2051
+ this._applyThemeColors();
2058
2052
  }
2059
2053
  /**
2060
- * Push the current resolved colours onto the live DOM (button border/icon,
2061
- * 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.
2062
2056
  * @private
2063
2057
  */
2064
2058
  _applyThemeColors() {
2065
- const o = this.options;
2066
- if (this.playBtn) {
2067
- this.playBtn.style.borderColor = o.buttonColor;
2068
- this.playBtn.style.color = o.buttonColor;
2069
- }
2070
- if (this.titleEl) this.titleEl.style.color = o.textColor;
2071
- if (this.subtitleEl) this.subtitleEl.style.color = o.textSecondaryColor;
2072
- this.container.querySelectorAll(".waveform-time, .waveform-bpm").forEach((el) => {
2073
- el.style.color = o.textSecondaryColor;
2074
- });
2059
+ this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
2075
2060
  if (this.canvas) this.drawWaveform();
2076
2061
  }
2077
2062
  /**
@@ -2185,16 +2170,13 @@
2185
2170
  * directly: `WaveformBar.play(event.detail)`.
2186
2171
  *
2187
2172
  * @private
2188
- * @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}}
2189
2174
  */
2190
2175
  _buildTrackDetail() {
2191
2176
  return {
2192
2177
  url: this.options.url,
2193
2178
  title: this.options.title,
2194
- subtitle: this.options.subtitle,
2195
- // Core has no separate `artist` option; mirror subtitle so the
2196
- // published event detail is self-consistent for controllers.
2197
- artist: this.options.artist || this.options.subtitle,
2179
+ artist: this.options.artist,
2198
2180
  artwork: this.options.artwork,
2199
2181
  markers: this.options.markers,
2200
2182
  waveform: this.options.waveform,