Video Waves

A Python CLI tool that turns audio files into waveform videos with hardware-accelerated encoding and an industrial aesthetic (white waveforms, mirrored shadows, subtle grain, scanlines, and gaussian zoom).

By default, output is rendered at 1440p / 60fps. Audio is muxed directly from the source file via FFmpeg without generational quality loss.

---

Requirements

• Python: >= 3.9
• FFmpeg: Required on your system PATH for video muxing and encoding.
  • macOS: brew install ffmpeg
  • Ubuntu/Debian: sudo apt install ffmpeg

---

Installation

Create and activate a virtual environment, then install the package:

python3 -m venv .venv
source .venv/bin/activate
pip install .

---

Usage

Single File

# Render to audio.mp4 in the same directory
video-waves path/to/audio.mp3

# Render with custom output path
video-waves path/to/audio.mp3 output.mp4

Batch Directory

# Render all audio files in a directory
video-waves path/to/audio_folder/

# Render all audio files to a specific output folder
video-waves path/to/audio_folder/ --out-dir path/to/output_folder/

Supported Formats

• .mp3, .wav, .flac, .aif, .aiff

Options

Flag	Default	Description
-d, --duration	full	Limit video duration in seconds
--fps	60	Output video framerate
--width	2560	Frame width in pixels
--height	1440	Frame height in pixels
--codec	h264_videotoolbox	Video encoder codec (h264_videotoolbox on Apple Silicon, libx264 on CPU/Linux)
-o, --out	None	Explicit output video file path (.mp4)
--out-dir	input dir	Output directory for batch or single exports
-v, --version	—	Display version
-h, --help	—	Display help message

---

How It Works

1. Waveform Analysis & Rendering: Librosa analyzes audio samples and RMS energy to compute the waveform coordinates, barrel curvature, and gaussian zoom focused on the playhead. MoviePy renders the silent video stream using hardware acceleration.
2. Audio Muxing: FFmpeg streams the original audio track into the container as AAC stereo (320 kbps, 48 kHz), preserving original audio fidelity without passing it through lossy intermediate conversions.

---

Development & Testing

Install development dependencies:

pip install -e ".[dev]"

Run test suite:

pytest