# ath-maas/pixelle-video architecture

> Architecture diagram of the GitHub repository ath-maas/pixelle-video, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-14). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ath-maas/pixelle-video
- Repository: https://github.com/ath-maas/pixelle-video

## Overview

#### Purpose and Entry Points
Pixelle-Video is a Python AI short-video generation engine. It turns a topic or supplied script into narrated, templated video through LLM scripting, media generation, TTS, frame rendering, and final composition. Primary user entry point is the Streamlit UI at `web/app.py`; shell launchers are `start_web.sh` and `start_web.bat`. A programmatic HTTP surface is exposed by `api/app.py`.

#### Interface Layers
The Streamlit application owns interactive configuration, workflow selection, previews, session state, and history. Its page-level flows dispatch into web-specific pipeline adapters:
- `web/pages/1_🎬_Home.py`
- `web/pipelines/standard.py`
- `web/pipelines/api_workflows.py`

The FastAPI layer provides equivalent atomic/domain APIs for content, images, video, TTS, frames, files, resources, and task management:
- `api/app.py`
- `api/routers/content.py`
- `api/routers/tasks.py`

#### Core Pipeline Orchestration
The reusable domain layer centers on pipeline variants: standard topic/script generation, linear/custom execution, and asset-based creation. These pipelines coordinate stages rather than embedding provider-specific behavior:
- `pixelle_video/pipelines/base.py`
- `pixelle_video/pipelines/standard.py`
- `pixelle_video/pipelines/asset_based.py`

Extended UI workflows add image-to-video, digital-human narration, and action transfer:
- `web/pipelines/i2v.py`
- `web/pipelines/digital_human.py`
- `web/pipelines/action_transfer.py`

#### Content and Storyboard Model
LLM prompts generate titles, narration, image/video prompts, and style conversions. Structured media, progress, and storyboard models form the boundary between creative planning and asset/rendering execution:
- `pixelle_video/prompts/topic_narration.py`
- `pixelle_video/prompts/image_generation.py`
- `pixelle_video/models/storyboard.py`

LLM access is centralized so configured providers and presets can be substituted without changing pipeline logic:
- `pixelle_video/services/llm_service.py`
- `pixelle_video/llm_presets.py`

#### Media Generation and External Providers
Media services abstract image, video, TTS, and visual analysis. Provider adapters support direct APIs—including DashScope, OpenAI/GPT Image, Seedream, Seedance, and Kling—while ComfyUI-oriented services support self-hosted or RunningHub workflow execution:
- `pixelle_video/services/api_services/image_client.py`
- `pixelle_video/services/api_services/video_client.py`
- `pixelle_video/services/comfy_base_service.py`

Workflow JSON is a runtime integration boundary: selected self-hosted or RunningHub graphs determine the actual generation backend:
- `workflows/selfhost/image_flux.json`
- `workflows/runninghub/video_wan2.2.json`

#### Rendering, Composition, and Assets
Generated or user-provided assets are analyzed/managed, then processed into template frames. HTML templates separate visual presentation from pipeline logic; media services handle video construction and BGM integration:
- `pixelle_video/services/frame_processor.py`
- `pixelle_video/services/video.py`
- `templates/1080x1920/video_default.html`

Templates are resolution-specific, while bundled music is held separately:
- `templates/1920x1080/image_film.html`
- `bgm/default.mp3`

#### Configuration, State, and Runtime
A shared typed configuration system loads and manages provider credentials, model settings, workflow choices, and runtime options across UI, API, and core services:
- `pixelle_video/config/schema.py`
- `pixelle_video/config/loader.py`
- `pixelle_video/config/manager.py`

Long-running API work is represented through a task manager and task models; history/persistence services support retained outputs and UI history:
- `api/tasks/manager.py`
- `api/tasks/models.py`
- `pixelle_video/services/persistence.py`

The material runtime is Python, Streamlit, FastAPI, and FFmpeg. Deployment supports Docker Compose and a packaged Windows distribution:
- `Dockerfile`
- `docker-compose.yml`
- `packaging/windows/build.py`

Main entry points: [`pixelle_video/pipelines/standard.py`](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/standard.py) (Standard pipeline), [`pixelle_video/services/comfy_base_service.py`](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/comfy_base_service.py) (ComfyUI service), [`pixelle_video/services/frame_processor.py`](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/frame_processor.py) (Frame processor), [`pixelle_video/config/manager.py`](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/config/manager.py) (Configuration manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interfaces["Interfaces"]
  node_streamlit["Streamlit UI<br/>interactive app<br/>[app.py]"]
  node_web_home["Home workflow<br/>UI page<br/>[1_🎬_Home.py]"]
  node_web_adapters["Web pipeline adapters<br/>UI adapters<br/>[standard.py]"]
  node_fastapi["FastAPI API<br/>HTTP API<br/>[app.py]"]
  node_api_content["Content routes<br/>API router<br/>[content.py]"]
  node_api_tasks["Task routes<br/>API router<br/>[tasks.py]"]
end

subgraph group_orchestration["Pipeline orchestration"]
  node_base_pipeline["Pipeline base<br/>pipeline contract<br/>[base.py]"]
  node_standard_pipeline["Standard pipeline<br/>topic/script pipeline<br/>[standard.py]"]
  node_asset_pipeline["Asset-based pipeline<br/>asset pipeline<br/>[asset_based.py]"]
  node_extended_workflows["Extended UI workflows<br/>specialized pipelines<br/>[i2v.py]"]
end

subgraph group_creative["Creative planning"]
  node_storyboard["Storyboard models<br/>domain models<br/>[storyboard.py]"]
  node_prompts["Prompt generators<br/>prompt templates<br/>[topic_narration.py]"]
  node_llm["LLM service<br/>provider gateway<br/>[llm_service.py]"]
end

subgraph group_media["Media and rendering"]
  node_image_video_clients["Image and video clients<br/>provider adapters<br/>[image_client.py]"]
  node_comfy["ComfyUI service<br/>workflow backend"]
  node_workflow_json["Generation workflows<br/>workflow JSON<br/>[image_flux.json]"]
  node_frame_processor["Frame processor<br/>renderer<br/>[frame_processor.py]"]
  node_templates["HTML templates<br/>visual templates<br/>[video_default.html]"]
  node_video_composer["Video composer<br/>FFmpeg media service<br/>[video.py]"]
end

subgraph group_runtime["Runtime state"]
  node_config["Configuration manager<br/>typed configuration<br/>[manager.py]"]
  node_task_manager["Task manager<br/>async task state<br/>[manager.py]"]
  node_persistence[("Persistence service<br/>history storage<br/>[persistence.py]")]
end

node_streamlit -->|"hosts"| node_web_home
node_web_home -->|"dispatches"| node_web_adapters
node_web_adapters -->|"runs"| node_standard_pipeline
node_web_adapters -->|"runs"| node_extended_workflows
node_fastapi -->|"mounts"| node_api_content
node_fastapi -->|"mounts"| node_api_tasks
node_api_content -->|"invokes"| node_standard_pipeline
node_api_tasks -->|"manages"| node_task_manager
node_standard_pipeline -.->|"implements"| node_base_pipeline
node_asset_pipeline -.->|"implements"| node_base_pipeline
node_standard_pipeline -->|"plans with"| node_prompts
node_prompts -->|"uses"| node_llm
node_standard_pipeline -->|"produces"| node_storyboard
node_storyboard -->|"drives generation"| node_image_video_clients
node_storyboard -->|"drives workflows"| node_comfy
node_comfy -->|"executes"| node_workflow_json
node_image_video_clients -->|"supplies assets"| node_frame_processor
node_comfy -->|"supplies assets"| node_frame_processor
node_frame_processor -->|"renders with"| node_templates
node_frame_processor -->|"supplies frames"| node_video_composer
node_video_composer -->|"stores outputs"| node_persistence
node_streamlit -->|"reads history"| node_persistence
node_config -.->|"configures"| node_llm
node_config -.->|"configures"| node_image_video_clients
node_config -.->|"selects workflows"| node_comfy

click node_streamlit "https://github.com/ath-maas/pixelle-video/blob/main/web/app.py"
click node_web_home "https://github.com/ath-maas/pixelle-video/blob/main/web/pages/1_%F0%9F%8E%AC_Home.py"
click node_web_adapters "https://github.com/ath-maas/pixelle-video/blob/main/web/pipelines/standard.py"
click node_fastapi "https://github.com/ath-maas/pixelle-video/blob/main/api/app.py"
click node_api_content "https://github.com/ath-maas/pixelle-video/blob/main/api/routers/content.py"
click node_api_tasks "https://github.com/ath-maas/pixelle-video/blob/main/api/routers/tasks.py"
click node_base_pipeline "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/base.py"
click node_standard_pipeline "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/standard.py"
click node_asset_pipeline "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/asset_based.py"
click node_extended_workflows "https://github.com/ath-maas/pixelle-video/blob/main/web/pipelines/i2v.py"
click node_storyboard "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/models/storyboard.py"
click node_prompts "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/prompts/topic_narration.py"
click node_llm "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/llm_service.py"
click node_image_video_clients "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/api_services/image_client.py"
click node_comfy "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/comfy_base_service.py"
click node_workflow_json "https://github.com/ath-maas/pixelle-video/blob/main/workflows/selfhost/image_flux.json"
click node_frame_processor "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/frame_processor.py"
click node_templates "https://github.com/ath-maas/pixelle-video/blob/main/templates/1080x1920/video_default.html"
click node_video_composer "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/video.py"
click node_config "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/config/manager.py"
click node_task_manager "https://github.com/ath-maas/pixelle-video/blob/main/api/tasks/manager.py"
click node_persistence "https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/persistence.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_streamlit,node_web_home,node_web_adapters,node_fastapi,node_api_content,node_api_tasks toneBlue
class node_base_pipeline,node_standard_pipeline,node_asset_pipeline,node_extended_workflows toneAmber
class node_storyboard,node_prompts,node_llm toneMint
class node_image_video_clients,node_comfy,node_workflow_json,node_frame_processor,node_templates,node_video_composer toneRose
class node_config,node_task_manager,node_persistence toneIndigo
```

## Components

### Interfaces

- [Streamlit UI](https://github.com/ath-maas/pixelle-video/blob/main/web/app.py): interactive app · Configuration, previews, session state, and history. · `web/app.py`
- [Home workflow](https://github.com/ath-maas/pixelle-video/blob/main/web/pages/1_%F0%9F%8E%AC_Home.py): UI page · `web/pages/1_🎬_Home.py`
- [Web pipeline adapters](https://github.com/ath-maas/pixelle-video/blob/main/web/pipelines/standard.py): UI adapters · `web/pipelines/standard.py`
- [FastAPI API](https://github.com/ath-maas/pixelle-video/blob/main/api/app.py): HTTP API · Atomic content and media operations. · `api/app.py`
- [Content routes](https://github.com/ath-maas/pixelle-video/blob/main/api/routers/content.py): API router · `api/routers/content.py`
- [Task routes](https://github.com/ath-maas/pixelle-video/blob/main/api/routers/tasks.py): API router · `api/routers/tasks.py`

### Pipeline orchestration

- [Pipeline base](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/base.py): pipeline contract · `pixelle_video/pipelines/base.py`
- [Standard pipeline](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/standard.py): topic/script pipeline · `pixelle_video/pipelines/standard.py`
- [Asset-based pipeline](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/pipelines/asset_based.py): asset pipeline · `pixelle_video/pipelines/asset_based.py`
- [Extended UI workflows](https://github.com/ath-maas/pixelle-video/blob/main/web/pipelines/i2v.py): specialized pipelines · Image-to-video, digital human, and action transfer. · `web/pipelines/i2v.py`

### Creative planning

- [Storyboard models](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/models/storyboard.py): domain models · Structured boundary from creative plan to media execution. · `pixelle_video/models/storyboard.py`
- [Prompt generators](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/prompts/topic_narration.py): prompt templates · Creates narration and media prompts. · `pixelle_video/prompts/topic_narration.py`
- [LLM service](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/llm_service.py): provider gateway · Configurable LLM providers and presets. · `pixelle_video/services/llm_service.py`

### Media and rendering

- [Image and video clients](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/api_services/image_client.py): provider adapters · Direct generation providers including DashScope, OpenAI, Seedream, Seedance, and Kling. · `pixelle_video/services/api_services/image_client.py`
- [ComfyUI service](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/comfy_base_service.py): workflow backend · Executes self-hosted or RunningHub workflows. · `pixelle_video/services/comfy_base_service.py`
- [Generation workflows](https://github.com/ath-maas/pixelle-video/blob/main/workflows/selfhost/image_flux.json): workflow JSON · Selected graphs determine ComfyUI generation behavior. · `workflows/selfhost/image_flux.json`
- [Frame processor](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/frame_processor.py): renderer · Builds template frames from assets. · `pixelle_video/services/frame_processor.py`
- [HTML templates](https://github.com/ath-maas/pixelle-video/blob/main/templates/1080x1920/video_default.html): visual templates · Resolution-specific presentation layouts. · `templates/1080x1920/video_default.html`
- [Video composer](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/video.py): FFmpeg media service · Constructs final video and integrates BGM. · `pixelle_video/services/video.py`

### Runtime state

- [Configuration manager](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/config/manager.py): typed configuration · Shares credentials, models, workflows, and runtime options. · `pixelle_video/config/manager.py`
- [Task manager](https://github.com/ath-maas/pixelle-video/blob/main/api/tasks/manager.py): async task state · Tracks long-running API work. · `api/tasks/manager.py`
- [Persistence service](https://github.com/ath-maas/pixelle-video/blob/main/pixelle_video/services/persistence.py): history storage · Retains outputs for UI history. · `pixelle_video/services/persistence.py`

## Connections

- Streamlit UI → Home workflow: hosts
- Home workflow → Web pipeline adapters: dispatches
- Web pipeline adapters → Standard pipeline: runs
- Web pipeline adapters → Extended UI workflows: runs
- FastAPI API → Content routes: mounts
- FastAPI API → Task routes: mounts
- Content routes → Standard pipeline: invokes
- Task routes → Task manager: manages
- Standard pipeline → Pipeline base: implements
- Asset-based pipeline → Pipeline base: implements
- Standard pipeline → Prompt generators: plans with
- Prompt generators → LLM service: uses
- Standard pipeline → Storyboard models: produces
- Storyboard models → Image and video clients: drives generation
- Storyboard models → ComfyUI service: drives workflows
- ComfyUI service → Generation workflows: executes
- Image and video clients → Frame processor: supplies assets
- ComfyUI service → Frame processor: supplies assets
- Frame processor → HTML templates: renders with
- Frame processor → Video composer: supplies frames
- Video composer → Persistence service: stores outputs
- Streamlit UI → Persistence service: reads history
- Configuration manager → LLM service: configures
- Configuration manager → Image and video clients: configures
- Configuration manager → ComfyUI service: selects workflows