# yenloned/aistoryvideogenerator architecture

> Architecture diagram of the GitHub repository yenloned/aistoryvideogenerator, 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/yenloned/aistoryvideogenerator
- Repository: https://github.com/yenloned/aistoryvideogenerator

## Overview

AI Story Video Generator turns a keyword or supplied story into a narrated, illustrated video. The principal workflow is initiated through `main.py`: it obtains structured script data, generates scene images and paragraph audio, then composes them with synchronized subtitles into an MP4. Interactive topic selection reads `data/topics.json`, and batch generation repeatedly invokes the same pipeline. README capabilities include local Ollama script generation, Stable Diffusion imagery, Coqui/Piper narration, subtitle generation and FFmpeg composition. Source excerpts are partial, so links for unsampled implementation details are limited to documented behavior.

Main entry points: [`main.py`](https://github.com/yenloned/aistoryvideogenerator/blob/main/main.py) (Video pipeline), [`scripts/generate_video.py`](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_video.py) (Video composition), [`scripts/generate_audio.py`](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_audio.py) (Audio generation), [`scripts/generate_images.py`](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_images.py) (Image generation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and orchestration"]
  node_batch["Batch runner<br/>[batch_generate.py]"]
  node_pipeline["Video pipeline<br/>[main.py]"]
  node_topics["Topic catalog<br/>[topics.json]"]
end

subgraph group_story["Story preparation"]
  node_scriptgen["Script generation<br/>[generate_script.py]"]
  node_storyconvert["Story conversion<br/>[main.py]"]
  node_scriptfile["Script JSON"]
end

subgraph group_assets["Scene assets"]
  node_images["Image generation<br/>[generate_images.py]"]
  node_audio["Audio generation<br/>[generate_audio.py]"]
  node_imagefiles["Scene images"]
  node_audiofiles["Narration audio"]
end

subgraph group_composition["Video composition"]
  node_video["Video composition<br/>[generate_video.py]"]
  node_mp4["Subtitled MP4"]
end

node_user(("User"))
node_ollama["Ollama Qwen"]
node_sd["Stable Diffusion"]
node_coqui["Coqui TTS"]
node_piper["Piper TTS"]
node_ffmpeg["FFmpeg"]

node_user -->|"provides input"| node_pipeline
node_user -->|"provides keywords"| node_batch
node_batch -->|"runs per keyword"| node_pipeline
node_pipeline -->|"reads topics"| node_topics
node_pipeline -->|"converts supplied story"| node_storyconvert
node_pipeline -->|"requests script"| node_scriptgen
node_scriptgen -->|"requests generation"| node_ollama
node_pipeline -->|"writes script"| node_scriptfile
node_pipeline -->|"requests images"| node_images
node_images -->|"generates scenes"| node_sd
node_images -->|"writes images"| node_imagefiles
node_pipeline -->|"requests narration"| node_audio
node_audio -->|"synthesizes speech"| node_coqui
node_audio -.->|"synthesizes speech"| node_piper
node_audio -->|"writes audio"| node_audiofiles
node_pipeline -->|"requests composition"| node_video
node_video -->|"assembles media"| node_ffmpeg
node_video -->|"reads script"| node_scriptfile
node_video -->|"reads images"| node_imagefiles
node_video -->|"reads audio"| node_audiofiles
node_video -->|"writes subtitled video"| node_mp4

click node_batch "https://github.com/yenloned/aistoryvideogenerator/blob/main/batch_generate.py"
click node_pipeline "https://github.com/yenloned/aistoryvideogenerator/blob/main/main.py"
click node_topics "https://github.com/yenloned/aistoryvideogenerator/blob/main/data/topics.json"
click node_scriptgen "https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_script.py"
click node_storyconvert "https://github.com/yenloned/aistoryvideogenerator/blob/main/main.py"
click node_images "https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_images.py"
click node_audio "https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_audio.py"
click node_video "https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_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_batch,node_pipeline,node_topics,node_user,node_coqui toneBlue
class node_scriptgen,node_storyconvert,node_scriptfile toneAmber
class node_images,node_audio,node_imagefiles,node_audiofiles toneMint
class node_video,node_mp4 toneRose
class node_ollama,node_sd,node_piper,node_ffmpeg toneIndigo
```

## Components

### Entry and orchestration

- [Batch runner](https://github.com/yenloned/aistoryvideogenerator/blob/main/batch_generate.py): `batch_generate.py`
- [Video pipeline](https://github.com/yenloned/aistoryvideogenerator/blob/main/main.py): `main.py`
- [Topic catalog](https://github.com/yenloned/aistoryvideogenerator/blob/main/data/topics.json): `data/topics.json`

### Story preparation

- [Script generation](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_script.py): `scripts/generate_script.py`
- [Story conversion](https://github.com/yenloned/aistoryvideogenerator/blob/main/main.py): `main.py`
- **Script JSON**

### Scene assets

- [Image generation](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_images.py): `scripts/generate_images.py`
- [Audio generation](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_audio.py): `scripts/generate_audio.py`
- **Scene images**
- **Narration audio**

### Video composition

- [Video composition](https://github.com/yenloned/aistoryvideogenerator/blob/main/scripts/generate_video.py): `scripts/generate_video.py`
- **Subtitled MP4**

### Other components

- **User**
- **Ollama Qwen**
- **Stable Diffusion**
- **Coqui TTS**
- **Piper TTS**
- **FFmpeg**

## Connections

- User → Video pipeline: provides input
- User → Batch runner: provides keywords
- Batch runner → Video pipeline: runs per keyword
- Video pipeline → Topic catalog: reads topics
- Video pipeline → Story conversion: converts supplied story
- Video pipeline → Script generation: requests script
- Script generation → Ollama Qwen: requests generation
- Video pipeline → Script JSON: writes script
- Video pipeline → Image generation: requests images
- Image generation → Stable Diffusion: generates scenes
- Image generation → Scene images: writes images
- Video pipeline → Audio generation: requests narration
- Audio generation → Coqui TTS: synthesizes speech
- Audio generation → Piper TTS: synthesizes speech
- Audio generation → Narration audio: writes audio
- Video pipeline → Video composition: requests composition
- Video composition → FFmpeg: assembles media
- Video composition → Script JSON: reads script
- Video composition → Scene images: reads images
- Video composition → Narration audio: reads audio
- Video composition → Subtitled MP4: writes subtitled video