ffmpeg-waveforms-visualization

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:[email protected][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:[email protected]: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.