wavesurfer.js v7 beta 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
![waveform screenshot](https://private-user-images.githubusercontent.com/381895/241718529-05f03bed-800e-4fa1-b09a-82a39a1c62ce.png?jwt=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnaXRodWIuY29tIiwiYXVkIjoicmF3LmdpdGh1YnVzZXJjb250ZW50LmNvbSIsImtleSI6ImtleTUiLCJleHAiOjE3MjU3MDM2OTMsIm5iZiI6MTcyNTcwMzM5MywicGF0aCI6Ii8zODE4OTUvMjQxNzE4NTI5LTA1ZjAzYmVkLTgwMGUtNGZhMS1iMDlhLTgyYTM5YTFjNjJjZS5wbmc_WC1BbXotQWxnb3JpdGhtPUFXUzQtSE1BQy1TSEEyNTYmWC1BbXotQ3JlZGVudGlhbD1BS0lBVkNPRFlMU0E1M1BRSzRaQSUyRjIwMjQwOTA3JTJGdXMtZWFzdC0xJTJGczMlMkZhd3M0X3JlcXVlc3QmWC1BbXotRGF0ZT0yMDI0MDkwN1QxMDAzMTNaJlgtQW16LUV4cGlyZXM9MzAwJlgtQW16LVNpZ25hdHVyZT00NGZmOTBiZDQ0Y2MwODBiNzhmMTlhOGE1MWRmZjI2NTg1ZjdkMmY0MjJiNDZiNTJjNDc0NmY0OWJlNWE1MzJkJlgtQW16LVNpZ25lZEhlYWRlcnM9aG9zdCZhY3Rvcl9pZD0wJmtleV9pZD0wJnJlcG9faWQ9MCJ9.4QP2k9Pv-Dj6weWiDEd4MyT6ibsrVfkl34Hb2UjOJEI)
ℹ️ Looking for the old stable version? V6 is here: https://github.com/katspaugh/wavesurfer.js/tree/v6
Try it out:
npm install --save wavesurfer.js@beta
import WaveSurfer from 'wavesurfer.js'
Alternatively, import it from a CDN as a ES6 module directly in the browser:
<script type="module">
import WaveSurfer from 'https://unpkg.com/wavesurfer.js@beta'
const wavesurfer = WaveSurfer.create({ ... })
</script>
Or, as a UMD script tag which exports the library as a global WaveSurfer
variable:
<script src="https://unpkg.com/wavesurfer.js@beta/dist/wavesurfer.min.js"></script>
To import a plugin, e.g. the Timeline plugin:
import Timeline from 'https://unpkg.com/wavesurfer.js@beta/plugins/timeline.js'
TypeScript types are included in the package, so there's no need to install @types/wavesurfer.js
.
See more examples.
See the documentation on wavesurfer.js methods, options and events on our website.
The "official" plugins have been completely rewritten and enhanced:
- 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
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 via CSS using 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 for play around with styling.
Most options, events, and methods are similar to those in previous versions.
- The
backend
option is removed – HTML5 audio (or video) is the only playback mechanism. However, you can still connect wavesurfer to Web Audio viaMediaElementSourceNode
. See this example. - 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.
backend
,audioContext
,closeAudioContext', 'audioScriptProcessor
– there's no Web Audio backend, so no AudioContextautoCenterImmediately
–autoCenter
is now always immediate unless the audio is playingbackgroundColor
,hideCursor
– this can be easily set via CSSmediaType
,mediaControls
– 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.xhr
,drawingContextAttributes
,maxCanvasWidth
,forceDecode
– removed to reduce code complexity
getFilters
,setFilter
– as there's no Web Audio "backend"drawBuffer
– to redraw the waveform, usesetOptions
instead and pass new rendering optionscancelAjax
– ajax is replaced byfetch
loadBlob
– useURL.createObjectURL()
to convert a blob to a URL and callload(url)
insteadskipForward
,skipBackward
,setPlayEnd
– can be implemented usingsetTime(time)
exportPCM
is renamed togetDecodedData
and doesn't take any paramstoggleMute
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.
Have a question about integrating wavesurfer.js on your website? Feel free to ask in our Discussions forum.
- Q: Does wavesurfer support large files?
- A: Since wavesurfer decodes audio entirely in the browser, large files may fail to decode due to memory constraints. We recommend using pre-decoded peaks for large files (see this example). You can use a tool like bbc/audiowaveform to generate peaks.
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.
The tests are written in the Cypress framework. They are a mix of e2e and visual regression tests. To run the test suite locally:
yarn cypress
We appreciate your feedback and contributions! Join the conversation and share your thoughts here: katspaugh#2789
If you encounter any issues or have suggestions for improvements, please don't hesitate to open an issue or submit a pull request on the GitHub repository.
We hope you enjoy using wavesurfer.ts and look forward to hearing about your experiences with the library!