@arraypress/waveform-player 1.15.0 → 1.16.1

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.
package/index.d.ts CHANGED
@@ -76,7 +76,7 @@ export interface WaveformPlayerOptions {
76
76
  url?: string;
77
77
  /** Shorthand alias for {@link url} (`data-src`). The canonical name wins if both are set. */
78
78
  src?: string;
79
- /** Waveform height in pixels. @default 60 */
79
+ /** Waveform height in pixels. @default 64 */
80
80
  height?: number;
81
81
  /** Source peak resolution for live decode (ignored when `waveform` peaks are
82
82
  * supplied); resampled to fit the visible bars. @default 1800 */
@@ -97,7 +97,7 @@ export interface WaveformPlayerOptions {
97
97
  barWidth?: number;
98
98
  /** Gap between bars in pixels (style-dependent default). */
99
99
  barSpacing?: number;
100
- /** Rounded bar-cap radius in pixels (bars/mirror). `0` = square. @default 0 */
100
+ /** Rounded bar-cap radius in pixels (bars/mirror). `0` = square. @default 1 */
101
101
  barRadius?: number;
102
102
 
103
103
  // ── Colours ───────────────────────────────────────────────────
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.15.0",
3
+ "version": "1.16.1",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
@@ -268,6 +268,34 @@
268
268
  opacity: 1;
269
269
  }
270
270
 
271
+ /* Briefly reveal the marker's label when the playhead reaches it. The player
272
+ adds `.show-label` on activation and removes it after ~2.5s, so the label
273
+ flashes then fades while the `.active` highlight stays. Override to taste —
274
+ e.g. `.waveform-marker.active .waveform-marker-tooltip { opacity: 1 }` to keep
275
+ it on, or `{ opacity: 0 !important }` to disable. */
276
+ .waveform-marker.show-label .waveform-marker-tooltip {
277
+ opacity: 1;
278
+ }
279
+
280
+ /* Hover-time tooltip (showHoverTime) — follows the pointer over the waveform,
281
+ showing the time at that position. */
282
+ .waveform-hover-time {
283
+ position: absolute;
284
+ bottom: calc(100% + 4px);
285
+ transform: translateX(-50%);
286
+ background: rgba(0, 0, 0, 0.9);
287
+ color: #fff;
288
+ padding: 3px 7px;
289
+ border-radius: 4px;
290
+ font-size: 11px;
291
+ font-variant-numeric: tabular-nums;
292
+ white-space: nowrap;
293
+ pointer-events: none;
294
+ opacity: 0;
295
+ transition: opacity 0.15s;
296
+ z-index: 1000;
297
+ }
298
+
271
299
  /* Focus styles for accessibility */
272
300
  .waveform-btn:focus-visible {
273
301
  outline: 2px solid currentColor;
package/src/js/core.js CHANGED
@@ -18,6 +18,15 @@ import {
18
18
 
19
19
  import {DEFAULT_OPTIONS, STYLE_DEFAULTS, getColorPreset, COLOR_PRESETS} from './themes.js';
20
20
 
21
+ /**
22
+ * Placeholder shown when an artwork URL fails to load (404 / broken) — a muted
23
+ * music-note tile, so a missing cover degrades gracefully instead of showing the
24
+ * browser's broken-image icon. Inline SVG data-URI (no font / network needed).
25
+ */
26
+ const ARTWORK_FALLBACK = 'data:image/svg+xml,' + encodeURIComponent(
27
+ '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24"><rect width="24" height="24" rx="4" fill="#71717a" fill-opacity="0.15"/><g fill="none" stroke="#a1a1aa" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"><circle cx="8" cy="17" r="2.2"/><circle cx="17" cy="15" r="2.2"/><path d="M10.2 17V7l9-1.6v9"/></g></svg>'
28
+ );
29
+
21
30
  // Keyboard seek steps (seconds) for the accessible slider.
22
31
  const SEEK_STEP_SECONDS = 5;
23
32
  const SEEK_PAGE_SECONDS = 10;
@@ -106,6 +115,8 @@ export class WaveformPlayer {
106
115
  this.ctx = null;
107
116
  this.waveformData = [];
108
117
  this.progress = 0;
118
+ this._activeMarkerIndex = -1;
119
+ this._markerLabelTimer = null;
109
120
  this.isPlaying = false;
110
121
  this.isLoading = false;
111
122
  this.hasError = false;
@@ -325,6 +336,12 @@ export class WaveformPlayer {
325
336
  this.titleEl = this.container.querySelector('.waveform-title');
326
337
  this.subtitleEl = this.container.querySelector('.waveform-subtitle');
327
338
  this.artworkEl = this.container.querySelector('.waveform-artwork');
339
+ if (this.artworkEl) {
340
+ // Fall back to the placeholder tile if the cover URL fails to load.
341
+ this.artworkEl.addEventListener('error', () => {
342
+ if (!this.artworkEl.src.startsWith('data:')) this.artworkEl.src = ARTWORK_FALLBACK;
343
+ });
344
+ }
328
345
  this.currentTimeEl = this.container.querySelector('.time-current');
329
346
  this.totalTimeEl = this.container.querySelector('.time-total');
330
347
  this.bpmEl = this.container.querySelector('.waveform-bpm');
@@ -717,6 +734,9 @@ export class WaveformPlayer {
717
734
  // so the controller can position its own audio element.
718
735
  this.canvas.addEventListener('click', (e) => this.handleCanvasClick(e));
719
736
 
737
+ // Hover-time tooltip over the waveform (when showHoverTime is on).
738
+ this.setupHoverTime();
739
+
720
740
  // Window resize - store handler for cleanup
721
741
  this.resizeHandler = debounce(() => this.resizeCanvas(), 100);
722
742
  window.addEventListener('resize', this.resizeHandler);
@@ -1031,6 +1051,9 @@ export class WaveformPlayer {
1031
1051
 
1032
1052
  // Always clear existing markers first
1033
1053
  this.markersContainer.innerHTML = '';
1054
+ // Re-sync the active marker on the next progress tick (the DOM was wiped).
1055
+ this._activeMarkerIndex = -1;
1056
+ clearTimeout(this._markerLabelTimer);
1034
1057
 
1035
1058
  if (!this.options.showMarkers || !this.options.markers?.length) return;
1036
1059
 
@@ -1090,6 +1113,73 @@ export class WaveformPlayer {
1090
1113
  markers.forEach((el, i) => el.classList.toggle('active', i === index));
1091
1114
  }
1092
1115
 
1116
+ /**
1117
+ * Highlight the marker the playhead has most recently passed — the rendered
1118
+ * marker with the greatest `time` ≤ the current time — and reveal its label.
1119
+ * Driven from the progress loop; a no-op when there are no markers. Reuses
1120
+ * {@link WaveformPlayer#setActiveMarker}, and only re-applies when the active
1121
+ * marker actually changes.
1122
+ * @private
1123
+ */
1124
+ updateActiveMarker() {
1125
+ if (!this.markersContainer) return;
1126
+ const els = this.markersContainer.querySelectorAll('.waveform-marker');
1127
+ if (!els.length) return;
1128
+ const dur = this.getSeekDuration();
1129
+ const t = dur ? this.progress * dur : 0;
1130
+ let active = -1;
1131
+ let best = -Infinity;
1132
+ els.forEach((el, i) => {
1133
+ const mt = parseFloat(el.getAttribute('data-time'));
1134
+ if (Number.isFinite(mt) && mt <= t + 0.05 && mt > best) {
1135
+ best = mt;
1136
+ active = i;
1137
+ }
1138
+ });
1139
+ if (active !== this._activeMarkerIndex) {
1140
+ this._activeMarkerIndex = active;
1141
+ this.setActiveMarker(active);
1142
+ // Flash the newly-active marker's label, then let it fade — the
1143
+ // highlight stays. Override via `.waveform-marker.show-label` CSS.
1144
+ clearTimeout(this._markerLabelTimer);
1145
+ els.forEach((el, i) => el.classList.toggle('show-label', i === active));
1146
+ if (active >= 0) {
1147
+ this._markerLabelTimer = setTimeout(() => {
1148
+ this.markersContainer
1149
+ ?.querySelectorAll('.waveform-marker')
1150
+ .forEach((el) => el.classList.remove('show-label'));
1151
+ }, 2500);
1152
+ }
1153
+ }
1154
+ }
1155
+
1156
+ /**
1157
+ * Build a tooltip that follows the pointer over the waveform and shows the
1158
+ * time at that position. Enabled by the `showHoverTime` option; works in both
1159
+ * self and external modes (it only needs {@link WaveformPlayer#getSeekDuration}).
1160
+ * Uses the same pointer-X → percentage math as seeking.
1161
+ * @private
1162
+ */
1163
+ setupHoverTime() {
1164
+ if (!this.options.showHoverTime || !this.seekEl) return;
1165
+ const tip = document.createElement('div');
1166
+ tip.className = 'waveform-hover-time';
1167
+ tip.setAttribute('aria-hidden', 'true');
1168
+ this.seekEl.appendChild(tip);
1169
+ this.hoverTimeEl = tip;
1170
+
1171
+ this.seekEl.addEventListener('pointermove', (e) => {
1172
+ const dur = this.getSeekDuration();
1173
+ if (!dur) { tip.style.opacity = '0'; return; }
1174
+ const rect = this.canvas.getBoundingClientRect();
1175
+ const pct = clamp((e.clientX - rect.left) / rect.width);
1176
+ tip.textContent = formatTime(pct * dur);
1177
+ tip.style.left = (pct * 100) + '%';
1178
+ tip.style.opacity = '1';
1179
+ });
1180
+ this.seekEl.addEventListener('pointerleave', () => { tip.style.opacity = '0'; });
1181
+ }
1182
+
1093
1183
  // ============================================
1094
1184
  // Event Handlers
1095
1185
  // ============================================
@@ -1377,6 +1467,7 @@ export class WaveformPlayer {
1377
1467
  this.options.onTimeUpdate(this.audio.currentTime, this.audio.duration, this);
1378
1468
  }
1379
1469
 
1470
+ this.updateActiveMarker();
1380
1471
  this.updateSeekAccessibility();
1381
1472
  }
1382
1473
 
@@ -1639,6 +1730,7 @@ export class WaveformPlayer {
1639
1730
  this.totalTimeEl.dataset._extDur = String(duration);
1640
1731
  }
1641
1732
  this.drawWaveform?.();
1733
+ this.updateActiveMarker();
1642
1734
  this._emit('waveformplayer:timeupdate', {player: this, currentTime, duration, progress: this.progress, url: this.options.url});
1643
1735
  // Same (currentTime, duration, player) signature as self mode — the
1644
1736
  // arg order used to be swapped here, which made one shared handler
@@ -1752,6 +1844,7 @@ export class WaveformPlayer {
1752
1844
  // Stop playback and animations
1753
1845
  this.pause();
1754
1846
  this.stopSmoothUpdate();
1847
+ clearTimeout(this._markerLabelTimer);
1755
1848
 
1756
1849
  // Tear down every document/container/seek listener in one shot.
1757
1850
  this._ac?.abort();