Skip to content

README.md

Latest commit

 

History

History
359 lines (248 loc) · 8.79 KB

README.md

File metadata and controls

359 lines (248 loc) · 8.79 KB

Audio Plugin

Professional audio processing plugin for MediaProc CLI. Convert, extract, trim, merge, and normalize audio files with FFmpeg.

Features

  • 🔄 Convert - Convert between audio formats (MP3, AAC, WAV, FLAC, OGG, Opus)
  • 🎵 Extract - Extract audio tracks from video files
  • ✂️ Trim - Cut audio to specific time ranges with fade effects
  • 🔗 Merge - Concatenate multiple audio files with crossfade
  • 📊 Normalize - EBU R128 loudness normalization for consistent levels

Installation

npm install -g @mediaproc/audio

Or via MediaProc CLI:

mediaproc add audio

Requirements

  • FFmpeg 4.0+ with audio codecs support
  • Node.js 18+

Check if FFmpeg is installed:

ffmpeg -version

Commands

convert - Format Conversion

Convert audio files between different formats with quality control.

Supported Formats: MP3, AAC, WAV, FLAC, OGG, Opus, M4A

# Basic conversion
mediaproc audio convert input.wav -f mp3

# High-quality conversion
mediaproc audio convert input.flac -f mp3 -b 320k

# Lossless conversion
mediaproc audio convert input.wav -f flac -q lossless

# Change sample rate and channels
mediaproc audio convert input.mp3 -f wav -s 48000 -c 2

# Batch convert folder
mediaproc audio convert audio-files/ -f aac -o output/

Options:

  • -o, --output <path> - Output file/directory
  • -f, --format <format> - Output format (mp3, aac, wav, flac, ogg, opus, m4a)
  • -b, --bitrate <bitrate> - Audio bitrate (e.g., 128k, 192k, 320k)
  • -q, --quality <quality> - Quality preset: low, medium, high, lossless
  • -s, --sample-rate <rate> - Sample rate in Hz (44100, 48000)
  • -c, --channels <channels> - Channels: 1 (mono), 2 (stereo)

extract - Audio from Video

Extract audio tracks from video files to standalone audio files.

Supported Video Formats: MP4, MKV, AVI, MOV, WebM, FLV

# Extract as MP3 (default)
mediaproc audio extract video.mp4

# Extract as high-quality AAC
mediaproc audio extract video.mp4 -f aac -b 256k

# Extract as lossless FLAC
mediaproc audio extract video.mkv -f flac -q lossless

# Extract as mono for voice
mediaproc audio extract video.mp4 -f mp3 --channels 1

# Batch extract from folder
mediaproc audio extract videos/ -f mp3 -o audio-tracks/

Options:

  • -o, --output <path> - Output file/directory
  • -f, --format <format> - Output format (mp3, aac, wav, flac, opus, ogg)
  • -b, --bitrate <bitrate> - Audio bitrate
  • -q, --quality <quality> - Quality preset
  • --sample-rate <rate> - Sample rate
  • --channels <channels> - Number of channels

trim - Cut Audio

Trim audio files to specific time ranges with optional fade effects.

# Trim by time range
mediaproc audio trim audio.mp3 --start 00:01:00 --end 00:02:00

# Extract first 30 seconds
mediaproc audio trim audio.mp3 --duration 30

# Trim from 30s for 60s
mediaproc audio trim audio.mp3 -s 30 -d 60

# Add fade effects
mediaproc audio trim audio.mp3 -s 60 -d 120 --fade-in 2 --fade-out 3

# Fast mode (stream copy, no re-encoding)
mediaproc audio trim audio.mp3 --start 30 --duration 60 --fast

# Batch trim all files
mediaproc audio trim folder/ -s 10 -d 30 -o output/

Options:

  • -o, --output <path> - Output file/directory
  • -s, --start <time> - Start time (HH:MM:SS or seconds)
  • -e, --end <time> - End time (HH:MM:SS or seconds)
  • -d, --duration <time> - Duration from start
  • --fade-in <seconds> - Fade-in duration
  • --fade-out <seconds> - Fade-out duration
  • --fast - Fast mode (stream copy)

merge - Concatenate Audio

Join multiple audio files into one continuous file.

# Basic merge
mediaproc audio merge audio1.mp3 audio2.mp3 audio3.mp3

# Merge with custom output
mediaproc audio merge part*.mp3 -o complete.mp3

# Merge with crossfade
mediaproc audio merge song1.mp3 song2.mp3 --crossfade 2

# Merge with normalization
mediaproc audio merge *.wav --normalize -o normalized.wav

# Merge to different format
mediaproc audio merge *.wav -o output.flac --format flac

Options:

  • -o, --output <path> - Output file (default: merged.mp3)
  • --format <format> - Output format
  • --bitrate <bitrate> - Output bitrate
  • --crossfade <seconds> - Crossfade duration between files
  • --normalize - Normalize audio levels before merging

normalize - Loudness Normalization

Normalize audio levels using EBU R128 loudness standard for consistent volume.

# Normalize to broadcast standard (-16 LUFS)
mediaproc audio normalize audio.mp3

# Normalize to streaming standard (-23 LUFS)
mediaproc audio normalize audio.mp3 -t -23

# Custom target loudness
mediaproc audio normalize audio.mp3 -t -16 -l -1.0

# Simple peak normalization
mediaproc audio normalize audio.mp3 -m peak

# Batch normalize folder
mediaproc audio normalize folder/ -o output/

Options:

  • -o, --output <path> - Output file/directory
  • -t, --target <lufs> - Target loudness in LUFS (default: -16)
  • -l, --max-level <db> - Maximum true peak in dB (default: -1.5)
  • -m, --method <method> - Method: loudnorm (EBU R128), peak
  • --format <format> - Output format

LUFS Standards:

  • -16 LUFS - Broadcast standard (TV, radio)
  • -23 LUFS - Streaming platforms (Spotify, YouTube)
  • -14 LUFS - Apple Music, Tidal

Format Support

Format Extension Type Codec Best For
MP3 .mp3 Lossy libmp3lame Universal compatibility
AAC .aac, .m4a Lossy aac Modern devices, streaming
WAV .wav Lossless pcm_s16le Professional editing
FLAC .flac Lossless flac Archival, lossless quality
OGG .ogg Lossy libvorbis Open-source projects
Opus .opus Lossy libopus Voice, low bandwidth

Quality Guidelines

Bitrate Recommendations

Quality MP3 AAC Opus Use Case
Low 96k 64k 48k Voice, podcasts
Medium 192k 128k 96k General music
High 320k 256k 128k High-quality distribution

Sample Rates

  • 44100 Hz - CD quality (default for most content)
  • 48000 Hz - Professional audio, video production
  • 96000 Hz - High-resolution audio

Common Workflows

Podcast Production

# Extract audio from video recording
mediaproc audio extract recording.mp4 -f mp3 -b 128k --channels 1

# Normalize levels
mediaproc audio normalize recording-audio.mp3 -t -16

# Trim intro/outro
mediaproc audio trim recording-audio-normalized.mp3 -s 10 --duration 3600

Music Production

# Convert to lossless for editing
mediaproc audio convert track.mp3 -f wav -q lossless

# Merge multiple takes
mediaproc audio merge take1.wav take2.wav take3.wav --normalize

# Export final master
mediaproc audio convert merged.wav -f flac -q lossless

Video Production

# Extract audio from video
mediaproc audio extract video.mp4 -f wav

# Clean up audio
mediaproc audio normalize video-audio.wav -t -16

# Trim to match video
mediaproc audio trim video-audio-normalized.wav -s 0 -e 00:05:30

Advanced Examples

Batch Processing

# Convert all WAV files to MP3
for file in *.wav; do
  mediaproc audio convert "$file" -f mp3 -b 320k
done

# Or use folder processing
mediaproc audio convert wav-files/ -f mp3 -b 320k -o mp3-files/

Creating Audio Montage

# Merge with crossfades and normalization
mediaproc audio merge \
  intro.mp3 \
  main-content.mp3 \
  outro.mp3 \
  --crossfade 2 \
  --normalize \
  -o final-montage.mp3

Format Migration

# Migrate entire music library from MP3 to FLAC
mediaproc audio convert music-library/ \
  -f flac \
  -q lossless \
  -o flac-library/

Troubleshooting

FFmpeg Not Found

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt install ffmpeg

# Windows (via Chocolatey)
choco install ffmpeg

Audio Quality Issues

  • Use lossless formats (WAV, FLAC) for intermediate processing
  • Avoid multiple lossy conversions (MP3 → AAC → OGG)
  • Use higher bitrates (320k) for final distribution
  • Enable normalization for consistent loudness

Merge Compatibility Issues

Different formats may require re-encoding:

# Force re-encoding with specific format
mediaproc audio merge *.* --format mp3 --bitrate 192k

Performance Tips

  • Use --fast mode for large trim operations
  • Enable batch processing for multiple files
  • Consider hardware acceleration for video extraction
  • Use appropriate quality settings (avoid overkill)

License

MIT

Contributing

Issues and PRs welcome at mediaproc-cli