https://github.com/bcc-code/bcc-media-audio-vizualizer
Simple python container to generate video vizualization of an audio file
https://github.com/bcc-code/bcc-media-audio-vizualizer
Last synced: 29 days ago
JSON representation
Simple python container to generate video vizualization of an audio file
- Host: GitHub
- URL: https://github.com/bcc-code/bcc-media-audio-vizualizer
- Owner: bcc-code
- Created: 2025-09-01T10:11:54.000Z (10 months ago)
- Default Branch: master
- Last Pushed: 2025-09-01T12:20:51.000Z (10 months ago)
- Last Synced: 2025-09-01T12:38:51.942Z (10 months ago)
- Language: Python
- Size: 18.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Music Visualizer Video Generator
A Python-based music visualizer that creates stunning bar-style visualizations and renders them to video files. Available as both a command-line tool and REST API service.
## Features
- **Bar-style visualization** with frequency-responsive heights
- **Beautiful color gradients** from magenta through purple, blue, cyan, to red/orange
- **High-quality video output** with customizable resolution and frame rate
- **Audio synchronization** with automatic audio track addition
- **Optimized rendering** with pre-computed spectrum analysis
- **REST API** with background job processing
## Installation
1. Install Python dependencies:
```bash
pip install -r requirements.txt
```
2. Install FFmpeg (required for audio integration):
- **macOS**: `brew install ffmpeg`
- **Ubuntu/Debian**: `sudo apt install ffmpeg`
- **Windows**: Download from https://ffmpeg.org/
## Usage
### Command Line Usage
#### Basic Usage
```bash
python video_visualizer.py input_audio.mp3
```
#### Advanced Options
```bash
python video_visualizer.py input_audio.mp3 -o my_visualization.mp4 -w 1920 -b 1080 -f 60
```
#### Parameters
- `input_audio`: Path to your audio file (MP3, WAV, FLAC, OGG supported)
- `-o, --output`: Output video filename (default: visualization.mp4)
- `-w, --width`: Video width in pixels (default: 1920)
- `-b, --height`: Video height in pixels (default: 1080)
- `-f, --fps`: Video frame rate (default: 50)
- `--no-audio`: Generate video without audio track
#### Examples
Create a 4K visualization at 60fps:
```bash
python video_visualizer.py song.mp3 -o song_4k.mp4 -w 3840 -b 2160 -f 60
```
Generate silent video (video only):
```bash
python video_visualizer.py song.mp3 -o silent_viz.mp4 --no-audio
```
### REST API Usage
Start the Flask server:
```bash
python app.py
```
The API will be available at `http://localhost:5000`
#### API Endpoints
**POST /api/visualize**
Create a visualization job from a local audio file.
Request body:
```json
{
"audio_path": "/path/to/audio.mp3",
"output_path": "/path/to/output.mp4",
"width": 1920,
"height": 1080,
"fps": 50,
"include_audio": true
}
```
Response:
```json
{
"job_id": "uuid-string",
"status": "pending",
"message": "Visualization job started",
"output_path": "/path/to/output.mp4"
}
```
**GET /api/status/{job_id}**
Check the status of a visualization job.
Response:
```json
{
"job_id": "uuid-string",
"status": "completed",
"progress": 100,
"message": "Visualization completed successfully",
"output_file": "/path/to/output.mp4",
"created_at": 1234567890
}
```
**GET /api/jobs**
List all jobs.
**GET /api/health**
Health check endpoint.
#### Job Status Values
- `pending`: Job created but not started
- `processing`: Job is currently running
- `completed`: Job finished successfully
- `failed`: Job encountered an error
## How It Works
1. **Audio Analysis**: Uses librosa to perform Short-Time Fourier Transform (STFT) on the input audio
2. **Frequency Mapping**: Maps frequency data to visual bars with emphasis on lower frequencies (up to 8kHz)
3. **Color Generation**: Creates smooth color gradients across 120 bars
4. **Frame Generation**: Renders each video frame with PIL for precise drawing
5. **Video Encoding**: Uses OpenCV to encode frames and FFmpeg to add audio
## Technical Details
- **Bars**: 30 frequency bars across the width
- **Frequency Range**: 0-8kHz (optimized for music visualization)
- **Color Palette**: White bars on black background with optional gradient support
- **Audio Processing**: 44.1kHz sample rate with 8192-point FFT
- **Video Codec**: MP4V with AAC audio
## Troubleshooting
### Common Issues
**"Error: Could not open video writer"**
- Ensure you have write permissions in the output directory
- Try a different output filename
**"Warning: Could not add audio"**
- Install FFmpeg: the visualizer needs it to combine video and audio
- Check that FFmpeg is in your system PATH
**Slow rendering**
- Reduce resolution with `-w` and `-b` parameters
- Lower frame rate with `-f` parameter
- Use shorter audio files for testing
### Performance Tips
- **Resolution vs Speed**: 1920x1080 @ 50fps renders much faster than 4K @ 60fps
- **Audio Length**: 3-minute songs typically take 2-5 minutes to render
- **Memory Usage**: Longer songs require more RAM for spectrum analysis
## License
This project is open source. Feel free to modify and distribute.