designly-wavesurfer
v7.7.11
Published
Audio waveform player
Downloads
5
Maintainers
Readme
wavesurfer.js
Wavesurfer.js is an interactive waveform rendering and audio playback library, perfect for web applications. It leverages modern web technologies to provide a robust and visually engaging audio experience.
Getting started
Install and import the package:
npm install --save wavesurfer.js
import WaveSurfer from 'wavesurfer.js'
Alternatively, insert a UMD script tag which exports the library as a global WaveSurfer
variable:
<script src="https://unpkg.com/wavesurfer.js@7"></script>
Create a wavesurfer instance and pass various options:
const wavesurfer = WaveSurfer.create({
container: '#waveform',
waveColor: '#4F4A85',
progressColor: '#383351',
url: '/audio.mp3',
})
To import one of the plugins, e.g. the Regions plugin:
import Regions from 'wavesurfer.js/dist/plugins/regions.esm.js'
Or as a script tag that will export WaveSurfer.Regions
:
<script src="https://unpkg.com/wavesurfer.js@7/dist/plugins/regions.min.js"></script>
TypeScript types are included in the package, so there's no need to install @types/wavesurfer.js
.
See more examples.
API reference
See the wavesurfer.js documentation on our website:
Plugins
We maintain a number of official plugins that add various extra features:
- Regions – visual overlays and markers for regions of audio
- Timeline – displays notches and time labels below the waveform
- Minimap – a small waveform that serves as a scrollbar for the main waveform
- Envelope – a graphical interface to add fade-in and -out effects and control volume
- Record – records audio from the microphone and renders a waveform
- Spectrogram – visualization of an audio frequency spectrum (written by @akreal)
- Hover – shows a vertical line and timestmap on waveform hover
CSS styling
wavesurfer.js v7 is rendered into a Shadow DOM tree. This isolates its CSS from the rest of the web page.
However, it's still possible to style various wavesurfer.js elements with CSS via the ::part()
pseudo-selector.
For example:
#waveform ::part(cursor):before {
content: '🏄';
}
#waveform ::part(region) {
font-family: fantasy;
}
You can see which elements you can style in the DOM inspector – they will have a part
attribute.
See this example to play around with styling.
Questions
Have a question about integrating wavesurfer.js on your website? Feel free to ask in our Discussions forum.
However, please keep in mind that this forum is dedicated to wavesurfer-specific questions. If you're new to JavaScript and need help with the general basics like importing NPM modules, please consider asking ChatGPT or StackOverflow first.
FAQ
v7 – a new TypeScript version
Wavesurfer.js v7 is a TypeScript rewrite of wavesurfer.js that brings several improvements:
- Typed API for better development experience
- Enhanced decoding and rendering performance
- New and improved plugins
Upgrading from v6
Most options, events, and methods are similar to those in previous versions.
Notable differences
- HTML audio playback by default (used to be an opt-in via
backend: "MediaElement"
) - The Markers plugin is removed – you should use the Regions plugin with just a
startTime
. - No Microphone plugin – superseded by the new Record plugin with more features.
- The Cursor plugin is replaced by the Hover plugin.
Removed options
audioContext
,closeAudioContext
,audioScriptProcessor
autoCenterImmediately
–autoCenter
is now always immediate unless the audio is playingbackgroundColor
,hideCursor
– this can be easily set via CSSmediaType
– you should instead pass an entire media element in themedia
option. Example.partialRender
– done by defaultpixelRatio
–window.devicePixelRatio
is used by defaultrenderer
– there's just one renderer for now, so no need for this optionresponsive
– responsiveness is enabled by defaultscrollParent
– the container will scroll ifminPxPerSec
is set to a higher valueskipLength
– there's noskipForward
andskipBackward
methods anymoresplitChannelsOptions
– you should now usesplitChannels
to pass the channel options. Passheight: 0
to hide a channel. See this example.drawingContextAttributes
,maxCanvasWidth
,forceDecode
– removed to reduce code complexityxhr
- please usefetchParams
insteadbarMinHeight
- the minimum bar height is now 1 pixel by default
Removed methods
getFilters
,setFilter
– see the Web Audio exampledrawBuffer
– to redraw the waveform, usesetOptions
instead and pass new rendering optionscancelAjax
– you can pass an AbortSignal infetchParams
skipForward
,skipBackward
,setPlayEnd
– can be implemented usingsetTime(time)
exportPCM
is replaced withexportPeaks
which returns arrays of floatstoggleMute
is now calledsetMuted(true | false)
setHeight
,setWaveColor
,setCursorColor
, etc. – usesetOptions
with the corresponding params instead. E.g.,wavesurfer.setOptions({ height: 300, waveColor: '#abc' })
See the complete documentation of the new API.
Development
To get started with development, follow these steps:
- Install dev dependencies:
yarn
- Start the TypeScript compiler in watch mode and launch an HTTP server:
yarn start
This command will open http://localhost:9090 in your browser with live reload, allowing you to see the changes as you develop.
Tests
The tests are written in the Cypress framework. They are a mix of e2e and visual regression tests.
To run the test suite locally, first build the project:
yarn build
Then launch the tests:
yarn cypress
Feedback
We appreciate your feedback and contributions!
If you encounter any issues or have suggestions for improvements, please don't hesitate to post in our forum.
We hope you enjoy using wavesurfer.js and look forward to hearing about your experiences with the library!