# Core Player > Release history for @arraypress/waveform-player. :::note Generated from [`@arraypress/waveform-player`'s CHANGELOG](https://github.com/arraypress/waveform-player/blob/main/CHANGELOG.md). Run `npm run sync:changelogs` after a release to refresh. ::: ## [Unreleased] ## [1.26.0] — 2026-08-12 ### Added - **Pages can turn the automatic scan off.** ([#24]) Setting `data-waveform-autoinit="false"` on the document element suppresses the document-wide `[data-waveform-player]` scan that runs on import — for pages that render markup they don't author (user content, a CMS, an editor canvas) and want initialization to stay in their own hands. Read off `` rather than a global because ES module imports are evaluated before the importing module's body runs, so a consumer with a static `import` never gets the chance to set a flag first. The gate sits on the automatic call, not inside the scan, so an explicit `WaveformPlayer.init()` still works. This scopes initialization and is *not* a sanitizer: `playIcon` / `pauseIcon` still inject raw markup for any player that does get built. - **`WaveformPlayer.init()` takes an optional root.** Pass a `Document` or `Element` to scan only that subtree; the root is matched as well as its descendants, so handing it a single player element works rather than silently doing nothing. Pairs with the opt-out above — a page that suppresses the automatic scan can still initialize what it owns and keep the claim-checking and per-element error isolation the scan provides, instead of hand-rolling a `querySelectorAll` loop that has neither. Defaults to `document`; existing calls are unchanged. ### Fixed - **A player whose construction throws no longer poisons the registry.** The instance was added to `WaveformPlayer.instances` *before* `init()` ran, so a throw partway through left a half-built player in the map permanently. `getInstance()` matches by container, so every later declarative scan skipped that element — a transient construction failure became a permanently blank player. Worse, the shared theme watcher and `destroyAll()` both `forEach` that map, where a single throw aborts the loop and strands every instance registered after it: one OS light/dark switch could silently stop re-theming the rest of the page. A failed construction now unregisters itself and drops any listeners it had bound, then rethrows so the caller still sees it. [#24]: https://github.com/arraypress/waveform-player/pull/24 ## [1.25.1] — 2026-08-11 ### Fixed - **The track title no longer blinks in after the audio loads.** ([#25]) The title comes from the `title` option or the URL, so it needs nothing from the audio element — but it was written *after* the `loadedmetadata` wait, leaving the info row empty for the whole fetch and then popping in. On a slow or non-Range-capable origin that's a visible flash of an empty player. The title and the seek slider's accessible name are now painted up front, alongside the inline peaks moved ahead of the same wait in 1.24.5. The total time still waits on metadata (it genuinely needs the duration) and shows `0:00` until then, as it always has. - **A destroyed player can be re-initialized again.** `destroy()` emptied the container and dropped the instance but left `data-waveform-initialized="true"` on the element. `WaveformPlayer.init()` checks that flag before the instance lookup, so the element was skipped by every later scan and stayed blank permanently. Affected `destroyAll()` + `init()` resets and any teardown/remount cycle that reuses the same element instead of re-rendering it. The flag is now cleared with the markup it described. - **`sideEffects` no longer under-declares the entry bundles.** The field listed only `*.css`, which told bundlers every JS file in the package was side-effect-free — but the entry point scans the DOM for `[data-waveform-player]` and assigns `window.WaveformPlayer` at module scope. A declarative-only consumer doing a bare `import '@arraypress/waveform-player'` had an unused-binding import a bundler was licensed to drop, silently removing auto-init. The ESM/CJS/IIFE entries are now declared. No behavior or output change; the pure modules under `src/js/` are still tree-shakeable. [#25]: https://github.com/arraypress/waveform-player/issues/25 ## [1.25.0] — 2026-08-11 ### Fixed - **A valid-but-wrong option no longer takes the player down.** `JSON.parse` validates syntax, not shape, so `data-playback-rates="2"` or `data-markers='"hello"'` parsed cleanly and then threw at the first `.map()` / `.forEach()` — killing the whole player from a typo. Every option is now normalized once, on the merged result, so an unusable value resolves to its documented default and warns instead of throwing. - **Non-numeric geometry no longer renders an invisible player.** `data-height="tall"` parsed to `NaN`, which sized the canvas to zero with an empty console. `height`, `samples`, `barWidth`, `barSpacing`, `barRadius`, `bpm` and `playbackRate` now fall back to their defaults (and clamp to sane ranges) with a warning naming the option. - **Enumerated options are checked against their vocabularies.** `layout`, `buttonStyle`, `artworkPosition`, `waveformStyle`, `waveformGradient`, `audioMode`, `preload`, `colorPreset` and `crossOrigin` resolve to their defaults when unrecognised. `crossOrigin` mattered most: any unrecognised value makes the browser fall back to `anonymous`, forcing a CORS request the caller never asked for. - **The speed menu can no longer disagree with the audio.** Rates outside the supported range were rendered as buttons but clamped on click, so the label read `10x` while playback ran at the clamp and no menu item ever highlighted. Out-of-range rates are dropped from the menu. - **Markers are validated per entry.** A marker without a usable `time` produced `left: NaN%` and silently stacked at the left edge; a marker without a `label` rendered the string `"undefined"` into its tooltip and `aria-label`. Both are now dropped/defaulted, including markers arriving from a peaks JSON sidecar. - **Non-function callbacks** (`onPlay`, `onEnd`, …) are rejected at configuration time rather than throwing mid-playback. ### Changed - **`setPlaybackRate` now clamps to 0.25–4** (was 0.5–2), the range browsers keep audible — so `playbackRates` can offer the 2.5x/3x speeds podcast and audiobook UIs expect. The default menu is unchanged. - **`playbackRates` accepts a bare list.** `data-playback-rates="0.5, 1, 2"` now works alongside the JSON array form; previously it failed to parse and was silently dropped. - **Boolean options accept attribute-shaped strings.** `showTime: 'false'` reads as `false` rather than truthy, which is what a wrapper that stringifies props actually means. - New internal coercion helpers (`toFiniteNumber`, `toArray`, `toNumberArray`, `toBool`, `toEnum`) back all of the above; `setWaveformData` now shares them, so a peaks string with junk in it yields no peaks rather than `NaN` ones. Thanks to [@scruffian](https://github.com/scruffian) for raising declarative config validation in [#22](https://github.com/arraypress/waveform-player/pull/22). ## [1.24.5] — 2026-08-10 ### Fixed - **Caller-supplied peaks are drawn before the metadata wait, not after it.** `load()` assigned the `