# nzeronfourme/movieshort-ai architecture

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

- Interactive diagram: https://gitdiagram.com/nzeronfourme/movieshort-ai
- Repository: https://github.com/nzeronfourme/movieshort-ai

## Overview

MovieShort AI turns a movie into vertically formatted Shorts through a Gradio interface: analyze scenes and dialogue, select clips (with optional LLM scoring), then render crops and subtitles. Batch processing owns the analysis and clip-selection flow; the rendering pipeline handles per-clip output. The graph also includes settings, provider integrations, and person tracking. Relationships are limited to README statements and import/call references in the supplied SOURCE INDEX or excerpts; unsampled implementation details are not inferred.

Main entry points: [`core/pipeline.py`](https://github.com/nzeronfourme/movieshort-ai/blob/main/core/pipeline.py) (Render pipeline), [`gui/app.py`](https://github.com/nzeronfourme/movieshort-ai/blob/main/gui/app.py) (Gradio interface), [`core/batch.py`](https://github.com/nzeronfourme/movieshort-ai/blob/main/core/batch.py) (Batch selection), [`utils/ffmpeg_utils.py`](https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/ffmpeg_utils.py) (Video transforms)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interface["User interface"]
  node_app["Gradio interface<br/>[app.py]"]
end

subgraph group_analysis["Movie analysis"]
  node_batch["Batch selection<br/>[batch.py]"]
  node_detector["Scene detector<br/>[detector.py]"]
  node_scene["Scene analysis<br/>[scene_analyzer.py]"]
  node_scoring["Clip scoring<br/>[text_analyzer.py]"]
end

subgraph group_rendering["Clip rendering"]
  node_pipeline["Render pipeline<br/>[pipeline.py]"]
  node_processor["Person tracking<br/>[processor.py]"]
  node_subtitle["Transcription and subtitles<br/>[subtitle.py]"]
  node_ffmpeg["Video transforms<br/>[ffmpeg_utils.py]"]
  node_font["Font management<br/>[font_manager.py]"]
end

subgraph group_support["Configuration and utilities"]
  node_config["Runtime defaults<br/>[config.py]"]
  node_settings["User settings<br/>[user_config.py]"]
  node_logs["Log capture<br/>[log_capture.py]"]
end

subgraph group_integrations["External services"]
  node_provider{{"LLM providers"}}
  node_ffmpeg_service{{"FFmpeg tools"}}
  node_whisper{{"faster-whisper"}}
end

node_user(("Movie editor"))
node_clips["Rendered clips"]

node_user -->|"selects movie"| node_app
node_app -->|"starts batch"| node_batch
node_app -->|"starts manual render"| node_pipeline
node_app -->|"loads and saves"| node_settings
node_app -->|"verifies provider key"| node_scoring
node_app -->|"captures logs"| node_logs
node_batch -->|"requests scenes"| node_detector
node_batch -->|"uses analysis"| node_scene
node_batch -->|"scores blocks"| node_scoring
node_batch -->|"transcribes movie"| node_subtitle
node_batch -->|"renders selected clips"| node_pipeline
node_detector -->|"uses scene analysis"| node_scene
node_scoring -->|"sends scoring requests"| node_provider
node_scene -->|"probes and extracts media"| node_ffmpeg_service
node_subtitle -.->|"transcribes audio"| node_whisper
node_pipeline -->|"tracks people"| node_processor
node_pipeline -->|"generates subtitles"| node_subtitle
node_pipeline -->|"applies video transforms"| node_ffmpeg
node_pipeline -->|"resolves subtitle font"| node_font
node_pipeline -->|"loads preferences"| node_settings
node_ffmpeg -->|"uses font assets"| node_font
node_ffmpeg -->|"runs media commands"| node_ffmpeg_service
node_pipeline -->|"writes rendered clips"| node_clips
node_batch -->|"uses defaults"| node_config
node_pipeline -->|"uses defaults"| node_config
node_app -->|"reads runtime settings"| node_config

click node_app "https://github.com/nzeronfourme/movieshort-ai/blob/main/gui/app.py"
click node_batch "https://github.com/nzeronfourme/movieshort-ai/blob/main/core/batch.py"
click node_detector "https://github.com/nzeronfourme/movieshort-ai/blob/main/analyzers/detector.py"
click node_scene "https://github.com/nzeronfourme/movieshort-ai/blob/main/analyzers/scene_analyzer.py"
click node_scoring "https://github.com/nzeronfourme/movieshort-ai/blob/main/analyzers/text_analyzer.py"
click node_pipeline "https://github.com/nzeronfourme/movieshort-ai/blob/main/core/pipeline.py"
click node_processor "https://github.com/nzeronfourme/movieshort-ai/blob/main/core/processor.py"
click node_subtitle "https://github.com/nzeronfourme/movieshort-ai/blob/main/core/subtitle.py"
click node_ffmpeg "https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/ffmpeg_utils.py"
click node_font "https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/font_manager.py"
click node_config "https://github.com/nzeronfourme/movieshort-ai/blob/main/config.py"
click node_settings "https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/user_config.py"
click node_logs "https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/log_capture.py"
click node_clips "https://github.com/nzeronfourme/movieshort-ai/tree/main/output"

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_app toneBlue
class node_batch,node_detector,node_scene,node_scoring toneAmber
class node_pipeline,node_processor,node_subtitle,node_ffmpeg,node_font toneMint
class node_config,node_settings,node_logs toneRose
class node_provider,node_ffmpeg_service,node_whisper,node_user toneIndigo
class node_clips toneTeal
```

## Components

### User interface

- [Gradio interface](https://github.com/nzeronfourme/movieshort-ai/blob/main/gui/app.py): `gui/app.py`

### Movie analysis

- [Batch selection](https://github.com/nzeronfourme/movieshort-ai/blob/main/core/batch.py): `core/batch.py`
- [Scene detector](https://github.com/nzeronfourme/movieshort-ai/blob/main/analyzers/detector.py): `analyzers/detector.py`
- [Scene analysis](https://github.com/nzeronfourme/movieshort-ai/blob/main/analyzers/scene_analyzer.py): `analyzers/scene_analyzer.py`
- [Clip scoring](https://github.com/nzeronfourme/movieshort-ai/blob/main/analyzers/text_analyzer.py): `analyzers/text_analyzer.py`

### Clip rendering

- [Render pipeline](https://github.com/nzeronfourme/movieshort-ai/blob/main/core/pipeline.py): `core/pipeline.py`
- [Person tracking](https://github.com/nzeronfourme/movieshort-ai/blob/main/core/processor.py): `core/processor.py`
- [Transcription and subtitles](https://github.com/nzeronfourme/movieshort-ai/blob/main/core/subtitle.py): `core/subtitle.py`
- [Video transforms](https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/ffmpeg_utils.py): `utils/ffmpeg_utils.py`
- [Font management](https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/font_manager.py): `utils/font_manager.py`

### Configuration and utilities

- [Runtime defaults](https://github.com/nzeronfourme/movieshort-ai/blob/main/config.py): `config.py`
- [User settings](https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/user_config.py): `utils/user_config.py`
- [Log capture](https://github.com/nzeronfourme/movieshort-ai/blob/main/utils/log_capture.py): `utils/log_capture.py`

### External services

- **LLM providers**
- **FFmpeg tools**
- **faster-whisper**

### Other components

- **Movie editor**
- [Rendered clips](https://github.com/nzeronfourme/movieshort-ai/tree/main/output): `output`

## Connections

- Movie editor → Gradio interface: selects movie (evidence: `README.md`)
- Gradio interface → Batch selection: starts batch (evidence: `gui/app.py`)
- Gradio interface → Render pipeline: starts manual render (evidence: `gui/app.py`)
- Gradio interface → User settings: loads and saves (evidence: `gui/app.py`)
- Gradio interface → Clip scoring: verifies provider key (evidence: `gui/app.py`)
- Gradio interface → Log capture: captures logs (evidence: `gui/app.py`)
- Batch selection → Scene detector: requests scenes (evidence: `core/batch.py`)
- Batch selection → Scene analysis: uses analysis (evidence: `core/batch.py`)
- Batch selection → Clip scoring: scores blocks (evidence: `core/batch.py`)
- Batch selection → Transcription and subtitles: transcribes movie (evidence: `core/batch.py`)
- Batch selection → Render pipeline: renders selected clips (evidence: `core/batch.py`)
- Scene detector → Scene analysis: uses scene analysis (evidence: `analyzers/detector.py`)
- Clip scoring → LLM providers: sends scoring requests (evidence: `analyzers/text_analyzer.py`)
- Scene analysis → FFmpeg tools: probes and extracts media (evidence: `analyzers/scene_analyzer.py`)
- Transcription and subtitles → faster-whisper: transcribes audio
- Render pipeline → Person tracking: tracks people (evidence: `core/pipeline.py`)
- Render pipeline → Transcription and subtitles: generates subtitles (evidence: `core/pipeline.py`)
- Render pipeline → Video transforms: applies video transforms (evidence: `core/pipeline.py`)
- Render pipeline → Font management: resolves subtitle font (evidence: `core/pipeline.py`)
- Render pipeline → User settings: loads preferences (evidence: `core/pipeline.py`)
- Video transforms → Font management: uses font assets (evidence: `utils/ffmpeg_utils.py`)
- Video transforms → FFmpeg tools: runs media commands (evidence: `utils/ffmpeg_utils.py`)
- Render pipeline → Rendered clips: writes rendered clips (evidence: `README.md`)
- Batch selection → Runtime defaults: uses defaults (evidence: `core/batch.py`)
- Render pipeline → Runtime defaults: uses defaults (evidence: `core/pipeline.py`)
- Gradio interface → Runtime defaults: reads runtime settings (evidence: `gui/app.py`)
