# 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. ::: ## [1.17.0] — 2026-07-01 ### Added - **Seekbar drag-to-scrub.** Press and drag on the waveform/seekbar to scrub; the seek commits on release, so audio keeps playing during the drag instead of re-seeking on every move. - **Opt-in circular seek handle** on the `seekbar` style — `seekHandle` (default `false`, also `data-seek-handle`). A draggable handle that expands on hover; the bar turns it on. ### Changed - **Hardened peak extraction.** Replaced `Math.max(...peaks)` with a loop-based max (no `RangeError` on very large arrays) and centralised the default sample count in a shared `DEFAULT_SAMPLES` (1800) constant so live extraction and `DEFAULT_OPTIONS` can't drift. - **Playback-speed menu accessibility.** The speed toggle now sets `aria-haspopup` / `aria-expanded` (so the open/closed state is announced), closes on `Escape`, and returns focus to the trigger after a rate is chosen. Kept as a lightweight disclosure — the options remain plain buttons in the tab order, no ARIA-menu machinery. ### Fixed - **Activating a control no longer steals keyboard focus onto the player wrapper.** Clicking/activating the play button — or any interactive control (slider, link, input) — now keeps focus on that control; the container only takes focus when the click lands on a non-interactive area. (Reported in #10.) ## [1.16.1] — 2026-06-30 ### Changed - **Active-marker label now flashes then fades** instead of staying visible the whole time the playhead is past a marker. When the playhead reaches a marker its label appears for ~2.5s and then fades out, while the highlight stays. Driven by a `.show-label` class the player adds/removes, so it's CSS-overridable: keep it on with `.waveform-marker.active .waveform-marker-tooltip { opacity: 1 }` or hide it with `{ opacity: 0 !important }`. ## [1.16.0] — 2026-06-30 ### Added - **Hover-time tooltip.** With `showHoverTime: true` (`data-show-hover-time`), a tooltip follows the pointer over the waveform showing the time at that position. The option was previously parsed but did nothing — it's now wired up (works in both self and external modes). - **Active markers.** As playback passes a marker, the player highlights it and reveals its label automatically — it drives the existing `setActiveMarker()` from the progress loop (self and external modes), so chaptered tracks and DJ cues light up as you reach them. - **Artwork fallback.** When the `artwork` image fails to load (404 / broken URL), the player now shows a muted music-note placeholder tile instead of the browser's broken-image icon. ### Fixed - **`index.d.ts` `@default` JSDoc synced with the runtime.** The hand-written type file still annotated `height` as `@default 60` and `barRadius` as `@default 0`; `DEFAULT_OPTIONS` is `64` and `1`. Corrected so IDE tooltips match actual behaviour. Documentation-only — no type or runtime change. ## [1.15.0] — 2026-06-30 ### Fixed - **Live-decoded waveforms are now accurate.** `extractPeaks` inspected only ~1 in 10 frames per window (a real-time speed shortcut), which missed transients and made the waveform *shape* shift noticeably when the sample count changed. It now scans **every frame** — matching WaveformGen's offline output exactly (same shape, not just same amplitude), so a live decode and a pre-generated `.json` render identically. `decodeAudioData` dominates the cost, so the full scan is effectively free. ### Changed - **`samples` default raised 256 → 1800** (the SoundCloud / WaveformGen figure). It is the source peak resolution for live decode only (ignored when `waveform` peaks are supplied), resampled down to the visible bar count. At 256, any waveform wider than ~256 bars — common on wide or high-DPI displays — was upsampled and looked blurry; 1800 keeps it crisp. Paired with the every-frame scan it costs no extra extraction time. Override with `samples` / `data-samples`. ## [1.14.0] — 2026-06-28 ### Added - **`buttonSize` option** (+ `data-button-size`) to size the play/pause button. A number is treated as px; a string (e.g. `'4rem'`) is used verbatim. It sets a new `--wfp-btn-size` CSS variable that scales **both** button styles — `circle` and `minimal`, box *and* glyph — proportionally from a single value, so there are no per-style magic numbers left to drift. The default reproduces the prior 36px sizing exactly. Forwarded by the Astro/React wrappers. ### Fixed - **Minimal play button glyph size now actually applies.** `.waveform-btn svg` (16px) had equal specificity but *later* source order than the minimal-button rule, so it silently won — the glyph was pinned at 16px no matter what the minimal rule said (1.13.0/1.13.1 changes had no visible effect). The rule is now `.waveform-btn.waveform-btn-minimal svg` (higher specificity), and both button styles derive their size from `--wfp-btn-size`. ## [1.13.1] — 2026-06-28 ### Changed - **Minimal play button** (`buttonStyle: 'minimal'`) now renders the bare play/pause glyph at the same visual size as the default circle button — the glyph was noticeably smaller than the ring it replaces. Larger fixed box (2.5rem) + 36px glyph; still a fixed width so the waveform never shifts on play/pause. ## [1.13.0] — 2026-06-28 ### Added - **Live theme switching.** Auto-themed players (no explicit `colorPreset` or hand-set colours) now re-detect the page theme and redraw on a *runtime* light/dark switch — a class/attribute flip on ``/`` (Tailwind `dark`, `data-theme`, `data-color-scheme`) or an OS `prefers-color-scheme` change. Previously the palette was fixed at load, so a toggle left the player stuck in the old theme (invisible waveform/buttons). Event-driven (one shared `MutationObserver` + `matchMedia`, no polling), with a public `refreshTheme()` to trigger it manually. Explicit presets/colours are never overridden. ## [1.12.1] — 2026-06-28 ### Changed - **Larger `minimal` button glyph.** The bare play/pause glyph read too small; bumped the fixed button box to 2.25rem and the icon to 28px (still a fixed box, so it doesn't shift the waveform on play/pause). ## [1.12.0] — 2026-06-28 ### Added - **`bpm` option** (`data-bpm`). Show a known BPM in the badge (with `showBPM`) without decoding the audio — ideal when peaks are pre-generated but the tempo is known (e.g. sample-pack previews). A supplied value wins over detection. ### Fixed - **Minimal button no longer shifts the waveform on play/pause.** The `buttonStyle: 'minimal'` button was auto-width, so swapping the play glyph (optically nudged 1px) for the pause glyph changed its width — moving the adjacent waveform and re-sampling its bars on every toggle. It's now a fixed box, so the canvas stays put. ## [1.11.0] — 2026-06-28 ### Added - **`buttonStyle` option** (`'circle' | 'minimal'`, plus `data-button-style`). `'minimal'` renders a bare play/pause glyph with no circle — the look sample-pack and beat stores use in their preview grids. Composes with the `preview` layout. ### Changed - **Default look refresh.** The `mirror` style now uses `barSpacing: 2` (distinct thin bars rather than a solid fill); the default `barRadius` is `1` (soft caps), default `samples` is `256` (more source fidelity — resampled to fit the bar pitch), and default `height` is `64`. Players that set these explicitly are unaffected. ## [1.10.0] — 2026-06-28 ### Added - **`preview` layout** (`layout: 'preview'` / `data-layout="preview"`) — centers the title under the waveform and trims the meta row, for sample-pack previews and dense grids. ### Changed - **Monochrome by default (shadcn).** The keyboard-focus ring and speed-menu active state are now neutral, driven by a new `--wfp-accent` CSS variable (default zinc). Set `--wfp-accent` to a brand hue to re-tint. ## [1.9.0] — 2026-06-28 ### Added - **`WaveformPlayer.utils.parseDataAttributes`** exposed on the utils bridge, so wrappers (waveform-bar, waveform-playlist) can read the player's full `data-*` option surface off a host element without re-implementing — and drifting from — the contract. ## [1.8.0] — 2026-06-27 ### Added - **TypeScript definitions** — the package now ships a hand-authored `index.d.ts` (wired through a `types` export condition), so bundler/IDE users get full IntelliSense and type-checking with zero runtime bytes. It is the single source of truth for the option surface, the `WaveformPlayer` class API, and a typed custom-event map (`addEventListener('waveformplayer:timeupdate', …)` now types `e.detail`). The React/Astro wrappers can re-export from it instead of re-declaring the option list. - **Dual ESM + CommonJS build** — added a `dist/waveform-player.cjs` bundle and a `require` export condition, so `require('@arraypress/waveform-player')` works under Node CJS (previously ESM-only). External sourcemaps now ship for the ESM, CJS, and minified IIFE bundles. New `./styles.css` export alias. - **Accessibility polish** (near-zero footprint): a `@media (prefers-reduced-motion: reduce)` guard that neutralizes transitions/animations, `role="alert"` on the error node, and `aria-busy` toggled on the seek slider while loading. - **CSS custom properties for spacing** — `--waveform-line-height` (1.4), `--waveform-body-gap` (8px), and `--waveform-track-gap` (12px). Lets embedders (e.g. `@arraypress/waveform-bar`) retune layout without `!important` overrides of internal classes. Defaults are unchanged. - **Expressive bar styling** (bundle-neutral): `barRadius` for rounded bar caps (bars/mirror; falls back to square where `roundRect` is unavailable), and **gradient fills** — `waveformColor`/`progressColor` now also accept an array of CSS colour stops (e.g. `['#fafafa', '#71717a']`) rendered as a vertical canvas gradient. Both work via constructor options, `data-*` attributes (gradients as a JSON array), and the React/Astro wrappers. - **Lifecycle + event-contract completeness** (so controllers/analytics stop reaching into internals): - `waveformplayer:destroy` event — the symmetric counterpart to `:ready`; lets listeners release references on teardown. - `loadTrack(url, title, subtitle, { autoplay: false })` — load / restore / enqueue without forcing playback. - `waveformplayer:ended` now carries `{ currentTime, duration }`, and is synthesized in `external` mode when progress reaches the end (fires once). - `request-play` / `request-pause` / `request-seek` detail now includes `markers` and `waveform`, so controllers don't re-fetch them. - `parseDataAttributes` now reads `data-audio-mode`, `data-show-markers`, `data-accessible-seek`, `data-seek-label`, `data-play-icon`, `data-pause-icon` (previously silently inert on every auto-init path). - **Shorthand aliases** — `style` / `data-style` for `waveformStyle`, and `src` / `data-src` for `url` (e.g. `
`). The canonical names still work and win if both are set. - **Controller-support helpers** (so `@arraypress/waveform-bar` and other external controllers stop reaching into internals / shipping divergent copies): - `player.setActiveMarker(index | null)` — highlight the current marker via a core-owned `.waveform-marker.active` class instead of poking the marker DOM. - `WaveformPlayer.utils` — a static bridge exposing `formatTime`, `extractTitleFromUrl`, `escapeHtml`, and `isSafeHref` (allow-lists `http`/`https`/relative URLs; rejects `javascript:`/`data:` script schemes). - `setVolume()` now coerces + guards non-finite input (no more `NaN` reaching `audio.volume`). - The `request-*` event detail's `artist` now falls back to `subtitle`, so the published contract is self-consistent. - **`errorText` option** (default `'Unable to load audio'`) — customize/localize the message shown when audio fails to load. Escaped before render. Also settable via `data-error-text`. ### Fixed (additional) - Type hygiene in `audio.js`: cast the `webkitAudioContext` fallback (silences ts2568) and dropped a no-op `await` on the synchronous `detectBPM()`. ### Fixed - **AudioContext leak on failed decode** — `generateWaveform()` now closes the context in a `finally` block. Browsers hard-cap live AudioContexts (~6 in Chrome), so leaking one per failed load could break every later player on a catalogue page. - **`destroy()` listener leak** — all document/container/seek listeners are now registered against an `AbortController` and torn down on `destroy()`. The old teardown left the outside-click and container listeners attached. - **Constructor crash in external mode** — `audioMode: 'external'` combined with `showPlaybackSpeed: true` threw on init (dereferencing the null `