@arraypress/waveform-player 1.24.4 → 1.25.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.
@@ -26,6 +26,44 @@
26
26
  function clamp(value, min = 0, max = 1) {
27
27
  return Math.max(min, Math.min(value, max));
28
28
  }
29
+ function toFiniteNumber(value, fallback = null, opts = {}) {
30
+ const { min = -Infinity, max = Infinity, integer = false } = opts;
31
+ const n = typeof value === "number" ? value : typeof value === "string" && value.trim() !== "" ? Number(value) : NaN;
32
+ if (!Number.isFinite(n)) return fallback;
33
+ const bounded = clamp(n, min, max);
34
+ return integer ? Math.round(bounded) : bounded;
35
+ }
36
+ function toArray(value, fallback = null) {
37
+ if (Array.isArray(value)) return value;
38
+ if (typeof value === "string" && value.trim().startsWith("[")) {
39
+ try {
40
+ const parsed = JSON.parse(value);
41
+ if (Array.isArray(parsed)) return parsed;
42
+ } catch (e) {
43
+ }
44
+ }
45
+ return fallback;
46
+ }
47
+ function toNumberArray(value, opts = {}) {
48
+ const { min = -Infinity, max = Infinity, fallback = null } = opts;
49
+ let list = toArray(value);
50
+ if (!list && typeof value === "string" && value.trim() !== "") {
51
+ list = value.split(/[,\s]+/);
52
+ }
53
+ if (!list) return fallback;
54
+ const numbers = list.map((v) => toFiniteNumber(v)).filter((n) => n !== null && n >= min && n <= max);
55
+ return numbers.length ? numbers : fallback;
56
+ }
57
+ function toEnum(value, allowed, fallback = null) {
58
+ return allowed.includes(value) ? value : fallback;
59
+ }
60
+ function toBool(value) {
61
+ if (typeof value === "string") {
62
+ const v = value.trim().toLowerCase();
63
+ return v !== "" && v !== "false" && v !== "0";
64
+ }
65
+ return !!value;
66
+ }
29
67
  function parseBoolAttr(value) {
30
68
  return value === void 0 ? void 0 : value === "true";
31
69
  }
@@ -53,14 +91,12 @@
53
91
  if (!raw) return;
54
92
  options[optKey] = /^\d+(\.\d+)?$/.test(raw.trim()) ? parseFloat(raw) : raw;
55
93
  };
56
- const setJson = (optKey, dataKey = optKey) => {
94
+ const setJsonArray = (optKey, dataKey = optKey) => {
57
95
  const raw = element.dataset[dataKey];
58
96
  if (!raw) return;
59
- try {
60
- options[optKey] = JSON.parse(raw);
61
- } catch (e) {
62
- console.warn(`[WaveformPlayer] Invalid ${dataKey} JSON:`, e);
63
- }
97
+ const parsed = toArray(raw);
98
+ if (parsed) options[optKey] = parsed;
99
+ else console.warn(`[WaveformPlayer] Invalid ${dataKey} attribute, expected a JSON array:`, raw);
64
100
  };
65
101
  if (element.dataset.src) options.url = element.dataset.src;
66
102
  if (element.dataset.url) options.url = element.dataset.url;
@@ -105,10 +141,14 @@
105
141
  if (element.dataset.artwork) options.artwork = element.dataset.artwork;
106
142
  if (element.dataset.artworkPosition) options.artworkPosition = element.dataset.artworkPosition;
107
143
  if (element.dataset.waveform) options.waveform = element.dataset.waveform;
108
- setJson("markers");
144
+ setJsonArray("markers");
109
145
  setNum("playbackRate", "playbackRate", true);
110
146
  setBool("showPlaybackSpeed");
111
- setJson("playbackRates");
147
+ if (element.dataset.playbackRates) {
148
+ const rates = toNumberArray(element.dataset.playbackRates);
149
+ if (rates) options.playbackRates = rates;
150
+ else console.warn("[WaveformPlayer] Invalid playbackRates attribute:", element.dataset.playbackRates);
151
+ }
112
152
  setBool("enableMediaSession");
113
153
  setBool("showMarkers");
114
154
  setBool("accessibleSeek");
@@ -848,6 +888,123 @@
848
888
  dots: { barWidth: 3, barSpacing: 3 },
849
889
  seekbar: { barWidth: 1, barSpacing: 0 }
850
890
  };
891
+ var BUTTON_ALIGNMENTS = ["auto", "top", "center", "bottom"];
892
+ var PLAYBACK_RATE_MIN = 0.25;
893
+ var PLAYBACK_RATE_MAX = 4;
894
+ var ENUMS = {
895
+ buttonAlign: BUTTON_ALIGNMENTS,
896
+ layout: ["default", "preview"],
897
+ buttonStyle: ["circle", "minimal"],
898
+ artworkPosition: ["info", "button"],
899
+ waveformStyle: Object.keys(STYLE_DEFAULTS),
900
+ waveformGradient: ["vertical", "horizontal", "diagonal"],
901
+ audioMode: ["self", "external"],
902
+ preload: ["none", "metadata", "auto"],
903
+ colorPreset: Object.keys(COLOR_PRESETS),
904
+ // Anything other than these two makes the browser fall back to 'anonymous',
905
+ // which forces a CORS request the caller never asked for — so a bad value
906
+ // has to resolve to null (no crossorigin attribute), not pass through.
907
+ crossOrigin: ["anonymous", "use-credentials"]
908
+ };
909
+ var NUMBERS = {
910
+ height: { min: 1, integer: true },
911
+ samples: { min: 1, integer: true },
912
+ barWidth: { min: 0 },
913
+ barSpacing: { min: 0 },
914
+ barRadius: { min: 0 },
915
+ bpm: { min: 1 },
916
+ // Matches the clamp in setPlaybackRate() — the menu must not offer a rate
917
+ // the setter would then silently refuse.
918
+ playbackRate: { min: PLAYBACK_RATE_MIN, max: PLAYBACK_RATE_MAX }
919
+ };
920
+ var BOOLEANS = [
921
+ "autoplay",
922
+ "showControls",
923
+ "showInfo",
924
+ "showTime",
925
+ "showHoverTime",
926
+ "seekHandle",
927
+ "showBPM",
928
+ "singlePlay",
929
+ "playOnSeek",
930
+ "enableMediaSession",
931
+ "showMarkers",
932
+ "accessibleSeek",
933
+ "showPlaybackSpeed"
934
+ ];
935
+ var CALLBACKS = [
936
+ "onLoad",
937
+ "onPlay",
938
+ "onPause",
939
+ "onEnd",
940
+ "onError",
941
+ "onTimeUpdate",
942
+ "onNextTrack",
943
+ "onPreviousTrack"
944
+ ];
945
+ function warnInvalid(key, value) {
946
+ console.warn(`[WaveformPlayer] Invalid ${key} option, using default:`, value);
947
+ }
948
+ function normalizeMarkers(value) {
949
+ const list = toArray(value);
950
+ if (!list) {
951
+ if (value != null) warnInvalid("markers", value);
952
+ return [];
953
+ }
954
+ return list.reduce((markers, marker) => {
955
+ const time = marker && typeof marker === "object" ? toFiniteNumber(marker.time, null, { min: 0 }) : null;
956
+ if (time === null) {
957
+ warnInvalid("marker", marker);
958
+ return markers;
959
+ }
960
+ markers.push({ ...marker, time, label: marker.label == null ? "" : marker.label });
961
+ return markers;
962
+ }, []);
963
+ }
964
+ function normalizeOptions(options) {
965
+ const supplied = (key) => options[key] != null;
966
+ const reject = (key) => {
967
+ warnInvalid(key, options[key]);
968
+ options[key] = DEFAULT_OPTIONS[key];
969
+ };
970
+ for (const [key, range] of Object.entries(NUMBERS)) {
971
+ if (!supplied(key)) continue;
972
+ const n = toFiniteNumber(options[key], null, range);
973
+ if (n === null) reject(key);
974
+ else options[key] = n;
975
+ }
976
+ for (const [key, allowed] of Object.entries(ENUMS)) {
977
+ if (supplied(key) && toEnum(options[key], allowed) === null) reject(key);
978
+ }
979
+ for (const key of BOOLEANS) {
980
+ options[key] = toBool(options[key]);
981
+ }
982
+ for (const key of CALLBACKS) {
983
+ if (supplied(key) && typeof options[key] !== "function") reject(key);
984
+ }
985
+ if (supplied("playbackRates")) {
986
+ const rates = toNumberArray(options.playbackRates, {
987
+ min: PLAYBACK_RATE_MIN,
988
+ max: PLAYBACK_RATE_MAX,
989
+ fallback: null
990
+ });
991
+ if (rates === null) reject("playbackRates");
992
+ else options.playbackRates = rates;
993
+ }
994
+ options.markers = normalizeMarkers(options.markers);
995
+ for (const key of ["buttonSize", "buttonRadius"]) {
996
+ if (!supplied(key)) continue;
997
+ const value = options[key];
998
+ const ok = typeof value === "number" ? Number.isFinite(value) : typeof value === "string" && value.trim() !== "";
999
+ if (!ok) reject(key);
1000
+ }
1001
+ for (const key of ["waveformColor", "progressColor"]) {
1002
+ if (!supplied(key)) continue;
1003
+ const value = options[key];
1004
+ if (!(typeof value === "string" && value.trim() !== "") && !Array.isArray(value)) reject(key);
1005
+ }
1006
+ return options;
1007
+ }
851
1008
 
852
1009
  // src/js/core.js
853
1010
  var ARTWORK_FALLBACK = "data:image/svg+xml," + encodeURIComponent(
@@ -856,7 +1013,6 @@
856
1013
  var SEEK_STEP_SECONDS = 5;
857
1014
  var SEEK_PAGE_SECONDS = 10;
858
1015
  var INTERACTIVE_ELEMENTS = 'button, a[href], input, [role="slider"]';
859
- var BUTTON_ALIGNMENTS = ["auto", "top", "center", "bottom"];
860
1016
  var WaveformPlayer = class _WaveformPlayer {
861
1017
  /** @type {Map<string, WaveformPlayer>} */
862
1018
  static instances = /* @__PURE__ */ new Map();
@@ -888,7 +1044,7 @@
888
1044
  const userOptions = { ...options };
889
1045
  if (userOptions.style && !userOptions.waveformStyle) userOptions.waveformStyle = userOptions.style;
890
1046
  if (userOptions.src && !userOptions.url) userOptions.url = userOptions.src;
891
- this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions);
1047
+ this.options = normalizeOptions(mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions));
892
1048
  const preset = getColorPreset(this.options.colorPreset, this.container);
893
1049
  this._autoTheme = this.options.colorPreset == null || !COLOR_PRESETS[this.options.colorPreset];
894
1050
  this._presetKeys = [];
@@ -1736,9 +1892,10 @@
1736
1892
  * element, so the src/metadata step is skipped and only the visualization
1737
1893
  * is built (duration/time come from the controller via
1738
1894
  * {@link WaveformPlayer#setProgress}). Peaks come from the `waveform`
1739
- * option when provided, otherwise they are decoded from the audio; a
1740
- * decode failure falls back to a placeholder waveform. The `onLoad`
1741
- * callback fires on success.
1895
+ * option when provided — painted *before* the metadata wait, since they
1896
+ * need nothing from the audio element — otherwise they are decoded from
1897
+ * the audio; a decode failure falls back to a placeholder waveform. The
1898
+ * `onLoad` callback fires on success.
1742
1899
  * @param {string} url - Audio URL.
1743
1900
  * @returns {Promise<void>} Resolves once loading settles (errors are caught
1744
1901
  * internally and surfaced through {@link WaveformPlayer#onError}).
@@ -1749,31 +1906,35 @@
1749
1906
  this.progress = 0;
1750
1907
  this.hasError = false;
1751
1908
  this.container.classList.remove("waveform-is-placeholder");
1909
+ const hasInlinePeaks = !!this.options.waveform;
1910
+ if (hasInlinePeaks) {
1911
+ this.setWaveformData(this.options.waveform);
1912
+ }
1752
1913
  if (this.audio) {
1753
1914
  this.audio.src = url;
1754
- await new Promise((resolve, reject) => {
1755
- const metadataHandler = () => {
1756
- this.audio.removeEventListener("loadedmetadata", metadataHandler);
1757
- this.audio.removeEventListener("error", errorHandler);
1758
- resolve();
1759
- };
1760
- const errorHandler = (e) => {
1761
- this.audio.removeEventListener("loadedmetadata", metadataHandler);
1762
- this.audio.removeEventListener("error", errorHandler);
1763
- reject(e);
1764
- };
1765
- this.audio.addEventListener("loadedmetadata", metadataHandler);
1766
- this.audio.addEventListener("error", errorHandler);
1767
- });
1915
+ if (this.audio.preload !== "none") {
1916
+ await new Promise((resolve, reject) => {
1917
+ const metadataHandler = () => {
1918
+ this.audio.removeEventListener("loadedmetadata", metadataHandler);
1919
+ this.audio.removeEventListener("error", errorHandler);
1920
+ resolve();
1921
+ };
1922
+ const errorHandler = (e) => {
1923
+ this.audio.removeEventListener("loadedmetadata", metadataHandler);
1924
+ this.audio.removeEventListener("error", errorHandler);
1925
+ reject(e);
1926
+ };
1927
+ this.audio.addEventListener("loadedmetadata", metadataHandler);
1928
+ this.audio.addEventListener("error", errorHandler);
1929
+ });
1930
+ }
1768
1931
  }
1769
1932
  const title = this.options.title || extractTitleFromUrl(url);
1770
1933
  if (this.titleEl) {
1771
1934
  this.titleEl.textContent = title;
1772
1935
  }
1773
1936
  this.applySeekLabel(title);
1774
- if (this.options.waveform) {
1775
- this.setWaveformData(this.options.waveform);
1776
- } else {
1937
+ if (!hasInlinePeaks) {
1777
1938
  try {
1778
1939
  const result = await generateWaveform(url, this.options.samples, this.options.showBPM);
1779
1940
  this.waveformData = result.peaks;
@@ -1837,12 +1998,12 @@
1837
1998
  }
1838
1999
  this.progress = 0;
1839
2000
  this.waveformData = [];
1840
- this.options = mergeOptions(this.options, {
2001
+ this.options = normalizeOptions(mergeOptions(this.options, {
1841
2002
  url,
1842
2003
  title: title === null ? this.options.title : title,
1843
2004
  artist: artist === null ? this.options.artist : artist,
1844
2005
  ...options
1845
- });
2006
+ }));
1846
2007
  if (hasArtworkOption) {
1847
2008
  this.options.artwork = options.artwork || null;
1848
2009
  }
@@ -1852,10 +2013,10 @@
1852
2013
  this.options.artworkAlt = this.options.artwork ? DEFAULT_OPTIONS.artworkAlt : "";
1853
2014
  }
1854
2015
  if (options.preload && this.audio) {
1855
- this.audio.preload = options.preload;
2016
+ this.audio.preload = this.options.preload;
1856
2017
  }
1857
2018
  if (options.crossOrigin && this.audio) {
1858
- this.audio.crossOrigin = options.crossOrigin;
2019
+ this.audio.crossOrigin = this.options.crossOrigin;
1859
2020
  }
1860
2021
  if (artist !== null) {
1861
2022
  this.syncArtist(artist);
@@ -1866,7 +2027,7 @@
1866
2027
  hasArtworkAltOption ? options.artworkAlt : this.options.artworkAlt
1867
2028
  );
1868
2029
  }
1869
- this.options.markers = options.markers || [];
2030
+ this.options.markers = options.markers ? normalizeMarkers(options.markers) : [];
1870
2031
  this.options.waveform = options.waveform || null;
1871
2032
  await this.load(url);
1872
2033
  if (options.autoplay !== false) {
@@ -1894,7 +2055,7 @@
1894
2055
  fetch(data.trim()).then((r) => r.json()).then((json) => {
1895
2056
  this.waveformData = Array.isArray(json) ? json : json.peaks || [];
1896
2057
  if (json.markers && !this.options.markers?.length) {
1897
- this.options.markers = json.markers;
2058
+ this.options.markers = normalizeMarkers(json.markers);
1898
2059
  this.renderMarkers();
1899
2060
  }
1900
2061
  this.drawWaveform();
@@ -1902,16 +2063,7 @@
1902
2063
  });
1903
2064
  return;
1904
2065
  }
1905
- if (typeof data === "string") {
1906
- try {
1907
- const parsed = JSON.parse(data);
1908
- this.waveformData = Array.isArray(parsed) ? parsed : [];
1909
- } catch {
1910
- this.waveformData = data.split(",").map(Number);
1911
- }
1912
- } else {
1913
- this.waveformData = Array.isArray(data) ? data : [];
1914
- }
2066
+ this.waveformData = toNumberArray(data, { fallback: [] });
1915
2067
  this.drawWaveform();
1916
2068
  }
1917
2069
  /**
@@ -2190,7 +2342,8 @@
2190
2342
  setLoading(loading) {
2191
2343
  this.isLoading = loading;
2192
2344
  if (this.loadingEl) {
2193
- this.loadingEl.style.display = loading ? "block" : "none";
2345
+ const showIndicator = loading && this.waveformData.length === 0;
2346
+ this.loadingEl.style.display = showIndicator ? "block" : "none";
2194
2347
  }
2195
2348
  if (this.seekEl) {
2196
2349
  this.seekEl.setAttribute("aria-busy", loading ? "true" : "false");
@@ -2663,14 +2816,20 @@
2663
2816
  }
2664
2817
  }
2665
2818
  /**
2666
- * Set the owned `<audio>` element's playback rate (clamped to 0.5–2),
2819
+ * Set the owned `<audio>` element's playback rate (clamped to 0.25–4),
2667
2820
  * persist it onto `this.options.playbackRate`, and refresh the speed UI.
2668
2821
  * Self mode only — a no-op in external mode.
2669
- * @param {number} rate - Desired playback rate; clamped to the 0.5–2 range.
2822
+ *
2823
+ * The clamp bounds the range browsers keep audible; the default speed menu
2824
+ * offers a narrower 0.5–2, which `playbackRates` can widen up to these
2825
+ * bounds. A non-numeric rate is ignored rather than assigned, since
2826
+ * `audio.playbackRate = NaN` throws.
2827
+ * @param {number} rate - Desired playback rate; clamped to the 0.25–4 range.
2670
2828
  */
2671
2829
  setPlaybackRate(rate) {
2672
2830
  if (!this.audio) return;
2673
- const clampedRate = clamp(rate, 0.5, 2);
2831
+ const clampedRate = toFiniteNumber(rate, null, { min: PLAYBACK_RATE_MIN, max: PLAYBACK_RATE_MAX });
2832
+ if (clampedRate === null) return;
2674
2833
  this.audio.playbackRate = clampedRate;
2675
2834
  this.options.playbackRate = clampedRate;
2676
2835
  this.updateSpeedUI();