Generates waveform visualization images from audio files. Available as a graphical desktop app (waveform_gui.py) and a command-line tool (waveform_generator.py).
Python 3.8+ with the following packages:
librosa
numpy>=2.0.0
Pillow
Install with:
pip install -r requirements.txtMP3, WAV, FLAC, OGG, M4A (AAC support on Windows depends on installed codecs; MP3/WAV/FLAC are the most reliable).
python waveform_gui.pySwitch between Single file and Batch folder at the top of the window.
- Single file — select one audio file and generate its waveform.
- Batch folder — select a folder; all supported audio files in it will be processed in one run. Progress is shown in the status bar and any failures are reported at the end without stopping the batch.
Choose from built-in presets or enter custom dimensions:
| Preset | Width | Height |
|---|---|---|
| MusicBee thumb | 560 | 100 |
| Wide banner | 900 | 120 |
| Square tile | 300 | 300 |
| Compact | 400 | 60 |
Width and height spinboxes accept any value (px).
Click the Background or Waveform colour swatches to open the system colour picker. The Transparent background checkbox outputs an RGBA PNG with a transparent background — useful for overlaying waveforms on album art or web pages. The preview panel renders a checkerboard behind transparent images so you can see the result clearly.
| Option | Description |
|---|---|
| Peaks (min/max) | Draws the true min and max amplitude per pixel — captures transients and fine detail |
| RMS (smooth) | Draws ±RMS amplitude per pixel — smoother, more averaged appearance |
| Mirror (symmetric) | Reflects the waveform around the centre line (can be combined with either style above) |
After each generation the output is scaled to fit a preview panel at the bottom of the window — no need to open a separate viewer just to check colours or dimensions.
python waveform_generator.py <audio_file> [output.png] [options]| Flag | Default | Description |
|---|---|---|
--width N |
560 | Output width in pixels |
--height N |
100 | Output height in pixels |
--bg #RRGGBB |
#f9f9f9 |
Background colour |
--wave #RRGGBB |
#3e628e |
Waveform colour |
--style peaks|rms |
peaks |
Waveform style |
--mirror |
off | Symmetric/mirrored waveform |
--transparent |
off | Transparent background (RGBA PNG) |
If no output path is given, the file is saved as <input_name>_waveform.png in the current directory.
# Basic usage — defaults
python waveform_generator.py song.mp3
# Custom size and colours
python waveform_generator.py song.flac out.png --width 900 --height 120 --bg "#1a1a2e" --wave "#7c9cbf"
# Smooth symmetric waveform with transparent background
python waveform_generator.py song.wav --style rms --mirror --transparent
# Specify output path explicitly
python waveform_generator.py song.mp3 artwork/song_wave.png --width 300 --height 300All outputs are saved as PNG. When Transparent background is enabled the file is RGBA; otherwise it is RGB. Output filenames follow the pattern <source_name>_waveform.png unless overridden.