# fred-brenner/infernosaber---beatsaber-automapper architecture

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

- Interactive diagram: https://gitdiagram.com/fred-brenner/infernosaber---beatsaber-automapper
- Repository: https://github.com/fred-brenner/infernosaber---beatsaber-automapper

## Overview

##### Project Type & Purpose
- InfernoSaber is a Python-based AI pipeline that automaps Beat Saber tracks.
- It supports two main flows:
a. Inference (generate maps from audio + existing map data)
b. Training (train the four AI sub-models locally)

##### Main Components
A. User Interface Layer
- Pinokio Web App (main_app.py branch)
- CLI Entrypoints (main.py, main_multi.py, main_training.py)
B. Orchestrator & Configuration
- app_helper/ — path resolution, environment setup
- tools/config/ — folder structure checks, parameter definitions
C. Data Ingestion & Preprocessing
- preprocessing/ — audio loading, BPM detection, map metadata parsing
D. Inference Pipeline
1. Deep Conv Autoencoder (beat_prediction/ai_beat_gen.py)
2. TCN Beat Predictor (beat_prediction/tf_lighting.py in lighting_prediction for lights)
3. & Obstacle Classification (map_creation/ → gen_beats, gen_sliders, gen_obstacles)
4. Lighting/Event Classification (lighting_prediction/)
E. Post-Processing & Export
- bs_shift/ — map time-shifting, sanitization, export to Beat Saber JSON format
F. Model Storage & Retrieval
- Remote: HuggingFace (tools/utils/huggingface.py)
- Local cache under user’s home directory
G. Training & Evaluation
- training/ — model training scripts, TensorFlow model definitions
- evaluation/ — scripts to benchmark beat-finding and model accuracy
H. Utilities
- tools/utils/ — I/O helpers, string matching, parameter prompting, etc.

##### Component Relationships & Data Flow
User → (CLI or Pinokio App)
↓
Orchestrator
├→ load config (tools/config + app_helper)
↓
Preprocessing
- audio → beat_data_helper → feature vectors
- existing map JSON → map_info_processing
↓
Inference Pipeline
1. Autoencoder compresses features
↓
2. TCN predicts beat timestamps
↓
3. Generator classifies notes/obstacles
↓
4. Lighting model classifies light events
↓
Post-Processing
- note_postprocessing, BPM optimization
- sanity_check
↓
bs_shift
- adjust timing, format cleanup
- write output .json files
↓
Output saved locally (optionally passed to evaluation/)

Parallel:
Preprocessing → Training scripts → Trained models → Upload to HuggingFace → Inference pulls them back

##### Architectural Patterns & Technologies
- Layered, modular pipeline (Separation of Concerns)
- Config-driven via tools/config + app_helper
- Dependency injection of paths & parameters
- AI frameworks: TensorFlow for lighting and training, possibly PyTorch for autoencoder
- Remote model repo via HuggingFace SDK
- Deployment container: Pinokio for UI packaging

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "User Interface Layer"
        UIWeb["Pinokio Web App"]:::ui
        CLI1["main.py"]:::ui
        CLI2["main_multi.py"]:::ui
        CLI3["main_training.py"]:::ui
    end

    UIWeb --> Orches
    CLI1 --> Orches
    CLI2 --> Orches
    CLI3 --> Orches

    subgraph "Orchestrator & Configuration"
        Orches["Orchestrator"]:::config
        AppHelper["app_helper"]:::config
        ToolsConfig["tools/config"]:::config
    end

    Orches --> AppHelper
    Orches --> ToolsConfig
    Orches --> AudioPre

    subgraph "Data Ingestion & Preprocessing"
        AudioPre["Audio Preprocessor"]:::pre
        BeatData["Beat Data Helper"]:::pre
        MapInfo["Map Info Processor"]:::pre
    end

    AudioPre --> BeatData
    AudioPre --> MapInfo
    BeatData --> AE
    MapInfo --> AE

    subgraph "Inference Pipeline"
        AE["Deep Conv Autoencoder"]:::ai
        TCN["TCN Beat Predictor"]:::ai
        NoteGen["Note & Obstacle Generator"]:::ai
        Light["Lighting/Event Classifier"]:::ai
    end

    AE -->|"features"| TCN
    TCN -->|"beat_timestamps"| NoteGen
    NoteGen -->|"map_JSON"| Light

    subgraph "Post-Processing & Export"
        NotePost["Note Postprocessing"]:::post
        BPMOpt["BPM Optimizer"]:::post
        Sanity["Sanity Check"]:::post
        BSShift["bs_shift"]:::post
    end

    Light --> NotePost
    NotePost --> BPMOpt
    BPMOpt --> Sanity
    Sanity --> BSShift
    BSShift --> StorageLocal

    subgraph "Model Storage & Retrieval"
        CloudHF["HuggingFace"]:::external
        StorageLocal["Local File System"]:::storage
    end

    StorageLocal --> Orches
    CloudHF --> Orches
    Orches -->|"upload/download"| CloudHF

    subgraph "Training & Evaluation"
        Training["Training Scripts & Models"]:::train
        Eval["Evaluation Benchmarks"]:::train
    end

    AudioPre --> Training
    Training --> CloudHF
    Eval --> Training

    classDef ui fill:#ADD8E6,stroke:#000;
    classDef config fill:#90EE90,stroke:#000;
    classDef pre fill:#FFA500,stroke:#000;
    classDef ai fill:#FF6347,stroke:#000;
    classDef post fill:#9370DB,stroke:#000;
    classDef storage fill:#DEB887,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
    classDef train fill:#A9A9A9,stroke:#000;

    click UIWeb "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/main_app.py"
    click CLI1 "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/main.py"
    click CLI2 "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/main_multi.py"
    click CLI3 "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/main_training.py"
    click AppHelper "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/tree/main_app/app_helper/"
    click ToolsConfig "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/tree/main_app/tools/config/"
    click AudioPre "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/tree/main_app/preprocessing/"
    click BeatData "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/preprocessing/beat_data_helper.py"
    click MapInfo "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/preprocessing/map_info_processing.py"
    click AE "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/beat_prediction/ai_beat_gen.py"
    click TCN "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/lighting_prediction/tf_lighting.py"
    click NoteGen "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/map_creation/map_creator.py"
    click Light "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/blob/main_app/lighting_prediction/generate_lighting.py"
    click BSShift "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/tree/main_app/bs_shift/"
    click Training "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/tree/main_app/training/"
    click Eval "https://github.com/fred-brenner/infernosaber---beatsaber-automapper/tree/main_app/evaluation/"
```
