# Oscilloscope Video Generator

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

![Demo](https://img.shields.io/badge/demo-coming%20soon-blue) ![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

```bash
# Install dependencies
sudo apt install ffmpeg    # Ubuntu/Debian
# or
brew install ffmpeg        # macOS

# Build and install
cargo install --git https://github.com/yourusername/oscilloscope-video-gen

# Generate video
oscilloscope-video-gen -i your_music.flac -o oscilloscope.mp4
```

## 🎮 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*