# alexsaadfalcon/cpp_music_viz architecture

> Architecture diagram of the GitHub repository alexsaadfalcon/cpp_music_viz, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-12). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alexsaadfalcon/cpp_music_viz
- Repository: https://github.com/alexsaadfalcon/cpp_music_viz

## Overview

##### Project type and purpose
- This is a standalone C++ desktop application (“Fractal Music Vizualizer”) that ties real-time audio analysis (FFT) to GPU‐based fractal rendering (Mandelbrot/Julia) via OpenGL.
- Its primary goal is to load a .wav track, compute an FFT on the audio stream, and drive fractal parameters in shaders to produce a music‐synchronized visualizer.

##### File structure
- Top‐level source:
- main.cpp — application entry and main loop
- sfml_sound.cpp — audio loading & playback (SFML Sound)
- fft2d.cc — FFT implementation
- mandel_julia.cpp + Shader.h + .glsl files — fractal engine & shader loader
- config_file.txt — runtime config (select .wav file)
- Build & config:
- CMakeLists.txt + install.sh — bootstrap CMake build, install deps
- lib/{glfw,glew,glad} — vendored OpenGL context, extension loaders
- Assets:
- bensound_*.wav — sample audio files
- examples/ — demo media

##### README
- Confirms Linux / Mac support via CMake
- Usage: ./install.sh → build; run build/musicViz; edit config_file.txt to swap tracks
- No external services or network; purely local compute & render

##### Main components
a. Audio Subsystem
– SFML Sound module reads the WAV file (config_file.txt)
– Outputs PCM samples to the FFT module
b. FFT Module
– fft2d.cc consumes PCM data, computes spectral bands
– Emits time‐bucketed amplitude data
c. Fractal Engine
– Prepares uniform data for GPU
d. Shader Pipeline
– .glsl files (mandel_julia_shader.glsl, complex_shader.glsl, etc.) loaded via Shader.h
– Vertex & fragment stages implement fractal drawing on the GPU
e. Rendering Engine & Window Context
– GLFW initializes window and GL context
– GLEW/GLAD load OpenGL function pointers
f. Configuration & Assets
– config_file.txt, WAV files, shader files live on disk
– Loaded at startup or hot‐reloaded as needed
g. Build System (CMake)
– CMakeLists.txt invokes compiler, links SFML, OpenGL, lib/{glfw,glew,glad}

##### Relationships & data flow
1. Startup → install.sh / CMake config → binary built
2. Run → read config_file.txt → SFML loads WAV
3. Audio → PCM stream → FFT → spectral data
4. Spectral data → parameter updates → Fractal Engine
5. Fractal Engine → set shader uniforms → GPU pipeline
6. GPU → fragment shader renders fractal to screen via GLFW window
7. Loop back for next audio frame

##### Architectural patterns & design principles
- Modular separation: Audio I/O, signal processing (FFT), rendering logic, and resource management are separate modules.
- GPU‐accelerated compute: heavy work (fractal iteration) pushed into fragment shader.
- Single‐process, event‐driven main loop (typical game/graphics app pattern).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        CMake["CMakeLists.txt"]:::resource
        Install["install.sh"]:::resource
        FindSFML["FindSFML.cmake"]:::resource
    end
    CMake -->|configures| Install
    Install -->|bootstraps build| Binary["MusicViz Binary"]:::cpu

    %% Runtime
    config["config_file.txt"]:::resource
    config --> AudioSub
    AudioSub["Audio Subsystem (SFML)"]:::cpu
    FFT["FFT Module (fft2d.cc)"]:::cpu
    Fractal["Fractal Engine (mandel_julia.cpp)"]:::cpu
    ShaderLoader["Shader Loader Utility (Shader.h)"]:::cpu

    AudioSub -->|PCM stream| FFT
    FFT -->|spectral data| Fractal
    Fractal -->|uniform data| ShaderLoader

    %% Shader Files
    subgraph "Shader Files"
        MS["mandel_julia_shader.glsl"]:::resource
        CS["complex_shader.glsl"]:::resource
        DS["dft_shader.glsl"]:::resource
        QF["quad.f.glsl"]:::resource
        TVS["texture_vs.glsl"]:::resource
        TFS["texture_fs.glsl"]:::resource
    end
    MS --> ShaderLoader
    CS --> ShaderLoader
    DS --> ShaderLoader
    QF --> ShaderLoader
    TVS --> ShaderLoader
    TFS --> ShaderLoader

    %% GPU Pipeline
    GPU["GPU Pipeline (Vertex & Fragment Shaders)"]:::gpu
    ShaderLoader --> GPU

    %% Rendering Engine & Window Context
    subgraph "Rendering Engine & Window Context"
        MainLoop["main.cpp"]:::cpu
        GLADLoader["glad.c"]:::lib
        GLFWLib["lib/glfw/"]:::lib
        GLEWLib["lib/glew/"]:::lib
        GLADLib["lib/glad/"]:::lib
    end
    Fractal --> MainLoop
    GPU --> MainLoop
    GLADLoader --> MainLoop
    GLFWLib --> MainLoop
    GLEWLib --> MainLoop
    GLADLib --> MainLoop

    MainLoop -->|"draw call"| Display["Screen Output"]:::resource

    %% Click Events
    click AudioSub "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/sfml_sound.cpp"
    click FFT "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/fft2d.cc"
    click Fractal "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/mandel_julia.cpp"
    click ShaderLoader "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/Shader.h"
    click MS "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/mandel_julia_shader.glsl"
    click CS "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/complex_shader.glsl"
    click DS "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/dft_shader.glsl"
    click QF "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/quad.f.glsl"
    click TVS "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/texture_vs.glsl"
    click TFS "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/texture_fs.glsl"
    click MainLoop "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/main.cpp"
    click GLADLoader "https://github.com/alexsaadfalcon/cpp_music_viz/blob/master/glad.c"
    click GLFWLib "https://github.com/alexsaadfalcon/cpp_music_viz/tree/master/lib/glfw/"
    click GLEWLib "https://github.com/alexsaadfalcon/cpp_music_viz/tree/master/lib/glew/"
    click GLADLib "https://github.com/alexsaadfalcon/cpp_music_viz/tree/master/lib/glad/"

    %% Styles
    classDef cpu fill:#cfe2f3,stroke:#2a5d84,color:#0b2242;
    classDef resource fill:#d9ead3,stroke:#3c763d,color:#274e13,shape:parallelogram;
    classDef lib fill:#fce5cd,stroke:#b85400,color:#7f3700,shape:cylinder;
    classDef gpu fill:#e4d7f5,stroke:#5f259f,color:#3a0c57,shape:trapezoid;
```
