# Pixelle-Video Architecture: Core Components Explained

> Explore the Pixelle-Video architecture. Understand its core components including configuration management, specialized services, and orchestrated pipelines in this modular framework.

- Repository: [AIDC-AI/Pixelle-Video](https://github.com/AIDC-AI/Pixelle-Video)
- Tags: architecture
- Published: 2026-04-23

---

**Pixelle-Video is a service-oriented, pipeline-driven framework that transforms text scripts into complete videos through a modular architecture of configuration management, specialized services, and orchestrated pipelines.**

The AIDC-AI/Pixelle-Video repository implements a clean separation between configuration, service primitives, pipeline orchestration, and per-frame media handling. This design enables easy integration of new LLM providers, TTS backends, and ComfyUI workflows without modifying core logic.

## Configuration Manager

The configuration system provides typed, validated, and hot-reloadable settings through Pydantic models.

**Key implementation:** [`pixelle_video/config/__init__.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/config/__init__.py) defines `PixelleVideoConfig`, which loads YAML configuration files and validates parameters across all services. The manager supports runtime configuration updates without restarting the application.

## Core Service Layer

`PixelleVideoCore` in [`pixelle_video/service.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/service.py) serves as the **singleton entry point** for the entire framework.

This core component:
- Holds the global configuration instance
- Lazily instantiates a shared **ComfyKit** connection for ComfyUI workflows
- Exposes all high-level services (LLM, TTS, Media, Video)
- Registers and manages video-generation pipelines

Initialize the framework with:

```python
import pixelle_video

await pixelle_video.initialize()

```

## LLM Service

The `LLMService` in [`pixelle_video/services/llm_service.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/llm_service.py) provides a direct wrapper around OpenAI-compatible SDKs.

**Capabilities:**
- Plain text generation
- Structured output via Pydantic models
- Configurable model selection and parameters

This service handles script generation, title creation, and any text-based content transformation required by pipelines.

## TTS Service

[`pixelle_video/services/tts_service.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/tts_service.py) implements flexible speech generation with **dual backend support**:

| Backend | Use Case | Trigger |
|---------|----------|---------|
| **Local Edge TTS** | Fast, offline generation | Default mode |
| **ComfyUI workflow** | Self-hosted or RunningHub | Via configuration override |

The service automatically handles inference mode selection and supports workflow customization for advanced audio generation pipelines.

## Media Service

The `MediaService` in [`pixelle_video/services/media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/media.py) executes **ComfyUI workflows** for visual asset generation.

Key functionality:
- `media_type` parameter determines output extraction (image or video)
- Returns structured `MediaResult` with file paths and metadata
- Integrates with `ExecuteResult` from ComfyUI API calls

This service enables generation of both static images and motion video content through configurable workflow definitions.

## Video Service

[`pixelle_video/services/video.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/video.py) provides **low-level video manipulation utilities**:

- **Audio/video merging** – Synchronize generated speech with visual content
- **Image overlay** – Compose HTML frames onto video segments
- **Segment concatenation** – Join multiple scene clips into final output
- **Background music mixing** – Add optional BGM with volume control

These primitives support the post-production phase of pipeline execution.

## Frame Processor

The `FrameProcessor` in [`pixelle_video/services/frame_processor.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/frame_processor.py) **orchestrates per-frame media generation**:

Execution flow for each `StoryboardFrame`:

1. **LLM invocation** – Optional title/script generation
2. **TTS generation** – Audio file + duration extraction
3. **Media generation** – Image/video workflow with optional duration matching to audio
4. **HTML frame composition** – Template rendering from `templates/1080x1920/`
5. **Video segment creation** – Via `VideoService`

The processor also **normalizes progress reporting** across all sub-operations, enabling real-time feedback during generation.

## Pipelines

Pipeline architecture defines **high-level video generation strategies** with pluggable lifecycle hooks.

### Base Pipeline ([`pixelle_video/pipelines/base.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/pipelines/base.py))

Defines the abstract interface that all pipelines must implement, including:
- Configuration access
- Service injection points
- Result type specifications

### Linear Video Pipeline ([`pixelle_video/pipelines/linear.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/pipelines/linear.py))

Implements a **deterministic lifecycle** with ordered async hooks:

| Phase | Hook Name | Purpose |
|-------|-----------|---------|
| Setup | `setup_environment` | Initialize resources |
| Content | `generate_content` | Create script/narrative |
| Metadata | `determine_title` | Generate video title |
| Planning | `plan_visuals` | Define visual approach |
| Structure | `initialize_storyboard` | Create frame sequence |
| Production | `produce_assets` | Generate all media |
| Assembly | `post_production` | Composite final video |
| Cleanup | `finalize` | Save metadata, cleanup |

### Standard Pipeline ([`pixelle_video/pipelines/standard.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/pipelines/standard.py))

The **`StandardPipeline`** extends `LinearVideoPipeline` with default implementations for all lifecycle hooks. This is the **default pipeline** used when calling:

```python
result = await pixelle_video.generate_video(
    text="Your script here",
    pipeline="standard"
)

```

Custom pipelines can inherit from `LinearVideoPipeline` and override any subset of hooks without modifying core logic.

## Data Models

Typed Pydantic models ensure **type safety across component boundaries**:

| Model | Location | Purpose |
|-------|----------|---------|
| `Storyboard` | [`pixelle_video/models/storyboard.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/models/storyboard.py) | Complete video plan with frames |
| `StoryboardFrame` | [`pixelle_video/models/storyboard.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/models/storyboard.py) | Individual scene with timing, media refs |
| `VideoGenerationResult` | [`pixelle_video/models/media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/models/media.py) | Final output path, metadata, duration |
| `MediaResult` | [`pixelle_video/models/media.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/models/media.py) | Generated asset with type and location |
| `ProgressEvent` | `pixelle_video/models/*` | Normalized progress updates |

These models flow through Core → Services → Pipelines → FrameProcessor, ensuring consistent data validation at every stage.

## Utilities

Supporting helpers in `pixelle_video/utils/` provide:

- **Prompt construction** – Template-based prompt building for LLM calls
- **Template resolution** – HTML template discovery and rendering
- **Temporary task folders** – Isolated workspace management per generation
- **Path utilities** – Asset location and URL generation

## Summary

Pixelle-Video's architecture follows clear separation of concerns:

- **Configuration Manager** – Typed, hot-reloadable settings via Pydantic
- **Core Service Layer** – Singleton entry point with lazy service initialization
- **Specialized Services** – Modular LLM, TTS, Media, Video, and Frame processing
- **Pipeline System** – Pluggable linear lifecycle with customizable hooks
- **Data Models** – Type-safe structures flowing across all components

This design enables rapid extension of capabilities—new LLM providers, TTS engines, or ComfyUI workflows integrate without touching core orchestration logic.

## Frequently Asked Questions

### What is the entry point for generating videos in Pixelle-Video?

The `PixelleVideoCore` singleton in [`pixelle_video/service.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/service.py) serves as the primary entry point. After calling `await pixelle_video.initialize()`, you invoke `pixelle_video.generate_video(text, pipeline="standard")` which dispatches to the selected pipeline instance.

### How does Pixelle-Video handle different TTS backends?

The `TTSService` in [`pixelle_video/services/tts_service.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/services/tts_service.py) supports both local Edge TTS for offline generation and ComfyUI workflows for cloud or self-hosted inference. The backend is selected via configuration, with optional workflow overrides for advanced customization.

### Can I customize the video generation pipeline without modifying core code?

Yes. The `LinearVideoPipeline` in [`pixelle_video/pipelines/linear.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/pipelines/linear.py) defines abstract lifecycle hooks that you can override. Create a custom class inheriting from `LinearVideoPipeline`, implement only the hooks you need to change, and register it for use via the pipeline parameter in `generate_video()`.