# moh4696/cinematic-skill architecture

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

- Interactive diagram: https://gitdiagram.com/moh4696/cinematic-skill
- Repository: https://github.com/moh4696/cinematic-skill

## Overview

Cinematic Skill is an agent-guided toolkit for making deterministic, code-drawn narrated films. Its main workflow runs from agent-authored story and beat review through timed voice and licensed imagery, into a project scene rendered by the Skia engine, then sound mixing and caption finishing. The graph also preserves map generation, asset preparation, and review renders as distinct capabilities. Relationships for sampled code are tied to excerpts; broader stage links use the README’s workflow. Several scripts are unsampled, so their internal calls are not inferred.

Main entry points: [`skills/cinematic-film/scripts/render.py`](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/render.py) (Film Renderer), [`skills/cinematic-film/SKILL.md`](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/SKILL.md) (Film Skill), [`skills/cinematic-film/scripts/fetch_commons.py`](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/fetch_commons.py) (Commons Images), [`skills/cinematic-film/scripts/burn_captions.py`](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/burn_captions.py) (Caption Finisher)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_authoring["Story and Project"]
  node_skill["Film Skill<br/>[SKILL.md]"]
  node_project["Project Starter<br/>[new_project.py]"]
  node_beats["Beat Planner<br/>[make_beats.py]"]
end

subgraph group_assets["Media Preparation"]
  node_commons["Commons Images<br/>[fetch_commons.py]"]
  node_map["Map Builder<br/>[make_map.py]"]
  node_assetprep["Asset Preparation<br/>[prep_assets.py]"]
end

subgraph group_visuals["Scene and Render"]
  node_scene["Scene Definition<br/>[scene.py]"]
  node_engine["Film Engine<br/>[engine.py]"]
  node_renderer["Film Renderer<br/>[render.py]"]
end

subgraph group_audio["Voice and Sound"]
  node_voice["Scratch Voice<br/>[tts_say.py]"]
  node_takes["Take Splitter<br/>[split_takes.py]"]
  node_narration["Narration Builder<br/>[build_narration.py]"]
  node_sfx["Effects Synth<br/>[build_sfx.py]"]
  node_mixer["Sound Mixer<br/>[mix_soundtrack.py]"]
end

subgraph group_finishing["Captions and Output"]
  node_captionlogic["Caption Styles<br/>[captions.py]"]
  node_captionburn["Caption Finisher<br/>[burn_captions.py]"]
end

node_agent(("Coding Agent"))
node_commons_service(("Wikimedia Commons"))
node_film["Finished Film"]

node_agent -->|"uses"| node_skill
node_skill -->|"starts project"| node_project
node_agent -->|"plans story"| node_beats
node_skill -->|"guides beats"| node_beats
node_agent -->|"authors scene"| node_scene
node_agent -->|"finds images"| node_commons
node_commons -->|"searches and downloads"| node_commons_service
node_agent -->|"builds maps"| node_map
node_commons -->|"prepares photos"| node_assetprep
node_agent -->|"creates scratch voice"| node_voice
node_voice -->|"splits recordings"| node_takes
node_takes -->|"times narration"| node_narration
node_scene -->|"loads scene"| node_renderer
node_renderer -->|"renders frames"| node_engine
node_renderer -->|"writes cue list"| node_sfx
node_narration -->|"mixes voice"| node_mixer
node_sfx -->|"mixes effects"| node_mixer
node_renderer -->|"finishes render"| node_captionburn
node_captionburn -->|"uses styles"| node_captionlogic
node_captionburn -->|"writes captions and SRT"| node_film
node_mixer -->|"provides soundtrack"| node_film
node_renderer -->|"renders video"| node_film

click node_skill "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/SKILL.md"
click node_project "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/new_project.py"
click node_beats "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/make_beats.py"
click node_scene "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/scene.py"
click node_commons "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/fetch_commons.py"
click node_map "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/make_map.py"
click node_assetprep "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/prep_assets.py"
click node_voice "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/tts_say.py"
click node_takes "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/split_takes.py"
click node_narration "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/build_narration.py"
click node_engine "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/engine.py"
click node_renderer "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/render.py"
click node_sfx "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/build_sfx.py"
click node_mixer "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/mix_soundtrack.py"
click node_captionlogic "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/captions.py"
click node_captionburn "https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/burn_captions.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_skill,node_project,node_beats toneBlue
class node_commons,node_map,node_assetprep toneAmber
class node_scene,node_engine,node_renderer toneMint
class node_voice,node_takes,node_narration,node_sfx,node_mixer toneRose
class node_captionlogic,node_captionburn,node_agent,node_commons_service,node_film toneIndigo
```

## Components

### Story and Project

- [Film Skill](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/SKILL.md): `skills/cinematic-film/SKILL.md`
- [Project Starter](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/new_project.py): `skills/cinematic-film/scripts/new_project.py`
- [Beat Planner](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/make_beats.py): `skills/cinematic-film/scripts/make_beats.py`

### Media Preparation

- [Commons Images](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/fetch_commons.py): `skills/cinematic-film/scripts/fetch_commons.py`
- [Map Builder](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/make_map.py): `skills/cinematic-film/scripts/make_map.py`
- [Asset Preparation](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/prep_assets.py): `skills/cinematic-film/scripts/prep_assets.py`

### Scene and Render

- [Scene Definition](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/assets/template/scene.py): `skills/cinematic-film/assets/template/scene.py`
- [Film Engine](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/engine.py): `skills/cinematic-film/scripts/engine.py`
- [Film Renderer](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/render.py): `skills/cinematic-film/scripts/render.py`

### Voice and Sound

- [Scratch Voice](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/tts_say.py): `skills/cinematic-film/scripts/tts_say.py`
- [Take Splitter](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/split_takes.py): `skills/cinematic-film/scripts/split_takes.py`
- [Narration Builder](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/build_narration.py): `skills/cinematic-film/scripts/build_narration.py`
- [Effects Synth](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/build_sfx.py): `skills/cinematic-film/scripts/build_sfx.py`
- [Sound Mixer](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/mix_soundtrack.py): `skills/cinematic-film/scripts/mix_soundtrack.py`

### Captions and Output

- [Caption Styles](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/captions.py): `skills/cinematic-film/scripts/captions.py`
- [Caption Finisher](https://github.com/moh4696/cinematic-skill/blob/main/skills/cinematic-film/scripts/burn_captions.py): `skills/cinematic-film/scripts/burn_captions.py`

### Other components

- **Coding Agent**
- **Wikimedia Commons**
- **Finished Film**

## Connections

- Coding Agent → Film Skill: uses (evidence: `README.md`)
- Film Skill → Project Starter: starts project (evidence: `README.md`)
- Coding Agent → Beat Planner: plans story (evidence: `README.md`)
- Film Skill → Beat Planner: guides beats (evidence: `README.md`)
- Coding Agent → Scene Definition: authors scene (evidence: `README.md`)
- Coding Agent → Commons Images: finds images (evidence: `README.md`)
- Commons Images → Wikimedia Commons: searches and downloads (evidence: `skills/cinematic-film/scripts/fetch_commons.py`)
- Coding Agent → Map Builder: builds maps (evidence: `README.md`)
- Commons Images → Asset Preparation: prepares photos (evidence: `README.md`)
- Coding Agent → Scratch Voice: creates scratch voice (evidence: `README.md`)
- Scratch Voice → Take Splitter: splits recordings (evidence: `README.md`)
- Take Splitter → Narration Builder: times narration (evidence: `README.md`)
- Scene Definition → Film Renderer: loads scene (evidence: `skills/cinematic-film/scripts/render.py`)
- Film Renderer → Film Engine: renders frames (evidence: `skills/cinematic-film/scripts/render.py`)
- Film Renderer → Effects Synth: writes cue list (evidence: `skills/cinematic-film/scripts/build_sfx.py`)
- Narration Builder → Sound Mixer: mixes voice (evidence: `README.md`)
- Effects Synth → Sound Mixer: mixes effects (evidence: `README.md`)
- Film Renderer → Caption Finisher: finishes render (evidence: `README.md`)
- Caption Finisher → Caption Styles: uses styles (evidence: `skills/cinematic-film/scripts/burn_captions.py`)
- Caption Finisher → Finished Film: writes captions and SRT (evidence: `README.md`)
- Sound Mixer → Finished Film: provides soundtrack (evidence: `README.md`)
- Film Renderer → Finished Film: renders video (evidence: `README.md`)
