initial commit

libraries/FastLED/examples/Audio/simple/README.md

@@ -0,0 +1,157 @@
+# Audio Reactive Visualization Example
+
+This example demonstrates advanced audio reactive visualization capabilities using FastLED. It processes real-time audio input and creates stunning visual effects synchronized to music.
+
+## Features
+
+### Visualization Modes
+
+1. **Spectrum Analyzer** - Classic frequency spectrum display with customizable colors
+2. **Waveform** - Real-time audio waveform visualization
+3. **VU Meter** - Traditional volume unit meter with RMS and peak indicators
+4. **Spectrogram** - Scrolling frequency analysis over time
+5. **Combined** - Split-screen showing both spectrum and waveform
+6. **Reactive Patterns** - Dynamic patterns that respond to audio energy and beats
+
+### Audio Processing
+
+- **Real-time FFT** - Fast Fourier Transform for frequency analysis
+- **Beat Detection** - Automatic beat detection with adjustable sensitivity
+- **Auto Gain Control (AGC)** - Automatically adjusts to varying audio levels
+- **Noise Floor Filtering** - Removes background noise for cleaner visuals
+- **Attack/Decay/Sustain** - Professional audio envelope controls
+
+### Visual Controls
+
+- **Multiple Color Palettes** - Heat, Rainbow, Ocean, Forest, Lava, Cloud, Party
+- **Mirror Mode** - Creates symmetrical displays
+- **Brightness Control** - Adjustable LED brightness
+- **Fade Effects** - Smooth transitions with adjustable fade time
+- **Color Animation** - Animated color cycling with speed control
+- **Smoothing** - Optional smoothing for less jittery displays
+
+### Advanced Features
+
+- **Frequency Band Analysis** - 8-band frequency analyzer for detailed audio analysis
+- **FFT Smoothing** - Temporal smoothing of frequency data
+- **Logarithmic Scale** - Optional log scale for frequency display
+- **Freeze Frame** - Pause the visualization at any moment
+- **Frame Advance** - Step through frozen frames
+
+## UI Controls
+
+### Main Controls
+- **Enable Audio Reactive Mode** - Master on/off switch for audio processing
+- **Visualization Mode** - Dropdown to select visualization type
+
+### Audio Processing Group
+- **Fade Time** - How quickly levels decay (0-4 seconds)
+- **Attack Time** - How quickly levels rise (0-4 seconds)
+- **Output Smoothing** - Final output smoothing (0-2 seconds)
+- **Audio Gain** - Manual gain adjustment (0.1-5.0)
+- **Noise Floor** - Background noise threshold (-80 to -20 dB)
+
+### Visual Controls Group
+- **Fade to Black** - Trail/persistence effect (0-50)
+- **Brightness** - LED brightness (0-255)
+- **Color Speed** - Animation speed (0.1-5.0)
+- **Color Palette** - Choose from 7 palettes
+- **Mirror Mode** - Enable symmetrical display
+- **Smoothing** - Enable temporal smoothing
+
+### FFT Controls Group
+- **Min Frequency** - Lower frequency bound (20-1000 Hz)
+- **Max Frequency** - Upper frequency bound (1000-20000 Hz)
+- **Logarithmic Scale** - Use log scale for frequency
+- **FFT Smoothing** - Smoothing factor (0-0.95)
+
+### Advanced Controls Group
+- **Freeze Frame** - Pause visualization
+- **Advance Frame** - Step forward when frozen
+- **Beat Detection** - Enable beat detection
+- **Beat Sensitivity** - Beat detection threshold (0.5-3.0)
+- **Auto Gain Control** - Enable automatic gain adjustment
+
+## Hardware Setup
+
+### LED Configuration
+- Default: 128x128 LED matrix (16,384 LEDs)
+- Downscaled to 64x64 for output (4,096 LEDs)
+- Data pin: GPIO 3 (configurable)
+- LED type: WS2812B (Neopixel)
+
+### Audio Input
+The example uses the FastLED audio system which can accept input from:
+- Microphone (real-time audio capture)
+- Audio file playback
+- System audio (on supported platforms)
+
+## Usage
+
+1. **Basic Operation**
+   - Upload the sketch to your controller
+   - Connect your LED matrix
+   - Provide audio input
+   - Use the web UI to control visualization
+
+2. **Optimizing for Your Setup**
+   - Adjust the noise floor if visualization is too sensitive/insensitive
+   - Use AGC for varying audio levels
+   - Tune beat sensitivity for your music style
+   - Experiment with different color palettes and speeds
+
+3. **Performance Tips**
+   - Reduce matrix size for slower controllers
+   - Disable smoothing for more responsive display
+   - Use simpler visualization modes for lower CPU usage
+
+## Code Structure
+
+### Main Components
+
+1. **Audio Processing Pipeline**
+   ```cpp
+   AudioSample → FFT → Band Analysis → Beat Detection → Visualization
+   ```
+
+2. **Visualization Functions**
+   - `drawSpectrumAnalyzer()` - Frequency spectrum bars
+   - `drawWaveform()` - Audio waveform display
+   - `drawVUMeter()` - Volume meter visualization
+   - `drawSpectrogram()` - Time-frequency plot
+   - `drawReactivePatterns()` - Beat-reactive patterns
+
+3. **Audio Analysis Classes**
+   - `MaxFadeTracker` - Smooth peak tracking with attack/decay
+   - `BeatDetector` - Energy-based beat detection
+   - `FrequencyBandAnalyzer` - 8-band frequency analysis
+
+## Customization
+
+### Adding New Visualizations
+1. Create a new draw function
+2. Add it to the visualization mode dropdown
+3. Add a case in the main switch statement
+
+### Modifying Color Palettes
+Edit the `getCurrentPalette()` function to add custom palettes.
+
+### Adjusting Frequency Bands
+Modify the `FrequencyBandAnalyzer` constructor to change band boundaries.
+
+## Troubleshooting
+
+- **No visualization**: Check audio input and ensure "Enable Audio Reactive Mode" is on
+- **Too dim/bright**: Adjust brightness control
+- **Choppy animation**: Increase smoothing or reduce matrix size
+- **No beat detection**: Adjust beat sensitivity or check audio levels
+- **Visualization too sensitive**: Increase noise floor value
+
+## Memory Requirements
+
+This example requires significant memory for:
+- Framebuffer: 128×128×3 = 49,152 bytes
+- LED buffer: 64×64×3 = 12,288 bytes
+- Audio buffers and FFT data
+
+Platforms with limited memory may need to reduce the matrix size.