# joshmoody24/sitcom-simulator architecture

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

- Interactive diagram: https://gitdiagram.com/joshmoody24/sitcom-simulator
- Repository: https://github.com/joshmoody24/sitcom-simulator

## Overview

##### Main Modules & Components
- Command Line Interface (CLI) & Entry Point:
- Represented by components such as the “cli.py” file. This module accepts user inputs (via command-line arguments or as parameters in a Python script) that trigger the simulation.
- Script Generation Module:
- Includes the “script” directory and modules like “llm.py” and “llm_instructions.txt”.
- Integration with ChatGPT is used to generate the video script based on the provided prompt.
- Image Generation Module:
- Located in the “image” directory, with integrations for both Pillow (for image handling) and Stability (to interface with Stable Diffusion or similar).
- Responsible for creating images for the video frames.
- Music Generation Module:
- Found under the “music” directory with integrations to Freepd.
- This module identifies or generates background music.
- Speech Generation Module:
- Under the “speech” directory, with integrations to FakeYou and GTTS.
- It produces synthesized voices for the characters using deepfake voice generation tools.
- Video Generation Module:
- Present in the “video” directory, integrates tools like FFmpeg and MoviePy.
- This step combines images, synthesized speech, and music to produce the final meme video.
- Additional Modules:
- “auto.py” for automated generation workflows.
- “user_input.py” to capture and process user-provided parameters.
- “social” module (e.g., “yt_uploader.py”) indicated for potential automatic YouTube uploads.

##### External Service Integrations
- ChatGPT API – for generating scripts.
- Stable Diffusion (via Stability integration) – for image creation.
- FakeYou API – for voice deepfakes and character voice synthesis.
- Freepd – for obtaining background music.
- FFmpeg/MoviePy – for video editing and integration.

##### Establish Relationships and Interactions
- Flow of Data:
- Start at the CLI/user input, which passes a prompt and style.
- The script module uses ChatGPT to generate a script.
- The generated script is then sent to the image module and speech module to create visual assets and voice overs, respectively.
- The music module selects background audio.
- The video module takes these outputs (images, voice, audio) and assembles them into a final video.
- CLI → Script Generation
- Script Generation → Image & Speech Generation
- Music Generation → Video Generation
- Image, Speech, and Music modules → Video Generation

##### Architectural Patterns & Design Principles
- Modular Design:
- Each major functionality (script, image, music, speech, video) is encapsulated in its own module with separate interface integrations.
- Integration Points:
- Separate “integrations” directories under each feature (e.g., image/integrations, speech/integrations) emphasize the plug-and-play nature of external API dependency.
- Pipeline Flow:
- The overall architecture follows a pipeline pattern where the output from one module becomes the input for the next stage.
- Customizability:
- The design supports extensibility; for example, easy swapping of voice generation from FakeYou to another tool without major changes to the pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input Layer
    subgraph "Input Layer"
        CLI["CLI (cli.py)"]:::internal
        UI["User Input (user_input.py)"]:::internal
        AutoGen["Automated Workflow (auto.py)"]:::internal
    end

    %% Content Generation Layer
    subgraph "Content Generation Layer"
        ScriptGen["Script Generation (llm.py, llm_instructions.txt)"]:::internal
        ImageGen["Image Generation (image_generator.py)"]:::internal
        SpeechGen["Speech Generation (speech_generator.py)"]:::internal
        MusicGen["Music Generation (music_generator.py)"]:::internal

        ChatGPT["ChatGPT API"]:::external
        Pillow["Pillow"]:::external
        StableDiffusion["Stable Diffusion"]:::external
        Freepd["Freepd"]:::external
        FakeYou["FakeYou API"]:::external
        GTTS["GTTS"]:::external
    end

    %% Final Assembly Layer
    subgraph "Final Assembly Layer"
        VideoGen["Video Generation (video_generator.py)"]:::internal
        FFmpeg["FFmpeg"]:::external
        MoviePy["MoviePy"]:::external
        Social["Social Module (yt_uploader.py)"]:::internal
    end

    %% Data Flow Connections
    CLI -->|"triggers"| AutoGen
    CLI -->|"initiates"| UI
    UI -->|"supplies input to"| ScriptGen
    AutoGen -->|"automates"| ScriptGen

    ScriptGen -->|"calls ChatGPT API"| ChatGPT

    ScriptGen -->|"provides_script"| ImageGen
    ScriptGen -->|"provides_script"| SpeechGen

    %% Integration connections for Image Generation
    ImageGen -->|"integrates_with"| Pillow
    ImageGen -->|"integrates_with"| StableDiffusion

    %% Integration connections for Speech Generation
    SpeechGen -->|"integrates_with"| FakeYou
    SpeechGen -->|"integrates_with"| GTTS

    %% Integration connection for Music Generation
    MusicGen -->|"integrates_with"| Freepd

    %% Pipeline to Video Generation
    ImageGen -->|"sends_assets"| VideoGen
    SpeechGen -->|"sends_audio"| VideoGen
    MusicGen -->|"sends_music"| VideoGen

    %% Video Generation integrations and output
    VideoGen -->|"uses"| FFmpeg
    VideoGen -->|"uses"| MoviePy
    VideoGen -->|"uploads_to"| Social

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#000000,stroke-width:2px;
    classDef external fill:#90EE90,stroke:#000000,stroke-width:2px;

    %% Click Events for Internal Modules
    click CLI "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/cli.py"
    click UI "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/user_input.py"
    click AutoGen "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/auto.py"
    click ScriptGen "https://github.com/joshmoody24/sitcom-simulator/tree/master/sitcom_simulator/script/"
    click ImageGen "https://github.com/joshmoody24/sitcom-simulator/tree/master/sitcom_simulator/image/"
    click MusicGen "https://github.com/joshmoody24/sitcom-simulator/tree/master/sitcom_simulator/music/"
    click SpeechGen "https://github.com/joshmoody24/sitcom-simulator/tree/master/sitcom_simulator/speech/"
    click VideoGen "https://github.com/joshmoody24/sitcom-simulator/tree/master/sitcom_simulator/video/"
    click Social "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/social/yt_uploader.py"

    %% Click Events for External Integrations (File Mappings)
    click Pillow "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/image/integrations/pillow.py"
    click StableDiffusion "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/image/integrations/stability.py"
    click Freepd "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/music/integrations/freepd.py"
    click FakeYou "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/speech/integrations/fakeyou.py"
    click GTTS "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/speech/integrations/gtts.py"
    click FFmpeg "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/video/integrations/ffmpeg.py"
    click MoviePy "https://github.com/joshmoody24/sitcom-simulator/blob/master/sitcom_simulator/video/integrations/moviepy.py"
```
