@arraypress/waveform-player 1.7.2 → 1.8.1

package/src/js/core.js

@@ -11,7 +11,9 @@ import {
     generateId,
     parseDataAttributes,
     mergeOptions,
-    debounce
+    debounce,
+    clamp,
+    escapeHtml
 } from './utils.js';
 
 import {DEFAULT_OPTIONS, STYLE_DEFAULTS, getColorPreset} from './themes.js';
@@ -32,9 +34,21 @@ export class WaveformPlayer {
     static currentlyPlaying = null;
 
     /**
-     * Create a new WaveformPlayer instance
-     * @param {string|HTMLElement} container - Container element or selector
-     * @param {Object} options - Player options
+     * Create a new WaveformPlayer instance.
+     *
+     * Resolves the container, merges options (defaults < `data-*` attributes <
+     * constructor options), applies the colour preset and style-specific
+     * defaults, registers the instance in the static map, and kicks off
+     * {@link WaveformPlayer#init}. A `waveformplayer:ready` event is dispatched
+     * ~100ms later, once initialization has settled.
+     *
+     * @param {string|HTMLElement} container - Container element, or a CSS
+     *   selector resolved with `document.querySelector`.
+     * @param {Object} [options={}] - Player options. Accepts the shorthand
+     *   aliases `style` (→ `waveformStyle`) and `src` (→ `url`); the canonical
+     *   names win if both are supplied.
+     * @throws {Error} If the container element cannot be found.
+     * @fires WaveformPlayer#waveformplayer:ready
      */
     constructor(container, options = {}) {
         // Resolve container
@@ -43,14 +57,20 @@ export class WaveformPlayer {
             : container;
 
         if (!this.container) {
-            throw new Error('WaveformPlayer: Container element not found');
+            throw new Error('[WaveformPlayer] Container element not found');
         }
 
         // Parse data attributes if present
         const dataOptions = parseDataAttributes(this.container);
 
+        // Shorthand option aliases — `style` -> `waveformStyle`, `src` -> `url`.
+        // The canonical names still work and win if both are supplied.
+        const userOptions = { ...options };
+        if (userOptions.style && !userOptions.waveformStyle) userOptions.waveformStyle = userOptions.style;
+        if (userOptions.src && !userOptions.url) userOptions.url = userOptions.src;
+
         // Merge options: defaults < data attributes < constructor options
-        this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, options);
+        this.options = mergeOptions(DEFAULT_OPTIONS, dataOptions, userOptions);
 
         // Apply color preset (auto-detect if not specified)
         const preset = getColorPreset(this.options.colorPreset);
@@ -85,6 +105,11 @@ export class WaveformPlayer {
         this.updateTimer = null;
         this.resizeObserver = null;
 
+        // All DOM/document listeners are registered with this signal so a
+        // single abort() in destroy() tears every one of them down (the old
+        // destroy left the document-click and container listeners attached).
+        this._ac = new AbortController();
+
         // Generate unique ID
         this.id = this.container.id || generateId(this.options.url);
 
@@ -96,19 +121,53 @@ export class WaveformPlayer {
 
         // Dispatch ready event after initialization
         setTimeout(() => {
-            this.container.dispatchEvent(new CustomEvent('waveformplayer:ready', {
-                bubbles: true,
-                detail: {player: this, url: this.options.url}
-            }));
+            this._emit('waveformplayer:ready', {player: this, url: this.options.url});
         }, 100);
     }
 
+    /**
+     * Build and dispatch a bubbling `waveformplayer:*` CustomEvent on the
+     * container, returning the event so cancelable (request-*) events can have
+     * their `defaultPrevented` checked. Single source of truth for the event
+     * shape — every player event bubbles and carries the supplied detail.
+     * @param {string} type - Full event type, e.g. `'waveformplayer:play'`.
+     * @param {Object} detail - Event detail payload.
+     * @param {boolean} [cancelable=false] - Whether the event is cancelable.
+     * @returns {CustomEvent} The dispatched event.
+     * @private
+     */
+    _emit(type, detail, cancelable = false) {
+        const event = new CustomEvent(type, { bubbles: true, cancelable, detail });
+        this.container.dispatchEvent(event);
+        return event;
+    }
+
+    /**
+     * External-mode seek request: dispatch a cancelable
+     * `waveformplayer:request-seek` and, unless the controller calls
+     * `preventDefault()`, optimistically advance the local progress overlay so
+     * the canvas repaints at once. Shared by the keyboard slider and canvas click.
+     * @param {number} percent - Target position as a 0..1 fraction.
+     * @private
+     * @fires WaveformPlayer#waveformplayer:request-seek
+     */
+    _requestSeek(percent) {
+        const evt = this._emit('waveformplayer:request-seek', { ...this._buildTrackDetail(), percent }, true);
+        if (!evt.defaultPrevented) {
+            this.progress = percent;
+            this.drawWaveform?.();
+        }
+    }
+
     // ============================================
     // Initialization
     // ============================================
 
     /**
-     * Initialize the player
+     * Initialize the player: build the DOM, create the audio element (self
+     * mode only), wire up the feature controls (speed, keyboard, accessible
+     * seek), bind events, attach the resize observer, then size the canvas and
+     * — if a `url` option was given — load it and optionally autoplay.
      * @private
      */
     init() {
@@ -128,17 +187,24 @@ export class WaveformPlayer {
             if (this.options.url) {
                 this.load(this.options.url).then(() => {
                     if (this.options.autoplay) {
-                        this.play();
+                        this.play()?.catch(() => {});
                     }
                 }).catch(error => {
-                    console.error('Failed to load audio:', error);
+                    console.error('[WaveformPlayer] Failed to load audio:', error);
                 });
             }
         });
     }
 
     /**
-     * Create DOM elements
+     * Build the player's DOM tree inside the container and cache element
+     * references.
+     *
+     * Clears the container, resolves button alignment (`auto` → `bottom` for
+     * the `bars` style, `center` otherwise), and conditionally renders the play
+     * button, info row (artwork/title/subtitle), BPM badge, playback-speed
+     * menu, and time display based on the relevant `show*` options. Caches the
+     * canvas, controls, and text elements onto `this`, then sizes the canvas.
      * @private
      */
     createDOM() {
@@ -223,8 +289,8 @@ export class WaveformPlayer {
           <canvas></canvas>
           <div class="waveform-markers"></div>
           <div class="waveform-loading" style="display:none;"></div>
-          <div class="waveform-error" style="display:none;">
-            <span class="waveform-error-text">Unable to load audio</span>
+          <div class="waveform-error" style="display:none;" role="alert">
+            <span class="waveform-error-text">${escapeHtml(this.options.errorText)}</span>
           </div>
         </div>
       </div>
@@ -280,7 +346,9 @@ export class WaveformPlayer {
     // ============================================
 
     /**
-     * Initialize playback speed controls
+     * Apply the configured initial playback rate to the audio element (self
+     * mode only) and, when `showPlaybackSpeed` is enabled, wire up the speed
+     * menu UI via {@link WaveformPlayer#initSpeedControls}.
      * @private
      */
     initPlaybackSpeed() {
@@ -300,7 +368,11 @@ export class WaveformPlayer {
     }
 
     /**
-     * Initialize speed control UI
+     * Wire up the playback-speed menu: toggle it open on the speed button,
+     * close it on any outside click, and apply the chosen rate when a
+     * `.speed-option` is clicked. All listeners are registered against the
+     * instance `AbortController` signal so {@link WaveformPlayer#destroy} tears
+     * them down. No-op if the speed elements are absent.
      * @private
      */
     initSpeedControls() {
@@ -313,12 +385,12 @@ export class WaveformPlayer {
         speedBtn.addEventListener('click', (e) => {
             e.stopPropagation();
             speedMenu.style.display = speedMenu.style.display === 'none' ? 'block' : 'none';
-        });
+        }, {signal: this._ac.signal});
 
         // Close menu when clicking outside
         document.addEventListener('click', () => {
             speedMenu.style.display = 'none';
-        });
+        }, {signal: this._ac.signal});
 
         // Handle speed selection
         speedMenu.addEventListener('click', (e) => {
@@ -328,14 +400,21 @@ export class WaveformPlayer {
                 this.setPlaybackRate(rate);
                 speedMenu.style.display = 'none';
             }
-        });
+        }, {signal: this._ac.signal});
 
         // Set initial UI state
         this.updateSpeedUI();
     }
 
     /**
-     * Initialize keyboard controls
+     * Enable keyboard transport controls on the container.
+     *
+     * The container is focusable only after it is clicked (it carries
+     * `tabindex="-1"` until then, and clicking steals focus from sibling
+     * players). While focused it handles: digits 0-9 (seek to that tenth of
+     * the track), Space (toggle play), and — in self mode only, since
+     * `this.audio` is null in external mode — arrow keys (seek ±5s, volume
+     * ±0.1) and `m`/`M` (mute). Listeners use the instance abort signal.
      * @private
      */
     initKeyboardControls() {
@@ -353,7 +432,7 @@ export class WaveformPlayer {
             // Make this one focusable
             this.container.setAttribute('tabindex', '0');
             this.container.focus();
-        });
+        }, {signal: this._ac.signal});
 
         // Keyboard events. In external mode `this.audio` is null, so
         // seek/volume/mute keys are no-ops (the external controller
@@ -380,10 +459,10 @@ export class WaveformPlayer {
                 ' ': () => this.togglePlay(),
             };
             if (hasAudio) {
-                actions['ArrowLeft']  = () => this.seekTo(Math.max(0, currentTime - 5));
-                actions['ArrowRight'] = () => this.seekTo(Math.min(this.audio.duration, currentTime + 5));
-                actions['ArrowUp']    = () => this.setVolume(Math.min(1, this.audio.volume + 0.1));
-                actions['ArrowDown']  = () => this.setVolume(Math.max(0, this.audio.volume - 0.1));
+                actions['ArrowLeft']  = () => this.seekTo(clamp(currentTime - 5, 0, this.audio.duration));
+                actions['ArrowRight'] = () => this.seekTo(clamp(currentTime + 5, 0, this.audio.duration));
+                actions['ArrowUp']    = () => this.setVolume(clamp(this.audio.volume + 0.1));
+                actions['ArrowDown']  = () => this.setVolume(clamp(this.audio.volume - 0.1));
                 actions['m'] = actions['M'] = () => this.audio.muted = !this.audio.muted;
             }
 
@@ -391,7 +470,7 @@ export class WaveformPlayer {
                 e.preventDefault();
                 actions[key]();
             }
-        });
+        }, {signal: this._ac.signal});
     }
 
     /**
@@ -452,7 +531,7 @@ export class WaveformPlayer {
             e.preventDefault();
             e.stopPropagation();
             this.seekToSeconds(target);
-        });
+        }, {signal: this._ac.signal});
     }
 
     /**
@@ -485,28 +564,24 @@ export class WaveformPlayer {
 
     /**
      * Seek the slider to an absolute time, clamped to the track length.
-     * Routes through the external controller in external mode.
+     *
+     * In self mode this defers to {@link WaveformPlayer#seekTo}. In external
+     * mode it dispatches a cancelable `waveformplayer:request-seek` event with
+     * the target percentage; if the controller doesn't `preventDefault()`, the
+     * local progress/visual is updated optimistically. Either way the ARIA
+     * slider values are refreshed.
      * @param {number} seconds - Target time in seconds.
      * @private
+     * @fires WaveformPlayer#waveformplayer:request-seek
      */
     seekToSeconds(seconds) {
         const duration = this.getSeekDuration();
         if (!duration) return;
 
-        const clamped = Math.max(0, Math.min(seconds, duration));
+        const clamped = clamp(seconds, 0, duration);
 
         if (this.options.audioMode === 'external') {
-            const percent = clamped / duration;
-            const evt = new CustomEvent('waveformplayer:request-seek', {
-                bubbles: true,
-                cancelable: true,
-                detail: { ...this._buildTrackDetail(), percent }
-            });
-            this.container.dispatchEvent(evt);
-            if (!evt.defaultPrevented) {
-                this.progress = percent;
-                this.drawWaveform?.();
-            }
+            this._requestSeek(clamped / duration);
             this.updateSeekAccessibility();
             return;
         }
@@ -517,7 +592,9 @@ export class WaveformPlayer {
 
     /**
      * Set the slider's accessible name from `seekLabel`, falling back to the
-     * track title, then a generic 'Seek'.
+     * track title, then a generic 'Seek'. No-op if the slider isn't present.
+     * @param {string} [title=this.options.title] - Track title to fall back to
+     *   when `seekLabel` is not set.
      * @private
      */
     applySeekLabel(title = this.options.title) {
@@ -569,10 +646,10 @@ export class WaveformPlayer {
         navigator.mediaSession.setActionHandler('play', () => this.play());
         navigator.mediaSession.setActionHandler('pause', () => this.pause());
         navigator.mediaSession.setActionHandler('seekbackward', () => {
-            this.seekTo(Math.max(0, this.audio.currentTime - 10));
+            this.seekTo(clamp(this.audio.currentTime - 10, 0, this.audio.duration));
         });
         navigator.mediaSession.setActionHandler('seekforward', () => {
-            this.seekTo(Math.min(this.audio.duration, this.audio.currentTime + 10));
+            this.seekTo(clamp(this.audio.currentTime + 10, 0, this.audio.duration));
         });
         navigator.mediaSession.setActionHandler('seekto', (details) => {
             if (details.seekTime !== null) {
@@ -586,7 +663,10 @@ export class WaveformPlayer {
     // ============================================
 
     /**
-     * Bind event listeners
+     * Bind the core interaction listeners: play-button click, the `<audio>`
+     * media events (self mode only — external mode is fed state via
+     * {@link WaveformPlayer#setPlayingState}/{@link WaveformPlayer#setProgress}),
+     * canvas click-to-seek, and a debounced window-resize redraw.
      * @private
      */
     bindEvents() {
@@ -622,7 +702,8 @@ export class WaveformPlayer {
     }
 
     /**
-     * Setup resize observer
+     * Observe the canvas's parent element for size changes and re-fit the
+     * canvas on each one. No-op where `ResizeObserver` is unavailable.
      * @private
      */
     setupResizeObserver() {
@@ -642,9 +723,20 @@ export class WaveformPlayer {
     // ============================================
 
     /**
-     * Load audio file
-     * @param {string} url - Audio URL
-     * @returns {Promise<void>}
+     * Load an audio source: set the title, fetch/generate the waveform peaks,
+     * draw them, render markers, and initialise Media Session.
+     *
+     * In self mode the `<audio>` src is assigned and the method awaits
+     * `loadedmetadata` before proceeding. In external mode there is no audio
+     * element, so the src/metadata step is skipped and only the visualization
+     * is built (duration/time come from the controller via
+     * {@link WaveformPlayer#setProgress}). Peaks come from the `waveform`
+     * option when provided, otherwise they are decoded from the audio; a
+     * decode failure falls back to a placeholder waveform. The `onLoad`
+     * callback fires on success.
+     * @param {string} url - Audio URL.
+     * @returns {Promise<void>} Resolves once loading settles (errors are caught
+     *   internally and surfaced through {@link WaveformPlayer#onError}).
      */
     async load(url) {
         try {
@@ -701,7 +793,7 @@ export class WaveformPlayer {
                         this.updateBPMDisplay();
                     }
                 } catch (error) {
-                    console.warn('Using placeholder waveform:', error);
+                    console.warn('[WaveformPlayer] Using placeholder waveform:', error);
                     this.waveformData = generatePlaceholderWaveform(this.options.samples);
                 }
             }
@@ -715,7 +807,7 @@ export class WaveformPlayer {
                 this.options.onLoad(this);
             }
         } catch (error) {
-            console.error('Failed to load audio:', error);
+            // onError() is the single funnel for surfacing + logging errors.
             this.onError(error);
         } finally {
             this.setLoading(false);
@@ -723,11 +815,20 @@ export class WaveformPlayer {
     }
 
     /**
-     * Load a new track
-     * @param {string} url - Audio URL
-     * @param {string} [title] - Track title
-     * @param {string} [subtitle] - Track subtitle
-     * @param {Object} [options] - Additional options
+     * Swap the player to a new track at runtime.
+     *
+     * Pauses any current playback, fully resets the audio element (self mode),
+     * clears error/marker/progress state, merges the new metadata into
+     * `this.options`, updates the subtitle/artwork DOM, then calls
+     * {@link WaveformPlayer#load}. Auto-plays the new track unless
+     * `options.autoplay === false`.
+     * @param {string} url - Audio URL.
+     * @param {string|null} [title=null] - Track title; keeps the existing
+     *   title when null.
+     * @param {string|null} [subtitle=null] - Track subtitle; pass `''` to hide
+     *   the subtitle row, or null to keep the existing one.
+     * @param {Object} [options={}] - Additional options to merge (e.g.
+     *   `preload`, `artwork`, `markers`, `autoplay`).
      * @returns {Promise<void>}
      */
     async loadTrack(url, title = null, subtitle = null, options = {}) {
@@ -789,11 +890,22 @@ export class WaveformPlayer {
         // Clear or update markers
         this.options.markers = options.markers || [];
 
+        // Reset the waveform to the NEW track's peaks, or null to regenerate
+        // from the URL. mergeOptions() above keeps the previous track's
+        // this.options.waveform when the caller passes none, and load() does
+        // `if (this.options.waveform) setWaveformData(...)` — so without this
+        // reset a track loaded without peaks would redraw the PREVIOUS track's
+        // waveform (audio changes, visualization doesn't).
+        this.options.waveform = options.waveform || null;
+
         // Load the new track
         await this.load(url);
 
-        // Auto-play the new track
-        this.play().catch(() => {});
+        // Auto-play the new track unless the caller opted out — lets a
+        // controller load/restore/enqueue without forcing playback.
+        if (options.autoplay !== false) {
+            this.play()?.catch(() => {});
+        }
     }
 
     // ============================================
@@ -801,7 +913,15 @@ export class WaveformPlayer {
     // ============================================
 
     /**
-     * Set waveform data
+     * Normalise externally-supplied waveform data into `this.waveformData` and
+     * redraw.
+     *
+     * Accepts several shapes: a `.json` URL (fetched async; peaks and any
+     * embedded `markers` are applied on resolve), a JSON-encoded array string,
+     * a comma-separated number string, or a plain number array. Malformed
+     * input degrades to an empty array rather than throwing.
+     * @param {string|number[]} data - Peaks as an array, a JSON/CSV string, or
+     *   a URL to a `.json` peaks file.
      * @private
      */
     setWaveformData(data) {
@@ -835,7 +955,9 @@ export class WaveformPlayer {
     }
 
     /**
-     * Draw waveform
+     * Render the current waveform + progress to the canvas via the shared
+     * {@link draw} routine, passing the resolved style and colours. No-op
+     * before the context exists or while there is no peak data.
      * @private
      */
     drawWaveform() {
@@ -850,7 +972,9 @@ export class WaveformPlayer {
     }
 
     /**
-     * Resize canvas
+     * Re-fit the canvas backing store to its parent's width and the configured
+     * height, scaled by the device pixel ratio for crisp rendering, then
+     * redraw. Guards against running after destruction.
      * @private
      */
     resizeCanvas() {
@@ -870,7 +994,15 @@ export class WaveformPlayer {
     }
 
     /**
-     * Render markers on the waveform
+     * Render the configured cue markers as positioned, clickable buttons over
+     * the waveform.
+     *
+     * Clears any existing markers first, then bails out unless `showMarkers` is
+     * on, markers exist, and a duration is known (via the mode-agnostic
+     * {@link WaveformPlayer#getSeekDuration}). Each marker is placed by its
+     * time-as-percentage, carries a tooltip and ARIA label, and seeks on click
+     * (also starting playback when `playOnSeek` is set and currently paused).
+     * Markers past the track duration are skipped with a warning.
      * @private
      */
     renderMarkers() {
@@ -881,20 +1013,22 @@ export class WaveformPlayer {
 
         if (!this.options.showMarkers || !this.options.markers?.length) return;
 
-        // Don't render if audio duration isn't available yet
-        if (!this.audio || !this.audio.duration || this.audio.duration === 0) {
+        // Duration may come from the <audio> (self mode) or the external
+        // controller (external mode) — use the mode-agnostic accessor.
+        const duration = this.getSeekDuration();
+        if (!duration) {
             return;
         }
 
         // Add each marker
         this.options.markers.forEach((marker, index) => {
             // Skip markers that are beyond the audio duration
-            if (marker.time > this.audio.duration) {
-                console.warn(`Marker "${marker.label}" at ${marker.time}s exceeds audio duration of ${this.audio.duration}s`);
+            if (marker.time > duration) {
+                console.warn(`[WaveformPlayer] Marker "${marker.label}" at ${marker.time}s exceeds audio duration of ${duration}s`);
                 return;
             }
 
-            const position = (marker.time / this.audio.duration) * 100;
+            const position = (marker.time / duration) * 100;
 
             const markerEl = document.createElement('button');
             markerEl.className = 'waveform-marker';
@@ -922,13 +1056,34 @@ export class WaveformPlayer {
         });
     }
 
+    /**
+     * Highlight the marker at `index` (toggling an `active` class) and clear
+     * the rest. Pass `null` to clear all. Lets an external controller (e.g. a
+     * DJ bar) reflect the current section without reaching into the player's
+     * private marker DOM.
+     * @param {number|null} index - Marker index to activate, or `null` to clear.
+     */
+    setActiveMarker(index) {
+        if (!this.markersContainer) return;
+        const markers = this.markersContainer.querySelectorAll('.waveform-marker');
+        markers.forEach((el, i) => el.classList.toggle('active', i === index));
+    }
+
     // ============================================
     // Event Handlers
     // ============================================
 
     /**
-     * Handle canvas click
+     * Seek to the clicked horizontal position on the waveform canvas.
+     *
+     * Converts the click X into a 0..1 percentage. In external mode it
+     * dispatches a cancelable `waveformplayer:request-seek` event (updating the
+     * local visual optimistically unless the controller vetoes it); in self
+     * mode it seeks the owned `<audio>` via
+     * {@link WaveformPlayer#seekToPercent}.
+     * @param {MouseEvent} event - The canvas click event.
      * @private
+     * @fires WaveformPlayer#waveformplayer:request-seek
      */
     handleCanvasClick(event) {
         // In external mode the player has no audio of its own —
@@ -939,19 +1094,10 @@ export class WaveformPlayer {
         // controller's progress event will reconcile shortly after).
         const rect = this.canvas.getBoundingClientRect();
         const x = event.clientX - rect.left;
-        const targetPercent = Math.max(0, Math.min(1, x / rect.width));
+        const targetPercent = clamp(x / rect.width);
 
         if (this.options.audioMode === 'external') {
-            const evt = new CustomEvent('waveformplayer:request-seek', {
-                bubbles: true,
-                cancelable: true,
-                detail: { ...this._buildTrackDetail(), percent: targetPercent }
-            });
-            this.container.dispatchEvent(evt);
-            if (!evt.defaultPrevented) {
-                this.progress = targetPercent;
-                this.drawWaveform?.();
-            }
+            this._requestSeek(targetPercent);
             return;
         }
 
@@ -960,7 +1106,10 @@ export class WaveformPlayer {
     }
 
     /**
-     * Set loading state
+     * Toggle the loading state: show/hide the spinner overlay and set
+     * `aria-busy` on the accessible seek slider so assistive tech knows the
+     * player is fetching/decoding.
+     * @param {boolean} loading - True while audio is loading.
      * @private
      */
     setLoading(loading) {
@@ -968,10 +1117,16 @@ export class WaveformPlayer {
         if (this.loadingEl) {
             this.loadingEl.style.display = loading ? 'block' : 'none';
         }
+        // Let assistive tech know the player is busy fetching/decoding.
+        if (this.seekEl) {
+            this.seekEl.setAttribute('aria-busy', loading ? 'true' : 'false');
+        }
     }
 
     /**
-     * Handle metadata loaded
+     * `loadedmetadata` handler (self mode): write the total-time display, now
+     * that duration is known re-render markers, and publish duration to the
+     * accessible seek slider. No-op during destruction.
      * @private
      */
     onMetadataLoaded() {
@@ -988,8 +1143,29 @@ export class WaveformPlayer {
     }
 
     /**
-     * Handle play event
+     * Reflect play/pause state on the transport button: toggle the `playing`
+     * class and swap the play/pause icon visibility. The single source of
+     * truth shared by `onPlay`, `onPause`, and the external-mode
+     * `setPlayingState` pump so they can't drift. No-op without a button.
+     * @param {boolean} isPlaying - Whether playback is active.
+     * @private
+     */
+    setPlayButtonState(isPlaying) {
+        if (!this.playBtn) return;
+        this.playBtn.classList.toggle('playing', isPlaying);
+        const playIcon = this.playBtn.querySelector('.waveform-icon-play');
+        const pauseIcon = this.playBtn.querySelector('.waveform-icon-pause');
+        if (playIcon) playIcon.style.display = isPlaying ? 'none' : 'flex';
+        if (pauseIcon) pauseIcon.style.display = isPlaying ? 'flex' : 'none';
+    }
+
+    /**
+     * `play` handler (self mode): set the playing flag, swap the button to its
+     * pause icon, start the smooth progress loop, dispatch
+     * `waveformplayer:play`, and fire the `onPlay` callback. No-op during
+     * destruction.
      * @private
+     * @fires WaveformPlayer#waveformplayer:play
      */
     onPlay() {
         // Ignore during destruction
@@ -997,22 +1173,12 @@ export class WaveformPlayer {
 
         this.isPlaying = true;
 
-        if (this.playBtn) {
-            this.playBtn.classList.add('playing');
-
-            const playIcon = this.playBtn.querySelector('.waveform-icon-play');
-            const pauseIcon = this.playBtn.querySelector('.waveform-icon-pause');
-            if (playIcon) playIcon.style.display = 'none';
-            if (pauseIcon) pauseIcon.style.display = 'flex';
-        }
+        this.setPlayButtonState(true);
 
         this.startSmoothUpdate();
 
         // Dispatch play event
-        this.container.dispatchEvent(new CustomEvent('waveformplayer:play', {
-            bubbles: true,
-            detail: {player: this, url: this.options.url}
-        }));
+        this._emit('waveformplayer:play', {player: this, url: this.options.url});
 
         if (this.options.onPlay) {
             this.options.onPlay(this);
@@ -1020,8 +1186,12 @@ export class WaveformPlayer {
     }
 
     /**
-     * Handle pause event
+     * `pause` handler (self mode): clear the playing flag, swap the button back
+     * to its play icon, stop the smooth progress loop, dispatch
+     * `waveformplayer:pause`, and fire the `onPause` callback. No-op during
+     * destruction.
      * @private
+     * @fires WaveformPlayer#waveformplayer:pause
      */
     onPause() {
         // Ignore during destruction
@@ -1029,22 +1199,12 @@ export class WaveformPlayer {
 
         this.isPlaying = false;
 
-        if (this.playBtn) {
-            this.playBtn.classList.remove('playing');
-
-            const playIcon = this.playBtn.querySelector('.waveform-icon-play');
-            const pauseIcon = this.playBtn.querySelector('.waveform-icon-pause');
-            if (playIcon) playIcon.style.display = 'flex';
-            if (pauseIcon) pauseIcon.style.display = 'none';
-        }
+        this.setPlayButtonState(false);
 
         this.stopSmoothUpdate();
 
         // Dispatch pause event
-        this.container.dispatchEvent(new CustomEvent('waveformplayer:pause', {
-            bubbles: true,
-            detail: {player: this, url: this.options.url}
-        }));
+        this._emit('waveformplayer:pause', {player: this, url: this.options.url});
 
         if (this.options.onPause) {
             this.options.onPause(this);
@@ -1052,13 +1212,19 @@ export class WaveformPlayer {
     }
 
     /**
-     * Handle ended event
+     * `ended` handler (self mode): reset progress and `currentTime` to the
+     * start, redraw, reset the time display, dispatch `waveformplayer:ended`
+     * (carrying the final time), run {@link WaveformPlayer#onPause}, and fire
+     * the `onEnd` callback. No-op during destruction.
      * @private
+     * @fires WaveformPlayer#waveformplayer:ended
      */
     onEnded() {
         // Ignore during destruction
         if (this.isDestroying) return;
 
+        const duration = this.audio.duration;
+
         this.progress = 0;
         this.audio.currentTime = 0;
         this.drawWaveform();
@@ -1068,11 +1234,9 @@ export class WaveformPlayer {
             this.currentTimeEl.textContent = '0:00';
         }
 
-        // Dispatch ended event
-        this.container.dispatchEvent(new CustomEvent('waveformplayer:ended', {
-            bubbles: true,
-            detail: {player: this, url: this.options.url}
-        }));
+        // Dispatch ended event — carries the final time so listeners (e.g.
+        // analytics) don't have to reach into player.audio.
+        this._emit('waveformplayer:ended', {player: this, url: this.options.url, currentTime: duration, duration});
 
         this.onPause();
 
@@ -1082,14 +1246,18 @@ export class WaveformPlayer {
     }
 
     /**
-     * Handle error event
+     * `error` handler: set the error flag, hide the spinner, reveal the error
+     * overlay, dim the canvas, disable the play button, and fire the `onError`
+     * callback. No-op during destruction.
+     * @param {Event|Error} error - The audio error event, or an Error thrown
+     *   during loading.
      * @private
      */
     onError(error) {
         // Ignore errors during destruction
         if (this.isDestroying) return;
 
-        console.error('Audio error:', error);
+        console.error('[WaveformPlayer] Audio error:', error);
         this.hasError = true;
         this.setLoading(false);
 
@@ -1115,7 +1283,10 @@ export class WaveformPlayer {
     // ============================================
 
     /**
-     * Start smooth update animation
+     * Start the `requestAnimationFrame` loop that drives smooth progress
+     * updates while playing (self mode only — external mode is redrawn by
+     * controller {@link WaveformPlayer#setProgress} pushes). Cancels any
+     * existing loop first so it's safe to call repeatedly.
      * @private
      */
     startSmoothUpdate() {
@@ -1135,7 +1306,7 @@ export class WaveformPlayer {
     }
 
     /**
-     * Stop smooth update animation
+     * Cancel the smooth-update animation frame, if one is scheduled.
      * @private
      */
     stopSmoothUpdate() {
@@ -1146,8 +1317,15 @@ export class WaveformPlayer {
     }
 
     /**
-     * Update progress
+     * Recompute progress from the owned `<audio>` clock and reflect it
+     * everywhere (self mode only — external mode uses
+     * {@link WaveformPlayer#setProgress}).
+     *
+     * Redraws the canvas when progress moves meaningfully, updates the
+     * current-time display, dispatches `waveformplayer:timeupdate`, fires the
+     * `onTimeUpdate` callback, and refreshes the accessible slider values.
      * @private
+     * @fires WaveformPlayer#waveformplayer:timeupdate
      */
     updateProgress() {
         // Self-mode only — external mode receives progress via
@@ -1166,15 +1344,13 @@ export class WaveformPlayer {
         }
 
         // Dispatch timeupdate event
-        this.container.dispatchEvent(new CustomEvent('waveformplayer:timeupdate', {
-            bubbles: true,
-            detail: {
-                player: this,
-                currentTime: this.audio.currentTime,
-                duration: this.audio.duration,
-                url: this.options.url
-            }
-        }));
+        this._emit('waveformplayer:timeupdate', {
+            player: this,
+            currentTime: this.audio.currentTime,
+            duration: this.audio.duration,
+            progress: this.progress,
+            url: this.options.url
+        });
 
         if (this.options.onTimeUpdate) {
             this.options.onTimeUpdate(this.audio.currentTime, this.audio.duration, this);
@@ -1188,7 +1364,7 @@ export class WaveformPlayer {
     // ============================================
 
     /**
-     * Update BPM display
+     * Show the detected BPM in the badge, once a value has been detected.
      * @private
      */
     updateBPMDisplay() {
@@ -1199,10 +1375,17 @@ export class WaveformPlayer {
     }
 
     /**
-     * Update speed UI to reflect current rate
+     * Sync the speed control's label and the menu's active-option highlight to
+     * the audio element's current `playbackRate`. No-op in external mode (no
+     * owned `<audio>`), which also avoids reading `playbackRate` before the
+     * element exists.
      * @private
      */
     updateSpeedUI() {
+        // External mode owns no <audio>; nothing to reflect (and reading
+        // this.audio.playbackRate here would throw during construction).
+        if (!this.audio) return;
+
         const speedValue = this.container.querySelector('.speed-value');
         if (speedValue) {
             const rate = this.audio.playbackRate;
@@ -1233,7 +1416,12 @@ export class WaveformPlayer {
      * setPlayingState() / setProgress(). Calling preventDefault() on
      * the event lets the controller veto the play (state is unchanged).
      *
-     * @return {Promise|undefined}
+     * When `singlePlay` is enabled, any other currently-playing instance is
+     * paused first.
+     *
+     * @return {Promise|undefined} The promise from `HTMLMediaElement.play()` in
+     *   self mode; `undefined` in external mode.
+     * @fires WaveformPlayer#waveformplayer:request-play
      */
     play() {
         if (this.options.singlePlay && WaveformPlayer.currentlyPlaying &&
@@ -1242,12 +1430,7 @@ export class WaveformPlayer {
         }
 
         if (this.options.audioMode === 'external') {
-            const evt = new CustomEvent('waveformplayer:request-play', {
-                bubbles: true,
-                cancelable: true,
-                detail: this._buildTrackDetail()
-            });
-            this.container.dispatchEvent(evt);
+            const evt = this._emit('waveformplayer:request-play', this._buildTrackDetail(), true);
             // If the controller cancels (preventDefault), don't claim
             // "currentlyPlaying" — the controller didn't accept the play.
             if (!evt.defaultPrevented) {
@@ -1265,17 +1448,15 @@ export class WaveformPlayer {
      *
      * In `audioMode: 'external'`, dispatches `waveformplayer:request-pause`
      * (cancelable) and does NOT touch any audio element. See play().
+     *
+     * @fires WaveformPlayer#waveformplayer:request-pause
      */
     pause() {
         if (WaveformPlayer.currentlyPlaying === this) {
             WaveformPlayer.currentlyPlaying = null;
         }
         if (this.options.audioMode === 'external') {
-            this.container.dispatchEvent(new CustomEvent('waveformplayer:request-pause', {
-                bubbles: true,
-                cancelable: true,
-                detail: this._buildTrackDetail()
-            }));
+            this._emit('waveformplayer:request-pause', this._buildTrackDetail(), true);
             return;
         }
         this.audio.pause();
@@ -1295,8 +1476,12 @@ export class WaveformPlayer {
             url:      this.options.url,
             title:    this.options.title,
             subtitle: this.options.subtitle,
-            artist:   this.options.artist,
+            // Core has no separate `artist` option; mirror subtitle so the
+            // published event detail is self-consistent for controllers.
+            artist:   this.options.artist || this.options.subtitle,
             artwork:  this.options.artwork,
+            markers:  this.options.markers,
+            waveform: this.options.waveform,
             id:       this.id,
             player:   this
         };
@@ -1307,31 +1492,26 @@ export class WaveformPlayer {
      * touching audio. Mirrors what onPlay()/onPause() do but skips the
      * audio-element interactions. Safe to call repeatedly — idempotent.
      *
-     * @param {boolean} playing
+     * Only dispatches `waveformplayer:play`/`waveformplayer:pause` (and runs
+     * the matching callback) on an actual transition, starting/stopping the
+     * smooth-update loop accordingly.
+     *
+     * @param {boolean} playing - True to enter the playing state, false to
+     *   enter the paused state.
+     * @fires WaveformPlayer#waveformplayer:play
+     * @fires WaveformPlayer#waveformplayer:pause
      */
     setPlayingState(playing) {
         const wasPlaying = this.isPlaying;
         this.isPlaying = !!playing;
-        if (this.playBtn) {
-            this.playBtn.classList.toggle('playing', this.isPlaying);
-            const playIcon  = this.playBtn.querySelector('.waveform-icon-play');
-            const pauseIcon = this.playBtn.querySelector('.waveform-icon-pause');
-            if (playIcon)  playIcon.style.display  = this.isPlaying ? 'none'   : 'flex';
-            if (pauseIcon) pauseIcon.style.display = this.isPlaying ? 'flex'   : 'none';
-        }
+        this.setPlayButtonState(this.isPlaying);
         if (this.isPlaying && !wasPlaying) {
             this.startSmoothUpdate?.();
-            this.container.dispatchEvent(new CustomEvent('waveformplayer:play', {
-                bubbles: true,
-                detail: {player: this, url: this.options.url}
-            }));
+            this._emit('waveformplayer:play', {player: this, url: this.options.url});
             if (this.options.onPlay) this.options.onPlay(this);
         } else if (!this.isPlaying && wasPlaying) {
             this.stopSmoothUpdate?.();
-            this.container.dispatchEvent(new CustomEvent('waveformplayer:pause', {
-                bubbles: true,
-                detail: {player: this, url: this.options.url}
-            }));
+            this._emit('waveformplayer:pause', {player: this, url: this.options.url});
             if (this.options.onPause) this.options.onPause(this);
         }
     }
@@ -1341,32 +1521,58 @@ export class WaveformPlayer {
      * from an external clock (e.g. WaveformBar's audio element's
      * timeupdate). Drives the canvas redraw + the time displays.
      *
-     * @param {number} currentTime  Current playback position in seconds.
-     * @param {number} duration     Total track duration in seconds.
+     * Redraws the canvas, updates the current/total time displays, stores the
+     * external duration for the accessible slider, dispatches
+     * `waveformplayer:timeupdate`, runs `onTimeUpdate`, and synthesizes a
+     * one-shot `waveformplayer:ended` (with `onEnd`) when progress reaches the
+     * end. No-op for a non-positive duration.
+     *
+     * @param {number} currentTime - Current playback position in seconds.
+     * @param {number} duration - Total track duration in seconds.
+     * @fires WaveformPlayer#waveformplayer:timeupdate
+     * @fires WaveformPlayer#waveformplayer:ended
      */
     setProgress(currentTime, duration) {
         if (!duration || duration <= 0) return;
-        this.progress = Math.max(0, Math.min(1, currentTime / duration));
+        this.progress = clamp(currentTime / duration);
         // Mirror the existing display update code so callers don't have
         // to know which DOM elements live where.
         if (this.currentTimeEl)  this.currentTimeEl.textContent  = formatTime(currentTime);
-        if (this.totalTimeEl && (!this.totalTimeEl.dataset._extSet || this._extDuration !== duration)) {
+        // Publish the duration unconditionally — the accessible seek slider
+        // and keyboard seeking read getSeekDuration()/_extDuration even when
+        // there's no time display to update.
+        this._extDuration = duration;
+        if (this.totalTimeEl && (!this.totalTimeEl.dataset._extSet || this.totalTimeEl.dataset._extDur !== String(duration))) {
             this.totalTimeEl.textContent = formatTime(duration);
             this.totalTimeEl.dataset._extSet = '1';
-            this._extDuration = duration;
+            this.totalTimeEl.dataset._extDur = String(duration);
         }
         this.drawWaveform?.();
-        this.container.dispatchEvent(new CustomEvent('waveformplayer:timeupdate', {
-            bubbles: true,
-            detail: {player: this, currentTime, duration, progress: this.progress}
-        }));
-        if (this.options.onTimeUpdate) this.options.onTimeUpdate(this, currentTime, duration);
+        this._emit('waveformplayer:timeupdate', {player: this, currentTime, duration, progress: this.progress, url: this.options.url});
+        // Same (currentTime, duration, player) signature as self mode — the
+        // arg order used to be swapped here, which made one shared handler
+        // impossible across audioModes.
+        if (this.options.onTimeUpdate) this.options.onTimeUpdate(currentTime, duration, this);
+
+        // External mode has no <audio> 'ended' event — synthesize one when the
+        // controller's progress reaches the end (fires once per playthrough).
+        if (this.progress >= 1) {
+            if (!this._extEnded) {
+                this._extEnded = true;
+                this._emit('waveformplayer:ended', {player: this, url: this.options.url, currentTime: duration, duration});
+                if (this.options.onEnd) this.options.onEnd(this);
+            }
+        } else {
+            this._extEnded = false;
+        }
 
         this.updateSeekAccessibility();
     }
 
     /**
-     * Toggle play/pause
+     * Toggle between play and pause based on the current `isPlaying` state.
+     * Works in both audio modes (in external mode it routes through the
+     * request-play/pause events).
      */
     togglePlay() {
         if (this.isPlaying) {
@@ -1377,45 +1583,56 @@ export class WaveformPlayer {
     }
 
     /**
-     * Seek to time in seconds
-     * @param {number} seconds - Time in seconds
+     * Seek the owned `<audio>` element to an absolute time, clamped to
+     * `[0, duration]`, and refresh progress. Self mode only — a no-op when
+     * there is no audio element or duration. External-mode keyboard/click
+     * seeks go through {@link WaveformPlayer#seekToSeconds} instead.
+     * @param {number} seconds - Target time in seconds.
      */
     seekTo(seconds) {
         if (this.audio && this.audio.duration) {
-            this.audio.currentTime = Math.max(0, Math.min(seconds, this.audio.duration));
+            this.audio.currentTime = clamp(seconds, 0, this.audio.duration);
             this.updateProgress();
         }
     }
 
     /**
-     * Seek to percentage
-     * @param {number} percent - Percentage (0-1)
+     * Seek the owned `<audio>` element to a fraction of the track, clamped to
+     * `[0, 1]`, and refresh progress. Self mode only — a no-op without an audio
+     * element or duration.
+     * @param {number} percent - Position as a fraction from 0 to 1.
      */
     seekToPercent(percent) {
         if (this.audio && this.audio.duration) {
-            this.audio.currentTime = this.audio.duration * Math.max(0, Math.min(1, percent));
+            this.audio.currentTime = this.audio.duration * clamp(percent);
             this.updateProgress();
         }
     }
 
     /**
-     * Set volume
-     * @param {number} volume - Volume (0-1)
+     * Set the owned `<audio>` element's volume, clamped to `[0, 1]`. Self mode
+     * only — a no-op in external mode where the controller owns volume.
+     * @param {number} volume - Volume from 0 (silent) to 1 (full).
      */
     setVolume(volume) {
-        if (this.audio) {
-            this.audio.volume = Math.max(0, Math.min(1, volume));
+        // Coerce + guard: a non-finite value (e.g. from a bad config or stale
+        // storage) must not propagate NaN into audio.volume (which throws).
+        const v = Number(volume);
+        if (this.audio && Number.isFinite(v)) {
+            this.audio.volume = clamp(v);
         }
     }
 
     /**
-     * Set playback rate
-     * @param {number} rate - Playback rate (0.5 to 2)
+     * Set the owned `<audio>` element's playback rate (clamped to 0.5–2),
+     * persist it onto `this.options.playbackRate`, and refresh the speed UI.
+     * Self mode only — a no-op in external mode.
+     * @param {number} rate - Desired playback rate; clamped to the 0.5–2 range.
      */
     setPlaybackRate(rate) {
         if (!this.audio) return;
 
-        const clampedRate = Math.max(0.5, Math.min(2, rate));
+        const clampedRate = clamp(rate, 0.5, 2);
         this.audio.playbackRate = clampedRate;
         this.options.playbackRate = clampedRate;
 
@@ -1423,16 +1640,31 @@ export class WaveformPlayer {
     }
 
     /**
-     * Destroy player instance
+     * Tear down the player and release all resources.
+     *
+     * Flags destruction (so in-flight handlers bail), dispatches
+     * `waveformplayer:destroy`, stops playback and the animation loop, aborts
+     * every listener registered on the instance signal, disconnects the resize
+     * observer, removes the window-resize handler, drops the instance from the
+     * static map and `currentlyPlaying`, resets/releases the audio element, and
+     * empties the container.
+     * @fires WaveformPlayer#waveformplayer:destroy
      */
     destroy() {
         // Set a flag to indicate we're destroying
         this.isDestroying = true;
 
+        // Let listeners (analytics, controllers) release their references
+        // before teardown — the symmetric counterpart to waveformplayer:ready.
+        this._emit('waveformplayer:destroy', {player: this, url: this.options.url});
+
         // Stop playback and animations
         this.pause();
         this.stopSmoothUpdate();
 
+        // Tear down every document/container/seek listener in one shot.
+        this._ac?.abort();
+
         // Disconnect observer
         if (this.resizeObserver) {
             this.resizeObserver.disconnect();
@@ -1526,7 +1758,7 @@ export class WaveformPlayer {
             const result = await generateWaveform(url, samples);
             return result.peaks;
         } catch (error) {
-            console.error('Failed to generate waveform:', error);
+            console.error('[WaveformPlayer] Failed to generate waveform:', error);
             throw error;
         }
     }