@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.
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,12 +147,14 @@ 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;
156
154
  /** Show a time tooltip on hover. @default false */
157
155
  showHoverTime?: boolean;
156
+ /** Show a draggable circle handle + hover brightness on the seekbar style (hover/drag); the bar enables it. Drag-to-scrub works regardless. @default false */
157
+ seekHandle?: boolean;
158
158
  /** Show detected BPM. @default false */
159
159
  showBPM?: boolean;
160
160
  /** Known BPM shown in the badge (with `showBPM`); wins over auto-detection. */
@@ -184,7 +184,7 @@ export interface WaveformPlayerOptions {
184
184
 
185
185
  // ── Content metadata ──────────────────────────────────────────
186
186
  title?: string | null;
187
- subtitle?: string | null;
187
+ artist?: string | null;
188
188
  artwork?: string | null;
189
189
  album?: string;
190
190
  /** Message shown when audio fails to load. @default 'Unable to load audio' */
@@ -229,8 +229,7 @@ export interface WaveformTimeUpdateEventDetail {
229
229
  export interface WaveformTrackDetail {
230
230
  url: string;
231
231
  title: string | null;
232
- subtitle: string | null;
233
- artist?: string;
232
+ artist: string | null;
234
233
  artwork: string | null;
235
234
  /** Chapter markers for the track (forwarded so controllers don't re-fetch). */
236
235
  markers?: WaveformMarker[];
@@ -301,7 +300,7 @@ export declare class WaveformPlayer {
301
300
  /** Load (or replace) the audio URL and regenerate the waveform. */
302
301
  load(url: string): Promise<void>;
303
302
  /** Load a new track without re-instantiating; updates metadata then plays. */
304
- loadTrack(url: string, title?: string | null, subtitle?: string | null, options?: WaveformPlayerOptions): Promise<void>;
303
+ loadTrack(url: string, title?: string | null, artist?: string | null, options?: WaveformPlayerOptions): Promise<void>;
305
304
  /** Seek to an absolute time in seconds (self mode). */
306
305
  seekTo(seconds: number): void;
307
306
  /** 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.16.1",
3
+ "version": "1.18.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;
@@ -296,6 +314,32 @@
296
314
  z-index: 1000;
297
315
  }
298
316
 
317
+ /* Draggable seek handle — a DOM circle over the playhead, shown only on
318
+ hover / drag, that grows on direct hover / while dragging. A DOM element
319
+ (not canvas-drawn) so it's always a perfect circle and animates smoothly. */
320
+ .waveform-seek-handle {
321
+ position: absolute;
322
+ top: 50%;
323
+ left: 0;
324
+ width: 11px;
325
+ height: 11px;
326
+ border-radius: 50%;
327
+ background: #fff;
328
+ box-shadow: 0 1px 4px rgba(0, 0, 0, 0.35);
329
+ transform: translate(-50%, -50%) scale(0);
330
+ opacity: 0;
331
+ transition: opacity 0.12s ease, transform 0.12s ease;
332
+ pointer-events: none;
333
+ z-index: 6;
334
+ }
335
+ .waveform-seek-handle.is-visible {
336
+ opacity: 1;
337
+ transform: translate(-50%, -50%) scale(1);
338
+ }
339
+ .waveform-seek-handle.is-active {
340
+ transform: translate(-50%, -50%) scale(1.25);
341
+ }
342
+
299
343
  /* Focus styles for accessibility */
300
344
  .waveform-btn:focus-visible {
301
345
  outline: 2px solid currentColor;
@@ -450,7 +494,7 @@
450
494
  font-size: 12px;
451
495
  }
452
496
 
453
- .waveform-subtitle,
497
+ .waveform-artist,
454
498
  .waveform-time,
455
499
  .waveform-bpm {
456
500
  font-size: 10px;
package/src/js/audio.js CHANGED
@@ -4,7 +4,7 @@
4
4
  */
5
5
 
6
6
  import {detectBPM} from './bpm.js';
7
- import {clamp} from './utils.js';
7
+ import {clamp, maxOf, DEFAULT_SAMPLES} from './utils.js';
8
8
 
9
9
  /**
10
10
  * Extract peaks from a decoded audio buffer for waveform visualization.
@@ -18,10 +18,10 @@ import {clamp} from './utils.js';
18
18
  * returned unscaled).
19
19
  *
20
20
  * @param {AudioBuffer} buffer - Decoded audio buffer to analyse.
21
- * @param {number} [samples=200] - Number of peak windows (output array length).
21
+ * @param {number} [samples=1800] - Number of peak windows (output array length).
22
22
  * @returns {number[]} Array of `samples` normalized peak values in the 0-1 range.
23
23
  */
24
- export function extractPeaks(buffer, samples = 200) {
24
+ export function extractPeaks(buffer, samples = DEFAULT_SAMPLES) {
25
25
  const sampleSize = buffer.length / samples;
26
26
  const channels = buffer.numberOfChannels;
27
27
  const peaks = [];
@@ -56,7 +56,7 @@ export function extractPeaks(buffer, samples = 200) {
56
56
  }
57
57
 
58
58
  // Normalize peaks
59
- const maxPeak = Math.max(...peaks);
59
+ const maxPeak = maxOf(peaks);
60
60
  return maxPeak > 0 ? peaks.map(peak => peak / maxPeak) : peaks;
61
61
  }
62
62
 
@@ -71,13 +71,13 @@ export function extractPeaks(buffer, samples = 200) {
71
71
  * callers can fall back to a placeholder waveform.
72
72
  *
73
73
  * @param {string} url - Audio file URL to fetch and decode.
74
- * @param {number} [samples=200] - Number of peak windows to extract.
74
+ * @param {number} [samples=1800] - Number of peak windows to extract.
75
75
  * @param {boolean} [shouldDetectBPM=false] - Whether to run BPM detection on the decoded buffer.
76
76
  * @returns {Promise<{peaks: number[], bpm: (number|null)}>} Resolves with the
77
77
  * normalized peaks and the detected BPM (`null` when detection is disabled or fails).
78
78
  * @throws {Error} Re-throws any fetch/decode error after logging it.
79
79
  */
80
- export async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
80
+ export async function generateWaveform(url, samples = DEFAULT_SAMPLES, shouldDetectBPM = false) {
81
81
  // Created lazily so the finally block can always close it — browsers
82
82
  // hard-cap live AudioContexts (~6 in Chrome), so leaking one per failed
83
83
  // decode would break every subsequent player on the page.
@@ -115,10 +115,10 @@ export async function generateWaveform(url, samples = 200, shouldDetectBPM = fal
115
115
  * variation across the array, clamped to the 0.1-1 range so the result always
116
116
  * looks like a plausible waveform rather than pure noise.
117
117
  *
118
- * @param {number} [samples=200] - Number of bars (output array length).
118
+ * @param {number} [samples=1800] - Number of bars (output array length).
119
119
  * @returns {number[]} Array of `samples` pseudo-random peak values in the 0.1-1 range.
120
120
  */
121
- export function generatePlaceholderWaveform(samples = 200) {
121
+ export function generatePlaceholderWaveform(samples = DEFAULT_SAMPLES) {
122
122
  const data = [];
123
123
  for (let i = 0; i < samples; i++) {
124
124
  const base = Math.random() * 0.5 + 0.3;
@@ -142,7 +142,7 @@ export function generatePlaceholderWaveform(samples = 200) {
142
142
  * @private
143
143
  */
144
144
  function normalizePeaks(peaks, targetMax = 0.95) {
145
- const maxPeak = Math.max(...peaks);
145
+ const maxPeak = maxOf(peaks);
146
146
 
147
147
  // Don't normalize if already loud enough or silent
148
148
  if (maxPeak === 0 || maxPeak > targetMax) return peaks;