Last updated: February 4, 2025
# Creative waveform visualizations with Audiowaveform
**Tim Koschützki**
Co-founder · Berlin, Germany · Show bio
[](https://x.com/tim%5Fkos)[](https://github.com/tim-kos)
Creating engaging audio experiences goes beyond just playing back sound. Waveform images provide a visual layer that enhances user interaction and deepens how visitors engage with your audio projects.
## Introduction
Visual representations of sound can provide critical insights into audio dynamics. Audiowaveform, developed and maintained by the BBC, is a powerful tool for generating waveform visualizations from audio files. This post explores how to use audiowaveform effectively, from installation to advanced customization.
## Installation
Audiowaveform can be installed on various platforms. Here are the platform-specific instructions:
For Ubuntu/Debian:
```bash
sudo add-apt-repository ppa:chris-needham/ppa
sudo apt-get update
sudo apt-get install audiowaveform
```
For macOS:
```bash
brew tap bbc/audiowaveform
brew install audiowaveform
```
For Windows, download the latest binary from the[official releases page](https://github.com/bbc/audiowaveform/releases).
## Supported formats
Audiowaveform works with several popular audio formats:
* MP3
* WAV
* FLAC
* Ogg Vorbis
* Opus (requires libsndfile 1.0.29 or later)
Output can be generated in multiple formats:
* Waveform data files (.dat)
* JSON format (.json)
* PNG images (.png)
* WAV audio (.wav)
## Basic command usage
To generate a waveform visualization, you have two approaches. The first creates a data file that can be reused:
```bash
audiowaveform -i input.mp3 -o waveform.dat -z 256 -b 8
```
Then generate a PNG from the data file:
```bash
audiowaveform -i waveform.dat -o waveform.png -w 800 -h 200 --pixels-per-second 100
```
Alternatively, generate a PNG directly:
```bash
audiowaveform -i input.mp3 -o waveform.png -w 800 -h 200 \
--background-color ffffff --waveform-color 000000 --pixels-per-second 100
```
## Advanced customization
Audiowaveform offers extensive customization options:
```bash
audiowaveform \
-i input.mp3 \
-o waveform-custom.png \
--width 800 \
--height 200 \
--background-color ffffff \
--waveform-color 1a73e8 \
--pixels-per-second 100 \
--split-channels \
--amplitude-scale 2
```
Key parameters include:
* `--split-channels`: Display stereo channels separately
* `--amplitude-scale`: Adjust waveform amplitude scaling
* `--pixels-per-second`: Control horizontal zoom level
* `--bits`: Set bits per sample in output data file (8 or 16)
## Troubleshooting
When working with audiowaveform, keep these points in mind:
* Verify input audio files are not corrupted
* Ensure sufficient memory for high-resolution waveforms
* When using `--split-channels`, confirm input has multiple channels
* Check system dependencies (libmad, libsndfile, libid3tag, gd)
Common error messages and solutions:
* "Error: cannot load input file": Check file permissions and format support
* "Error: insufficient memory": Reduce resolution or file size
* "Error: invalid color format": Use hex color codes without '#' prefix
## Integration with applications
Audiowaveform can be integrated into media processing pipelines. For automated processing, consider using Transloadit's `/audio/waveform` Robot, which generates waveform visualizations as part of your workflow:
```json
{
"steps": {
"waveform": {
"robot": "/audio/waveform",
"use": ":original",
"result": true,
"width": 800,
"height": 200
}
}
}
```
## Conclusion
Audiowaveform is a versatile tool for creating visual representations of audio files. Its extensive customization options and format support make it valuable for audio-focused applications. For automated processing needs, explore Transloadit's Audio Encoding service, which includes waveform generation capabilities.
\#audiowaveform#audio-encoding-service#audio-visualization[#devtips](/devtips.md)
### 👩💻 Join 20k+ developers
Sign up for our [monthly newsletter](/newsletters.md) to receive direct links to 3 exclusive tech — and 2 product updates. No less, no more.
Your email:
Get access
## File uploading and encoding. Made simple.
Transloadit streamlines file handling for developers, trusted by brands like Coursera and The New York Times. We’re known for a reliable API, top-notch support, and a strong commitment to open source, with projects like [Uppy](https://uppy.io) and [Tus](https://tus.io) setting standards in file processing.
[Sign up](/c/)[Book a Demo](https://survey.typeform.com/to/kRg47Xi5)
No credit card needed · 5 GB included in the free plan
Cancel anytime