@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.
@@ -128,11 +128,23 @@ function parseDataAttributes(element) {
128
128
  setBool("showMarkers");
129
129
  setBool("accessibleSeek");
130
130
  if (element.dataset.seekLabel) options.seekLabel = element.dataset.seekLabel;
131
+ if (element.dataset.seekValueText) options.seekValueText = element.dataset.seekValueText;
131
132
  if (element.dataset.errorText) options.errorText = element.dataset.errorText;
133
+ if (element.dataset.playPauseLabel) options.playPauseLabel = element.dataset.playPauseLabel;
134
+ if (element.dataset.speedLabel) options.speedLabel = element.dataset.speedLabel;
135
+ if (element.dataset.artworkAlt) options.artworkAlt = element.dataset.artworkAlt;
136
+ if (element.dataset.unknownTrackText) options.unknownTrackText = element.dataset.unknownTrackText;
132
137
  if (element.dataset.playIcon) options.playIcon = element.dataset.playIcon;
133
138
  if (element.dataset.pauseIcon) options.pauseIcon = element.dataset.pauseIcon;
134
139
  return options;
135
140
  }
141
+ function formatSeekValueText(template, ...args) {
142
+ let sequentialIndex = 0;
143
+ return template.replace(/%(?:(\d+)\$)?s/g, (match, position) => {
144
+ const index = position ? Number(position) - 1 : sequentialIndex++;
145
+ return args[index] ?? match;
146
+ });
147
+ }
136
148
  function formatTime(seconds) {
137
149
  if (!seconds || isNaN(seconds) || seconds < 0) return "0:00";
138
150
  const hrs = Math.floor(seconds / 3600);
@@ -752,8 +764,13 @@ var DEFAULT_OPTIONS = {
752
764
  // (role="slider" + ARIA value attributes + arrow/page/home/end seeking).
753
765
  // seekLabel sets the slider's accessible name; when null it falls back
754
766
  // to the track title, then 'Seek'.
767
+ // seekValueText templates the slider's spoken aria-valuetext: %1$s is the
768
+ // current time and %2$s the total duration (both formatted M:SS). When null
769
+ // it falls back to '%1$s of %2$s'. Lets consumers localize the connective
770
+ // text without reformatting the times.
755
771
  accessibleSeek: true,
756
772
  seekLabel: null,
773
+ seekValueText: null,
757
774
  // Content
758
775
  title: null,
759
776
  artist: null,
@@ -761,6 +778,15 @@ var DEFAULT_OPTIONS = {
761
778
  album: "",
762
779
  // Message shown in the error state when audio fails to load.
763
780
  errorText: "Unable to load audio",
781
+ // Localizable UI strings (alongside seekLabel / seekValueText / errorText).
782
+ // These are screen-reader / assistive-tech facing, so translate them for
783
+ // non-English UIs. playPauseLabel/speedLabel are aria-labels; artworkAlt is
784
+ // the cover image alt text; unknownTrackText is the Media Session (lock-
785
+ // screen) title fallback used when no track title is set.
786
+ playPauseLabel: "Play/Pause",
787
+ speedLabel: "Playback speed",
788
+ artworkAlt: "Album artwork",
789
+ unknownTrackText: "Unknown Track",
764
790
  // Icons (SVG)
765
791
  playIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M8 5v14l11-7z"/></svg>',
766
792
  pauseIcon: '<svg viewBox="0 0 24 24" width="16" height="16"><path d="M6 4h4v16H6zM14 4h4v16h-4z"/></svg>',
@@ -958,7 +984,7 @@ var WaveformPlayer = class _WaveformPlayer {
958
984
  }
959
985
  this.container.classList.toggle("waveform-theme-light", this._scheme === "light");
960
986
  const buttonHTML = this.options.showControls ? `
961
- <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};"` : ""}>
987
+ <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};"` : ""}>
962
988
  <span class="waveform-icon-play">${this.options.playIcon}</span>
963
989
  <span class="waveform-icon-pause" style="display:none;">${this.options.pauseIcon}</span>
964
990
  </button>
@@ -966,7 +992,7 @@ var WaveformPlayer = class _WaveformPlayer {
966
992
  const infoHTML = this.options.showInfo ? `
967
993
  <div class="waveform-info">
968
994
  ${this.options.artwork ? `
969
- <img class="waveform-artwork" src="${this.options.artwork}" alt="Album artwork" style="
995
+ <img class="waveform-artwork" src="${this.options.artwork}" alt="${escapeHtml(this.options.artworkAlt)}" style="
970
996
  width: 40px;
971
997
  height: 40px;
972
998
  border-radius: 4px;
@@ -986,10 +1012,10 @@ var WaveformPlayer = class _WaveformPlayer {
986
1012
  ` : ""}
987
1013
  ${this.options.showPlaybackSpeed ? `
988
1014
  <div class="waveform-speed">
989
- <button class="speed-btn" aria-label="Playback speed" aria-haspopup="menu" aria-expanded="false">
1015
+ <button class="speed-btn" aria-label="${escapeHtml(this.options.speedLabel)}" aria-haspopup="menu" aria-expanded="false">
990
1016
  <span class="speed-value">1x</span>
991
1017
  </button>
992
- <div class="speed-menu" role="menu" aria-label="Playback speed" style="display: none;">
1018
+ <div class="speed-menu" role="menu" aria-label="${escapeHtml(this.options.speedLabel)}" style="display: none;">
993
1019
  ${this.options.playbackRates.map(
994
1020
  (rate) => `<button class="speed-option" role="menuitemradio" tabindex="-1" aria-checked="false" data-rate="${rate}">${rate}x</button>`
995
1021
  ).join("")}
@@ -1030,11 +1056,7 @@ var WaveformPlayer = class _WaveformPlayer {
1030
1056
  this.titleEl = this.container.querySelector(".waveform-title");
1031
1057
  this.artistEl = this.container.querySelector(".waveform-artist");
1032
1058
  this.artworkEl = this.container.querySelector(".waveform-artwork");
1033
- if (this.artworkEl) {
1034
- this.artworkEl.addEventListener("error", () => {
1035
- if (!this.artworkEl.src.startsWith("data:")) this.artworkEl.src = ARTWORK_FALLBACK;
1036
- });
1037
- }
1059
+ this.bindArtworkFallback(this.artworkEl);
1038
1060
  this.currentTimeEl = this.container.querySelector(".time-current");
1039
1061
  this.totalTimeEl = this.container.querySelector(".time-total");
1040
1062
  this.bpmEl = this.container.querySelector(".waveform-bpm");
@@ -1047,6 +1069,94 @@ var WaveformPlayer = class _WaveformPlayer {
1047
1069
  this.resizeCanvas();
1048
1070
  this.updateBPMDisplay();
1049
1071
  }
1072
+ /**
1073
+ * Bind the artwork error fallback to an image element.
1074
+ *
1075
+ * @param {HTMLImageElement|null} img - Artwork image element.
1076
+ * @private
1077
+ */
1078
+ bindArtworkFallback(img) {
1079
+ if (!img) return;
1080
+ img.addEventListener("error", () => {
1081
+ if (!img.src.startsWith("data:")) img.src = ARTWORK_FALLBACK;
1082
+ }, { signal: this._ac.signal });
1083
+ }
1084
+ /**
1085
+ * Create an artwork image element matching the initial player markup.
1086
+ *
1087
+ * @returns {HTMLImageElement} Artwork image element.
1088
+ * @private
1089
+ */
1090
+ createArtworkElement() {
1091
+ const img = document.createElement("img");
1092
+ img.className = "waveform-artwork";
1093
+ img.style.width = "40px";
1094
+ img.style.height = "40px";
1095
+ img.style.borderRadius = "4px";
1096
+ img.style.objectFit = "cover";
1097
+ img.style.flexShrink = "0";
1098
+ this.bindArtworkFallback(img);
1099
+ return img;
1100
+ }
1101
+ /**
1102
+ * Create an artist text element matching the initial player markup.
1103
+ *
1104
+ * @returns {HTMLSpanElement} Artist text element.
1105
+ * @private
1106
+ */
1107
+ createArtistElement() {
1108
+ const span = document.createElement("span");
1109
+ span.className = "waveform-artist";
1110
+ return span;
1111
+ }
1112
+ /**
1113
+ * Reconcile artist metadata and markup for the current track.
1114
+ *
1115
+ * @param {string|null} artist - Artist text, or a falsy value to remove it.
1116
+ * @private
1117
+ */
1118
+ syncArtist(artist) {
1119
+ this.options.artist = artist || null;
1120
+ if (!this.options.showInfo) return;
1121
+ if (!artist) {
1122
+ this.artistEl?.remove();
1123
+ this.artistEl = null;
1124
+ return;
1125
+ }
1126
+ if (!this.artistEl) {
1127
+ const titleEl = this.container.querySelector(".waveform-title");
1128
+ if (!titleEl) return;
1129
+ this.artistEl = this.createArtistElement();
1130
+ titleEl.after(this.artistEl);
1131
+ }
1132
+ this.artistEl.textContent = artist;
1133
+ this.artistEl.style.display = "";
1134
+ }
1135
+ /**
1136
+ * Reconcile artwork metadata and markup for the current track.
1137
+ *
1138
+ * @param {string|null} artwork - Artwork image URL, or a falsy value to remove artwork.
1139
+ * @param {string} artworkAlt - Artwork alt text.
1140
+ * @private
1141
+ */
1142
+ syncArtwork(artwork, artworkAlt = "") {
1143
+ this.options.artwork = artwork || null;
1144
+ this.options.artworkAlt = artworkAlt || "";
1145
+ if (!this.options.showInfo) return;
1146
+ if (!artwork) {
1147
+ this.artworkEl?.remove();
1148
+ this.artworkEl = null;
1149
+ return;
1150
+ }
1151
+ if (!this.artworkEl) {
1152
+ const textEl = this.container.querySelector(".waveform-text");
1153
+ if (!textEl) return;
1154
+ this.artworkEl = this.createArtworkElement();
1155
+ textEl.before(this.artworkEl);
1156
+ }
1157
+ this.artworkEl.src = artwork;
1158
+ this.artworkEl.alt = artworkAlt || "";
1159
+ }
1050
1160
  /**
1051
1161
  * Create audio element
1052
1162
  * @private
@@ -1340,7 +1450,11 @@ var WaveformPlayer = class _WaveformPlayer {
1340
1450
  this.seekEl.setAttribute("aria-valuenow", String(Math.round(current)));
1341
1451
  this.seekEl.setAttribute(
1342
1452
  "aria-valuetext",
1343
- `${formatTime(current)} of ${formatTime(duration)}`
1453
+ formatSeekValueText(
1454
+ this.options.seekValueText || "%1$s of %2$s",
1455
+ formatTime(current),
1456
+ formatTime(duration)
1457
+ )
1344
1458
  );
1345
1459
  }
1346
1460
  /**
@@ -1382,7 +1496,7 @@ var WaveformPlayer = class _WaveformPlayer {
1382
1496
  _applyMediaMetadata() {
1383
1497
  if (!("mediaSession" in navigator) || !this.options.enableMediaSession) return;
1384
1498
  navigator.mediaSession.metadata = new MediaMetadata({
1385
- title: this.options.title || "Unknown Track",
1499
+ title: this.options.title || this.options.unknownTrackText,
1386
1500
  artist: this.options.artist || "",
1387
1501
  album: this.options.album || "",
1388
1502
  artwork: this.options.artwork ? [
@@ -1592,10 +1706,12 @@ var WaveformPlayer = class _WaveformPlayer {
1592
1706
  * @param {string|null} [artist=null] - Track artist; pass `''` to hide
1593
1707
  * the artist row, or null to keep the existing one.
1594
1708
  * @param {Object} [options={}] - Additional options to merge (e.g.
1595
- * `preload`, `artwork`, `markers`, `autoplay`).
1709
+ * `preload`, `artwork`, `artworkAlt`, `markers`, `autoplay`).
1596
1710
  * @returns {Promise<void>}
1597
1711
  */
1598
1712
  async loadTrack(url, title = null, artist = null, options = {}) {
1713
+ const hasArtworkOption = Object.prototype.hasOwnProperty.call(options, "artwork");
1714
+ const hasArtworkAltOption = Object.prototype.hasOwnProperty.call(options, "artworkAlt");
1599
1715
  if (this.isPlaying) {
1600
1716
  this.pause();
1601
1717
  }
@@ -1617,23 +1733,29 @@ var WaveformPlayer = class _WaveformPlayer {
1617
1733
  this.waveformData = [];
1618
1734
  this.options = mergeOptions(this.options, {
1619
1735
  url,
1620
- title: title || this.options.title,
1621
- artist: artist || this.options.artist,
1736
+ title: title === null ? this.options.title : title,
1737
+ artist: artist === null ? this.options.artist : artist,
1622
1738
  ...options
1623
1739
  });
1740
+ if (hasArtworkOption) {
1741
+ this.options.artwork = options.artwork || null;
1742
+ }
1743
+ if (hasArtworkAltOption) {
1744
+ this.options.artworkAlt = options.artworkAlt || "";
1745
+ } else if (hasArtworkOption) {
1746
+ this.options.artworkAlt = this.options.artwork ? DEFAULT_OPTIONS.artworkAlt : "";
1747
+ }
1624
1748
  if (options.preload && this.audio) {
1625
1749
  this.audio.preload = options.preload;
1626
1750
  }
1627
- if (this.artistEl) {
1628
- if (artist) {
1629
- this.artistEl.textContent = artist;
1630
- this.artistEl.style.display = "";
1631
- } else if (artist === "") {
1632
- this.artistEl.style.display = "none";
1633
- }
1751
+ if (artist !== null) {
1752
+ this.syncArtist(artist);
1634
1753
  }
1635
- if (options.artwork && this.artworkEl) {
1636
- this.artworkEl.src = options.artwork;
1754
+ if (hasArtworkOption || hasArtworkAltOption) {
1755
+ this.syncArtwork(
1756
+ hasArtworkOption ? options.artwork : this.options.artwork,
1757
+ hasArtworkAltOption ? options.artworkAlt : this.options.artworkAlt
1758
+ );
1637
1759
  }
1638
1760
  this.options.markers = options.markers || [];
1639
1761
  this.options.waveform = options.waveform || null;