@arraypress/waveform-player 1.24.5 → 1.25.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/dist/waveform-player.cjs +195 -39
- package/dist/waveform-player.esm.js +6 -6
- package/dist/waveform-player.js +195 -39
- package/dist/waveform-player.min.js +6 -6
- package/index.d.ts +6 -2
- package/package.json +7 -2
- package/src/js/core.js +82 -45
- package/src/js/themes.js +230 -2
- package/src/js/utils.js +149 -9
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@arraypress/waveform-player",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.25.1",
|
|
4
4
|
"description": "Lightweight, customizable audio player with waveform visualization",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"types": "./index.d.ts",
|
|
@@ -81,7 +81,12 @@
|
|
|
81
81
|
"registry": "https://registry.npmjs.org/"
|
|
82
82
|
},
|
|
83
83
|
"sideEffects": [
|
|
84
|
-
"*.css"
|
|
84
|
+
"*.css",
|
|
85
|
+
"./dist/waveform-player.esm.js",
|
|
86
|
+
"./dist/waveform-player.cjs",
|
|
87
|
+
"./dist/waveform-player.js",
|
|
88
|
+
"./dist/waveform-player.min.js",
|
|
89
|
+
"./src/js/index.js"
|
|
85
90
|
],
|
|
86
91
|
"devDependencies": {
|
|
87
92
|
"concurrently": "^10.0.3",
|
package/src/js/core.js
CHANGED
|
@@ -16,10 +16,23 @@ import {
|
|
|
16
16
|
clamp,
|
|
17
17
|
escapeHtml,
|
|
18
18
|
formatCssLength,
|
|
19
|
+
toFiniteNumber,
|
|
20
|
+
toNumberArray,
|
|
19
21
|
DEFAULT_SAMPLES
|
|
20
22
|
} from './utils.js';
|
|
21
23
|
|
|
22
|
-
import {
|
|
24
|
+
import {
|
|
25
|
+
DEFAULT_OPTIONS,
|
|
26
|
+
STYLE_DEFAULTS,
|
|
27
|
+
getColorPreset,
|
|
28
|
+
COLOR_PRESETS,
|
|
29
|
+
detectColorScheme,
|
|
30
|
+
normalizeOptions,
|
|
31
|
+
normalizeMarkers,
|
|
32
|
+
BUTTON_ALIGNMENTS,
|
|
33
|
+
PLAYBACK_RATE_MIN,
|
|
34
|
+
PLAYBACK_RATE_MAX
|
|
35
|
+
} from './themes.js';
|
|
23
36
|
|
|
24
37
|
/**
|
|
25
38
|
* Placeholder shown when an artwork URL fails to load (404 / broken) — a muted
|
|
@@ -40,12 +53,6 @@ const SEEK_PAGE_SECONDS = 10;
|
|
|
40
53
|
// wrapper, moving it off the control the user just operated.
|
|
41
54
|
const INTERACTIVE_ELEMENTS = 'button, a[href], input, [role="slider"]';
|
|
42
55
|
|
|
43
|
-
// Recognised `buttonAlign` values. `createDOM` interpolates the resolved value
|
|
44
|
-
// into a class name, so an unrecognised value is coerced back to 'auto' rather
|
|
45
|
-
// than reaching the template — that guards both configuration paths (constructor
|
|
46
|
-
// options and `data-button-align`) at the single point of use.
|
|
47
|
-
const BUTTON_ALIGNMENTS = ['auto', 'top', 'center', 'bottom'];
|
|
48
|
-
|
|
49
56
|
/**
|
|
50
57
|
* WaveformPlayer - Modern audio player with waveform visualization
|
|
51
58
|
* @class
|
|
@@ -93,8 +100,12 @@ export class WaveformPlayer {
|
|
|
93
100
|
if (userOptions.style && !userOptions.waveformStyle) userOptions.waveformStyle = userOptions.style;
|
|
94
101
|
if (userOptions.src && !userOptions.url) userOptions.url = userOptions.src;
|
|
95
102
|
|
|
96
|
-
// Merge options: defaults < data attributes < constructor options
|
|
97
|
-
|
|
103
|
+
// Merge options: defaults < data attributes < constructor options, then
|
|
104
|
+
// normalize the result. Both configuration paths are untyped, so this is
|
|
105
|
+
// the single point where an unusable value (non-array `playbackRates`,
|
|
106
|
+
// NaN geometry, an unrecognised enum) resolves to its default instead of
|
|
107
|
+
// reaching a consumer that assumes a shape it never checked.
|
|
108
|
+
this.options = normalizeOptions(mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions));
|
|
98
109
|
|
|
99
110
|
// Apply color preset (auto-detect if not specified). Detection reads
|
|
100
111
|
// the backdrop behind THIS container, so a player dropped into a themed
|
|
@@ -253,7 +264,10 @@ export class WaveformPlayer {
|
|
|
253
264
|
this.container.innerHTML = '';
|
|
254
265
|
this.container.className = 'waveform-player';
|
|
255
266
|
|
|
256
|
-
// Determine button alignment
|
|
267
|
+
// Determine button alignment. normalizeOptions() has already rejected
|
|
268
|
+
// unrecognised values, but the resolved name is interpolated into a
|
|
269
|
+
// class name, so the allowlist is re-checked at the point of use —
|
|
270
|
+
// options stay publicly mutable after construction.
|
|
257
271
|
let buttonAlign = BUTTON_ALIGNMENTS.includes(this.options.buttonAlign)
|
|
258
272
|
? this.options.buttonAlign
|
|
259
273
|
: 'auto';
|
|
@@ -1147,11 +1161,13 @@ export class WaveformPlayer {
|
|
|
1147
1161
|
* `loadedmetadata` before proceeding. In external mode there is no audio
|
|
1148
1162
|
* element, so the src/metadata step is skipped and only the visualization
|
|
1149
1163
|
* is built (duration/time come from the controller via
|
|
1150
|
-
* {@link WaveformPlayer#setProgress}).
|
|
1151
|
-
*
|
|
1152
|
-
*
|
|
1153
|
-
*
|
|
1154
|
-
*
|
|
1164
|
+
* {@link WaveformPlayer#setProgress}). The title and the seek slider's
|
|
1165
|
+
* accessible name are written *before* the metadata wait, as are peaks
|
|
1166
|
+
* supplied via the `waveform` option — none of them need anything from the
|
|
1167
|
+
* audio element, and behind the wait they blink in on a slow origin.
|
|
1168
|
+
* Without inline peaks the waveform is decoded from the audio instead; a
|
|
1169
|
+
* decode failure falls back to a placeholder. The `onLoad` callback fires
|
|
1170
|
+
* on success.
|
|
1155
1171
|
* @param {string} url - Audio URL.
|
|
1156
1172
|
* @returns {Promise<void>} Resolves once loading settles (errors are caught
|
|
1157
1173
|
* internally and surfaced through {@link WaveformPlayer#onError}).
|
|
@@ -1173,6 +1189,18 @@ export class WaveformPlayer {
|
|
|
1173
1189
|
this.setWaveformData(this.options.waveform);
|
|
1174
1190
|
}
|
|
1175
1191
|
|
|
1192
|
+
// Same reasoning as the peaks above: the title comes from the
|
|
1193
|
+
// `title` option or the URL, so it needs nothing from the audio
|
|
1194
|
+
// element and has no business waiting on the network. Behind the
|
|
1195
|
+
// metadata wait it left the info row blank for the whole fetch and
|
|
1196
|
+
// then popped in — a visible blink on any slow origin. See #25.
|
|
1197
|
+
const title = this.options.title || extractTitleFromUrl(url);
|
|
1198
|
+
if (this.titleEl) {
|
|
1199
|
+
this.titleEl.textContent = title;
|
|
1200
|
+
}
|
|
1201
|
+
// Keep the seek slider's accessible name in sync with the track.
|
|
1202
|
+
this.applySeekLabel(title);
|
|
1203
|
+
|
|
1176
1204
|
// In external mode we don't own an <audio> element — skip
|
|
1177
1205
|
// src assignment + metadata-wait, but still generate the
|
|
1178
1206
|
// waveform peaks so the canvas can render the visualization.
|
|
@@ -1184,7 +1212,7 @@ export class WaveformPlayer {
|
|
|
1184
1212
|
|
|
1185
1213
|
// preload="none" tells the browser to fetch nothing until
|
|
1186
1214
|
// play(), so `loadedmetadata` will never arrive and awaiting
|
|
1187
|
-
// it would strand the rest of this method forever (no
|
|
1215
|
+
// it would strand the rest of this method forever (no peaks,
|
|
1188
1216
|
// no markers, no onLoad, loading state stuck on). Skip the
|
|
1189
1217
|
// wait; the bindEvents() `loadedmetadata` listener still
|
|
1190
1218
|
// fires whenever metadata does land, and onMetadataLoaded()
|
|
@@ -1208,14 +1236,6 @@ export class WaveformPlayer {
|
|
|
1208
1236
|
}
|
|
1209
1237
|
}
|
|
1210
1238
|
|
|
1211
|
-
// Set title
|
|
1212
|
-
const title = this.options.title || extractTitleFromUrl(url);
|
|
1213
|
-
if (this.titleEl) {
|
|
1214
|
-
this.titleEl.textContent = title;
|
|
1215
|
-
}
|
|
1216
|
-
// Keep the seek slider's accessible name in sync with the track.
|
|
1217
|
-
this.applySeekLabel(title);
|
|
1218
|
-
|
|
1219
1239
|
// Peaks were drawn above; only the decode path is left.
|
|
1220
1240
|
if (!hasInlinePeaks) {
|
|
1221
1241
|
// Generate waveform
|
|
@@ -1298,13 +1318,15 @@ export class WaveformPlayer {
|
|
|
1298
1318
|
this.progress = 0;
|
|
1299
1319
|
this.waveformData = [];
|
|
1300
1320
|
|
|
1301
|
-
// Update options (including preload if specified)
|
|
1302
|
-
|
|
1321
|
+
// Update options (including preload if specified). Normalized on the
|
|
1322
|
+
// same terms as the constructor — loadTrack takes a fresh, caller-
|
|
1323
|
+
// supplied option set, so it's the second untyped entry point.
|
|
1324
|
+
this.options = normalizeOptions(mergeOptions(this.options, {
|
|
1303
1325
|
url,
|
|
1304
1326
|
title: title === null ? this.options.title : title,
|
|
1305
1327
|
artist: artist === null ? this.options.artist : artist,
|
|
1306
1328
|
...options
|
|
1307
|
-
});
|
|
1329
|
+
}));
|
|
1308
1330
|
if (hasArtworkOption) {
|
|
1309
1331
|
this.options.artwork = options.artwork || null;
|
|
1310
1332
|
}
|
|
@@ -1314,14 +1336,16 @@ export class WaveformPlayer {
|
|
|
1314
1336
|
this.options.artworkAlt = this.options.artwork ? DEFAULT_OPTIONS.artworkAlt : '';
|
|
1315
1337
|
}
|
|
1316
1338
|
|
|
1317
|
-
// Apply preload setting if it was changed
|
|
1339
|
+
// Apply preload setting if it was changed. The caller's value decides
|
|
1340
|
+
// WHETHER to apply; the normalized one decides WHAT to apply, so an
|
|
1341
|
+
// unsupported value can't reach the media element.
|
|
1318
1342
|
if (options.preload && this.audio) {
|
|
1319
|
-
this.audio.preload = options.preload;
|
|
1343
|
+
this.audio.preload = this.options.preload;
|
|
1320
1344
|
}
|
|
1321
1345
|
|
|
1322
1346
|
// Apply crossOrigin if it was changed for this track
|
|
1323
1347
|
if (options.crossOrigin && this.audio) {
|
|
1324
|
-
this.audio.crossOrigin = options.crossOrigin;
|
|
1348
|
+
this.audio.crossOrigin = this.options.crossOrigin;
|
|
1325
1349
|
}
|
|
1326
1350
|
|
|
1327
1351
|
// Update artist only when explicitly provided. A null artist keeps the
|
|
@@ -1340,7 +1364,7 @@ export class WaveformPlayer {
|
|
|
1340
1364
|
}
|
|
1341
1365
|
|
|
1342
1366
|
// Clear or update markers
|
|
1343
|
-
this.options.markers = options.markers
|
|
1367
|
+
this.options.markers = options.markers ? normalizeMarkers(options.markers) : [];
|
|
1344
1368
|
|
|
1345
1369
|
// Reset the waveform to the NEW track's peaks, or null to regenerate
|
|
1346
1370
|
// from the URL. mergeOptions() above keeps the previous track's
|
|
@@ -1383,8 +1407,10 @@ export class WaveformPlayer {
|
|
|
1383
1407
|
.then(r => r.json())
|
|
1384
1408
|
.then(json => {
|
|
1385
1409
|
this.waveformData = Array.isArray(json) ? json : (json.peaks || []);
|
|
1410
|
+
// A peaks sidecar is a third source of markers, and a remote
|
|
1411
|
+
// one — normalize it on the same terms as the option paths.
|
|
1386
1412
|
if (json.markers && !this.options.markers?.length) {
|
|
1387
|
-
this.options.markers = json.markers;
|
|
1413
|
+
this.options.markers = normalizeMarkers(json.markers);
|
|
1388
1414
|
this.renderMarkers();
|
|
1389
1415
|
}
|
|
1390
1416
|
this.drawWaveform();
|
|
@@ -1393,16 +1419,11 @@ export class WaveformPlayer {
|
|
|
1393
1419
|
return;
|
|
1394
1420
|
}
|
|
1395
1421
|
|
|
1396
|
-
|
|
1397
|
-
|
|
1398
|
-
|
|
1399
|
-
|
|
1400
|
-
|
|
1401
|
-
this.waveformData = data.split(',').map(Number);
|
|
1402
|
-
}
|
|
1403
|
-
} else {
|
|
1404
|
-
this.waveformData = Array.isArray(data) ? data : [];
|
|
1405
|
-
}
|
|
1422
|
+
// Peaks may arrive as an array, a JSON array string, or a bare
|
|
1423
|
+
// comma-separated list — all three collapse into one coercion, which
|
|
1424
|
+
// also drops non-numeric members (the old comma path mapped them to
|
|
1425
|
+
// NaN, and a NaN peak draws as a gap rather than an error).
|
|
1426
|
+
this.waveformData = toNumberArray(data, {fallback: []});
|
|
1406
1427
|
this.drawWaveform();
|
|
1407
1428
|
}
|
|
1408
1429
|
|
|
@@ -2320,15 +2341,21 @@ export class WaveformPlayer {
|
|
|
2320
2341
|
}
|
|
2321
2342
|
|
|
2322
2343
|
/**
|
|
2323
|
-
* Set the owned `<audio>` element's playback rate (clamped to 0.
|
|
2344
|
+
* Set the owned `<audio>` element's playback rate (clamped to 0.25–4),
|
|
2324
2345
|
* persist it onto `this.options.playbackRate`, and refresh the speed UI.
|
|
2325
2346
|
* Self mode only — a no-op in external mode.
|
|
2326
|
-
*
|
|
2347
|
+
*
|
|
2348
|
+
* The clamp bounds the range browsers keep audible; the default speed menu
|
|
2349
|
+
* offers a narrower 0.5–2, which `playbackRates` can widen up to these
|
|
2350
|
+
* bounds. A non-numeric rate is ignored rather than assigned, since
|
|
2351
|
+
* `audio.playbackRate = NaN` throws.
|
|
2352
|
+
* @param {number} rate - Desired playback rate; clamped to the 0.25–4 range.
|
|
2327
2353
|
*/
|
|
2328
2354
|
setPlaybackRate(rate) {
|
|
2329
2355
|
if (!this.audio) return;
|
|
2330
2356
|
|
|
2331
|
-
const clampedRate =
|
|
2357
|
+
const clampedRate = toFiniteNumber(rate, null, {min: PLAYBACK_RATE_MIN, max: PLAYBACK_RATE_MAX});
|
|
2358
|
+
if (clampedRate === null) return;
|
|
2332
2359
|
this.audio.playbackRate = clampedRate;
|
|
2333
2360
|
this.options.playbackRate = clampedRate;
|
|
2334
2361
|
|
|
@@ -2393,6 +2420,16 @@ export class WaveformPlayer {
|
|
|
2393
2420
|
// Clear the container
|
|
2394
2421
|
this.container.innerHTML = '';
|
|
2395
2422
|
|
|
2423
|
+
// Drop the declarative-scan flag along with the markup it described.
|
|
2424
|
+
// autoInit() checks `data-waveform-initialized` *before* the instance
|
|
2425
|
+
// lookup, so leaving it behind on an emptied container makes the
|
|
2426
|
+
// element permanently un-initializable: destroy() wipes the DOM and
|
|
2427
|
+
// the instance, then every later WaveformPlayer.init() skips the
|
|
2428
|
+
// element on the stale flag and it stays blank. Matters most for
|
|
2429
|
+
// destroyAll() + init() resets and for teardown/remount cycles that
|
|
2430
|
+
// reuse the same element rather than re-rendering it.
|
|
2431
|
+
delete this.container.dataset.waveformInitialized;
|
|
2432
|
+
|
|
2396
2433
|
// Clear all references
|
|
2397
2434
|
this.canvas = null;
|
|
2398
2435
|
this.ctx = null;
|
package/src/js/themes.js
CHANGED
|
@@ -3,7 +3,16 @@
|
|
|
3
3
|
* @description Color presets and default options for WaveformPlayer
|
|
4
4
|
*/
|
|
5
5
|
|
|
6
|
-
import {
|
|
6
|
+
import {
|
|
7
|
+
parseColor,
|
|
8
|
+
perceivedBrightness,
|
|
9
|
+
toArray,
|
|
10
|
+
toBool,
|
|
11
|
+
toEnum,
|
|
12
|
+
toFiniteNumber,
|
|
13
|
+
toNumberArray,
|
|
14
|
+
DEFAULT_SAMPLES
|
|
15
|
+
} from './utils.js';
|
|
7
16
|
|
|
8
17
|
/**
|
|
9
18
|
* Brightness (0–255) above which a backdrop counts as light.
|
|
@@ -400,4 +409,223 @@ export const STYLE_DEFAULTS = {
|
|
|
400
409
|
blocks: {barWidth: 4, barSpacing: 2},
|
|
401
410
|
dots: {barWidth: 3, barSpacing: 3},
|
|
402
411
|
seekbar: {barWidth: 1, barSpacing: 0}
|
|
403
|
-
};
|
|
412
|
+
};
|
|
413
|
+
|
|
414
|
+
/**
|
|
415
|
+
* Permitted `buttonAlign` values. `auto` resolves per waveform style at DOM
|
|
416
|
+
* build time (bottom for `bars`, center otherwise).
|
|
417
|
+
* @type {string[]}
|
|
418
|
+
*/
|
|
419
|
+
export const BUTTON_ALIGNMENTS = ['auto', 'top', 'center', 'bottom'];
|
|
420
|
+
|
|
421
|
+
/**
|
|
422
|
+
* Playback-rate bounds. Single source of truth for both the `setPlaybackRate()`
|
|
423
|
+
* clamp and the `playbackRates` menu — an offered rate the setter would refuse
|
|
424
|
+
* leaves the speed label reading one thing while the audio plays another.
|
|
425
|
+
*
|
|
426
|
+
* The window is deliberately wider than the default menu (0.5–2). Audiobook and
|
|
427
|
+
* podcast UIs routinely want 2.5x or 3x, and there's no reason the *setter* should
|
|
428
|
+
* cap what the menu merely doesn't offer by default. 0.25–4 is the conservative
|
|
429
|
+
* limit: browsers keep audio audible and pitch-corrected across that range and
|
|
430
|
+
* start muting it beyond, so a rate outside these bounds would play silently.
|
|
431
|
+
* @type {number}
|
|
432
|
+
*/
|
|
433
|
+
export const PLAYBACK_RATE_MIN = 0.25;
|
|
434
|
+
export const PLAYBACK_RATE_MAX = 4;
|
|
435
|
+
|
|
436
|
+
/**
|
|
437
|
+
* Closed vocabularies for the enumerated options, keyed by option name. Each
|
|
438
|
+
* unrecognised value resolves to that option's {@link DEFAULT_OPTIONS} entry.
|
|
439
|
+
* @type {Object<string, string[]>}
|
|
440
|
+
* @private
|
|
441
|
+
*/
|
|
442
|
+
const ENUMS = {
|
|
443
|
+
buttonAlign: BUTTON_ALIGNMENTS,
|
|
444
|
+
layout: ['default', 'preview'],
|
|
445
|
+
buttonStyle: ['circle', 'minimal'],
|
|
446
|
+
artworkPosition: ['info', 'button'],
|
|
447
|
+
waveformStyle: Object.keys(STYLE_DEFAULTS),
|
|
448
|
+
waveformGradient: ['vertical', 'horizontal', 'diagonal'],
|
|
449
|
+
audioMode: ['self', 'external'],
|
|
450
|
+
preload: ['none', 'metadata', 'auto'],
|
|
451
|
+
colorPreset: Object.keys(COLOR_PRESETS),
|
|
452
|
+
// Anything other than these two makes the browser fall back to 'anonymous',
|
|
453
|
+
// which forces a CORS request the caller never asked for — so a bad value
|
|
454
|
+
// has to resolve to null (no crossorigin attribute), not pass through.
|
|
455
|
+
crossOrigin: ['anonymous', 'use-credentials']
|
|
456
|
+
};
|
|
457
|
+
|
|
458
|
+
/**
|
|
459
|
+
* Numeric options and their acceptable ranges. Out-of-range values are clamped;
|
|
460
|
+
* non-numeric ones fall back to the default.
|
|
461
|
+
* @type {Object<string, {min?: number, max?: number, integer?: boolean}>}
|
|
462
|
+
* @private
|
|
463
|
+
*/
|
|
464
|
+
const NUMBERS = {
|
|
465
|
+
height: {min: 1, integer: true},
|
|
466
|
+
samples: {min: 1, integer: true},
|
|
467
|
+
barWidth: {min: 0},
|
|
468
|
+
barSpacing: {min: 0},
|
|
469
|
+
barRadius: {min: 0},
|
|
470
|
+
bpm: {min: 1},
|
|
471
|
+
// Matches the clamp in setPlaybackRate() — the menu must not offer a rate
|
|
472
|
+
// the setter would then silently refuse.
|
|
473
|
+
playbackRate: {min: PLAYBACK_RATE_MIN, max: PLAYBACK_RATE_MAX}
|
|
474
|
+
};
|
|
475
|
+
|
|
476
|
+
/**
|
|
477
|
+
* Boolean feature flags. Coerced with {@link toBool} so the string `'false'`
|
|
478
|
+
* (a `data-*` value, or a wrapper that stringified a prop) doesn't read as true.
|
|
479
|
+
* @type {string[]}
|
|
480
|
+
* @private
|
|
481
|
+
*/
|
|
482
|
+
const BOOLEANS = [
|
|
483
|
+
'autoplay', 'showControls', 'showInfo', 'showTime', 'showHoverTime',
|
|
484
|
+
'seekHandle', 'showBPM', 'singlePlay', 'playOnSeek', 'enableMediaSession',
|
|
485
|
+
'showMarkers', 'accessibleSeek', 'showPlaybackSpeed'
|
|
486
|
+
];
|
|
487
|
+
|
|
488
|
+
/**
|
|
489
|
+
* Callback options. A non-function here would throw at call time, deep inside
|
|
490
|
+
* playback, rather than at the point the bad value was supplied.
|
|
491
|
+
* @type {string[]}
|
|
492
|
+
* @private
|
|
493
|
+
*/
|
|
494
|
+
const CALLBACKS = [
|
|
495
|
+
'onLoad', 'onPlay', 'onPause', 'onEnd', 'onError', 'onTimeUpdate',
|
|
496
|
+
'onNextTrack', 'onPreviousTrack'
|
|
497
|
+
];
|
|
498
|
+
|
|
499
|
+
/**
|
|
500
|
+
* Warn about an option that was supplied but unusable. Invalid options resolve
|
|
501
|
+
* to their default rather than throwing, so without this they'd fail silently —
|
|
502
|
+
* a `NaN` height renders an invisible player with an empty console.
|
|
503
|
+
* @param {string} key - Option name.
|
|
504
|
+
* @param {*} value - The rejected value.
|
|
505
|
+
* @private
|
|
506
|
+
*/
|
|
507
|
+
function warnInvalid(key, value) {
|
|
508
|
+
console.warn(`[WaveformPlayer] Invalid ${key} option, using default:`, value);
|
|
509
|
+
}
|
|
510
|
+
|
|
511
|
+
/**
|
|
512
|
+
* Normalize a marker list into renderable markers.
|
|
513
|
+
*
|
|
514
|
+
* Accepts an array or a JSON array string, and keeps only entries that are
|
|
515
|
+
* objects with a finite, non-negative `time` — `renderMarkers()` divides by
|
|
516
|
+
* duration and writes the result into `style.left`, so a non-numeric time
|
|
517
|
+
* produces `left: NaN%` and silently stacks every bad marker at the left edge.
|
|
518
|
+
* A missing `label` becomes `''` rather than reaching the tooltip and the
|
|
519
|
+
* marker's `aria-label` as the string `"undefined"`.
|
|
520
|
+
*
|
|
521
|
+
* @param {*} value - Candidate marker list.
|
|
522
|
+
* @returns {Array<Object>} Renderable markers (empty when nothing survives).
|
|
523
|
+
*/
|
|
524
|
+
export function normalizeMarkers(value) {
|
|
525
|
+
const list = toArray(value);
|
|
526
|
+
if (!list) {
|
|
527
|
+
if (value != null) warnInvalid('markers', value);
|
|
528
|
+
return [];
|
|
529
|
+
}
|
|
530
|
+
|
|
531
|
+
return list.reduce((markers, marker) => {
|
|
532
|
+
const time = marker && typeof marker === 'object'
|
|
533
|
+
? toFiniteNumber(marker.time, null, {min: 0})
|
|
534
|
+
: null;
|
|
535
|
+
|
|
536
|
+
if (time === null) {
|
|
537
|
+
warnInvalid('marker', marker);
|
|
538
|
+
return markers;
|
|
539
|
+
}
|
|
540
|
+
|
|
541
|
+
markers.push({...marker, time, label: marker.label == null ? '' : marker.label});
|
|
542
|
+
return markers;
|
|
543
|
+
}, []);
|
|
544
|
+
}
|
|
545
|
+
|
|
546
|
+
/**
|
|
547
|
+
* Normalize a merged option set in place, resolving every unusable value to its
|
|
548
|
+
* {@link DEFAULT_OPTIONS} entry.
|
|
549
|
+
*
|
|
550
|
+
* Options arrive from three untyped directions — `data-*` attributes, framework
|
|
551
|
+
* wrappers forwarding props, and hand-written JS — and the consumers downstream
|
|
552
|
+
* assume shapes that none of those paths guarantee. `playbackRates.map()` and
|
|
553
|
+
* `markers.forEach()` throw outright on valid-but-non-array JSON (`JSON.parse`
|
|
554
|
+
* validates syntax, not shape); `NaN` geometry sizes the canvas to nothing; and
|
|
555
|
+
* unrecognised enum values reach class names and DOM properties. Normalizing
|
|
556
|
+
* once, on the merged object, covers both configuration paths and every wrapper
|
|
557
|
+
* at a single point.
|
|
558
|
+
*
|
|
559
|
+
* Mutates and returns the same object, so it can be dropped in directly after
|
|
560
|
+
* {@link mergeOptions}. Options left unset (`null`) are untouched — `null` is
|
|
561
|
+
* the documented "inherit / auto-detect" state for colours, `bpm`, `buttonSize`
|
|
562
|
+
* and the callbacks.
|
|
563
|
+
*
|
|
564
|
+
* @param {Object} options - Merged options object (mutated).
|
|
565
|
+
* @returns {Object} The same object, normalized.
|
|
566
|
+
*/
|
|
567
|
+
export function normalizeOptions(options) {
|
|
568
|
+
// Only normalize what the caller actually supplied — mergeOptions() drops
|
|
569
|
+
// null/undefined sources, so a null here is a default that means "unset".
|
|
570
|
+
const supplied = (key) => options[key] != null;
|
|
571
|
+
|
|
572
|
+
// Fall back to the documented default, warning only when a real value was
|
|
573
|
+
// rejected (an unset option is not a mistake).
|
|
574
|
+
const reject = (key) => {
|
|
575
|
+
warnInvalid(key, options[key]);
|
|
576
|
+
options[key] = DEFAULT_OPTIONS[key];
|
|
577
|
+
};
|
|
578
|
+
|
|
579
|
+
for (const [key, range] of Object.entries(NUMBERS)) {
|
|
580
|
+
if (!supplied(key)) continue;
|
|
581
|
+
const n = toFiniteNumber(options[key], null, range);
|
|
582
|
+
if (n === null) reject(key); else options[key] = n;
|
|
583
|
+
}
|
|
584
|
+
|
|
585
|
+
for (const [key, allowed] of Object.entries(ENUMS)) {
|
|
586
|
+
if (supplied(key) && toEnum(options[key], allowed) === null) reject(key);
|
|
587
|
+
}
|
|
588
|
+
|
|
589
|
+
for (const key of BOOLEANS) {
|
|
590
|
+
options[key] = toBool(options[key]);
|
|
591
|
+
}
|
|
592
|
+
|
|
593
|
+
for (const key of CALLBACKS) {
|
|
594
|
+
if (supplied(key) && typeof options[key] !== 'function') reject(key);
|
|
595
|
+
}
|
|
596
|
+
|
|
597
|
+
// Speed menu: every offered rate must be one setPlaybackRate() will honour,
|
|
598
|
+
// or the menu label and the audio disagree. Members are interpolated into
|
|
599
|
+
// markup, so non-numeric entries must not survive.
|
|
600
|
+
if (supplied('playbackRates')) {
|
|
601
|
+
const rates = toNumberArray(options.playbackRates, {
|
|
602
|
+
min: PLAYBACK_RATE_MIN,
|
|
603
|
+
max: PLAYBACK_RATE_MAX,
|
|
604
|
+
fallback: null
|
|
605
|
+
});
|
|
606
|
+
if (rates === null) reject('playbackRates'); else options.playbackRates = rates;
|
|
607
|
+
}
|
|
608
|
+
|
|
609
|
+
options.markers = normalizeMarkers(options.markers);
|
|
610
|
+
|
|
611
|
+
// A CSS length is a number (px) or a verbatim unit string ('4rem'); both
|
|
612
|
+
// reach an inline style attribute, escaped, via formatCssLength().
|
|
613
|
+
for (const key of ['buttonSize', 'buttonRadius']) {
|
|
614
|
+
if (!supplied(key)) continue;
|
|
615
|
+
const value = options[key];
|
|
616
|
+
const ok = typeof value === 'number'
|
|
617
|
+
? Number.isFinite(value)
|
|
618
|
+
: typeof value === 'string' && value.trim() !== '';
|
|
619
|
+
if (!ok) reject(key);
|
|
620
|
+
}
|
|
621
|
+
|
|
622
|
+
// A colour is a CSS colour string or an array of gradient stops; anything
|
|
623
|
+
// else resolves to null so the theme preset fills it in instead.
|
|
624
|
+
for (const key of ['waveformColor', 'progressColor']) {
|
|
625
|
+
if (!supplied(key)) continue;
|
|
626
|
+
const value = options[key];
|
|
627
|
+
if (!(typeof value === 'string' && value.trim() !== '') && !Array.isArray(value)) reject(key);
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
return options;
|
|
631
|
+
}
|