@arraypress/waveform-player 1.7.2 → 1.8.1

package/index.d.ts

@@ -0,0 +1,344 @@
+/**
+ * Type definitions for @arraypress/waveform-player
+ * Project: https://github.com/arraypress/waveform-player
+ *
+ * Hand-authored to mirror the runtime option surface and public API. This is
+ * the single source of truth for the library's types — the React and Astro
+ * wrappers re-export from here rather than re-declaring the option list.
+ */
+
+/**
+ * Visual style of the waveform.
+ *
+ * - `bars`    — vertical bars from the baseline up
+ * - `mirror`  — symmetrical bars mirrored around the centre line (default)
+ * - `line`    — connected line graph
+ * - `blocks`  — chunky square blocks
+ * - `dots`    — dotted plot
+ * - `seekbar` — minimal seek bar with no peak detail
+ */
+export type WaveformStyle = 'bars' | 'mirror' | 'line' | 'blocks' | 'dots' | 'seekbar';
+
+/** Forced colour scheme. `null` (default) auto-detects from the page theme and `prefers-color-scheme`. */
+export type ColorPreset = 'dark' | 'light' | null;
+
+/**
+ * How the player handles audio.
+ *
+ * - `self`     — the player owns an `<audio>` element and plays the URL itself (default).
+ * - `external` — visualisation-only; `play()`/`pause()`/seek dispatch
+ *   `waveformplayer:request-*` events for an external controller, which drives
+ *   the visualisation back via {@link WaveformPlayer.setPlayingState} / {@link WaveformPlayer.setProgress}.
+ */
+export type AudioMode = 'self' | 'external';
+
+/** Browser preload hint for the underlying `<audio>` element. */
+export type AudioPreload = 'auto' | 'metadata' | 'none';
+
+/** Vertical alignment of the play button relative to the waveform. */
+export type ButtonAlign = 'auto' | 'top' | 'center' | 'bottom';
+
+/** A clickable chapter marker rendered on top of the waveform. */
+export interface WaveformMarker {
+	/** Time in seconds at which the marker appears. */
+	time: number;
+	/** Short label shown as a tooltip / accessible name. */
+	label: string;
+	/** Optional override colour (any CSS colour string). */
+	color?: string;
+}
+
+/**
+ * Pre-computed waveform peaks, OR a pointer to them.
+ *
+ * - `number[]`            — inline array of peak amplitudes (0..1)
+ * - `string` (.json URL)  — JSON file URL the library will `fetch()`
+ * - `string` (JSON array) — inline JSON string the library will parse
+ * - `null` / omitted      — the library decodes the audio with the Web Audio API at load time
+ */
+export type WaveformPeaks = number[] | string | null;
+
+/** `onTimeUpdate` fires with the same `(currentTime, duration, player)` order in both audio modes. */
+export type WaveformTimeUpdateHandler = (currentTime: number, duration: number, player: WaveformPlayer) => void;
+/** Lifecycle callback receiving the player instance. */
+export type WaveformPlayerHandler = (player: WaveformPlayer) => void;
+/** Error callback receiving the thrown error and the player instance. */
+export type WaveformErrorHandler = (error: unknown, player: WaveformPlayer) => void;
+
+/**
+ * Construction options for {@link WaveformPlayer}. Every field is optional; the
+ * library fills in defaults. The same keys can be supplied as `data-*`
+ * attributes on the host element for the zero-build drop-in.
+ */
+export interface WaveformPlayerOptions {
+	// ── Audio source ──────────────────────────────────────────────
+	/** Audio file URL. */
+	url?: string;
+	/** Shorthand alias for {@link url} (`data-src`). The canonical name wins if both are set. */
+	src?: string;
+	/** Waveform height in pixels. @default 60 */
+	height?: number;
+	/** Number of peak samples to extract when decoding. @default 200 */
+	samples?: number;
+	/** `<audio>` preload hint. @default 'metadata' */
+	preload?: AudioPreload;
+	/** Whether the player owns its `<audio>` or delegates to an external controller. @default 'self' */
+	audioMode?: AudioMode;
+	/** Pre-computed peaks (array, .json URL, or JSON string). Skips Web Audio decoding when provided. */
+	waveform?: WaveformPeaks;
+
+	// ── Waveform visualisation ────────────────────────────────────
+	/** Visual style. @default 'mirror' */
+	waveformStyle?: WaveformStyle;
+	/** Shorthand alias for {@link waveformStyle} (`data-style`). The canonical name wins if both are set. */
+	style?: WaveformStyle;
+	/** Bar width in pixels (style-dependent default). */
+	barWidth?: number;
+	/** Gap between bars in pixels (style-dependent default). */
+	barSpacing?: number;
+	/** Rounded bar-cap radius in pixels (bars/mirror). `0` = square. @default 0 */
+	barRadius?: number;
+
+	// ── Colours ───────────────────────────────────────────────────
+	/** Force a colour preset, or `null` to auto-detect. @default null */
+	colorPreset?: ColorPreset;
+	/**
+	 * Unplayed waveform colour (each `null` = use the preset). Pass an array of
+	 * CSS colour stops for a vertical gradient, e.g. `['#fafafa', '#71717a']`.
+	 */
+	waveformColor?: string | string[] | null;
+	/** Played-through colour. Also accepts an array of stops for a gradient. */
+	progressColor?: string | string[] | null;
+	buttonColor?: string | null;
+	buttonHoverColor?: string | null;
+	textColor?: string | null;
+	textSecondaryColor?: string | null;
+	backgroundColor?: string | null;
+	borderColor?: string | null;
+
+	// ── Playback ──────────────────────────────────────────────────
+	/** Initial playback rate. @default 1 */
+	playbackRate?: number;
+	/** Show the playback-speed control. @default false */
+	showPlaybackSpeed?: boolean;
+	/** Selectable playback rates. @default [0.5, 0.75, 1, 1.25, 1.5, 1.75, 2] */
+	playbackRates?: number[];
+
+	// ── Layout / UI toggles ───────────────────────────────────────
+	/** Play-button alignment. @default 'auto' */
+	buttonAlign?: ButtonAlign;
+	/** Show transport controls. @default true */
+	showControls?: boolean;
+	/** Show the info (title/subtitle) block. @default true */
+	showInfo?: boolean;
+	/** Show current/total time. @default true */
+	showTime?: boolean;
+	/** Show a time tooltip on hover. @default false */
+	showHoverTime?: boolean;
+	/** Show detected BPM. @default false */
+	showBPM?: boolean;
+
+	// ── Behaviour ─────────────────────────────────────────────────
+	/** Begin playback on load. @default false */
+	autoplay?: boolean;
+	/** Pause every other player instance when this one plays. @default true */
+	singlePlay?: boolean;
+	/** Start playing when the user seeks. @default true */
+	playOnSeek?: boolean;
+	/** Register system Media Session controls (self mode only). @default true */
+	enableMediaSession?: boolean;
+
+	// ── Markers ───────────────────────────────────────────────────
+	/** Chapter markers. @default [] */
+	markers?: WaveformMarker[];
+	/** Render markers. @default true */
+	showMarkers?: boolean;
+
+	// ── Accessibility ─────────────────────────────────────────────
+	/** Expose the waveform as a keyboard-operable ARIA slider. @default true */
+	accessibleSeek?: boolean;
+	/** Accessible name for the seek slider (falls back to the title, then `'Seek'`). @default null */
+	seekLabel?: string | null;
+
+	// ── Content metadata ──────────────────────────────────────────
+	title?: string | null;
+	subtitle?: string | null;
+	artwork?: string | null;
+	album?: string;
+	/** Message shown when audio fails to load. @default 'Unable to load audio' */
+	errorText?: string;
+
+	// ── Icons (raw SVG markup) ────────────────────────────────────
+	playIcon?: string;
+	pauseIcon?: string;
+
+	// ── Callbacks ─────────────────────────────────────────────────
+	onLoad?: WaveformPlayerHandler | null;
+	onPlay?: WaveformPlayerHandler | null;
+	onPause?: WaveformPlayerHandler | null;
+	onEnd?: WaveformPlayerHandler | null;
+	onError?: WaveformErrorHandler | null;
+	onTimeUpdate?: WaveformTimeUpdateHandler | null;
+}
+
+/** `detail` of `waveformplayer:play | pause | ready | destroy`. */
+export interface WaveformLifecycleEventDetail {
+	player: WaveformPlayer;
+	url: string;
+}
+
+/** `detail` of `waveformplayer:ended` — lifecycle plus the final time. */
+export interface WaveformEndedEventDetail extends WaveformLifecycleEventDetail {
+	currentTime: number;
+	duration: number;
+}
+
+/** `detail` of `waveformplayer:timeupdate`. */
+export interface WaveformTimeUpdateEventDetail {
+	player: WaveformPlayer;
+	currentTime: number;
+	duration: number;
+	/** Progress as a 0..1 fraction. */
+	progress: number;
+	url: string;
+}
+
+/** Track metadata carried by the external-mode `request-*` events. */
+export interface WaveformTrackDetail {
+	url: string;
+	title: string | null;
+	subtitle: string | null;
+	artist?: string;
+	artwork: string | null;
+	/** Chapter markers for the track (forwarded so controllers don't re-fetch). */
+	markers?: WaveformMarker[];
+	/** Pre-computed peaks for the track, if any. */
+	waveform?: WaveformPeaks;
+	id: string;
+	player: WaveformPlayer;
+}
+
+/** `detail` of `waveformplayer:request-play | request-pause`. */
+export type WaveformRequestEventDetail = WaveformTrackDetail;
+
+/** `detail` of `waveformplayer:request-seek` — adds the requested position. */
+export interface WaveformRequestSeekEventDetail extends WaveformTrackDetail {
+	/** Requested position as a 0..1 fraction of total duration. */
+	percent: number;
+}
+
+/** Map of every custom event the player dispatches on its container (bubbling). */
+export interface WaveformPlayerEventMap {
+	'waveformplayer:ready': CustomEvent<WaveformLifecycleEventDetail>;
+	'waveformplayer:play': CustomEvent<WaveformLifecycleEventDetail>;
+	'waveformplayer:pause': CustomEvent<WaveformLifecycleEventDetail>;
+	'waveformplayer:destroy': CustomEvent<WaveformLifecycleEventDetail>;
+	'waveformplayer:ended': CustomEvent<WaveformEndedEventDetail>;
+	'waveformplayer:timeupdate': CustomEvent<WaveformTimeUpdateEventDetail>;
+	'waveformplayer:request-play': CustomEvent<WaveformRequestEventDetail>;
+	'waveformplayer:request-pause': CustomEvent<WaveformRequestEventDetail>;
+	'waveformplayer:request-seek': CustomEvent<WaveformRequestSeekEventDetail>;
+}
+
+/**
+ * Modern audio player with waveform visualisation.
+ *
+ * @example
+ * ```ts
+ * import WaveformPlayer from '@arraypress/waveform-player';
+ * const player = new WaveformPlayer('#player', { url: '/track.mp3' });
+ * ```
+ */
+export declare class WaveformPlayer {
+	/**
+	 * @param container Host element, or a CSS selector / element id resolving to one.
+	 * @param options   Player options (also readable from `data-*` attributes on the element).
+	 */
+	constructor(container: string | HTMLElement, options?: WaveformPlayerOptions);
+
+	/** Resolved options after merging defaults, data-attributes, and constructor options. */
+	readonly options: Required<WaveformPlayerOptions>;
+	/** Unique instance id (the host element id, or a generated one). */
+	readonly id: string;
+	/** Host element. */
+	readonly container: HTMLElement;
+	/** Current progress as a 0..1 fraction. */
+	progress: number;
+	/** Whether playback is active. */
+	isPlaying: boolean;
+
+	/**
+	 * Start playback. In `self` mode returns the native `HTMLMediaElement.play()`
+	 * promise; in `external` mode dispatches `waveformplayer:request-play` and returns `undefined`.
+	 */
+	play(): Promise<void> | undefined;
+	/** Pause playback (or dispatch `request-pause` in external mode). */
+	pause(): void;
+	/** Toggle play / pause. */
+	togglePlay(): void;
+	/** Load (or replace) the audio URL and regenerate the waveform. */
+	load(url: string): Promise<void>;
+	/** Load a new track without re-instantiating; updates metadata then plays. */
+	loadTrack(url: string, title?: string | null, subtitle?: string | null, options?: WaveformPlayerOptions): Promise<void>;
+	/** Seek to an absolute time in seconds (self mode). */
+	seekTo(seconds: number): void;
+	/** Seek to a fraction of total duration, 0..1 (self mode). */
+	seekToPercent(percent: number): void;
+	/** Set output volume, 0..1 (self mode). */
+	setVolume(volume: number): void;
+	/** Set the playback rate (self mode). */
+	setPlaybackRate(rate: number): void;
+	/** Provide pre-computed peaks directly. */
+	setWaveformData(data: WaveformPeaks): void;
+	/** Highlight the marker at `index` (clears the rest); pass `null` to clear all. */
+	setActiveMarker(index: number | null): void;
+	/** External mode: push play/pause state so the visualisation reflects your audio source. */
+	setPlayingState(playing: boolean): void;
+	/** External mode: push the current position so the progress overlay advances. */
+	setProgress(currentTime: number, duration: number): void;
+	/** Tear down the player: stops audio, removes all listeners, clears the container. */
+	destroy(): void;
+
+	/** Map of live instances keyed by id. */
+	static readonly instances: Map<string, WaveformPlayer>;
+	/** The instance currently playing, if any. */
+	static currentlyPlaying: WaveformPlayer | null;
+	/** Look up an instance by id, element, or element id. */
+	static getInstance(idOrElement: string | HTMLElement): WaveformPlayer | undefined;
+	/** All live instances. */
+	static getAllInstances(): WaveformPlayer[];
+	/** Destroy every live instance. */
+	static destroyAll(): void;
+	/** Decode an audio URL to peak data without constructing a player. */
+	static generateWaveformData(url: string, samples?: number): Promise<{ peaks: number[]; bpm: number | null }>;
+	/** Convention helper: derive the sibling `.json` peaks URL for an audio URL. */
+	static getPeaksUrl(audioUrl: string): string;
+	/** Scan the document for `[data-waveform-player]` elements and initialise them. */
+	static init(): void;
+	/**
+	 * Pure helper functions exposed as a single source of truth so consumers
+	 * (e.g. `@arraypress/waveform-bar`) can reuse them instead of shipping
+	 * divergent copies.
+	 */
+	static readonly utils: {
+		/** Format seconds as `M:SS` (or `H:MM:SS` past an hour). */
+		formatTime(seconds: number): string;
+		/** Derive a display title from a URL's filename. */
+		extractTitleFromUrl(url: string): string;
+		/** Escape a value for safe interpolation into HTML. */
+		escapeHtml(str: unknown): string;
+		/** Whether a URL uses a safe (`http`/`https`/relative) scheme. */
+		isSafeHref(url: string): boolean;
+	};
+}
+
+export default WaveformPlayer;
+
+declare global {
+	interface Window {
+		/** Global constructor exposed by the IIFE/UMD build for `<script>` usage. */
+		WaveformPlayer: typeof WaveformPlayer;
+	}
+
+	interface HTMLElementEventMap extends WaveformPlayerEventMap {}
+}

package/package.json

@@ -1,37 +1,45 @@
 {
   "name": "@arraypress/waveform-player",
-  "version": "1.7.2",
+  "version": "1.8.1",
   "description": "Lightweight, customizable audio player with waveform visualization",
   "type": "module",
-  "main": "dist/waveform-player.esm.js",
+  "types": "./index.d.ts",
+  "main": "dist/waveform-player.cjs",
   "module": "dist/waveform-player.esm.js",
   "unpkg": "dist/waveform-player.min.js",
   "exports": {
     ".": {
+      "types": "./index.d.ts",
       "import": "./dist/waveform-player.esm.js",
+      "require": "./dist/waveform-player.cjs",
       "default": "./dist/waveform-player.esm.js"
     },
+    "./styles.css": "./dist/waveform-player.css",
     "./dist/*": "./dist/*",
     "./package.json": "./package.json"
   },
   "files": [
     "dist/",
     "src/",
+    "index.d.ts",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
-    "build": "npm run build:css && npm run build:iife && npm run build:esm && npm run build:min",
+    "build": "npm run build:css && npm run build:iife && npm run build:esm && npm run build:cjs && npm run build:min",
     "build:css": "esbuild src/css/waveform-player.css --minify --outfile=dist/waveform-player.css",
     "build:iife": "esbuild src/js/index.js --bundle --format=iife --outfile=dist/waveform-player.js",
-    "build:min": "esbuild src/js/index.js --bundle --format=iife --outfile=dist/waveform-player.min.js --minify",
-    "build:esm": "esbuild src/js/index.js --bundle --format=esm --outfile=dist/waveform-player.esm.js --minify",
+    "build:min": "esbuild src/js/index.js --bundle --format=iife --outfile=dist/waveform-player.min.js --minify --sourcemap=external",
+    "build:esm": "esbuild src/js/index.js --bundle --format=esm --outfile=dist/waveform-player.esm.js --minify --sourcemap=external",
+    "build:cjs": "esbuild src/js/index.js --bundle --format=cjs --outfile=dist/waveform-player.cjs --sourcemap=external",
     "dev": "npm run build:css && esbuild src/js/index.js --bundle --format=iife --outfile=dist/waveform-player.js --watch",
     "dev:css": "esbuild src/css/waveform-player.css --outfile=dist/waveform-player.css --watch",
     "dev:demo": "npm run build:css && concurrently \"npm run dev\" \"npm run dev:css\"",
     "size": "npm run build:min && npm run build:css && echo 'JS:' && gzip -c dist/waveform-player.min.js | wc -c && echo 'CSS:' && gzip -c dist/waveform-player.css | wc -c",
     "serve": "npx http-server -p 8000",
-    "prepublishOnly": "npm run build"
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run test && npm run build"
   },
   "keywords": [
     "audio",
@@ -75,7 +83,9 @@
     "*.css"
   ],
   "devDependencies": {
-    "concurrently": "^7.6.0",
-    "esbuild": "^0.25.0"
+    "concurrently": "^10.0.3",
+    "esbuild": "^0.28.1",
+    "jsdom": "^29.1.1",
+    "vitest": "^4.1.9"
   }
 }

package/src/css/waveform-player.css

@@ -2,7 +2,7 @@
 .waveform-player {
     font-family: inherit;
     color: inherit;
-    line-height: 1.4;
+    line-height: var(--waveform-line-height, 1.4);
 }
 
 .waveform-player * {
@@ -13,14 +13,14 @@
 .waveform-body {
     display: flex;
     flex-direction: column;
-    gap: 8px;
+    gap: var(--waveform-body-gap, 8px);
 }
 
 /* Track row */
 .waveform-track {
     display: flex;
     align-items: center;
-    gap: 12px;
+    gap: var(--waveform-track-gap, 12px);
     position: relative;
 }
 
@@ -201,6 +201,13 @@
     z-index: 20;
 }
 
+/* Active marker — set via player.setActiveMarker(index). */
+.waveform-marker.active {
+    width: 4px;
+    background: currentColor;
+    z-index: 10;
+}
+
 /* Marker tooltip */
 .waveform-marker-tooltip {
     position: absolute;
@@ -364,4 +371,15 @@
     .waveform-bpm {
         font-size: 10px;
     }
+}
+
+/* Respect users who prefer reduced motion — neutralize transitions/animations. */
+@media (prefers-reduced-motion: reduce) {
+    .waveform-player *,
+    .waveform-player *::before,
+    .waveform-player *::after {
+        transition-duration: 0.01ms !important;
+        animation-duration: 0.01ms !important;
+        animation-iteration-count: 1 !important;
+    }
 }

package/src/js/audio.js

@@ -4,12 +4,21 @@
  */
 
 import {detectBPM} from './bpm.js';
+import {clamp} from './utils.js';
 
 /**
- * Extract peaks from audio buffer for waveform visualization
- * @param {AudioBuffer} buffer - Audio buffer
- * @param {number} samples - Number of samples to extract
- * @returns {number[]} Array of peak values (0-1)
+ * Extract peaks from a decoded audio buffer for waveform visualization.
+ *
+ * Divides the buffer into `samples` equal-width windows and, within each
+ * window, finds the largest absolute amplitude. To keep large files fast the
+ * inner loop strides through every 10th frame (`sampleStep`) rather than
+ * inspecting every frame. Across multiple channels the per-window peaks are
+ * merged by taking the loudest channel, then the whole array is normalized so
+ * the maximum peak becomes 1 (a silent buffer is returned unscaled).
+ *
+ * @param {AudioBuffer} buffer - Decoded audio buffer to analyse.
+ * @param {number} [samples=200] - Number of peak windows (output array length).
+ * @returns {number[]} Array of `samples` normalized peak values in the 0-1 range.
  */
 export function extractPeaks(buffer, samples = 200) {
     const sampleSize = buffer.length / samples;
@@ -47,15 +56,30 @@ export function extractPeaks(buffer, samples = 200) {
 }
 
 /**
- * Generate waveform data from audio URL
- * @param {string} url - Audio URL
- * @param {number} samples - Number of samples
- * @param {boolean} [shouldDetectBPM=false] - Whether to detect BPM
- * @returns {Promise<{peaks: number[], bpm?: number}>} Waveform data
+ * Generate waveform data by fetching and decoding an audio file at a URL.
+ *
+ * Fetches the URL, decodes it through a short-lived AudioContext, runs
+ * {@link extractPeaks} followed by {@link normalizePeaks}, and optionally
+ * detects the track's BPM. The AudioContext is created lazily and always
+ * closed in the `finally` block so failed decodes never leak one (browsers
+ * hard-cap the number of live contexts). Errors are logged and re-thrown so
+ * callers can fall back to a placeholder waveform.
+ *
+ * @param {string} url - Audio file URL to fetch and decode.
+ * @param {number} [samples=200] - Number of peak windows to extract.
+ * @param {boolean} [shouldDetectBPM=false] - Whether to run BPM detection on the decoded buffer.
+ * @returns {Promise<{peaks: number[], bpm: (number|null)}>} Resolves with the
+ *   normalized peaks and the detected BPM (`null` when detection is disabled or fails).
+ * @throws {Error} Re-throws any fetch/decode error after logging it.
  */
-export async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {  // Renamed parameter
+export async function generateWaveform(url, samples = 200, shouldDetectBPM = false) {
+    // Created lazily so the finally block can always close it — browsers
+    // hard-cap live AudioContexts (~6 in Chrome), so leaking one per failed
+    // decode would break every subsequent player on the page.
+    let audioContext;
     try {
-        const audioContext = new (window.AudioContext || window.webkitAudioContext)();
+        const AudioCtx = window.AudioContext || /** @type {any} */ (window).webkitAudioContext;
+        audioContext = new AudioCtx();
         const response = await fetch(url);
         const arrayBuffer = await response.arrayBuffer();
         const audioBuffer = await audioContext.decodeAudioData(arrayBuffer);
@@ -66,38 +90,50 @@ export async function generateWaveform(url, samples = 200, shouldDetectBPM = fal
         peaks = normalizePeaks(peaks);
 
         let bpm = null;
-        if (shouldDetectBPM) {  // Use renamed parameter
-            bpm = await detectBPM(audioBuffer);  // Now this correctly calls the imported function
+        if (shouldDetectBPM) {
+            bpm = detectBPM(audioBuffer); // synchronous — returns number|null
         }
 
-        audioContext.close();
         return {peaks, bpm};
-    } catch (error) {
-        console.error('Failed to generate waveform:', error);
-        throw error;
+    } finally {
+        // Error (if any) propagates to the caller, which decides how to log /
+        // recover; the context is always closed either way.
+        if (audioContext) audioContext.close();
     }
 }
 
 /**
- * Generate placeholder waveform data
- * @param {number} samples - Number of samples
- * @returns {number[]} Random waveform data
+ * Generate a synthetic placeholder waveform for use before (or instead of)
+ * real peak data is available.
+ *
+ * Each bar combines a random base height (0.3-0.8) with a slow sinusoidal
+ * variation across the array, clamped to the 0.1-1 range so the result always
+ * looks like a plausible waveform rather than pure noise.
+ *
+ * @param {number} [samples=200] - Number of bars (output array length).
+ * @returns {number[]} Array of `samples` pseudo-random peak values in the 0.1-1 range.
  */
 export function generatePlaceholderWaveform(samples = 200) {
     const data = [];
     for (let i = 0; i < samples; i++) {
         const base = Math.random() * 0.5 + 0.3;
         const variation = Math.sin(i / samples * Math.PI * 4) * 0.2;
-        data.push(Math.max(0.1, Math.min(1, base + variation)));
+        data.push(clamp(base + variation, 0.1, 1));
     }
     return data;
 }
 
 /**
- * Normalize waveform peaks to ensure consistent visualization
- * @param {number[]} peaks - Array of peak values (0-1 range)
- * @param {number} [targetMax=0.95] - Target maximum peak value
- * @returns {number[]} Normalized peak array
+ * Scale peak values so quiet tracks fill the available height consistently.
+ *
+ * Finds the loudest peak and, only when it is non-zero yet below `targetMax`,
+ * scales every peak proportionally so the maximum lands on `targetMax`. Silent
+ * arrays (max 0) and already-loud arrays (max above `targetMax`) are returned
+ * untouched, so the function never amplifies clipping or divides by zero.
+ *
+ * @param {number[]} peaks - Peak values, typically in the 0-1 range.
+ * @param {number} [targetMax=0.95] - Desired maximum peak after scaling.
+ * @returns {number[]} The normalized peak array (the original array when no scaling is applied).
  * @private
  */
 function normalizePeaks(peaks, targetMax = 0.95) {

package/src/js/bpm.js

@@ -4,9 +4,18 @@
  */
 
 /**
- * Detect BPM from audio buffer
- * @param {AudioBuffer} buffer - Audio buffer to analyze
- * @returns {number|null} Detected BPM or null
+ * Estimate the tempo (beats per minute) of an audio buffer.
+ *
+ * Analyses the first (left/mono) channel by detecting onsets, measuring the
+ * time between successive onsets, converting each interval to a tempo, and
+ * histogramming those tempos into 3-BPM buckets (60-200 BPM) to find the most
+ * common one. Octave errors are corrected by doubling very slow results and
+ * halving very fast ones when a strong half/double bucket also exists, then a
+ * fixed -1 BPM calibration offset is applied. Returns a 120 BPM fallback when
+ * too few onsets are found, and null if analysis throws.
+ *
+ * @param {AudioBuffer} buffer - Decoded audio buffer to analyse; only channel 0 is read.
+ * @returns {number|null} Detected tempo in BPM, 120 as a fallback when onsets are insufficient, or null on error.
  */
 export function detectBPM(buffer) {
     try {
@@ -51,13 +60,25 @@ export function detectBPM(buffer) {
 
         return detectedBPM - 1; // Calibration offset
     } catch (e) {
-        console.warn('BPM detection failed:', e);
+        console.warn('[WaveformPlayer] BPM detection failed:', e);
         return null;
     }
 }
 
 /**
- * Detect onsets (transients/beats) in audio
+ * Detect onset sample positions (transients/beats) within a channel of audio.
+ *
+ * Slides a 2048-sample window (50% overlap via a half-window hop) across the
+ * signal, computing the mean squared energy of each window. An onset is flagged
+ * when the energy rise over the previous (smoothed) energy exceeds an adaptive
+ * threshold and the window energy is above a noise floor, subject to a minimum
+ * spacing of 150 ms so a single transient is not counted twice. The running
+ * previousEnergy is exponentially smoothed (0.8 new / 0.2 old) to track the
+ * local energy envelope.
+ *
+ * @param {Float32Array} channelData - PCM samples (normalised -1..1) for a single channel.
+ * @param {number} sampleRate - Sample rate in Hz, used to derive the minimum onset spacing.
+ * @returns {number[]} Ascending sample indices at which onsets were detected.
  * @private
  */
 function detectOnsets(channelData, sampleRate) {