@arraypress/waveform-player 1.17.0 → 1.19.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.
package/index.d.ts CHANGED
@@ -99,6 +99,8 @@ export interface WaveformPlayerOptions {
99
99
  barSpacing?: number;
100
100
  /** Rounded bar-cap radius in pixels (bars/mirror). `0` = square. @default 1 */
101
101
  barRadius?: number;
102
+ /** Gradient axis when waveformColor/progressColor is an array of stops. @default 'vertical' */
103
+ waveformGradient?: 'vertical' | 'horizontal' | 'diagonal';
102
104
 
103
105
  // ── Colours ───────────────────────────────────────────────────
104
106
  /** Force a colour preset, or `null` to auto-detect. @default null */
@@ -110,12 +112,8 @@ export interface WaveformPlayerOptions {
110
112
  waveformColor?: string | string[] | null;
111
113
  /** Played-through colour. Also accepts an array of stops for a gradient. */
112
114
  progressColor?: string | string[] | null;
113
- buttonColor?: string | null;
114
- buttonHoverColor?: string | null;
115
- textColor?: string | null;
116
- textSecondaryColor?: string | null;
117
- backgroundColor?: string | null;
118
- borderColor?: string | null;
115
+ // DOM chrome colours are CSS variables now (--wfp-button-color,
116
+ // --wfp-text-color, --wfp-text-secondary-color), not options.
119
117
 
120
118
  // ── Playback ──────────────────────────────────────────────────
121
119
  /** Initial playback rate. @default 1 */
@@ -149,7 +147,7 @@ export interface WaveformPlayerOptions {
149
147
  buttonSize?: number | string | null;
150
148
  /** Show transport controls. @default true */
151
149
  showControls?: boolean;
152
- /** Show the info (title/subtitle) block. @default true */
150
+ /** Show the info (title/artist) block. @default true */
153
151
  showInfo?: boolean;
154
152
  /** Show current/total time. @default true */
155
153
  showTime?: boolean;
@@ -186,7 +184,7 @@ export interface WaveformPlayerOptions {
186
184
 
187
185
  // ── Content metadata ──────────────────────────────────────────
188
186
  title?: string | null;
189
- subtitle?: string | null;
187
+ artist?: string | null;
190
188
  artwork?: string | null;
191
189
  album?: string;
192
190
  /** Message shown when audio fails to load. @default 'Unable to load audio' */
@@ -203,6 +201,10 @@ export interface WaveformPlayerOptions {
203
201
  onEnd?: WaveformPlayerHandler | null;
204
202
  onError?: WaveformErrorHandler | null;
205
203
  onTimeUpdate?: WaveformTimeUpdateHandler | null;
204
+ /** Called when the Media Session "next track" control is used. Registering it shows the lock-screen skip-forward button. */
205
+ onNextTrack?: WaveformPlayerHandler | null;
206
+ /** Called when the Media Session "previous track" control is used. */
207
+ onPreviousTrack?: WaveformPlayerHandler | null;
206
208
  }
207
209
 
208
210
  /** `detail` of `waveformplayer:play | pause | ready | destroy`. */
@@ -231,8 +233,7 @@ export interface WaveformTimeUpdateEventDetail {
231
233
  export interface WaveformTrackDetail {
232
234
  url: string;
233
235
  title: string | null;
234
- subtitle: string | null;
235
- artist?: string;
236
+ artist: string | null;
236
237
  artwork: string | null;
237
238
  /** Chapter markers for the track (forwarded so controllers don't re-fetch). */
238
239
  markers?: WaveformMarker[];
@@ -303,7 +304,7 @@ export declare class WaveformPlayer {
303
304
  /** Load (or replace) the audio URL and regenerate the waveform. */
304
305
  load(url: string): Promise<void>;
305
306
  /** Load a new track without re-instantiating; updates metadata then plays. */
306
- loadTrack(url: string, title?: string | null, subtitle?: string | null, options?: WaveformPlayerOptions): Promise<void>;
307
+ loadTrack(url: string, title?: string | null, artist?: string | null, options?: WaveformPlayerOptions): Promise<void>;
307
308
  /** Seek to an absolute time in seconds (self mode). */
308
309
  seekTo(seconds: number): void;
309
310
  /** Seek to a fraction of total duration, 0..1 (self mode). */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.17.0",
3
+ "version": "1.19.0",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
@@ -6,6 +6,20 @@
6
6
  /* Neutral accent for the keyboard-focus ring + active states. Monochrome
7
7
  by default (shadcn-style); override this variable to re-tint it. */
8
8
  --wfp-accent: #71717a;
9
+
10
+ /* DOM chrome colours (dark defaults). Override any of these to re-theme the
11
+ button/text without touching JS. Canvas colours stay JS options. */
12
+ --wfp-button-color: rgba(255, 255, 255, 0.9);
13
+ --wfp-text-color: #ffffff;
14
+ --wfp-text-secondary-color: rgba(255, 255, 255, 0.6);
15
+ }
16
+
17
+ /* Light theme — the player adds .waveform-theme-light when it detects a light
18
+ page (or with colorPreset: 'light'). */
19
+ .waveform-player.waveform-theme-light {
20
+ --wfp-button-color: rgba(0, 0, 0, 0.8);
21
+ --wfp-text-color: #333333;
22
+ --wfp-text-secondary-color: rgba(0, 0, 0, 0.6);
9
23
  }
10
24
 
11
25
  .waveform-player * {
@@ -39,7 +53,7 @@
39
53
  border-radius: 50%;
40
54
  border: 2px solid currentColor;
41
55
  background: transparent;
42
- color: inherit;
56
+ color: var(--wfp-button-color, inherit);
43
57
  cursor: pointer;
44
58
  display: flex;
45
59
  align-items: center;
@@ -154,13 +168,15 @@
154
168
  }
155
169
 
156
170
  .waveform-title {
171
+ color: var(--wfp-text-color);
157
172
  white-space: nowrap;
158
173
  overflow: hidden;
159
174
  text-overflow: ellipsis;
160
175
  font-weight: 500;
161
176
  }
162
177
 
163
- .waveform-subtitle {
178
+ .waveform-artist {
179
+ color: var(--wfp-text-secondary-color);
164
180
  font-size: 11px;
165
181
  white-space: nowrap;
166
182
  overflow: hidden;
@@ -168,6 +184,7 @@
168
184
  }
169
185
 
170
186
  .waveform-time {
187
+ color: var(--wfp-text-secondary-color);
171
188
  font-size: 11px;
172
189
  white-space: nowrap;
173
190
  flex-shrink: 0;
@@ -175,6 +192,7 @@
175
192
 
176
193
  /* BPM display */
177
194
  .waveform-bpm {
195
+ color: var(--wfp-text-secondary-color);
178
196
  font-size: 11px;
179
197
  white-space: nowrap;
180
198
  flex-shrink: 0;
@@ -476,7 +494,7 @@
476
494
  font-size: 12px;
477
495
  }
478
496
 
479
- .waveform-subtitle,
497
+ .waveform-artist,
480
498
  .waveform-time,
481
499
  .waveform-bpm {
482
500
  font-size: 10px;
package/src/js/core.js CHANGED
@@ -17,7 +17,7 @@ import {
17
17
  DEFAULT_SAMPLES
18
18
  } from './utils.js';
19
19
 
20
- import {DEFAULT_OPTIONS, STYLE_DEFAULTS, getColorPreset, COLOR_PRESETS} from './themes.js';
20
+ import {DEFAULT_OPTIONS, STYLE_DEFAULTS, getColorPreset, COLOR_PRESETS, detectColorScheme} from './themes.js';
21
21
 
22
22
  /**
23
23
  * Placeholder shown when an artwork URL fails to load (404 / broken) — a muted
@@ -96,6 +96,9 @@ export class WaveformPlayer {
96
96
  // explicit colorPreset or hand-set colour is never overridden.
97
97
  this._autoTheme = this.options.colorPreset == null || !COLOR_PRESETS[this.options.colorPreset];
98
98
  this._presetKeys = [];
99
+ // Resolved scheme name for the CSS theme class (CSS provides the DOM
100
+ // chrome colours via --wfp-* variables).
101
+ this._scheme = (this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset]) ? this.options.colorPreset : detectColorScheme();
99
102
 
100
103
  // Apply preset colors only if individual colors aren't explicitly set
101
104
  for (const [key, value] of Object.entries(preset)) {
@@ -230,7 +233,7 @@ export class WaveformPlayer {
230
233
  *
231
234
  * Clears the container, resolves button alignment (`auto` → `bottom` for
232
235
  * the `bars` style, `center` otherwise), and conditionally renders the play
233
- * button, info row (artwork/title/subtitle), BPM badge, playback-speed
236
+ * button, info row (artwork/title/artist), BPM badge, playback-speed
234
237
  * menu, and time display based on the relevant `show*` options. Caches the
235
238
  * canvas, controls, and text elements onto `this`, then sizes the canvas.
236
239
  * @private
@@ -258,14 +261,11 @@ export class WaveformPlayer {
258
261
  if (isPreview) {
259
262
  this.container.classList.add('waveform-layout-preview');
260
263
  }
264
+ this.container.classList.toggle('waveform-theme-light', this._scheme === 'light');
261
265
 
262
266
  // Build play button HTML (conditional)
263
267
  const buttonHTML = this.options.showControls ? `
264
- <button class="waveform-btn${this.options.buttonStyle === 'minimal' ? ' waveform-btn-minimal' : ''}" aria-label="Play/Pause" style="
265
- border-color: ${this.options.buttonColor};
266
- color: ${this.options.buttonColor};
267
- ${this.options.buttonSize != null ? `--wfp-btn-size: ${typeof this.options.buttonSize === 'number' ? `${this.options.buttonSize}px` : this.options.buttonSize};` : ''}
268
- ">
268
+ <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};"` : ''}>
269
269
  <span class="waveform-icon-play">${this.options.playIcon}</span>
270
270
  <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
271
271
  </button>
@@ -284,12 +284,12 @@ export class WaveformPlayer {
284
284
  ">
285
285
  ` : ''}
286
286
  <div class="waveform-text">
287
- <span class="waveform-title" style="color: ${this.options.textColor};"></span>
288
- ${this.options.subtitle ? `<span class="waveform-subtitle" style="color: ${this.options.textSecondaryColor};">${this.options.subtitle}</span>` : ''}
287
+ <span class="waveform-title"></span>
288
+ ${this.options.artist ? `<span class="waveform-artist">${this.options.artist}</span>` : ''}
289
289
  </div>
290
290
  <div class="waveform-meta" style="display: flex; align-items: center; gap: 1rem;">
291
291
  ${this.options.showBPM ? `
292
- <span class="waveform-bpm" style="color: ${this.options.textSecondaryColor}; display: none;">
292
+ <span class="waveform-bpm" style="display: none;">
293
293
  <span class="bpm-value">--</span> BPM
294
294
  </span>
295
295
  ` : ''}
@@ -306,7 +306,7 @@ export class WaveformPlayer {
306
306
  </div>
307
307
  ` : ''}
308
308
  ${this.options.showTime ? `
309
- <span class="waveform-time" style="color: ${this.options.textSecondaryColor};">
309
+ <span class="waveform-time">
310
310
  <span class="time-current">0:00</span> / <span class="time-total">0:00</span>
311
311
  </span>
312
312
  ` : ''}
@@ -341,7 +341,7 @@ export class WaveformPlayer {
341
341
  this.canvas = this.container.querySelector('canvas');
342
342
  this.ctx = this.canvas.getContext('2d');
343
343
  this.titleEl = this.container.querySelector('.waveform-title');
344
- this.subtitleEl = this.container.querySelector('.waveform-subtitle');
344
+ this.artistEl = this.container.querySelector('.waveform-artist');
345
345
  this.artworkEl = this.container.querySelector('.waveform-artwork');
346
346
  if (this.artworkEl) {
347
347
  // Fall back to the placeholder tile if the cover URL fails to load.
@@ -561,6 +561,17 @@ export class WaveformPlayer {
561
561
  this.updateSeekAccessibility();
562
562
 
563
563
  this.seekEl.addEventListener('keydown', (e) => {
564
+ // Space toggles play/pause even while the waveform slider is focused —
565
+ // it's a media control, so play/pause should work here too, not only
566
+ // when the player root is the active element (restores the pre-a11y
567
+ // Space path reported in #10).
568
+ if (e.key === ' ' || e.key === 'Spacebar') {
569
+ e.preventDefault();
570
+ e.stopPropagation();
571
+ this.togglePlay();
572
+ return;
573
+ }
574
+
564
575
  const duration = this.getSeekDuration();
565
576
  if (!duration) return;
566
577
 
@@ -698,15 +709,7 @@ export class WaveformPlayer {
698
709
  // Session handlers; ours would conflict with its.
699
710
  if (!this.audio) return;
700
711
 
701
- // Set metadata
702
- navigator.mediaSession.metadata = new MediaMetadata({
703
- title: this.options.title || 'Unknown Track',
704
- artist: this.options.subtitle || '',
705
- album: this.options.album || '',
706
- artwork: this.options.artwork ? [
707
- {src: this.options.artwork, sizes: '512x512', type: 'image/jpeg'}
708
- ] : []
709
- });
712
+ this._applyMediaMetadata();
710
713
 
711
714
  // Set up action handlers
712
715
  navigator.mediaSession.setActionHandler('play', () => this.play());
@@ -722,6 +725,53 @@ export class WaveformPlayer {
722
725
  this.seekTo(details.seekTime);
723
726
  }
724
727
  });
728
+
729
+ // Optional queue navigation — lights up the lock-screen skip-track
730
+ // buttons. Registered only when a host (bar / playlist) supplies a
731
+ // callback; a null handler hides the button.
732
+ const onNext = this.options.onNextTrack, onPrev = this.options.onPreviousTrack;
733
+ try { navigator.mediaSession.setActionHandler('nexttrack', typeof onNext === 'function' ? () => onNext(this) : null); } catch (e) { /* unsupported */ }
734
+ try { navigator.mediaSession.setActionHandler('previoustrack', typeof onPrev === 'function' ? () => onPrev(this) : null); } catch (e) { /* unsupported */ }
735
+ }
736
+
737
+ /**
738
+ * Publish the current track's Media Session metadata (lock-screen /
739
+ * Now-Playing title, artist, album, artwork). Idempotent — safe to re-call.
740
+ * @private
741
+ */
742
+ _applyMediaMetadata() {
743
+ if (!('mediaSession' in navigator) || !this.options.enableMediaSession) return;
744
+ navigator.mediaSession.metadata = new MediaMetadata({
745
+ title: this.options.title || 'Unknown Track',
746
+ artist: this.options.artist || '',
747
+ album: this.options.album || '',
748
+ artwork: this.options.artwork ? [
749
+ {src: this.options.artwork, sizes: '512x512', type: 'image/jpeg'}
750
+ ] : []
751
+ });
752
+ }
753
+
754
+ /**
755
+ * Sync Media Session playback state + scrubber position on play/pause. iOS
756
+ * ignores metadata set before the media is active, so we re-assert it on
757
+ * play — that's what fixes the blank lock-screen card on mobile.
758
+ * @param {'playing'|'paused'} state
759
+ * @private
760
+ */
761
+ _updateMediaSession(state) {
762
+ if (!('mediaSession' in navigator) || !this.options.enableMediaSession || !this.audio) return;
763
+ try {
764
+ if (state === 'playing') this._applyMediaMetadata();
765
+ navigator.mediaSession.playbackState = state;
766
+ const d = this.audio.duration;
767
+ if (navigator.mediaSession.setPositionState && d && isFinite(d)) {
768
+ navigator.mediaSession.setPositionState({
769
+ duration: d,
770
+ playbackRate: this.audio.playbackRate || 1,
771
+ position: clamp(this.audio.currentTime, 0, d),
772
+ });
773
+ }
774
+ } catch (e) { /* Media Session is best-effort */ }
725
775
  }
726
776
 
727
777
  // ============================================
@@ -809,9 +859,15 @@ export class WaveformPlayer {
809
859
  const endDrag = (e) => {
810
860
  if (!this._dragging) return;
811
861
  this._dragging = false;
862
+ // The browser fires a click after pointerup on a tap/short drag —
863
+ // flag it so handleCanvasClick ignores it (a second seek from the
864
+ // synthetic click's coordinate can snap the playhead, e.g. to 0).
865
+ this._suppressClick = true;
812
866
  try { this.canvas.releasePointerCapture(e.pointerId); } catch (err) { /* ignore */ }
813
867
  this._seekFromPointer(e.clientX); // commit the seek now — audio jumps once
814
- if (!this._seekHover) this._hideHoverTip();
868
+ // Hide the drag tooltip on release, unless hover-time keeps it (or
869
+ // the seekbar handle is being hovered), to avoid a hide/show flicker.
870
+ if (!this._seekHover && !this.options.showHoverTime) this._hideHoverTip();
815
871
  this._updateSeekHandle();
816
872
  };
817
873
  this.canvas.addEventListener('pointerup', endDrag);
@@ -945,19 +1001,19 @@ export class WaveformPlayer {
945
1001
  *
946
1002
  * Pauses any current playback, fully resets the audio element (self mode),
947
1003
  * clears error/marker/progress state, merges the new metadata into
948
- * `this.options`, updates the subtitle/artwork DOM, then calls
1004
+ * `this.options`, updates the artist/artwork DOM, then calls
949
1005
  * {@link WaveformPlayer#load}. Auto-plays the new track unless
950
1006
  * `options.autoplay === false`.
951
1007
  * @param {string} url - Audio URL.
952
1008
  * @param {string|null} [title=null] - Track title; keeps the existing
953
1009
  * title when null.
954
- * @param {string|null} [subtitle=null] - Track subtitle; pass `''` to hide
955
- * the subtitle row, or null to keep the existing one.
1010
+ * @param {string|null} [artist=null] - Track artist; pass `''` to hide
1011
+ * the artist row, or null to keep the existing one.
956
1012
  * @param {Object} [options={}] - Additional options to merge (e.g.
957
1013
  * `preload`, `artwork`, `markers`, `autoplay`).
958
1014
  * @returns {Promise<void>}
959
1015
  */
960
- async loadTrack(url, title = null, subtitle = null, options = {}) {
1016
+ async loadTrack(url, title = null, artist = null, options = {}) {
961
1017
  // Stop current playback and clear state
962
1018
  if (this.isPlaying) {
963
1019
  this.pause();
@@ -989,7 +1045,7 @@ export class WaveformPlayer {
989
1045
  this.options = mergeOptions(this.options, {
990
1046
  url,
991
1047
  title: title || this.options.title,
992
- subtitle: subtitle || this.options.subtitle,
1048
+ artist: artist || this.options.artist,
993
1049
  ...options
994
1050
  });
995
1051
 
@@ -999,12 +1055,12 @@ export class WaveformPlayer {
999
1055
  }
1000
1056
 
1001
1057
  // Update UI elements
1002
- if (this.subtitleEl) {
1003
- if (subtitle) {
1004
- this.subtitleEl.textContent = subtitle;
1005
- this.subtitleEl.style.display = '';
1006
- } else if (subtitle === '') {
1007
- this.subtitleEl.style.display = 'none';
1058
+ if (this.artistEl) {
1059
+ if (artist) {
1060
+ this.artistEl.textContent = artist;
1061
+ this.artistEl.style.display = '';
1062
+ } else if (artist === '') {
1063
+ this.artistEl.style.display = 'none';
1008
1064
  }
1009
1065
  }
1010
1066
 
@@ -1240,20 +1296,23 @@ export class WaveformPlayer {
1240
1296
  }
1241
1297
 
1242
1298
  /**
1243
- * Build a tooltip that follows the pointer over the waveform and shows the
1244
- * time at that position. Enabled by the `showHoverTime` option; works in both
1299
+ * Build the time tooltip that follows the pointer over the waveform. The
1300
+ * element is always created so **drag-scrub** can show the time you're
1301
+ * dragging to; the *hover* reveal is gated on `showHoverTime`. Works in both
1245
1302
  * self and external modes (it only needs {@link WaveformPlayer#getSeekDuration}).
1246
- * Uses the same pointer-X → percentage math as seeking.
1247
1303
  * @private
1248
1304
  */
1249
1305
  setupHoverTime() {
1250
- if (!this.options.showHoverTime || !this.seekEl) return;
1306
+ if (!this.seekEl) return;
1251
1307
  const tip = document.createElement('div');
1252
1308
  tip.className = 'waveform-hover-time';
1253
1309
  tip.setAttribute('aria-hidden', 'true');
1254
1310
  this.seekEl.appendChild(tip);
1255
1311
  this.hoverTimeEl = tip;
1256
1312
 
1313
+ // Without showHoverTime the tip is drag-only — no hover listeners.
1314
+ if (!this.options.showHoverTime) return;
1315
+
1257
1316
  // Hover updates the tip; the drag handlers also call _updateHoverTip so
1258
1317
  // the time follows the playhead while scrubbing (Spotify-style). The
1259
1318
  // guard avoids a double-update when a drag is in progress (the canvas
@@ -1304,6 +1363,12 @@ export class WaveformPlayer {
1304
1363
  this.drawWaveform();
1305
1364
  this._updateSeekHandle();
1306
1365
  this._updateHoverTip(clientX);
1366
+ // Live time readout while scrubbing (Spotify-style): the audio keeps
1367
+ // playing at its old position; the display shows where release lands.
1368
+ const dur = this.getSeekDuration();
1369
+ if (dur && this.currentTimeEl) {
1370
+ this.currentTimeEl.textContent = formatTime(this.progress * dur);
1371
+ }
1307
1372
  }
1308
1373
 
1309
1374
  /**
@@ -1353,6 +1418,8 @@ export class WaveformPlayer {
1353
1418
  * @fires WaveformPlayer#waveformplayer:request-seek
1354
1419
  */
1355
1420
  handleCanvasClick(event) {
1421
+ // Ignore the synthetic click that trails a pointer drag (see endDrag).
1422
+ if (this._suppressClick) { this._suppressClick = false; return; }
1356
1423
  this._seekFromPointer(event.clientX);
1357
1424
  }
1358
1425
 
@@ -1453,6 +1520,10 @@ export class WaveformPlayer {
1453
1520
 
1454
1521
  this.startSmoothUpdate();
1455
1522
 
1523
+ // iOS drops Media Session metadata set before playback begins — re-assert
1524
+ // metadata + playback state now that we're actually playing.
1525
+ this._updateMediaSession('playing');
1526
+
1456
1527
  // Dispatch play event
1457
1528
  this._emit('waveformplayer:play', {player: this, url: this.options.url});
1458
1529
 
@@ -1479,6 +1550,8 @@ export class WaveformPlayer {
1479
1550
 
1480
1551
  this.stopSmoothUpdate();
1481
1552
 
1553
+ this._updateMediaSession('paused');
1554
+
1482
1555
  // Dispatch pause event
1483
1556
  this._emit('waveformplayer:pause', {player: this, url: this.options.url});
1484
1557
 
@@ -1667,34 +1740,22 @@ export class WaveformPlayer {
1667
1740
  * @public
1668
1741
  */
1669
1742
  refreshTheme() {
1670
- if (!this._autoTheme || !this._presetKeys || !this._presetKeys.length) return;
1743
+ if (!this._autoTheme) return;
1744
+ this._scheme = detectColorScheme();
1671
1745
  const preset = getColorPreset(this.options.colorPreset);
1672
- let changed = false;
1673
- for (const key of this._presetKeys) {
1674
- if (this.options[key] !== preset[key]) {
1675
- this.options[key] = preset[key];
1676
- changed = true;
1677
- }
1746
+ for (const key of (this._presetKeys || [])) {
1747
+ if (key in preset) this.options[key] = preset[key];
1678
1748
  }
1679
- if (changed) this._applyThemeColors();
1749
+ this._applyThemeColors();
1680
1750
  }
1681
1751
 
1682
1752
  /**
1683
- * Push the current resolved colours onto the live DOM (button border/icon,
1684
- * title, subtitle, time, BPM) and redraw the waveform.
1753
+ * Sync the theme class (CSS drives the DOM chrome colours via `--wfp-*`
1754
+ * variables) and redraw the canvas with the resolved waveform colours.
1685
1755
  * @private
1686
1756
  */
1687
1757
  _applyThemeColors() {
1688
- const o = this.options;
1689
- if (this.playBtn) {
1690
- this.playBtn.style.borderColor = o.buttonColor;
1691
- this.playBtn.style.color = o.buttonColor;
1692
- }
1693
- if (this.titleEl) this.titleEl.style.color = o.textColor;
1694
- if (this.subtitleEl) this.subtitleEl.style.color = o.textSecondaryColor;
1695
- this.container.querySelectorAll('.waveform-time, .waveform-bpm').forEach((el) => {
1696
- el.style.color = o.textSecondaryColor;
1697
- });
1758
+ this.container.classList.toggle('waveform-theme-light', this._scheme === 'light');
1698
1759
  if (this.canvas) this.drawWaveform();
1699
1760
  }
1700
1761
 
@@ -1820,16 +1881,13 @@ export class WaveformPlayer {
1820
1881
  * directly: `WaveformBar.play(event.detail)`.
1821
1882
  *
1822
1883
  * @private
1823
- * @return {{url:string,title:?string,subtitle:?string,artist:?string,artwork:?string,player:WaveformPlayer}}
1884
+ * @return {{url:string,title:?string,artist:?string,artwork:?string,player:WaveformPlayer}}
1824
1885
  */
1825
1886
  _buildTrackDetail() {
1826
1887
  return {
1827
1888
  url: this.options.url,
1828
1889
  title: this.options.title,
1829
- subtitle: this.options.subtitle,
1830
- // Core has no separate `artist` option; mirror subtitle so the
1831
- // published event detail is self-consistent for controllers.
1832
- artist: this.options.artist || this.options.subtitle,
1890
+ artist: this.options.artist,
1833
1891
  artwork: this.options.artwork,
1834
1892
  markers: this.options.markers,
1835
1893
  waveform: this.options.waveform,
package/src/js/drawing.js CHANGED
@@ -7,22 +7,38 @@ import {resampleData, clamp} from './utils.js';
7
7
 
8
8
  /**
9
9
  * Resolve a fill value that may be a CSS colour string OR an array of colour
10
- * stops (rendered as a vertical canvas gradient). Bundle-light gradient
11
- * support: pass e.g. `waveformColor: ['#fafafa', '#71717a']`.
12
- * A single-element array collapses to that one colour; a multi-element array
13
- * is spread evenly from top (y=0) to bottom (y=height).
10
+ * stops (rendered as a canvas gradient). Bundle-light gradient support: pass
11
+ * e.g. `waveformColor: ['#fafafa', '#71717a']`. A single-element array collapses
12
+ * to that one colour; a multi-element array is spread evenly along the axis set
13
+ * by `options.waveformGradient`:
14
+ * - `'vertical'` (default) a canvas-height gradient (colour keyed to
15
+ * absolute Y, so short bars occupy only the lower band).
16
+ * - `'horizontal'` left -> right across the whole waveform (a hue sweep).
17
+ * - `'diagonal'` top-left -> bottom-right.
14
18
  * @private
15
19
  * @param {CanvasRenderingContext2D} ctx - Canvas context used to build the gradient.
16
20
  * @param {string|string[]} value - A CSS colour string, or an array of colour stops.
17
- * @param {number} height - Canvas height in device pixels (gradient span).
18
- * @returns {string|CanvasGradient} The original string, or a vertical linear gradient.
21
+ * @param {HTMLCanvasElement} canvas - Canvas (provides the device-pixel span).
22
+ * @param {Object} [options] - Drawing options; reads `waveformGradient`.
23
+ * @returns {string|CanvasGradient} The original string, or a linear gradient.
19
24
  */
20
- function makeFill(ctx, value, height) {
25
+ function makeFill(ctx, value, canvas, options) {
21
26
  if (!Array.isArray(value)) return value;
22
- if (value.length === 1) return value[0];
23
- const grad = ctx.createLinearGradient(0, 0, 0, height);
24
- value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
25
- return grad;
27
+ if (value.length < 2) return value[0];
28
+ const w = canvas.width;
29
+ const h = canvas.height;
30
+ const dir = options && options.waveformGradient;
31
+ const [x0, y0, x1, y1] =
32
+ dir === 'horizontal' ? [0, 0, w, 0] :
33
+ dir === 'diagonal' ? [0, 0, w, h] :
34
+ [0, 0, 0, h];
35
+ try {
36
+ const grad = ctx.createLinearGradient(x0, y0, x1, y1);
37
+ value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
38
+ return grad;
39
+ } catch (e) {
40
+ return value[0]; // a bad stop shouldn't abort the whole render
41
+ }
26
42
  }
27
43
 
28
44
  /**
@@ -120,8 +136,8 @@ export function drawBars(ctx, canvas, peaks, progress, options) {
120
136
  const height = canvas.height;
121
137
  const progressWidth = progress * canvas.width;
122
138
  const radii = barRadii(options, dpr);
123
- const baseFill = makeFill(ctx, options.color, height);
124
- const progFill = makeFill(ctx, options.progressColor, height);
139
+ const baseFill = makeFill(ctx, options.color, canvas, options);
140
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
125
141
 
126
142
  ctx.clearRect(0, 0, canvas.width, canvas.height);
127
143
 
@@ -184,8 +200,8 @@ export function drawMirror(ctx, canvas, peaks, progress, options) {
184
200
  const r = barRadiusPx(options, dpr);
185
201
  const topRadii = [r, r, 0, 0]; // round the upper cap
186
202
  const botRadii = [0, 0, r, r]; // round the lower cap
187
- const baseFill = makeFill(ctx, options.color, height);
188
- const progFill = makeFill(ctx, options.progressColor, height);
203
+ const baseFill = makeFill(ctx, options.color, canvas, options);
204
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
189
205
 
190
206
  ctx.clearRect(0, 0, canvas.width, canvas.height);
191
207
 
@@ -252,12 +268,16 @@ export function drawLine(ctx, canvas, peaks, progress, options) {
252
268
  * @returns {void}
253
269
  */
254
270
  const drawCurve = (color, lineWidth, endProgress = 1, addGlow = false) => {
271
+ // strokeStyle accepts a gradient; shadowColor must be a solid string, so
272
+ // collapse a stop array to its last stop for the glow.
273
+ const stroke = makeFill(ctx, color, canvas, options);
274
+ const solid = Array.isArray(color) ? color[color.length - 1] : color;
255
275
  if (addGlow) {
256
276
  ctx.shadowBlur = 12;
257
- ctx.shadowColor = color;
277
+ ctx.shadowColor = solid;
258
278
  }
259
279
 
260
- ctx.strokeStyle = color;
280
+ ctx.strokeStyle = stroke;
261
281
  ctx.lineWidth = lineWidth;
262
282
  ctx.lineCap = 'round';
263
283
  ctx.lineJoin = 'round';
@@ -350,8 +370,8 @@ export function drawBlocks(ctx, canvas, peaks, progress, options) {
350
370
  const blockGap = 2 * dpr;
351
371
  const progressWidth = progress * canvas.width;
352
372
  const centerY = height / 2;
353
- const baseFill = makeFill(ctx, options.color, height);
354
- const progFill = makeFill(ctx, options.progressColor, height);
373
+ const baseFill = makeFill(ctx, options.color, canvas, options);
374
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
355
375
 
356
376
  ctx.clearRect(0, 0, canvas.width, canvas.height);
357
377
 
@@ -402,8 +422,8 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
402
422
  const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
403
423
  const progressWidth = progress * canvas.width;
404
424
  const centerY = height / 2;
405
- const baseFill = makeFill(ctx, options.color, height);
406
- const progFill = makeFill(ctx, options.progressColor, height);
425
+ const baseFill = makeFill(ctx, options.color, canvas, options);
426
+ const progFill = makeFill(ctx, options.progressColor, canvas, options);
407
427
 
408
428
  ctx.clearRect(0, 0, canvas.width, canvas.height);
409
429
 
@@ -452,7 +472,7 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
452
472
  ctx.clearRect(0, 0, width, height);
453
473
 
454
474
  // Draw background track
455
- ctx.fillStyle = options.color || 'rgba(255, 255, 255, 0.2)';
475
+ ctx.fillStyle = makeFill(ctx, options.color, canvas, options) || 'rgba(255, 255, 255, 0.2)';
456
476
 
457
477
  // Rounded background track
458
478
  capsulePath(ctx, borderRadius, width, centerY, barHeight);
@@ -471,7 +491,7 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
471
491
  // enabled (the bar); a standalone seekbar stays at full progress.
472
492
  ctx.save();
473
493
  ctx.globalAlpha = options.seekHandle && !active ? 0.7 : 1;
474
- ctx.fillStyle = options.progressColor || 'rgba(255, 255, 255, 0.9)';
494
+ ctx.fillStyle = makeFill(ctx, options.progressColor, canvas, options) || 'rgba(255, 255, 255, 0.9)';
475
495
  capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
476
496
  ctx.fill();
477
497
  ctx.restore();