DOCSEARCHbyAlgolia
Submit Docs

wavesurfer.js

repository·main·Indexed 27 days ago

https://github.com/katspaugh/wavesurfer.js

An interactive waveform rendering and audio playback library for web applications. It provides audio visualization, playback controls, and a reactive state system. The library includes official plugins for Regions, Timeline, Minimap, Envelope, Record, Spectrogram, and Hover, and supports custom plugin development via the definePlugin API.

Tokens
4.5K
Snippets
12
Records
29
Agent score
94%

What's inside wavesurfer.js

  1. Locate wavesurfer.js source and examples

    main

    The project is organized as follows:

    • Core Library: The TypeScript source files are located in src/. The main entry point for the library is src/wavesurfer.ts.
    • Demos and Documentation: Stand-alone HTML demos that demonstrate specific features can be found in the examples/ directory.
    • Testing: End-to-end and visual regression tests are located in cypress/ (specifically cypress/e2e), with snapshots stored in cypress/snapshots.

  2. Style wavesurfer.js elements with CSS

    main

    Since wavesurfer.js v7 uses Shadow DOM, styles are isolated. To style internal elements, use the ::part() pseudo-selector. Elements with a part attribute can be targeted.

    Example of styling the cursor and a region:

    #waveform ::part(cursor):before {
  content: '🏄';
}
#waveform ::part(region) {
  font-family: fantasy;
}

  4. Install, build, and run wavesurfer.js

    main

    Use the following commands to manage the development lifecycle of the wavesurfer.js project:

    • Install dependencies: Use yarn to install all necessary packages.
    • Run the development server: Use yarn start to compile TypeScript in watch mode and serve the examples at http://localhost:9090.
    • Build for production: Use yarn build to generate production assets.
    • Run lint checks: Use yarn lint to verify code quality.
    • Run Cypress tests: Use yarn cypress to execute end-to-end and visual regression tests.
    yarn
yarn start
yarn build
yarn lint
yarn cypress

  5. Import wavesurfer.js plugins

    main

    Plugins can be imported as ESM modules or included via script tags.

    ESM Import (e.g., Regions plugin):

    import Regions from 'wavesurfer.js/dist/plugins/regions.esm.js'

    UMD Script Tag (exports WaveSurfer.Regions):

    <script src="https://unpkg.com/wavesurfer.js@7/dist/plugins/regions.min.js"></script>

  8. Fix asymmetrical waveforms in stereo audio

    main
    By default, wavesurfer.js renders stereo audio as a single waveform (left channel on top, right on bottom). If the audio is hard-panned, it will look asymmetrical. To render each channel separately, use the splitChannels option.

  9. Handle large audio files

    main
    Because wavesurfer.js decodes audio entirely in the browser using Web Audio, very large files may fail due to memory constraints. For large files, it is recommended to use pre-decoded peaks. You can generate these peaks using tools like audiowaveform.

  10. Troubleshoot CORS issues

    main
    If you encounter CORS issues, ensure the server hosting your audio files sends the correct Access-Control-Allow-Origin headers. Wavesurfer fetches audio via URL to decode it, and browsers restrict cross-origin fetches unless permitted by the remote server.

  11. Fix audio and waveform mismatch

    main

    If the waveform does not align with the audio, it is likely due to a Variable Bit Rate (VBR) file. To fix this:

    1. Convert the audio file to Constant Bit Rate (CBR).
    2. Alternatively, use the Web Audio shim for better accuracy.

  12. Initialize a WaveSurfer instance

    main

    Create a new waveform instance using WaveSurfer.create(). You must provide a container (a CSS selector for the element where the waveform will be rendered) and can provide various options like waveColor, progressColor, and the audio url.

    import WaveSurfer from 'wavesurfer.js'

const wavesurfer = WaveSurfer.create({
  container: '#waveform',
  waveColor: '#4F4A85',
  progressColor: '#383351',
  url: '/audio.mp3',
})