# 2swap/swaptube architecture

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

- Interactive diagram: https://gitdiagram.com/2swap/swaptube
- Repository: https://github.com/2swap/swaptube

## Overview

##### Main Architectural Layers
a. Build System (CMake + Scripts)
b. Entry Point / CLI
c. Core Rendering Engine
d. External Dependencies & Services
e. Input Media & Output Artifacts

##### Break Out the Key Components
- Build System
– CMakeLists.txt & cmake/Find*.cmake
– go.sh / play.sh / record_audios.py
- Entry Point
– misc/Main.cpp (invoked by go.sh)
– Argument parser (project name, resolution, smoke-test flag)
- Core Engine
– Project Loader (src/Projects/*.cpp)
– Time Control
- Macroblock Manager
- Microblock Manager
– Scene Manager (src/Scenes/Scene.cpp + scene subclasses)
– State Manager (StateManager.cpp)
– DataObjects (src/DataObjects/**)
– Render Engine
- CPU modules (misc/Convolution.cpp, ColorScheme.cpp, etc.)
- GPU modules (src/CUDA/*.cu)
- I/O Subsystem
– VideoWriter (wrapping FFmpeg APIs)
– AudioWriter (PCM buffers)
– SubtitleWriter, SFX, DebugPlot (gnuplot), PathManager
– Media folder (input PNG, MP4, generated LaTeX)
– Out folder (output MP4, WAV, subtitle files, gnuplots)
- External Dependencies
– FFmpeg (libav* for encode/decode)
– CUDA
– GLM / Eigen (math)
– MicroTeX → SVG
– RSVG + GLib → rasterize SVG
– Cairo → final pixel surfaces
– gnuplot → debug plots

##### Relationships & Data Flows
1. Build Flow:
go.sh → CMake → compile all src/ into binary (in build/)
2. Runtime Initialization:
go.sh invokes binary → Main parses args → Project Loader instantiates a Scene
3. Rendering Loop:
For each Macroblock:
- Stage Macroblock (audio file / silence / generated)
- For each Microblock:
– Scene.render_microblock()
– StateManager updates numeric state
– DataObjects supply non-numeric data
– RenderEngine (CPU or CUDA) produces a frame buffer
– I/O: VideoWriter .pushFrame(buffer)
End
- AudioWriter writes audio samples per Macroblock
4. Post-processing:
- SubtitleWriter writes .srt
- record_audios.py reads record_list.tsv → helps record voiceovers

##### Architectural Patterns & Principles
– **Separation of Concerns**:
- CLI vs. Core Engine vs. I/O
- Scene vs. State vs. Data
– **Two-Layer Time Control**: Macroblocks & Microblocks
– **Plugin-Style Scenes**: Each scene is a subclass implementing render_microblock
– **Hybrid CPU/GPU Rendering**: Fallback to CPU modules vs. CUDA accelerated code
– **External Service Pipelines**: LaTeX → SVG → Cairo → pixels; Gnuplot → PNG

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build System
    subgraph "Build System"
        direction TB
        CMake["CMakeLists.txt"]:::build
        FindCairo["cmake/FindCairo.cmake"]:::build
        FindFFmpeg["cmake/FindFFmpeg.cmake"]:::build
        FindGLib["cmake/FindGLib.cmake"]:::build
        FindRSVG["cmake/FindRSVG.cmake"]:::build
        GoScript["go.sh"]:::build
        PlayScript["play.sh"]:::build
        RecordAudioScript["record_audios.py"]:::build
    end

    %% Entry Point / CLI
    subgraph "Entry Point / CLI"
        direction TB
        Main["Main.cpp"]:::core
    end

    %% Core Rendering Engine
    subgraph "Core Rendering Engine"
        direction TB
        subgraph "Project Loader"
            direction TB
            Projects["src/Projects/*.cpp"]:::core
        end
        subgraph "Time Control"
            direction TB
            MacroMgr["Macroblock Manager\n(src/io/Macroblock.cpp)"]:::core
            MicroMgr["Microblock Manager\n(src/Scenes/*)"]:::core
        end
        SceneMgr["Scene Manager\n(src/Scenes/Scene.cpp)"]:::core
        StateMgr["State Manager\n(StateManager.cpp)"]:::core
        DataObjs["DataObjects\n(src/DataObjects/**)"]:::core
        subgraph "Render Engine"
            direction TB
            CPU["CPU Modules\n(src/misc/Convolution.cpp,\nColorScheme.cpp)"]:::core
            GPU["GPU Modules\n(src/CUDA/*.cu)"]:::core
        end
    end

    %% I/O Subsystem
    subgraph "I/O Subsystem"
        direction TB
        VideoW["VideoWriter\n(src/io/VideoWriter.cpp)"]:::io
        AudioW["AudioWriter\n(src/io/AudioWriter.cpp)"]:::io
        SubW["SubtitleWriter\n(src/io/SubtitleWriter.cpp)"]:::io
        SFX["SFX\n(src/io/SFX.cpp)"]:::io
        DebugPlot["DebugPlot\n(src/io/DebugPlot.h)"]:::io
        PathMgr["PathManager\n(src/io/PathManager.cpp)"]:::io
        GUI["GUI\n(src/io/GUI.cpp)"]:::io
        IoHelpers["IoHelpers\n(src/io/IoHelpers.cpp)"]:::io
        VideoDec["Media Decoding\n(src/io/video_decoding.cpp)"]:::io
        VisualMedia["VisualMedia\n(src/io/VisualMedia.cpp)"]:::io
        Shtooka["ShtookaWriter\n(src/io/ShtookaWriter.cpp)"]:::io
    end

    %% Media and Output
    media[(Media Folder)]:::io
    out[(Out Folder)]:::io

    %% External Dependencies
    subgraph "External Services"
        direction TB
        FFmpeg["FFmpeg"]:::external
        CUDAdep["CUDA"]:::external
        MathLibs["GLM/Eigen"]:::external
        TeX["MicroTeX→SVG"]:::external
        RSVGdep["RSVG+GLib"]:::external
        Cairodep["Cairo"]:::external
        Gnuplot["gnuplot"]:::external
    end

    %% Build Flow
    GoScript -->|runs| CMake
    CMake -->|compiles src/| Binary["SwapTube Binary"]:::core

    %% Runtime Initialization
    GoScript -->|invokes| Binary
    Binary -->|calls| Main
    Main -->|parses args| Projects
    Main -->|loads scene| SceneMgr

    %% Rendering Loop Control Flow
    SceneMgr -->|manage| MacroMgr
    MacroMgr -->|iterates| MicroMgr
    MicroMgr -->|calls render_microblock| SceneMgr
    SceneMgr -->|updates| StateMgr
    SceneMgr -->|requests| DataObjs
    SceneMgr -->|uses| CPU
    SceneMgr -->|uses| GPU

    %% I/O Data Flow
    SceneMgr -->|raw RGBA buffer| VideoW
    VideoW -->|MP4| out
    MacroMgr -->|PCM buffers| AudioW
    AudioW -->|WAV| out
    SceneMgr -->|.srt data| SubW
    SubW -->|.srt| out

    %% Media Input
    media -->|input PNG/MP4| VisualMedia
    media -->|record_list.tsv| RecordAudioScript
    RecordAudioScript -->|voiceovers| out

    %% External pipelines
    TeX -->|.tex→SVG| RSVGdep
    RSVGdep -->|SVG→raster| Cairodep
    Cairodep -->|pixel surfaces| SceneMgr
    Gnuplot -->|debug PNG| DebugPlot

    %% Dependencies
    VideoW --> FFmpeg
    AudioW --> FFmpeg
    CPU --> MathLibs
    GPU --> CUDAdep

    %% Click Events
    click CMake "https://github.com/2swap/swaptube/blob/master/CMakeLists.txt"
    click FindCairo "https://github.com/2swap/swaptube/blob/master/cmake/FindCairo.cmake"
    click FindFFmpeg "https://github.com/2swap/swaptube/blob/master/cmake/FindFFmpeg.cmake"
    click FindGLib "https://github.com/2swap/swaptube/blob/master/cmake/FindGLib.cmake"
    click FindRSVG "https://github.com/2swap/swaptube/blob/master/cmake/FindRSVG.cmake"
    click GoScript "https://github.com/2swap/swaptube/blob/master/go.sh"
    click PlayScript "https://github.com/2swap/swaptube/blob/master/play.sh"
    click RecordAudioScript "https://github.com/2swap/swaptube/blob/master/record_audios.py"
    click Main "https://github.com/2swap/swaptube/blob/master/src/misc/Main.cpp"
    click Projects "https://github.com/2swap/swaptube/blob/master/src/Projects/BuildGraph.cpp"
    click MacroMgr "https://github.com/2swap/swaptube/blob/master/src/io/Macroblock.cpp"
    click SceneMgr "https://github.com/2swap/swaptube/blob/master/src/Scenes/Scene.cpp"
    click StateMgr "https://github.com/2swap/swaptube/blob/master/src/misc/StateManager.cpp"
    click DataObjs "https://github.com/2swap/swaptube/tree/master/src/DataObjects/"
    click CPU "https://github.com/2swap/swaptube/blob/master/src/misc/Convolution.cpp"
    click GPU "https://github.com/2swap/swaptube/tree/master/src/CUDA/"
    click VideoW "https://github.com/2swap/swaptube/blob/master/src/io/VideoWriter.cpp"
    click AudioW "https://github.com/2swap/swaptube/blob/master/src/io/AudioWriter.cpp"
    click SubW "https://github.com/2swap/swaptube/blob/master/src/io/SubtitleWriter.cpp"
    click SFX "https://github.com/2swap/swaptube/blob/master/src/io/SFX.cpp"
    click DebugPlot "https://github.com/2swap/swaptube/blob/master/src/io/DebugPlot.h"
    click PathMgr "https://github.com/2swap/swaptube/blob/master/src/io/PathManager.cpp"
    click GUI "https://github.com/2swap/swaptube/blob/master/src/io/GUI.cpp"
    click IoHelpers "https://github.com/2swap/swaptube/blob/master/src/io/IoHelpers.cpp"
    click VideoDec "https://github.com/2swap/swaptube/blob/master/src/io/video_decoding.cpp"
    click VisualMedia "https://github.com/2swap/swaptube/blob/master/src/io/VisualMedia.cpp"
    click Shtooka "https://github.com/2swap/swaptube/blob/master/src/io/ShtookaWriter.cpp"

    classDef build fill:#cccccc,stroke:#333,stroke-width:1px
    classDef core fill:#add8e6,stroke:#333,stroke-width:1px
    classDef io fill:#90ee90,stroke:#333,stroke-width:1px
    classDef external fill:#ffa500,stroke:#333,stroke-width:1px
```
