red77290/dmd_gif_converter

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.