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

Use the Streamlit web UI for Pixelle-Video by running ./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 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
Entry point	Configures navigation and page routing	web/app.py
Session manager	Caches PixelleVideoCore per user	web/state/session.py
Settings UI	LLM/ComfyUI configuration panel	web/components/settings.py
Pipeline registry	Discovers and loads all pipeline UIs	web/pipelines/__init__.py
Core service	Orchestrates LLM, ComfyUI, TTS, and assembly	pixelle_video/service.py

Page Structure

The UI exposes two main pages defined in 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

# 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 script executes:

#!/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 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 via pixelle_video/config/manager.py. Changes trigger a session recreation via web/state/session.py, which calls safe_rerun() from 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. Each pipeline extends the PipelineUI base class from 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 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

import subprocess

# Programmatic equivalent of ./start_web.sh

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

Accessing Core Service Directly

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

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

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 which launches 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
• 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 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, 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, implement the render() method, and place your file in web/pipelines/. The registry in 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 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 refreshes the UI to apply changes.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}