wavesurfer.js v7 is a TypeScript rewrite of wavesurfer.js that brings several improvements:
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/dist/wavesurfer.min.js"></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.js'
Or as a script tag:
<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.
See the documentation on wavesurfer methods, options and events.
container
: HTMLElement | string
- Required: an HTML element or selector where the waveform will be rendered.height
: number | 'auto'
- The height of the waveform in pixels, or "auto" to fill the container heightwaveColor
: string | string[] | CanvasGradient
- The color of the waveformprogressColor
: string | string[] | CanvasGradient
- The color of the progress maskcursorColor
: string
- The color of the playpack cursorcursorWidth
: number
- The cursor widthbarWidth
: number
- Render the waveform with bars like this: ▁ ▂ ▇ ▃ ▅ ▂barGap
: number
- Spacing between bars in pixelsbarRadius
: number
- Rounded borders for barsbarHeight
: number
- A vertical scaling factor for the waveformbarAlign
: 'top' | 'bottom'
- Vertical bar alignmentminPxPerSec
: number
- Minimum pixels per second of audio (i.e. zoom level)fillParent
: boolean
- Stretch the waveform to fill the container, true by defaulturl
: string
- Audio URLpeaks
: Array<Float32Array | number[]>
- Pre-computed audio dataduration
: number
- Pre-computed durationmedia
: HTMLMediaElement
- Use an existing media element instead of creating oneautoplay
: boolean
- Play the audio on loadinteract
: boolean
- Pass false to disable clicks on the waveformhideScrollbar
: boolean
- Hide the scrollbaraudioRate
: number
- Audio rateautoScroll
: boolean
- Automatically scroll the container to keep the current position in viewportautoCenter
: boolean
- If autoScroll is enabled, keep the cursor in the center of the waveform during playbacksampleRate
: number
- Decoding sample rate. Doesn't affect the playback. Defaults to 8000splitChannels
: WaveSurferOptions[]
- Render each audio channel as a separate waveformnormalize
: boolean
- Stretch the waveform to the full heightplugins
: GenericPlugin[]
- The list of plugins to initialize on startrenderFunction
: (peaks: Array<Float32Array | number[]>, ctx: CanvasRenderingContext2D) => void
- Custom render functionfetchParams
: RequestInit
- Options to pass to the fetch methodload
: [url: string]
- When audio starts loadingloading
: [percentage: number]
- When audio is being loadeddecode
: [duration: number]
- When the audio has been decodedready
: [duration: number]
- When the audio is both decoded and can playredraw
: []
- When a waveform is drawnplay
: []
- When the audio starts playingpause
: []
- When the audio pausesfinish
: []
- When the audio finishes playingtimeupdate
: [currentTime: number]
- On audio position change, fires continuously during playbackaudioprocess
: [currentTime: number]
- An alias of timeupdate but only when the audio is playingseeking
: [currentTime: number]
- When the user seeks to a new positioninteraction
: [newTime: number]
- When the user interacts with the waveform (i.g. clicks or drags on it)click
: [relativeX: number]
- When the user clicks on the waveformdrag
: [relativeX: number]
- When the user drags the cursorscroll
: [visibleStartTime: number, visibleEndTime: number]
- When the waveform is scrolled (panned)zoom
: [minPxPerSec: number]
- When the zoom level changesdestroy
: []
- Just before the waveform is destroyed so you can clean up your eventsThe "official" plugins have been completely rewritten and enhanced:
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 for play around with styling.
Most options, events, and methods are similar to those in previous versions.
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.startTime
.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 the media
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 if minPxPerSec
is set to a higher valueskipLength
– there's no skipForward
and skipBackward
methods anymoresplitChannelsOptions
– you should now use splitChannels
to pass the channel options. Pass height: 0
to hide a channel. See this example.drawingContextAttributes
, maxCanvasWidth
, forceDecode
– removed to reduce code complexityxhr
- please use fetchParams
insteadbarMinHeight
- the minimum bar height is now 1 pixel by defaultgetFilters
, setFilter
– as there's no Web Audio "backend"drawBuffer
– to redraw the waveform, use setOptions
instead and pass new rendering optionscancelAjax
– you can pass an AbortSignal in fetchParams
skipForward
, skipBackward
, setPlayEnd
– can be implemented using setTime(time)
exportPCM
is replaced with exportPeaks
that returns arrays of floatstoggleMute
is now called setMuted(true | false)
setHeight
, setWaveColor
, setCursorColor
, etc. – use setOptions
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.
To get started with development, follow these steps:
yarn
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, first build the project:
yarn build
Then launch the tests:
yarn cypress
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.ts and look forward to hearing about your experiences with the library!
Author: katspaugh
Source Code: https://github.com/katspaugh/wavesurfer.js
License: BSD-3-Clause license