# sarpstar/cinecode architecture

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

- Interactive diagram: https://gitdiagram.com/sarpstar/cinecode
- Repository: https://github.com/sarpstar/cinecode

## Overview

cinecode is a local, agent-guided filmmaking toolkit: the user develops an idea with a coding agent, chooses a direction, and iterates through previews before receiving a mastered MP4. The map preserves its documented branches for research, typography, music videos, narration, and editing user footage. Source excerpts confirm several module calls; other product-stage links are based on the README’s workflow and are marked dashed where implementation wiring was not shown.

Main entry points: [`scripts/make.py`](https://github.com/sarpstar/cinecode/blob/main/scripts/make.py) (Render and master), [`starter/scene.html`](https://github.com/sarpstar/cinecode/blob/main/starter/scene.html) (Scene authoring), [`scripts/brief.py`](https://github.com/sarpstar/cinecode/blob/main/scripts/brief.py) (Brief and prompts), [`scripts/deal.py`](https://github.com/sarpstar/cinecode/blob/main/scripts/deal.py) (Idea deals)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creative["Creative development"]
  node_brief["Brief and prompts<br/>[brief.py]"]
  node_ideas["Idea deals<br/>[deal.py]"]
  node_film_plan["Film plan<br/>[STATE.md]"]
end

subgraph group_research["Research and direction"]
  node_seed["Outside seeds<br/>[dice.py]"]
  node_assets["Asset search<br/>[asset_search.py]"]
  node_direction["Look direction<br/>[direction.py]"]
  node_styles["Style library<br/>[styles.py]"]
  node_type_refs["Type references<br/>[type_refs.py]"]
  node_type_deal["Type pairings<br/>[type_deal.py]"]
  node_fonts["Font search<br/>[fonts.py]"]
end

subgraph group_production["Film production"]
  node_film_scene["Scene authoring<br/>[scene.html]"]
  node_camera["Camera moves<br/>[camera.mjs]"]
  node_capture["Frame capture<br/>[capture.mjs]"]
  node_render["Render and master<br/>[make.py]"]
  node_words["Word checks<br/>[words_check.py]"]
  node_qc["Quality checks<br/>[qc.py]"]
end

subgraph group_sound["Sound and finishing"]
  node_music_grid["Beat grid<br/>[beat_grid.py]"]
  node_narration["Voice generation<br/>[tts.py]"]
  node_sound_assets["Sound search<br/>[sounds.py]"]
  node_audio_mix["Audio mix<br/>[mix.py]"]
  node_audio_master["Audio mastering<br/>[master_audio.py]"]
end

subgraph group_extras["Specialized formats"]
  node_footage["Footage editing<br/>[footage_cut.py]"]
  node_lyrics["Lyric alignment<br/>[lyrics_align.py]"]
  node_reference_video["Reference analysis<br/>[ref_video.py]"]
end

node_user(("User"))
node_agent(("Coding agent"))

node_user -.->|"shares idea"| node_agent
node_agent -.->|"elicits brief"| node_brief
node_brief -.->|"frames options"| node_ideas
node_ideas -->|"draws seeds"| node_seed
node_agent -.->|"presents plan"| node_film_plan
node_agent -.->|"proposes looks"| node_direction
node_direction -->|"uses recipes"| node_styles
node_agent -.->|"finds references"| node_assets
node_agent -.->|"finds type references"| node_type_refs
node_agent -.->|"selects pairings"| node_type_deal
node_type_deal -->|"checks fonts"| node_fonts
node_agent -.->|"authors scenes"| node_film_scene
node_film_scene -.->|"uses camera"| node_camera
node_agent -.->|"renders preview"| node_capture
node_capture -.->|"captures frames"| node_film_scene
node_agent -.->|"requests render"| node_render
node_render -->|"imports"| node_fonts
node_render -->|"imports"| node_music_grid
node_render -->|"runs check"| node_words
node_agent -.->|"creates voice"| node_narration
node_agent -.->|"finds sound"| node_sound_assets
node_agent -.->|"mixes audio"| node_audio_mix
node_audio_mix -.->|"masters audio"| node_audio_master
node_render -.->|"checks draft"| node_qc
node_agent -.->|"cuts footage"| node_footage
node_agent -.->|"aligns lyrics"| node_lyrics
node_agent -.->|"analyzes reference"| node_reference_video
node_qc -.->|"shows draft"| node_user
node_render -.->|"delivers MP4"| node_user

click node_brief "https://github.com/sarpstar/cinecode/blob/main/scripts/brief.py"
click node_ideas "https://github.com/sarpstar/cinecode/blob/main/scripts/deal.py"
click node_seed "https://github.com/sarpstar/cinecode/blob/main/scripts/dice.py"
click node_assets "https://github.com/sarpstar/cinecode/blob/main/scripts/asset_search.py"
click node_direction "https://github.com/sarpstar/cinecode/blob/main/scripts/direction.py"
click node_styles "https://github.com/sarpstar/cinecode/blob/main/scripts/styles.py"
click node_type_refs "https://github.com/sarpstar/cinecode/blob/main/scripts/type_refs.py"
click node_type_deal "https://github.com/sarpstar/cinecode/blob/main/scripts/type_deal.py"
click node_fonts "https://github.com/sarpstar/cinecode/blob/main/scripts/fonts.py"
click node_film_plan "https://github.com/sarpstar/cinecode/blob/main/templates/STATE.md"
click node_film_scene "https://github.com/sarpstar/cinecode/blob/main/starter/scene.html"
click node_camera "https://github.com/sarpstar/cinecode/blob/main/starter/camera.mjs"
click node_capture "https://github.com/sarpstar/cinecode/blob/main/scripts/capture.mjs"
click node_render "https://github.com/sarpstar/cinecode/blob/main/scripts/make.py"
click node_words "https://github.com/sarpstar/cinecode/blob/main/scripts/words_check.py"
click node_music_grid "https://github.com/sarpstar/cinecode/blob/main/scripts/beat_grid.py"
click node_narration "https://github.com/sarpstar/cinecode/blob/main/scripts/tts.py"
click node_sound_assets "https://github.com/sarpstar/cinecode/blob/main/scripts/sounds.py"
click node_audio_mix "https://github.com/sarpstar/cinecode/blob/main/scripts/mix.py"
click node_audio_master "https://github.com/sarpstar/cinecode/blob/main/scripts/master_audio.py"
click node_qc "https://github.com/sarpstar/cinecode/blob/main/scripts/qc.py"
click node_footage "https://github.com/sarpstar/cinecode/blob/main/scripts/footage_cut.py"
click node_lyrics "https://github.com/sarpstar/cinecode/blob/main/scripts/lyrics_align.py"
click node_reference_video "https://github.com/sarpstar/cinecode/blob/main/scripts/ref_video.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_brief,node_ideas,node_film_plan,node_user toneBlue
class node_seed,node_assets,node_direction,node_styles,node_type_refs,node_type_deal,node_fonts toneAmber
class node_film_scene,node_camera,node_capture,node_render,node_words,node_qc toneMint
class node_music_grid,node_narration,node_sound_assets,node_audio_mix,node_audio_master toneRose
class node_footage,node_lyrics,node_reference_video,node_agent toneIndigo
```

## Components

### Creative development

- [Brief and prompts](https://github.com/sarpstar/cinecode/blob/main/scripts/brief.py): `scripts/brief.py`
- [Idea deals](https://github.com/sarpstar/cinecode/blob/main/scripts/deal.py): `scripts/deal.py`
- [Film plan](https://github.com/sarpstar/cinecode/blob/main/templates/STATE.md): `templates/STATE.md`

### Research and direction

- [Outside seeds](https://github.com/sarpstar/cinecode/blob/main/scripts/dice.py): `scripts/dice.py`
- [Asset search](https://github.com/sarpstar/cinecode/blob/main/scripts/asset_search.py): `scripts/asset_search.py`
- [Look direction](https://github.com/sarpstar/cinecode/blob/main/scripts/direction.py): `scripts/direction.py`
- [Style library](https://github.com/sarpstar/cinecode/blob/main/scripts/styles.py): `scripts/styles.py`
- [Type references](https://github.com/sarpstar/cinecode/blob/main/scripts/type_refs.py): `scripts/type_refs.py`
- [Type pairings](https://github.com/sarpstar/cinecode/blob/main/scripts/type_deal.py): `scripts/type_deal.py`
- [Font search](https://github.com/sarpstar/cinecode/blob/main/scripts/fonts.py): `scripts/fonts.py`

### Film production

- [Scene authoring](https://github.com/sarpstar/cinecode/blob/main/starter/scene.html): `starter/scene.html`
- [Camera moves](https://github.com/sarpstar/cinecode/blob/main/starter/camera.mjs): `starter/camera.mjs`
- [Frame capture](https://github.com/sarpstar/cinecode/blob/main/scripts/capture.mjs): `scripts/capture.mjs`
- [Render and master](https://github.com/sarpstar/cinecode/blob/main/scripts/make.py): `scripts/make.py`
- [Word checks](https://github.com/sarpstar/cinecode/blob/main/scripts/words_check.py): `scripts/words_check.py`
- [Quality checks](https://github.com/sarpstar/cinecode/blob/main/scripts/qc.py): `scripts/qc.py`

### Sound and finishing

- [Beat grid](https://github.com/sarpstar/cinecode/blob/main/scripts/beat_grid.py): `scripts/beat_grid.py`
- [Voice generation](https://github.com/sarpstar/cinecode/blob/main/scripts/tts.py): `scripts/tts.py`
- [Sound search](https://github.com/sarpstar/cinecode/blob/main/scripts/sounds.py): `scripts/sounds.py`
- [Audio mix](https://github.com/sarpstar/cinecode/blob/main/scripts/mix.py): `scripts/mix.py`
- [Audio mastering](https://github.com/sarpstar/cinecode/blob/main/scripts/master_audio.py): `scripts/master_audio.py`

### Specialized formats

- [Footage editing](https://github.com/sarpstar/cinecode/blob/main/scripts/footage_cut.py): `scripts/footage_cut.py`
- [Lyric alignment](https://github.com/sarpstar/cinecode/blob/main/scripts/lyrics_align.py): `scripts/lyrics_align.py`
- [Reference analysis](https://github.com/sarpstar/cinecode/blob/main/scripts/ref_video.py): `scripts/ref_video.py`

### Other components

- **User**
- **Coding agent**

## Connections

- User → Coding agent: shares idea (evidence: `README.md`)
- Coding agent → Brief and prompts: elicits brief (evidence: `README.md`)
- Brief and prompts → Idea deals: frames options (evidence: `scripts/brief.py`)
- Idea deals → Outside seeds: draws seeds (evidence: `scripts/deal.py`)
- Coding agent → Film plan: presents plan (evidence: `README.md`)
- Coding agent → Look direction: proposes looks (evidence: `README.md`)
- Look direction → Style library: uses recipes (evidence: `scripts/direction.py`)
- Coding agent → Asset search: finds references (evidence: `README.md`)
- Coding agent → Type references: finds type references (evidence: `README.md`)
- Coding agent → Type pairings: selects pairings (evidence: `README.md`)
- Type pairings → Font search: checks fonts (evidence: `scripts/type_deal.py`)
- Coding agent → Scene authoring: authors scenes (evidence: `README.md`)
- Scene authoring → Camera moves: uses camera
- Coding agent → Frame capture: renders preview (evidence: `README.md`)
- Frame capture → Scene authoring: captures frames (evidence: `README.md`)
- Coding agent → Render and master: requests render (evidence: `README.md`)
- Render and master → Font search: imports (evidence: `scripts/make.py`)
- Render and master → Beat grid: imports (evidence: `scripts/make.py`)
- Render and master → Word checks: runs check (evidence: `scripts/make.py`)
- Coding agent → Voice generation: creates voice (evidence: `README.md`)
- Coding agent → Sound search: finds sound (evidence: `README.md`)
- Coding agent → Audio mix: mixes audio (evidence: `README.md`)
- Audio mix → Audio mastering: masters audio (evidence: `README.md`)
- Render and master → Quality checks: checks draft (evidence: `README.md`)
- Coding agent → Footage editing: cuts footage (evidence: `README.md`)
- Coding agent → Lyric alignment: aligns lyrics (evidence: `README.md`)
- Coding agent → Reference analysis: analyzes reference (evidence: `README.md`)
- Quality checks → User: shows draft (evidence: `README.md`)
- Render and master → User: delivers MP4 (evidence: `README.md`)