JosiahSiegel/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.