@arraypress/waveform-player 1.20.0 → 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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@arraypress/waveform-player",
3
- "version": "1.20.0",
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
@@ -344,12 +344,7 @@ export class WaveformPlayer {
344
344
  this.titleEl = this.container.querySelector('.waveform-title');
345
345
  this.artistEl = this.container.querySelector('.waveform-artist');
346
346
  this.artworkEl = this.container.querySelector('.waveform-artwork');
347
- if (this.artworkEl) {
348
- // Fall back to the placeholder tile if the cover URL fails to load.
349
- this.artworkEl.addEventListener('error', () => {
350
- if (!this.artworkEl.src.startsWith('data:')) this.artworkEl.src = ARTWORK_FALLBACK;
351
- });
352
- }
347
+ this.bindArtworkFallback(this.artworkEl);
353
348
  this.currentTimeEl = this.container.querySelector('.time-current');
354
349
  this.totalTimeEl = this.container.querySelector('.time-total');
355
350
  this.bpmEl = this.container.querySelector('.waveform-bpm');
@@ -367,6 +362,109 @@ export class WaveformPlayer {
367
362
  this.updateBPMDisplay();
368
363
  }
369
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
+
370
468
  /**
371
469
  * Create audio element
372
470
  * @private
@@ -1045,10 +1143,13 @@ export class WaveformPlayer {
1045
1143
  * @param {string|null} [artist=null] - Track artist; pass `''` to hide
1046
1144
  * the artist row, or null to keep the existing one.
1047
1145
  * @param {Object} [options={}] - Additional options to merge (e.g.
1048
- * `preload`, `artwork`, `markers`, `autoplay`).
1146
+ * `preload`, `artwork`, `artworkAlt`, `markers`, `autoplay`).
1049
1147
  * @returns {Promise<void>}
1050
1148
  */
1051
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
+
1052
1153
  // Stop current playback and clear state
1053
1154
  if (this.isPlaying) {
1054
1155
  this.pause();
@@ -1079,29 +1180,37 @@ export class WaveformPlayer {
1079
1180
  // Update options (including preload if specified)
1080
1181
  this.options = mergeOptions(this.options, {
1081
1182
  url,
1082
- title: title || this.options.title,
1083
- artist: artist || this.options.artist,
1183
+ title: title === null ? this.options.title : title,
1184
+ artist: artist === null ? this.options.artist : artist,
1084
1185
  ...options
1085
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
+ }
1086
1195
 
1087
1196
  // Apply preload setting if it was changed
1088
1197
  if (options.preload && this.audio) {
1089
1198
  this.audio.preload = options.preload;
1090
1199
  }
1091
1200
 
1092
- // Update UI elements
1093
- if (this.artistEl) {
1094
- if (artist) {
1095
- this.artistEl.textContent = artist;
1096
- this.artistEl.style.display = '';
1097
- } else if (artist === '') {
1098
- this.artistEl.style.display = 'none';
1099
- }
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);
1100
1205
  }
1101
1206
 
1102
- // Update artwork if provided
1103
- if (options.artwork && this.artworkEl) {
1104
- 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
+ );
1105
1214
  }
1106
1215
 
1107
1216
  // Clear or update markers
@@ -2266,4 +2375,4 @@ export class WaveformPlayer {
2266
2375
  return swapped === audioUrl ? undefined : swapped;
2267
2376
  }
2268
2377
 
2269
- }
2378
+ }