Fix: Additional memory leaks and performance issues in plugins (#4211)

* Fix: Clear envelope plugin timeouts and event listeners on destroy

- Clear throttleTimeout in EnvelopePlugin destroy to prevent callbacks after destruction
- Store and remove dblclick listener from Polyline SVG element
- Store and remove touch event listeners (touchstart, touchmove, touchend)
- Clear pressTimer on Polyline destroy to prevent pending callbacks

Fixes memory leaks in envelope plugin (issues #16, #21, #22)

* Fix: Improve hover plugin event listener cleanup and memory usage

- Create unsubscribe functions immediately after attaching listeners
- Store only pointer coordinates instead of entire PointerEvent object
- Properly track zoom and scroll event unsubscribers

Fixes issues #17 and #24

* Fix: Remove zoom wheel listener from correct element

- Listener was added to container but removed from wrapper
- Now correctly removes listener from container element

Fixes issue #18

* Fix: Use single scroll listener for all timeline notches

- Refactored to use one scroll listener instead of one per notch
- Store notch metadata in a Map for batch visibility updates
- Significantly improves scroll performance with many notches
- Previously created N listeners for N notches (e.g., 60 for a 60-second audio)

Fixes issue #19

* Fix: Clear minimap container reference and prevent race condition

- Clear container reference on destroy to aid garbage collection
- Add isInitializing flag to prevent concurrent initMinimap() calls
- Ensures proper cleanup and prevents orphaned WaveSurfer instances

Fixes issues #20 and #25

* Fix: Improve decoder AudioContext safety and input validation

- Use explicit try/finally for AudioContext cleanup in decode()
- Add input validation to createBuffer() to prevent invalid AudioBuffer
- Prevent division by zero and undefined channel data errors

Fixes issues #23 and #29

* Fix: Clarify renderer createDelay logic and cleanup

- Rename 'reject' variable to 'rejectFn' for clarity
- Clear both timeout and reject function in onClear
- Add explicit typing and comments for better maintainability
- Ensure proper cleanup of pending delays

Fixes issue #26

* Doc: Clarify blob URL management responsibility in WebAudioPlayer

- Add documentation noting WebAudioPlayer doesn't manage blob URLs
- Clarify that Player class handles blob URL lifecycle
- Helps prevent memory leaks when using WebAudioPlayer standalone

Addresses issue #27

* Fix: Reorder player destroy operations for logical cleanup

- Call media.load() before media.remove() instead of after
- Ensures media element is properly reset before DOM removal
- More logical cleanup sequence

Fixes issue #30

* Fix: Move validation after channelData conversion in decoder

- Validate channel length after converting flat array to array of arrays
- Prevents false validation errors for valid flat array inputs
- Fixes failing e2e tests for pre-decoded waveform and blob loading

Author: katspaugh

src/decoder.ts

@@ -1,8 +1,12 @@
 /** Decode an array buffer into an audio buffer */
 async function decode(audioData: ArrayBuffer, sampleRate: number): Promise<AudioBuffer> {
   const audioCtx = new AudioContext({ sampleRate })
-  const decode = audioCtx.decodeAudioData(audioData)
-  return decode.finally(() => audioCtx.close())
+  try {
+    return await audioCtx.decodeAudioData(audioData)
+  } finally {
+    // Ensure AudioContext is always closed, even on synchronous errors
+    audioCtx.close()
+  }
 }
 
 /** Normalize peaks to -1..1 */
@@ -26,9 +30,22 @@ function normalize<T extends Array<Float32Array | number[]>>(channelData: T): T
 
 /** Create an audio buffer from pre-decoded audio data */
 function createBuffer(channelData: Array<Float32Array | number[]>, duration: number): AudioBuffer {
+  // Validate inputs
+  if (!channelData || channelData.length === 0) {
+    throw new Error('channelData must be a non-empty array')
+  }
+  if (duration <= 0) {
+    throw new Error('duration must be greater than 0')
+  }
+
   // If a single array of numbers is passed, make it an array of arrays
   if (typeof channelData[0] === 'number') channelData = [channelData as unknown as number[]]
 
+  // Validate channel data after conversion
+  if (!channelData[0] || channelData[0].length === 0) {
+    throw new Error('channelData must contain non-empty channel arrays')
+  }
+
   // Normalize to -1..1
   normalize(channelData)
 

src/player.ts

@@ -91,11 +91,12 @@ class Player<T extends GeneralEventTypes> extends EventEmitter<T> {
   protected destroy() {
     if (this.isExternalMedia) return
     this.media.pause()
-    this.media.remove()
     this.revokeSrc()
     this.media.removeAttribute('src')
     // Load resets the media element to its initial state
     this.media.load()
+    // Remove from DOM after cleanup
+    this.media.remove()
   }
 
   protected setMediaElement(element: HTMLMediaElement) {

src/plugins/envelope.ts

@@ -56,6 +56,11 @@ class Polyline extends EventEmitter<{
     }
   >
   private subscriptions: (() => void)[] = []
+  private dblClickListener?: (e: MouseEvent) => void
+  private touchStartListener?: (e: TouchEvent) => void
+  private touchMoveListener?: () => void
+  private touchEndListener?: () => void
+  private pressTimer?: number
 
   constructor(options: Options, wrapper: HTMLElement) {
     super()
@@ -131,37 +136,42 @@ class Polyline extends EventEmitter<{
     }
 
     // Listen to double click to add a new point
-    svg.addEventListener('dblclick', (e) => {
+    this.dblClickListener = (e) => {
       const rect = svg.getBoundingClientRect()
       const x = e.clientX - rect.left
       const y = e.clientY - rect.top
       this.emit('point-create', x / rect.width, y / rect.height)
-    })
+    }
+    svg.addEventListener('dblclick', this.dblClickListener)
 
     // Long press on touch devices
-    {
-      let pressTimer: number
-
-      const clearTimer = () => clearTimeout(pressTimer)
-
-      svg.addEventListener('touchstart', (e) => {
-        if (e.touches.length === 1) {
-          pressTimer = window.setTimeout(() => {
-            e.preventDefault()
-            const rect = svg.getBoundingClientRect()
-            const x = e.touches[0].clientX - rect.left
-            const y = e.touches[0].clientY - rect.top
-            this.emit('point-create', x / rect.width, y / rect.height)
-          }, 500)
-        } else {
-          clearTimer()
-        }
-      })
-
-      svg.addEventListener('touchmove', clearTimer)
-
-      svg.addEventListener('touchend', clearTimer)
+    const clearTimer = () => {
+      if (this.pressTimer !== undefined) {
+        clearTimeout(this.pressTimer)
+        this.pressTimer = undefined
+      }
+    }
+
+    this.touchStartListener = (e) => {
+      if (e.touches.length === 1) {
+        this.pressTimer = window.setTimeout(() => {
+          e.preventDefault()
+          const rect = svg.getBoundingClientRect()
+          const x = e.touches[0].clientX - rect.left
+          const y = e.touches[0].clientY - rect.top
+          this.emit('point-create', x / rect.width, y / rect.height)
+        }, 500)
+      } else {
+        clearTimer()
+      }
     }
+
+    this.touchMoveListener = clearTimer
+    this.touchEndListener = clearTimer
+
+    svg.addEventListener('touchstart', this.touchStartListener)
+    svg.addEventListener('touchmove', this.touchMoveListener)
+    svg.addEventListener('touchend', this.touchEndListener)
   }
 
   private makeDraggable(draggable: SVGElement, onDrag: (x: number, y: number) => void) {
@@ -279,6 +289,30 @@ class Polyline extends EventEmitter<{
   }
 
   destroy() {
+    // Clear pending press timer
+    if (this.pressTimer !== undefined) {
+      clearTimeout(this.pressTimer)
+      this.pressTimer = undefined
+    }
+
+    // Remove event listeners
+    if (this.dblClickListener) {
+      this.svg.removeEventListener('dblclick', this.dblClickListener)
+      this.dblClickListener = undefined
+    }
+    if (this.touchStartListener) {
+      this.svg.removeEventListener('touchstart', this.touchStartListener)
+      this.touchStartListener = undefined
+    }
+    if (this.touchMoveListener) {
+      this.svg.removeEventListener('touchmove', this.touchMoveListener)
+      this.touchMoveListener = undefined
+    }
+    if (this.touchEndListener) {
+      this.svg.removeEventListener('touchend', this.touchEndListener)
+      this.touchEndListener = undefined
+    }
+
     this.subscriptions.forEach((unsubscribe) => unsubscribe())
     this.polyPoints.clear()
     this.svg.remove()
@@ -363,6 +397,12 @@ class EnvelopePlugin extends BasePlugin<EnvelopePluginEvents, EnvelopePluginOpti
    * Destroy the plugin instance.
    */
   public destroy() {
+    // Clear pending throttle timeout
+    if (this.throttleTimeout) {
+      clearTimeout(this.throttleTimeout)
+      this.throttleTimeout = null
+    }
+
     this.polyline?.destroy()
     super.destroy()
   }

src/plugins/hover.ts

@@ -52,7 +52,7 @@ class HoverPlugin extends BasePlugin<HoverPluginEvents, HoverPluginOptions> {
   protected options: HoverPluginOptions & typeof defaultOptions
   private wrapper: HTMLElement
   private label: HTMLElement
-  private lastPointerMove: PointerEvent | null = null
+  private lastPointerPosition: { clientX: number; clientY: number } | null = null
   private unsubscribe: () => void = () => undefined
 
   constructor(options?: HoverPluginOptions) {
@@ -109,31 +109,36 @@ class HoverPlugin extends BasePlugin<HoverPluginEvents, HoverPluginOptions> {
     const container = this.wavesurfer.getWrapper()
     container.appendChild(this.wrapper)
 
-    // Attach pointer events
-    container.addEventListener('pointermove', this.onPointerMove)
-    container.addEventListener('pointerleave', this.onPointerLeave)
-
     // When zoom or scroll happens, re-run the pointer move logic
     // with the last known mouse position
     const onUpdate = () => {
-      if (this.lastPointerMove) this.onPointerMove(this.lastPointerMove)
+      if (this.lastPointerPosition) {
+        // Recreate a minimal PointerEvent-like object
+        this.onPointerMove(this.lastPointerPosition as PointerEvent)
+      }
     }
 
-    this.wavesurfer.on('zoom', onUpdate)
-    this.wavesurfer.on('scroll', onUpdate)
+    // Create unsubscribe function for wavesurfer events
+    const unsubscribeZoom = this.wavesurfer.on('zoom', onUpdate)
+    const unsubscribeScroll = this.wavesurfer.on('scroll', onUpdate)
+
+    // Attach pointer events and create complete unsubscribe function
+    container.addEventListener('pointermove', this.onPointerMove)
+    container.addEventListener('pointerleave', this.onPointerLeave)
+
     this.unsubscribe = () => {
       container.removeEventListener('pointermove', this.onPointerMove)
       container.removeEventListener('pointerleave', this.onPointerLeave)
-      this.wavesurfer?.un('zoom', onUpdate)
-      this.wavesurfer?.un('scroll', onUpdate)
+      unsubscribeZoom()
+      unsubscribeScroll()
     }
   }
 
   private onPointerMove = (e: PointerEvent) => {
     if (!this.wavesurfer) return
 
-    // Used when zooming
-    this.lastPointerMove = e
+    // Store only the position data needed for zoom/scroll updates
+    this.lastPointerPosition = { clientX: e.clientX, clientY: e.clientY }
 
     // Position
     const bbox = this.wavesurfer.getWrapper().getBoundingClientRect()
@@ -157,7 +162,7 @@ class HoverPlugin extends BasePlugin<HoverPluginEvents, HoverPluginOptions> {
 
   private onPointerLeave = () => {
     this.wrapper.style.opacity = '0'
-    this.lastPointerMove = null
+    this.lastPointerPosition = null
   }
 
   /** Unmount */

src/plugins/minimap.ts

@@ -54,6 +54,7 @@ class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions
   private miniWavesurfer: WaveSurfer | null = null
   private overlay: HTMLElement
   private container: HTMLElement | null = null
+  private isInitializing = false
 
   constructor(options: MinimapPluginOptions) {
     super(options)
@@ -122,16 +123,26 @@ class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions
   }
 
   private initMinimap() {
+    // Prevent concurrent initialization
+    if (this.isInitializing) return
+    this.isInitializing = true
+
     if (this.miniWavesurfer) {
       this.miniWavesurfer.destroy()
       this.miniWavesurfer = null
     }
 
-    if (!this.wavesurfer) return
+    if (!this.wavesurfer) {
+      this.isInitializing = false
+      return
+    }
 
     const data = this.wavesurfer.getDecodedData()
     const media = this.wavesurfer.getMediaElement()
-    if (!data || !media) return
+    if (!data || !media) {
+      this.isInitializing = false
+      return
+    }
 
     const peaks = []
     for (let i = 0; i < data.numberOfChannels; i++) {
@@ -209,6 +220,9 @@ class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions
         this.emit('timeupdate', currentTime)
       }),
     )
+
+    // Reset flag after initialization completes
+    this.isInitializing = false
   }
 
   private getOverlayWidth(): number {
@@ -249,6 +263,7 @@ class MinimapPlugin extends BasePlugin<MinimapPluginEvents, MinimapPluginOptions
   public destroy() {
     this.miniWavesurfer?.destroy()
     this.minimapWrapper.remove()
+    this.container = null
     super.destroy()
   }
 }

src/plugins/timeline.ts

@@ -58,6 +58,7 @@ class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOpti
   private timelineWrapper: HTMLElement
   private unsubscribeNotches: (() => void)[] = []
   protected options: TimelinePluginOptions & typeof defaultOptions
+  private notchElements: Map<HTMLElement, { start: number; width: number; wasVisible: boolean }> = new Map()
 
   constructor(options?: TimelinePluginOptions) {
     super(options || {})
@@ -150,39 +151,46 @@ class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOpti
   }
 
   private virtualAppend(start: number, container: HTMLElement, element: HTMLElement) {
-    let wasVisible = false
+    // Store notch metadata for batch updates
+    this.notchElements.set(element, {
+      start,
+      width: element.clientWidth,
+      wasVisible: false,
+    })
+
+    // Initial render check
+    if (!this.wavesurfer) return
+    const scrollLeft = this.wavesurfer.getScroll()
+    const scrollRight = scrollLeft + this.wavesurfer.getWidth()
 
-    const renderIfVisible = (scrollLeft: number, scrollRight: number) => {
-      if (!this.wavesurfer) return
-      const width = element.clientWidth
-      const isVisible = start >= scrollLeft && start + width < scrollRight
+    const notchData = this.notchElements.get(element)!
+    const isVisible = start >= scrollLeft && start + notchData.width < scrollRight
+    notchData.wasVisible = isVisible
 
-      if (isVisible === wasVisible) return
-      wasVisible = isVisible
+    if (isVisible) {
+      container.appendChild(element)
+    }
+  }
+
+  private updateVisibleNotches(scrollLeft: number, scrollRight: number, container: HTMLElement) {
+    this.notchElements.forEach((notchData, element) => {
+      const isVisible = notchData.start >= scrollLeft && notchData.start + notchData.width < scrollRight
+
+      if (isVisible === notchData.wasVisible) return
+      notchData.wasVisible = isVisible
 
       if (isVisible) {
         container.appendChild(element)
       } else {
         element.remove()
       }
-    }
-
-    if (!this.wavesurfer) return
-    const scrollLeft = this.wavesurfer.getScroll()
-    const scrollRight = scrollLeft + this.wavesurfer.getWidth()
-
-    renderIfVisible(scrollLeft, scrollRight)
-
-    this.unsubscribeNotches.push(
-      this.wavesurfer.on('scroll', (_start, _end, scrollLeft, scrollRight) => {
-        renderIfVisible(scrollLeft, scrollRight)
-      }),
-    )
+    })
   }
 
   private initTimeline() {
     this.unsubscribeNotches.forEach((unsubscribe) => unsubscribe())
     this.unsubscribeNotches = []
+    this.notchElements.clear()
 
     const duration = this.wavesurfer?.getDuration() ?? this.options.duration ?? 0
     const pxPerSec = (this.wavesurfer?.getWrapper().scrollWidth || this.timelineWrapper.scrollWidth) / duration
@@ -265,6 +273,15 @@ class TimelinePlugin extends BasePlugin<TimelinePluginEvents, TimelinePluginOpti
     this.timelineWrapper.innerHTML = ''
     this.timelineWrapper.appendChild(timeline)
 
+    // Add single scroll listener for all notches (instead of one per notch)
+    if (this.wavesurfer) {
+      this.unsubscribeNotches.push(
+        this.wavesurfer.on('scroll', (_start, _end, scrollLeft, scrollRight) => {
+          this.updateVisibleNotches(scrollLeft, scrollRight, timeline)
+        }),
+      )
+    }
+
     this.emit('ready')
   }
 }

src/plugins/zoom.ts

@@ -157,8 +157,8 @@ class ZoomPlugin extends BasePlugin<ZoomPluginEvents, ZoomPluginOptions> {
   }
 
   destroy() {
-    if (this.wrapper) {
-      this.wrapper.removeEventListener('wheel', this.onWheel)
+    if (this.container) {
+      this.container.removeEventListener('wheel', this.onWheel)
     }
     super.destroy()
   }