# langat2005/live-strean-clipping-tool architecture

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

- Interactive diagram: https://gitdiagram.com/langat2005/live-strean-clipping-tool
- Repository: https://github.com/langat2005/live-strean-clipping-tool

## Overview

This application monitors live chat and video, detects engagement spikes, and turns promising moments into vertical, captioned clips. Its main workflow runs through the pipeline: it waits for pre-roll footage, captures a spike window, scores the candidate, then transcribes, reframes, generates captions, and burns them into the export. Other branches include platform chat clients, stream resolution, metadata generation, and a live dashboard. The workflow is documented in the README and partly visible in sampled source; some subsystem links therefore rely on README evidence.

Main entry points: [`pipeline.py`](https://github.com/langat2005/live-strean-clipping-tool/blob/main/pipeline.py) (Clip Pipeline), [`main.py`](https://github.com/langat2005/live-strean-clipping-tool/blob/main/main.py) (Application Entry), [`chat/base.py`](https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/base.py) (Chat Messages), [`ffmpeg_utils.py`](https://github.com/langat2005/live-strean-clipping-tool/blob/main/ffmpeg_utils.py) (FFmpeg Tools)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_ingestion["Stream Ingestion"]
  node_youtube["YouTube Chat<br/>[youtube_client.py]"]
  node_twitch["Twitch Chat<br/>[twitch_client.py]"]
  node_mock["Mock Chat<br/>[mock_client.py]"]
  node_chatbase["Chat Messages<br/>[base.py]"]
  node_resolver["Stream Resolver<br/>[stream_resolver.py]"]
  node_ring[("Rolling Buffer<br/>[ring_buffer.py]")]
end

subgraph group_detection["Spike Detection"]
  node_detector["Spike Detector<br/>[spike_detector.py]"]
end

subgraph group_processing["Clip Processing"]
  node_pipeline["Clip Pipeline<br/>[pipeline.py]"]
  node_scorer["Virality Scorer<br/>[scorer.py]"]
  node_transcriber["Speech Transcriber<br/>[transcriber.py]"]
  node_formatter["Vertical Formatter<br/>[formatting.py]"]
  node_ass["Caption Generator<br/>[ass_generator.py]"]
  node_burner["Subtitle Burner<br/>[burn_in.py]"]
end

subgraph group_operations["Output and Monitoring"]
  node_metadata["Clip Metadata"]
  node_state["Pipeline Telemetry<br/>[pipeline_state.py]"]
  node_dashboard["Live Dashboard<br/>[app.py]"]
  node_config["Application Settings<br/>[config.py]"]
  node_ffmpeg["FFmpeg Tools<br/>[ffmpeg_utils.py]"]
  node_main["Application Entry<br/>[main.py]"]
end

node_viewer(("Stream Operator"))
node_livevideo(("Live Video"))
node_export["Final Clip"]

node_viewer -->|"starts app"| node_main
node_main -->|"selects client"| node_youtube
node_main -->|"selects client"| node_twitch
node_main -->|"selects client"| node_mock
node_youtube -->|"dispatches messages"| node_chatbase
node_twitch -->|"dispatches messages"| node_chatbase
node_mock -->|"dispatches messages"| node_chatbase
node_main -->|"resolves stream"| node_resolver
node_livevideo -->|"supplies footage"| node_ring
node_main -->|"starts pipeline"| node_pipeline
node_pipeline -->|"starts and extracts"| node_ring
node_pipeline -->|"handles chat"| node_detector
node_chatbase -->|"processes messages"| node_detector
node_detector -->|"triggers clip"| node_pipeline
node_pipeline -->|"transcribes candidate"| node_transcriber
node_pipeline -->|"scores candidate"| node_scorer
node_pipeline -->|"reframes accepted clip"| node_formatter
node_pipeline -->|"generates captions"| node_ass
node_pipeline -->|"burns captions"| node_burner
node_pipeline -->|"generates metadata"| node_metadata
node_pipeline -->|"updates telemetry"| node_state
node_state -->|"feeds status"| node_dashboard
node_formatter -->|"produces video"| node_export
node_burner -->|"renders final clip"| node_export
node_viewer -->|"monitors pipeline"| node_dashboard
node_pipeline -->|"uses settings"| node_config
node_ring -->|"resolves executable"| node_ffmpeg
node_transcriber -->|"extracts audio"| node_ffmpeg
node_formatter -->|"encodes video"| node_ffmpeg
node_burner -->|"burns subtitles"| node_ffmpeg

click node_youtube "https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/youtube_client.py"
click node_twitch "https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/twitch_client.py"
click node_mock "https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/mock_client.py"
click node_chatbase "https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/base.py"
click node_resolver "https://github.com/langat2005/live-strean-clipping-tool/blob/main/stream_resolver.py"
click node_ring "https://github.com/langat2005/live-strean-clipping-tool/blob/main/buffer/ring_buffer.py"
click node_detector "https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/spike_detector.py"
click node_pipeline "https://github.com/langat2005/live-strean-clipping-tool/blob/main/pipeline.py"
click node_scorer "https://github.com/langat2005/live-strean-clipping-tool/blob/main/virality/scorer.py"
click node_transcriber "https://github.com/langat2005/live-strean-clipping-tool/blob/main/transcription/transcriber.py"
click node_formatter "https://github.com/langat2005/live-strean-clipping-tool/blob/main/video/formatting.py"
click node_ass "https://github.com/langat2005/live-strean-clipping-tool/blob/main/transcription/ass_generator.py"
click node_burner "https://github.com/langat2005/live-strean-clipping-tool/blob/main/video/burn_in.py"
click node_metadata "https://github.com/langat2005/live-strean-clipping-tool/blob/main/metadata_generator.py"
click node_state "https://github.com/langat2005/live-strean-clipping-tool/blob/main/pipeline_state.py"
click node_dashboard "https://github.com/langat2005/live-strean-clipping-tool/blob/main/dashboard/app.py"
click node_config "https://github.com/langat2005/live-strean-clipping-tool/blob/main/config.py"
click node_ffmpeg "https://github.com/langat2005/live-strean-clipping-tool/blob/main/ffmpeg_utils.py"
click node_main "https://github.com/langat2005/live-strean-clipping-tool/blob/main/main.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_youtube,node_twitch,node_mock,node_chatbase,node_resolver,node_ring toneBlue
class node_detector toneAmber
class node_pipeline,node_scorer,node_transcriber,node_formatter,node_ass,node_burner toneMint
class node_metadata,node_state,node_dashboard,node_config,node_ffmpeg,node_main toneRose
class node_viewer,node_livevideo,node_export toneIndigo
```

## Components

### Stream Ingestion

- [YouTube Chat](https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/youtube_client.py): `chat/youtube_client.py`
- [Twitch Chat](https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/twitch_client.py): `chat/twitch_client.py`
- [Mock Chat](https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/mock_client.py): `chat/mock_client.py`
- [Chat Messages](https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/base.py): `chat/base.py`
- [Stream Resolver](https://github.com/langat2005/live-strean-clipping-tool/blob/main/stream_resolver.py): `stream_resolver.py`
- [Rolling Buffer](https://github.com/langat2005/live-strean-clipping-tool/blob/main/buffer/ring_buffer.py): `buffer/ring_buffer.py`

### Spike Detection

- [Spike Detector](https://github.com/langat2005/live-strean-clipping-tool/blob/main/chat/spike_detector.py): `chat/spike_detector.py`

### Clip Processing

- [Clip Pipeline](https://github.com/langat2005/live-strean-clipping-tool/blob/main/pipeline.py): `pipeline.py`
- [Virality Scorer](https://github.com/langat2005/live-strean-clipping-tool/blob/main/virality/scorer.py): `virality/scorer.py`
- [Speech Transcriber](https://github.com/langat2005/live-strean-clipping-tool/blob/main/transcription/transcriber.py): `transcription/transcriber.py`
- [Vertical Formatter](https://github.com/langat2005/live-strean-clipping-tool/blob/main/video/formatting.py): `video/formatting.py`
- [Caption Generator](https://github.com/langat2005/live-strean-clipping-tool/blob/main/transcription/ass_generator.py): `transcription/ass_generator.py`
- [Subtitle Burner](https://github.com/langat2005/live-strean-clipping-tool/blob/main/video/burn_in.py): `video/burn_in.py`

### Output and Monitoring

- [Clip Metadata](https://github.com/langat2005/live-strean-clipping-tool/blob/main/metadata_generator.py): `metadata_generator.py`
- [Pipeline Telemetry](https://github.com/langat2005/live-strean-clipping-tool/blob/main/pipeline_state.py): `pipeline_state.py`
- [Live Dashboard](https://github.com/langat2005/live-strean-clipping-tool/blob/main/dashboard/app.py): `dashboard/app.py`
- [Application Settings](https://github.com/langat2005/live-strean-clipping-tool/blob/main/config.py): `config.py`
- [FFmpeg Tools](https://github.com/langat2005/live-strean-clipping-tool/blob/main/ffmpeg_utils.py): `ffmpeg_utils.py`
- [Application Entry](https://github.com/langat2005/live-strean-clipping-tool/blob/main/main.py): `main.py`

### Other components

- **Stream Operator**
- **Live Video**
- **Final Clip**

## Connections

- Stream Operator → Application Entry: starts app (evidence: `main.py`)
- Application Entry → YouTube Chat: selects client (evidence: `main.py`)
- Application Entry → Twitch Chat: selects client (evidence: `main.py`)
- Application Entry → Mock Chat: selects client (evidence: `main.py`)
- YouTube Chat → Chat Messages: dispatches messages (evidence: `chat/youtube_client.py`)
- Twitch Chat → Chat Messages: dispatches messages (evidence: `chat/twitch_client.py`)
- Mock Chat → Chat Messages: dispatches messages (evidence: `chat/mock_client.py`)
- Application Entry → Stream Resolver: resolves stream (evidence: `main.py`)
- Live Video → Rolling Buffer: supplies footage (evidence: `README.md`)
- Application Entry → Clip Pipeline: starts pipeline (evidence: `main.py`)
- Clip Pipeline → Rolling Buffer: starts and extracts (evidence: `pipeline.py`)
- Clip Pipeline → Spike Detector: handles chat (evidence: `pipeline.py`)
- Chat Messages → Spike Detector: processes messages (evidence: `README.md`)
- Spike Detector → Clip Pipeline: triggers clip (evidence: `README.md`)
- Clip Pipeline → Speech Transcriber: transcribes candidate (evidence: `pipeline.py`)
- Clip Pipeline → Virality Scorer: scores candidate (evidence: `pipeline.py`)
- Clip Pipeline → Vertical Formatter: reframes accepted clip (evidence: `README.md`)
- Clip Pipeline → Caption Generator: generates captions (evidence: `README.md`)
- Clip Pipeline → Subtitle Burner: burns captions (evidence: `README.md`)
- Clip Pipeline → Clip Metadata: generates metadata (evidence: `pipeline.py`)
- Clip Pipeline → Pipeline Telemetry: updates telemetry (evidence: `pipeline_state.py`)
- Pipeline Telemetry → Live Dashboard: feeds status (evidence: `pipeline_state.py`)
- Vertical Formatter → Final Clip: produces video (evidence: `README.md`)
- Subtitle Burner → Final Clip: renders final clip (evidence: `README.md`)
- Stream Operator → Live Dashboard: monitors pipeline (evidence: `README.md`)
- Clip Pipeline → Application Settings: uses settings (evidence: `pipeline.py`)
- Rolling Buffer → FFmpeg Tools: resolves executable (evidence: `buffer/ring_buffer.py`)
- Speech Transcriber → FFmpeg Tools: extracts audio (evidence: `transcription/transcriber.py`)
- Vertical Formatter → FFmpeg Tools: encodes video (evidence: `video/formatting.py`)
- Subtitle Burner → FFmpeg Tools: burns subtitles (evidence: `video/burn_in.py`)
