@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/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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.19.3",
3
+ "version": "1.21.0",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
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="Play/Pause"${this.options.buttonSize != null ? ` style="--wfp-btn-size: ${typeof this.options.buttonSize === 'number' ? `${this.options.buttonSize}px` : this.options.buttonSize};"` : ''}>
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="Album artwork" style="
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="Playback speed" aria-haspopup="menu" aria-expanded="false">
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="Playback speed" style="display: none;">
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
- if (this.artworkEl) {
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
- `${formatTime(current)} of ${formatTime(duration)}`
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 || 'Unknown Track',
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 || this.options.title,
1078
- artist: artist || this.options.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 UI elements
1088
- if (this.artistEl) {
1089
- if (artist) {
1090
- this.artistEl.textContent = artist;
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 if provided
1098
- if (options.artwork && this.artworkEl) {
1099
- this.artworkEl.src = options.artwork;
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
  *