Skip to content

Latest commit

 

History

History
149 lines (100 loc) · 5.9 KB

README.md

File metadata and controls

149 lines (100 loc) · 5.9 KB
Raw

logo wavesurfer.js

npm

New TypeScript version

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

Screenshot

ℹ️ Looking for the old stable version? V6 is here: https://github.com/katspaugh/wavesurfer.js/tree/master

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/dist/plugins/timeline.js'

TypeScript types are included in the package, so there's no need to install @types/wavesurfer.js.

See more examples.

Documentation

See the documentation on wavesurfer.js methods, options and events on our website.

Plugins

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

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 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.

DOM inspector screenshot

See this example for play around with styling.

Migrating from v6

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.
  • The Markers plugin is removed – use the Regions plugin with startTime equal to endTime.
  • No Microphone plugn – superseded by the new Record plugin with more features.
  • No Cursor and Playhead plugins yet – to be done.

Removed methods

  • getFilters, setFilter – as there's no Web Audio "backend"
  • drawBuffer – to redraw the waveform, use setOptions instead and pass new rendering options
  • cancelAjax – ajax is replaced by fetch
  • loadBlob – use URL.createObjectURL() to convert a blob to a URL and call load(url) instead
  • skipForward, skipBackward, setPlayEnd – can be implemented using setTime(time)
  • exportPCM is renamed to getDecodedData and doesn't take any params
  • toggleMute 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.

Questions

Have a question about integrating wavesurfer.js on your website? Feel free to ask in our forum: https://github.com/wavesurfer-js/wavesurfer.js/discussions/categories/q-a

Development

To get started with development, follow these steps:

  1. Install dev dependencies:
yarn
  1. 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:

yarn cypress

Feedback

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!