# beyondtahir/beyondgtaclips architecture

> Architecture diagram of the GitHub repository beyondtahir/beyondgtaclips, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/beyondtahir/beyondgtaclips
- Repository: https://github.com/beyondtahir/beyondgtaclips

## Overview

Beyond GTA Clips is a local stream-to-short-video tool, operated through a command-line workflow that can also be guided by an AI assistant. The user finds and selects streams, then the pipeline analyzes each stream, identifies clip moments, and produces vertical reels with captions and posting notes. The README documents five editing styles and self-check images; the sampled source shows the rendering modules but not every style implementation. External-service links are limited to documented or excerpt-supported behavior.

Main entry points: [`scripts/bgt/produce.py`](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/produce.py) (Clip production), [`scripts/bgt/pipeline.py`](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/pipeline.py) (Stream pipeline), [`scripts/bgt/cli.py`](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/cli.py) (CLI commands), [`scripts/bgt/discover.py`](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/discover.py) (Stream discovery)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_discovery["Find streams"]
  node_discovery["Stream discovery<br/>[discover.py]"]
end

subgraph group_analysis["Analyze and select"]
  node_pipeline["Stream pipeline<br/>[pipeline.py]"]
  node_media["Stream media<br/>[media.py]"]
  node_listening["Audio and chat<br/>[listen.py]"]
  node_highlights["Moment selection<br/>[highlights.py]"]
  node_brains["AI assistants<br/>[brains.py]"]
end

subgraph group_editing["Create reels"]
  node_production["Clip production<br/>[produce.py]"]
  node_frame["Frame analysis<br/>[frame.py]"]
  node_templates["Reel styles<br/>[templates.py]"]
  node_art["Graphics and captions<br/>[art.py]"]
  node_titlecard["Title cards<br/>[titlecard.py]"]
end

subgraph group_runtime["Command and runtime"]
  node_cli["CLI commands<br/>[cli.py]"]
  node_entry["Script entry<br/>[beyondgtaclips.py]"]
  node_settings["Clip settings<br/>[settings.py]"]
  node_common["Shared helpers<br/>[common.py]"]
end

node_user(("Clip creator"))
node_youtube["YouTube"]
node_assistant["Installed assistant"]
node_ffmpeg["FFmpeg tools"]
node_reels["Finished reels"]
node_posting["Posting notes"]

node_user -->|"runs"| node_entry
node_entry -->|"starts"| node_cli
node_cli -->|"loads settings"| node_settings
node_cli -->|"finds streams"| node_discovery
node_discovery -->|"searches"| node_youtube
node_cli -->|"processes selection"| node_pipeline
node_pipeline -->|"fetches media"| node_media
node_pipeline -->|"analyzes audio"| node_listening
node_pipeline -->|"selects moments"| node_highlights
node_pipeline -->|"builds clips"| node_production
node_highlights -->|"requests picks"| node_brains
node_brains -.->|"invokes optionally"| node_assistant
node_production -->|"analyzes frames"| node_frame
node_production -->|"renders styles"| node_templates
node_templates -->|"draws graphics"| node_art
node_production -->|"uses transcript"| node_listening
node_production -->|"fetches clip parts"| node_media
node_production -->|"encodes video"| node_ffmpeg
node_production -->|"writes reels"| node_reels
node_pipeline -->|"writes notes"| node_posting
node_titlecard -->|"uses helpers"| node_common

click node_cli "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/cli.py"
click node_entry "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/beyondgtaclips.py"
click node_settings "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/settings.py"
click node_common "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/common.py"
click node_discovery "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/discover.py"
click node_pipeline "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/pipeline.py"
click node_media "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/media.py"
click node_listening "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/listen.py"
click node_highlights "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/highlights.py"
click node_brains "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/brains.py"
click node_production "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/produce.py"
click node_frame "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/frame.py"
click node_templates "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/templates.py"
click node_art "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/art.py"
click node_titlecard "https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/titlecard.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_discovery toneBlue
class node_pipeline,node_media,node_listening,node_highlights,node_brains toneAmber
class node_production,node_frame,node_templates,node_art,node_titlecard toneMint
class node_cli,node_entry,node_settings,node_common toneRose
class node_user,node_youtube,node_assistant,node_ffmpeg,node_reels,node_posting toneIndigo
```

## Components

### Find streams

- [Stream discovery](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/discover.py): `scripts/bgt/discover.py`

### Analyze and select

- [Stream pipeline](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/pipeline.py): `scripts/bgt/pipeline.py`
- [Stream media](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/media.py): `scripts/bgt/media.py`
- [Audio and chat](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/listen.py): `scripts/bgt/listen.py`
- [Moment selection](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/highlights.py): `scripts/bgt/highlights.py`
- [AI assistants](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/brains.py): `scripts/bgt/brains.py`

### Create reels

- [Clip production](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/produce.py): `scripts/bgt/produce.py`
- [Frame analysis](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/frame.py): `scripts/bgt/frame.py`
- [Reel styles](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/templates.py): `scripts/bgt/templates.py`
- [Graphics and captions](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/art.py): `scripts/bgt/art.py`
- [Title cards](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/titlecard.py): `scripts/bgt/titlecard.py`

### Command and runtime

- [CLI commands](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/cli.py): `scripts/bgt/cli.py`
- [Script entry](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/beyondgtaclips.py): `scripts/beyondgtaclips.py`
- [Clip settings](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/settings.py): `scripts/bgt/settings.py`
- [Shared helpers](https://github.com/beyondtahir/beyondgtaclips/blob/main/scripts/bgt/common.py): `scripts/bgt/common.py`

### Other components

- **Clip creator**
- **YouTube**
- **Installed assistant**
- **FFmpeg tools**
- **Finished reels**
- **Posting notes**

## Connections

- Clip creator → Script entry: runs (evidence: `README.md`)
- Script entry → CLI commands: starts (evidence: `scripts/beyondgtaclips.py`)
- CLI commands → Clip settings: loads settings (evidence: `scripts/bgt/cli.py`)
- CLI commands → Stream discovery: finds streams (evidence: `scripts/bgt/cli.py`)
- Stream discovery → YouTube: searches (evidence: `scripts/bgt/discover.py`)
- CLI commands → Stream pipeline: processes selection (evidence: `scripts/bgt/cli.py`)
- Stream pipeline → Stream media: fetches media (evidence: `scripts/bgt/pipeline.py`)
- Stream pipeline → Audio and chat: analyzes audio (evidence: `scripts/bgt/pipeline.py`)
- Stream pipeline → Moment selection: selects moments (evidence: `scripts/bgt/pipeline.py`)
- Stream pipeline → Clip production: builds clips (evidence: `scripts/bgt/pipeline.py`)
- Moment selection → AI assistants: requests picks (evidence: `scripts/bgt/highlights.py`)
- AI assistants → Installed assistant: invokes optionally (evidence: `scripts/bgt/brains.py`)
- Clip production → Frame analysis: analyzes frames (evidence: `scripts/bgt/produce.py`)
- Clip production → Reel styles: renders styles (evidence: `scripts/bgt/produce.py`)
- Reel styles → Graphics and captions: draws graphics (evidence: `scripts/bgt/templates.py`)
- Clip production → Audio and chat: uses transcript (evidence: `scripts/bgt/produce.py`)
- Clip production → Stream media: fetches clip parts (evidence: `scripts/bgt/produce.py`)
- Clip production → FFmpeg tools: encodes video (evidence: `README.md`)
- Clip production → Finished reels: writes reels (evidence: `README.md`)
- Stream pipeline → Posting notes: writes notes (evidence: `scripts/bgt/pipeline.py`)
- Title cards → Shared helpers: uses helpers (evidence: `scripts/bgt/titlecard.py`)
