Feat: Add setScrollTime method (#3547)

* Feat: Add setScrollTime method

This adds a `setScrollTime` method to `wavesurfer` that takes a time in
seconds. It also adds `setScroll` and `setScrollPercentage` methods to
`renderer` which are used by `setScrollTime`.

This allows the viwing window to be set indepenently of the play head.

Fixes: #3411
Related: #3361

* Add a test

* make this more accurate

* Update src/renderer.ts

Co-authored-by: katspaugh <[email protected]>

* Update src/wavesurfer.ts

Co-authored-by: katspaugh <[email protected]>

---------

Co-authored-by: katspaugh <[email protected]>

cypress/e2e/basic.cy.js

@@ -143,6 +143,23 @@ describe('WaveSurfer basic tests', () => {
     })
   })
 
+  it('should scroll on setScrollTime if zoomed in', () => {
+    cy.window().then((win) => {
+      win.wavesurfer.zoom(300)
+      const zoomedWidth = win.wavesurfer.getWrapper().clientWidth
+      win.wavesurfer.zoom(600)
+      const newWidth = win.wavesurfer.getWrapper().clientWidth
+
+      expect(Math.round(newWidth / zoomedWidth)).to.equal(2)
+
+      win.wavesurfer.setScrollTime(20)
+
+      cy.wait(1000).then(() => {
+        expect(win.wavesurfer.getScroll()).to.be.greaterThan(100)
+      })
+    })
+  })
+
   it('should export decoded audio data', () => {
     cy.window().then((win) => {
       const data = win.wavesurfer.getDecodedData()

src/player.ts

@@ -106,7 +106,7 @@ class Player<T extends GeneralEventTypes> extends EventEmitter<T> {
     return !this.media.paused && !this.media.ended
   }
 
-  /** Jumpt to a specific time in the audio (in seconds) */
+  /** Jump to a specific time in the audio (in seconds) */
   public setTime(time: number) {
     this.media.currentTime = time
   }

src/renderer.ts

@@ -249,6 +249,16 @@ class Renderer extends EventEmitter<RendererEvents> {
     return this.scrollContainer.scrollLeft
   }
 
+  private setScroll(pixels: number) {
+    this.scrollContainer.scrollLeft = pixels
+  }
+
+  setScrollPercentage(percent: number) {
+    const { scrollWidth } = this.scrollContainer
+    const scrollStart =  scrollWidth * percent
+    this.setScroll(scrollStart)
+  }
+
   destroy() {
     this.container.remove()
     this.resizeObserver?.disconnect()

src/wavesurfer.ts

@@ -350,6 +350,12 @@ class WaveSurfer extends Player<WaveSurferEvents> {
     return this.renderer.getScroll()
   }
 
+  /** Move the start of the viewing window to a specific time in the audio (in seconds) */
+  public setScrollTime(time: number) {
+    const percentage = time / this.getDuration()
+    this.renderer.setScrollPercentage(percentage)
+  }
+
   /** Get all registered plugins */
   public getActivePlugins() {
     return this.plugins
@@ -459,7 +465,7 @@ class WaveSurfer extends Player<WaveSurferEvents> {
     this.options.interact = isInteractive
   }
 
-  /** Jumpt to a specific time in the audio (in seconds) */
+  /** Jump to a specific time in the audio (in seconds) */
   public setTime(time: number) {
     super.setTime(time)
     this.updateProgress(time)