# Oscilloscope Video Generator

Transform any audio file into stunning oscilloscope visualizations. Supports massive files with zero memory issues.

![License](https://img.shields.io/badge/license-AGPL--3.0--or--later-green)

## ✨ Key Features

- **🎵 Universal Audio Support** - FLAC, MP3, WAV, AAC, and 200+ formats via ffmpeg
- **🚀 Streaming Architecture** - Processes huge files without filling RAM or SSD
- **📊 Professional Spectrometer** - FFT analyzer with smooth Cava-style animations
- **🎯 4-Quadrant Display** - Waveforms + XY pattern + spectrometer in one video
- **🎬 High Quality Output** - 4K 60fps support with customizable colors
- **⚡ Memory Efficient** - Constant RAM usage regardless of file size

## 🚀 Quick Start

### 1. Install System Dependencies

**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg
```

**macOS:**
```bash
brew install ffmpeg
```

**Windows:**
```bash
# Via winget (recommended)
winget install ffmpeg

# Or download from https://ffmpeg.org/download.html
# Make sure ffmpeg is in your PATH
```

### 2. Build the Project

```bash
# If you have the source code locally:
cd /path/to/oscilloscope-video-gen

# Build in release mode (much faster)
cargo build --release

# The binary will be at: target/release/oscilloscope-video-gen
```

### 3. Generate Your First Video

```bash
# Basic usage - replace 'audio.wav' with your audio file
./target/release/oscilloscope-video-gen -i audio.wav -o oscilloscope.mp4

# Check available options
./target/release/oscilloscope-video-gen --help
```

## 🎮 Usage Examples

### Basic Usage
```bash
oscilloscope-video-gen -i audio.wav -o video.mp4
```

### High Quality 4K Output
```bash
oscilloscope-video-gen \
  -i audio.flac \
  -o video.mp4 \
  --width 3840 --height 2160 --fps 60 \
  --mode all \
  --quality high
```

### Custom Styling
```bash
oscilloscope-video-gen \
  -i audio.mp3 \
  -o video.mp4 \
  --left-color "#ff0080" \
  --right-color "#8000ff" \
  --background "#000000" \
  --line-thickness 3
```

## 🎛️ Visualization Modes

- **`all`** (default) - 4 quadrants: L/R waveforms + XY pattern + spectrometer
- **`combined`** - Single merged waveform
- **`separate`** - Left channel top, right channel bottom

## 🏗️ How It Works

This tool uses a **streaming pipeline** that pipes audio decoding directly to video encoding, eliminating temporary files and memory issues. The FFT spectrometer provides real-time frequency analysis with logarithmic scaling and temporal smoothing for smooth animations.

**No file size limits** - handles anything ffmpeg can decode, from tiny samples to 24-hour recordings.

## 📋 Requirements

- **Rust 1.70+**
- **ffmpeg** (with libavcodec, libavformat, libswresample)

## 🔧 Troubleshooting

### ffmpeg not found
```bash
# Ubuntu/Debian
sudo apt install ffmpeg

# macOS
brew install ffmpeg

# Windows (via winget or chocolatey)
winget install ffmpeg
```

### File Format Issues
If your audio file isn't recognized:
```bash
# Check if ffmpeg can decode it
ffmpeg -i your_file.ext -f null -
```

## 📄 License

**AGPL-3.0-or-later** - Free software that respects your freedom.

See [LICENSE](LICENSE) for full terms.

---

*Made with ❤️ using Rust and ffmpeg*