# How to Use the Streamlit Web UI for Pixelle-Video: Complete Setup and Operation Guide

> Learn to use the Streamlit web UI for Pixelle-Video with our complete setup and operation guide. Effortlessly generate videos by running start_web.sh and configuring settings.

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

---

**Use the Streamlit web UI for Pixelle-Video by running [`./start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/./start_web.sh), configuring LLM and ComfyUI credentials in System Settings, selecting a pipeline tab, and clicking Generate Video.**

The Streamlit web UI for Pixelle-Video provides a browser-based interface for AI video generation without writing code. This guide covers the complete architecture, setup process, and operational workflow based on the actual source implementation in the [AIDC-AI/Pixelle-Video](https://github.com/AIDC-AI/Pixelle-Video) repository.

---

## Architecture Overview

The Streamlit web UI for Pixelle-Video follows a multi-page application pattern with clear separation between presentation and core logic.

### Key Components

| Component | Purpose | Source File |
|-----------|---------|-------------|
| **Launch script** | Boots Streamlit with proper environment | [`start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh) |
| **Entry point** | Configures navigation and page routing | [`web/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/app.py) |
| **Session manager** | Caches `PixelleVideoCore` per user | [`web/state/session.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/state/session.py) |
| **Settings UI** | LLM/ComfyUI configuration panel | [`web/components/settings.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/components/settings.py) |
| **Pipeline registry** | Discovers and loads all pipeline UIs | [`web/pipelines/__init__.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/__init__.py) |
| **Core service** | Orchestrates LLM, ComfyUI, TTS, and assembly | [`pixelle_video/service.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/service.py) |

### Page Structure

The UI exposes two main pages defined in [`web/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/app.py):

- **Home** (`web/pages/1_🎬_Home.py`): Pipeline selection, prompt input, and video generation
- **History** (`web/pages/2_📚_History.py`): Job listing and previous result preview

---

## Installation and First Launch

### Prerequisites

- Python 3.10+
- `uv` package manager
- LLM API key (OpenAI-compatible)
- ComfyUI instance or RunningHub account

### Step-by-Step Setup

```bash

# 1. Clone and enter repository

git clone https://github.com/AIDC-AI/Pixelle-Video.git
cd Pixelle-Video

# 2. Install dependencies

uv sync

# 3. Configure credentials

cp config.example.yaml config.yaml

# Edit config.yaml with your LLM API key and ComfyUI endpoint

# 4. Launch the Streamlit web UI

./start_web.sh

```

The [`start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh) script executes:

```bash
#!/bin/bash
echo "🚀 Starting Pixelle-Video Web UI..."
uv run streamlit run web/app.py

```

Upon successful launch, your browser opens to `http://localhost:8501`.

---

## Configuring System Settings

Before generating videos, you must validate two required services in the **System Settings** expander.

### LLM Configuration

The settings panel in [`web/components/settings.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/components/settings.py) manages LLM presets:

1. Select a preset (OpenAI, Azure, or custom)
2. Verify `api_key`, `base_url`, and `model` fields
3. Click **"Test Connection"** to validate

Validation succeeds when the LLM responds to a simple ping request.

### ComfyUI / RunningHub Configuration

Two backend modes are supported:

| Mode | Use Case | Configuration |
|------|----------|-------------|
| **Local ComfyUI** | Self-hosted GPU | `comfyui_url: http://127.0.0.1:8188` |
| **RunningHub** | Cloud GPU service | `runninghub_api_key` and `runninghub_url` |

Click **"Test Connection"** to verify the chosen backend responds.

### Persistence

Settings are saved to [`config.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.yaml) via [`pixelle_video/config/manager.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/pixelle_video/config/manager.py). Changes trigger a session recreation via [`web/state/session.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/state/session.py), which calls `safe_rerun()` from [`web/utils/streamlit_helpers.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/utils/streamlit_helpers.py) to refresh the UI.

---

## Using Pipeline Tabs for Video Generation

The **Home** page loads available pipelines through `get_all_pipeline_uis()` in [`web/pipelines/__init__.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/__init__.py). Each pipeline extends the `PipelineUI` base class from [`web/pipelines/base.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/base.py).

### Available Pipeline Types

| Pipeline | Purpose | Typical Input |
|----------|---------|---------------|
| **Standard** | General text-to-video | Topic, style, background music |
| **Asset-Based** | Brand-consistent video | Upload assets, scene descriptions |
| **Digital Human** | Avatar/narrator videos | Avatar selection, script |
| **I2V (Image-to-Video)** | Animate existing images | Source images, motion prompts |
| **Action Transfer** | Transfer actions to new subjects | Source video, target subject |

### Standard Pipeline Workflow

The `StandardPipelineUI` in [`web/pipelines/standard.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/standard.py) demonstrates the typical flow:

1. **Render input form** – topic, style selector, optional music path
2. **Validate inputs** – ensure non-empty topic and valid backend connections
3. **Call core service** – invoke `pixelle_video.run_standard()` with parameters
4. **Display progress** – show spinner during generation stages
5. **Present result** – embed video player with download link

### Generation Process Internally

When you click **"Generate Video"**, the `PixelleVideoCore` service orchestrates:

1. **Storyboard generation** – LLM creates scene descriptions and timing
2. **Visual generation** – ComfyUI/RunningHub renders images per scene
3. **Audio generation** – TTS converts scripts to synchronized speech
4. **Final assembly** – FFmpeg combines video, audio, and background music

The result path displays in the UI and logs to the History page via `web/pages/2_📚_History.py`.

---

## Monitoring Jobs in History

The **History** page queries completed and in-progress jobs from the session state. Each entry shows:

- **Prompt / Topic**
- **Pipeline type used**
- **Timestamp and duration**
- **Output video path** with inline preview

Click any history item to reload its parameters into the Home page for regeneration or modification.

---

## Code Snippets for Advanced Use

### Launching UI from Python

```python
import subprocess

# Programmatic equivalent of ./start_web.sh

subprocess.run(
    ["uv", "run", "streamlit", "run", "web/app.py"],
    check=True
)

```

### Accessing Core Service Directly

```python
from web.state.session import get_pixelle_video

# Retrieve cached PixelleVideoCore instance

pixelle = get_pixelle_video()

# Generate storyboard manually

storyboard = pixelle.generate_storyboard(
    prompt="A cyberpunk marketplace at night"
)

```

### Running Pipeline Without UI

```python
from pixelle_video.service import PixelleVideoCore

# Initialize core service

core = PixelleVideoCore()
core.initialize()

# Execute standard pipeline directly

result = core.run_standard(
    prompt="Mars colony documentary",
    style="cinematic",
    music="bgm/epic.mp3"
)
print(f"Video saved to: {result.video_path}")

```

### Resetting Configuration

```python
from pixelle_video.config.schema import PixelleVideoConfig
from pixelle_video.config.manager import config_manager

# Reset to defaults

config_manager.config = PixelleVideoConfig()
config_manager.save()

```

---

## Summary

- **Start the UI** with [`./start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/./start_web.sh) which launches [`web/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/app.py) via Streamlit
- **Configure required services** in System Settings: LLM API credentials and ComfyUI/RunningHub endpoint
- **Select pipeline tabs** on the Home page—each extends `PipelineUI` from [`web/pipelines/base.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/base.py)
- **Generate videos** through the orchestrated workflow: storyboard → visuals → audio → final assembly
- **Track history** via the dedicated page that persists job metadata and enables result preview

---

## Frequently Asked Questions

### What is the default URL for the Pixelle-Video Streamlit UI?

The UI starts at `http://localhost:8501` by default. The [`start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh) script automatically opens this address in your default browser after launching the Streamlit server.

### Can I use RunningHub instead of a local ComfyUI instance?

Yes. In [`web/components/settings.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/components/settings.py), select RunningHub mode and provide your `runninghub_api_key` and `runninghub_url`. The connection test validates your credentials before allowing generation.

### How do I add a new pipeline to the UI?

Create a class extending `PipelineUI` from [`web/pipelines/base.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/base.py), implement the `render()` method, and place your file in `web/pipelines/`. The registry in [`web/pipelines/__init__.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pipelines/__init__.py) automatically discovers and displays your pipeline as a new tab.

### What happens when I change LLM settings mid-session?

[`web/state/session.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/state/session.py) detects configuration changes via `get_pixelle_video()`, destroys the cached `PixelleVideoCore` instance, and recreates it with new settings. The `safe_rerun()` helper from [`web/utils/streamlit_helpers.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/utils/streamlit_helpers.py) refreshes the UI to apply changes.