@arraypress/waveform-player 1.19.1 → 1.20.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.1",
3
+ "version": "1.20.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('')}
@@ -722,7 +723,11 @@ export class WaveformPlayer {
722
723
  this.seekEl.setAttribute('aria-valuenow', String(Math.round(current)));
723
724
  this.seekEl.setAttribute(
724
725
  'aria-valuetext',
725
- `${formatTime(current)} of ${formatTime(duration)}`
726
+ formatSeekValueText(
727
+ this.options.seekValueText || '%1$s of %2$s',
728
+ formatTime(current),
729
+ formatTime(duration)
730
+ )
726
731
  );
727
732
  }
728
733
 
@@ -770,7 +775,7 @@ export class WaveformPlayer {
770
775
  _applyMediaMetadata() {
771
776
  if (!('mediaSession' in navigator) || !this.options.enableMediaSession) return;
772
777
  navigator.mediaSession.metadata = new MediaMetadata({
773
- title: this.options.title || 'Unknown Track',
778
+ title: this.options.title || this.options.unknownTrackText,
774
779
  artist: this.options.artist || '',
775
780
  album: this.options.album || '',
776
781
  artwork: this.options.artwork ? [
@@ -1392,12 +1397,18 @@ export class WaveformPlayer {
1392
1397
  this.progress = clamp((clientX - rect.left) / rect.width);
1393
1398
  this.drawWaveform();
1394
1399
  this._updateSeekHandle();
1395
- this._updateHoverTip(clientX);
1396
1400
  // Live time readout while scrubbing (Spotify-style): the audio keeps
1397
1401
  // playing at its old position; the display shows where release lands.
1398
1402
  const dur = this.getSeekDuration();
1399
1403
  if (dur && this.currentTimeEl) {
1400
1404
  this.currentTimeEl.textContent = formatTime(this.progress * dur);
1405
+ // The current-time already shows the target — don't also pop the
1406
+ // hover tooltip with the same value (that duplicate is the bug).
1407
+ this._hideHoverTip();
1408
+ } else {
1409
+ // No current-time readout to fall back on — keep the tooltip as the
1410
+ // only scrub feedback.
1411
+ this._updateHoverTip(clientX);
1401
1412
  }
1402
1413
  }
1403
1414
 
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
  *