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:

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:

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/