audiowaveform is a C++ command-line application that generates waveform data from either MP3, WAV, FLAC, or Ogg Vorbis format audio files. Waveform data can be used to produce a visual rendering of the audio, similar in appearance to audio editing applications.
Waveform data files are saved in either binary format (.dat) or JSON (.json). Given an input waveform data file, audiowaveform can also render the audio waveform as a PNG image at a given time offset and zoom level.
The waveform data is produced from an input audio signal by first combining the
input channels to produce a mono signal. The next stage is to compute the
minimum and maximum sample values over groups of N input samples (where N is
controlled by the --zoom command-line option), such that each N input
samples produces one pair of minimum and maxmimum points in the output.
Binary packages are available on Ubuntu Launchpad here.
$ sudo add-apt-repository ppa:chris-needham/ppa
$ sudo apt-get update
$ sudo apt-get install audiowaveform
There is an audiowaveform package available in the AUR.
To install audiowaveform using Homebrew:
$ brew tap bbc/audiowaveform
$ brew install audiowaveform
Windows binaries are not currently available. Please follow this issue for details.
audiowaveform requires cmake 2.8.7 or later, g++ 4.6.3 or later, and Boost 1.46.0 or later.
The software has been developed on Ubuntu 12.04 and Fedora 18. Due to compiler and library version requirements, the software may not build on earlier operating system releases.
$ sudo dnf install git make cmake gcc-c++ libmad-devel \
libid3tag-devel libsndfile-devel gd-devel boost-devel
If you have not already done so, you should follow the instructions here to add the RPM Fusion free repository. For example, for CentOS 7:
$ sudo yum localinstall --nogpgcheck \
https://download1.rpmfusion.org/free/el/rpmfusion-free-release-7.noarch.rpm
and then install the dependencies:
$ sudo yum install git make cmake gcc-c++ libmad-devel \
libid3tag-devel libsndfile-devel gd-devel boost-devel
$ sudo apt-get install git make cmake gcc g++ libmad0-dev \
libid3tag0-dev libsndfile1-dev libgd-dev libboost-filesystem-dev \
libboost-program-options-dev \
libboost-regex-dev
Note: for Ubuntu 12.04, replace libgd-dev with libgd2-xpm-dev.
$ apk add git make cmake gcc g++ libmad-dev \
libid3tag-dev libsndfile-dev gd-dev boost-dev
$ sudo pacman -S base-devel boost-libs gd \
libid3tag libmad libsndfile boost cmake git
$ zypper install git cmake gcc-c++ libmad-devel \
libid3tag-devel libsndfile-devel gd-devel \
libboost_filesystem1_67_0-devel \
libboost_program_options1_67_0-devel \
libboost_regex1_67_0-devel
Note: replace 1_67_0 with the boost version actually available.
Install XCode and Homebrew, then:
$ brew install cmake libmad libid3tag libsndfile gd
$ brew install boost --with-c++11
$ git clone https://github.com/bbc/audiowaveform.git
$ cd audiowaveform
audiowaveform uses Google Test for unit testing. Following this advice in the Google Test FAQ, download the source and unzip:
$ wget https://github.com/google/googletest/archive/release-1.10.0.tar.gz
$ tar xzf release-1.10.0.tar.gz
$ ln -s googletest-release-1.10.0/googletest googletest
$ ln -s googletest-release-1.10.0/googlemock googlemock
$ mkdir build
$ cd build
$ cmake ..
$ make
The default build type is Release. To build in Debug mode add
-D CMAKE_BUILD_TYPE=Debug to the cmake command above:
$ cmake -D CMAKE_BUILD_TYPE=Debug ..
If you don't want to compile the unit tests add -D ENABLE_TESTS=0:
$ cmake -D ENABLE_TESTS=0 ..
To statically link the library dependencies add -D BUILD_STATIC=1, for example:
$ cmake -D BUILD_STATIC=1 ..
To compile with clang instead of g++:
$ cmake -D CMAKE_C_COMPILER=/usr/local/bin/clang -D CMAKE_CXX_COMPILER=/usr/local/bin/clang++ ..
$ make test
To see detailed test output:
$ ./audiowaveform_tests
$ sudo make install
By default this installs the audiowaveform program in /usr/local/bin, and
man pages in /usr/local/share/man. To change these locations, add a -D CMAKE_INSTALL_PREFIX=... option when invoking cmake above.
$ audiowaveform --help
audiowaveform accepts the following command-line options:
| Short | Long | Description |
|---|---|---|
--help |
Show help message | |
-v |
--version |
Show version information |
-i <filename> |
--input-filename <filename> |
Input audio (.wav, .flac, .mp3, or .ogg) or waveform data (.dat) file name |
-o <filename> |
--output-filename <filename> |
Output waveform data (.dat or .json), audio (.wav), or PNG image (.png) file name |
--input-format <format> |
Input file format (wav, flac, mp3, ogg, or dat) | |
--output-format <format> |
Output file format (dat, json, wav, or png) | |
-z <level> |
--zoom <zoom> |
Zoom level (samples per pixel), default: 256. Not valid if --end or --pixels-per-second is also specified |
--pixels-per-second <zoom> |
Zoom level (pixels per second), default: 100. Not valid if --end or --zoom is also specified |
|
-b <bits> |
--bits <bits> |
Number of bits resolution when creating a waveform data file (either 8 or 16), default: 16 |
--split-channels |
Output files are multi-channel, not combined into a single waveform | |
-s <seconds> |
--start <seconds> |
Start time (seconds), default: 0 |
-e <seconds> |
--end <seconds> |
End time (seconds). Not valid if --zoom is also specified |
-w <width> |
--width <width> |
Width of output image (pixels), default: 800 |
-h <height> |
--height <height> |
Height of output image (pixels), default: 250 |
-c <scheme> |
--colors <scheme> |
Color scheme of output image (either 'audition' or 'audacity'), default: audacity |
--border-color <color> |
Border color (in rrggbb[aa] hex format), default: set by --colors option |
|
--background-color <color> |
Background color (in rrggbb[aa] hex format), default: set by --colors option |
|
--waveform-color <color> |
Waveform color (in rrggbb[aa] hex format), default: set by --colors option |
|
--axis-label-color <color> |
Axis label color (in rrggbb[aa] hex format), default: set by --colors option |
|
--no-axis-labels |
Render PNG images without axis labels | |
--with-axis-labels |
Render PNG images with axis labels (default) | |
--amplitude-scale <scale> |
Amplitude scale (number or auto), default: 1 |
|
--compression <level> |
PNG compression level: 0 (none) to 9 (best), or -1 (default) |
In general, you should use audiowaveform to create waveform data files (.dat) from input MP3 or WAV audio files, then create waveform images from the waveform data files.
For example, to create a waveform data file from an MP3 file, at 256 samples per point with 8-bit resolution:
$ audiowaveform -i test.mp3 -o test.dat -z 256 -b 8
Then, to create a PNG image of a waveform, either specify the zoom level, in samples per pixel. Note that it is not possible to set a zoom level less than that used to create the original waveform data file.
$ audiowaveform -i test.dat -o test.png -z 512
The following command creates a 1000x200 pixel PNG image from a waveform data file, at 50 pixels per second, starting at 5.0 seconds from the start of the audio:
$ audiowaveform -i test.dat -o test.png --pixels-per-second 50 -s 5.0 -w 1000 -h 200
This command creates a 1000x200 pixel PNG image from a waveform data file, showing the region from 45.0 seconds to 60.0 seconds from the start of the audio:
$ audiowaveform -i test.dat -o test.png -s 45.0 -e 60.0 -w 1000 -h 200
You can use the --split-channels option to create a waveform data file
containing multiple channels, rather than combining all channels into a single
waveform:
$ audiowaveform -i test.mp3 -o test.dat -z 256 -b 8 --split-channels
It is also possible to create PNG images directly from either MP3 or WAV files, although if you want to render multiple images from the same audio file, it's generally preferable to first create a waveform data (.dat) file, and create the images from that, as decoding long MP3 files can take significant time.
The following command creates a 1000x200 PNG image directly from a WAV file, at 300 samples per pixel, starting at 60.0 seconds from the start of the audio:
$ audiowaveform -i test.wav -o test.png -z 300 -s 60.0 -w 1000 -h 200
If you are using audiowaveform to generate waveform data for use in a web application, e.g, using Peaks.js, you can choose whether to use binary or JSON format waveform data.
The following command generates waveform data in JSON format:
$ audiowaveform -i test.flac -o test.json -z 256 -b 8
The following command converts a waveform data file (.dat) to JSON format:
$ audiowaveform -i test.dat -o test.json
In addition, audiowaveform can also be used to convert MP3 to WAV format audio:
$ audiowaveform -i test.mp3 -o test.wav
You can use the --input-format and --output-format options to read from
standard input and write to standard output. For example, the following command
generates a waveform data file by converting a video file using ffmpeg:
$ ffmpeg -i test.mp4 -f wav - | audiowaveform --input-format wav --output-format dat -b 8 > test.dat
Note: Piping audio into audiowaveform is currently only supported for MP3 and WAV format audio, and not FLAC or Ogg Vorbis.
You can find details of the waveform data file formats produced by audiowaveform here.
This program contains code from the following open-source projects, used under the terms of these projects' respective licenses:
See COPYING for details.
If you have a feature request or want to report a bug, we'd be happy to hear from you. Please either raise an issue, or fork the project and send us a pull request.
This software was written by Chris Needham, chris.needham at bbc.co.uk.
Copyright 2013-2019 British Broadcasting Corporation