ath-maas/pixelle-video

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