squiggl

A javascript library to create a squiggly SVG waveform from audio data. Inspired by the podcast player by Megaphone.

Responsive Demo

I decided to split the squiggl functionality into 3 parts (one async, two sync) so that the audio data can be read once, then re-formatted and re-rendered multiple times without too much I/O. This way, the waveform can be re-rendered in response to changing screen widths.

Check it out.

Installation

Via <script> tag (example):

<script src="https://unpkg.com/squiggl/dist/index.js"></script>

Via npm i squiggl:

const squiggl = require('squiggl');
// or
import squiggl from 'squiggl';

Usage

The squiggl object consists of 3 functions:

• extractVolumeData
• formatVolumeData
• createElement

These functions are used in tandem to:

1. Extract the useful bits of data we need from an audio file.
2. Format the data into a shape that we can use.
3. Create an SVG element that is the visualization of the data.

Quick Example

// Step 0.1: Define squiggly SVG element's parent container.
var container = document.querySelector( '#waveform-container' );
// Step 0.2: Define options.
const options = {
  svg: {
    id: 'squigglSvg',
    width: 810,
    height: 60
  },
  path: {
    arcRadius: 2.25, // recommended
    stroke: '#eaeaef',
    strokeWidth: 1.2 // recommended
  }
};

fetch( '/radiolab.mp3' )
  // Step 0.3: Retrieve an audio file.
  .then( res => res.arrayBuffer() )
  // Step 1: Extract the useful bits of data we need.
  .then( audioData => squiggl.extractVolumeData( audioData ) )
  .then( volumeData => {
    // Step 2: Format the data into a shape that we can use.
    const formattedVolumeData = squiggl.formatVolumeData( volumeData, options.svg.width, options.path.arcRadius );
    // Step 3: Create an SVG element that is the visualization of the data.
    const svgElement = squiggl.createElement( formatVolumeData, options );

    container.appendChild( svgElement );
  });

Detailed Explanation

options

squiggl requires you to define certain attributes of its internal <svg> and <path> elements through the options parameter. This allows you to dynamically define certain visual properties of the waveform.

// Example
const options = {
  svg: {
    id: 'squigglSvg',
    width: 810,
    height: 60
  },
  path: {
    arcRadius: 2.25, // recommended
    stroke: '#eaeaef',
    strokeWidth: 1.2 // recommended
  }
};

extractVolumeData( audioData )

Parameter	Type	Description
audioData	ArrayBuffer	This is decoded using the decodeAudioData function from either window.AudioContext or window.webkitAudioContext (whichever is available). We can then call getChannelData(0) from the resulting buffer to pull out the volume data.

Returns
Array of Numbers between -1.0 and 1.0

This function doesn't care where you get your audio data from (HTTP request, file input, etc...) as long as it's compatible with the AudioContext API.

formatVolumeData( volumeData, width, arcRadius )

Parameter	Type	Description
volumeData	Array of Numbers between -1.0 and 1.0	Ideally generated from the extractVolumeData function.
width	Number	The desired width of your SVG. Used to determine how many squiggles to draw.
arcRadius	Number	The radius of each turn in the waveform. Used to determine how many squiggles to draw.

Returns
Array of Numbers between 0.0 and 1.0

This function formats the audio data into a smaller set of numbers that models the number of squiggles in the waveform, and their magnitudes.

createElement( volumeData, options )

Parameter	Type	Description
volumeData	Array of Numbers between 0.0 and 1.0	Ideally generated from the formatVolumeData function.
options	Object	See above.

Returns
An <svg> Element that is ready to be added to the DOM.