136 lines
3.2 KiB
Markdown
136 lines
3.2 KiB
Markdown
# Oscilloscope Video Generator
|
|
|
|
Transform any audio file into stunning oscilloscope visualizations. Supports massive files with zero memory issues.
|
|
|
|
|
|
|
|
## ✨ 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*
|