# tetraslam/shfla architecture

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

- Interactive diagram: https://gitdiagram.com/tetraslam/shfla
- Repository: https://github.com/tetraslam/shfla

## Overview

Key Components to Include:

##### Input Layer
- A YouTube downloader component (yt-dlp integration)
- An audio file input processor (ffmpeg component)

##### Audio Processing Pipeline
a. Pitch Analysis (Fundamental Frequency)
b. Spectral Centroid Calculator
c. Chroma Feature Extractor (Pitch Class Profile)

##### Fractal Generation Engine
- Julia Set generator component
- Parameter mapping modules connecting audio features to fractal parameters:
- Pitch → Complex parameter c
- Spectral Centroid → max_iter

##### Visualization Layer
- Pygame rendering engine
- Synchronization controller between audio and visuals
- Output component

Design Guidelines:

**[User Input] → [YouTube Downloader] → [Audio Processor]**
- ↓
**[Audio Feature Extractors] ←→ [Parameter Mapping]**
- ↓
**[GPU-Accelerated Julia Set Generator] → [Visualization Engine]**
- ↓
- [Display Output]

##### Real-Time Processing
- A feedback loop for real-time visualization updates

##### Performance Optimization
- GPU acceleration paths with distinct markers
- Parallel processing capabilities where applicable

##### Resource Management
- Memory buffers between major processing stages
- Where CUDA optimization occurs

##### Error Handling
- Error handling components for input validation
- Fallback paths for non-GPU systems

## Diagram (Mermaid)

```mermaid
graph TB
    %% Define styles
    classDef input fill:#a8d1f0,stroke:#000
    classDef audio fill:#90EE90,stroke:#000
    classDef gpu fill:#FFB6C1,stroke:#000
    classDef viz fill:#DDA0DD,stroke:#000
    classDef storage fill:#F0E68C,stroke:#000
    classDef external fill:#D3D3D3,stroke:#000

    %% Input Layer
    subgraph Input
        UI[User Input]
        YT["YouTube Downloader<br/>(yt-dlp)"]
        AP["Audio Processor<br/>(ffmpeg)"]
    end

    %% Audio Processing Layer
    subgraph AudioProcessing
        AFE["Audio Feature Extraction"]
        PA["Pitch Analysis"]
        SC["Spectral Centroid"]
        CF["Chroma Features"]
    end

    %% Parameter Mapping
    subgraph Mapping
        PM["Parameter Mapping"]
        PTC["Pitch → c parameter"]
        SCM["Spectral → max_iter"]
        CHC["Chroma → Colors"]
    end

    %% GPU Processing
    subgraph GPUProcessing
        GPU["GPU Acceleration<br/>(CUDA/Numba)"]
        JSG["Julia Set Generator"]
    end

    %% Visualization
    subgraph Visualization
        PE["Pygame Engine"]
        SYNC["Sync Controller"]
        OUT["Display Output"]
    end

    %% Connections
    UI --> YT
    YT --> AP
    AP --> AFE
    AFE --> PA & SC & CF
    PA --> PTC
    SC --> SCM
    CF --> CHC
    PTC & SCM & CHC --> JSG
    GPU --- JSG
    JSG --> PE
    PE --> SYNC
    SYNC --> OUT
    AP -.-> SYNC

    %% Click events
    click OUT "https://github.com/tetraslam/shfla/tree/main/images/"
    click UI "https://github.com/tetraslam/shfla/blob/main/main.py"

    %% Legend
    subgraph Legend
        L1["Input Components"]:::input
        L2["Audio Processing"]:::audio
        L3["GPU Components"]:::gpu
        L4["Visualization"]:::viz
    end

    %% Style Applications
    class UI,YT,AP input
    class AFE,PA,SC,CF audio
    class GPU,JSG gpu
    class PE,SYNC,OUT viz
    class PTC,SCM,CHC audio
```
