# dcroma1/codex-video-tool architecture

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

- Interactive diagram: https://gitdiagram.com/dcroma1/codex-video-tool
- Repository: https://github.com/dcroma1/codex-video-tool

## Overview

Codex Video Tool is a CLI application that turns a script or video spec and source images into a vertical marketing video. The user invokes `make` or `build`; the documented workflow prepares narration and shot cards, combines narration with optional music, and produces an MP4 and supporting artifacts. The sampled implementation is concentrated in `codex_video/cli.py`; the README documents major workflow stages whose orchestration details were not excerpted, so those links cite the README rather than implying additional source inspection.

Main entry points: [`codex_video/cli.py`](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py) (CLI command)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["CLI and Inputs"]
  node_command["CLI command<br/>[cli.py]"]
  node_spec["Spec and script<br/>[cli.py]"]
  node_media["Source images<br/>[cli.py]"]
end

subgraph group_visuals["Visual Production"]
  node_cards["Shot cards<br/>[cli.py]"]
end

subgraph group_audio["Audio Production"]
  node_narration["Narration audio<br/>[cli.py]"]
  node_tts["TTS providers<br/>[cli.py]"]
  node_music["Music mix<br/>[cli.py]"]
end

subgraph group_output["Video Output"]
  node_ffmpeg["ffmpeg tools"]
  node_video["Final MP4<br/>[cli.py]"]
  node_manifest["Build manifest<br/>[cli.py]"]
end

node_user(("User"))

node_user -->|"runs"| node_command
node_command -->|"reads"| node_spec
node_command -->|"uses"| node_media
node_command -->|"creates"| node_cards
node_command -->|"generates or attaches"| node_narration
node_narration -.->|"may use"| node_tts
node_command -->|"mixes"| node_music
node_command -->|"invokes"| node_ffmpeg
node_command -->|"produces"| node_video
node_command -->|"produces"| node_manifest
node_cards -->|"compiled into"| node_video
node_narration -->|"mixed into"| node_video
node_music -->|"mixed into"| node_video

click node_command "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_spec "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_media "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_cards "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_narration "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_tts "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_music "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_video "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py"
click node_manifest "https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.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_command,node_spec,node_media,node_user toneBlue
class node_cards toneAmber
class node_narration,node_tts,node_music toneMint
class node_ffmpeg,node_video,node_manifest toneRose
```

## Components

### CLI and Inputs

- [CLI command](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`
- [Spec and script](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`
- [Source images](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`

### Visual Production

- [Shot cards](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`

### Audio Production

- [Narration audio](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`
- [TTS providers](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`
- [Music mix](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`

### Video Output

- **ffmpeg tools**
- [Final MP4](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`
- [Build manifest](https://github.com/dcroma1/codex-video-tool/blob/main/codex_video/cli.py): `codex_video/cli.py`

### Other components

- **User**

## Connections

- User → CLI command: runs (evidence: `README.md`)
- CLI command → Spec and script: reads (evidence: `README.md`)
- CLI command → Source images: uses (evidence: `README.md`)
- CLI command → Shot cards: creates (evidence: `README.md`)
- CLI command → Narration audio: generates or attaches (evidence: `README.md`)
- Narration audio → TTS providers: may use (evidence: `README.md`)
- CLI command → Music mix: mixes (evidence: `README.md`)
- CLI command → ffmpeg tools: invokes (evidence: `codex_video/cli.py`)
- CLI command → Final MP4: produces (evidence: `README.md`)
- CLI command → Build manifest: produces (evidence: `README.md`)
- Shot cards → Final MP4: compiled into (evidence: `README.md`)
- Narration audio → Final MP4: mixed into (evidence: `README.md`)
- Music mix → Final MP4: mixed into (evidence: `README.md`)