# alexfazio/viral-clips-crew architecture

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

- Interactive diagram: https://gitdiagram.com/alexfazio/viral-clips-crew
- Repository: https://github.com/alexfazio/viral-clips-crew

## Overview

##### Project type and purpose
- **Type**: An open‑source command‑line video‑processing tool (not a full‑blown web or microservices system).
- **Purpose**: Ingest long‑form video, transcribe and analyze it with LLMs (OpenAI & Google Gemini), extract “viral” highlights, generate subtitles, and output ready‑to‑publish clips.

##### File structure
Top‑level entries and their roles:
- `app.py` (orchestrator): entry point that ties all steps together
- Modules handling each stage:
- `ytdl.py`: video ingestion/download
- `local_transcribe.py` & `crew.py`: transcription and AI‑driven analysis
- `clipper.py`: segment extraction
- `subtitler.py`: subtitle generation
- `extracts.py`: utility for collating AI outputs
- `utils.py`: shared helper functions
- `resources/`: prompts, lists, static data
- `input_files/`: drop‑zone for source clips
- `crew_output/`: stores intermediate API responses
- `subtitler_output/`: final output directory
- Config & metadata: `pyproject.toml`, `.env`, `.github/workflows/pylint.yml`

##### Key architecture insights from README
- Uses Python 3.7+, Poetry for dependency management
- External dependencies: CrewAI library, OpenAI API, Google Gemini API
- Linear pipeline: ingestion → transcription → analysis → clipping → subtitling

##### Main components & how to represent them
A. **Video Ingestion**
– Component: ytdl.py
– Input: raw video (from `input_files/`)
– Output: local video file
B. **Transcription Service**
– Components: local_transcribe.py (optional local engine), crew.py (CrewAI wrapper)
– External: OpenAI LLM / Google Gemini APIs
– Output: transcript (text) + timestamps
C. **AI Analysis & Highlight Extraction**
– Component: crew.py & extracts.py
– Processes transcript to identify “viral” moments
– Uses prompts (`faster_subs_prompt.txt`) and variant lists
– Output: candidate clip metadata
D. **Clip Generation**
– Component: clipper.py
– Input: source video + timestamps
– Output: trimmed video segments
E. **Subtitle Generation**
– Component: subtitler.py
– Input: clip + transcript segment
– Output: subtitle file (e.g., SRT)
F. **Output Storage**
– Directory: `subtitler_output/`
– Also log intermediate JSON in `crew_output/`

##### Relationships & data flow
1. User drops video → `app.py` kicks off pipeline
2. `ytdl.py` fetches/validates source
3. Transcript stage calls external LLM APIs → text + timestamps
4. AI analysis module processes transcript → selects high‑impact moments
5. `clipper.py` extracts segments based on timestamps
6. `subtitler.py` annotates clips with subtitles
7. Final assets pushed to `subtitler_output/`

##### Architectural patterns & design principles
- **Pipeline/chain of responsibility**: each module performs one step, passes results downstream
- **Separation of concerns**: ingestion, transcription, analysis, clipping, subtitling are decoupled
- **External service abstraction**: crew.py wraps API calls, isolating AI‑specific logic
- **Config‑as‑code**: resources and prompts live in `resources/` for easy tweakability
- **Utility functions** in `utils.py` to avoid duplication

## Diagram (Mermaid)

```mermaid
graph TB
    subgraph "Configuration"
        Env[".env"]:::config
        Pyproject["pyproject.toml"]:::config
        Lint[".github/workflows/pylint.yml"]:::config
        click Pyproject "https://github.com/alexfazio/viral-clips-crew/blob/main/pyproject.toml"
        click Lint "https://github.com/alexfazio/viral-clips-crew/blob/main/.github/workflows/pylint.yml"
    end

    App["app.py"]:::orchestrator
    click App "https://github.com/alexfazio/viral-clips-crew/blob/main/app.py"

    subgraph "Storage - Input"
        Input["input_files/"]:::storage
        click Input "https://github.com/alexfazio/viral-clips-crew/tree/main/input_files/PLACE_CLIPS_HERE"
    end

    App -->|"starts pipeline"| YTDL["ytdl.py"]:::ingestion
    click YTDL "https://github.com/alexfazio/viral-clips-crew/blob/main/ytdl.py"

    YTDL -->|"video file"| LocTrans["local_transcribe.py"]:::ai
    click LocTrans "https://github.com/alexfazio/viral-clips-crew/blob/main/local_transcribe.py"

    subgraph "Transcription Stage"
        CrewWrap["crew.py"]:::ai
        click CrewWrap "https://github.com/alexfazio/viral-clips-crew/blob/main/crew.py"
        OpenAI["OpenAI API"]:::external
        Gemini["Google Gemini API"]:::external
        CrewWrap --> OpenAI
        CrewWrap --> Gemini
    end

    LocTrans -->|"transcript"| CrewWrap

    CrewWrap -->|"transcript JSON"| Extracts["extracts.py"]:::ai
    click Extracts "https://github.com/alexfazio/viral-clips-crew/blob/main/extracts.py"

    subgraph "Resources"
        Prompt["resources/faster_subs_prompt.txt"]:::resources
        Variants["resources/yt_url_variants_list.txt"]:::resources
        click Prompt "https://github.com/alexfazio/viral-clips-crew/blob/main/resources/faster_subs_prompt.txt"
        click Variants "https://github.com/alexfazio/viral-clips-crew/blob/main/resources/yt_url_variants_list.txt"
    end

    Prompt --> Extracts
    Variants --> Extracts

    Extracts -->|"metadata"| Clipper["clipper.py"]:::processing
    click Clipper "https://github.com/alexfazio/viral-clips-crew/blob/main/clipper.py"

    Clipper -->|"segments"| Subtitler["subtitler.py"]:::processing
    click Subtitler "https://github.com/alexfazio/viral-clips-crew/blob/main/subtitler.py"

    subgraph "Storage - Output"
        Out["subtitler_output/"]:::storage
    end

    Subtitler -->|"clips + subs"| Out

    CrewWrap --> CrewOutput["crew_output/"]:::storage
    click CrewOutput "https://github.com/alexfazio/viral-clips-crew/blob/main/crew_output/api_response.json"

    Utils["utils.py"]:::util
    click Utils "https://github.com/alexfazio/viral-clips-crew/blob/main/utils.py"

    App --> Utils
    YTDL --> Utils
    LocTrans --> Utils
    CrewWrap --> Utils
    Extracts --> Utils
    Clipper --> Utils
    Subtitler --> Utils

    classDef orchestrator fill:#FFD966,stroke:#333,stroke-width:1px;
    classDef ingestion fill:#CFE2F3,stroke:#333,stroke-width:1px;
    classDef ai fill:#D9D2E9,stroke:#333,stroke-width:1px;
    classDef processing fill:#F4CCCC,stroke:#333,stroke-width:1px;
    classDef storage fill:#E2EFDA,stroke:#333,stroke-width:1px;
    classDef external fill:#A2C4C9,stroke:#333,stroke-width:1px;
    classDef resources fill:#F9CB9C,stroke:#333,stroke-width:1px;
    classDef util fill:#B7DEE8,stroke:#333,stroke-width:1px;
    classDef config fill:#EAD1DC,stroke:#333,stroke-width:1px;
```
