# mir-learn/ai-video-creator architecture

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

- Interactive diagram: https://gitdiagram.com/mir-learn/ai-video-creator
- Repository: https://github.com/mir-learn/ai-video-creator

## Overview

This is a local AI video creator: an agent or user prepares a story and reusable character, then chooses a narrated B-roll or talking-head workflow that produces a vertical video. Image/video generation is dispatched through the local ComfyUI client; audio, visual review, and final assembly are separate stages. The README documents model comparison and QA capabilities, though their full implementations were not sampled, so their wiring is shown only where supported.

Main entry points: [`stories`](https://github.com/mir-learn/ai-video-creator/tree/main/stories) (Story JSON), [`scripts/talk.py`](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/talk.py) (Lip-sync video), [`scripts/keyframes.py`](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/keyframes.py) (Portrait and keyframes), [`scripts/comfy.py`](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/comfy.py) (ComfyUI client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Story and characters"]
  node_story["Story JSON"]
  node_characters["Character assets"]
end

subgraph group_narrated["Narrated video"]
  node_audio["Narration TTS<br/>[tts.py]"]
  node_keyframes["Portrait and keyframes<br/>[keyframes.py]"]
  node_animate["Wan animation<br/>[animate.py]"]
  node_assemble["Video assembly<br/>[assemble.py]"]
  node_comfy["ComfyUI client<br/>[comfy.py]"]
end

subgraph group_talking["Talking head"]
  node_talkaudio["Designed voice TTS<br/>[tts_qwen.py]"]
  node_talk["Lip-sync video<br/>[talk.py]"]
  node_wordcaptions["Word timestamps<br/>[captions.py]"]
  node_finish["Talking export<br/>[finish_talk.py]"]
end

subgraph group_review["Review and comparison"]
  node_preview["Visual review<br/>[preview.py]"]
  node_linecheck["Voice QA<br/>[check_lines.py]"]
  node_compare["Model comparison"]
  node_comparecomfy["Comparison renders<br/>[compare_comfy.py]"]
end

node_creator(("User / agent"))
node_engine["ComfyUI engine"]
node_output["Generated media"]

node_creator -->|"writes"| node_story
node_creator -->|"creates"| node_characters
node_story -->|"provides lines"| node_audio
node_story -->|"provides prompts"| node_keyframes
node_characters -->|"reuses portrait"| node_keyframes
node_story -->|"provides motion"| node_animate
node_keyframes -->|"provides frames"| node_animate
node_audio -->|"provides narration"| node_assemble
node_animate -->|"provides clips"| node_assemble
node_story -->|"provides captions"| node_assemble
node_assemble -->|"writes final video"| node_output
node_story -->|"provides lines"| node_talkaudio
node_story -->|"provides prompts"| node_talk
node_talkaudio -->|"provides shot audio"| node_talk
node_keyframes -->|"provides start images"| node_talk
node_talk -->|"provides clips"| node_wordcaptions
node_talkaudio -->|"provides audio"| node_wordcaptions
node_wordcaptions -->|"provides timestamps"| node_finish
node_talk -->|"provides clips"| node_finish
node_story -->|"provides script"| node_finish
node_finish -->|"writes final video"| node_output
node_keyframes -->|"queues workflows"| node_comfy
node_animate -->|"queues workflows"| node_comfy
node_talk -->|"queues workflows"| node_comfy
node_comfy -->|"queues and polls"| node_engine
node_preview -->|"reads media"| node_output
node_linecheck -->|"checks audio"| node_output
node_creator -->|"reviews output"| node_preview
node_creator -->|"runs QA"| node_linecheck
node_comparecomfy -.->|"queues renders"| node_comfy
node_comparecomfy -.->|"writes comparison clips"| node_compare
node_compare -.->|"presents comparison"| node_creator

click node_story "https://github.com/mir-learn/ai-video-creator/tree/main/stories"
click node_characters "https://github.com/mir-learn/ai-video-creator/tree/main/characters"
click node_audio "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/tts.py"
click node_keyframes "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/keyframes.py"
click node_animate "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/animate.py"
click node_assemble "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/assemble.py"
click node_talkaudio "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/tts_qwen.py"
click node_talk "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/talk.py"
click node_wordcaptions "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/captions.py"
click node_finish "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/finish_talk.py"
click node_comfy "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/comfy.py"
click node_preview "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/preview.py"
click node_linecheck "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/check_lines.py"
click node_compare "https://github.com/mir-learn/ai-video-creator/tree/main/compare"
click node_comparecomfy "https://github.com/mir-learn/ai-video-creator/blob/main/scripts/compare_comfy.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_story,node_characters,node_creator,node_engine toneBlue
class node_audio,node_keyframes,node_animate,node_assemble,node_comfy toneAmber
class node_talkaudio,node_talk,node_wordcaptions,node_finish toneMint
class node_preview,node_linecheck,node_compare,node_comparecomfy toneRose
class node_output toneIndigo
```

## Components

### Story and characters

- [Story JSON](https://github.com/mir-learn/ai-video-creator/tree/main/stories): `stories`
- [Character assets](https://github.com/mir-learn/ai-video-creator/tree/main/characters): `characters`

### Narrated video

- [Narration TTS](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/tts.py): `scripts/tts.py`
- [Portrait and keyframes](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/keyframes.py): `scripts/keyframes.py`
- [Wan animation](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/animate.py): `scripts/animate.py`
- [Video assembly](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/assemble.py): `scripts/assemble.py`
- [ComfyUI client](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/comfy.py): `scripts/comfy.py`

### Talking head

- [Designed voice TTS](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/tts_qwen.py): `scripts/tts_qwen.py`
- [Lip-sync video](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/talk.py): `scripts/talk.py`
- [Word timestamps](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/captions.py): `scripts/captions.py`
- [Talking export](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/finish_talk.py): `scripts/finish_talk.py`

### Review and comparison

- [Visual review](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/preview.py): `scripts/preview.py`
- [Voice QA](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/check_lines.py): `scripts/check_lines.py`
- [Model comparison](https://github.com/mir-learn/ai-video-creator/tree/main/compare): `compare`
- [Comparison renders](https://github.com/mir-learn/ai-video-creator/blob/main/scripts/compare_comfy.py): `scripts/compare_comfy.py`

### Other components

- **User / agent**
- **ComfyUI engine**
- **Generated media**

## Connections

- User / agent → Story JSON: writes
- User / agent → Character assets: creates
- Story JSON → Narration TTS: provides lines
- Story JSON → Portrait and keyframes: provides prompts
- Character assets → Portrait and keyframes: reuses portrait
- Story JSON → Wan animation: provides motion
- Portrait and keyframes → Wan animation: provides frames
- Narration TTS → Video assembly: provides narration
- Wan animation → Video assembly: provides clips
- Story JSON → Video assembly: provides captions
- Video assembly → Generated media: writes final video
- Story JSON → Designed voice TTS: provides lines
- Story JSON → Lip-sync video: provides prompts
- Designed voice TTS → Lip-sync video: provides shot audio
- Portrait and keyframes → Lip-sync video: provides start images
- Lip-sync video → Word timestamps: provides clips
- Designed voice TTS → Word timestamps: provides audio
- Word timestamps → Talking export: provides timestamps
- Lip-sync video → Talking export: provides clips
- Story JSON → Talking export: provides script
- Talking export → Generated media: writes final video
- Portrait and keyframes → ComfyUI client: queues workflows
- Wan animation → ComfyUI client: queues workflows
- Lip-sync video → ComfyUI client: queues workflows
- ComfyUI client → ComfyUI engine: queues and polls
- Visual review → Generated media: reads media
- Voice QA → Generated media: checks audio
- User / agent → Visual review: reviews output
- User / agent → Voice QA: runs QA
- Comparison renders → ComfyUI client: queues renders
- Comparison renders → Model comparison: writes comparison clips
- Model comparison → User / agent: presents comparison