# konlu/story-studio architecture

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

## Overview

Story Studio is an AI-agent skill for creating historical and biographical short-video assets, from topic and script through voice, timed visuals, and an editable Jianying draft. The README documents both a full workflow and modular handoffs; image generation and semantic review are agent-guided stages, not fully represented by sampled runtime code. The graph preserves those capabilities while keeping optional local rendering separate. Edges follow README workflow statements or visible imports/calls; unsampled subsystems use existing directory paths.

Main entry points: [`SKILL.md`](https://github.com/konlu/story-studio/blob/main/SKILL.md) (Agent Skill), [`scripts/doubao_tts.py`](https://github.com/konlu/story-studio/blob/main/scripts/doubao_tts.py) (Doubao TTS), [`modules/render-history-video/scripts/export_jianying.py`](https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/export_jianying.py) (Jianying Export), [`modules/render-history-video/scripts/align_with_coli.py`](https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/align_with_coli.py) (Shot Alignment)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_creation["Story and Script"]
  node_skill["Agent Skill<br/>[SKILL.md]"]
  node_character["Character Writing<br/>[GUIDE.md]"]
  node_historywriting["Historical Writing<br/>[history_tool.py]"]
  node_corpus["Story Corpus"]
  node_historycorpus["History Corpus"]
end

subgraph group_media["Voice and Visuals"]
  node_voiceconfig["Voice Settings<br/>[voice_settings.py]"]
  node_tts["Doubao TTS<br/>[doubao_tts.py]"]
  node_audio["Voice Audio"]
  node_asr["Coli Transcription"]
  node_visuals["Storyboard and Images"]
  node_references["Style References"]
end

subgraph group_assembly["Timing and Delivery"]
  node_alignment["Shot Alignment<br/>[align_with_coli.py]"]
  node_handoff["Review Checks<br/>[check_handoff.py]"]
  node_motion["Motion Planning<br/>[motion.py]"]
  node_jianying["Jianying Export<br/>[export_jianying.py]"]
  node_renderer["Local Video Render<br/>[render.py]"]
end

subgraph group_runtime["Runtime Support"]
  node_runtimehelper["Runtime Discovery<br/>[studio_runtime.py]"]
end

node_creator(("Creator"))
node_speechservice{{"Doubao Speech"}}

node_creator -->|"requests creation"| node_skill
node_skill -->|"guides writing"| node_character
node_skill -->|"guides writing"| node_historywriting
node_character -->|"uses examples"| node_corpus
node_historywriting -->|"searches corpus"| node_historycorpus
node_skill -->|"configures voice"| node_voiceconfig
node_voiceconfig -->|"provides profile"| node_tts
node_tts -->|"synthesizes with"| node_speechservice
node_tts -->|"produces audio"| node_audio
node_creator -.->|"supplies recording"| node_audio
node_audio -->|"transcribes"| node_asr
node_skill -->|"plans shots"| node_visuals
node_visuals -->|"anchors style"| node_references
node_audio -->|"times cuts"| node_alignment
node_asr -.->|"provides timestamps"| node_alignment
node_alignment -.->|"supports review"| node_handoff
node_handoff -->|"checks delivery"| node_jianying
node_jianying -->|"uses motion logic"| node_motion
node_jianying -->|"uses render helpers"| node_renderer
node_skill -.->|"offers local render"| node_renderer
node_tts -->|"discovers tools"| node_runtimehelper

click node_skill "https://github.com/konlu/story-studio/blob/main/SKILL.md"
click node_character "https://github.com/konlu/story-studio/blob/main/modules/characterstory-writing/GUIDE.md"
click node_historywriting "https://github.com/konlu/story-studio/blob/main/modules/history-writing/scripts/history_tool.py"
click node_corpus "https://github.com/konlu/story-studio/tree/main/modules/characterstory-writing/corpus"
click node_historycorpus "https://github.com/konlu/story-studio/tree/main/modules/history-writing/corpus"
click node_voiceconfig "https://github.com/konlu/story-studio/blob/main/scripts/voice_settings.py"
click node_tts "https://github.com/konlu/story-studio/blob/main/scripts/doubao_tts.py"
click node_asr "https://github.com/konlu/story-studio/blob/main/modules/history-image/scripts/transcribe_with_coli.py"
click node_visuals "https://github.com/konlu/story-studio/tree/main/modules/history-image"
click node_references "https://github.com/konlu/story-studio/tree/main/modules/history-image/references"
click node_alignment "https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/align_with_coli.py"
click node_handoff "https://github.com/konlu/story-studio/blob/main/scripts/check_handoff.py"
click node_motion "https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/motion.py"
click node_jianying "https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/export_jianying.py"
click node_renderer "https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/render.py"
click node_runtimehelper "https://github.com/konlu/story-studio/blob/main/scripts/studio_runtime.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_character,node_historywriting,node_corpus,node_historycorpus toneBlue
class node_voiceconfig,node_tts,node_audio,node_asr,node_visuals,node_references toneAmber
class node_alignment,node_handoff,node_motion,node_jianying,node_renderer toneMint
class node_runtimehelper toneRose
class node_creator,node_speechservice toneIndigo
```

## Components

### Story and Script

- [Agent Skill](https://github.com/konlu/story-studio/blob/main/SKILL.md): `SKILL.md`
- [Character Writing](https://github.com/konlu/story-studio/blob/main/modules/characterstory-writing/GUIDE.md): `modules/characterstory-writing/GUIDE.md`
- [Historical Writing](https://github.com/konlu/story-studio/blob/main/modules/history-writing/scripts/history_tool.py): `modules/history-writing/scripts/history_tool.py`
- [Story Corpus](https://github.com/konlu/story-studio/tree/main/modules/characterstory-writing/corpus): `modules/characterstory-writing/corpus`
- [History Corpus](https://github.com/konlu/story-studio/tree/main/modules/history-writing/corpus): `modules/history-writing/corpus`

### Voice and Visuals

- [Voice Settings](https://github.com/konlu/story-studio/blob/main/scripts/voice_settings.py): `scripts/voice_settings.py`
- [Doubao TTS](https://github.com/konlu/story-studio/blob/main/scripts/doubao_tts.py): `scripts/doubao_tts.py`
- **Voice Audio**
- [Coli Transcription](https://github.com/konlu/story-studio/blob/main/modules/history-image/scripts/transcribe_with_coli.py): `modules/history-image/scripts/transcribe_with_coli.py`
- [Storyboard and Images](https://github.com/konlu/story-studio/tree/main/modules/history-image): `modules/history-image`
- [Style References](https://github.com/konlu/story-studio/tree/main/modules/history-image/references): `modules/history-image/references`

### Timing and Delivery

- [Shot Alignment](https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/align_with_coli.py): `modules/render-history-video/scripts/align_with_coli.py`
- [Review Checks](https://github.com/konlu/story-studio/blob/main/scripts/check_handoff.py): `scripts/check_handoff.py`
- [Motion Planning](https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/motion.py): `modules/render-history-video/scripts/motion.py`
- [Jianying Export](https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/export_jianying.py): `modules/render-history-video/scripts/export_jianying.py`
- [Local Video Render](https://github.com/konlu/story-studio/blob/main/modules/render-history-video/scripts/render.py): `modules/render-history-video/scripts/render.py`

### Runtime Support

- [Runtime Discovery](https://github.com/konlu/story-studio/blob/main/scripts/studio_runtime.py): `scripts/studio_runtime.py`

### Other components

- **Creator**
- **Doubao Speech**

## Connections

- Creator → Agent Skill: requests creation (evidence: `README.md`)
- Agent Skill → Character Writing: guides writing (evidence: `README.md`)
- Agent Skill → Historical Writing: guides writing (evidence: `README.md`)
- Character Writing → Story Corpus: uses examples (evidence: `README.md`)
- Historical Writing → History Corpus: searches corpus (evidence: `README.md`)
- Agent Skill → Voice Settings: configures voice (evidence: `README.md`)
- Voice Settings → Doubao TTS: provides profile (evidence: `scripts/doubao_tts.py`)
- Doubao TTS → Doubao Speech: synthesizes with (evidence: `README.md`)
- Doubao TTS → Voice Audio: produces audio (evidence: `README.md`)
- Creator → Voice Audio: supplies recording (evidence: `README.md`)
- Voice Audio → Coli Transcription: transcribes (evidence: `modules/history-image/scripts/transcribe_with_coli.py`)
- Agent Skill → Storyboard and Images: plans shots (evidence: `README.md`)
- Storyboard and Images → Style References: anchors style (evidence: `README.md`)
- Voice Audio → Shot Alignment: times cuts (evidence: `README.md`)
- Coli Transcription → Shot Alignment: provides timestamps
- Shot Alignment → Review Checks: supports review
- Review Checks → Jianying Export: checks delivery (evidence: `scripts/check_handoff.py`)
- Jianying Export → Motion Planning: uses motion logic (evidence: `modules/render-history-video/scripts/export_jianying.py`)
- Jianying Export → Local Video Render: uses render helpers (evidence: `modules/render-history-video/scripts/export_jianying.py`)
- Agent Skill → Local Video Render: offers local render (evidence: `README.md`)
- Doubao TTS → Runtime Discovery: discovers tools (evidence: `scripts/doubao_tts.py`)