ffmpeg-audio-processing

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 (`/`).

---

## Quick Reference

| Task | Command |
|------|---------|
| Extract audio | `ffmpeg -i video.mp4 -vn -c:a copy audio.m4a` |
| Convert to MP3 | `ffmpeg -i input.flac -c:a libmp3lame -q:a 2 output.mp3` |
| Normalize (EBU R128) | `-af loudnorm=I=-23:LRA=7:TP=-2` |
| Podcast standard | `-af loudnorm=I=-16:TP=-1.5` |
| Adjust volume | `-af "volume=1.5"` or `-af "volume=6dB"` |
| Mono to stereo | `-ac 2` |

| Codec | Recommended Bitrate | Use Case |
|-------|---------------------|----------|
| AAC | 128-192k (music), 64k (speech) | Streaming, mobile |
| MP3 | 192-320k (music), 128k (speech) | Universal compatibility |
| Opus | 96-128k (music), 48k (speech) | WebM, VoIP, modern |

## When to Use This Skill

Use for **audio-focused operations**:
- Extracting audio from video files
- Loudness normalization for broadcast/streaming compliance
- Podcast and audiobook processing
- Audio format conversion
- Audio effects (EQ, compression, noise reduction)

---

# FFmpeg Audio Processing (2025)

Complete guide to audio encoding, normalization, and professional audio workflows with FFmpeg.

## Audio Codec Reference

### Codec Comparison

| Codec | Encoder | Bitrate Range | Quality | Compatibility | Use Case |
|-------|---------|---------------|---------|---------------|----------|
| AAC | aac, libfdk_aac | 64-320 kbps | Excellent | Universal | Streaming, mobile |
| MP3 | libmp3lame | 96-320 kbps | Good | Universal | Legacy, podcasts |
| Opus | libopus | 32-256 kbps | Best | Modern | VoIP, WebM |
| FLAC | flac | ~900 kbps | Lossless | Wide | Archival |
| ALAC | alac | ~900 kbps | Lossless | Apple | Apple ecosystem |
| Vorbis | libvorbis | 64-500 kbps | Very Good | Wide | WebM, games |
| AC3 | ac3 | 192-640 kbps | Good | Universal | DVD, Blu-ray |
| EAC3 | eac3 | 192-768 kbps | Very Good | Wide | Streaming |
| xHE-AAC | - (decode only) | 12-64 kbps | Excellent | Emerging | Ultra-low bitrate |

### Recommended Bitrates

| Use Case | AAC | MP3 | Opus |
|----------|-----|-----|------|
| Podcast/Speech | 64-96k | 96-128k | 48-64k |
| Music (Standard) | 128-192k | 192-256k | 96-128k |
| Music (High Quality) | 256-320k | 320k | 160-256k |
| Transparent Quality | 256k+ | 320k | 192k+ |

## Basic Audio Operations

### Extract Audio

```bash
# Extract to original format (no re-encode)
ffmpeg -i video.mp4 -vn -c:a copy audio.m4a

# Extract to MP3
ffmpeg -i video.mp4 -vn -c:a libmp3lame -b:a 320k audio.mp3

# Extract to AAC
ffmpeg -i video.mp4 -vn -c:a aac -b:a 256k audio.m4a

# Extract to FLAC (lossless)
ffmpeg -i video.mp4 -vn -c:a flac audio.flac

# Extract to WAV (uncompressed)
ffmpeg -i video.mp4 -vn -c:a pcm_s16le audio.wav
```

### Convert Audio Formats

```bash
# MP3 to AAC
ffmpeg -i input.mp3 -c:a aac -b:a 256k output.m4a

# WAV to MP3
ffmpeg -i input.wav -c:a libmp3lame -b:a 320k output.mp3

# FLAC to MP3
ffmpeg -i input.flac -c:a libmp3lame -b:a 320k output.mp3

# Multiple files (batch)
for f in *.flac; do
  ffmpeg -i "$f" -c:a libmp3lame -b:a 320k "${f%.flac}.mp3"
done
```

### Quality Settings

```bash
# AAC VBR quality (1-5, higher = better)
ffmpeg -i input.wav -c:a aac -q:a 2 output.m4a

# MP3 VBR quality (0-9, lower = better)
ffmpeg -i input.wav -c:a libmp3lame -q:a 0 output.mp3

# Opus with target bitrate
ffmpeg -i input.wav -c:a libopus -b:a 128k output.opus
```

## Audio Normalization

### Loudness Standards

| Standard | Target | TP (True Peak) | Use Case |
|----------|--------|----------------|----------|
| EBU R128 | -23 LUFS | -1 dBTP | European broadcast |
| ATSC A/85 | -24 LKFS | -2 dBTP | US broadcast |
| Spotify | -14 LUFS | -1 dBTP | Streaming |
| YouTube | -14 LUFS | -1 dBTP | Video platform |
| Apple Music | -16 LUFS | -1 dBTP | Music streaming |
| Podcast | -16 to -19 LUFS | -1 dBTP | Podcast |

### EBU R128 Normalization (loudnorm)

#### Single-Pass (Live/Real-time)
```bash
# Quick normalization (less accurate)
ffmpeg -i input.mp3 \
  -af loudnorm=I=-16:TP=-1.5:LRA=11 \
  output.mp3
```

#### Two-Pass (Recommended)

```bash
# Pass 1: Analyze
ffmpeg -i input.mp3 \
  -af loudnorm=I=-16:TP=-1.5:LRA=11:print_format=json \
  -f null -

# Output will include:
# "input_i": "-25.23"
# "input_tp": "-0.50"
# "input_lra": "8.32"
# "input_thresh": "-35.87"
# "target_offset": "1.23"

# Pass 2: Normalize with measured values
ffmpeg -i input.mp3 \
  -af loudnorm=I=-16:TP=-1.5:LRA=11:measured_I=-25.23:measured_TP=-0.50:measured_LRA=8.32:measured_thresh=-35.87:offset=1.23:linear=true \
  -ar 48000 \
  output.mp3
```

#### Two-Pass Script

```bash
#!/bin/bash
# loudnorm-2pass.sh

INPUT="$1"
OUTPUT="$2"
TARGET_I="${3:--16}"
TARGET_TP="${4:--1.5}"
TARGET_LRA="${5:-11}"

# Pass 1: Analyze
stats=$(ffmpeg -i "$INPUT" \
  -af loudnorm=I=${TARGET_I}:TP=${TARGET_TP}:LRA=${TARGET_LRA}:print_format=json \
  -f null - 2>&1 | grep -A 12 "Parsed_loudnorm")

# Extract values
input_i=$(echo "$stats" | grep input_i | tr -d '", ' | cut -d':' -f2)
input_tp=$(echo "$stats" | grep input_tp | tr -d '", ' | cut -d':' -f2)
input_lra=$(echo "$stats" | grep input_lra | tr -d '", ' | cut -d':' -f2)
input_thresh=$(echo "$stats" | grep input_thresh | tr -d '", ' | cut -d':' -f2)
offset=$(echo "$stats" | grep target_offset | tr -d '", ' | cut -d':' -f2)

# Pass 2: Normalize
ffmpeg -i "$INPUT" \
  -af "loudnorm=I=${TARGET_I}:TP=${TARGET_TP}:LRA=${TARGET_LRA}:measured_I=${input_i}:measured_TP=${input_tp}:measured_LRA=${input_lra}:measured_thresh=${input_thresh}:offset=${offset}:linear=true" \
  -ar 48000 \
  "$OUTPUT"
```

### Peak Normalization

```bash
# Normalize to peak level
ffmpeg -i input.mp3 \
  -af "volume=0dB:eval=once:precision=fixed" \
  -af "loudnorm=I=-16:TP=-1:LRA=11" \
  output.mp3

# Simple peak normalization
ffmpeg -i input.mp3 \
  -filter:a "volume=replaygain=peak" \
  output.mp3
```

### RMS Normalization

```bash
# Normalize to specific RMS level
ffmpeg -i input.mp3 \
  -af "loudnorm=I=-23:LRA=7:TP=-2" \
  output.mp3
```

### ffmpeg-normalize Tool

The `ffmpeg-normalize` Python utility provides an easier interface:

```bash
# Install
pip install ffmpeg-normalize

# Basic usage
ffmpeg-normalize input.mp3 -o output.mp3

# Custom target
ffmpeg-normalize input.mp3 -o output.mp3 -t -14

# Batch normalize (album mode - preserves relative loudness)
ffmpeg-normalize *.mp3 --batch -o normalized/

# Use built-in presets (v1.36.0+)
ffmpeg-normalize input.mp3 --preset podcast -o output.mp3
ffmpeg-normalize *.mp3 --preset music --batch -o normalized/
```

## Audio Filters

### Volume Control

```bash
# Increase volume by 50%
ffmpeg -i input.mp3 -af "volume=1.5" output.mp3

# Increase by 6dB
ffmpeg -i input.mp3 -af "volume=6dB" output.mp3

# Decrease by 3dB
ffmpeg -i input.mp3 -af "volume=-3dB" output.mp3
```

### Fade In/Out

```bash
# Fade in 3 seconds, fade out last 3 seconds
ffmpeg -i input.mp3 \
  -af "afade=t=in:ss=0:d=3,afade=t=out:st=57:d=3" \
  output.mp3

# Calculate fade out start automatically
duration=$(ffprobe -v error -show_entries format=duration -of default=noprint_wrappers=1:nokey=1 input.mp3)
fadeout_start=$(echo "$duration - 3" | bc)
ffmpeg -i input.mp3 \
  -af "afade=t=in:ss=0:d=3,afade=t=out:st=${fadeout_start}:d=3" \
  output.mp3
```

### Equalization

```bash
# Bass boost
ffmpeg -i input.mp3 \
  -af "equalizer=f=100:width_type=o:width=2:g=5" \
  output.mp3

# Treble reduction
ffmpeg -i input.mp3 \
  -af "equalizer=f=8000:width_type=o:width=2:g=-3" \
  output.mp3

# Multi-band EQ
ffmpeg -i input.mp3 \
  -af "equalizer=f=100:width_type=o:w