bbc/audiowaveform
On GitHub, bbc/audiowaveform has picked up 2.2k stars, Backend, C++. C++ program to generate waveform data and render waveform images from audio files
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
Snapshot
Top contributors
Show top contributors
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 [email protected]: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 file, or a PNG image file. By default, audiowaveform
uses the file extension to decide the kind of output to generate
(either .wav, .dat, .json, or .png, as appropriate), but this can be overridden
by the --output-format option. If the --output-filename option is
- or is omitted, audiowaveform writes to standard output, and the
--output-format option must be used to specify the data format.
--input-format <format>
Input data format, either wav, mp3, flac, ogg, opus, .raw, dat, or
json. This option must be used when reading from standard input. It may also be
used to set the input file format, instead of it being determined from the file
extension from the --input-filename option.
--output-format <format>
Output data format, either wav, dat, json, or png. This
option must be used when writing to standard output. It may also be used to set
the output file format, instead of it being determined from the file extension
from the --output-filename option.
--zoom, -z <zoom> (default: 256)
When creating a waveform data file or image, specifies the number of input
samples to use to generate each output waveform data point.
Note: this option cannot be used if either the --pixels-per-second or
--end option is specified. When creating a PNG image file, a value of
auto scales the waveform automatically to fit the image width.
--pixels-per-second <zoom> (default: 100)
When creating a waveform data file or image, specifies the number of output
waveform data points to generate for each second of audio input.
Note: this option cannot be used if either the --zoom or --end
option is specified.
--bits, -b <bits> (default: 16)
When creating a waveform data file, specifies the number of data bits to use for output waveform data points. Valid values are either 8 or 16.
--split-channels
Output files are multi-channel, not combined into a single waveform.
--start, -s <start> (default: 0)
When creating a waveform image, specifies the start time, in seconds.
--end, -e <end> (default: 0)
When creating a waveform image, specifies the end time, in seconds.
Note: this option cannot be used if the --zoom option is specified.
--width, -w <width> (default: 800)
When creating a waveform image, specifies the image width.
--height, -h <height> (default: 250)
When creating a waveform image, specifies the image height.
--colors, -c <colors> (default: audacity)
When creating a waveform image, specifies the color scheme to use. Valid values
are either audacity, which generates a blue waveform on a grey background,
similar to Audacity, or audition, which generates a green waveform on a
dark background, similar to Adobe Audition.
--border-color <rrggbb[aa]>
When creating a waveform image, specifies the border color. If not given,
the default color used is controlled by the --colors option.
The color value should include two hexadecimal digits for each of red, green, and blue (00 to FF), and optional alpha transparency (00 to FF).
--background-color <rrggbb[aa]>
When creating a waveform image, specifies the background color. If not given,
the default color used is controlled by the --colors option.
--waveform-color <rrggbb[aa]>[, <rrggbb[aa]>, ...]
When creating a waveform image, specifies the waveform color. If not given,
the default color used is controlled by the --colors option. This option
accepts multiple comma-separated color values, which are used with the
--split-channels option to produce a waveform image with multiple channels.
--axis-label-color <rrggbb[aa]>
When creating a waveform image, specifies the axis labels color. If not given,
the default color used is controlled by the --colors option.
--with-axis-labels, --no-axis-labels (default: --with-axis-labels)
When creating a waveform image, specifies whether to render axis labels and image border.
--amplitude-scale <scale> (default: 1)
When creating a waveform image or waveform data file, specifies an amplitude
scaling (or vertical zoom) to apply to the waveform. Must be either a number
or auto, which scales the waveform to the maximum height.
--waveform-style <style> (default: normal)
When creating a waveform image, specifies how waveform is drawn. Valid values
are either normal, which draws a normal waveform, or bars, which
draws the waveform as vertical bars.
--bar-width <width> (default: 8)
When creating a waveform image with the --waveform-style bars option,
specifies the width of each bar, in pixels.
--bar-gap <width> (default: 4)
When creating a waveform image with the --waveform-style bars option,
specifies the separation between each bar, in pixels.
--bar-style <style> (default: square)
When creating a waveform image with the --waveform-style bars option,
specifies how each bar is drawn. Valid values are either square,
which draws the waveform bars with square corners, or rounded, which
draws the waveform with rounded corners.
--compression <level> (default: -1)
When creating a waveform image, specifies the PNG compression level. Must be either -1 (default compression) or between 0 (fastest) and 9 (best compression).
--raw-samplerate
When using raw input audio format, this must be set to the appropriate sample rate, in Hz.
--raw-channels
When using raw input audio format, this must be set to the appropriate number of channels.
--raw-format
When using raw input audio format, this must be set to the appropriate sample format.
Valid options are s8, u8, s16le, s16be, s24le, s24be, s32le, s32be,
f32le, f32be, f64le and f64be.
Examples
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
The --waveform-style option allows you to produce waveform images drawn
as vertical bars. The --bar-width, --bar-gap, and --bar-style options
customize the immage:
audiowaveform -i test.mp3 -o test.png -w 1000 -h 200 -z auto \
--waveform-style bars --bar-width 10 --bar-gap 2 --bar-style rounded
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 WAV format as well as raw audio, but not FLAC nor Ogg Vorbis.
Data Formats
You can find details of the waveform data file formats produced by audiowaveform here.
Credits
This program contains code from the following open-source projects, used under the terms of these projects' respective licenses:
- Audacity
- madlld
- pdjson
License
See COPYING for details.
Contributing
If you'd like to contribute to audiowaveform, please take a look at our contributor guidelines.
Authors
This software was written by Chris Needham, chris at chrisneedham.com.
Thank you to all our contributors.
Copyright
Copyright 2013-2025 British Broadcasting Corporation
Related repositories
Bitcoin Core is the reference implementation of the Bitcoin protocol, hosted at bitcoin/bitcoin on GitHub. Per its README, it joins the Bitcoin peer-to-peer network to independently validate blocks and transactions, ships an optional wallet and GUI, and is written in C++ under the MIT license.
The OBS Studio README promises efficient capture and streaming. Four user issues from 2020 to 2023 show where that promise met real setups.
Public APIs is a community-curated GitHub repository listing free, publicly accessible APIs across a wide range of categories, with auth type, HTTPS, and CORS noted for each entry. It's a browsable reference, not a library to install.
Awesome-Selfhosted is a community-maintained GitHub list at awesome-selfhosted/awesome-selfhosted that catalogs Free Software network-service and web-app projects meant for running on a server you control rather than someone else's cloud. Entries are grouped by category, each tagged with a license and a language or deployment option, and the project keeps proprietary alternatives on a separate Non-Free page.
Quick answers
Does bbc/audiowaveform have a project website?
No homepage URL was recorded for bbc/audiowaveform in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
How active is development on bbc/audiowaveform?
The most recent commit recorded on bbc/audiowaveform was 1.2 years ago, based on the GitHub push timestamp. The repository has 254 forks — one of the better signals of community interest.
How many stars does bbc/audiowaveform have?
bbc/audiowaveform has 2.2k GitHub stars — refresh the page for the live number, or check github.com/bbc/audiowaveform. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is bbc/audiowaveform open source?
Yes — bbc/audiowaveform ships under the GPL-3.0 license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/bbc/audiowaveform.
What else is in the Backend space?
bbc/audiowaveform is tracked by TopGit under the Backend category, alongside 2 GitHub-tagged topics. Trending and Topics pages list peer repositories of comparable stars and language.
What topics is bbc/audiowaveform associated with?
GitHub's repository topics for bbc/audiowaveform: "audio", "c-plus-plus". TopGit's editorial category is Backend.
Where do I read more about bbc/audiowaveform?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/bbc/audiowaveform is the definitive source.
Read full README in the tab above.
Is audiowaveform worth your time?
ChatGPT, Claude and Perplexity can all read this page. Ask one of them what it makes of audiowaveform.