@arraypress/waveform-player 1.19.3 → 1.21.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/dist/waveform-player.cjs +145 -23
- package/dist/waveform-player.cjs.map +2 -2
- package/dist/waveform-player.esm.js +7 -7
- package/dist/waveform-player.esm.js.map +3 -3
- package/dist/waveform-player.js +145 -23
- package/dist/waveform-player.min.js +7 -7
- package/dist/waveform-player.min.js.map +3 -3
- package/index.d.ts +17 -0
- package/package.json +1 -1
- package/src/js/core.js +141 -27
- package/src/js/themes.js +15 -0
- package/src/js/utils.js +26 -0
package/index.d.ts
CHANGED
|
@@ -181,12 +181,29 @@ export interface WaveformPlayerOptions {
|
|
|
181
181
|
accessibleSeek?: boolean;
|
|
182
182
|
/** Accessible name for the seek slider (falls back to the title, then `'Seek'`). @default null */
|
|
183
183
|
seekLabel?: string | null;
|
|
184
|
+
/**
|
|
185
|
+
* Template for the seek slider's spoken `aria-valuetext`. `%1$s` is the
|
|
186
|
+
* current time and `%2$s` the total duration (both formatted `M:SS`);
|
|
187
|
+
* sequential `%s` and reordered positional args are also supported. Lets
|
|
188
|
+
* consumers localize the connective text without reformatting the times.
|
|
189
|
+
* Falls back to `'%1$s of %2$s'`.
|
|
190
|
+
* @default null
|
|
191
|
+
*/
|
|
192
|
+
seekValueText?: string | null;
|
|
193
|
+
/** Accessible label (`aria-label`) for the play/pause button. Localize for non-English UIs. @default 'Play/Pause' */
|
|
194
|
+
playPauseLabel?: string;
|
|
195
|
+
/** Accessible label (`aria-label`) for the playback-speed button and menu. Localize for non-English UIs. @default 'Playback speed' */
|
|
196
|
+
speedLabel?: string;
|
|
184
197
|
|
|
185
198
|
// ── Content metadata ──────────────────────────────────────────
|
|
186
199
|
title?: string | null;
|
|
187
200
|
artist?: string | null;
|
|
188
201
|
artwork?: string | null;
|
|
189
202
|
album?: string;
|
|
203
|
+
/** Alt text for the artwork image. Localize for non-English UIs. @default 'Album artwork' */
|
|
204
|
+
artworkAlt?: string;
|
|
205
|
+
/** Media Session (lock-screen) title fallback used when no track `title` is set. Localize for non-English UIs. @default 'Unknown Track' */
|
|
206
|
+
unknownTrackText?: string;
|
|
190
207
|
/** Message shown when audio fails to load. @default 'Unable to load audio' */
|
|
191
208
|
errorText?: string;
|
|
192
209
|
|
package/package.json
CHANGED
package/src/js/core.js
CHANGED
|
@@ -7,6 +7,7 @@ import {draw} from './drawing.js';
|
|
|
7
7
|
import {generateWaveform, generatePlaceholderWaveform} from './audio.js';
|
|
8
8
|
import {
|
|
9
9
|
formatTime,
|
|
10
|
+
formatSeekValueText,
|
|
10
11
|
extractTitleFromUrl,
|
|
11
12
|
generateId,
|
|
12
13
|
parseDataAttributes,
|
|
@@ -265,7 +266,7 @@ export class WaveformPlayer {
|
|
|
265
266
|
|
|
266
267
|
// Build play button HTML (conditional)
|
|
267
268
|
const buttonHTML = this.options.showControls ? `
|
|
268
|
-
<button class="waveform-btn${this.options.buttonStyle === 'minimal' ? ' waveform-btn-minimal' : ''}" aria-label="
|
|
269
|
+
<button class="waveform-btn${this.options.buttonStyle === 'minimal' ? ' waveform-btn-minimal' : ''}" aria-label="${escapeHtml(this.options.playPauseLabel)}"${this.options.buttonSize != null ? ` style="--wfp-btn-size: ${typeof this.options.buttonSize === 'number' ? `${this.options.buttonSize}px` : this.options.buttonSize};"` : ''}>
|
|
269
270
|
<span class="waveform-icon-play">${this.options.playIcon}</span>
|
|
270
271
|
<span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
|
|
271
272
|
</button>
|
|
@@ -275,7 +276,7 @@ export class WaveformPlayer {
|
|
|
275
276
|
const infoHTML = this.options.showInfo ? `
|
|
276
277
|
<div class="waveform-info">
|
|
277
278
|
${this.options.artwork ? `
|
|
278
|
-
<img class="waveform-artwork" src="${this.options.artwork}" alt="
|
|
279
|
+
<img class="waveform-artwork" src="${this.options.artwork}" alt="${escapeHtml(this.options.artworkAlt)}" style="
|
|
279
280
|
width: 40px;
|
|
280
281
|
height: 40px;
|
|
281
282
|
border-radius: 4px;
|
|
@@ -295,10 +296,10 @@ export class WaveformPlayer {
|
|
|
295
296
|
` : ''}
|
|
296
297
|
${this.options.showPlaybackSpeed ? `
|
|
297
298
|
<div class="waveform-speed">
|
|
298
|
-
<button class="speed-btn" aria-label="
|
|
299
|
+
<button class="speed-btn" aria-label="${escapeHtml(this.options.speedLabel)}" aria-haspopup="menu" aria-expanded="false">
|
|
299
300
|
<span class="speed-value">1x</span>
|
|
300
301
|
</button>
|
|
301
|
-
<div class="speed-menu" role="menu" aria-label="
|
|
302
|
+
<div class="speed-menu" role="menu" aria-label="${escapeHtml(this.options.speedLabel)}" style="display: none;">
|
|
302
303
|
${this.options.playbackRates.map(rate =>
|
|
303
304
|
`<button class="speed-option" role="menuitemradio" tabindex="-1" aria-checked="false" data-rate="${rate}">${rate}x</button>`
|
|
304
305
|
).join('')}
|
|
@@ -343,12 +344,7 @@ export class WaveformPlayer {
|
|
|
343
344
|
this.titleEl = this.container.querySelector('.waveform-title');
|
|
344
345
|
this.artistEl = this.container.querySelector('.waveform-artist');
|
|
345
346
|
this.artworkEl = this.container.querySelector('.waveform-artwork');
|
|
346
|
-
|
|
347
|
-
// Fall back to the placeholder tile if the cover URL fails to load.
|
|
348
|
-
this.artworkEl.addEventListener('error', () => {
|
|
349
|
-
if (!this.artworkEl.src.startsWith('data:')) this.artworkEl.src = ARTWORK_FALLBACK;
|
|
350
|
-
});
|
|
351
|
-
}
|
|
347
|
+
this.bindArtworkFallback(this.artworkEl);
|
|
352
348
|
this.currentTimeEl = this.container.querySelector('.time-current');
|
|
353
349
|
this.totalTimeEl = this.container.querySelector('.time-total');
|
|
354
350
|
this.bpmEl = this.container.querySelector('.waveform-bpm');
|
|
@@ -366,6 +362,109 @@ export class WaveformPlayer {
|
|
|
366
362
|
this.updateBPMDisplay();
|
|
367
363
|
}
|
|
368
364
|
|
|
365
|
+
/**
|
|
366
|
+
* Bind the artwork error fallback to an image element.
|
|
367
|
+
*
|
|
368
|
+
* @param {HTMLImageElement|null} img - Artwork image element.
|
|
369
|
+
* @private
|
|
370
|
+
*/
|
|
371
|
+
bindArtworkFallback(img) {
|
|
372
|
+
if (!img) return;
|
|
373
|
+
|
|
374
|
+
// Fall back to the placeholder tile if the cover URL fails to load.
|
|
375
|
+
img.addEventListener('error', () => {
|
|
376
|
+
if (!img.src.startsWith('data:')) img.src = ARTWORK_FALLBACK;
|
|
377
|
+
}, {signal: this._ac.signal});
|
|
378
|
+
}
|
|
379
|
+
|
|
380
|
+
/**
|
|
381
|
+
* Create an artwork image element matching the initial player markup.
|
|
382
|
+
*
|
|
383
|
+
* @returns {HTMLImageElement} Artwork image element.
|
|
384
|
+
* @private
|
|
385
|
+
*/
|
|
386
|
+
createArtworkElement() {
|
|
387
|
+
const img = document.createElement('img');
|
|
388
|
+
img.className = 'waveform-artwork';
|
|
389
|
+
img.style.width = '40px';
|
|
390
|
+
img.style.height = '40px';
|
|
391
|
+
img.style.borderRadius = '4px';
|
|
392
|
+
img.style.objectFit = 'cover';
|
|
393
|
+
img.style.flexShrink = '0';
|
|
394
|
+
this.bindArtworkFallback(img);
|
|
395
|
+
return img;
|
|
396
|
+
}
|
|
397
|
+
|
|
398
|
+
/**
|
|
399
|
+
* Create an artist text element matching the initial player markup.
|
|
400
|
+
*
|
|
401
|
+
* @returns {HTMLSpanElement} Artist text element.
|
|
402
|
+
* @private
|
|
403
|
+
*/
|
|
404
|
+
createArtistElement() {
|
|
405
|
+
const span = document.createElement('span');
|
|
406
|
+
span.className = 'waveform-artist';
|
|
407
|
+
return span;
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
/**
|
|
411
|
+
* Reconcile artist metadata and markup for the current track.
|
|
412
|
+
*
|
|
413
|
+
* @param {string|null} artist - Artist text, or a falsy value to remove it.
|
|
414
|
+
* @private
|
|
415
|
+
*/
|
|
416
|
+
syncArtist(artist) {
|
|
417
|
+
this.options.artist = artist || null;
|
|
418
|
+
|
|
419
|
+
if (!this.options.showInfo) return;
|
|
420
|
+
|
|
421
|
+
if (!artist) {
|
|
422
|
+
this.artistEl?.remove();
|
|
423
|
+
this.artistEl = null;
|
|
424
|
+
return;
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
if (!this.artistEl) {
|
|
428
|
+
const titleEl = this.container.querySelector('.waveform-title');
|
|
429
|
+
if (!titleEl) return;
|
|
430
|
+
this.artistEl = this.createArtistElement();
|
|
431
|
+
titleEl.after(this.artistEl);
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
this.artistEl.textContent = artist;
|
|
435
|
+
this.artistEl.style.display = '';
|
|
436
|
+
}
|
|
437
|
+
|
|
438
|
+
/**
|
|
439
|
+
* Reconcile artwork metadata and markup for the current track.
|
|
440
|
+
*
|
|
441
|
+
* @param {string|null} artwork - Artwork image URL, or a falsy value to remove artwork.
|
|
442
|
+
* @param {string} artworkAlt - Artwork alt text.
|
|
443
|
+
* @private
|
|
444
|
+
*/
|
|
445
|
+
syncArtwork(artwork, artworkAlt = '') {
|
|
446
|
+
this.options.artwork = artwork || null;
|
|
447
|
+
this.options.artworkAlt = artworkAlt || '';
|
|
448
|
+
|
|
449
|
+
if (!this.options.showInfo) return;
|
|
450
|
+
|
|
451
|
+
if (!artwork) {
|
|
452
|
+
this.artworkEl?.remove();
|
|
453
|
+
this.artworkEl = null;
|
|
454
|
+
return;
|
|
455
|
+
}
|
|
456
|
+
|
|
457
|
+
if (!this.artworkEl) {
|
|
458
|
+
const textEl = this.container.querySelector('.waveform-text');
|
|
459
|
+
if (!textEl) return;
|
|
460
|
+
this.artworkEl = this.createArtworkElement();
|
|
461
|
+
textEl.before(this.artworkEl);
|
|
462
|
+
}
|
|
463
|
+
|
|
464
|
+
this.artworkEl.src = artwork;
|
|
465
|
+
this.artworkEl.alt = artworkAlt || '';
|
|
466
|
+
}
|
|
467
|
+
|
|
369
468
|
/**
|
|
370
469
|
* Create audio element
|
|
371
470
|
* @private
|
|
@@ -722,7 +821,11 @@ export class WaveformPlayer {
|
|
|
722
821
|
this.seekEl.setAttribute('aria-valuenow', String(Math.round(current)));
|
|
723
822
|
this.seekEl.setAttribute(
|
|
724
823
|
'aria-valuetext',
|
|
725
|
-
|
|
824
|
+
formatSeekValueText(
|
|
825
|
+
this.options.seekValueText || '%1$s of %2$s',
|
|
826
|
+
formatTime(current),
|
|
827
|
+
formatTime(duration)
|
|
828
|
+
)
|
|
726
829
|
);
|
|
727
830
|
}
|
|
728
831
|
|
|
@@ -770,7 +873,7 @@ export class WaveformPlayer {
|
|
|
770
873
|
_applyMediaMetadata() {
|
|
771
874
|
if (!('mediaSession' in navigator) || !this.options.enableMediaSession) return;
|
|
772
875
|
navigator.mediaSession.metadata = new MediaMetadata({
|
|
773
|
-
title: this.options.title ||
|
|
876
|
+
title: this.options.title || this.options.unknownTrackText,
|
|
774
877
|
artist: this.options.artist || '',
|
|
775
878
|
album: this.options.album || '',
|
|
776
879
|
artwork: this.options.artwork ? [
|
|
@@ -1040,10 +1143,13 @@ export class WaveformPlayer {
|
|
|
1040
1143
|
* @param {string|null} [artist=null] - Track artist; pass `''` to hide
|
|
1041
1144
|
* the artist row, or null to keep the existing one.
|
|
1042
1145
|
* @param {Object} [options={}] - Additional options to merge (e.g.
|
|
1043
|
-
* `preload`, `artwork`, `markers`, `autoplay`).
|
|
1146
|
+
* `preload`, `artwork`, `artworkAlt`, `markers`, `autoplay`).
|
|
1044
1147
|
* @returns {Promise<void>}
|
|
1045
1148
|
*/
|
|
1046
1149
|
async loadTrack(url, title = null, artist = null, options = {}) {
|
|
1150
|
+
const hasArtworkOption = Object.prototype.hasOwnProperty.call(options, 'artwork');
|
|
1151
|
+
const hasArtworkAltOption = Object.prototype.hasOwnProperty.call(options, 'artworkAlt');
|
|
1152
|
+
|
|
1047
1153
|
// Stop current playback and clear state
|
|
1048
1154
|
if (this.isPlaying) {
|
|
1049
1155
|
this.pause();
|
|
@@ -1074,29 +1180,37 @@ export class WaveformPlayer {
|
|
|
1074
1180
|
// Update options (including preload if specified)
|
|
1075
1181
|
this.options = mergeOptions(this.options, {
|
|
1076
1182
|
url,
|
|
1077
|
-
title: title
|
|
1078
|
-
artist: artist
|
|
1183
|
+
title: title === null ? this.options.title : title,
|
|
1184
|
+
artist: artist === null ? this.options.artist : artist,
|
|
1079
1185
|
...options
|
|
1080
1186
|
});
|
|
1187
|
+
if (hasArtworkOption) {
|
|
1188
|
+
this.options.artwork = options.artwork || null;
|
|
1189
|
+
}
|
|
1190
|
+
if (hasArtworkAltOption) {
|
|
1191
|
+
this.options.artworkAlt = options.artworkAlt || '';
|
|
1192
|
+
} else if (hasArtworkOption) {
|
|
1193
|
+
this.options.artworkAlt = this.options.artwork ? DEFAULT_OPTIONS.artworkAlt : '';
|
|
1194
|
+
}
|
|
1081
1195
|
|
|
1082
1196
|
// Apply preload setting if it was changed
|
|
1083
1197
|
if (options.preload && this.audio) {
|
|
1084
1198
|
this.audio.preload = options.preload;
|
|
1085
1199
|
}
|
|
1086
1200
|
|
|
1087
|
-
// Update
|
|
1088
|
-
|
|
1089
|
-
|
|
1090
|
-
|
|
1091
|
-
this.artistEl.style.display = '';
|
|
1092
|
-
} else if (artist === '') {
|
|
1093
|
-
this.artistEl.style.display = 'none';
|
|
1094
|
-
}
|
|
1201
|
+
// Update artist only when explicitly provided. A null artist keeps the
|
|
1202
|
+
// existing artist, while an empty string removes it.
|
|
1203
|
+
if (artist !== null) {
|
|
1204
|
+
this.syncArtist(artist);
|
|
1095
1205
|
}
|
|
1096
1206
|
|
|
1097
|
-
// Update artwork
|
|
1098
|
-
|
|
1099
|
-
|
|
1207
|
+
// Update artwork when explicitly provided. The caller can pass an empty
|
|
1208
|
+
// value to remove existing artwork from the in-place player.
|
|
1209
|
+
if (hasArtworkOption || hasArtworkAltOption) {
|
|
1210
|
+
this.syncArtwork(
|
|
1211
|
+
hasArtworkOption ? options.artwork : this.options.artwork,
|
|
1212
|
+
hasArtworkAltOption ? options.artworkAlt : this.options.artworkAlt
|
|
1213
|
+
);
|
|
1100
1214
|
}
|
|
1101
1215
|
|
|
1102
1216
|
// Clear or update markers
|
|
@@ -2261,4 +2375,4 @@ export class WaveformPlayer {
|
|
|
2261
2375
|
return swapped === audioUrl ? undefined : swapped;
|
|
2262
2376
|
}
|
|
2263
2377
|
|
|
2264
|
-
}
|
|
2378
|
+
}
|
package/src/js/themes.js
CHANGED
|
@@ -226,8 +226,13 @@ export const DEFAULT_OPTIONS = {
|
|
|
226
226
|
// (role="slider" + ARIA value attributes + arrow/page/home/end seeking).
|
|
227
227
|
// seekLabel sets the slider's accessible name; when null it falls back
|
|
228
228
|
// to the track title, then 'Seek'.
|
|
229
|
+
// seekValueText templates the slider's spoken aria-valuetext: %1$s is the
|
|
230
|
+
// current time and %2$s the total duration (both formatted M:SS). When null
|
|
231
|
+
// it falls back to '%1$s of %2$s'. Lets consumers localize the connective
|
|
232
|
+
// text without reformatting the times.
|
|
229
233
|
accessibleSeek: true,
|
|
230
234
|
seekLabel: null,
|
|
235
|
+
seekValueText: null,
|
|
231
236
|
|
|
232
237
|
// Content
|
|
233
238
|
title: null,
|
|
@@ -238,6 +243,16 @@ export const DEFAULT_OPTIONS = {
|
|
|
238
243
|
// Message shown in the error state when audio fails to load.
|
|
239
244
|
errorText: 'Unable to load audio',
|
|
240
245
|
|
|
246
|
+
// Localizable UI strings (alongside seekLabel / seekValueText / errorText).
|
|
247
|
+
// These are screen-reader / assistive-tech facing, so translate them for
|
|
248
|
+
// non-English UIs. playPauseLabel/speedLabel are aria-labels; artworkAlt is
|
|
249
|
+
// the cover image alt text; unknownTrackText is the Media Session (lock-
|
|
250
|
+
// screen) title fallback used when no track title is set.
|
|
251
|
+
playPauseLabel: 'Play/Pause',
|
|
252
|
+
speedLabel: 'Playback speed',
|
|
253
|
+
artworkAlt: 'Album artwork',
|
|
254
|
+
unknownTrackText: 'Unknown Track',
|
|
255
|
+
|
|
241
256
|
// Icons (SVG)
|
|
242
257
|
playIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M8 5v14l11-7z"/></svg>',
|
|
243
258
|
pauseIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M6 4h4v16H6zM14 4h4v16h-4z"/></svg>',
|
package/src/js/utils.js
CHANGED
|
@@ -220,8 +220,15 @@ export function parseDataAttributes(element) {
|
|
|
220
220
|
// Accessibility
|
|
221
221
|
setBool('accessibleSeek');
|
|
222
222
|
if (element.dataset.seekLabel) options.seekLabel = element.dataset.seekLabel;
|
|
223
|
+
if (element.dataset.seekValueText) options.seekValueText = element.dataset.seekValueText;
|
|
223
224
|
if (element.dataset.errorText) options.errorText = element.dataset.errorText;
|
|
224
225
|
|
|
226
|
+
// Localizable UI strings (screen-reader / lock-screen facing)
|
|
227
|
+
if (element.dataset.playPauseLabel) options.playPauseLabel = element.dataset.playPauseLabel;
|
|
228
|
+
if (element.dataset.speedLabel) options.speedLabel = element.dataset.speedLabel;
|
|
229
|
+
if (element.dataset.artworkAlt) options.artworkAlt = element.dataset.artworkAlt;
|
|
230
|
+
if (element.dataset.unknownTrackText) options.unknownTrackText = element.dataset.unknownTrackText;
|
|
231
|
+
|
|
225
232
|
// Custom icons (raw SVG markup)
|
|
226
233
|
if (element.dataset.playIcon) options.playIcon = element.dataset.playIcon;
|
|
227
234
|
if (element.dataset.pauseIcon) options.pauseIcon = element.dataset.pauseIcon;
|
|
@@ -229,6 +236,25 @@ export function parseDataAttributes(element) {
|
|
|
229
236
|
return options;
|
|
230
237
|
}
|
|
231
238
|
|
|
239
|
+
/**
|
|
240
|
+
* Interpolate a printf-style seek value-text template.
|
|
241
|
+
*
|
|
242
|
+
* Substitutes positional (`%1$s`, `%2$s`) and sequential (`%s`) placeholders so
|
|
243
|
+
* a localized template resolves the same way `sprintf` would — including
|
|
244
|
+
* templates that reorder the arguments for a given language. Placeholders with
|
|
245
|
+
* no matching argument are left intact.
|
|
246
|
+
* @param {string} template - Value-text template, e.g. `'%1$s of %2$s'`.
|
|
247
|
+
* @param {...string} args - Replacement values, in order (current, duration).
|
|
248
|
+
* @returns {string} The interpolated value text.
|
|
249
|
+
*/
|
|
250
|
+
export function formatSeekValueText(template, ...args) {
|
|
251
|
+
let sequentialIndex = 0;
|
|
252
|
+
return template.replace(/%(?:(\d+)\$)?s/g, (match, position) => {
|
|
253
|
+
const index = position ? Number(position) - 1 : sequentialIndex++;
|
|
254
|
+
return args[index] ?? match;
|
|
255
|
+
});
|
|
256
|
+
}
|
|
257
|
+
|
|
232
258
|
/**
|
|
233
259
|
* Format a duration as a clock string.
|
|
234
260
|
*
|