# anil-matcha/zack-d-films-ai-video-generator architecture

> Architecture diagram of the GitHub repository anil-matcha/zack-d-films-ai-video-generator, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/anil-matcha/zack-d-films-ai-video-generator
- Repository: https://github.com/anil-matcha/zack-d-films-ai-video-generator

## Overview

This repository is an agent-guided pipeline for turning a topic into a vertical, stylized 3D explainer short. The user or coding agent researches/selects a topic, creates and reviews a beat map, then generates character references, keyframes, motion clips, and narration before assembling the final video. The README describes approval gates and additional editing capabilities; the sampled assembly code confirms clip ordering, impact zooms, transitions, and audio handling. The sampled scripts show MuAPI calls through a shared provider. Other README-described details, including caption behavior, are not independently verified in the excerpts.

Main entry points: [`scripts/script_generator.py`](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/script_generator.py) (beats.json), [`scripts/provider.py`](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/provider.py) (MuAPI client), [`scripts/clips.py`](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/clips.py) (Motion clips), [`scripts/assemble.py`](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/assemble.py) (Video assembly)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_planning["Topic and story"]
  node_research["Topic research<br/>[trend_research.py]"]
  node_script["Beat breakdown"]
  node_beats["beats.json"]
end

subgraph group_visuals["Visual production"]
  node_sheets["Character sheets"]
  node_keyframes["Keyframes<br/>[keyframes.py]"]
  node_clips["Motion clips<br/>[clips.py]"]
end

subgraph group_media["Audio and assembly"]
  node_audio["Narration audio<br/>[audio.py]"]
  node_assembly["Video assembly<br/>[assemble.py]"]
  node_final["final.mp4<br/>[assemble.py]"]
end

subgraph group_services["Provider integration"]
  node_provider["MuAPI client<br/>[provider.py]"]
end

node_creator(("User / agent"))
node_muapi{{"MuAPI platform"}}
node_ffmpeg{{"FFmpeg / ffprobe"}}

node_creator -->|"explores topics"| node_research
node_creator -->|"provides topic"| node_script
node_research -->|"selects topic"| node_script
node_script -->|"writes beats"| node_beats
node_beats -->|"defines references"| node_sheets
node_beats -->|"describes shots"| node_keyframes
node_beats -->|"describes shots"| node_clips
node_beats -->|"supplies narration"| node_audio
node_sheets -->|"requests images"| node_provider
node_keyframes -->|"requests images"| node_provider
node_keyframes -->|"provides keyframes"| node_clips
node_clips -->|"requests animation"| node_provider
node_audio -->|"requests narration"| node_provider
node_clips -->|"provides clips"| node_assembly
node_audio -->|"provides audio"| node_assembly
node_assembly -->|"renders with"| node_ffmpeg
node_assembly -->|"writes render"| node_final
node_provider -->|"calls API"| node_muapi

click node_research "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/trend_research.py"
click node_script "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/script_generator.py"
click node_beats "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/script_generator.py"
click node_sheets "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/character_sheets.py"
click node_keyframes "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/keyframes.py"
click node_clips "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/clips.py"
click node_audio "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/audio.py"
click node_assembly "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/assemble.py"
click node_final "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/assemble.py"
click node_provider "https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/provider.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_research,node_script,node_beats,node_creator toneBlue
class node_sheets,node_keyframes,node_clips toneAmber
class node_audio,node_assembly,node_final,node_muapi toneMint
class node_provider toneRose
class node_ffmpeg toneIndigo
```

## Components

### Topic and story

- [Topic research](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/trend_research.py): `scripts/trend_research.py`
- [Beat breakdown](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/script_generator.py): `scripts/script_generator.py`
- [beats.json](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/script_generator.py): `scripts/script_generator.py`

### Visual production

- [Character sheets](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/character_sheets.py): `scripts/character_sheets.py`
- [Keyframes](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/keyframes.py): `scripts/keyframes.py`
- [Motion clips](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/clips.py): `scripts/clips.py`

### Audio and assembly

- [Narration audio](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/audio.py): `scripts/audio.py`
- [Video assembly](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/assemble.py): `scripts/assemble.py`
- [final.mp4](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/assemble.py): `scripts/assemble.py`

### Provider integration

- [MuAPI client](https://github.com/anil-matcha/zack-d-films-ai-video-generator/blob/main/scripts/provider.py): `scripts/provider.py`

### Other components

- **User / agent**
- **MuAPI platform**
- **FFmpeg / ffprobe**

## Connections

- User / agent → Topic research: explores topics (evidence: `README.md`)
- User / agent → Beat breakdown: provides topic (evidence: `README.md`)
- Topic research → Beat breakdown: selects topic (evidence: `README.md`)
- Beat breakdown → beats.json: writes beats (evidence: `scripts/script_generator.py`)
- beats.json → Character sheets: defines references (evidence: `scripts/character_sheets.py`)
- beats.json → Keyframes: describes shots (evidence: `scripts/keyframes.py`)
- beats.json → Motion clips: describes shots (evidence: `scripts/clips.py`)
- beats.json → Narration audio: supplies narration (evidence: `scripts/audio.py`)
- Character sheets → MuAPI client: requests images (evidence: `scripts/character_sheets.py`)
- Keyframes → MuAPI client: requests images (evidence: `scripts/keyframes.py`)
- Keyframes → Motion clips: provides keyframes (evidence: `README.md`)
- Motion clips → MuAPI client: requests animation (evidence: `scripts/clips.py`)
- Narration audio → MuAPI client: requests narration (evidence: `scripts/audio.py`)
- Motion clips → Video assembly: provides clips (evidence: `scripts/assemble.py`)
- Narration audio → Video assembly: provides audio (evidence: `README.md`)
- Video assembly → FFmpeg / ffprobe: renders with (evidence: `scripts/assemble.py`)
- Video assembly → final.mp4: writes render (evidence: `scripts/assemble.py`)
- MuAPI client → MuAPI platform: calls API (evidence: `scripts/provider.py`)