audio-to-vizualization

Audio to Visualization

The purpose of this small Python script is to transform an audio file into a video using a background image and an audio visualizer. This tool was written leveraging ffmpeg and requires it be installed and accessible via the ffmpeg command on the command line.

FFMPEG

Download ffmpeg and get access to the documentation at https://www.ffmpeg.org/

Requirements

Install via pip:

pip install -r requirements.txt

Run the script

python audio_to_visualization/audio_to_visualization.py <arguments>

Command line arguments

Argument	Description	Required	Default
--audio	path to audio file to visualize	true	N/A
--background	path to image to use for background	true	N/A
--output	path and name of output file. Must end in .mp4	true	N/A
--vis-background-to-vid-ratio	ratio of visualization background height to input image height (0.0-1.0)	false	0.2
--vis-waves-to-vid-ratio	ratio of visualization waves height to input image height (0.0-1.0)	false	0.15
--vis-color	color for visualization waveforms. can be used multiple times	false	"0xffffff"
--vis-color-opacity	opacity of vis colors (0.0-1.0)	false	0.9
--background-color	background color for visualization waveforms	false	"0x000000"
--background-color-opacity	opacity for visualization background color (0.0-1.0)	false	0.5
--aspect-ratio	crop/resize image to aspect ratio with minimal loss (format: W:H, e.g., 3:2, 16:9)	false	none
--test-frames	output only N frames for testing (e.g., 50 for ~2 seconds at 25fps)	false	none
--bg-effect	enable audio-reactive background effects (zoom, movement, blur)	false	false
--bg-zoom	base zoom level for background effect (0.0-1.0, default 0.1 = 10% zoom)	false	0.1
--bg-movement	movement intensity for background effect (0.0-1.0)	false	0.02
--bg-blur	blur intensity for background effect (0.0-1.0, 0.0 = no blur)	false	0.0

Examples

Basic usage

python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output video.mp4

With aspect ratio cropping

python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output video.mp4 \
  --aspect-ratio 16:9

With background effects

python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output video.mp4 \
  --bg-effect \
  --bg-zoom 0.15 \
  --bg-movement 0.03

Quick test (limited frames)

python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output test.mp4 \
  --test-frames 50

Full featured example

python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output video.mp4 \
  --aspect-ratio 3:2 \
  --vis-color 0xff5500 0x00ff55 \
  --vis-color-opacity 0.8 \
  --background-color 0x222222 \
  --background-color-opacity 0.6 \
  --bg-effect \
  --bg-zoom 0.1 \
  --bg-movement 0.02 \
  --bg-blur 0.05

Features

• Audio waveform visualization: Displays animated waveforms synced to the audio
• Customizable colors: Set waveform and background colors with opacity control
• Aspect ratio cropping: Automatically crop images to target aspect ratios (e.g., 16:9, 3:2) with minimal image loss using center crop
• Background effects: Optional smooth panning/movement effect with zoom and blur
• Test mode: Generate short clips for quick testing