A real-time, optimized C++ audio visualizer for the Windows console.

System Architecture

Spectrum captures raw system audio directly from the soundcard, processes it through a real-time DSP pipeline, and renders it to the console without screen tearing.

%%{init: {'theme': 'base', 'themeVariables': { 'fontFamily': 'Comic Sans MS, Comic Neue, Chalkboard SE, cursive', 'lineColor': '#000000', 'primaryTextColor': '#000000', 'edgeLabelBackground':'#ffffff'}, 'flowchart': {'curve': 'basis'}}}%%
graph LR
    classDef default fill:#ffffff,stroke:#000000,stroke-width:2px,color:#000000
    
    subgraph T1 [Thread 1: Audio Capture]
        A([WASAPI]) --> B[Accumulate<br/>Audio]
        B --> C{2400<br/>Samples?}
        C -->|No| B
        C -->|Yes| D[Lock Mutex &<br/>Notify Ready]
        D -->|Reset Index| B
    end

    subgraph Shared [Shared State]
        M[(Thread-Safe<br/>readyBuffer)]
    end

    subgraph T2 [Thread 2: DSP & Render]
        E{Buffer<br/>Ready?}
        
        %% The true self loop (Mermaid will force this into a square)
        E -->|Wait| E
        
        E -->|Yes| F[Execute FFTW3<br/>& Decibel Math]
        F --> G[Group to a # of Bins]
        G --> H([Draw ASCII Bars<br/>Zero-Flicker])
        H --> I[Reset Flag]
        I -->|Loop| E
    end

    %% Data flow across threads
    D == Copy Data ==> M
    M == Read Data ==> E

Loading

The DSP Engine

At the core of the visualizer is the Discrete Fourier Transform (DFT), powered by the FFTW3 C-API.
The engine takes a time-domain window of audio samples and transforms it into a number of distinct frequency magnitudes.

$$X_k = \sum_{n=0}^{N-1} x_n e^{-i 2\pi k n / N}$$

To make the output visually accurate to human hearing:

1. Data Scrubbing: Acts as a firewall against WASAPI driver glitches, dropping inf, NaN, and integer overflows.
2. Decibel Conversion: Raw amplitudes are normalized and converted to a logarithmic $\text{log}_{10}$ scale.
3. Frequency Binning: The pitches are averaged down into a number visual UI bins, depending on the terminal size.

Performance

Benchmarked on an AMD Ryzen 5 7520U (2.80 GHz) at a 2400-sample window size:

Metric	Value
CPU usage	~0%
Memory footprint	0.4 MB

spectrum is designed to be lightweight, it should never compete with your music.

Quick Start (Casuals)

For those who just want to run the visualizer without compiling:

1. Download the latest release (v1.1.0) from the Releases Page.
2. Extract the ZIP file to your preferred location.
3. Run spectrum.exe.
4. Play some music and enjoy the show!

Getting Started

Prerequisites

• Windows 10/11
• CMake (v3.10+)
• FFTW3 (Pre-compiled binaries included in third_party/)
• OpenMP (Usually included with your compiler)

Building from Source (Contributors)

First, clone the repository:

git clone https://github.com/majockbim/spectrum
cd spectrum

Option 1: g++ (MinGW-w64)

Best for those using MSYS2 or a standalone MinGW installation.

# Generate build files
cmake -B build_mingw -G "MinGW Makefiles"

# Compile
cmake --build build_mingw

# Run!
.\build_mingw\spectrum.exe

Option 2: cl (MSVC Command Line)

Best for those who prefer the Microsoft C++ compiler but want to stay in the terminal.
Note: Because this uses the Visual Studio CMake generator, you can run these commands directly in standard PowerShell.

# Generate build files (Ensure x64 architecture)
cmake -S . -B build_msvc -G "Visual Studio 17 2022" -A x64

# Compile
cmake --build build_msvc --config Release

# Run!!
.\build_msvc\Release\spectrum.exe

Option 3: Visual Studio (MSVC IDE)

The easiest way for Windows developers.

1. Open Visual Studio.
2. Select Open a local folder and choose the spectrum directory.
3. Visual Studio will automatically detect CMakeLists.txt and configure the project.
4. Select spectrum.exe in the "Select Startup Item" dropdown.
5. Press F5 to build and run!!!

References & Libraries

Documentation & Readings:
WASAPI: IAudioEndpointVolume
WASAPI: audioclient.h
WASAPI: IAudioClient::Initialize [4]
Fast Fourier Transform (Wiki)

Third-Party Libraries:
FFTW (org)
FFTW (GitHub)

Contributors

A massive thank you to everyone who has helped build and optimize spectrum.
Check out Contributors Hall of Fame.