Skip to content

README.md

Latest commit

 

History

History
207 lines (158 loc) · 6.22 KB

README.md

File metadata and controls

207 lines (158 loc) · 6.22 KB
Raw

SoundGraph

Professional Audio Analysis and Visualization Platform

SoundGraph is a powerful web-based audio analysis tool specifically designed for DJs and music professionals. Built with advanced signal processing algorithms, it generates professional-grade audio visualizations comparable to industry-standard software including Serato DJ, Virtual DJ, Traktor Pro, and Ableton Live.

Features

Audio Visualizations

  • Multi-frequency Waveform Analysis - Color-coded waveform representation with precise frequency band separation (Bass/Red, Mid-range/Green, High frequencies/Blue)
  • Mel-Spectrogram Generation - AI-compatible audio-to-image representation optimized for generative audio models
  • Real-time Spectrogram Display - Dynamic frequency domain analysis with temporal progression
  • 3D Audio Landscape - Interactive three-dimensional topographic representation of audio characteristics

Technical Capabilities

  • Automatic BPM Detection - Precise tempo analysis utilizing advanced onset detection algorithms
  • Multi-format Audio Support - Comprehensive processing of MP3, WAV, M4A, and FLAC audio formats
  • RESTful API Architecture - FastAPI-powered backend delivering structured JSON responses
  • Optimized Real-time Processing - Efficient audio analysis engine with performance-tuned algorithms

Installation

Prerequisites

  • Python 3.8 or higher
  • pip package manager
  • Virtual environment (recommended)

Setup Instructions

  1. Clone the repository
git clone https://github.com/rodrigo-ds4/soundgraph.git
cd soundgraph
  1. Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
  1. Install dependencies
pip install -r requirements.txt
  1. Start the application
uvicorn main:app --host 0.0.0.0 --port 8001 --reload
  1. Access the application
http://localhost:8001

Usage

Web Interface

  1. Navigate to the web interface
  2. Upload audio file via drag-and-drop or file selector
  3. Wait for analysis processing (typically 2-5 seconds)
  4. View generated visualizations and BPM analysis

Desktop Application

For advanced 3D visualizations:

python run_desktop.py

Technical Architecture

Backend Stack

  • FastAPI - High-performance Python web framework
  • Librosa - Audio signal analysis and music information retrieval
  • NumPy/SciPy - Numerical computing and signal processing
  • Matplotlib - Static visualization generation
  • Plotly - Interactive web-based visualizations
  • PyVista - 3D scientific visualization (desktop app)

Frontend Stack

  • HTML5/CSS3 - Modern web standards
  • Vanilla JavaScript - No framework dependencies
  • Plotly.js - Interactive visualization rendering
  • Web Audio API - Client-side audio handling

Audio Processing Pipeline

  1. File Input - Multi-format audio file handling with ffmpeg integration
  2. Signal Processing - Librosa-based audio analysis with STFT computation
  3. Feature Extraction - BPM detection, frequency analysis, onset detection
  4. Visualization Generation - Multiple rendering engines for different output types
  5. Web Delivery - JSON API responses with embedded visualization data

Project Structure

soundgraph/
├── main.py                    # FastAPI application entry point
├── audio_processor.py         # Core audio analysis engine
├── audio_journey_3d.py        # 3D visualization processing
├── soundgraph_desktop.py      # Desktop GUI application
├── run_desktop.py             # Desktop application launcher
├── requirements.txt           # Python dependencies
├── templates/
│   └── index.html            # Web interface template
├── static/
│   ├── style.css            # Application styling
│   └── script.js            # Frontend JavaScript
└── README_DESKTOP.md        # Desktop application documentation

API Endpoints

POST /upload

Processes audio file and returns analysis data.

Request: Multipart form data with audio file Response: JSON with visualizations, BPM, and metadata

GET /health

Application health check endpoint.

Response: JSON status indicator

Development

Running in Development Mode

uvicorn main:app --reload --port 8001

Running Tests

python test_pyvista.py  # Test 3D visualization capabilities

Configuration

Audio Processing Parameters

  • Sample Rate: 22,050 Hz (optimized for music analysis)
  • FFT Window: 2048 samples
  • Hop Length: 256-512 samples (adaptive)
  • Mel Bands: 128-256 (for spectrograms, variable resolution)
  • Max File Size: 25MB for optimal performance

Performance Optimization

  • Efficient memory management for large audio files
  • Parallel processing for multiple visualization types
  • Caching for repeated analysis operations

Troubleshooting

Common Issues

ffmpeg not found

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows
Download from https://ffmpeg.org/download.html

Port already in use

# Change port in main.py or use command line
uvicorn main:app --port 8002

Memory issues with large files

  • File size limit: 25MB maximum (automatically enforced)
  • Use WAV format for fastest processing
  • MP3/M4A files are automatically converted to WAV
  • Ensure sufficient RAM (4GB+ recommended)

Future Development

Planned Features

  • Machine learning-based song similarity analysis
  • Advanced beat detection and rhythm analysis
  • Scientific audio metrics and reporting
  • Multi-track comparison and overlay
  • Export capabilities (JSON, CSV, PNG formats)

Technical Roadmap

  • WebAssembly integration for client-side processing
  • GPU acceleration for large file analysis
  • Real-time audio stream processing
  • Plugin architecture for custom visualizations

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Implement changes with appropriate tests
  4. Submit a pull request with detailed description

License

MIT License - Open source software for educational and commercial use.

Technical Support

For technical issues, please refer to the troubleshooting section above or create an issue in the project repository.