Waveform.js makes drawing SoundCloud waveforms simple and lets you style and color them the way you want it. It comes as a small JavaScript library and is using a lightweight service hosted on waveformjs.org that translates the waveform images provided by SoundCloud into floating points.

"Damn Good Waveforms" (Eric Wahlforss, CTO of SoundCloud, 2nd of July 2013)

The project is open source and hosted on Github. This page provides all the documentation you'll need as well as a list of examples. Waveform.js is available to use under the MIT software license. It was written by Johannes Wagener and Lee Martin. You can report bugs and discuss features on the Github issues page.

Download Latest Version (1.0.0)


Start by adding the waveform.js script to your page or app:

<script src="waveform.js"></script>

Once added you can create new waveforms using the Waveform prototype:

var waveform = new Waveform({
  container: document.getElementById("test"),
  data: [1, 0.2, 0.5]

The following options can be passed, except for container all others are optional:

html element that will contain the new canvas element.
width in pixel, if not passed will be calculated from the container
height in pixel, if not passed will be calculated from the container
color of the waveform. can be a hex triplet string, a canvas gradient or a function that returns one of these.
color of the outer area. can be a hex triplet string or a canvas gradient.
interpolated waveforms will be stretched to the full width, non interpolated will be drawn in one pixel lines per sample and cut off on the left end.


With the update method the data can be updated and the waveform redrawn, it also accepts the interpolate option.

  data: [0.5, 1.0, 0.5, 1.0]


The dataFromSoundCloudTrack method accepts a SoundCloud track object (containing the waveform_url) and will call the waveformjs.org endpoint to retrieve and set the data samples.


The optionsForSyncedStream method returns an options object that can be passed to soundManager or the SoundCloud JS SDK SC.stream method. These options will automatically sync and redraw the waveform according to its stream loading and playing progress. The options will only include the whileplaying and whileloading option, all others can be overridden.

SoundCloud Waveform Endpoint

The endpoint is located at http://waveformjs.org/w and accepts a url parameter that is pointing to a SoundCloud waveform image URL (waveform_url in the track object). The response will be an array of floats between 0 and 1. JSONP is supported.


Hooking up a waveform to a SoundCloud track

Using the dataFromSoundCloudTrack the data of the waveform will be pulled from the endpoint on waveform.js.org that converts the SoundCloud waveform image into the floats. Additionally optionsForSyncedStream will prepare options for SC.stream that will sync up the loading and playing progress of the stream with the waveform. Click here to test playback!

Drawing a waveform with a gradient on the fly

When the interpolate option is false, each data sample will be drawn on one pixel. Once the full width has been exceeded the older data will be cut off. This can be used to draw waveforms when sounds are recorded with the SoundCloud Javascript SDK. In addition this waveform is styled using a canvas gradient as innerColor.

Weird customized waveform with random colors

In this example the data is set manually to just a few samples, which will be interpolated to the full width. The innerColor is a function that gets called for each vertical line and will return a random color.