# tillo13/ai_storyboard_video_generator architecture

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

- Interactive diagram: https://gitdiagram.com/tillo13/ai_storyboard_video_generator
- Repository: https://github.com/tillo13/ai_storyboard_video_generator

## Overview

Kumori is a script-driven AI storyboard and video generator: users configure story parameters, generate and enrich a chapter-based story, create consistent character and chapter imagery, assemble and post-process videos, then review upload metadata and schedule publication. The README documents the main stages and capabilities; sampled source confirms parts of story generation, image generation, video assembly, and YouTube scheduling. Several stage-to-stage links reflect the documented workflow, while unsampled implementation details are intentionally not inferred.

Main entry points: [`9_create_voiceover.py`](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/9_create_voiceover.py) (Create voiceover), [`0_preview_mosaics_then_upload_to_youtube.py`](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/0_preview_mosaics_then_upload_to_youtube.py) (Review and upload), [`1_dream_up_a_story.py`](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/1_dream_up_a_story.py) (Generate story), [`2_build_out_chapters.py`](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/2_build_out_chapters.py) (Expand chapters)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_story["Story creation"]
  node_config["Story settings"]
  node_storygen["Generate story"]
  node_chapters["Expand chapters"]
  node_prompts["Summaries and prompts"]
  node_storyfiles["Story data"]
end

subgraph group_visuals["Visual generation"]
  node_images["Chapter images"]
  node_character["Character consistency"]
  node_faceid["Face identity tools<br/>[faceid_utils.py]"]
  node_mainchar["Character image generation"]
  node_enhance["Image enhancement"]
end

subgraph group_media["Video production"]
  node_movie["Create movie<br/>[5_create_movie.py]"]
  node_mosaic["Create mosaic<br/>[6_create_mosaic.py]"]
  node_zoompan["Zoom and pan<br/>[7_zoompan_movie.py]"]
  node_subtitles["Add subtitles"]
  node_voiceover["Create voiceover"]
  node_music["Music sourcing<br/>[rfm_music_utils.py]"]
end

subgraph group_publish["Publishing"]
  node_review["Review and upload"]
  node_csvprep["Upload metadata"]
  node_validator["Mosaic validation"]
  node_scheduler["Upload scheduler"]
  node_youtubecheck["Check scheduled posts"]
end

node_user(("User"))
node_ollama["Ollama"]
node_sd["Stable Diffusion"]
node_tts["Google TTS"]
node_ffmpeg["FFmpeg"]
node_youtube["YouTube"]

node_user -->|"sets options"| node_config
node_config -->|"configures"| node_storygen
node_storygen -->|"generates with"| node_ollama
node_storygen -->|"writes story"| node_storyfiles
node_storyfiles -->|"reads story"| node_chapters
node_chapters -->|"expands with"| node_ollama
node_chapters -->|"updates chapters"| node_storyfiles
node_storyfiles -->|"reads chapters"| node_prompts
node_prompts -->|"summarizes with"| node_ollama
node_prompts -->|"writes prompts"| node_storyfiles
node_storyfiles -->|"provides prompts"| node_images
node_images -->|"generates with"| node_sd
node_storyfiles -->|"provides character data"| node_character
node_character -->|"extracts identity"| node_faceid
node_character -->|"requests image"| node_mainchar
node_images -.->|"enhances images"| node_enhance
node_storyfiles -->|"provides chapter images"| node_movie
node_movie -->|"assembles video"| node_ffmpeg
node_movie -->|"video output"| node_mosaic
node_mosaic -->|"video input"| node_zoompan
node_zoompan -->|"video input"| node_subtitles
node_subtitles -->|"video input"| node_voiceover
node_voiceover -->|"synthesizes speech"| node_tts
node_voiceover -.->|"optional music"| node_music
node_voiceover -->|"combines audio"| node_ffmpeg
node_user -->|"reviews queue"| node_review
node_review -->|"validates mosaics"| node_validator
node_review -->|"prepares queue"| node_csvprep
node_review -->|"dispatches upload"| node_scheduler
node_scheduler -->|"uploads and schedules"| node_youtube
node_youtubecheck -->|"checks schedule"| node_youtube

click node_config "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/GLOBAL_VARIABLES.py"
click node_storygen "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/1_dream_up_a_story.py"
click node_chapters "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/2_build_out_chapters.py"
click node_prompts "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/3_summarize_chapters_add_ai_prompts.py"
click node_images "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/4_create_images_from_ai_prompts.py"
click node_character "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/4b_unique_character.py"
click node_faceid "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/faceid_utils.py"
click node_mainchar "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/main_character_generator_utils.py"
click node_enhance "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/enhance_image_via_import.py"
click node_movie "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/5_create_movie.py"
click node_mosaic "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/6_create_mosaic.py"
click node_zoompan "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/7_zoompan_movie.py"
click node_subtitles "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/8_add_ffmpeg_subtitles.py"
click node_voiceover "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/9_create_voiceover.py"
click node_music "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/rfm_music_utils.py"
click node_review "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/0_preview_mosaics_then_upload_to_youtube.py"
click node_csvprep "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/youtube_csv_prep_utils.py"
click node_validator "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/mosaic_validator_utils.py"
click node_scheduler "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/youtube/youtube_scheduler_utils.py"
click node_youtubecheck "https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/youtube/youtube_check_publish.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_config,node_storygen,node_chapters,node_prompts,node_storyfiles,node_user toneBlue
class node_images,node_character,node_faceid,node_mainchar,node_enhance toneAmber
class node_movie,node_mosaic,node_zoompan,node_subtitles,node_voiceover,node_music toneMint
class node_review,node_csvprep,node_validator,node_scheduler,node_youtubecheck toneRose
class node_ollama,node_sd,node_tts,node_ffmpeg,node_youtube toneIndigo
```

## Components

### Story creation

- [Story settings](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/GLOBAL_VARIABLES.py): `GLOBAL_VARIABLES.py`
- [Generate story](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/1_dream_up_a_story.py): `1_dream_up_a_story.py`
- [Expand chapters](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/2_build_out_chapters.py): `2_build_out_chapters.py`
- [Summaries and prompts](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/3_summarize_chapters_add_ai_prompts.py): `3_summarize_chapters_add_ai_prompts.py`
- **Story data**

### Visual generation

- [Chapter images](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/4_create_images_from_ai_prompts.py): `4_create_images_from_ai_prompts.py`
- [Character consistency](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/4b_unique_character.py): `4b_unique_character.py`
- [Face identity tools](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/faceid_utils.py): `utilities/faceid_utils.py`
- [Character image generation](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/main_character_generator_utils.py): `utilities/main_character_generator_utils.py`
- [Image enhancement](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/enhance_image_via_import.py): `utilities/enhance_image_via_import.py`

### Video production

- [Create movie](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/5_create_movie.py): `5_create_movie.py`
- [Create mosaic](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/6_create_mosaic.py): `6_create_mosaic.py`
- [Zoom and pan](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/7_zoompan_movie.py): `7_zoompan_movie.py`
- [Add subtitles](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/8_add_ffmpeg_subtitles.py): `8_add_ffmpeg_subtitles.py`
- [Create voiceover](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/9_create_voiceover.py): `9_create_voiceover.py`
- [Music sourcing](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/rfm_music_utils.py): `utilities/rfm_music_utils.py`

### Publishing

- [Review and upload](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/0_preview_mosaics_then_upload_to_youtube.py): `0_preview_mosaics_then_upload_to_youtube.py`
- [Upload metadata](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/youtube_csv_prep_utils.py): `utilities/youtube_csv_prep_utils.py`
- [Mosaic validation](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/mosaic_validator_utils.py): `utilities/mosaic_validator_utils.py`
- [Upload scheduler](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/youtube/youtube_scheduler_utils.py): `utilities/youtube/youtube_scheduler_utils.py`
- [Check scheduled posts](https://github.com/tillo13/ai_storyboard_video_generator/blob/main/utilities/youtube/youtube_check_publish.py): `utilities/youtube/youtube_check_publish.py`

### Other components

- **User**
- **Ollama**
- **Stable Diffusion**
- **Google TTS**
- **FFmpeg**
- **YouTube**

## Connections

- User → Story settings: sets options
- Story settings → Generate story: configures
- Generate story → Ollama: generates with
- Generate story → Story data: writes story
- Story data → Expand chapters: reads story
- Expand chapters → Ollama: expands with
- Expand chapters → Story data: updates chapters
- Story data → Summaries and prompts: reads chapters
- Summaries and prompts → Ollama: summarizes with
- Summaries and prompts → Story data: writes prompts
- Story data → Chapter images: provides prompts
- Chapter images → Stable Diffusion: generates with
- Story data → Character consistency: provides character data
- Character consistency → Face identity tools: extracts identity
- Character consistency → Character image generation: requests image
- Chapter images → Image enhancement: enhances images
- Story data → Create movie: provides chapter images
- Create movie → FFmpeg: assembles video
- Create movie → Create mosaic: video output
- Create mosaic → Zoom and pan: video input
- Zoom and pan → Add subtitles: video input
- Add subtitles → Create voiceover: video input
- Create voiceover → Google TTS: synthesizes speech
- Create voiceover → Music sourcing: optional music
- Create voiceover → FFmpeg: combines audio
- User → Review and upload: reviews queue
- Review and upload → Mosaic validation: validates mosaics
- Review and upload → Upload metadata: prepares queue
- Review and upload → Upload scheduler: dispatches upload
- Upload scheduler → YouTube: uploads and schedules
- Check scheduled posts → YouTube: checks schedule