# red77290/dmd_gif_converter architecture

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

- Interactive diagram: https://gitdiagram.com/red77290/dmd_gif_converter
- Repository: https://github.com/red77290/dmd_gif_converter

## Overview

1. **Repository shape**
   - This project is split into three major layers under `src/`: a **conversion engine**, an **AI-assisted auto-action/video analysis engine**, and a **cross-platform desktop UI**.
   - The README makes clear there are also two entry modes: a **GUI launcher** and a **CLI automation path**, with the UI depending on optional third-party packages while the core engine is intended to stay lightweight.

2. **Primary product goal**
   - The system transforms source media files—animated GIFs or common video formats—into output optimized for a **128×32 HUB75 LED matrix**.
   - The important architectural constraint is that the output is not a generic video export; it is tailored for **DMD/LED visibility**, which drives the color, framing, trimming, and scoring subsystems.

3. **Core conversion pipeline**
   - `src/engine/conversion` is the main media-processing subsystem.
   - It contains the command-line entrypoints, conversion core logic, FFmpeg helpers, colorimetry/quality logic, and several services that break work into jobs, run batch orchestration, and apply overlays.
   - The data flow here is: **input media → job expansion/batch orchestration → FFmpeg-based conversion → optional overlay/color adjustments → exported GIF/output artifact**.

4. **Conversion services boundary**
   - The `services/` subpackage is where most of the reusable conversion behaviors live:
     - `ffmpeg_converter.py` for actual transcoding,
     - `batch_orchestrator.py` for multi-file processing,
     - `job_expander.py` for splitting or normalizing work,
     - `gif_search_service.py` and `search_engines.py` for remote GIF acquisition,
     - `pillow_overlay.py` for text or image overlays when FFmpeg is not enough.
   - This is the main boundary between “orchestration” and “media processing.”

5. **Auto-action / cinematic framing subsystem**
   - `src/engine/auto_action` is the AI-assisted framing pipeline.
   - It includes reader/renderer/writer components plus `camera.py`, `pipeline.py`, and `interfaces.py`, indicating a staged flow:
     - **read frames**
     - **analyze/track subjects**
     - **decide camera motion and crop**
     - **render intermediate output**
     - **write final framed media**
   - The README’s “Auto Action Framing” maps to this subsystem: it dynamically tracks subjects and crops the scene to keep action centered for a tiny display.

6. **Analysis and scene classification**
   - `src/engine/analysis` appears to provide the non-UI analytical core used to classify scenes and drive automated decisions.
   - `scene_types.py`, `analyzer.py`, and `analysis.py` suggest a pipeline that scores or labels content so the rest of the system can choose the right camera/profile behavior.
   - This is the bridge between raw frame data and higher-level heuristics like platformer/talking/action scene handling.

7. **AI moments extraction**
   - The `auto_action/ai_moments.py` module and the UI’s dedicated AI moments panel indicate a separate feature for **finding the best highlight segments** inside long videos.
   - The README describes this as “AI Iconic Moments,” which is conceptually distinct from framing: it selects **which parts of a source video are worth exporting**, whereas auto-action decides **how to frame them**.
   - In architecture terms, this is a **pre-conversion content selection layer** that feeds clips into the conversion workflow.

8. **Plugin-style scoring and detection**
   - `src/plugins` contains reusable AI/heuristic components:
     - `detectors/` for detection logic,
     - `trackers/` for tracking subject motion,
     - `scorers/` for quality/ranking logic such as AI moments, DMD-specific scoring, and highlights.
   - This suggests the engine is designed with **pluggable scoring and detection strategies**, so different pipelines can share common detection/tracking primitives without hard-coding behavior into the UI or converter.

9. **Configuration and feature flags**
   - `src/engine/config` holds separate config modules for auto-action, conversion, display, and export.
   - That separation indicates configuration is organized by **feature domain**, not by user interface screen.
   - The README’s “Per-GIF Config,” “Advanced Settings,” and “Let Me Handle It” modes all depend on these config boundaries, where global defaults can be overridden per file or per operation.

10. **UI architecture**
    - `src/ui` is a structured desktop app built around **controllers, models, panels, preview, settings, events, and widgets**.
    - `application_state.py` is the shared state model; `event_bus.py` is the coordination mechanism; controllers mediate between UI actions and engine calls.
    - Panels are split by responsibility: action list, AI moments, left/middle panels, preview, and settings screens. This suggests a **model–event–controller** style rather than a monolithic Tkinter window.

11. **Preview and visualization path**
    - The UI includes a preview subsystem (`src/ui/preview`) and a DMD LED simulator (`dmd_led_sim.py`).
    - From the README, the preview is three-part: **source**, **auto-action intermediate**, and **final DMD output**.
    - This means the UI does not just display final results; it visualizes the **intermediate pipeline states** so users can inspect cropping, auto-framing, and the LED-grid effect before exporting.

12. **External dependencies and runtime boundaries**
    - **FFmpeg** is the key system-level dependency for media processing.
    - **OpenCV + ONNX Runtime** are optional and only matter for auto-action/YOLO-style inference.
    - **CustomTkinter**, **Pillow**, **duckduckgo-search**, and **Requests** are UI/auxiliary dependencies.
    - The architecture intentionally keeps the CLI/engine mostly standard-library-based, while the UI and AI features are opt-in through extra packages.

13. **Entry points and deployment model**
    - The repository provides OS-specific launchers (`launch_ui.sh`, `.bat`, `.ps1`) that bootstrap a local environment and start the GUI.
    - That indicates the UI is expected to be run as a **self-contained desktop application**, while the engine can also be used headlessly via CLI modules in `engine/conversion/cli.py` and `engine/auto_action/cli.py`.

14. **Testing and repo validation**
    - The `tests/` tree is organized to mirror the architecture: separate suites for `auto_action`, `converter`, `engine/analysis`, and `ui`.
    - This mirrors the system boundaries and suggests each subsystem is meant to be testable in isolation, especially where AI, FFmpeg, and UI event flow intersect.

Main entry points: [`src/ui/app.py`](https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/app.py) (App), [`src/engine/auto_action/pipeline.py`](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/pipeline.py) (Pipeline), [`src/engine/conversion/services`](https://github.com/red77290/dmd_gif_converter/tree/main/src/engine/conversion/services) (Services), [`src/ui/controllers`](https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/controllers) (Controllers)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_src_engine_conversion["Conversion Engine"]
  node_conversion_cli["CLI<br/>conversion entrypoint<br/>[cli.py]"]
  node_conversion_core["Core<br/>conversion pipeline<br/>[core.py]"]
  node_conversion_services["Services"]
  node_ffmpeg_converter["FFmpeg<br/>transcoding service"]
  node_batch_orchestrator["Batch<br/>orchestration service"]
  node_job_expander["Jobs<br/>work splitter<br/>[job_expander.py]"]
  node_overlay_search["Overlays<br/>overlay and search services"]
end

subgraph group_src_engine_auto_action["Auto Action"]
  node_auto_cli["Auto CLI<br/>auto-action entrypoint<br/>[cli.py]"]
  node_auto_pipeline["Pipeline<br/>[pipeline.py]"]
  node_auto_camera["Camera<br/>crop/motion logic<br/>[camera.py]"]
  node_ai_moments["AI Moments<br/>clip selection<br/>[ai_moments.py]"]
end

subgraph group_src_engine_analysis["Analysis"]
  node_analysis_core["Analysis Core<br/>scene analysis<br/>[analysis.py]"]
  node_scene_types["Scene Types<br/>scene taxonomy<br/>[scene_types.py]"]
end

subgraph group_src_plugins["Plugins"]
  node_detectors["Detectors<br/>detection plugins<br/>[detector.py]"]
  node_trackers["Trackers<br/>tracking plugins<br/>[tracker.py]"]
  node_scorers["Scorers<br/>ranking plugins"]
end

subgraph group_src_ui["Desktop UI"]
  node_ui_app["App<br/>desktop shell<br/>[app.py]"]
  node_ui_state["State"]
  node_ui_bus["Event Bus<br/>ui coordination<br/>[event_bus.py]"]
  node_ui_controllers["Controllers"]
  node_ui_panels["Panels"]
  node_ui_preview["Preview<br/>visualization<br/>[preview_panel.py]"]
  node_ui_dmd_sim["DMD Sim<br/>display simulator<br/>[dmd_led_sim.py]"]
  node_ui_settings["Settings"]
end

subgraph group_tests["Tests"]
  node_tests_converter["Converter Tests<br/>test suite"]
  node_tests_auto_action["Auto Action Tests<br/>test suite"]
  node_tests_ui["UI Tests<br/>test suite"]
end

node_conversion_cli -->|"invokes"| node_conversion_core
node_conversion_core -->|"delegates"| node_conversion_services
node_conversion_services -->|"uses"| node_ffmpeg_converter
node_conversion_services -->|"uses"| node_batch_orchestrator
node_conversion_services -->|"uses"| node_job_expander
node_conversion_services -->|"uses"| node_overlay_search
node_auto_cli -->|"invokes"| node_auto_pipeline
node_auto_pipeline -->|"drives"| node_auto_camera
node_auto_pipeline -->|"uses"| node_detectors
node_auto_pipeline -->|"uses"| node_trackers
node_auto_pipeline -->|"uses"| node_scorers
node_ai_moments -->|"scores with"| node_analysis_core
node_analysis_core -->|"classifies"| node_scene_types
node_ui_app -->|"binds"| node_ui_state
node_ui_app -->|"coordinates"| node_ui_bus
node_ui_app -->|"hosts"| node_ui_controllers
node_ui_controllers -->|"triggers"| node_conversion_core
node_ui_controllers -->|"triggers"| node_auto_pipeline
node_ui_app -->|"renders"| node_ui_panels
node_ui_app -->|"shows"| node_ui_preview
node_ui_app -->|"simulates"| node_ui_dmd_sim
node_ui_app -->|"configures"| node_ui_settings
node_ui_controllers -->|"publishes"| node_ui_bus
node_tests_converter -.->|"covers"| node_conversion_core
node_tests_auto_action -.->|"covers"| node_auto_pipeline
node_tests_ui -.->|"covers"| node_ui_app

click node_conversion_cli "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/cli.py"
click node_conversion_core "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/core.py"
click node_conversion_services "https://github.com/red77290/dmd_gif_converter/tree/main/src/engine/conversion/services"
click node_ffmpeg_converter "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/services/ffmpeg_converter.py"
click node_batch_orchestrator "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/services/batch_orchestrator.py"
click node_job_expander "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/services/job_expander.py"
click node_overlay_search "https://github.com/red77290/dmd_gif_converter/tree/main/src/engine/conversion/services"
click node_auto_cli "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/cli.py"
click node_auto_pipeline "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/pipeline.py"
click node_auto_camera "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/camera.py"
click node_ai_moments "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/ai_moments.py"
click node_analysis_core "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/analysis/analysis.py"
click node_scene_types "https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/analysis/scene_types.py"
click node_detectors "https://github.com/red77290/dmd_gif_converter/blob/main/src/plugins/detectors/detector.py"
click node_trackers "https://github.com/red77290/dmd_gif_converter/blob/main/src/plugins/trackers/tracker.py"
click node_scorers "https://github.com/red77290/dmd_gif_converter/tree/main/src/plugins/scorers"
click node_ui_app "https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/app.py"
click node_ui_state "https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/models/application_state.py"
click node_ui_bus "https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/events/event_bus.py"
click node_ui_controllers "https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/controllers"
click node_ui_panels "https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/panels"
click node_ui_preview "https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/preview/preview_panel.py"
click node_ui_dmd_sim "https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/dmd_led_sim.py"
click node_ui_settings "https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/settings"
click node_tests_converter "https://github.com/red77290/dmd_gif_converter/tree/main/tests/converter"
click node_tests_auto_action "https://github.com/red77290/dmd_gif_converter/tree/main/tests/auto_action"
click node_tests_ui "https://github.com/red77290/dmd_gif_converter/tree/main/tests/ui"

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_conversion_cli,node_conversion_core,node_conversion_services,node_ffmpeg_converter,node_batch_orchestrator,node_job_expander,node_overlay_search toneBlue
class node_auto_cli,node_auto_pipeline,node_auto_camera,node_ai_moments toneAmber
class node_analysis_core,node_scene_types toneMint
class node_detectors,node_trackers,node_scorers toneRose
class node_ui_app,node_ui_state,node_ui_bus,node_ui_controllers,node_ui_panels,node_ui_preview,node_ui_dmd_sim,node_ui_settings toneIndigo
class node_tests_converter,node_tests_auto_action,node_tests_ui toneTeal
```

## Components

### Conversion Engine

Media conversion pipeline for GIF/video to DMD-optimized output.

- [CLI](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/cli.py): conversion entrypoint · Headless conversion entrypoint for batch or scripted use. · `src/engine/conversion/cli.py`
- [Core](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/core.py): conversion pipeline · Central conversion workflow coordinating media transforms and output generation. · `src/engine/conversion/core.py`
- [Services](https://github.com/red77290/dmd_gif_converter/tree/main/src/engine/conversion/services): conversion services · Reusable orchestration and media-processing services boundary. · `src/engine/conversion/services`
- [FFmpeg](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/services/ffmpeg_converter.py): transcoding service · Primary transcoding and media conversion implementation. · `src/engine/conversion/services/ffmpeg_converter.py`
- [Batch](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/services/batch_orchestrator.py): orchestration service · Coordinates multi-file processing and batch execution. · `src/engine/conversion/services/batch_orchestrator.py`
- [Jobs](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/conversion/services/job_expander.py): work splitter · Expands or normalizes incoming work items before conversion. · `src/engine/conversion/services/job_expander.py`
- [Overlays](https://github.com/red77290/dmd_gif_converter/tree/main/src/engine/conversion/services): overlay and search services · GIF search, remote acquisition, and Pillow-based overlays. · `src/engine/conversion/services`

### Auto Action

AI-assisted framing, clip selection, and cinematic crop pipeline.

- [Auto CLI](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/cli.py): auto-action entrypoint · Headless entrypoint for AI-assisted framing and moments workflows. · `src/engine/auto_action/cli.py`
- [Pipeline](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/pipeline.py): framing pipeline · Staged auto-action workflow from reading frames to final rendered output. · `src/engine/auto_action/pipeline.py`
- [Camera](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/camera.py): crop/motion logic · Decides framing, motion, and crop behavior for tiny-display output. · `src/engine/auto_action/camera.py`
- [AI Moments](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/auto_action/ai_moments.py): clip selection · Selects highlight or iconic segments worth exporting. · `src/engine/auto_action/ai_moments.py`

### Analysis

Scene analysis and classification used by automated decisions.

- [Analysis Core](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/analysis/analysis.py): scene analysis · Scores and labels scenes to drive automated decisions. · `src/engine/analysis/analysis.py`
- [Scene Types](https://github.com/red77290/dmd_gif_converter/blob/main/src/engine/analysis/scene_types.py): scene taxonomy · Defines scene categories and classification labels. · `src/engine/analysis/scene_types.py`

### Plugins

Reusable detectors, trackers, and scoring strategies.

- [Detectors](https://github.com/red77290/dmd_gif_converter/blob/main/src/plugins/detectors/detector.py): detection plugins · Reusable subject and motion detection primitives. · `src/plugins/detectors/detector.py`
- [Trackers](https://github.com/red77290/dmd_gif_converter/blob/main/src/plugins/trackers/tracker.py): tracking plugins · Motion and subject tracking primitives shared across pipelines. · `src/plugins/trackers/tracker.py`
- [Scorers](https://github.com/red77290/dmd_gif_converter/tree/main/src/plugins/scorers): ranking plugins · Heuristics and AI scoring for highlights, DMD visibility, and moments. · `src/plugins/scorers`

### Desktop UI

Cross-platform desktop application, state, preview, and controls.

- [App](https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/app.py): desktop shell · Main desktop application shell and launcher wiring. · `src/ui/app.py`
- [State](https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/models/application_state.py): application state · Shared UI state model used across panels and controllers. · `src/ui/models/application_state.py`
- [Event Bus](https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/events/event_bus.py): ui coordination · Event-driven coordination mechanism between controllers and views. · `src/ui/events/event_bus.py`
- [Controllers](https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/controllers): ui controllers · Bridges user actions to engine calls and state updates. · `src/ui/controllers`
- [Panels](https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/panels): ui panels · Main workspace panels for actions, AI moments, and layout. · `src/ui/panels`
- [Preview](https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/preview/preview_panel.py): visualization · Source, auto-action, and final-output preview path. · `src/ui/preview/preview_panel.py`
- [DMD Sim](https://github.com/red77290/dmd_gif_converter/blob/main/src/ui/dmd_led_sim.py): display simulator · Simulates the HUB75 LED matrix appearance in the UI. · `src/ui/dmd_led_sim.py`
- [Settings](https://github.com/red77290/dmd_gif_converter/tree/main/src/ui/settings): settings screens · Feature-specific settings for conversion, display, export, and auto-action. · `src/ui/settings`

### Tests

Architecture-mirroring test suites for major subsystems.

- [Converter Tests](https://github.com/red77290/dmd_gif_converter/tree/main/tests/converter): test suite · Tests for conversion core, CLI, quality, and FFmpeg helpers. · `tests/converter`
- [Auto Action Tests](https://github.com/red77290/dmd_gif_converter/tree/main/tests/auto_action): test suite · Tests for framing, camera, analysis, detector, tracker, and AI moments. · `tests/auto_action`
- [UI Tests](https://github.com/red77290/dmd_gif_converter/tree/main/tests/ui): test suite · Tests for application state, event bus, controllers, preview, and widgets. · `tests/ui`

## Connections

- CLI → Core: invokes · CLI drives the main conversion workflow.
- Core → Services: delegates · Core conversion logic relies on reusable services.
- Services → FFmpeg: uses · Transcoding is handled by the FFmpeg service.
- Services → Batch: uses · Batch execution is coordinated here.
- Services → Jobs: uses · Incoming work is expanded into executable jobs.
- Services → Overlays: uses · Search and overlay helpers support the conversion pipeline.
- Auto CLI → Pipeline: invokes · CLI starts the staged auto-action pipeline.
- Pipeline → Camera: drives · Pipeline feeds framing and crop decisions into camera logic.
- Pipeline → Detectors: uses · Detection primitives support subject and motion analysis.
- Pipeline → Trackers: uses · Tracking primitives maintain subject continuity.
- Pipeline → Scorers: uses · Scoring strategies rank candidate clips or frames.
- AI Moments → Analysis Core: scores with · AI moments depends on scene analysis and ranking.
- Analysis Core → Scene Types: classifies · Analysis assigns scene categories and behaviors.
- App → State: binds · Desktop shell binds to shared application state.
- App → Event Bus: coordinates · Events connect UI components and controllers.
- App → Controllers: hosts · Controllers mediate between user actions and engine calls.
- Controllers → Core: triggers · UI can launch conversion workflows.
- Controllers → Pipeline: triggers · UI can launch auto-action framing workflows.
- App → Panels: renders · Main workspace is composed of multiple functional panels.
- App → Preview: shows · Preview exposes source, intermediate, and final states.
- App → DMD Sim: simulates · LED matrix output is visualized in-app.
- App → Settings: configures · Feature-specific settings screens configure the app.
- Controllers → Event Bus: publishes · Controllers push state changes through the event bus.
- Converter Tests → Core: covers · Converter tests exercise core conversion behavior.
- Auto Action Tests → Pipeline: covers · Auto-action tests exercise framing and analysis flow.
- UI Tests → App: covers · UI tests validate state, events, and panel behavior.