Wavesurfer. js is a customizable Audio waveform visualization component based on Web Audio API and HTML5 Canvas, which is widely used in the scene of Audio waveform display and Audio waveform interaction. After practice, this paper has done a sorting work through the translation of official documents and my own understanding (there will be detailed articles related to specific practice next).

1. Application scenarios

In some scenarios where audio waveform display and interaction are required, for example:

Supports audio waveform display

• You can select the waveform and fill in the label information
• Optionally modify or drag to select the waveform range
• Support marking data reverse rendering waveform, and can modify the marking data

After investigation, wavesurfer.js is a very wide range of applications and powerful, flexible customization of audio waveform visualization components, can fully meet the needs of our audio marking components.

2. Wavesurfer. Js

1. Script tag introduction:

<script src="https://unpkg.com/wavesurfer.js"></script>

2. In general, we recommend the introduction of NPM:

npm install wavesurfer.js 
Copy the code

The import code:

import WaveSurfer from 'wavesurfer.js' 
// Create wavesurfer instance

var wavesurfer = WaveSurfer.create({
    container: '#waveform'.scrollParent: true
});
Copy the code

3. Wavesurfer is introduced

Wavesurfer consists of some Options, instance Methods, Events and Plugins for instance creation. Understand these three basically can be regarded as a complete grasp of wavesurfer, can realize the basic needs of audio waveform display and interaction.

3.1 options

Wavesurfer: wavesurfer: wavesurfer: wavesurfer: wavesurfer: wavesurfer: wavesurfer: wavesurfer: wavesurfer

var wavesurfer = WaveSurfer.create({ 
     container: this.$refs.wavesurfer,
     progressColor: '#fff'.backend: 'MediaElement'.waveColor: '# 666'.height: 80.width: 400.normalize: true.mediaControls: true.preload: true. })Copy the code

The options are as follows:

option	type	default	description
audioRate	float	1	Audio playback speed, the lower the value, the slower
audioContext	object	none	Its own audio context, analogous to a Canvas context, contains columns
audioScriptProcessor	object	none	Using your own previously initialized ScriptProcessorNode is custom javaScript to generate, process, or analyze audio
autoCenter	boolean	true	If there is a scroll bar, center the waveform according to progress
backend	string	WebAudio	Optional WebAudio, MediaElement or MediaElementWebAudio.
backgroundColor	string	none	The background color of the waveform container
barGap	number	none	Waveform bar spacing, if not provided will be calculated automatically
barHeight	number	1	Height of the waveform bar. A number greater than 1 increases the height of the waveform bar
barMinHeight	number	null	Minimum height for drawing a waveform bar. By default, no waveform bar is drawn during the mute period
barRadius	number	0	Radius of waveform bar
barWidth	number	none	If specified, the waveform will be shown as follows
closeAudioContext	boolean	false	When you call the destroy method, close and cancel all audio contexts
container	mixed	none	Audio waveform container CSS selector or HTML element, which is the only required parameter
cursorColor	string	# 333	The fill color of the cursor indicating the position of the playback header
cursorWidth	integer	1	Cursor width, unit: Pixels
drawingContextAttributes	object	{desynchronized: true}	Specifies the Canvas 2D drawing context property
fillParent	boolean	true	Whether to fill the entire container or just draw according to minPxPerSec
forceDecode	boolean	false	Whether to use Web Audio to force decode audio when zooming to get a more detailed waveform
height	integer	128	The height of the waveform, in pixels
hideScrollbar	boolean	false	Whether to hide the horizontal scroll bar
interact	boolean	true	Whether to enable mouse interaction during initialization. You can then switch this parameter at any time
loopSelection	boolean	true	(used with the zone plug-in) enables a loop for the selected zone
maxCanvasWidth	integer	4000	The maximum width (in pixels) of a single canvas, excluding small overlaps (2 * pixelRatio, rounded to the next even integer). If the waveform length is greater than this value, the waveform will be rendered with another canvas. This is useful for very large waveforms that are too large for browsers to draw on a single canvas. The sub-parameter is used for MultiCanvas rendering
mediaControls	boolean	false	True (used with MediaElement) launches the native control for the MediaElement
mediaType	string	audio	Use ‘audio’ or ‘video’ with MediaElement
minPxPerSec	integer	50	Minimum number of audio pixels per second
normalize	boolean	false	If true, the maximum peak is normalized instead of 1.0
partialRender	boolean	false	Use PeakCache to improve rendering speed of large waveforms.
pixelRatio	integer	window.devicePixelRatio	Can be set to 1 to speed up rendering
plugins	array	[]	A set of plug-in definitions to be registered during instantiation. They will be initialized directly unless the deferInit property is set to true
progressColor	string	# 555	The fill color of the waveform section following the cursor. Progress waves are not rendered at all when progressColor is the same as waveColor.
regionsMinLength	number	null	The default minLength for the region is in seconds. When creating a region, specifying minLength for the region overrides this parameter
removeMediaElementOnDestroy	boolean	true	False preserves the media element in the DOM when the player is destroyed. This feature is useful when reusing existing media elements through the loadMediaElement method
renderer	Object	MultiCanvas	Can be used to inject custom renderers.
responsive	boolean or float	false	If true, adjust the waveform size when adjusting the window size. By default, the waveform size will be shaken every 100ms. If this parameter is passed in as a number, it indicates the time and frequency of shaking
scrollParent	boolean	false	Whether to roll the container with a longer waveform, otherwise the waveform will shrink to the width of the container (see fillParent).
skipLength	float	2	Number of seconds skipped using the skipForward() and skipBackward() methods.
splitChannels	boolean	false	Use separate waveform rendering for different channels of audio
splitChannelsOptions	object	{}	Option to separate audio channels. Only valid if splitChannels=true. See the options below.
splitChannelsOptions.overlay	boolean	false	Overlay channel waveforms instead of rendering them on separate lines
splitChannelsOptions.relativeNormalization	boolean	false	Normalization preserves the ratio between channels and only applies if Normalize = True
splitChannelsOptions.filterChannels	array	[]	List of channel numbers excluded from the rendered waveform. The channel index starts at 0
splitChannelsOptions.channelColors	object	{}	Overriding the color of each channel, each key indicates a channel number, and the corresponding value is an object that describes its color characteristics. For example: channelColors={0: {progressColor: ‘green’, waveColor: ‘pink’}, 1: {progressColor: ‘orange’, waveColor: ‘purple’ } }
waveColor	string	# 999	Fill color of waveform after cursor.
xhr	Object	{}	For example, let XHR = {cache: ‘default’, mode: ‘cors’, method: ‘GET’, credentials: ‘same-origin’, redirect: ‘follow’, referrer: ‘client’, headers: [ { key: ‘Authorization’, value: ‘my-token’ } ]}; (Because the resolution of audio waveform is to send asynchronous request, so there may be some network request problems need to be set, this option can be used)

3.2 methods

After creating the Wavesurfer instance, you can invoke these methods from the created instance. All methods, their meanings and usage are summarized below.

• CancelAjax () – Cancels the audio file loading process.
• Destroy () – Removes events, elements, and disconnects Web Audio nodes.
• Empty () – Clears the waveform.
• GetActivePlugins () – Returns the map of the currently initialized plug-in.
• GetBackgroundColor () – Returns the background color of the waveform container.
• GetCurrentTime () – Returns the current progress in seconds.
• GetCursorColor () – Returns the cursor fill color indicating the position of the playback header.
• GetDuration () – Returns the duration of the audio.
• GetPlaybackRate () – Returns the playback speed of the audio clip.
• GetProgressColor () – Returns the fill color of the waveform behind the cursor.
• GetVolume () – Returns the volume of the current audio segment.
• GetMute () – Returns the current mute state.
• GetFilters () – Returns the array of filters currently set.
• GetWaveColor () – Returns the waveform fill color behind the cursor.
• ExportPCM (Length, accuracy, noWindow, start) – Exports PCM data as a JSON array. Parameters: length [number] – default: 1024, accuracy [number] – the default: 10000, noWindow (true | false] – the default: false, start [number] – default: 0
• ExportImage (format, quality, Type) – Returns images of waveforms in data URI or Blob format.
• IsPlaying () – Returns whether it is currently playing.
• Load (URL, peaks, preload) — Load audio urls via XHR. Optional parameters: peak peaks array, preload [none | metadata | auto], if you use a MediaElement will be passed on to the Audio element.
• LoadBlob (URL) – Loads audio through Blob or File objects.
• On (eventName, callback) – Event listener. Refer to WaveSurfer Events for a list of all Events.
• UN (eventName, callback) – Cancels event listening.
• UnAll () – Cancel all event listening.
• Pause () – Pauses.
• Play ([start[, end]]) – Plays from the current position. Optional start and end in seconds can be used to set the audio range to play.
• PlayPause () – Plays if it is paused and pauses if it is playing.
• SeekAndCenter (Progress) — Progress jump and center The current progress is trying to center (0 = beginning, 1 = end).
• SeekTo (Progress) — Progress jump (0 = beginning, 1 = end).
• SetBackgroundColor (color) – Sets the background color of the waveform container.
• SetCursorColor (color) – Sets the background color for the cursor to play.
• SetHeight (height) – Sets the waveform height.
• SetFilter (filters) – Inserts your own WebAudio node into the graph. See Connecting Filters for details.
• SetPlaybackRate (rate) – Sets the playback speed (0.5 half speed, 1 normal speed, 2 times speed and so on).
• SetPlayEnd (Position) – Sets the pause point for playback in seconds.
• SetVolume (newVolume) – Sets the playback volume [0..1] (0 mute, 1 maximum volume).
• SetMute (mute) – To mute the current sound, Boolean true or false.
• SetProgressColor (color) – Sets the fill color of the waveform before the cursor.
• SetWaveColor (color) – Sets the fill color of the waveform behind the cursor.
• Skip (offset) – to skip a few seconds from the current position (move after using negative images)
• SkipBackward () – The number of skipLength seconds rewind skipLength skipped.
• SkipForward () – Number of skipLength seconds skipped forward.
• SetSinkId (deviceId) – Sets the receiver ID to change the audio output device.
• Stop () – Pause and return to the starting point.
• ToggleMute () — Toggle the sound switch.
• ToggleInteraction () — Toggle mouse interaction switches.
• ToggleScroll () — Toggles scrollParent.
• Zoom (pxPerSec) — Zooms in or out the waveform horizontally in horizontal pixels of audio per second. Setting this changes the minPxPerSec parameter and enables the scrollParent option

3.3 event

Wavesufer also provides many events for us to use flexibly in different scenarios. Events are subscribed and unsubscribed via on() and UN ()

Wavesurfer. On (‘ pause ‘, function () {wavesurfer. Params. Container. Style. The opacity = 0.9; });

Wavesufer all events are as follows:

• Audioprocess – Listens for audio progress and is also triggered when seeking is continuously started while audio is playing.
• Dblclick – Triggered when the instance is double-clicked.
• Destroy – Triggered when the instance is destroyed.
• Error – Error listening, triggered when an error occurs. The callback returns a string error message. .
• Finish – Fires when playback is complete.
• Interaction – Triggered when interacting with the waveform.
• Loading – Constantly triggered when fetch, drag, or drop is used. The callback will receive a percentage of the load (integer) progress [0..100].
• Mute: Triggered when the mute status changes. The callback receives the new mute state.
• Pause – Triggered when audio is paused.
• Play – Triggered when playing starts.
• Ready – Triggered when the audio is loaded and the waveform is decoded and drawn. Triggered before waveform drawing when using MediaElement, refer to detection-ready.
• Scroll – Triggered when the roller bar moves, the callback receives a ScrollEvent object.
• Seek – triggered when seeking. The callback receives the (floating point) progress [0..1].
• Volume – Triggered when the volume changes. Callback receives (integer) new volume value.
• Detection-ready – triggered after drawing the waveform when using MediaElement; If you’re using WebAudio, you can use ready listeners.
• Zoom — Triggered when the waveform is scaled. The callback function will receive an (integer) minPxPerSec value.

 

3.4 plug-in

In fact, you can use wavesurfer flexibly to generate audio waveform. In order to better user experience Wavesurfer also provides a lot of plug-ins to meet different needs, such as regional selection, timeline and so on. Here are some commonly used plug-ins: Regions, Timeline, Minimap, and Cursor

If you want to use a plug-in, you first need to import the plug-in, which is as follows

# HTML global introduction <script SRC ="https://unpkg.com/wavesurfer.js"></script>
<script src="https://unpkg.com/wavesurfer.js/dist/plugin/wavesurfer.minimap.min.js"></script>#js dynamic introductionimport MinimapPlugin from 'wavesurfer.js/dist/plugin/wavesurfer.minimap.min'
import CursorPlugin from 'wavesurfer.js/dist/plugin/wavesurfer.cursor.min'
import RegionsPlugin from 'wavesurfer.js/dist/plugin/wavesurfer.regions.min'
import TimelinePlugin from 'wavesurfer.js/dist/plugin/wavesurfer.timeline.min'
Copy the code

And when creating WaveSurfer instance, you need to introduce the plugins configuration. Plugins are configured in the plugins parameter after being introduced. As follows:

var wavesurfer = WaveSurfer.create({
    container: '#waveform'.plugins: [
        WaveSurfer.regions.create({})
        // timelineplugin.create ({}]});Copy the code

3.4.1 track Regions plug-in

The Regions plugin identifies the segment for looping by placing a layer on top of the waveform, which can be dragged or resized. Get a feel for the official examples

Regions-demo

3.4.1.1 Methods to add directly to WaveSurfer instances

Regions provides several methods directly appended to the WaveSurfer instance (i.e. methods that can be called directly from the WaveSurfer instance) :

AddRegion (options) – Creates a Region on the waveform and returns a Region object. The properties of the Region object refer to the following Region options, Region methods, and Region events. (note: You cannot add a region fragment until the audio is loaded, otherwise the start and end properties of the new fragment will be set to 0, Or an unexpected value) clearRegions() – removes all region fragments. EnableDragSelection (options) – Allows waveform regions to be selected by mouse while creating region fragments. Options Refer to the Regions options configuration below. Note: The wavesurfer.regions. List command is used to obtain the list of all regions.

After creating an instance of Wavesurfer containing Regions, you can call the above methods directly based on the wavesurfer instance, as shown in the following example:

var wavesurfer = WaveSurfer.create({
    container: '#waveform'.plugins: [
        WaveSurfer.regions.create({...regionsOptions})
    ]
});
/ / create region
const curRegion = wavesurfer.addRegion({
 start: 10.end: 20.loop: false.drag: false.resize: false.color: 'RGB (217, 184, 241, 0.8)'
 })
Copy the code

3.4.1.2 Options Options

The Region object has the following options. You can use these options when creating a Region instance:

option	type	default	description
id	string	random	Region INDICATES the REGION ID
start	float	0	Start time of region (seconds)
end	float	0	End time of region (s)
loop	boolean	false	Whether to loop region.
drag	boolean	true	Whether dragging regions is allowed.
resize	boolean	true	Whether the area size can be adjusted.
color	string	“Rgba (0, 0, 0, 0.1)”	The color value of the region.
minLength	number	null	The minimum length of the region in seconds.
maxLength	number	null	The maximum length of the region in seconds.

3.4.1.3 Region Instance Methods

Method of the Region instance created by addRegion.

• Play () – Play Region once from start to finish.
• PlayLoop () – Plays the region in a loop.
• Remove () – Removes the region.
• OnDrag (timeInSeconds) – Adds the timeInSeconds value to the start and end parameters.
• OnResize (timeInSeconds, ‘start’) – Adds timeInSeconds to the end argument by default. The optional ‘start’ argument will add timeInSeconds to start.

3.4.1.4 event

Each region object has the following events:

General events:

• In – When playing into the zone.
• Out – When playing leaves the area.
• Remove – Triggered before the region is removed.
• Update – When the options of the field are updated.
• Update-end – After completion of the dragging or resizing.

Mouse events:

• Click – When the mouse clicks on the area. The callback will receive a mouse event.
• Dblclick – Triggered when a region is double-clicked. The callback will receive a mouse event.
• Over – Triggered when the mouse moves over the area. The callback will receive a mouse event.
• Leave – Triggered when the mouse leaves the area. The callback will receive a mouse event.

WaveSurfer events:

The WaveSurfer instance also fires a set of matching events (passing region objects) :

• region-created
• region-updated
• region-update-end
• region-removed
• region-play
• region-in
• region-out
• region-mouseenter
• region-mouseleave
• region-click
• region-dblclick

 

3.4.2 Timeline plug-in

Timeline is to add a Timeline to wavesurfer

As shown in figure:

Example:Timeline-demo

With the introduction of Regions plug-in, Wavesurfer instance creation needs to introduce the plug-in, the basic usage is as follows:

var wavesurfer = WaveSurfer.create({
    container: '#waveform'.plugins: [
        WaveSurfer.timeline.create({
              container: "#wave-timeline"]}}));Copy the code

Timeline options:

• Container – Must pass – The element that places the timeline, or the CSS selector used to find it
• Height – The height of the timeline, in pixels. The default value is 20.
• NotchPercentHeight – The height (in percentage) of the secondary notch line in the timeline. The default value is 90.
• PrimaryColor – The colour of the die’s ten notched lines (e.g. 10 seconds, 20 seconds). The default value is #000.
• SecondaryColor – The color of the ten notches in the die. The default is ‘#c0c0c0’.
• PrimaryFontColor – Label colour next to the main notch (e.g. 10 seconds, 20 seconds). The default value is #000.
• SecondaryFontColor – The label color next to the secondary notch (e.g. 5 seconds, 15 seconds). The default value is #c0c0c0.
• timeInterval -number of intervals that records consists of. Usually it is equal to – the duration in minutes. (Integer Or function which receives pxPerSec value and reurns value
• primaryLabelInterval – number of primary time labels. (Integer or function which – receives pxPerSec value and reurns value)
• secondaryLabelInterval – number of secondary time labels (Time labels between primary labels, Integer or function which receives pxPerSec value and reurns value).
• FormatTimeCallback – Custom time format callback. (Function that receives the number of seconds and returns a formatted string)
• Offset – The offset (in seconds) from the start of the time axis. The value can also be negative, and the default is 0.

Rule 3.4.3 Minimap plug-in

Add a thumbnail representation of the entire audio waveform as shown in the figure below, which can be felt through the example minimap-demo.

The introduction is as follows:

var wavesurfer = WaveSurfer.create({
    // your options here
    plugins: [
        WaveSurfer.minimap.create({
            container: '#wave-minimap'.// Thumbnail container ID
            waveColor: '# 777'.// Thumbnail waveform color
            progressColor: '# 222'.// The color of the played waveform
            height: 50    // Thumbnail height]}}));Copy the code

3.4.4 Cursor plug-in

As shown in the figure below, the Cursor plug-in is mainly used for wavesurfer to increase the display of mouse position hovering time as shown in the figure below: you can see that the specific time of the current position is displayed on the right side of the mouse, accurate to the number of milliseconds. You can also feel the actual cursor-demo

Specific usage is as follows:

let wavesurfer = WaveSurfer.create({
    container: document.querySelector('#waveform'),
    plugins: [
        WaveSurfer.cursor.create({
            showTime: true.// Whether to display the time
            opacity: 1.// Cursor and time transparency of the entire component
            customShowTimeStyle: {  // Time display Settings
                'background-color': '# 000'.// Time display block background color
                color: '#fff'.// Time displays the color of the text
                padding: '2px'.// Time display block padding
                'font-size': '10px'  // Time display text font size}})});Copy the code

In addition to some of the above commonly used plug-ins, Wavesurfer also has some other plug-ins, if you need to refer to wavesurfer-js.org/plugins/

Article reference: wavesurfer-js.org/