Audio Waveform Image Generator

Note: Ongoing development of this project has moved to https://codeberg.org/chrisn/audiowaveform.

audiowaveform is a C++ command-line application that generates waveform data from either MP3, WAV, FLAC, Ogg Vorbis, or Opus 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 maximum points in the output.

Contents

• Installation
• Building from source
• Usage
• Data Formats
• Credits
• License
• Contributing
• Authors
• Copyright

Installation

Ubuntu

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

Debian

Binary packages for amd64 and arm64 architectures are available on the Releases page.

Download the correct package file for your Debian version, following the examples below.

| Filename | Debian version | | ----------------------------------- | -------------------- | | audiowaveform-1.10.2-1-13.amd64.deb | Debian 13 (trixie) | | audiowaveform-1.10.2-1-12.amd64.deb | Debian 12 (bookworm) | | audiowaveform-1.10.2-1-11.amd64.deb | Debian 11 (bullseye) | | audiowaveform-1.10.2-1-10.amd64.deb | Debian 10 (buster) |

Use these commands to install the package and its dependencies. Replace the version number with the latest release version.

sudo apt-get update
sudo dpkg -i audiowaveform-1.10.2-1-13.amd64.deb
sudo apt-get -f install -y

RHEL, CentOS, AlmaLinux etc

Binary packages are available on the Releases page.

Download the correct RPM for your CentOS version and use these commands to install the RPM package, together with all required dependencies. Replace the version number with the latest release version.

sudo yum install -y epel-release
sudo yum localinstall audiowaveform-1.10.2-1.el8.x86_64.rpm

Arch Linux

There is an audiowaveform package available in the AUR.

Mac OSX

You can install audiowaveform using Homebrew, thanks to Adam Jensen:

brew install audiowaveform

Windows

Windows binaries are available on the Releases page, and are built using compile-static-audiowaveform.

Amazon Linux

A binary package for Amazon Linux 2 is available on the Releases page.

Use these commands to install the RPM package, together with all required dependencies. Replace the version with the latest release version.

sudo amazon-linux-extras install epel
sudo yum install \
  https://github.com/bbc/audiowaveform/releases/download/1.10.1/audiowaveform-1.10.1-1.amzn2.x86_64.rpm

Docker

A Docker image based on Alpine Linux is available here, thanks to @realies.

Example usage:

docker pull realies/audiowaveform
alias awf='docker run --rm -v `pwd`:/tmp -w /tmp realies/audiowaveform'
awf -i input.wav -o output.png

Building from source

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.

Install package dependencies

Fedora

sudo dnf install git make cmake gcc-c++ libmad-devel \
  libid3tag-devel libsndfile-devel gd-devel boost-devel

CentOS 7

Most packages needed to build audiowaveform are already present in CentOS 7, except libmad/libmad-devel, which must be taken from the EPEL repository.

Install the EPEL repository and the libmad-devel package:

sudo yum install -y https://dl.fedoraproject.org/pub/epel/epel-release-latest-7.noarch.rpm
sudo yum install -y --enablerepo=epel libmad-devel

And then install the other build dependencies (other than libmad-devel):

sudo yum install -y redhat-lsb-core rpm-build wget \
  git make cmake gcc-c++ libid3tag-devel libsndfile-devel gd-devel boost-devel

Ubuntu

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.

Alpine

apk add git make cmake gcc g++ libmad-dev \
  libid3tag-dev libsndfile-dev gd-dev boost-dev \
  libgd libpng-dev zlib-dev

Note: for a static build you will need to include the following dependencies

apk add zlib-static libpng-static boost-static

A statically linkable build of FLAC is also required. This is not available in Alpine so you must compile it yourself.

apk add autoconf automake libtool gettext
wget https://github.com/xiph/flac/archive/1.3.3.tar.gz
tar xzf 1.3.3.tar.gz
cd flac-1.3.3
./autogen.sh
./configure --enable-shared=no
make
make install

Arch

sudo pacman -S base-devel boost-libs gd \
  libid3tag libmad libsndfile boost cmake git

SUSE

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.

Mac OSX

Install XCode and Homebrew, then:

brew install cmake libmad libid3tag libsndfile gd
brew install boost --with-c++11

Obtain the source code

git clone git@github.com:bbc/audiowaveform.git
cd audiowaveform

Install Google Test test framework

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.12.1.tar.gz
tar xzf release-1.12.1.tar.gz
ln -s googletest-release-1.12.1 googletest

Build

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++ ..

Test

make test

To see detailed test output:

./audiowaveform_tests

Package

Use the following command on Debian-based systems to build a Debian package:

cpack -G DEB

or this command on Red Hat-based systems to build an RPM package:

cpack -G RPM

The packages can be locally installed (e.g., rpm -ivh *.rpm, dpkg -i *.deb) or installed on another system, as long as the runtime dependencies of the package are present (libmad, libsndfile, libid3tag, gd and boost).

Install

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.

Run

audiowaveform --help

Usage

Command line options

audiowaveform accepts the following command-line options:

--help

Show help message.

--version, -v

Show version information.

--quiet, -q

Disable status messages.

--input-filename, -i <filename>

Input filename, which should be a MP3, WAV, FLAC, Ogg Vorbis, or Opus audio file, or a binary or JSON format waveform data file. By default, audiowaveform uses the file extension to decide how to read the input file (either .mp3, .wav, .flac, .ogg, .oga, .opus, .raw, .dat, or .json as appropriate), but this can be overridden by the --input-format option. If the --input-filename option is - or is omitted, audiowaveform reads from standard input, and the --input-format option must be used to specify the data format.

Note that Opus support requires libsndfile 1.0.29 or later, so may not be available on all systems.

--output-filename, -o <filename>

Output filename, which may be either a WAV audio file, a binary or JSON format waveform data