# 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
```bash
python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output video.mp4
```

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

### With background effects
```bash
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)
```bash
python audio_to_visualization/audio_to_visualization.py \
  --audio input.mp3 \
  --background image.jpg \
  --output test.mp4 \
  --test-frames 50
```

### Full featured example
```bash
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