Feat: splitChannels (#2796)

* Feat: splitChannels

* Refactor rendering

* Update tests

* Timeout contexts

* Fix color usage in the record plugin

* Fix test

Author: katspaugh

README.md

@@ -92,11 +92,26 @@ See [this example](https://wavesurfer.pages.dev/examples/#styling.js) for play a
 Most options, events, and methods are similar to those in previous versions.
 
 ### Notable differences
- * The `backend` option is removed – HTML5 audio (or video) is the only playback mechanism. However, you can still connect wavesurfer to Web Audio via `MediaElementSourceNode`. See this [example](https://wavesurfer.pages.dev/examples/#webaudio.js).
+ * The `backend` option is removed – [HTML5 audio (or video) is the only playback mechanism](https://github.com/katspaugh/wavesurfer.js/discussions/2762#discussioncomment-5669347). However, you can still connect wavesurfer to Web Audio via `MediaElementSourceNode`. See this [example](https://wavesurfer.pages.dev/examples/#webaudio.js).
  * The Markers plugin is removed – use the Regions plugin with just a `startTime`.
  * No Microphone plugn – superseded by the new Record plugin with more features.
  * No Cursor and Playhead plugins yet – to be done.
 
+### Removed options
+ * `backend`, `audioContext`, `closeAudioContext', 'audioScriptProcessor` – there's no Web Audio backend, so no AudioContext
+ * `autoCenterImmediately` – `autoCenter` is now always immediate unless the audio is playing
+ * `backgroundColor`, `hideCursor` – this can be easily set via CSS
+ * `mediaType`, `mediaControls` – you should instead pass an entire media element in the `media` option. [Example](https://wavesurfer-js.org/examples/#video.js).
+ * `normalize` – peaks are normalized to -1..1 by default
+ * `partialRender` – done by default
+ * `pixelRatio` – `window.devicePixelRatio` is used by default
+ * `renderer` – there's just one renderer for now, so no need for this option
+ * `responsive` – responsiveness is enabled by default
+ * `scrollParent` – the container will scroll if `minPxPerSec` is set to a higher value
+ * `skipLength` – there's no `skipForward` and `skipBackward` methods anymore
+ * `splitChannelsOptions` – you should now use `splitChannels` to pass the channel options. Pass `height: 0` to hide a channel. See [this example](https://wavesurfer-js.org/examples/#split-channels.js).
+ * `xhr`, `drawingContextAttributes`, `maxCanvasWidth`, `forceDecode` – removed to reduce code complexity
+
 ### Removed methods
  * `getFilters`, `setFilter` – as there's no Web Audio "backend"
  * `drawBuffer` – to redraw the waveform, use `setOptions` instead and pass new rendering options

cypress/e2e/basic.cy.js

@@ -27,13 +27,13 @@ describe('WaveSurfer', () => {
 
   it('should load an audio file without errors', () => {
     cy.window().then((win) => {
-      expect(win.wavesurfer.getDuration()).to.equal(21.773878)
+      expect(win.wavesurfer.getDuration().toFixed(2)).to.equal('21.77')
 
       win.wavesurfer.load('../../examples/audio/audio.wav')
 
       return new Promise((resolve) => {
         win.wavesurfer.once('ready', () => {
-          expect(win.wavesurfer.getDuration()).to.equal(26.386688)
+          expect(win.wavesurfer.getDuration().toFixed(2)).to.equal('26.39')
           resolve()
         })
       })
@@ -101,7 +101,6 @@ describe('WaveSurfer', () => {
 
   it('should scroll on seek if zoomed in', () => {
     cy.window().then((win) => {
-      const initialWidth = win.wavesurfer.getWrapper().clientWidth
       win.wavesurfer.zoom(300)
       const zoomedWidth = win.wavesurfer.getWrapper().clientWidth
       win.wavesurfer.zoom(600)

cypress/e2e/options.cy.js

@@ -105,12 +105,7 @@ describe('WaveSurfer', () => {
         win.wavesurfer = win.WaveSurfer.create({
           container: id,
           url: '../../examples/audio/demo.wav',
-          waveColor: [
-            "rgb(200, 165, 49)",
-            "rgb(211, 194, 138)",
-            "rgb(205, 124, 49)",
-            "rgb(205, 98, 49)",
-          ],
+          waveColor: ['rgb(200, 165, 49)', 'rgb(211, 194, 138)', 'rgb(205, 124, 49)', 'rgb(205, 98, 49)'],
           progressColor: 'rgba(0, 0, 0, 0.25)',
           cursorColor: 'blue',
         })
@@ -258,6 +253,53 @@ describe('WaveSurfer', () => {
     })
   })
 
+  it('should split channels', () => {
+    cy.window().then((win) => {
+      return new Promise((resolve) => {
+        win.wavesurfer = win.WaveSurfer.create({
+          container: id,
+          url: '../../examples/audio/stereo.mp3',
+          splitChannels: true,
+          waveColor: 'rgb(200, 0, 200)',
+          progressColor: 'rgb(100, 0, 100)',
+        })
+
+        win.wavesurfer.once('ready', () => {
+          win.wavesurfer.setTime(2)
+          cy.wait(100)
+          cy.get(id).matchImageSnapshot('split-channels')
+          resolve()
+        })
+      })
+    })
+  })
+
+  it('should split channels with options', () => {
+    cy.window().then((win) => {
+      return new Promise((resolve) => {
+        win.wavesurfer = win.WaveSurfer.create({
+          container: id,
+          url: '../../examples/audio/stereo.mp3',
+          splitChannels: [
+            {
+              waveColor: 'rgb(200, 0, 200)',
+              progressColor: 'rgb(100, 0, 100)',
+            },
+            {
+              waveColor: 'rgb(0, 200, 200)',
+              progressColor: 'rgb(0, 100, 100)',
+            },
+          ],
+        })
+
+        win.wavesurfer.once('ready', () => {
+          cy.get(id).matchImageSnapshot('split-channels-options')
+          resolve()
+        })
+      })
+    })
+  })
+
   it('should use plugins with Regions', () => {
     cy.window().then((win) => {
       return new Promise((resolve) => {

cypress/snapshots/barWidth.snap.png

@@ -12,6 +12,8 @@ const options = {
   container: 'body',
   /** The height of the waveform in pixels */
   height: 128,
+  /** Render each audio channel as a separate waveform */
+  splitChannels: false,
   /** The color of the waveform */
   waveColor: '#ff4e00',
   /** The color of the progress mask */

cypress/snapshots/bars.snap.png

@@ -121,7 +121,7 @@ multitrack.on('intro-end-change', ({ id, endTime }) => {
 multitrack.on('drop', ({ id }) => {
   multitrack.addTrack({
     id,
-    url: '/examples/demo.wav',
+    url: '/examples/audio/demo.wav',
     startPosition: 0,
     draggable: true,
     options: {