@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/README.md +4 -4
- package/dist/waveform-player.cjs +264 -148
- package/dist/waveform-player.cjs.map +2 -2
- package/dist/waveform-player.css +1 -1
- package/dist/waveform-player.esm.js +13 -17
- package/dist/waveform-player.esm.js.map +3 -3
- package/dist/waveform-player.js +264 -148
- package/dist/waveform-player.min.js +13 -17
- package/dist/waveform-player.min.js.map +3 -3
- package/index.d.ts +10 -11
- package/package.json +1 -1
- package/src/css/waveform-player.css +47 -3
- package/src/js/audio.js +9 -9
- package/src/js/core.js +253 -88
- package/src/js/drawing.js +59 -58
- package/src/js/themes.js +19 -24
- package/src/js/utils.js +27 -7
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
|
-
|
|
114
|
-
|
|
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/
|
|
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
|
-
|
|
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
|
-
|
|
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,
|
|
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
|
@@ -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-
|
|
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-
|
|
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=
|
|
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 =
|
|
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 =
|
|
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=
|
|
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 =
|
|
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=
|
|
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 =
|
|
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 =
|
|
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;
|