ffmpeg-waveforms-visualization

What this skill does

## 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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_co