# jberg/butterchurn architecture

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

- Interactive diagram: https://gitdiagram.com/jberg/butterchurn
- Repository: https://github.com/jberg/butterchurn

## Overview

##### Project Type and Purpose
- Purpose: Butterchurn is a client-side audio visualizer that uses WebGL to implement a MilkDrop-style effect. The README shows how to integrate the visualizer into web applications, load presets, and connect audio nodes.
- Main Use Case: Being a library for music visualization, it processes audio input, applies visual effects (using shaders and WebGL) and supports numerous customizable presets.

##### Analyzing the File Structure
- Top-Level Files:
– Configuration files (.eslintrc, .gitignore, webpack.config.js) and package management files indicate a well-structured JavaScript project.
- Directories:
– “src”: Contains the core application code. Subdirectories like “audio”, “rendering”, “equations”, “noise”, “image”, and “visualizer.js” indicate separation of concerns.
▪ The “audio” directory includes modules for audio processing (audioLevels, fft, audioProcessor) that process the audio signal.
▪ “equations” and “presetBase” point to the management and execution of presets, possibly involving both JavaScript and WASM (see presetEquationRunnerWASM.js).
▪ “assemblyscript” under both src and loaders indicate usage of AssemblyScript (WASM code) for performance-critical functions.
– “experiments”: Contains subprojects like “wasm-eel” with numerous preset files. This shows active experimentation with new presets and WASM-based functionality, as well as performance tests (e.g., the “speed” subdirectory).
– “loaders”: Contains custom loader scripts (e.g., assemblyscript.js) that probably handle dynamic imports or WASM module initialization.
– “config” and “netlify.toml”: Provide settings for building and deployment.
- Observed Patterns:
– Separation between audio processing, visual rendering (WebGL and shaders), equations/preset management, and experimental presets.
– Use of experiments to maintain various presets and blending techniques, the layering of visual effects using WebGL shader pipelines, and integration with different external Web APIs and frameworks.

##### Additional Details
- Be very detailed in capturing the entire flow: how presets can be loaded, blended (the visualizer.loadPreset function), and how the renderer resizes and renders new frames.
- Integration with external tools (the README lists integrations with Webamp, browser extension, etc.), though not part of the core library, they provide context for ecosystem use.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Integration & Initialization
    subgraph "Integration & Initialization"
        AE["App Entry"]:::integration
        VI["Visualizer Initialization"]:::integration
    end

    %% Audio Processing Module
    subgraph "Audio Processing"
        AP["Audio Input & Processing Module"]:::audio
    end

    %% Presets & Equations Engine
    subgraph "Presets & Equations Engine"
        ER["Equation Runner (JS/WASM)"]:::preset
        PB["Preset Base"]:::preset
    end

    %% Rendering Pipeline
    subgraph "Rendering Pipeline"
        RE["Rendering Engine"]:::render
        SH["Shaders"]:::render
        SP["Sprites"]:::render
        TX["Text Rendering"]:::render
        WF["Waveforms"]:::render
        SHP["Shapes"]:::render
    end

    %% Loaders & Configuration
    subgraph "Loaders & Configuration"
        AL["AssemblyScript Loader"]:::loader
        WC["Webpack Config"]:::loader
    end

    %% Experiments & Presets Library
    EX["Experiments & Presets Library"]:::experiment

    %% Connections
    AE --> VI
    VI --> AP
    VI --> RE
    AL --> VI
    WC --> VI

    AP --> ER
    AP --> PB

    EX --> ER
    EX --> PB

    ER --> RE
    PB --> RE

    RE --> SH
    RE --> SP
    RE --> TX
    RE --> WF
    RE --> SHP

    %% Styles
    classDef audio fill:#f9c74f,stroke:#000,stroke-width:1px;
    classDef preset fill:#90be6d,stroke:#000,stroke-width:1px;
    classDef render fill:#577590,stroke:#000,stroke-width:1px,color:#fff;
    classDef integration fill:#277da1,stroke:#000,stroke-width:1px,color:#fff;
    classDef loader fill:#6a4c93,stroke:#000,stroke-width:1px,color:#fff;
    classDef experiment fill:#f3722c,stroke:#000,stroke-width:1px,color:#fff;

    %% Click Events
    click AP "https://github.com/jberg/butterchurn/tree/master/src/audio"
    click ER "https://github.com/jberg/butterchurn/tree/master/src/equations"
    click PB "https://github.com/jberg/butterchurn/blob/master/src/presetBase.js"
    click RE "https://github.com/jberg/butterchurn/blob/master/src/rendering/renderer.js"
    click SH "https://github.com/jberg/butterchurn/tree/master/src/rendering/shaders"
    click SP "https://github.com/jberg/butterchurn/tree/master/src/rendering/sprites"
    click TX "https://github.com/jberg/butterchurn/tree/master/src/rendering/text"
    click WF "https://github.com/jberg/butterchurn/tree/master/src/rendering/waves"
    click SHP "https://github.com/jberg/butterchurn/tree/master/src/rendering/shapes"
    click VI "https://github.com/jberg/butterchurn/blob/master/src/visualizer.js"
    click AE "https://github.com/jberg/butterchurn/blob/master/src/index.js"
    click AL "https://github.com/jberg/butterchurn/blob/master/loaders/assemblyscript.js"
    click WC "https://github.com/jberg/butterchurn/blob/master/config/webpack.config.js"
    click EX "https://github.com/jberg/butterchurn/tree/master/experiments/wasm-eel"
```
