@arraypress/waveform-player 1.21.0 → 1.23.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
@@ -35,6 +35,15 @@ export type AudioMode = 'self' | 'external';
35
35
  /** Browser preload hint for the underlying `<audio>` element. */
36
36
  export type AudioPreload = 'auto' | 'metadata' | 'none';
37
37
 
38
+ /**
39
+ * CORS mode for the underlying `<audio>` element. Left unset by default so the
40
+ * player behaves like a plain `<audio>` and never forces a CORS request. Set
41
+ * `'anonymous'` / `'use-credentials'` only if you specifically need it — doing
42
+ * so breaks playback of media hosted on origins that don't send
43
+ * `Access-Control-Allow-Origin` (e.g. default-config S3/CDN).
44
+ */
45
+ export type AudioCrossOrigin = 'anonymous' | 'use-credentials';
46
+
38
47
  /** Vertical alignment of the play button relative to the waveform. */
39
48
  export type ButtonAlign = 'auto' | 'top' | 'center' | 'bottom';
40
49
 
@@ -83,6 +92,13 @@ export interface WaveformPlayerOptions {
83
92
  samples?: number;
84
93
  /** `<audio>` preload hint. @default 'metadata' */
85
94
  preload?: AudioPreload;
95
+ /**
96
+ * `<audio>` CORS mode. Unset by default so the player behaves like a plain
97
+ * `<audio>` and never forces a CORS request (which breaks playback of media
98
+ * on origins without `Access-Control-Allow-Origin`). Set only if you need it.
99
+ * @default null
100
+ */
101
+ crossOrigin?: AudioCrossOrigin | null;
86
102
  /** Whether the player owns its `<audio>` or delegates to an external controller. @default 'self' */
87
103
  audioMode?: AudioMode;
88
104
  /** Pre-computed peaks (array, .json URL, or JSON string). Skips Web Audio decoding when provided. */
@@ -145,8 +161,28 @@ export interface WaveformPlayerOptions {
145
161
  * @default null
146
162
  */
147
163
  buttonSize?: number | string | null;
164
+ /**
165
+ * Play/pause button corner radius. A number is treated as px; a string (e.g.
166
+ * `'8px'`) is used verbatim. Set `0` for a square button. Sets the
167
+ * `--wfp-btn-radius` CSS variable, shaping the `circle` style's box — the
168
+ * bare `minimal` glyph has no box to round.
169
+ * @default null
170
+ */
171
+ buttonRadius?: number | string | null;
148
172
  /** Show transport controls. @default true */
149
173
  showControls?: boolean;
174
+ /**
175
+ * Where the `artwork` image renders. `'info'` places it in the info row
176
+ * beside the title (requires `showInfo`); `'button'` makes the cover the
177
+ * play/pause button, which still works when the info row is hidden. Only one
178
+ * placement ever renders, so the cover cannot appear twice.
179
+ *
180
+ * `'button'` needs no other options: it drops the button's ring and uses
181
+ * cover-sized defaults (64px, 8px rounding) rather than the transport
182
+ * button's 36px circle. Set `buttonSize` / `buttonRadius` to override.
183
+ * @default 'info'
184
+ */
185
+ artworkPosition?: 'info' | 'button';
150
186
  /** Show the info (title/artist) block. @default true */
151
187
  showInfo?: boolean;
152
188
  /** Show current/total time. @default true */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.21.0",
3
+ "version": "1.23.0",
4
4
  "description": "Lightweight, customizable audio player with waveform visualization",
5
5
  "type": "module",
6
6
  "types": "./index.d.ts",
@@ -12,6 +12,17 @@
12
12
  --wfp-button-color: rgba(255, 255, 255, 0.9);
13
13
  --wfp-text-color: #ffffff;
14
14
  --wfp-text-secondary-color: rgba(255, 255, 255, 0.6);
15
+
16
+ /* Play-button artwork (artworkPosition: 'button'). Deliberately NOT
17
+ re-themed for light pages below: the cover underneath is an arbitrary
18
+ image, so a light page tells us nothing about it — flipping the glyph
19
+ dark is exactly the unreadable case. This surface is always dark, so it
20
+ always takes the dark treatment (same value as --wfp-button-color's dark
21
+ form). The scrim earns its keep: at 0.5 a 0.9-white glyph clears 3:1
22
+ (WCAG 1.4.11) against even a pure-white cover; any darker cover is
23
+ better. Re-theme both together or the contrast guarantee goes with it. */
24
+ --wfp-btn-artwork-color: rgba(255, 255, 255, 0.9);
25
+ --wfp-btn-artwork-scrim: rgba(0, 0, 0, 0.5);
15
26
  }
16
27
 
17
28
  /* Light theme — the player adds .waveform-theme-light when it detects a light
@@ -50,7 +61,7 @@
50
61
  width: var(--wfp-btn-size, 36px);
51
62
  height: var(--wfp-btn-size, 36px);
52
63
  min-width: var(--wfp-btn-size, 36px);
53
- border-radius: 50%;
64
+ border-radius: var(--wfp-btn-radius, 50%);
54
65
  border: 2px solid currentColor;
55
66
  background: transparent;
56
67
  color: var(--wfp-button-color, inherit);
@@ -121,6 +132,56 @@
121
132
  display: block;
122
133
  }
123
134
 
135
+ /* Play-button artwork — in cover mode the artwork IS the control, so the
136
+ button's own chrome gets out of its way: no ring, and cover-sized defaults.
137
+ The transport button's defaults are wrong for a cover in both directions —
138
+ 36px shrinks album art to a smudge, and 50% rounding crops a square cover
139
+ into a circle — and neither is a look worth making anyone opt out of.
140
+
141
+ These are declared as var DEFAULTS, not fixed values: `buttonSize` and
142
+ `buttonRadius` land as inline custom properties on the element, and inline
143
+ beats a stylesheet rule, so an explicit option still wins. `overflow: hidden`
144
+ clips the cover to the radius (an outline paints outside the border box, so
145
+ the focus ring survives the clip). */
146
+ .waveform-btn-has-artwork {
147
+ --wfp-btn-size: 64px;
148
+ --wfp-btn-radius: 8px;
149
+ position: relative;
150
+ overflow: hidden;
151
+ border: none;
152
+ color: var(--wfp-btn-artwork-color);
153
+ }
154
+
155
+ /* NOTE: must out-specify `.waveform-btn > * { display: flex; … }` above, which
156
+ ties on specificity and would otherwise flex the image. The compound
157
+ `.waveform-btn > .waveform-btn-artwork` wins outright. */
158
+ .waveform-btn > .waveform-btn-artwork {
159
+ display: block;
160
+ position: absolute;
161
+ inset: 0;
162
+ width: 100%;
163
+ height: 100%;
164
+ object-fit: cover;
165
+ pointer-events: none;
166
+ z-index: 0;
167
+ }
168
+
169
+ /* The scrim. Generated content paints after the element's children, so without
170
+ the z-index ladder here it would bury the glyph it exists to make readable. */
171
+ .waveform-btn-has-artwork::after {
172
+ content: "";
173
+ position: absolute;
174
+ inset: 0;
175
+ background: var(--wfp-btn-artwork-scrim);
176
+ pointer-events: none;
177
+ z-index: 1;
178
+ }
179
+
180
+ .waveform-btn-has-artwork > :not(.waveform-btn-artwork) {
181
+ position: relative;
182
+ z-index: 2;
183
+ }
184
+
124
185
  .waveform-icon-play svg {
125
186
  margin-left: 1px;
126
187
  }
@@ -480,10 +541,14 @@
480
541
 
481
542
  /* Responsive adjustments */
482
543
  @media (max-width: 480px) {
544
+ /* Narrow-screen default only — must stay var-driven. Hardcoding the width
545
+ here silently beat `buttonSize` (equal specificity, later source order),
546
+ so a 64px button collapsed to 32px on a phone; a cover tile would have
547
+ collapsed with it. The fallback still gives an unset button its 32px. */
483
548
  .waveform-btn {
484
- width: 32px;
485
- height: 32px;
486
- min-width: 32px;
549
+ width: var(--wfp-btn-size, 32px);
550
+ height: var(--wfp-btn-size, 32px);
551
+ min-width: var(--wfp-btn-size, 32px);
487
552
  }
488
553
 
489
554
  .waveform-container {
package/src/js/core.js CHANGED
@@ -15,6 +15,7 @@ import {
15
15
  debounce,
16
16
  clamp,
17
17
  escapeHtml,
18
+ formatCssLength,
18
19
  DEFAULT_SAMPLES
19
20
  } from './utils.js';
20
21
 
@@ -264,9 +265,30 @@ export class WaveformPlayer {
264
265
  }
265
266
  this.container.classList.toggle('waveform-theme-light', this._scheme === 'light');
266
267
 
268
+ // Button sizing/shape ride in on CSS vars so the stylesheet keeps the
269
+ // fallbacks (36px, 50%) — an unset option emits no var at all.
270
+ const buttonVars = [];
271
+ if (this.options.buttonSize != null) {
272
+ buttonVars.push(`--wfp-btn-size: ${formatCssLength(this.options.buttonSize)}`);
273
+ }
274
+ if (this.options.buttonRadius != null) {
275
+ buttonVars.push(`--wfp-btn-radius: ${formatCssLength(this.options.buttonRadius)}`);
276
+ }
277
+ const buttonStyleAttr = buttonVars.length ? ` style="${buttonVars.join('; ')};"` : '';
278
+
279
+ // Artwork renders in exactly one place — the button or the info row —
280
+ // so the same cover can never appear twice. Button artwork is
281
+ // decorative: the button already carries its own aria-label, so a
282
+ // second accessible name here would just be noise.
283
+ const artworkOnButton = this.options.artworkPosition === 'button' && this.options.artwork;
284
+ const buttonArtworkHTML = artworkOnButton
285
+ ? `<img class="waveform-btn-artwork" src="${escapeHtml(this.options.artwork)}" alt="" aria-hidden="true">`
286
+ : '';
287
+
267
288
  // Build play button HTML (conditional)
268
289
  const buttonHTML = this.options.showControls ? `
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};"` : ''}>
290
+ <button class="waveform-btn${this.options.buttonStyle === 'minimal' ? ' waveform-btn-minimal' : ''}${artworkOnButton ? ' waveform-btn-has-artwork' : ''}" aria-label="${escapeHtml(this.options.playPauseLabel)}"${buttonStyleAttr}>
291
+ ${buttonArtworkHTML}
270
292
  <span class="waveform-icon-play">${this.options.playIcon}</span>
271
293
  <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
272
294
  </button>
@@ -275,8 +297,8 @@ export class WaveformPlayer {
275
297
  // Build info section HTML (conditional)
276
298
  const infoHTML = this.options.showInfo ? `
277
299
  <div class="waveform-info">
278
- ${this.options.artwork ? `
279
- <img class="waveform-artwork" src="${this.options.artwork}" alt="${escapeHtml(this.options.artworkAlt)}" style="
300
+ ${this.options.artworkPosition !== 'button' && this.options.artwork ? `
301
+ <img class="waveform-artwork" src="${escapeHtml(this.options.artwork)}" alt="${escapeHtml(this.options.artworkAlt)}" style="
280
302
  width: 40px;
281
303
  height: 40px;
282
304
  border-radius: 4px;
@@ -286,7 +308,7 @@ export class WaveformPlayer {
286
308
  ` : ''}
287
309
  <div class="waveform-text">
288
310
  <span class="waveform-title"></span>
289
- ${this.options.artist ? `<span class="waveform-artist">${this.options.artist}</span>` : ''}
311
+ ${this.options.artist ? `<span class="waveform-artist">${escapeHtml(this.options.artist)}</span>` : ''}
290
312
  </div>
291
313
  <div class="waveform-meta" style="display: flex; align-items: center; gap: 1rem;">
292
314
  ${this.options.showBPM ? `
@@ -343,7 +365,10 @@ export class WaveformPlayer {
343
365
  this.ctx = this.canvas.getContext('2d');
344
366
  this.titleEl = this.container.querySelector('.waveform-title');
345
367
  this.artistEl = this.container.querySelector('.waveform-artist');
346
- this.artworkEl = this.container.querySelector('.waveform-artwork');
368
+ // One reference for either placement — artworkPosition is structural
369
+ // (like showInfo/buttonStyle) and fixed for the player's lifetime, so
370
+ // the image only ever has one home.
371
+ this.artworkEl = this.container.querySelector('.waveform-artwork, .waveform-btn-artwork');
347
372
  this.bindArtworkFallback(this.artworkEl);
348
373
  this.currentTimeEl = this.container.querySelector('.time-current');
349
374
  this.totalTimeEl = this.container.querySelector('.time-total');
@@ -395,6 +420,25 @@ export class WaveformPlayer {
395
420
  return img;
396
421
  }
397
422
 
423
+ /**
424
+ * Create a play-button artwork image matching the initial player markup.
425
+ *
426
+ * Decorative by design — the button already has an accessible name from its
427
+ * `aria-label`, so the cover is hidden from assistive tech rather than
428
+ * given a competing one. Sizing and clipping are the stylesheet's job.
429
+ *
430
+ * @returns {HTMLImageElement} Play-button artwork image element.
431
+ * @private
432
+ */
433
+ createButtonArtworkElement() {
434
+ const img = document.createElement('img');
435
+ img.className = 'waveform-btn-artwork';
436
+ img.alt = '';
437
+ img.setAttribute('aria-hidden', 'true');
438
+ this.bindArtworkFallback(img);
439
+ return img;
440
+ }
441
+
398
442
  /**
399
443
  * Create an artist text element matching the initial player markup.
400
444
  *
@@ -435,17 +479,58 @@ export class WaveformPlayer {
435
479
  this.artistEl.style.display = '';
436
480
  }
437
481
 
482
+ /**
483
+ * Reconcile the play button's artwork image (`artworkPosition: 'button'`).
484
+ *
485
+ * Shares {@link bindArtworkFallback} with the info-row image, so a broken
486
+ * cover degrades to the same placeholder tile in either placement. The
487
+ * `waveform-btn-has-artwork` class is what turns on the scrim + glyph
488
+ * treatment, so it tracks the image's presence exactly.
489
+ *
490
+ * @param {string|null} artwork - Artwork image URL, or a falsy value to remove it.
491
+ * @private
492
+ */
493
+ syncButtonArtwork(artwork) {
494
+ // Nothing to hang the cover on when the transport is hidden.
495
+ if (!this.playBtn) return;
496
+
497
+ if (!artwork) {
498
+ this.artworkEl?.remove();
499
+ this.artworkEl = null;
500
+ this.playBtn.classList.remove('waveform-btn-has-artwork');
501
+ return;
502
+ }
503
+
504
+ if (!this.artworkEl) {
505
+ this.artworkEl = this.createButtonArtworkElement();
506
+ this.playBtn.prepend(this.artworkEl);
507
+ }
508
+
509
+ this.artworkEl.src = artwork;
510
+ this.playBtn.classList.add('waveform-btn-has-artwork');
511
+ }
512
+
438
513
  /**
439
514
  * Reconcile artwork metadata and markup for the current track.
440
515
  *
516
+ * The image lives in one of two homes depending on `artworkPosition` — the
517
+ * info row (default) or the play button — and only ever one of them, so a
518
+ * cover can't render twice.
519
+ *
441
520
  * @param {string|null} artwork - Artwork image URL, or a falsy value to remove artwork.
442
- * @param {string} artworkAlt - Artwork alt text.
521
+ * @param {string} artworkAlt - Artwork alt text. Info-row placement only:
522
+ * button artwork is decorative and defers to the button's own label.
443
523
  * @private
444
524
  */
445
525
  syncArtwork(artwork, artworkAlt = '') {
446
526
  this.options.artwork = artwork || null;
447
527
  this.options.artworkAlt = artworkAlt || '';
448
528
 
529
+ if (this.options.artworkPosition === 'button') {
530
+ this.syncButtonArtwork(this.options.artwork);
531
+ return;
532
+ }
533
+
449
534
  if (!this.options.showInfo) return;
450
535
 
451
536
  if (!artwork) {
@@ -482,7 +567,13 @@ export class WaveformPlayer {
482
567
  }
483
568
  this.audio = new Audio();
484
569
  this.audio.preload = this.options.preload || 'metadata';
485
- this.audio.crossOrigin = 'anonymous';
570
+ // Only set crossOrigin when explicitly opted in. Setting it forces a
571
+ // CORS request that breaks playback of media on origins without
572
+ // Access-Control-Allow-Origin; the player never needs CORS-clean media
573
+ // for playback (no createMediaElementSource). See issue #18.
574
+ if (this.options.crossOrigin) {
575
+ this.audio.crossOrigin = this.options.crossOrigin;
576
+ }
486
577
  }
487
578
 
488
579
  // ============================================
@@ -1198,6 +1289,11 @@ export class WaveformPlayer {
1198
1289
  this.audio.preload = options.preload;
1199
1290
  }
1200
1291
 
1292
+ // Apply crossOrigin if it was changed for this track
1293
+ if (options.crossOrigin && this.audio) {
1294
+ this.audio.crossOrigin = options.crossOrigin;
1295
+ }
1296
+
1201
1297
  // Update artist only when explicitly provided. A null artist keeps the
1202
1298
  // existing artist, while an empty string removes it.
1203
1299
  if (artist !== null) {
package/src/js/themes.js CHANGED
@@ -147,6 +147,15 @@ export const DEFAULT_OPTIONS = {
147
147
  // every-frame scan means a higher value costs no extra extraction time.
148
148
  samples: DEFAULT_SAMPLES,
149
149
  preload: 'metadata',
150
+ // CORS mode for the underlying <audio> element. Left null by default so the
151
+ // player behaves like a plain <audio> and never forces a CORS request —
152
+ // setting 'anonymous' here would break playback of media hosted on origins
153
+ // that don't send Access-Control-Allow-Origin (default-config S3/CDN). The
154
+ // playback element is never fed to createMediaElementSource, so it never
155
+ // needs CORS-clean media; peak analysis uses a separate fetch() path with
156
+ // its own placeholder fallback. Set 'anonymous' / 'use-credentials' only if
157
+ // you specifically need it. See issue #18.
158
+ crossOrigin: null,
150
159
 
151
160
  // Audio mode — 'self' = player owns the <audio> element (default, current
152
161
  // behavior). 'external' = player is a visualization-only surface; no audio
@@ -176,6 +185,12 @@ export const DEFAULT_OPTIONS = {
176
185
  // is used verbatim. Sets the `--wfp-btn-size` CSS var, which scales BOTH
177
186
  // styles — box and glyph — proportionally.
178
187
  buttonSize: null,
188
+ // Play/pause button corner radius. null = the stylesheet default (50%, a
189
+ // circle). A number is treated as px; a string (e.g. '8px') is used
190
+ // verbatim. Set 0 for a square button. Sets the `--wfp-btn-radius` CSS var,
191
+ // which shapes the 'circle' style's box — the bare 'minimal' glyph has no
192
+ // box to round, so this is a no-op there.
193
+ buttonRadius: null,
179
194
 
180
195
  // Default waveform style
181
196
  waveformStyle: 'mirror',
@@ -238,6 +253,17 @@ export const DEFAULT_OPTIONS = {
238
253
  title: null,
239
254
  artist: null,
240
255
  artwork: null,
256
+ // Where the `artwork` image renders. 'info' = the info row beside the title
257
+ // (needs showInfo). 'button' = the cover becomes the play/pause button,
258
+ // which still works with the info row hidden. Only ONE placement ever
259
+ // renders, so the same cover can't appear twice.
260
+ //
261
+ // 'button' is self-contained: the stylesheet drops the button's ring and
262
+ // swaps its defaults for cover-sized ones (64px, 8px rounding), because the
263
+ // transport defaults are wrong for artwork in both directions — 36px
264
+ // smudges a cover, and 50% crops square art into a circle. buttonSize /
265
+ // buttonRadius still override it if you want a different tile.
266
+ artworkPosition: 'info',
241
267
  album: '',
242
268
 
243
269
  // Message shown in the error state when audio fails to load.
package/src/js/utils.js CHANGED
@@ -42,6 +42,22 @@ export function escapeHtml(str) {
42
42
  .replace(/'/g, '&#39;');
43
43
  }
44
44
 
45
+ /**
46
+ * Format a CSS length option (`buttonSize`, `buttonRadius`) for interpolation
47
+ * into an inline `style` attribute. A number is treated as px; a string (e.g.
48
+ * `'4rem'`) is used verbatim.
49
+ *
50
+ * The result is HTML-escaped: these values reach the markup from author-supplied
51
+ * `data-*` attributes, so an unescaped quote would otherwise close the `style`
52
+ * attribute and let arbitrary markup in.
53
+ *
54
+ * @param {number|string} value - Length option value.
55
+ * @returns {string} Escaped CSS length, e.g. `36px` or `4rem`.
56
+ */
57
+ export function formatCssLength(value) {
58
+ return escapeHtml(typeof value === 'number' ? `${value}px` : value);
59
+ }
60
+
45
61
  /**
46
62
  * Whether a URL is safe to navigate to (assign to `location.href`): allows only
47
63
  * `http`/`https` and relative URLs, rejecting `javascript:`, `data:`, `blob:`,
@@ -134,6 +150,14 @@ export function parseDataAttributes(element) {
134
150
  if (raw) options[optKey] = float ? parseFloat(raw) : parseInt(raw, 10);
135
151
  };
136
152
 
153
+ // Read a CSS length attribute: a bare number is px (data-button-size="64"),
154
+ // a unit string (e.g. "4rem") is kept verbatim for the stylesheet to resolve.
155
+ const setLength = (optKey, dataKey = optKey) => {
156
+ const raw = element.dataset[dataKey];
157
+ if (!raw) return;
158
+ options[optKey] = /^\d+(\.\d+)?$/.test(raw.trim()) ? parseFloat(raw) : raw;
159
+ };
160
+
137
161
  // Parse a JSON-valued attribute defensively — warn and skip on bad JSON.
138
162
  const setJson = (optKey, dataKey = optKey) => {
139
163
  const raw = element.dataset[dataKey];
@@ -151,6 +175,9 @@ export function parseDataAttributes(element) {
151
175
  if (element.dataset.preload) {
152
176
  options.preload = element.dataset.preload;
153
177
  }
178
+ if (element.dataset.crossOrigin) {
179
+ options.crossOrigin = element.dataset.crossOrigin;
180
+ }
154
181
  if (element.dataset.audioMode) options.audioMode = element.dataset.audioMode;
155
182
 
156
183
  // Waveform style attributes. `data-style` is a shorthand alias for
@@ -164,12 +191,8 @@ export function parseDataAttributes(element) {
164
191
  if (element.dataset.buttonAlign) options.buttonAlign = element.dataset.buttonAlign;
165
192
  if (element.dataset.layout) options.layout = element.dataset.layout;
166
193
  if (element.dataset.buttonStyle) options.buttonStyle = element.dataset.buttonStyle;
167
- // buttonSize: a bare number is px (data-button-size="64"); a unit string
168
- // (e.g. "4rem") is kept verbatim.
169
- if (element.dataset.buttonSize) {
170
- const bs = element.dataset.buttonSize;
171
- options.buttonSize = /^\d+(\.\d+)?$/.test(bs.trim()) ? parseFloat(bs) : bs;
172
- }
194
+ setLength('buttonSize');
195
+ setLength('buttonRadius');
173
196
 
174
197
  // Color preset
175
198
  if (element.dataset.colorPreset) options.colorPreset = element.dataset.colorPreset;
@@ -199,6 +222,7 @@ export function parseDataAttributes(element) {
199
222
  if (element.dataset.artist) options.artist = element.dataset.artist;
200
223
  if (element.dataset.album) options.album = element.dataset.album;
201
224
  if (element.dataset.artwork) options.artwork = element.dataset.artwork;
225
+ if (element.dataset.artworkPosition) options.artworkPosition = element.dataset.artworkPosition;
202
226
 
203
227
  // Waveform data
204
228
  if (element.dataset.waveform) options.waveform = element.dataset.waveform;