# rafaelgodoyebert/viralcutter architecture

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

- Interactive diagram: https://gitdiagram.com/rafaelgodoyebert/viralcutter
- Repository: https://github.com/rafaelgodoyebert/viralcutter

## Overview

ViralCutter turns long-form video into short, portrait clips with AI-selected moments, transcription, face-aware framing, styled subtitles, translation, and optional Premiere XML export. Users start from the CLI or Gradio WebUI; the documented workflow downloads a video, analyzes and cuts it, edits the framing, then produces subtitled clips for the project library. The graph includes these domain stages and the subtitle-editing and XML-export branches. Some runtime wiring is unsampled, so uncertain WebUI and optional AI-provider links are marked dashed.

Main entry points: [`main_improved.py`](https://github.com/rafaelgodoyebert/viralcutter/blob/main/main_improved.py) (CLI workflow), [`webui/app.py`](https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/app.py) (Gradio WebUI), [`scripts/edit_video.py`](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/edit_video.py) (Face-aware framing), [`scripts/export_xml_lib/exporter.py`](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/exporter.py) (Premiere XML export)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User interfaces"]
  node_cli["CLI workflow<br/>[main_improved.py]"]
  node_webui["Gradio WebUI<br/>[app.py]"]
end

subgraph group_processing["Clip processing"]
  node_download["Video download<br/>[download_video.py]"]
  node_transcribe["Whisper transcription"]
  node_viral["Moment selection"]
  node_cut["Segment cutting<br/>[cut_segments.py]"]
  node_framing["Face-aware framing<br/>[edit_video.py]"]
  node_face_single["Single-face crop<br/>[one_face.py]"]
  node_face_split["Split-screen crop<br/>[two_face.py]"]
  node_face_detect["Face detection"]
end

subgraph group_captions["Captions and translation"]
  node_subtitle_adjust["Subtitle styling"]
  node_subtitle_burn["Subtitle rendering<br/>[burn_subtitles.py]"]
  node_subtitle_editor["Subtitle editor<br/>[subtitle_editor.py]"]
  node_subtitle_handler["Subtitle controls"]
  node_translation["Subtitle translation<br/>[translate_json.py]"]
end

subgraph group_delivery["Project outputs"]
  node_library["Project library<br/>[library.py]"]
  node_organize["Output organization<br/>[organize_output.py]"]
  node_xml_export["Premiere XML export<br/>[exporter.py]"]
  node_xml_single["Single-face XML<br/>[xml_1face.py]"]
  node_xml_split["Split-screen XML<br/>[xml_2face.py]"]
  node_xml_common["XML composition<br/>[xml_common.py]"]
end

node_user(("Creator"))
node_ai_services{{"AI model providers"}}
node_youtube{{"YouTube"}}

node_user -->|"starts"| node_cli
node_user -->|"starts"| node_webui
node_cli -->|"downloads"| node_download
node_youtube -->|"provides video"| node_download
node_cli -->|"transcribes"| node_transcribe
node_cli -->|"selects moments"| node_viral
node_ai_services -.->|"analyzes"| node_viral
node_cli -->|"cuts segments"| node_cut
node_cli -->|"edits clips"| node_framing
node_framing -->|"uses"| node_face_single
node_framing -->|"uses"| node_face_split
node_framing -->|"detects faces"| node_face_detect
node_cli -->|"styles subtitles"| node_subtitle_adjust
node_cli -->|"burns subtitles"| node_subtitle_burn
node_webui -->|"offers editing"| node_subtitle_editor
node_subtitle_editor -->|"generates subtitles"| node_subtitle_adjust
node_webui -->|"offers controls"| node_subtitle_handler
node_subtitle_handler -->|"previews styles"| node_subtitle_adjust
node_cli -->|"translates"| node_translation
node_cli -->|"organizes output"| node_organize
node_webui -->|"shows projects"| node_library
node_webui -->|"requests export"| node_xml_export
node_xml_export -->|"generates single-face"| node_xml_single
node_xml_export -->|"generates split-screen"| node_xml_split
node_xml_single -->|"uses composition"| node_xml_common
node_xml_split -->|"uses composition"| node_xml_common

click node_cli "https://github.com/rafaelgodoyebert/viralcutter/blob/main/main_improved.py"
click node_webui "https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/app.py"
click node_download "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/download_video.py"
click node_transcribe "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/transcribe_video.py"
click node_viral "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/create_viral_segments.py"
click node_cut "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/cut_segments.py"
click node_framing "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/edit_video.py"
click node_face_single "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/one_face.py"
click node_face_split "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/two_face.py"
click node_face_detect "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/face_detection_insightface.py"
click node_subtitle_adjust "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/adjust_subtitles.py"
click node_subtitle_burn "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/burn_subtitles.py"
click node_subtitle_editor "https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/subtitle_editor.py"
click node_subtitle_handler "https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/subtitle_handler.py"
click node_translation "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/translate_json.py"
click node_library "https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/library.py"
click node_organize "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/organize_output.py"
click node_xml_export "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/exporter.py"
click node_xml_single "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/xml_1face.py"
click node_xml_split "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/xml_2face.py"
click node_xml_common "https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/xml_common.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_cli,node_webui toneBlue
class node_download,node_transcribe,node_viral,node_cut,node_framing,node_face_single,node_face_split,node_face_detect toneAmber
class node_subtitle_adjust,node_subtitle_burn,node_subtitle_editor,node_subtitle_handler,node_translation toneMint
class node_library,node_organize,node_xml_export,node_xml_single,node_xml_split,node_xml_common toneRose
class node_user,node_ai_services,node_youtube toneIndigo
```

## Components

### User interfaces

- [CLI workflow](https://github.com/rafaelgodoyebert/viralcutter/blob/main/main_improved.py): `main_improved.py`
- [Gradio WebUI](https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/app.py): `webui/app.py`

### Clip processing

- [Video download](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/download_video.py): `scripts/download_video.py`
- [Whisper transcription](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/transcribe_video.py): `scripts/transcribe_video.py`
- [Moment selection](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/create_viral_segments.py): `scripts/create_viral_segments.py`
- [Segment cutting](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/cut_segments.py): `scripts/cut_segments.py`
- [Face-aware framing](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/edit_video.py): `scripts/edit_video.py`
- [Single-face crop](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/one_face.py): `scripts/one_face.py`
- [Split-screen crop](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/two_face.py): `scripts/two_face.py`
- [Face detection](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/face_detection_insightface.py): `scripts/face_detection_insightface.py`

### Captions and translation

- [Subtitle styling](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/adjust_subtitles.py): `scripts/adjust_subtitles.py`
- [Subtitle rendering](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/burn_subtitles.py): `scripts/burn_subtitles.py`
- [Subtitle editor](https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/subtitle_editor.py): `webui/subtitle_editor.py`
- [Subtitle controls](https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/subtitle_handler.py): `webui/subtitle_handler.py`
- [Subtitle translation](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/translate_json.py): `scripts/translate_json.py`

### Project outputs

- [Project library](https://github.com/rafaelgodoyebert/viralcutter/blob/main/webui/library.py): `webui/library.py`
- [Output organization](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/organize_output.py): `scripts/organize_output.py`
- [Premiere XML export](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/exporter.py): `scripts/export_xml_lib/exporter.py`
- [Single-face XML](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/xml_1face.py): `scripts/export_xml_lib/xml_1face.py`
- [Split-screen XML](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/xml_2face.py): `scripts/export_xml_lib/xml_2face.py`
- [XML composition](https://github.com/rafaelgodoyebert/viralcutter/blob/main/scripts/export_xml_lib/xml_common.py): `scripts/export_xml_lib/xml_common.py`

### Other components

- **Creator**
- **AI model providers**
- **YouTube**

## Connections

- Creator → CLI workflow: starts (evidence: `README.md`)
- Creator → Gradio WebUI: starts (evidence: `README.md`)
- CLI workflow → Video download: downloads (evidence: `main_improved.py`)
- YouTube → Video download: provides video (evidence: `README.md`)
- CLI workflow → Whisper transcription: transcribes (evidence: `main_improved.py`)
- CLI workflow → Moment selection: selects moments (evidence: `main_improved.py`)
- AI model providers → Moment selection: analyzes (evidence: `README.md`)
- CLI workflow → Segment cutting: cuts segments (evidence: `main_improved.py`)
- CLI workflow → Face-aware framing: edits clips (evidence: `main_improved.py`)
- Face-aware framing → Single-face crop: uses (evidence: `scripts/edit_video.py`)
- Face-aware framing → Split-screen crop: uses (evidence: `scripts/edit_video.py`)
- Face-aware framing → Face detection: detects faces (evidence: `scripts/edit_video.py`)
- CLI workflow → Subtitle styling: styles subtitles (evidence: `main_improved.py`)
- CLI workflow → Subtitle rendering: burns subtitles (evidence: `main_improved.py`)
- Gradio WebUI → Subtitle editor: offers editing (evidence: `webui/app.py`)
- Subtitle editor → Subtitle styling: generates subtitles (evidence: `webui/subtitle_editor.py`)
- Gradio WebUI → Subtitle controls: offers controls (evidence: `webui/app.py`)
- Subtitle controls → Subtitle styling: previews styles (evidence: `webui/subtitle_handler.py`)
- CLI workflow → Subtitle translation: translates (evidence: `main_improved.py`)
- CLI workflow → Output organization: organizes output (evidence: `main_improved.py`)
- Gradio WebUI → Project library: shows projects (evidence: `webui/app.py`)
- Gradio WebUI → Premiere XML export: requests export (evidence: `webui/app.py`)
- Premiere XML export → Single-face XML: generates single-face (evidence: `scripts/export_xml_lib/exporter.py`)
- Premiere XML export → Split-screen XML: generates split-screen (evidence: `scripts/export_xml_lib/exporter.py`)
- Single-face XML → XML composition: uses composition (evidence: `scripts/export_xml_lib/xml_1face.py`)
- Split-screen XML → XML composition: uses composition (evidence: `scripts/export_xml_lib/xml_2face.py`)
