@arraypress/waveform-player 1.24.0 → 1.24.2
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/dist/waveform-player.cjs +57 -31
- package/dist/waveform-player.cjs.map +2 -2
- package/dist/waveform-player.esm.js +3 -3
- package/dist/waveform-player.esm.js.map +3 -3
- package/dist/waveform-player.js +57 -31
- package/dist/waveform-player.min.js +3 -3
- package/dist/waveform-player.min.js.map +3 -3
- package/index.d.ts +7 -0
- package/package.json +2 -1
- package/src/js/core.js +7 -5
- package/src/js/index.js +8 -3
- package/src/js/themes.js +119 -33
- package/src/js/utils.js +52 -12
package/index.d.ts
CHANGED
|
@@ -413,6 +413,13 @@ export declare class WaveformPlayer {
|
|
|
413
413
|
* Lets wrappers inherit the complete option surface without drifting.
|
|
414
414
|
*/
|
|
415
415
|
parseDataAttributes(element: HTMLElement): Partial<WaveformPlayerOptions>;
|
|
416
|
+
/**
|
|
417
|
+
* Detect whether the page around `element` reads as light or dark —
|
|
418
|
+
* explicit theme classes/attributes first, then the backdrop actually
|
|
419
|
+
* visible behind it (every ancestor background composited over the UA
|
|
420
|
+
* canvas). Pass the element the caller is theming; defaults to `<body>`.
|
|
421
|
+
*/
|
|
422
|
+
detectColorScheme(element?: Element): 'dark' | 'light';
|
|
416
423
|
};
|
|
417
424
|
}
|
|
418
425
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arraypress/waveform-player",
|
|
3
|
-
"version": "1.24.
|
|
3
|
+
"version": "1.24.2",
|
|
4
4
|
"description": "Lightweight, customizable audio player with waveform visualization",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"types": "./index.d.ts",
|
|
@@ -39,6 +39,7 @@
|
|
|
39
39
|
"serve": "npx http-server -p 8000",
|
|
40
40
|
"test": "vitest run",
|
|
41
41
|
"test:watch": "vitest",
|
|
42
|
+
"test:visual": "node test/visual/theme-matrix.mjs",
|
|
42
43
|
"prepublishOnly": "npm run test && npm run build"
|
|
43
44
|
},
|
|
44
45
|
"keywords": [
|
package/src/js/core.js
CHANGED
|
@@ -90,8 +90,10 @@ export class WaveformPlayer {
|
|
|
90
90
|
// Merge options: defaults < data attributes < constructor options
|
|
91
91
|
this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions);
|
|
92
92
|
|
|
93
|
-
// Apply color preset (auto-detect if not specified)
|
|
94
|
-
|
|
93
|
+
// Apply color preset (auto-detect if not specified). Detection reads
|
|
94
|
+
// the backdrop behind THIS container, so a player dropped into a themed
|
|
95
|
+
// card matches the card rather than the page.
|
|
96
|
+
const preset = getColorPreset(this.options.colorPreset, this.container);
|
|
95
97
|
|
|
96
98
|
// Track auto-theme state so the player can re-detect on a runtime light/
|
|
97
99
|
// dark switch. Only colours the user LEFT UNSET follow the preset; an
|
|
@@ -100,7 +102,7 @@ export class WaveformPlayer {
|
|
|
100
102
|
this._presetKeys = [];
|
|
101
103
|
// Resolved scheme name for the CSS theme class (CSS provides the DOM
|
|
102
104
|
// chrome colours via --wfp-* variables).
|
|
103
|
-
this._scheme = (this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset]) ? this.options.colorPreset : detectColorScheme();
|
|
105
|
+
this._scheme = (this.options.colorPreset && COLOR_PRESETS[this.options.colorPreset]) ? this.options.colorPreset : detectColorScheme(this.container);
|
|
104
106
|
|
|
105
107
|
// Apply preset colors only if individual colors aren't explicitly set
|
|
106
108
|
for (const [key, value] of Object.entries(preset)) {
|
|
@@ -1989,8 +1991,8 @@ export class WaveformPlayer {
|
|
|
1989
1991
|
*/
|
|
1990
1992
|
refreshTheme() {
|
|
1991
1993
|
if (!this._autoTheme) return;
|
|
1992
|
-
this._scheme = detectColorScheme();
|
|
1993
|
-
const preset = getColorPreset(this.options.colorPreset);
|
|
1994
|
+
this._scheme = detectColorScheme(this.container);
|
|
1995
|
+
const preset = getColorPreset(this.options.colorPreset, this.container);
|
|
1994
1996
|
for (const key of (this._presetKeys || [])) {
|
|
1995
1997
|
if (key in preset) this.options[key] = preset[key];
|
|
1996
1998
|
}
|
package/src/js/index.js
CHANGED
|
@@ -13,14 +13,19 @@
|
|
|
13
13
|
// Import the main class
|
|
14
14
|
import {WaveformPlayer} from './core.js';
|
|
15
15
|
import {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes} from './utils.js';
|
|
16
|
+
import {detectColorScheme} from './themes.js';
|
|
16
17
|
|
|
17
18
|
// Expose a small set of pure helpers as a single source of truth so consumers
|
|
18
19
|
// (e.g. @arraypress/waveform-bar, @arraypress/waveform-playlist) can reuse them
|
|
19
20
|
// instead of shipping divergent copies. `parseDataAttributes` lets wrappers read
|
|
20
21
|
// the player's full `data-*` option surface off a host element without
|
|
21
|
-
// re-implementing (and drifting from) the contract.
|
|
22
|
-
//
|
|
23
|
-
|
|
22
|
+
// re-implementing (and drifting from) the contract. `detectColorScheme` is here
|
|
23
|
+
// for the same reason: the bar used to carry its own copy of the heuristic and
|
|
24
|
+
// the two drifted (both shipped the transparent-background bug of #21, fixed
|
|
25
|
+
// independently). Attached to the class so it's reachable from the IIFE global
|
|
26
|
+
// too — which is how the bar reaches it, since it depends on this package as a
|
|
27
|
+
// runtime peer rather than importing the module.
|
|
28
|
+
WaveformPlayer.utils = {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref, parseDataAttributes, detectColorScheme};
|
|
24
29
|
|
|
25
30
|
/**
|
|
26
31
|
* Whether we're running in a browser (vs. SSR / Node), where `window` and
|
package/src/js/themes.js
CHANGED
|
@@ -3,7 +3,14 @@
|
|
|
3
3
|
* @description Color presets and default options for WaveformPlayer
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
-
import {perceivedBrightness, DEFAULT_SAMPLES} from './utils.js';
|
|
6
|
+
import {parseColor, perceivedBrightness, DEFAULT_SAMPLES} from './utils.js';
|
|
7
|
+
|
|
8
|
+
/**
|
|
9
|
+
* Brightness (0–255) above which a backdrop counts as light.
|
|
10
|
+
* @type {number}
|
|
11
|
+
* @private
|
|
12
|
+
*/
|
|
13
|
+
const LIGHT_THRESHOLD = 128;
|
|
7
14
|
|
|
8
15
|
/**
|
|
9
16
|
* Does `<html>` or `<body>` explicitly signal the given colour scheme via a
|
|
@@ -28,6 +35,88 @@ function hasThemeHint(scheme) {
|
|
|
28
35
|
);
|
|
29
36
|
}
|
|
30
37
|
|
|
38
|
+
/**
|
|
39
|
+
* Collect what the page paints behind `el`.
|
|
40
|
+
*
|
|
41
|
+
* Walks `el` and its ancestors up to `<html>`, alpha-compositing each element's
|
|
42
|
+
* background *colour* front-to-back. Walking the chain (rather than reading
|
|
43
|
+
* `<body>` alone) is what makes real layouts work: plenty of pages paint their
|
|
44
|
+
* background on a wrapper `<div>` or on `<html>` instead of `<body>`, and a
|
|
45
|
+
* player sitting inside a dark card on an otherwise light page should theme to
|
|
46
|
+
* the card.
|
|
47
|
+
*
|
|
48
|
+
* Compositing rather than taking the first colour found means translucent
|
|
49
|
+
* layers — an `rgba(0, 0, 0, 0.04)` tint over white, say — score as what the eye
|
|
50
|
+
* sees instead of as their own colour. Brightness is linear in R/G/B, so
|
|
51
|
+
* blending per-layer brightnesses is equivalent to blending the colours.
|
|
52
|
+
*
|
|
53
|
+
* Background *images* and gradients can't be scored from CSS, so a page painted
|
|
54
|
+
* only that way contributes no colour here and is classified by
|
|
55
|
+
* {@link detectCanvasScheme} instead.
|
|
56
|
+
*
|
|
57
|
+
* @param {Element} el - Element to start from (the player's container).
|
|
58
|
+
* @returns {{sum: number, alpha: number}} Premultiplied brightness, and how much
|
|
59
|
+
* of the stack is opaque (0–1).
|
|
60
|
+
* @private
|
|
61
|
+
*/
|
|
62
|
+
function collectBackdrop(el) {
|
|
63
|
+
let sum = 0;
|
|
64
|
+
let alpha = 0;
|
|
65
|
+
|
|
66
|
+
for (let node = el; node && node.nodeType === 1 && alpha < 0.995; node = node.parentElement) {
|
|
67
|
+
const c = parseColor(getComputedStyle(node).backgroundColor);
|
|
68
|
+
if (!c || c.a <= 0) continue;
|
|
69
|
+
|
|
70
|
+
// Each layer only shows through however much is still see-through.
|
|
71
|
+
const weight = c.a * (1 - alpha);
|
|
72
|
+
sum += ((c.r * 299 + c.g * 587 + c.b * 114) / 1000) * weight;
|
|
73
|
+
alpha += weight;
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
return {sum, alpha};
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* Scheme of the canvas — what is visible wherever the page paints no background
|
|
81
|
+
* colour of its own.
|
|
82
|
+
*
|
|
83
|
+
* Read from the page's *resolved text colour*. `color` initially resolves to the
|
|
84
|
+
* `canvastext` system colour, which browsers flip to white exactly when the
|
|
85
|
+
* document's used colour-scheme is dark, so it reports the palette the page is
|
|
86
|
+
* actually designed for. It is also the only signal that sees the
|
|
87
|
+
* `<meta name="color-scheme" content="light dark">` form — Chrome reports
|
|
88
|
+
* `normal` for the computed `color-scheme` property there, so reading that
|
|
89
|
+
* instead would miss the exact setup in #21.
|
|
90
|
+
*
|
|
91
|
+
* Deliberately NOT `prefers-color-scheme`. That describes the **user**, not the
|
|
92
|
+
* page, and what browsers paint behind an unpainted page under a dark
|
|
93
|
+
* preference turns out to be engine-specific — measured by screenshotting the
|
|
94
|
+
* same page in both engines: Chromium composites a dark `#121212` base
|
|
95
|
+
* background, WebKit keeps it white. Since no scripted signal can tell those
|
|
96
|
+
* apart, we believe the page instead: black text means it was designed light,
|
|
97
|
+
* so it gets the light preset. That is right in WebKit, and in Chromium it only
|
|
98
|
+
* loses on a page whose own text is already unreadable against that same dark
|
|
99
|
+
* base background. The media query survives purely as a last resort for
|
|
100
|
+
* environments with no resolvable text colour.
|
|
101
|
+
*
|
|
102
|
+
* @returns {'dark'|'light'} Scheme of the canvas behind the page.
|
|
103
|
+
* @private
|
|
104
|
+
*/
|
|
105
|
+
function detectCanvasScheme() {
|
|
106
|
+
// Light text ⇒ the page is painted for a dark canvas, and vice versa.
|
|
107
|
+
const text = perceivedBrightness(getComputedStyle(document.body).color);
|
|
108
|
+
if (text !== null) return text > LIGHT_THRESHOLD ? 'dark' : 'light';
|
|
109
|
+
|
|
110
|
+
if (window.matchMedia) {
|
|
111
|
+
if (window.matchMedia('(prefers-color-scheme: dark)').matches) return 'dark';
|
|
112
|
+
if (window.matchMedia('(prefers-color-scheme: light)').matches) return 'light';
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
// Knowing nothing at all keeps the historic default — most audio players
|
|
116
|
+
// are dark.
|
|
117
|
+
return 'dark';
|
|
118
|
+
}
|
|
119
|
+
|
|
31
120
|
/**
|
|
32
121
|
* Detect the appropriate color scheme for the player from the surrounding page.
|
|
33
122
|
*
|
|
@@ -35,46 +124,41 @@ function hasThemeHint(scheme) {
|
|
|
35
124
|
* 1. Explicit theme hints on `<html>`/`<body>` — class names
|
|
36
125
|
* (`dark`, `dark-mode`, `theme-dark`, light equivalents) and data
|
|
37
126
|
* attributes (`data-theme`, `data-color-scheme`).
|
|
38
|
-
* 2. The
|
|
39
|
-
* {@link
|
|
40
|
-
*
|
|
41
|
-
* 3. The
|
|
42
|
-
*
|
|
127
|
+
* 2. The backdrop actually visible behind the player — every background from
|
|
128
|
+
* `el` up through `<html>` ({@link collectBackdrop}), composited over the
|
|
129
|
+
* canvas ({@link detectCanvasScheme}). >128 = light, <128 = dark.
|
|
130
|
+
* 3. The canvas scheme alone, for the knife-edge case where the composite
|
|
131
|
+
* lands exactly on the threshold.
|
|
43
132
|
*
|
|
133
|
+
* @param {Element} [el] - The player's container, so a player inside a themed
|
|
134
|
+
* card picks up that card. Defaults to `<body>`.
|
|
44
135
|
* @returns {string} The detected scheme, either `'dark'` or `'light'`.
|
|
45
136
|
*/
|
|
46
|
-
export function detectColorScheme() {
|
|
137
|
+
export function detectColorScheme(el) {
|
|
47
138
|
// 1. Explicit theme class names / data attributes win.
|
|
48
139
|
if (hasThemeHint('dark')) return 'dark';
|
|
49
140
|
if (hasThemeHint('light')) return 'light';
|
|
50
141
|
|
|
51
|
-
// 2. Try to detect website's theme from background color
|
|
52
142
|
try {
|
|
53
|
-
|
|
54
|
-
const
|
|
55
|
-
|
|
56
|
-
// Clear determination: bright background = light theme. Exactly 128
|
|
57
|
-
// (or unparseable) is ambiguous — fall through to the next method.
|
|
58
|
-
if (brightness !== null) {
|
|
59
|
-
if (brightness > 128) return 'light';
|
|
60
|
-
if (brightness < 128) return 'dark';
|
|
61
|
-
}
|
|
62
|
-
} catch (e) {
|
|
63
|
-
// If background detection fails, continue to next method
|
|
64
|
-
}
|
|
143
|
+
// 2. What the player is actually sitting on.
|
|
144
|
+
const start = (el && el.nodeType === 1) ? el : document.body;
|
|
145
|
+
const {sum, alpha} = collectBackdrop(start);
|
|
65
146
|
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
}
|
|
71
|
-
if (window.matchMedia('(prefers-color-scheme: light)').matches) {
|
|
72
|
-
return 'light';
|
|
73
|
-
}
|
|
74
|
-
}
|
|
147
|
+
// Whatever transparency is left over after the page's own layers shows
|
|
148
|
+
// the canvas through.
|
|
149
|
+
const canvas = detectCanvasScheme();
|
|
150
|
+
const brightness = sum + (canvas === 'dark' ? 0 : 255) * (1 - alpha);
|
|
75
151
|
|
|
76
|
-
|
|
77
|
-
|
|
152
|
+
if (brightness > LIGHT_THRESHOLD) return 'light';
|
|
153
|
+
if (brightness < LIGHT_THRESHOLD) return 'dark';
|
|
154
|
+
|
|
155
|
+
// 3. Dead-centre grey tells us nothing; go with the canvas.
|
|
156
|
+
return canvas;
|
|
157
|
+
} catch (e) {
|
|
158
|
+
// No usable computed styles (SSR shim, detached document) — most audio
|
|
159
|
+
// players are dark, so that stays the fallback.
|
|
160
|
+
return 'dark';
|
|
161
|
+
}
|
|
78
162
|
}
|
|
79
163
|
|
|
80
164
|
/**
|
|
@@ -110,17 +194,19 @@ export const COLOR_PRESETS = {
|
|
|
110
194
|
*
|
|
111
195
|
* @param {string|null} presetName - Preset name (`'dark'` or `'light'`), or
|
|
112
196
|
* null/invalid to trigger auto-detection.
|
|
197
|
+
* @param {Element} [el] - Container passed through to {@link detectColorScheme}
|
|
198
|
+
* so detection reads the backdrop behind this player, not just `<body>`.
|
|
113
199
|
* @returns {Object<string, string>} The matching colour token map from
|
|
114
200
|
* {@link COLOR_PRESETS}.
|
|
115
201
|
*/
|
|
116
|
-
export function getColorPreset(presetName) {
|
|
202
|
+
export function getColorPreset(presetName, el) {
|
|
117
203
|
// If explicitly set to a valid preset, use it
|
|
118
204
|
if (presetName && COLOR_PRESETS[presetName]) {
|
|
119
205
|
return COLOR_PRESETS[presetName];
|
|
120
206
|
}
|
|
121
207
|
|
|
122
208
|
// Auto-detect if not specified or invalid
|
|
123
|
-
const detected = detectColorScheme();
|
|
209
|
+
const detected = detectColorScheme(el);
|
|
124
210
|
return COLOR_PRESETS[detected];
|
|
125
211
|
}
|
|
126
212
|
|
package/src/js/utils.js
CHANGED
|
@@ -283,17 +283,22 @@ export function formatSeekValueText(template, ...args) {
|
|
|
283
283
|
* Format a duration as a clock string.
|
|
284
284
|
*
|
|
285
285
|
* Renders `M:SS` for durations under an hour and `H:MM:SS` for longer ones,
|
|
286
|
-
* zero-padding the minutes and seconds. Falsy,
|
|
287
|
-
* treated as zero and return `'0:00'`.
|
|
286
|
+
* zero-padding the minutes and seconds. Falsy, non-numeric, non-finite, or
|
|
287
|
+
* negative inputs are treated as zero and return `'0:00'`.
|
|
288
|
+
*
|
|
289
|
+
* `Infinity` matters here, and an `isNaN` check does not catch it: a streamed or
|
|
290
|
+
* unseekable source reports `audio.duration === Infinity`, and `Infinity % 3600`
|
|
291
|
+
* is `NaN`, so the old guard rendered a literal `'Infinity:NaN:NaN'` into the UI.
|
|
288
292
|
* @param {number} seconds - Time in seconds.
|
|
289
293
|
* @returns {string} Formatted time, e.g. `'3:07'` or `'1:02:09'`.
|
|
290
294
|
*/
|
|
291
295
|
export function formatTime(seconds) {
|
|
292
|
-
|
|
296
|
+
const total = Number(seconds);
|
|
297
|
+
if (!total || !Number.isFinite(total) || total < 0) return '0:00';
|
|
293
298
|
|
|
294
|
-
const hrs = Math.floor(
|
|
295
|
-
const mins = Math.floor((
|
|
296
|
-
const secs = Math.floor(
|
|
299
|
+
const hrs = Math.floor(total / 3600);
|
|
300
|
+
const mins = Math.floor((total % 3600) / 60);
|
|
301
|
+
const secs = Math.floor(total % 60);
|
|
297
302
|
|
|
298
303
|
if (hrs > 0) {
|
|
299
304
|
return `${hrs}:${mins.toString().padStart(2, '0')}:${secs.toString().padStart(2, '0')}`;
|
|
@@ -352,17 +357,52 @@ export function extractTitleFromUrl(url) {
|
|
|
352
357
|
.replace(/\b\w/g, l => l.toUpperCase());
|
|
353
358
|
}
|
|
354
359
|
|
|
360
|
+
/**
|
|
361
|
+
* Parse a CSS `rgb()`/`rgba()` colour into numeric channels.
|
|
362
|
+
*
|
|
363
|
+
* Handles both serializations a browser can hand back from `getComputedStyle`:
|
|
364
|
+
* the legacy comma form (`rgb(34, 34, 34)`, `rgba(34, 34, 34, 0.5)`) and the
|
|
365
|
+
* modern space/slash form (`rgb(34 34 34 / 50%)`). Anything else — the
|
|
366
|
+
* `transparent` keyword, a wide-gamut `color(srgb …)`, an empty string — is
|
|
367
|
+
* reported as `null` so callers treat it as *unknown* rather than as a colour.
|
|
368
|
+
*
|
|
369
|
+
* @param {string} color - CSS colour string.
|
|
370
|
+
* @returns {{r: number, g: number, b: number, a: number}|null} Channels 0–255
|
|
371
|
+
* with alpha 0–1, or `null` when the string isn't an rgb()/rgba() colour.
|
|
372
|
+
*/
|
|
373
|
+
export function parseColor(color) {
|
|
374
|
+
if (typeof color !== 'string') return null;
|
|
375
|
+
|
|
376
|
+
const m = color.match(/rgba?\(\s*([\d.]+)\s*[,\s]\s*([\d.]+)\s*[,\s]\s*([\d.]+)\s*(?:[,/]\s*([\d.]+)(%?))?/i);
|
|
377
|
+
if (!m) return null;
|
|
378
|
+
|
|
379
|
+
const r = Number(m[1]), g = Number(m[2]), b = Number(m[3]);
|
|
380
|
+
if (!Number.isFinite(r) || !Number.isFinite(g) || !Number.isFinite(b)) return null;
|
|
381
|
+
|
|
382
|
+
let a = m[4] === undefined ? 1 : Number(m[4]);
|
|
383
|
+
if (!Number.isFinite(a)) return null;
|
|
384
|
+
if (m[5] === '%') a /= 100;
|
|
385
|
+
|
|
386
|
+
return {r, g, b, a: clamp(a, 0, 1)};
|
|
387
|
+
}
|
|
388
|
+
|
|
355
389
|
/**
|
|
356
390
|
* Perceived brightness (0–255) of a CSS colour, via the luminance formula.
|
|
357
|
-
*
|
|
391
|
+
*
|
|
392
|
+
* A fully transparent colour returns `null`, not `0`. That distinction matters:
|
|
393
|
+
* `rgba(0, 0, 0, 0)` is the computed background of *every* element the page
|
|
394
|
+
* never paints, so scoring it as pure black made auto-theme detection classify
|
|
395
|
+
* unpainted (i.e. white) pages as dark — see issue #21. Transparent means "this
|
|
396
|
+
* tells you nothing", which is a different answer from "this is black".
|
|
397
|
+
*
|
|
358
398
|
* @param {string} color - CSS colour string, e.g. `"rgb(34, 34, 34)"`.
|
|
359
|
-
* @returns {number|null} Brightness 0–255, or `null` if it can't be parsed
|
|
399
|
+
* @returns {number|null} Brightness 0–255, or `null` if it can't be parsed or
|
|
400
|
+
* is fully transparent.
|
|
360
401
|
*/
|
|
361
402
|
export function perceivedBrightness(color) {
|
|
362
|
-
const
|
|
363
|
-
if (!
|
|
364
|
-
|
|
365
|
-
return (r * 299 + g * 587 + b * 114) / 1000;
|
|
403
|
+
const c = parseColor(color);
|
|
404
|
+
if (!c || c.a <= 0) return null;
|
|
405
|
+
return (c.r * 299 + c.g * 587 + c.b * 114) / 1000;
|
|
366
406
|
}
|
|
367
407
|
|
|
368
408
|
/**
|