rspektrum/SPECTROGRAM_README.md

Spectrogram Viewer (C/Raylib)

A real-time spectrogram viewer ported from the Unity Audio-Experiments project, with interactive region selection and audio playback.

Features

• Spectrogram Visualization: Displays frequency content of audio over time using STFT
• Time & Frequency Selection: Select both time regions AND frequency ranges
• Audio Playback: Play back only the selected time region
• Multiple Colormaps: 6 different heat map styles
• Adjustable Threshold: Control the dB floor for visualization
• Drag & Drop: Load files by dragging them onto the window

Building

Linux

cd rspektrum/build
./premake5 gmake
cd ..
make

Running

cd rspektrum/bin/Debug
./rspektrum

Controls

Key	Action
O	Open file dialog
Drag & drop	Load WAV file
LMB Drag	Select time region
Shift+LMB Drag	Select frequency range
SPACE	Play selected time region
M	Cycle colormap
W/S	Adjust dB floor (up/down)
G	Toggle grid overlay
R	Reset all selections to full range
ESC	Stop playback / Cancel dialog

File Loading

Two ways to load a WAV file:

1. Drag & Drop: Simply drag a .wav file onto the application window
2. File Dialog: Press O to open a file path input dialog

Selection Modes

Time Selection (Left Mouse Button)

• Click and drag horizontally to select a time range
• The non-selected areas are greyed out
• Yellow borders indicate the selection boundaries

Frequency Selection (Shift + Left Mouse Button)

• Hold Shift and drag vertically to select a frequency range
• Cyan borders indicate the frequency selection
• Useful for isolating specific frequency bands

Colormaps

Press M to cycle through available colormaps:

1. Grays - Classic grayscale
2. Inferno - Dark purple to bright yellow (default)
3. Viridis - Purple to yellow (perceptually uniform)
4. Plasma - Purple to yellow-orange
5. Hot - Black to red to yellow to white
6. Cool - Cyan to magenta

Threshold Control

Use W and S keys to adjust the amplitude floor:

• W: Raise the floor (show only louder signals)
• S: Lower the floor (show quieter signals too)

The current dB floor is displayed in the bottom right corner.

Technical Details

STFT Parameters

• FFT Size: 2048 samples
• Hop Size: 1024 samples (50% overlap)
• Window: Hann window
• Frequency Resolution: sampleRate / 2048 Hz per bin

Audio Format Support

• WAV files (any sample rate)
• Automatically detected sample rate (displayed in info panel)
• 8-bit, 16-bit PCM, and 32-bit float supported
• Stereo files are converted to mono

Display

• X-axis: Time (seconds)
• Y-axis: Frequency (Hz), scaled to actual sample rate
• Color/brightness: Amplitude in dB

Project Structure

rspektrum/
├── src/
│   ├── spectrogram.c    # Main application (~1000 lines)
│   └── icon.ico         # Windows icon
├── libs/
│   └── ...              # Optional external libraries
├── build/
│   ├── premake5.lua     # Build configuration
│   └── external/        # Downloaded dependencies (raylib)
└── bin/
    ├── Debug/           # Debug build
    └── Release/         # Release build

Comparison: Unity vs C/Raylib

Aspect	Unity Original	C/Raylib Port
Lines of Code	~2000+ (multiple files)	~1000 (single file)
Build Time	Minutes	Seconds
Dependencies	Unity Editor, .NET	raylib only
GPU Acceleration	Compute shaders	CPU-based
Colormaps	Single gradient	6 presets
Freq Selection	No	Yes
Startup Time	Slow	Fast

Tips

1. For 16kHz audio: The max frequency will show as 8kHz (Nyquist)
2. Better visibility: Use Inferno or Viridis colormap for better contrast
3. Quiet signals: Lower the dB floor with 'S' to see quieter content
4. Isolate frequencies: Use Shift+drag to focus on specific frequency bands
5. Playback: Only the time selection is played, full frequency range

Future Improvements

• Logarithmic frequency scale option
• Zoom in/out on frequency axis
• Real-time microphone input
• Export selection as WAV
• Faster FFT (pffft/kissfft)
• Save/load presets

License

Based on Unity Audio-Experiments by Sebastian Lague (Coding Adventure series)

C/Raylib port created for educational purposes.