Setting up Waveform Audio Player

Setup instructions

Download the latest release and unpack it. The files you want are in the release folder. Copy waveform-player.js into your project and include it in an HTML page with <script src="waveform-player.js" defer></script> (the defer attribute isn't required, but it will slightly improve page load time).

To provide SEO-friendliness, the specification for a Waveform player instance is just HTML. Here's an example that demonstrated pretty much all of Waveform's features:

<div id="first-player" class="waveform-player">
  <ul>
    <li><a href="../demo-audio/freesound-valdrag-401693.mp3" data-peaks="[base64 encoded peak data]">Track 1 name</a></li>
    <li><a href="../demo-audio/freesound-valdrag-401693.mp3" data-peaks="[base64 encoded peak data]">Track 1 name</a>
      <div>Optional description. Any HTML is valid here.</div>
    </li>
    <li><a href="../demo-audio/freesound-valdrag-401693.mp3" data-peaks="[base64 encoded peak data]">Track 1 name</a>
      <div>
        <p>Descriptions can have subsections. </p>
        <p class="subsection">0:00 to 0:10 Opening part</p>
        <p class="subsection">0:25 to 0:28 The best bit!</p>
        <p class="subsection">0:33 Closing shot</p>
      </div>
    </li>
  </ul>
</div>

After the page HTML finishes downloading, players are located by searching for the class="waveform-player" element. The internal structure is important:

• <div class="waveform-player"> This identifies a player. To view what the player will look like with JavaScript disabled or in old browsers, make this <div class="waveform-player" data-disable-waveform-player>
• <ul> The only child of the div must be a list
• <li><a The first anchor tag in each list item identifies the track. It should have the following attributes:
  • href="file.mp3" URL of the file to play - MP3 is the best cross-browser compatible sound format
  • data-peaks="..." base64-encoded peak data. See "Generating peak data" below for how to produce this
  • >track name</a> Friendly name for the track.
• <div> Each list item can optionally contain a div with a track description
• <p class="subsection">1:23 ...</p> Track descriptions can contain subsection paragraphs. Each subsection paragraph must start with a timestamp as minutes:seconds or a range as minutes:seconds to minutes:seconds.

If you programmatically add a new player to the DOM after the page has loaded, you can cause it to be picked up by calling the global initialiseWaveformPlayers() function.

Generating peak data

The peak data is a series of bytes, where 0 = the lowest peak height and 255 is the highest. These bytes are base64 encoded It's only necessary to have as many samples as your player is pixels wide.

I've created a handy utility to parse an audio file and generate peak data for you.

Theming

Theming is done with LESS. The player style file, waveform-player.less, has a few variables at the top that let you change key colours, or you can edit the file to your requirements.

Install LESS (install node.js then npm install -g less) modify waveform-player.less then compile it to CSS.