Songsee: Generate Audio Spectrograms and Feature Visualizations via CLI

Songsee is a command-line tool that turns audio files into spectrograms and multi-panel feature visualizations. If you work with audio processing, synthesis debugging, or need to inspect the frequency content of a track without opening a DAW, this is a fast, scriptable option.

What it does

Songsee reads an audio file and produces one or more visual representations of its content. You can generate a single spectrogram, or combine multiple feature types (mel, chroma, MFCC, and others) into a single grid image. It supports time slicing, custom color palettes, and configurable FFT parameters.

Before you start

• Go must be installed. Install it from go.dev.
• Install songsee with:

go install github.com/steipete/songsee/cmd/songsee@latest

• ffmpeg is optional but needed for audio formats other than WAV and MP3.
• Works on Linux, macOS, and Windows.

Quick Start

These examples cover the most common workflows. Run them from a terminal where songsee is on your PATH.

# Basic spectrogram
songsee track.mp3

# Save to specific file
songsee track.mp3 -o spectrogram.png

# Multi-panel visualization grid
songsee track.mp3 --viz spectrogram,mel,chroma,hpss,selfsim,loudness,tempogram,mfcc,flux

# Time slice (start at 12.5s, 8s duration)
songsee track.mp3 --start 12.5 --duration 8 -o slice.jpg

# From stdin
cat track.mp3 | songsee - --format png -o out.png

The first command writes a spectrogram image to the current directory. The -o flag lets you name the output. The --viz flag with multiple types produces a grid, which is useful for comparing features side by side. The stdin example is handy for piping output from another tool.

Visualization Types

Use --viz with comma-separated values to select which features to render. Each type shows a different aspect of the audio.

Type	Description
spectrogram	Standard frequency spectrogram
mel	Mel-scaled spectrogram
chroma	Pitch class distribution
hpss	Harmonic/percussive separation
selfsim	Self-similarity matrix
loudness	Loudness over time
tempogram	Tempo estimation
mfcc	Mel-frequency cepstral coefficients
flux	Spectral flux (onset detection)

Multiple --viz types render as a grid in a single image.

Common Flags

These flags let you control the output appearance and what part of the audio is analyzed.

Flag	Description
--viz	Visualization types (comma-separated)
--style	Color palette: classic, magma, inferno, viridis, gray
--width / --height	Output image dimensions
--window / --hop	FFT window and hop size
--min-freq / --max-freq	Frequency range filter
--start / --duration	Time slice of the audio
--format	Output format: jpg or png
-o	Output file path

Notes

• WAV and MP3 are decoded natively; other formats require ffmpeg.
• Output images can be inspected with vision_analyze for automated audio analysis.
• Useful for comparing audio outputs, debugging synthesis, or documenting audio processing pipelines.