# What changed in @arraypress/waveform-player

> 194 changes in @arraypress/waveform-player 1 from its official release notes, upgrade guides and advisories: 17 breaking, 2 security, 64 new APIs and options. Each one cited. Sources checked 2026-10-20. HTML: https://unstale.sh/npm/@arraypress/waveform-player/

To see which of these apply to a repository, run `npx @unstale/cli init` in it.

## @arraypress/waveform-player 1

### Breaking changes

- Bar drawers treat an unusable pitch as zero bars, including when mutable options become unusable after construction. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The canonical attribute now takes precedence over the legacy `data-color-preset` alias. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Destroying a player no longer emits `request-pause` or asks an external controller to pause playback. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- BPM detection returns `null` for silence, pads, speech with fewer than two onsets, or when no interval falls in the 60–200 range. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Loading a different track resets its duration and time readout to 0:00, including when using `load()` with a different URL. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- A track change resets `bpm` and `album` unless supplied, drops a detected BPM from the prior track, and hides the badge when the new track has no BPM. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- In external mode, progress updates wait for a drag to be released instead of moving the playhead beneath the cursor. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- A new entry point omits the import-time document-wide scan, so consumers can initialize the library explicitly with WaveformPlayer.init(root). (1.27.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1270--2026-09-21)
- Markers without a usable time or label are dropped or defaulted, including markers from peaks JSON sidecars. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- Peaks strings containing junk now yield no peaks rather than NaN values. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- The package no longer ships sourcemap files, reducing its packed and unpacked size. (1.24.3) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1243--2026-08-09)
- Renames the subtitle option to artist, including data-subtitle to data-artist, .waveform-subtitle to .waveform-artist, and the loadTrack parameter; there is no back-compat alias. (1.18.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1180--2026-07-01)
- Removes the buttonColor, buttonHoverColor, textColor, textSecondaryColor, and backgroundColor and borderColor options and their data-* attributes; use CSS variables to theme button and text colors. (1.18.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1180--2026-07-01)
- The mirror style now uses barSpacing: 2, producing distinct thin bars rather than a solid fill. (1.11.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1110--2026-06-28)
- `formatTime()` now uses H:MM:SS after one hour and clamps negative values, also correcting `aria-valuetext`. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- External mode now uses the self-mode argument order `(currentTime, duration, player)` instead of `(player, currentTime, duration)`; consumers relying on the previous order must update handlers. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The JSON config file feature was reverted because it caused layout and sizing issues when used inside WaveformBar. (1.4.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#141---2026-03-22)

### Security

- Values interpolated into the initial markup are now escaped, preventing quotes in author-supplied values from closing attributes and injecting markup. (1.22.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1220--2026-07-17)
- A static bridge exposes `formatTime`, `extractTitleFromUrl`, `escapeHtml`, and `isSafeHref`; the URL helper allows HTTP, HTTPS, and relative URLs while rejecting script schemes. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)

### New APIs and options

- Provides the player's own peak extraction for code that decodes audio itself and wants matching drawings. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- Set this attribute to false on the document element to suppress the automatic document-wide scan while keeping explicit WaveformPlayer.init() calls available. (1.26.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1260--2026-08-12)
- Accepts an optional Document or Element root and scans that subtree, matching the root itself as well as its descendants; defaults to document. (1.26.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1260--2026-08-12)
- Adds a container state class when waveform analysis fails and the player uses placeholder peaks; the class is removed when the next load starts, allowing integrators to detect and restyle the decorative waveform. (1.24.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1240--2026-07-30)
- Controls the CORS mode of the self-mode <audio> element, accepting 'anonymous', 'use-credentials', or null. (1.23.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1230--2026-07-22)
- Sets the CORS mode of the self-mode <audio> element through a data attribute. (1.23.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1230--2026-07-22)
- Choose whether artwork renders in the info row or fills the play/pause button; the option is also settable with data-artwork-position. (1.22.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1220--2026-07-17)
- Set the play/pause button's corner radius with a CSS length; it is also settable with data-button-radius. (1.22.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1220--2026-07-17)
- Re-theme the button artwork glyph color; re-theme it together with --wfp-btn-artwork-scrim to retain the contrast guarantee. (1.22.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1220--2026-07-17)
- Re-theme the scrim between button artwork and the glyph; re-theme it together with --wfp-btn-artwork-color to retain the contrast guarantee. (1.22.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1220--2026-07-17)
- Adds an option, also settable via data-*, to localize the artwork image alt text; its default is 'Album artwork'. (1.20.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1200--2026-07-05)
- Adds an option, also settable via data-*, to localize the play button aria-label; its default is 'Play/Pause'. (1.20.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1200--2026-07-05)
- Adds a configurable, translatable seek slider aria-valuetext template, also settable via data-seek-value-text; the default preserves existing output. (1.20.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1200--2026-07-05)
- Adds an option, also settable via data-*, to localize the speed button and menu aria-label; its default is 'Playback speed'. (1.20.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1200--2026-07-05)
- Adds an option, also settable via data-*, to localize the Media Session title fallback when no title is set; its default is 'Unknown Track'. (1.20.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1200--2026-07-05)
- Adds an option that registers a Media Session skip-track button, called with the player. (1.19.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1190--2026-07-01)
- Adds an option that registers a Media Session skip-track button, called with the player. (1.19.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1190--2026-07-01)
- Adds a configurable gradient axis for waveformColor and progressColor stop arrays: vertical by default, horizontal, or diagonal. (1.18.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1180--2026-07-01)
- Adds an opt-in draggable circular handle to the seekbar style; it expands on hover and defaults to false. (1.17.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1170--2026-07-01)
- Enabling this option now shows a tooltip that follows the pointer over the waveform and displays the time at that position. (1.16.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1160--2026-06-30)
- Adds an option to size the play/pause button; numbers are treated as pixels and strings are used verbatim. It sets --wfp-btn-size to scale both button styles and is forwarded by the Astro/React wrappers. (1.14.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1140--2026-06-28)
- A public API lets developers trigger theme refreshes manually. (1.13.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1130--2026-06-28)
- Accepts a known BPM to show in the badge with showBPM, without decoding audio; a supplied value takes precedence over detection. (1.12.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1120--2026-06-28)
- Adds a buttonStyle option with circle and minimal values; minimal renders a bare play/pause glyph and composes with the preview layout. (1.11.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1110--2026-06-28)
- Adds a preview layout that centers the title under the waveform and trims the meta row for sample-pack previews and dense grids. (1.10.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1100--2026-06-28)
- The keyboard-focus ring and speed-menu active state are now neutral by default; set this CSS variable to a brand hue to re-tint them. (1.10.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1100--2026-06-28)
- Exposes a utility for wrappers to read the player's full data-* option surface from a host element without reimplementing the contract. (1.9.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#190--2026-06-28)
- The new option rounds bar caps in bars and mirror styles; caps fall back to square where `roundRect` is unavailable. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `parseDataAttributes` now reads this attribute on auto-init paths. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `parseDataAttributes` now reads this attribute on auto-init paths. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `parseDataAttributes` now reads this attribute on auto-init paths. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `parseDataAttributes` now reads this attribute on auto-init paths. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `parseDataAttributes` now reads this attribute on auto-init paths. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `parseDataAttributes` now reads this attribute on auto-init paths. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- Customize or localize the audio-load error message; it defaults to `Unable to load audio`, is escaped before rendering, and can also be set with `data-error-text`. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `loadTrack` accepts `{ autoplay: false }` to load, restore, or enqueue a track without forcing playback. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A CommonJS bundle and `require` export condition allow the package to be loaded under Node CJS. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- Highlights the current marker using a core-owned `.waveform-marker.active` class, avoiding direct marker DOM manipulation. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `src` and `data-src` are shorthand aliases for `url`; canonical names still work and take precedence when both are set. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `style` and `data-style` are shorthand aliases for `waveformStyle`; canonical names still work and take precedence when both are set. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A new export alias provides access to the package stylesheet. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A CSS custom property sets the body gap, defaulting to 8px, so embedders can retune layout without overriding internal classes. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A CSS custom property sets waveform line height, defaulting to 1.4, so embedders can retune layout without overriding internal classes. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A CSS custom property sets the track gap, defaulting to 12px, so embedders can retune layout without overriding internal classes. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A destroy event lets listeners release references when the player is torn down. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- Adds a boolean option, defaulting to true, that enables the accessible seek slider; set it to false to keep the prior markup. (1.7.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#172--2026-06-27)
- Adds a string option for the slider's accessible name, defaulting to null and falling back to the track title, then 'Seek'. (1.7.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#172--2026-06-27)
- Static helper derives a peaks-JSON URL from an audio URL, preserving query strings and fragments; returns undefined for empty input or unrecognised extensions. (1.7.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#170--2026-05-23)
- Adds external audio mode, which skips the player's audio element and delegates playback to an external controller; the default remains self. (1.6.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#160---2026-05-13)
- Adds an external-state pump for the play/pause visual state that toggles the icon, starts or stops smooth updates, and dispatches play or pause events. (1.6.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#160---2026-05-13)
- Adds an external-state pump for the scrubber, canvas, and time displays, driven by an external clock without touching audio. (1.6.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#160---2026-05-13)
- External-mode pause interactions dispatch this cancelable event on the container so a controller can route playback to its own audio source. (1.6.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#160---2026-05-13)
- External-mode play interactions dispatch this cancelable event on the container so a controller can route playback to its own audio source. (1.6.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#160---2026-05-13)
- External-mode seek interactions dispatch this cancelable event on the container so a controller can route the action to its own audio source. (1.6.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#160---2026-05-13)
- JSON waveform files can include markers, which are automatically loaded when no markers are set via data attributes. (1.5.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#152---2026-03-22)
- The bar, block, and dot drawing styles are now accepted as aliases for bars, blocks, and dots. (1.5.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#151---2026-03-22)
- Accepts a URL to a JSON file ending in .json, reads peaks from an array or a peaks object, and falls back to generating the waveform from audio if fetching fails. (1.5.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#150---2026-03-22)
- Accepts a URL to a JSON file ending in .json, reads peaks from an array or a peaks object, and falls back to generating the waveform from audio if fetching fails. (1.5.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#150---2026-03-22)
- Load track configuration from an external JSON file using the data-config attribute. (1.4.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#140---2026-03-22-yanked)
- Load JSON configuration dynamically by passing a file path through options.config. (1.4.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#140---2026-03-22-yanked)
- The JSON config meta object passes through for use by extensions. (1.4.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#140---2026-03-22-yanked)
- Adds an option to hide the play/pause button for custom UI implementations, configurable through HTML data attributes or the JavaScript API. (1.3.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#130---2026-03-16)
- Adds an option to hide the title, artist, time, and metadata bar, configurable through HTML data attributes or the JavaScript API. (1.3.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#130---2026-03-16)
- Set data-color-preset to light or dark to override automatic theme detection. (1.2.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#120---2025-10-19)

### Performance

- Config files are cached in memory so subsequent loads of the same file are instant. (1.4.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#140---2026-03-22-yanked)

### Behavior and default changes

- Auto-theme now continues its backdrop walk from the shadow host, so players in shadow roots can theme against their surrounding card. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- Peaks supplied during audio decoding now win over the decode or placeholder fallback; loads with peaks supplied before they start skip decoding. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- Also sets the current track's waveform option, allowing same-track reloads to reuse peaks and external-mode request-play events to carry them; loadTrack() replaces them for a new track. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- A sidecar's BPM is shown with `showBPM` when no `bpm` option is set; an explicit option still takes precedence. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The option's type now accepts `null`. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The canonical attribute takes precedence over its legacy alias and accepts a JSON gradient stop array. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- `pause()` now dispatches the cancelable event before changing the current player; `preventDefault()` vetoes the pause request and retains the player as `currentlyPlaying`. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Markers are placed when the duration changes, allowing external-mode markers to render without manually calling `renderMarkers()`. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- For a sidecar URL, the method returns a `Promise<boolean>` indicating whether the sidecar was applied; inline peaks still return nothing. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Self-mode progress events continue in a background tab using native audio time updates when the animation frame loop has been quiet for 500ms. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The track title and seek slider accessible name are painted before waiting for audio metadata, preventing an empty info row during fetch; total time still waits for metadata. (1.25.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1251--2026-08-11)
- Boolean options accept attribute-shaped strings, interpreting the string 'false' as false rather than as a truthy value. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- Options are normalized after merging; unusable values resolve to their documented defaults and produce a warning instead of throwing. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- Non-numeric geometry and playback values, including height, now fall back to defaults and clamp to sane ranges with a warning naming the option. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- The option accepts a bare comma-separated list as well as a JSON array, including in the data-playback-rates attribute. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- The method now clamps playback rates to 0.25–4 instead of 0.5–2, enabling audible 2.5x and 3x speeds. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- The <audio> element no longer sets crossOrigin to 'anonymous' by default, allowing playback from origins that do not send Access-Control-Allow-Origin. (1.23.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1230--2026-07-22)
- loadTrack() now adds, updates, or removes artist and artwork metadata in place, so consumers can switch tracks with differing metadata without recreating the player. (1.21.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1210--2026-07-10)
- The speed selector now uses an accessible menu with menuitemradio options, arrow-key and Home/End navigation, and focus management. (1.19.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1191--2026-07-01)
- Dragging to seek now updates the time readout and shows a tooltip live at the drag position; the tooltip appears on any waveform style, while showHoverTime still governs the hover tooltip. (1.18.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1180--2026-07-01)
- Activating an interactive control keeps focus on that control; the container takes focus only when a click lands on a non-interactive area. (1.17.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1170--2026-07-01)
- The speed toggle announces open and closed state, closes on Escape, and returns focus to the trigger after a rate is chosen. (1.17.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1170--2026-07-01)
- Dragging on the waveform or seekbar scrubs without re-seeking during the drag; the seek commits on release. (1.17.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1170--2026-07-01)
- The player adds and removes .show-label so an active marker label appears for about 2.5 seconds and fades out while the highlight remains; CSS can override the label visibility. (1.16.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1161--2026-06-30)
- Markers are highlighted and their labels revealed automatically as playback passes them. (1.16.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1160--2026-06-30)
- A failed artwork image now displays a muted music-note placeholder tile instead of the browser's broken-image icon. (1.16.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1160--2026-06-30)
- The default source peak resolution for live decode rises from 256 to 1800, keeping wide or high-DPI waveforms crisp; supplied waveform peaks ignore this setting. (1.15.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1150--2026-06-30)
- Auto-themed players re-detect the page theme and redraw when the page theme or OS color scheme changes; explicit presets and hand-set colours are not overridden. (1.13.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1130--2026-06-28)
- The minimal button uses a larger play/pause glyph and a fixed 2.25rem button box, without shifting the waveform when toggled. (1.12.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1121--2026-06-28)
- The default barRadius is now 1, giving bars soft caps. (1.11.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1110--2026-06-28)
- The default height is now 64. (1.11.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1110--2026-06-28)
- The default samples value is now 256 for more source fidelity; samples are resampled to fit the bar pitch. (1.11.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1110--2026-06-28)
- The seek slider now toggles `aria-busy` while loading. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- A reduced-motion media query neutralizes transitions and animations for users who request reduced motion. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `progressColor` now accepts an array of CSS colour stops, rendered as a vertical canvas gradient; it works through constructor options, data attributes, and the React/Astro wrappers. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The request-pause event detail now includes `markers`, `waveform`, and `artist`, so controllers can use the published contract without re-fetching data. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The request-play event detail now includes `markers`, `waveform`, and `artist`, so controllers can use the published contract without re-fetching data. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The request-seek event detail now includes `markers`, `waveform`, and `artist`, so controllers can use the published contract without re-fetching data. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The error node now has `role="alert"` for accessibility. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `waveformColor` now accepts an array of CSS colour stops, rendered as a vertical canvas gradient; it works through constructor options, data attributes, and the React/Astro wrappers. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The ended event now carries `currentTime` and `duration`; external mode synthesizes it when progress reaches the end, firing once. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The waveform surface is now a keyboard-operable ARIA slider, with synchronized value attributes and keyboard seeking in both self and external modes. (1.7.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#172--2026-06-27)
- Configuration values are resolved in order: JSON config as the base, then data attributes, then JS options as overrides. (1.4.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#140---2026-03-22-yanked)
- The waveform automatically fills the full width when controls are hidden. (1.3.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#130---2026-03-16)
- The player automatically adapts to the website’s color scheme by checking background brightness, theme classes, and system preferences. (1.2.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#120---2025-10-19)

### Tooling

- The package ships hand-authored TypeScript definitions for its options, WaveformPlayer class API, and custom-event map, enabling IntelliSense and type-checking without runtime bytes. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)

### Fixes and other changes

- When the browser reports a target as unseekable, the player waits for the download to finish, reloads from cache, and continues from the new position, allowing Chromium to seek on hosts that ignore byte ranges. (1.29.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1291--2026-09-27)
- Keyboard controls now work inside a shadow root, including Space on the focused player and the speed menu's arrow keys. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- Peaks supplied immediately after construction are no longer overwritten by the first load frame drawing the waveform option. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- The placeholder indicator clears when real peaks arrive through setWaveformData() after a failed decode. (1.29.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1290--2026-09-27)
- Values below 60px now size the waveform container correctly, avoiding a taller container and stretched, blurry bars. (1.28.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1281--2026-09-24)
- A zero bar width is normalized to 0.1, preventing an infinite bar count and a page hang when spacing is also zero. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Destroying the player during the metadata wait no longer throws or prevents `load()` from settling. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The declaration now types the resolved value as `number[]`, matching the peaks array returned at runtime. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- JSON sidecar URLs with query strings or fragments are recognized as URLs rather than parsed as inline peaks. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The declaration now accepts `null` and `undefined` and returns `string | undefined`, as documented. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- A load now stops after an await if a newer load or destroy has started, preventing stale results, duplicate autoplay, and premature clearing of the loading state. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Calling `load(url)` after a failed load clears the whole error state, including the disabled play button and error overlay. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Calling `loadTrack()` immediately after construction no longer causes the same file to be fetched and decoded twice. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The lock-screen scrubber state updates on seeks and playback-rate changes, and only for the player that owns the session. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- A self-mode audio failure now invokes `onError` only once. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- With a JSON peaks sidecar, `onLoad` fires after the sidecar has been applied. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- A non-2xx response, network error, or sidecar without peaks falls back to decoding the audio instead of leaving the canvas blank. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The configured playback rate and a speed selected from the menu now survive track changes. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The public method is now declared in the type declarations. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The public method is now declared in the type declarations. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- `seekTo()` and `seekToPercent()` ignore non-finite targets instead of assigning an invalid current time and throwing. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- The declaration now allows `Promise<boolean> | void` to match the method's return behavior. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- At the end of a self-mode track, listeners now receive one pause event and `onPause` runs once. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- A player destroyed within its first frame no longer emits `ready` or performs its initial audio fetch and decode. (1.28.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1280--2026-09-24)
- Calling load() now records the new URL in options.url at the start, so events during loading and failed loads report the track being loaded. (1.27.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1271--2026-09-24)
- A construction failure now unregisters the player and drops listeners it bound before rethrowing, preventing later scans and shared instance operations from being blocked by a half-built player. (1.26.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1260--2026-08-12)
- The initialization flag is cleared when a player is destroyed, allowing the same element to be initialized again. (1.25.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1251--2026-08-11)
- The package metadata now declares the ESM/CJS/IIFE entry bundles as side-effectful so bundlers do not drop declarative-only imports; pure modules under src/js/ remain tree-shakeable. (1.25.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1251--2026-08-11)
- Non-function callback values are rejected during configuration rather than throwing during playback. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- Unrecognised enumerated option values resolve to their defaults, avoiding unintended browser behavior such as an unexpected CORS request for crossOrigin. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- Rates outside the supported range are dropped from the speed menu so its buttons and highlighted rate match actual playback. (1.25.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1250--2026-08-11)
- The loading indicator appears only while the canvas is empty; aria-busy continues to track the real loading state. (1.24.5) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1245--2026-08-10)
- When preload is 'none', load() skips the metadata wait so it can settle; a later metadata event still fills in duration and re-renders markers. (1.24.5) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1245--2026-08-10)
- Caller-supplied peaks now paint before waiting for audio metadata, so the canvas is not left blank while metadata loads. (1.24.5) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1245--2026-08-10)
- Unrecognized alignment values are coerced to auto in createDOM(), covering both constructor options and data-button-align. (1.24.4) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1244--2026-08-10)
- Initialization skips elements that already have a player instance, preventing programmatically constructed players from being re-initialized during a scan. (1.24.4) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1244--2026-08-10)
- Non-finite and non-numeric input now formats as '0:00' instead of producing an invalid time string; numeric strings are still coerced. (1.24.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1242--2026-08-09)
- An explicit buttonSize is now honored on narrow screens instead of being overridden by the 32px fallback. (1.22.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1220--2026-07-17)
- During seek-drag, the current-time readout owns the live scrub time and the duplicate hover tooltip is suppressed; the tooltip still shows when there is no current-time readout. (1.19.3) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1193--2026-07-02)
- A player now claims Media Session action handlers and metadata when it starts playing, so lock-screen controls target the track being played. (1.19.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1191--2026-07-01)
- Prevents the synthetic click after a pointer drag from re-seeking using a stale coordinate and snapping the playhead. (1.19.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1190--2026-07-01)
- Reasserts metadata on play and sets playbackState and position state, fixing blank iOS Now-Playing cards. (1.19.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1190--2026-07-01)
- Space now starts playback when the waveform itself is focused; previously, play/pause only worked when the player root was focused. (1.19.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1190--2026-07-01)
- Live decoding now scans every frame, matching WaveformGen’s offline waveform shape and making live and pre-generated renders identical. (1.15.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1150--2026-06-30)
- Fixes the minimal play button glyph size so its sizing rule applies instead of the later, equally specific 16px rule. (1.14.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1140--2026-06-28)
- The minimal play button now renders its glyph at the default circle button’s visual size while keeping a fixed width so the waveform does not shift on play/pause. (1.13.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1131--2026-06-28)
- The minimal button now uses a fixed box, so playing or pausing no longer shifts the adjacent waveform or re-samples its bars. (1.12.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#1120--2026-06-28)
- Duration is now published unconditionally, enabling keyboard seeking and the ARIA slider in external mode even when `showTime` is off. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- External mode no longer crashes during initialization when `showPlaybackSpeed` is enabled; `updateSpeedUI()` now no-ops without audio. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- Autoplay no longer emits an unhandled promise rejection when the browser blocks playback. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `destroy()` now tears down document, container, and seek listeners registered through an AbortController, fixing listeners left attached during teardown. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- IDs now hash the full URL plus a counter, avoiding same-host track collisions and errors on non-Latin1 or Unicode URLs. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- The AudioContext now closes in a `finally` block after failed decoding, preventing leaked contexts from exhausting browser limits. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- Marker rendering now uses a mode-agnostic duration, allowing chapter markers to render when audio is delegated. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- `setVolume()` now coerces and guards non-finite input so `NaN` does not reach `audio.volume`. (1.8.0) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#180--2026-06-27)
- SSR and Node consumers can import WaveformPlayer by name without an export error. (1.7.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#171--unreleased)
- Marker elements from a previous track no longer persist when loading a new track without markers. (1.3.5) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#135---2026-03-17)
- Markers from the previous track no longer persist when loading a new track without markers. (1.3.4) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#134---2026-03-17)
- Removed inline style.height so the canvas can fill available width in flex containers; the container div still controls height. (1.3.3) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#133---2026-03-17)
- The waveform canvas now fills the available width when embedded in flex containers because resizeCanvas() reads width from the container div instead of the canvas element. (1.3.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#132---2026-03-17)
- Catches the play() promise internally when loadTrack triggers autoplay before user interaction, preventing an uncaught NotAllowedError. (1.3.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#131---2026-03-17)
- play() now returns the Promise from HTMLMediaElement.play(), allowing callers to handle errors like AbortError. (1.2.2) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#122---2026-02-28)
- All custom events now bubble for better framework integration. (1.2.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#121---2026-02-14)
- Calling destroy() during resize events no longer causes a null reference error; the resize listener is cleaned up, and event handlers guard against destruction to prevent memory leaks and race conditions. (1.2.1) — [release notes](https://github.com/arraypress/waveform-player/blob/d26574081f0de7c34fcd934d22937a576e0a3b9a/CHANGELOG.md#121---2026-02-14)