josiahsiegel CRITICAL GUIDELINES
Windows File Path Requirements
MANDATORY: Always Use Backslashes on Windows for File Paths
When using Edit or Write tools on Windows, you MUST use backslashes (\) in file paths, NOT forward slashes (/).
Documentation Guidelines
NEVER create new documentation files unless explicitly requested by the user.
Quick Reference
| Visualization | Filter | Output | Command Snippet |
|---|---|---|---|
| Animated waveform | showwaves |
Video | [0:a]showwaves=s=1280x720:mode=line[v] |
| Static waveform | showwavespic |
Image | [0:a]showwavespic=s=1280x240:colors=0x00FF00 |
| Spectrum | showspectrum |
Video | [0:a]showspectrum=s=1280x720:color=fire |
| Frequency bars | showfreqs |
Video | [0:a]showfreqs=s=1280x720:mode=bar |
| Vectorscope | avectorscope |
Video | [0:a]avectorscope=s=512x512:mode=lissajous |
| Color Scheme | Effect |
|---|---|
rainbow |
Full spectrum gradient |
fire |
Warm orange/red tones |
cool |
Blue tones |
viridis |
Scientific colormap |
When to Use This Skill
Use for audio visualization creation:
- Music video waveform backgrounds
- Podcast video thumbnails
- SoundCloud-style waveform images
- Spectrum analyzer overlays
- Audio-reactive visualizations
FFmpeg Waveforms and Audio Visualization (2025)
Complete guide to generating audio waveforms, spectrum analyzers, and audio-reactive visualizations using FFmpeg.
Audio Visualization Filters
Filter Overview
| Filter | Output | Use Case |
|---|---|---|
| showwaves | Video of animated waveform | Music videos, live vis |
| showwavespic | Static waveform image | Thumbnails, podcasts |
| showspectrum | Spectrum analyzer video | Frequency analysis |
| showspectrumpic | Static spectrum image | Audio fingerprinting |
| showfreqs | Frequency bars video | Equalizer visualization |
| avectorscope | Stereo phase visualization | Audio engineering |
| ahistogram | Audio level histogram | Loudness analysis |
| showcqt | Constant-Q transform | Musical note visualization |
Waveform Generation (showwaves)
Basic Animated Waveform
# Simple waveform video
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x720:mode=line[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -c:a aac \
waveform.mp4
# Waveform from video with audio
ffmpeg -i video.mp4 \
-filter_complex "[0:a]showwaves=s=1920x200:mode=line[wave];[0:v][wave]overlay=0:H-200[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -c:a copy \
video_with_wave.mp4
Waveform Modes
# Line mode (default) - connected lines
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line[v]" \
-map "[v]" waveform_line.mp4
# Point mode - individual points
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=point[v]" \
-map "[v]" waveform_point.mp4
# Filled mode - filled area
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=p2p[v]" \
-map "[v]" waveform_filled.mp4
# Centered line mode
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=cline[v]" \
-map "[v]" waveform_centered.mp4
Available Modes
| Mode | Description |
|---|---|
| point | Draw a point for each sample |
| line | Draw lines between samples |
| p2p | Draw point-to-point (filled) |
| cline | Centered line mode |
Colored Waveforms
# Single color waveform
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=cline:colors=0x00FF00[v]" \
-map "[v]" green_wave.mp4
# Multi-channel colors (stereo)
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:colors=red|blue:split_channels=1[v]" \
-map "[v]" stereo_wave.mp4
# Gradient-style (requires multiple passes)
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=cline:colors=0xFF6600[v]" \
-map "[v]" orange_wave.mp4
Rate and Scale
# Adjust waveform speed (n = samples per column)
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:n=2[v]" \
-map "[v]" fast_wave.mp4
# Adjust scale (amplitude)
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:scale=lin[v]" \
-map "[v]" linear_wave.mp4
# Logarithmic scale (better for quiet audio)
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:scale=log[v]" \
-map "[v]" log_wave.mp4
# Square root scale
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:scale=sqrt[v]" \
-map "[v]" sqrt_wave.mp4
# Cube root scale (compressed dynamics)
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:scale=cbrt[v]" \
-map "[v]" cbrt_wave.mp4
Scale Options
| Scale | Description | Best For |
|---|---|---|
| lin | Linear amplitude | General use |
| log | Logarithmic | Quiet audio, speech |
| sqrt | Square root | Moderate compression |
| cbrt | Cube root | Heavy compression |
Static Waveform Images (showwavespic)
Basic Waveform Image
# Generate waveform PNG
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwavespic=s=1280x240:colors=0x00FF00" \
-frames:v 1 \
waveform.png
# High-resolution waveform
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwavespic=s=3840x480:colors=white" \
-frames:v 1 \
waveform_hires.png
Styled Waveform Images
# Split stereo channels
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwavespic=s=1280x480:split_channels=1:colors=0xFF0000|0x0000FF" \
-frames:v 1 \
stereo_waveform.png
# Filled style
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwavespic=s=1280x240:colors=0x1E90FF:draw=full" \
-frames:v 1 \
filled_waveform.png
# Scale adjustment
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwavespic=s=1280x240:scale=sqrt:colors=0xFFD700" \
-frames:v 1 \
golden_waveform.png
Waveform with Background
# Waveform on colored background
ffmpeg -i audio.mp3 \
-filter_complex "color=c=0x1a1a2e:s=1280x240:d=1[bg];\
[0:a]showwavespic=s=1280x240:colors=0x00FF88[wave];\
[bg][wave]overlay[v]" \
-map "[v]" -frames:v 1 \
waveform_bg.png
# Waveform on gradient background
ffmpeg -f lavfi \
-i "gradients=s=1280x240:c0=0x000033:c1=0x003366:duration=1" \
-i audio.mp3 \
-filter_complex "[1:a]showwavespic=s=1280x240:colors=0x00FFFF[wave];\
[0:v][wave]overlay[v]" \
-map "[v]" -frames:v 1 \
waveform_gradient.png
Spectrum Visualization (showspectrum)
Basic Spectrum Analyzer
# Animated spectrum
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:mode=combined:color=rainbow[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -c:a aac \
spectrum.mp4
# Vertical spectrum
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=720x1280:orientation=vertical:color=fire[v]" \
-map "[v]" -map 0:a \
spectrum_vertical.mp4
Spectrum Modes
# Combined channels
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:mode=combined[v]" \
-map "[v]" spectrum_combined.mp4
# Separate channels
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:mode=separate[v]" \
-map "[v]" spectrum_separate.mp4
Color Schemes
# Rainbow spectrum
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:color=rainbow[v]" \
-map "[v]" spectrum_rainbow.mp4
# Fire spectrum
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:color=fire[v]" \
-map "[v]" spectrum_fire.mp4
# Cool spectrum
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:color=cool[v]" \
-map "[v]" spectrum_cool.mp4
# Channel-based colors
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:color=channel[v]" \
-map "[v]" spectrum_channel.mp4
Available Color Schemes
| Color | Description |
|---|---|
| channel | Use channel colors |
| rainbow | Rainbow gradient |
| moreland | Diverging color map |
| nebulae | Space-like colors |
| fire | Warm fire colors |
| fiery | Intense fire |
| fruit | Fruit-inspired |
| cool | Cool blue tones |
| magma | Volcanic colors |
| green | Green gradient |
| viridis | Scientific colormap |
| plasma | Plasma colormap |
| cividis | Colorblind-friendly |
| terrain | Terrain-like |
Spectrum Scale and Window
# Logarithmic frequency scale
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:fscale=log:color=fire[v]" \
-map "[v]" spectrum_log.mp4
# Different window functions
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:win_func=blackman:color=rainbow[v]" \
-map "[v]" spectrum_blackman.mp4
# Higher frequency resolution
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1280x720:win_size=4096:color=fire[v]" \
-map "[v]" spectrum_hires.mp4
Static Spectrum Image (showspectrumpic)
# Full audio spectrogram
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrumpic=s=1920x480:color=fire[v]" \
-map "[v]" \
spectrogram.png
# With legend
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrumpic=s=1920x480:color=rainbow:legend=1[v]" \
-map "[v]" \
spectrogram_legend.png
# Logarithmic frequency scale
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrumpic=s=1920x480:fscale=log:color=viridis[v]" \
-map "[v]" \
spectrogram_log.png
Frequency Bars (showfreqs)
Basic Frequency Display
# Bar-style equalizer
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showfreqs=s=1280x720:mode=bar:ascale=log:colors=green[v]" \
-map "[v]" -map 0:a \
freqs_bar.mp4
# Line-style frequency display
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showfreqs=s=1280x720:mode=line:colors=cyan[v]" \
-map "[v]" -map 0:a \
freqs_line.mp4
# Dot-style display
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showfreqs=s=1280x720:mode=dot:colors=0xFF00FF[v]" \
-map "[v]" -map 0:a \
freqs_dot.mp4
Equalizer-Style Visualization
# Classic equalizer bars
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showfreqs=s=1280x720:mode=bar:fscale=log:ascale=log:win_size=1024:colors=0x00FF00[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -c:a aac \
equalizer.mp4
Constant-Q Transform (showcqt)
Musical Note Visualization
# Basic CQT visualization
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showcqt=s=1920x1080[v]" \
-map "[v]" -map 0:a \
cqt.mp4
# CQT with axis labels
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showcqt=s=1920x1080:axis=1:text=1:fontfile=/path/to/font.ttf[v]" \
-map "[v]" -map 0:a \
cqt_labeled.mp4
# Custom colors
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showcqt=s=1920x1080:sono_g='st(0, floor(log2(400*meter))); if(gt(ld(0),-2), if(lt(ld(0),0),ld(0)+2, if(lt(ld(0),3),1, 3-ld(0))),0)'[v]" \
-map "[v]" -map 0:a \
cqt_custom.mp4
Vector Scope (avectorscope)
Stereo Phase Visualization
# Basic vectorscope
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]avectorscope=s=512x512:mode=lissajous[v]" \
-map "[v]" -map 0:a \
vectorscope.mp4
# Polar mode
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]avectorscope=s=512x512:mode=polar:zoom=1.5[v]" \
-map "[v]" -map 0:a \
vectorscope_polar.mp4
# With color coding
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]avectorscope=s=512x512:mode=lissajous:draw=line:scale=sqrt[v]" \
-map "[v]" -map 0:a \
vectorscope_color.mp4
Audio Histogram (ahistogram)
Level Distribution Visualization
# Basic audio histogram
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]ahistogram=s=1280x720:dmode=separate[v]" \
-map "[v]" -map 0:a \
histogram.mp4
# Combined mode
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]ahistogram=s=1280x720:dmode=combined:slide=scroll[v]" \
-map "[v]" -map 0:a \
histogram_combined.mp4
Combining Visualizations
Waveform Over Video
# Waveform overlay at bottom
ffmpeg -i video.mp4 \
-filter_complex "[0:a]showwaves=s=1920x200:mode=cline:colors=white@0.7[wave];\
[0:v][wave]overlay=0:H-200[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -c:a copy \
video_waveform.mp4
# Transparent waveform overlay
ffmpeg -i video.mp4 \
-filter_complex "[0:a]showwaves=s=1920x1080:mode=p2p:colors=0x00FF00@0.5:scale=sqrt[wave];\
[0:v][wave]blend=all_mode=addition[v]" \
-map "[v]" -map 0:a \
video_wave_blend.mp4
Multiple Visualizations
# Waveform + Spectrum side by side
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]asplit=2[a1][a2];\
[a1]showwaves=s=640x360:mode=cline:colors=green[wave];\
[a2]showspectrum=s=640x360:color=fire[spec];\
[wave][spec]hstack[v]" \
-map "[v]" -map 0:a \
combined_vis.mp4
# Full visualization dashboard
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]asplit=4[a1][a2][a3][a4];\
[a1]showwaves=s=640x240:mode=cline:colors=cyan[wave];\
[a2]showspectrum=s=640x240:color=fire:scale=log[spec];\
[a3]showfreqs=s=640x240:mode=bar:colors=lime[freq];\
[a4]avectorscope=s=640x240:mode=lissajous[vec];\
[wave][spec]hstack[top];\
[freq][vec]hstack[bottom];\
[top][bottom]vstack[v]" \
-map "[v]" -map 0:a \
dashboard.mp4
Visualization with Progress Bar
# Waveform with animated progress indicator
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwavespic=s=1280x200:colors=0x333333[bg];\
[0:a]showwaves=s=1280x200:mode=cline:colors=0x00FF00:n=4[wave];\
[bg][wave]overlay[v];\
color=c=red:s=4x200:d=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 audio.mp3)[bar];\
[v][bar]overlay=x='t/$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 audio.mp3)*W'[out]" \
-map "[out]" -map 0:a \
waveform_progress.mp4
Podcast/Music Video Templates
SoundCloud-Style Waveform
# Static waveform for music thumbnail
ffmpeg -i audio.mp3 \
-filter_complex "color=c=0x1a1a2e:s=1200x300:d=1[bg];\
[0:a]showwavespic=s=1200x200:colors=0xFF6B00:scale=sqrt[wave];\
[bg][wave]overlay=0:50[v]" \
-map "[v]" -frames:v 1 \
soundcloud_wave.png
Music Visualizer Video
# Full music visualizer
ffmpeg -i audio.mp3 -i album_art.jpg \
-filter_complex "[1:v]scale=1920:1080,boxblur=30[bg];\
[0:a]showwaves=s=1920x300:mode=cline:colors=white:scale=sqrt[wave];\
[1:v]scale=400:400[art];\
[bg][wave]overlay=0:H-350[tmp];\
[tmp][art]overlay=(W-400)/2:(H-400)/2-100[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -preset fast -crf 23 -c:a aac -b:a 192k \
music_video.mp4
Podcast Waveform Video
# Podcast with waveform and title
ffmpeg -i podcast.mp3 \
-filter_complex "color=c=0x2d3436:s=1920x1080:d=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 podcast.mp3)[bg];\
[0:a]showwaves=s=1920x400:mode=cline:colors=0x74b9ff:scale=sqrt[wave];\
[bg][wave]overlay=0:(H-400)/2[tmp];\
[tmp]drawtext=text='Episode Title':fontsize=72:fontcolor=white:x=(w-tw)/2:y=100[v]" \
-map "[v]" -map 0:a \
-c:v libx264 -c:a aac \
podcast_video.mp4
Performance Optimization
Large Audio Files
# Use threading for faster processing
ffmpeg -i long_audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:n=4[v]" \
-threads 0 \
-map "[v]" -map 0:a \
-c:v libx264 -preset fast -c:a aac \
output.mp4
Hardware Acceleration
# NVENC encoding for visualization
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showspectrum=s=1920x1080:color=fire[v]" \
-map "[v]" -map 0:a \
-c:v h264_nvenc -preset fast -c:a aac \
spectrum_nvenc.mp4
Troubleshooting
Common Issues
"Buffer too small" error
# Increase buffer size
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:n=1[v]" \
-map "[v]" output.mp4
Waveform appears silent/flat
# Adjust scale for quiet audio
ffmpeg -i quiet_audio.mp3 \
-filter_complex "[0:a]volume=10,showwaves=s=1280x360:mode=line:scale=log[v]" \
-map "[v]" output.mp4
Audio/video sync issues
# Force frame rate
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:rate=30[v]" \
-map "[v]" -map 0:a \
-r 30 \
output.mp4
Visualization too fast/slow
# Adjust samples per column (n)
# Higher n = faster scrolling
# Lower n = slower scrolling
ffmpeg -i audio.mp3 \
-filter_complex "[0:a]showwaves=s=1280x360:mode=line:n=3[v]" \
-map "[v]" output.mp4
This guide covers FFmpeg audio visualization. For video transitions and effects, see the transitions-effects skill.