Welcome to JustWave Project

Create PNG waveform of audio (mp3/ogg) and use it in Web applications

JustWave tries to make it easy to create and use waveforms of different audios for your Web applications. It can create waveform for any audio (or even video) that ffmpeg can accept but aimed primarily to mp3 and ogg audio for they are most suitable for browsers. To use it you should create an instance of JustWave class and call method create with path or url to an audio as a single parameter. All additional parameters passed through constructor method as a link to external array (POST/GET/ARGV etc. - see below).

JustWave Project consists of several server- and client-side scripts and aimed to create waveforms of audio - ogg/mp3, any - for interactive players as an example.

The main script is server-side script JustWave.class.php. It uses ffmpeg system binary as a back-end for converting audio to WAV (PCM) format in order to create peaks of waveform.

There are two server-side scripts based on it - justwave.ajax.php and justwave.cli.php.

justwave.player.js has been made to create and control waveforms of audio elements for HTML pages and uses justwave.ajax.php server-side script as a back-end for creating PNG-waveforms.


Parameters source can be passed in construction method and is a super-global $_POST array by default. You can use POST, GET, REQUEST, COOKIE, SESSION or ARGV constants. When ARGV constant used you should pass an array with 'option=value' string values as a second parameter (see justwave.cli.php description below).
All possible parameters are described for justwave.ajax.php script.

Usage of this class (PHP native code):

require_once 'JustWave.class.php';

// we accept parameters as GET data
// e.g.: script.php?mode=file&wave_color=F00&prog_color=F00&back_color=0F0
$justwave = new JustWave('GET');
// create waveform image(s)
if($justwave->status == 'ok') {
  echo 'Duration of my_song.mp3 = ' . $justwave->duration . '<br>';
  echo 'See waveform image under the link: <a href="' . $justwave->dataUrlWave . '">waveform</a>';
  echo 'Failed! Message = ' . $justwave->message;

See working script made of this example: working example.

After calling create method following public properties will be initialized:

In file mode there are two PNG waveform images that will be generated in the wavedir directory on the server, $this->md5.png and $this->md5_bg.png. If wave_color = prog_color the image will be only one ($this->md5.png).
$this->dataUrlWave and $this->dataUrlProgress will hold relative links to these waveform PNG images.

In dataurl mode these two properties will hold data-url of PNG images in themselves. If wave_color = prog_color $this->dataUrlProgress will be null.


It accepts POST data from client side (JavaScript) and returns JSON data with waveforms of required audio. You can set colors for foreground and background (progress) waveform and get two separate images of the waveforms differ in colors. If foreground and background colors are the same there will be only one waveform. In this context progress means the progress of playhead during audio playing.

The possible POST data is as following:

KeyDefault valueDescription
audio*REQUIRED*Url or path to the audio file (mp3/ogg or any audio format which ffmpeg understands - and it understands really much if not all). If it is a path look for it is accessible in the working directory of justwave.ajax.php - it is not a problem if your HTML page with mp3/ogg links is in the same directory. If it is a url it will be downloaded to wavedir directory temporarily if it is not found in cache or file system.
mode'dataurl'String 'dataurl' or 'file'. Set returning mode of the images in data-url or link to sources in file system.
wavedir'waves/'Directory in file system for storing waveform images.
Note 1: This directory is also used for temporary files during conversion process and should be writable.
Note 2: On Windows' systems always use '/' in path instead of '\'.
width500Width of waveform image(s) in pixels.
height100Height of waveform image(s) in pixels.
wave_color'#909296'Color of foreground waveform image.
prog_color'#FF530D'Color of background (progress) waveform image.
back_colorColor of background for the waveform image(s). If not set or an empty string - transparent then.

Extra options

force Do not seek for waveform images in file system*.
nocache Do not use caching mechanism (why?)*
twopass Use two pass conversion for normalization*.
If waveforms are in cache or in file system this option does not take effect if you don't use nocache and force options.

*If extra options are not set, default behavior will be used:

If waves are in cache they will be fetched from there.
If waves were created previously in file system (and are in a wavedir directory) they will be fetched from there then.
Otherwise audio will be converted to WAV format temporally (using ffmpeg external binary) and new waveform images will be created.
In file mode these images (or one image if wave_color = prog_color) will be stored in wavedir directory and you get links to them in waveurl and progressurl JSON-parameters, otherwise you get data-url in waveurl and progressurl JSON-parameters and can use it as image sources.
If audio src is a url it will be temporally downloaded and converted as usual audio.

The returning data in JSON format

statusStatus of returning, strings ok or err only. ok means waveforms are ready to be used, err - something went wrong.
messageMessage describing returning result or error cause more specifically.
  • In cache - the waveform data has been fetched from cache.
  • Images exist - waveforms images are located in file system.
  • New wave(s) created - new waveforms has been drawn and are ready.
  • Conversion failed - something went wrong in conversion process.
  • Downloading failed - url could not be downloaded for some reason.
durationDuration of the audio in seconds (fixed value). Some browsers may fail defining real duration parameter for some CBR mp3 and this can somehow help.
keyMD5 key composed from audio url (path) + waveform width and height + colors of waveforms.
nameBase name of the audio
waveurlSrc for main wave (consists either of data-url of PNG-image or a link to external PNG-image location)
progressurlThe same for the progress (second background) wave. For dataurl mode it is defined when wave_color <> prog_color only. In file mode it can be the same as waveurl when these colors are the same.


This script should be used in command-line mode and can generate waveforms for multiple audio sources simultaneously.
Parameters for this script are in a option=value format and are almost the same as for justwave.ajax.php script in its POST data.
Run this script without parameters to see help screen.

$ php justwave.cli.php mask [ options ]

mask - filename or pattern for media, e.g.: song.mp3 or *.ogg

options - optional parameter(s), in option=value format, for example:
$ php justwave.cli.php ../my_mp3_dir/*.mp3 width=450 height=75 wave_color=#3F87BE back_color=#FFFFFF

Possible options are: (shown their default values):
width=500 - width of the wave image (in pixels).
height=100 - height of the wave image (in pixels).
wave_color=#909296 - color of foreground wave in #RRGGBB format.
back_color= - color of background in #RRGGBB format.
If not set or is empty - transparent then.
wavedir=waves - directory in file system for storing waveform image(s).
Note 1: This directory is also used for temporary files
during conversion process and should be writable.
Note 2: On Windows' systems always use '/' in path instead of '\'.

Extra options:
force=1 - do not seek for wave image in file system.
nocache=1 - do not use caching mechanism (why?)
twopass=1 - use two pass conversion for normalization.

(c) beotiger Andrey Tzar 2015 AD http://justwave.beotiger.com https://github.com/beotiger email: beotiger@gmail.com Yandex.Metrica