@arraypress/waveform-player 1.7.2 → 1.8.1

package/src/js/drawing.js

@@ -3,10 +3,113 @@
  * @description Core waveform drawing styles optimized for visual distinction at all sizes
  */
 
-import {resampleData} from './utils.js';
+import {resampleData, clamp} from './utils.js';
 
 /**
- * Draw standard bars waveform - Classic vertical bars
+ * Resolve a fill value that may be a CSS colour string OR an array of colour
+ * stops (rendered as a vertical canvas gradient). Bundle-light gradient
+ * support: pass e.g. `waveformColor: ['#fafafa', '#71717a']`.
+ * A single-element array collapses to that one colour; a multi-element array
+ * is spread evenly from top (y=0) to bottom (y=height).
+ * @private
+ * @param {CanvasRenderingContext2D} ctx - Canvas context used to build the gradient.
+ * @param {string|string[]} value - A CSS colour string, or an array of colour stops.
+ * @param {number} height - Canvas height in device pixels (gradient span).
+ * @returns {string|CanvasGradient} The original string, or a vertical linear gradient.
+ */
+function makeFill(ctx, value, height) {
+    if (!Array.isArray(value)) return value;
+    if (value.length === 1) return value[0];
+    const grad = ctx.createLinearGradient(0, 0, 0, height);
+    value.forEach((c, i) => grad.addColorStop(i / (value.length - 1), c));
+    return grad;
+}
+
+/**
+ * Fill a bar rect, optionally with rounded caps (`barRadius`). Falls back to
+ * a plain fillRect where `roundRect` is unavailable (older Safari) — square
+ * bars, no error. Radii are clamped to half the rect's width/height so a
+ * large `barRadius` never overflows a thin or short bar.
+ * @private
+ * @param {CanvasRenderingContext2D} ctx - Canvas context (current fillStyle is used).
+ * @param {number} x - Left edge of the bar in device pixels.
+ * @param {number} y - Top edge of the bar in device pixels.
+ * @param {number} w - Bar width in device pixels.
+ * @param {number} h - Bar height in device pixels (may be negative for upward fills).
+ * @param {number|number[]} radii - Corner radius (number, or [tl, tr, br, bl]).
+ * @returns {void}
+ */
+function fillBar(ctx, x, y, w, h, radii) {
+    const any = Array.isArray(radii) ? radii.some(r => r > 0) : radii > 0;
+    if (any && typeof ctx.roundRect === 'function') {
+        const max = Math.min(w / 2, Math.abs(h) / 2);
+        const clampR = (r) => clamp(r, 0, max);
+        ctx.beginPath();
+        ctx.roundRect(x, y, w, h, Array.isArray(radii) ? radii.map(clampR) : clampR(radii));
+        ctx.fill();
+    } else {
+        ctx.fillRect(x, y, w, h);
+    }
+}
+
+/**
+ * Scale the configured `barRadius` into device pixels (scalar).
+ * @private
+ * @param {Object} options - Drawing options (`barRadius` in CSS pixels, defaults to 0).
+ * @param {number} dpr - Device pixel ratio multiplier.
+ * @returns {number} The bar corner radius in device pixels.
+ */
+function barRadiusPx(options, dpr) {
+    return (options.barRadius || 0) * dpr;
+}
+
+/**
+ * Top-rounded corner radii for bottom-anchored bars: [tl, tr, br, bl].
+ * Only the top two corners are rounded so bars sit flush on the baseline.
+ * @private
+ * @param {Object} options - Drawing options (supplies `barRadius`).
+ * @param {number} dpr - Device pixel ratio multiplier.
+ * @returns {number[]} Corner radii in device pixels as [tl, tr, br, bl].
+ */
+function barRadii(options, dpr) {
+    const r = barRadiusPx(options, dpr);
+    return [r, r, 0, 0];
+}
+
+/**
+ * Trace a horizontal rounded-capsule (stadium) path from `startX` to `endX`,
+ * ready to fill. The end caps are semicircles of radius `barHeight / 2`.
+ * @private
+ * @param {CanvasRenderingContext2D} ctx - Canvas context.
+ * @param {number} startX - Left edge x (also the left cap centre).
+ * @param {number} endX - Right edge x.
+ * @param {number} centerY - Vertical centre of the capsule.
+ * @param {number} barHeight - Capsule thickness in pixels.
+ * @returns {void}
+ */
+function capsulePath(ctx, startX, endX, centerY, barHeight) {
+    const r = barHeight / 2;
+    ctx.beginPath();
+    ctx.moveTo(startX, centerY - r);
+    ctx.lineTo(endX - r, centerY - r);
+    ctx.arc(endX - r, centerY, r, -Math.PI / 2, Math.PI / 2);
+    ctx.lineTo(startX, centerY + r);
+    ctx.arc(startX, centerY, r, Math.PI / 2, -Math.PI / 2);
+    ctx.closePath();
+}
+
+/**
+ * Draw standard bars waveform - classic vertical bars anchored to the baseline.
+ * Peaks are resampled to fit the available bar slots, drawn at 90% of canvas
+ * height, then the progress portion is repainted in `progressColor` via a
+ * left-anchored clip rect.
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
+ * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
+ * @param {number[]} peaks - Normalised waveform peak values (0-1).
+ * @param {number} progress - Playback progress (0-1) that drives the colour overlay.
+ * @param {Object} options - Drawing options: `barWidth`, `barSpacing`, `barRadius`,
+ *   `color`, `progressColor` (colour strings or gradient stop arrays).
+ * @returns {void}
  */
 export function drawBars(ctx, canvas, peaks, progress, options) {
     const dpr = window.devicePixelRatio || 1;
@@ -16,10 +119,14 @@ export function drawBars(ctx, canvas, peaks, progress, options) {
     const resampledPeaks = resampleData(peaks, barCount);
     const height = canvas.height;
     const progressWidth = progress * canvas.width;
+    const radii = barRadii(options, dpr);
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
 
     ctx.clearRect(0, 0, canvas.width, canvas.height);
 
     // Draw all bars first
+    ctx.fillStyle = baseFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
         const x = i * (barWidth + barSpacing);
         if (x + barWidth > canvas.width) break;
@@ -28,8 +135,7 @@ export function drawBars(ctx, canvas, peaks, progress, options) {
         // Draw from bottom up, not centered
         const y = height - peakHeight;
 
-        ctx.fillStyle = options.color;
-        ctx.fillRect(x, y, barWidth, peakHeight);
+        fillBar(ctx, x, y, barWidth, peakHeight, radii);
     }
 
     // Progress overlay
@@ -38,6 +144,7 @@ export function drawBars(ctx, canvas, peaks, progress, options) {
     ctx.rect(0, 0, progressWidth, height);
     ctx.clip();
 
+    ctx.fillStyle = progFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
         const x = i * (barWidth + barSpacing);
         if (x > progressWidth) break;
@@ -46,18 +153,24 @@ export function drawBars(ctx, canvas, peaks, progress, options) {
         // Draw from bottom up, not centered
         const y = height - peakHeight;
 
-        ctx.fillStyle = options.progressColor;
-        ctx.fillRect(x, y, barWidth, peakHeight);
+        fillBar(ctx, x, y, barWidth, peakHeight, radii);
     }
 
     ctx.restore();
 }
 
 /**
- * Draw mirror/SoundCloud style waveform - Symmetrical bars
- */
-/**
- * Draw mirror/SoundCloud style waveform - Symmetrical bars
+ * Draw mirror/SoundCloud style waveform - symmetrical bars about the centre line.
+ * Each peak is drawn twice (45% of height up and down) with the upper cap rounded
+ * on top and the lower cap rounded on the bottom; the progress portion is then
+ * repainted in `progressColor` through a left-anchored clip rect.
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
+ * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
+ * @param {number[]} peaks - Normalised waveform peak values (0-1).
+ * @param {number} progress - Playback progress (0-1) that drives the colour overlay.
+ * @param {Object} options - Drawing options: `barWidth`, `barSpacing`, `barRadius`,
+ *   `color`, `progressColor`.
+ * @returns {void}
  */
 export function drawMirror(ctx, canvas, peaks, progress, options) {
     const dpr = window.devicePixelRatio || 1;
@@ -68,19 +181,24 @@ export function drawMirror(ctx, canvas, peaks, progress, options) {
     const height = canvas.height;
     const centerY = height / 2;
     const progressWidth = progress * canvas.width;
+    const r = barRadiusPx(options, dpr);
+    const topRadii = [r, r, 0, 0];   // round the upper cap
+    const botRadii = [0, 0, r, r];   // round the lower cap
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
 
     ctx.clearRect(0, 0, canvas.width, canvas.height);
 
     // Draw all bars
+    ctx.fillStyle = baseFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
         const x = i * (barWidth + barSpacing);
         if (x + barWidth > canvas.width) break;
 
         const peakHeight = resampledPeaks[i] * height * 0.45;
 
-        ctx.fillStyle = options.color;
-        ctx.fillRect(x, centerY - peakHeight, barWidth, peakHeight);
-        ctx.fillRect(x, centerY, barWidth, peakHeight);
+        fillBar(ctx, x, centerY - peakHeight, barWidth, peakHeight, topRadii);
+        fillBar(ctx, x, centerY, barWidth, peakHeight, botRadii);
     }
 
     // Progress overlay
@@ -89,22 +207,32 @@ export function drawMirror(ctx, canvas, peaks, progress, options) {
     ctx.rect(0, 0, progressWidth, height);
     ctx.clip();
 
+    ctx.fillStyle = progFill;
     for (let i = 0; i < resampledPeaks.length; i++) {
         const x = i * (barWidth + barSpacing);
         if (x > progressWidth) break;
 
         const peakHeight = resampledPeaks[i] * height * 0.45;
 
-        ctx.fillStyle = options.progressColor;
-        ctx.fillRect(x, centerY - peakHeight, barWidth, peakHeight);
-        ctx.fillRect(x, centerY, barWidth, peakHeight);
+        fillBar(ctx, x, centerY - peakHeight, barWidth, peakHeight, topRadii);
+        fillBar(ctx, x, centerY, barWidth, peakHeight, botRadii);
     }
 
     ctx.restore();
 }
 
 /**
- * Draw line/oscilloscope style waveform - Smooth flowing wave with glow
+ * Draw line/oscilloscope style waveform - smooth flowing wave with glow.
+ * Renders a faint oscilloscope grid (centre line + 10 vertical divisions), the
+ * full waveform as a bezier-smoothed curve, then the played portion on top with
+ * a coloured shadow glow. Peaks are modulated by a sine term so the line undulates
+ * rather than reading as static bars.
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
+ * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
+ * @param {number[]} peaks - Normalised waveform peak values (0-1).
+ * @param {number} progress - Playback progress (0-1); the glowing curve is only drawn when > 0.
+ * @param {Object} options - Drawing options: `color` (base wave), `progressColor` (played wave).
+ * @returns {void}
  */
 export function drawLine(ctx, canvas, peaks, progress, options) {
     const width = canvas.width;
@@ -114,7 +242,15 @@ export function drawLine(ctx, canvas, peaks, progress, options) {
 
     ctx.clearRect(0, 0, width, height);
 
-    // Helper to draw a smooth curve through the peaks
+    /**
+     * Stroke a bezier-smoothed curve through the (optionally sine-modulated) peaks.
+     * @private
+     * @param {string} color - Stroke colour (and shadow colour when glowing).
+     * @param {number} lineWidth - Stroke width in pixels.
+     * @param {number} [endProgress=1] - Fraction (0-1) of the peaks to draw, left to right.
+     * @param {boolean} [addGlow=false] - When true, applies a coloured shadow blur for a glow effect.
+     * @returns {void}
+     */
     const drawCurve = (color, lineWidth, endProgress = 1, addGlow = false) => {
         if (addGlow) {
             ctx.shadowBlur = 12;
@@ -190,7 +326,18 @@ export function drawLine(ctx, canvas, peaks, progress, options) {
 }
 
 /**
- * Draw blocks/LED meter style waveform - Segmented blocks
+ * Draw blocks/LED meter style waveform - segmented blocks growing from the centre.
+ * Each bar's height is quantised into fixed-size blocks separated by gaps, drawn
+ * symmetrically up and down from the centre line (the shared centre block is not
+ * duplicated downward). Per-bar colour is chosen by comparing the bar's x against
+ * the played width — there is no clip overlay here.
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
+ * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
+ * @param {number[]} peaks - Normalised waveform peak values (0-1).
+ * @param {number} progress - Playback progress (0-1) used to pick each bar's colour.
+ * @param {Object} options - Drawing options: `barWidth` (default 3), `barSpacing` (default 1),
+ *   `color`, `progressColor`.
+ * @returns {void}
  */
 export function drawBlocks(ctx, canvas, peaks, progress, options) {
     const dpr = window.devicePixelRatio || 1;
@@ -203,6 +350,8 @@ export function drawBlocks(ctx, canvas, peaks, progress, options) {
     const blockGap = 2 * dpr;
     const progressWidth = progress * canvas.width;
     const centerY = height / 2;
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
 
     ctx.clearRect(0, 0, canvas.width, canvas.height);
 
@@ -213,7 +362,7 @@ export function drawBlocks(ctx, canvas, peaks, progress, options) {
         const peakHeight = resampledPeaks[i] * height * 0.9;
         const blockCount = Math.floor(peakHeight / (blockSize + blockGap));
 
-        ctx.fillStyle = x < progressWidth ? options.progressColor : options.color;
+        ctx.fillStyle = x < progressWidth ? progFill : baseFill;
 
         // Draw blocks from center outward
         for (let j = 0; j < blockCount; j++) {
@@ -231,7 +380,17 @@ export function drawBlocks(ctx, canvas, peaks, progress, options) {
 }
 
 /**
- * Draw dots style waveform - Circular points
+ * Draw dots style waveform - pairs of circular points mirrored about the centre.
+ * For each sample a dot is drawn above and below the centre line at half the peak
+ * height; dot radius scales with bar width but is floored at 1.5 device pixels.
+ * Per-dot colour is chosen by comparing x against the played width (no clip overlay).
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
+ * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
+ * @param {number[]} peaks - Normalised waveform peak values (0-1).
+ * @param {number} progress - Playback progress (0-1) used to pick each dot's colour.
+ * @param {Object} options - Drawing options: `barWidth` (default 2), `barSpacing` (default 3),
+ *   `color`, `progressColor`.
+ * @returns {void}
  */
 export function drawDots(ctx, canvas, peaks, progress, options) {
     const dpr = window.devicePixelRatio || 1;
@@ -243,6 +402,8 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
     const dotRadius = Math.max(1.5 * dpr, barWidth / 2);
     const progressWidth = progress * canvas.width;
     const centerY = height / 2;
+    const baseFill = makeFill(ctx, options.color, height);
+    const progFill = makeFill(ctx, options.progressColor, height);
 
     ctx.clearRect(0, 0, canvas.width, canvas.height);
 
@@ -252,7 +413,7 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
 
         const peakHeight = resampledPeaks[i] * height * 0.9;
 
-        ctx.fillStyle = x < progressWidth ? options.progressColor : options.color;
+        ctx.fillStyle = x < progressWidth ? progFill : baseFill;
 
         // Draw upper dot
         ctx.beginPath();
@@ -267,7 +428,17 @@ export function drawDots(ctx, canvas, peaks, progress, options) {
 }
 
 /**
- * Draw seekbar style - Simple progress bar without waveform
+ * Draw seekbar style - a simple rounded progress bar with no waveform.
+ * Renders a pill-shaped background track, a glowing pill-shaped filled portion
+ * (clamped to at least one full pill width so it never collapses), and a draggable
+ * circular handle/thumb at the playhead with a drop shadow and inner accent dot.
+ * The `peaks` argument is accepted for signature parity but is unused by this style.
+ * @param {CanvasRenderingContext2D} ctx - Canvas 2D context to draw into.
+ * @param {HTMLCanvasElement} canvas - Canvas element (provides device-pixel dimensions).
+ * @param {number[]} peaks - Ignored; present to match the shared draw-function signature.
+ * @param {number} progress - Playback progress (0-1); the fill and handle are only drawn when > 0.
+ * @param {Object} options - Drawing options: `color` (track), `progressColor` (fill/glow/accent).
+ * @returns {void}
  */
 export function drawSeekbar(ctx, canvas, peaks, progress, options) {
     const width = canvas.width;
@@ -281,14 +452,8 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
     // Draw background track
     ctx.fillStyle = options.color || 'rgba(255, 255, 255, 0.2)';
 
-    // Create rounded rectangle for background
-    ctx.beginPath();
-    ctx.moveTo(borderRadius, centerY - barHeight / 2);
-    ctx.lineTo(width - borderRadius, centerY - barHeight / 2);
-    ctx.arc(width - borderRadius, centerY, barHeight / 2, -Math.PI / 2, Math.PI / 2);
-    ctx.lineTo(borderRadius, centerY + barHeight / 2);
-    ctx.arc(borderRadius, centerY, barHeight / 2, Math.PI / 2, -Math.PI / 2);
-    ctx.closePath();
+    // Rounded background track
+    capsulePath(ctx, borderRadius, width, centerY, barHeight);
     ctx.fill();
 
     // Draw progress
@@ -301,14 +466,8 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
 
         ctx.fillStyle = options.progressColor || 'rgba(255, 255, 255, 0.9)';
 
-        // Create rounded rectangle for progress
-        ctx.beginPath();
-        ctx.moveTo(borderRadius, centerY - barHeight / 2);
-        ctx.lineTo(progressWidth - borderRadius, centerY - barHeight / 2);
-        ctx.arc(progressWidth - borderRadius, centerY, barHeight / 2, -Math.PI / 2, Math.PI / 2);
-        ctx.lineTo(borderRadius, centerY + barHeight / 2);
-        ctx.arc(borderRadius, centerY, barHeight / 2, Math.PI / 2, -Math.PI / 2);
-        ctx.closePath();
+        // Rounded progress fill
+        capsulePath(ctx, borderRadius, progressWidth, centerY, barHeight);
         ctx.fill();
 
         ctx.shadowBlur = 0;
@@ -339,8 +498,10 @@ export function drawSeekbar(ctx, canvas, peaks, progress, options) {
 }
 
 /**
- * Map of style names to drawing functions
- * 6 visually distinct styles including a simple seekbar
+ * Map of style names (and singular aliases) to their drawing functions.
+ * Six visually distinct styles including a simple seekbar; keys are matched
+ * against `options.waveformStyle` by {@link draw}.
+ * @type {Object.<string, function(CanvasRenderingContext2D, HTMLCanvasElement, number[], number, Object): void>}
  */
 export const DRAWING_STYLES = {
     'bars': drawBars,        // Classic vertical bars
@@ -355,12 +516,15 @@ export const DRAWING_STYLES = {
 };
 
 /**
- * Main drawing function that delegates to appropriate style
+ * Main drawing entry point that delegates to the style named by
+ * `options.waveformStyle`, falling back to {@link drawBars} for unknown styles.
  * @param {CanvasRenderingContext2D} ctx - Canvas context
  * @param {HTMLCanvasElement} canvas - Canvas element
- * @param {number[]} peaks - Waveform peak data
+ * @param {number[]} peaks - Waveform peak data (0-1)
  * @param {number} progress - Progress (0-1)
- * @param {Object} options - Drawing options
+ * @param {Object} options - Drawing options, including `waveformStyle` plus the
+ *   per-style fields (`barWidth`, `barSpacing`, `barRadius`, `color`, `progressColor`).
+ * @returns {void}
  */
 export function draw(ctx, canvas, peaks, progress, options) {
     const drawFunc = DRAWING_STYLES[options.waveformStyle] || drawBars;

package/src/js/index.js

@@ -1,15 +1,47 @@
 /**
- * WaveformPlayer
+ * @module index
+ * @description Public entry point for the WaveformPlayer library.
  *
- * Modern audio player with waveform visualization
+ * Wires together the runtime surfaces for the player: it re-exports the
+ * {@link WaveformPlayer} class (default and named), exposes a static
+ * `WaveformPlayer.init` hook, scans the DOM for declarative `[data-waveform-player]`
+ * markup and auto-instantiates a player for each match, and attaches the class
+ * to `window` for plain `<script>`/CDN usage. Loading this module is enough to
+ * make any markup-driven players on the page come alive once the DOM is ready.
  */
 
 // Import the main class
 import {WaveformPlayer} from './core.js';
+import {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref} from './utils.js';
 
-// Auto-initialization for data attributes
+// Expose a small set of pure helpers as a single source of truth so consumers
+// (e.g. @arraypress/waveform-bar) can reuse them instead of shipping divergent
+// copies. Attached to the class so it's reachable from the IIFE global too.
+WaveformPlayer.utils = {formatTime, extractTitleFromUrl, escapeHtml, isSafeHref};
+
+/**
+ * Whether we're running in a browser (vs. SSR / Node), where `window` and
+ * `document` are available. Guards the auto-init and global-attach steps.
+ * @returns {boolean}
+ */
+const isBrowser = () => typeof window !== 'undefined' && typeof document !== 'undefined';
+
+/**
+ * Scan the document for declarative player markup and instantiate one
+ * {@link WaveformPlayer} per matching element.
+ *
+ * Finds every element carrying the `data-waveform-player` attribute and, for
+ * each one not already initialized, constructs a player from it (the constructor
+ * reads the element's `data-*` attributes for configuration). Each successfully
+ * initialized element is flagged with `data-waveform-initialized="true"` so
+ * repeat calls are idempotent and never double-initialize the same element.
+ * Construction errors are caught and logged so one broken element cannot abort
+ * the rest of the scan. A no-op in non-DOM environments (e.g. SSR).
+ *
+ * @returns {void}
+ */
 function autoInit() {
-    if (typeof document === 'undefined') return;
+    if (!isBrowser()) return;
 
     const elements = document.querySelectorAll('[data-waveform-player]');
 
@@ -20,13 +52,14 @@ function autoInit() {
             new WaveformPlayer(element);
             element.dataset.waveformInitialized = 'true';
         } catch (error) {
-            console.error('Failed to initialize WaveformPlayer:', error, element);
+            console.error('[WaveformPlayer] Failed to initialize:', error, element);
         }
     });
 }
 
-// Initialize when DOM is ready
-if (typeof document !== 'undefined') {
+// Initialize when DOM is ready: defer until DOMContentLoaded if the document is
+// still parsing, otherwise run the scan immediately on import.
+if (isBrowser()) {
     if (document.readyState === 'loading') {
         document.addEventListener('DOMContentLoaded', autoInit);
     } else {
@@ -34,15 +67,27 @@ if (typeof document !== 'undefined') {
     }
 }
 
-// Add init method
+/**
+ * Static re-scan hook.
+ *
+ * Exposes {@link autoInit} as `WaveformPlayer.init` so callers can manually
+ * (re-)scan the DOM after dynamically injecting `[data-waveform-player]` markup.
+ * Already-initialized elements are skipped on subsequent calls.
+ *
+ * @type {typeof autoInit}
+ */
 WaveformPlayer.init = autoInit;
 
-// For CDN/browser usage
-if (typeof window !== 'undefined') {
+// For CDN/browser usage: expose the class as a global so it is reachable from a
+// plain <script> tag without an ES module loader.
+if (isBrowser()) {
     window.WaveformPlayer = WaveformPlayer;
 }
 
-// Default export for ES modules
+/**
+ * The {@link WaveformPlayer} class.
+ * @type {typeof WaveformPlayer}
+ */
 export default WaveformPlayer;
 
 // Named exports