wavesurfer.js 7.11.1 → 7.12.1

package/README.md

@@ -112,7 +112,7 @@ However, please keep in mind that this forum is dedicated to wavesurfer-specific
 
 <details>
   <summary>Does wavesurfer support large files?</summary>
-  Since wavesurfer decodes audio entirely in the browser using Web Audio, large clips may fail to decode due to memory constraints. We recommend using pre-decoded peaks for large files (see <a href="https://wavesurfer.xyz/examples/?predecoded.js">this example</a>). You can use a tool like <a href="https://github.com/bbc/audiowaveform">bbc/audiowaveform</a> to generate peaks.
+  Since wavesurfer decodes audio entirely in the browser using Web Audio, large clips may fail to decode due to memory constraints. We recommend using pre-decoded peaks for large files (see <a href="https://wavesurfer.xyz/examples/?predecoded.js">this example</a>). You can use a tool like <a href="https://codeberg.org/chrisn/audiowaveform">audiowaveform</a> to generate peaks.
 </details>
 
 <details>

package/dist/__tests__/memory-leaks.test.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Memory Leak Detection Tests
+ *
+ * These tests verify that WaveSurfer properly cleans up resources
+ * and doesn't leak memory when destroyed and recreated multiple times.
+ */
+export {};

package/dist/__tests__/memory-leaks.test.js

@@ -0,0 +1,281 @@
+/**
+ * Memory Leak Detection Tests
+ *
+ * These tests verify that WaveSurfer properly cleans up resources
+ * and doesn't leak memory when destroyed and recreated multiple times.
+ */
+import WaveSurfer from '../wavesurfer.js';
+import RegionsPlugin from '../plugins/regions.js';
+// Mock audio context and matchMedia
+beforeAll(() => {
+    global.AudioContext = jest.fn().mockImplementation(() => ({
+        createMediaElementSource: jest.fn(() => ({
+            connect: jest.fn(),
+            disconnect: jest.fn(),
+        })),
+        createGain: jest.fn(() => ({
+            connect: jest.fn(),
+            disconnect: jest.fn(),
+            gain: { value: 1, setValueAtTime: jest.fn() },
+        })),
+        destination: {},
+        close: jest.fn(),
+    }));
+    // Mock matchMedia for drag-stream
+    Object.defineProperty(window, 'matchMedia', {
+        writable: true,
+        value: jest.fn().mockImplementation((query) => ({
+            matches: false,
+            media: query,
+            onchange: null,
+            addListener: jest.fn(),
+            removeListener: jest.fn(),
+            addEventListener: jest.fn(),
+            removeEventListener: jest.fn(),
+            dispatchEvent: jest.fn(),
+        })),
+    });
+});
+describe('Memory Leak Detection', () => {
+    let container;
+    beforeEach(() => {
+        container = document.createElement('div');
+        container.id = 'waveform';
+        document.body.appendChild(container);
+    });
+    afterEach(() => {
+        document.body.removeChild(container);
+    });
+    describe('WaveSurfer lifecycle', () => {
+        it('should cleanup subscriptions on destroy', () => {
+            const ws = WaveSurfer.create({ container });
+            // Track if cleanup functions are called
+            const cleanupSpy = jest.fn();
+            // Access internal state to verify cleanup
+            const originalDestroy = ws.destroy.bind(ws);
+            ws.destroy = () => {
+                cleanupSpy();
+                originalDestroy();
+            };
+            ws.destroy();
+            expect(cleanupSpy).toHaveBeenCalled();
+        });
+        it('should not leak memory after multiple create/destroy cycles', () => {
+            const instances = [];
+            // Create and destroy multiple instances
+            for (let i = 0; i < 10; i++) {
+                const ws = WaveSurfer.create({ container });
+                instances.push(ws);
+                ws.destroy();
+            }
+            // All instances should be destroyed
+            instances.forEach((ws) => {
+                // After destroy, the instance should not have active listeners
+                expect(ws).toBeDefined();
+            });
+        });
+        it('should remove all event listeners on destroy', () => {
+            const ws = WaveSurfer.create({ container });
+            const clickHandler = jest.fn();
+            const timeUpdateHandler = jest.fn();
+            ws.on('click', clickHandler);
+            ws.on('timeupdate', timeUpdateHandler);
+            ws.destroy();
+            // After destroy, handlers should be removed
+            // We can't test emit directly as it's protected, but we verified
+            // the cleanup happened via destroy()
+            expect(clickHandler).not.toHaveBeenCalled();
+            expect(timeUpdateHandler).not.toHaveBeenCalled();
+        });
+        it('should cleanup DOM elements on destroy', () => {
+            const ws = WaveSurfer.create({ container });
+            const childCountBefore = container.children.length;
+            expect(childCountBefore).toBeGreaterThan(0);
+            ws.destroy();
+            const childCountAfter = container.children.length;
+            expect(childCountAfter).toBe(0);
+        });
+        it('should cleanup reactive subscriptions on destroy', () => {
+            const ws = WaveSurfer.create({ container });
+            // Get state to check reactive cleanup
+            const state = ws.getState();
+            // State should have reactive signals
+            expect(state).toBeDefined();
+            expect(state.isPlaying).toBeDefined();
+            expect(state.currentTime).toBeDefined();
+            ws.destroy();
+            // After destroy, reactive subscriptions should be cleaned up
+            expect(state).toBeDefined();
+        });
+    });
+    describe('Plugin lifecycle', () => {
+        it('should track registered plugins', () => {
+            const ws = WaveSurfer.create({ container });
+            // WaveSurfer should start with no plugins
+            expect(ws).toBeDefined();
+            ws.destroy();
+        });
+        it('should remove plugin elements from DOM on destroy', () => {
+            WaveSurfer.create({ container });
+            // Mock a plugin that adds DOM elements
+            const pluginElement = document.createElement('div');
+            pluginElement.className = 'test-plugin';
+            container.appendChild(pluginElement);
+            const elementCountBefore = container.querySelectorAll('.test-plugin').length;
+            expect(elementCountBefore).toBe(1);
+            // Plugin should cleanup its elements
+            pluginElement.remove();
+            const elementCountAfter = container.querySelectorAll('.test-plugin').length;
+            expect(elementCountAfter).toBe(0);
+        });
+    });
+    describe('Regions plugin memory leak (#4243)', () => {
+        it('should cleanup region event listeners when removed', () => {
+            const ws = WaveSurfer.create({ container });
+            const regions = ws.registerPlugin(RegionsPlugin.create());
+            // Mock duration so regions are saved immediately
+            jest.spyOn(ws, 'getDuration').mockReturnValue(10);
+            jest.spyOn(ws, 'getDecodedData').mockReturnValue({ numberOfChannels: 1 });
+            // Create a region
+            const region = regions.addRegion({ start: 0, end: 1 });
+            // Track if cleanup is happening
+            const clickHandler = jest.fn();
+            region.on('click', clickHandler);
+            // Remove the region
+            region.remove();
+            // After removal, the region element should be null
+            expect(region.element).toBeNull();
+            // Cleanup
+            ws.destroy();
+        });
+        it('should not retain regions in memory after removal', () => {
+            const ws = WaveSurfer.create({ container });
+            const regions = ws.registerPlugin(RegionsPlugin.create());
+            // Mock duration so regions are saved immediately
+            jest.spyOn(ws, 'getDuration').mockReturnValue(10);
+            jest.spyOn(ws, 'getDecodedData').mockReturnValue({ numberOfChannels: 1 });
+            // Create multiple regions
+            const region1 = regions.addRegion({ start: 0, end: 1 });
+            const region2 = regions.addRegion({ start: 2, end: 3 });
+            const region3 = regions.addRegion({ start: 4, end: 5 });
+            expect(regions.getRegions().length).toBe(3);
+            // Remove regions
+            region1.remove();
+            region2.remove();
+            // Only one region should remain
+            expect(regions.getRegions().length).toBe(1);
+            expect(regions.getRegions()[0]).toBe(region3);
+            // Remove last region
+            region3.remove();
+            expect(regions.getRegions().length).toBe(0);
+            // Cleanup
+            ws.destroy();
+        });
+        it('should cleanup content event listeners when region is removed', () => {
+            const ws = WaveSurfer.create({ container });
+            const regions = ws.registerPlugin(RegionsPlugin.create());
+            // Mock duration so regions are saved immediately
+            jest.spyOn(ws, 'getDuration').mockReturnValue(10);
+            jest.spyOn(ws, 'getDecodedData').mockReturnValue({ numberOfChannels: 1 });
+            // Create a region with editable content
+            const region = regions.addRegion({
+                start: 0,
+                end: 1,
+                content: 'Test content',
+                contentEditable: true,
+            });
+            // Remove the region
+            region.remove();
+            // Content should be cleaned up
+            expect(region.element).toBeNull();
+            // Cleanup
+            ws.destroy();
+        });
+        it('should cleanup DOM event streams on region removal', () => {
+            const ws = WaveSurfer.create({ container });
+            const regions = ws.registerPlugin(RegionsPlugin.create());
+            // Mock duration so regions are saved immediately
+            jest.spyOn(ws, 'getDuration').mockReturnValue(10);
+            jest.spyOn(ws, 'getDecodedData').mockReturnValue({ numberOfChannels: 1 });
+            // Create regions
+            const createdRegions = [];
+            for (let i = 0; i < 10; i++) {
+                createdRegions.push(regions.addRegion({ start: i, end: i + 1 }));
+            }
+            expect(regions.getRegions().length).toBe(10);
+            // Remove all regions
+            createdRegions.forEach((r) => r.remove());
+            // All regions should be removed
+            expect(regions.getRegions().length).toBe(0);
+            // Cleanup
+            ws.destroy();
+        });
+    });
+    describe('Event listener cleanup', () => {
+        it('should properly cleanup on destroy', () => {
+            const ws = WaveSurfer.create({ container });
+            // Get renderer to ensure it's initialized
+            const renderer = ws.getRenderer();
+            expect(renderer).toBeDefined();
+            // Should not throw during destroy
+            expect(() => {
+                ws.destroy();
+            }).not.toThrow();
+        });
+    });
+    describe('Reactive system cleanup', () => {
+        it('should have reactive state available', () => {
+            const ws = WaveSurfer.create({ container });
+            const state = ws.getState();
+            // State should expose reactive signals
+            expect(state.isPlaying).toBeDefined();
+            expect(state.currentTime).toBeDefined();
+            expect(state.duration).toBeDefined();
+            expect(state.volume).toBeDefined();
+            expect(state.progressPercent).toBeDefined();
+            // Cleanup
+            ws.destroy();
+        });
+        it('should not accumulate subscriptions across instances', () => {
+            const instances = [];
+            // Create multiple instances
+            for (let i = 0; i < 5; i++) {
+                const ws = WaveSurfer.create({ container });
+                instances.push(ws);
+            }
+            // Each instance should be independent
+            expect(instances.length).toBe(5);
+            // Destroy all instances
+            instances.forEach((ws) => ws.destroy());
+            // All instances should be cleaned up
+            expect(instances.every((ws) => ws !== null)).toBe(true);
+        });
+    });
+    describe('Edge cases', () => {
+        it('should handle destroy called multiple times', () => {
+            const ws = WaveSurfer.create({ container });
+            // Should not throw when destroyed multiple times
+            expect(() => {
+                ws.destroy();
+                ws.destroy();
+                ws.destroy();
+            }).not.toThrow();
+        });
+        it('should handle destroy without initialization', () => {
+            const ws = WaveSurfer.create({ container });
+            // Destroy immediately without loading audio
+            expect(() => {
+                ws.destroy();
+            }).not.toThrow();
+        });
+        it('should cleanup even if events are subscribed during destroy', () => {
+            const ws = WaveSurfer.create({ container });
+            // Subscribe to destroy event
+            const destroyHandler = jest.fn();
+            ws.on('destroy', destroyHandler);
+            ws.destroy();
+            // Destroy handler should have been called
+            expect(destroyHandler).toHaveBeenCalled();
+        });
+    });
+});

package/dist/__tests__/player.test.js

@@ -60,4 +60,111 @@ describe('Player', () => {
         yield player.setSinkId('id');
         expect(media.setSinkId).toHaveBeenCalledWith('id');
     }));
+    describe('reactive signals', () => {
+        test('exposes isPlayingSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.isPlayingSignal).toBeDefined();
+            expect(player.isPlayingSignal.value).toBe(false);
+        });
+        test('exposes currentTimeSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.currentTimeSignal).toBeDefined();
+            expect(player.currentTimeSignal.value).toBe(0);
+        });
+        test('exposes durationSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.durationSignal).toBeDefined();
+            expect(typeof player.durationSignal.value).toBe('number');
+        });
+        test('exposes volumeSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.volumeSignal).toBeDefined();
+            expect(typeof player.volumeSignal.value).toBe('number');
+        });
+        test('exposes mutedSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.mutedSignal).toBeDefined();
+            expect(typeof player.mutedSignal.value).toBe('boolean');
+        });
+        test('exposes playbackRateSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.playbackRateSignal).toBeDefined();
+            expect(typeof player.playbackRateSignal.value).toBe('number');
+        });
+        test('exposes seekingSignal', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.seekingSignal).toBeDefined();
+            expect(player.seekingSignal.value).toBe(false);
+        });
+        test('isPlayingSignal updates on play event', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.isPlayingSignal.value).toBe(false);
+            media.dispatchEvent(new Event('play'));
+            expect(player.isPlayingSignal.value).toBe(true);
+        });
+        test('isPlayingSignal updates on pause event', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            media.dispatchEvent(new Event('play'));
+            expect(player.isPlayingSignal.value).toBe(true);
+            media.dispatchEvent(new Event('pause'));
+            expect(player.isPlayingSignal.value).toBe(false);
+        });
+        test('isPlayingSignal updates on ended event', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            media.dispatchEvent(new Event('play'));
+            expect(player.isPlayingSignal.value).toBe(true);
+            media.dispatchEvent(new Event('ended'));
+            expect(player.isPlayingSignal.value).toBe(false);
+        });
+        test('currentTimeSignal updates on timeupdate event', () => {
+            const media = createMedia();
+            Object.defineProperty(media, 'currentTime', { configurable: true, value: 5.5, writable: true });
+            const player = new Player({ media });
+            expect(player.currentTimeSignal.value).toBe(0);
+            media.dispatchEvent(new Event('timeupdate'));
+            expect(player.currentTimeSignal.value).toBe(5.5);
+        });
+        test('durationSignal updates on durationchange event', () => {
+            const media = createMedia();
+            Object.defineProperty(media, 'duration', { configurable: true, value: 120.5, writable: true });
+            const player = new Player({ media });
+            media.dispatchEvent(new Event('durationchange'));
+            expect(player.durationSignal.value).toBe(120.5);
+        });
+        test('seekingSignal updates on seeking and seeked events', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            expect(player.seekingSignal.value).toBe(false);
+            media.dispatchEvent(new Event('seeking'));
+            expect(player.seekingSignal.value).toBe(true);
+            media.dispatchEvent(new Event('seeked'));
+            expect(player.seekingSignal.value).toBe(false);
+        });
+        test('volumeSignal and mutedSignal update on volumechange event', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            Object.defineProperty(media, 'volume', { configurable: true, value: 0.7, writable: true });
+            Object.defineProperty(media, 'muted', { configurable: true, value: true, writable: true });
+            media.dispatchEvent(new Event('volumechange'));
+            expect(player.volumeSignal.value).toBe(0.7);
+            expect(player.mutedSignal.value).toBe(true);
+        });
+        test('playbackRateSignal updates on ratechange event', () => {
+            const media = createMedia();
+            const player = new Player({ media });
+            Object.defineProperty(media, 'playbackRate', { configurable: true, value: 1.5, writable: true });
+            media.dispatchEvent(new Event('ratechange'));
+            expect(player.playbackRateSignal.value).toBe(1.5);
+        });
+    });
 });

package/dist/__tests__/renderer-utils.test.js

@@ -29,6 +29,7 @@ describe('renderer-utils', () => {
                 barRadius: 3,
                 barIndexScale: 100 / ((4 + 2) * 10),
                 barSpacing: 6,
+                barMinHeight: 0,
             });
         });
     });
@@ -47,6 +48,23 @@ describe('renderer-utils', () => {
                 vScale: 1,
             })).toEqual({ topHeight: 0, totalHeight: 1 });
         });
+        it('ensures total height is at least barMinHeight', () => {
+            expect(calculateBarHeights({
+                maxTop: 0,
+                maxBottom: 0,
+                halfHeight: 20,
+                vScale: 1,
+                barMinHeight: 10,
+            })).toEqual({ topHeight: 5, totalHeight: 10 });
+            expect(calculateBarHeights({
+                maxTop: 0,
+                maxBottom: 0,
+                halfHeight: 20,
+                vScale: 1,
+                barMinHeight: 10,
+                barAlign: 'top',
+            })).toEqual({ topHeight: 0, totalHeight: 10 });
+        });
     });
     describe('resolveBarYPosition', () => {
         const baseArgs = {
@@ -85,6 +103,7 @@ describe('renderer-utils', () => {
                 vScale: 1,
                 canvasHeight: 40,
                 barAlign: undefined,
+                barMinHeight: 0,
             });
             expect(segments).toEqual([
                 { x: 0, y: 8, width: 1, height: 3 },
@@ -95,6 +114,33 @@ describe('renderer-utils', () => {
                 { x: 5, y: 0, width: 1, height: 16 },
             ]);
         });
+        it('ensures bars are at least barMinHeight tall', () => {
+            const height = 40;
+            const length = 10;
+            const { barIndexScale, barSpacing, barWidth, halfHeight } = calculateBarRenderConfig({
+                width: 100,
+                height,
+                length,
+                options,
+                pixelRatio: 1,
+            });
+            const segments = calculateBarSegments({
+                channelData: [
+                    new Float32Array(length).fill(0.001), // Very small values
+                ],
+                barIndexScale,
+                barSpacing,
+                barWidth,
+                halfHeight,
+                vScale: 1,
+                canvasHeight: height / 2,
+                barAlign: undefined,
+                barMinHeight: 10,
+            });
+            expect(segments.length).toBeGreaterThan(0);
+            expect(segments[0].height).toBe(10);
+            expect(segments[0].y).toBe(15); // Centered: 20 - 10/2
+        });
     });
     describe('getRelativePointerPosition', () => {
         it('returns pointer coordinates as relative offsets', () => {
@@ -302,12 +348,12 @@ describe('renderer-utils', () => {
         });
     });
     describe('calculateScrollPercentages', () => {
-        it('returns zero percentages when scroll width is zero', () => {
+        it('returns full range when scroll width is zero', () => {
             expect(calculateScrollPercentages({
                 scrollLeft: 0,
                 clientWidth: 100,
                 scrollWidth: 0,
-            })).toEqual({ startX: 0, endX: 0 });
+            })).toEqual({ startX: 0, endX: 1 });
         });
         it('returns start and end ratios relative to scroll width', () => {
             expect(calculateScrollPercentages({
@@ -316,5 +362,12 @@ describe('renderer-utils', () => {
                 scrollWidth: 400,
             })).toEqual({ startX: 0.125, endX: 0.375 });
         });
+        it('clamps values to 0-1 range', () => {
+            expect(calculateScrollPercentages({
+                scrollLeft: -10,
+                clientWidth: 100,
+                scrollWidth: 400,
+            })).toEqual({ startX: 0, endX: 0.225 });
+        });
     });
 });

package/dist/draggable.d.ts

@@ -1 +1,5 @@
+/**
+ * @deprecated Use createDragStream from './reactive/drag-stream.js' instead.
+ * This function is maintained for backward compatibility but will be removed in a future version.
+ */
 export declare function makeDraggable(element: HTMLElement | null, onDrag: (dx: number, dy: number, x: number, y: number) => void, onStart?: (x: number, y: number) => void, onEnd?: (x: number, y: number) => void, threshold?: number, mouseButton?: number, touchDelay?: number): () => void;

package/dist/draggable.js

@@ -1,3 +1,7 @@
+/**
+ * @deprecated Use createDragStream from './reactive/drag-stream.js' instead.
+ * This function is maintained for backward compatibility but will be removed in a future version.
+ */
 export function makeDraggable(element, onDrag, onStart, onEnd, threshold = 3, mouseButton = 0, touchDelay = 100) {
     if (!element)
         return () => void 0;

package/dist/player.d.ts

@@ -1,4 +1,5 @@
 import EventEmitter, { type GeneralEventTypes } from './event-emitter.js';
+import { type WritableSignal } from './reactive/store.js';
 type PlayerOptions = {
     media?: HTMLMediaElement;
     mediaControls?: boolean;
@@ -8,7 +9,27 @@ type PlayerOptions = {
 declare class Player<T extends GeneralEventTypes> extends EventEmitter<T> {
     protected media: HTMLMediaElement;
     private isExternalMedia;
+    private _isPlaying;
+    private _currentTime;
+    private _duration;
+    private _volume;
+    private _muted;
+    private _playbackRate;
+    private _seeking;
+    private reactiveMediaEventCleanups;
+    get isPlayingSignal(): WritableSignal<boolean>;
+    get currentTimeSignal(): WritableSignal<number>;
+    get durationSignal(): WritableSignal<number>;
+    get volumeSignal(): WritableSignal<number>;
+    get mutedSignal(): WritableSignal<boolean>;
+    get playbackRateSignal(): WritableSignal<number>;
+    get seekingSignal(): WritableSignal<boolean>;
     constructor(options: PlayerOptions);
+    /**
+     * Setup reactive media event handlers that update signals
+     * This bridges the imperative HTMLMediaElement API to reactive state
+     */
+    private setupReactiveMediaEvents;
     protected onMediaEvent<K extends keyof HTMLElementEventMap>(event: K, callback: (ev: HTMLElementEventMap[K]) => void, options?: boolean | AddEventListenerOptions): () => void;
     protected getSrc(): string;
     private revokeSrc;