# How to Set Up and Run Pixelle-Video Locally: Complete Installation Guide

> Learn to set up and run Pixelle-Video locally with this complete installation guide. Install dependencies, clone the repo, and launch the UI effortlessly.

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

---

**To run Pixelle-Video locally, install `uv` and `ffmpeg`, clone the repository, and launch the Streamlit UI with `uv run streamlit run web/app.py`.**

Pixelle-Video is an open-source AI platform for generating short videos from text prompts. This guide walks you through the complete local setup process using source code from the [AIDC-AI/Pixelle-Video](https://github.com/AIDC-AI/Pixelle-Video) repository.

## Prerequisites: Install uv and ffmpeg

Before cloning the repository, you need two system dependencies: **uv** (a fast Python package manager) and **ffmpeg** (for video/audio encoding).

### Install uv

Follow the official installation guide at [docs.astral.sh/uv](https://docs.astral.sh/uv/getting-started/installation/).

### Install ffmpeg

The README documents these steps at lines 1020-1026:

- **macOS**: `brew install ffmpeg`
- **Ubuntu/Debian**: `sudo apt update && sudo apt install ffmpeg`
- **Windows**: Download from [ffmpeg.org/download.html](https://ffmpeg.org/download.html) and add `bin` to your `PATH`

## Clone and Launch the Web UI

Once dependencies are installed, set up the project:

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

```

Launch the **Streamlit web interface** with:

```bash
uv run streamlit run web/app.py

```

This command matches the [`start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh) helper script (lines 7-9)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/start_web.sh#L7-L9】. The entry point at [`web/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/app.py) (lines 40-58) sets up multi-page navigation and runs the UI【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/web/app.py#L40-L58】.

The UI opens at `http://localhost:8501` by default.

## (Optional) Run the API Server Directly

If you prefer programmatic access or want to build custom clients, launch the **FastAPI backend** separately:

```bash
uv run python api/app.py

```

The server initialization at [`api/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/app.py) (lines 71-85) prints a startup banner and launches uvicorn【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/api/app.py#L71-L85】. Configuration including host, port, CORS settings, and API prefixes lives in [`api/config.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/config.py) (lines 24-46)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/api/config.py#L24-L46】.

## Configure Your API Keys and Services

Before generating videos, you must configure external services in the **System Configuration** panel (⚙️):

| Setting | Required For | Typical Value |
|---------|-------------|---------------|
| **LLM API** | Script generation | OpenAI, Claude, or local endpoint |
| **Image generation** | Visual assets | ComfyUI at `http://127.0.0.1:8188` or RunningHub API key |
| **TTS workflow** | Voice narration | Edge-TTS, Index-TTS, or voice cloning with reference audio |

These settings map to the [`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml) schema, which the UI copies to [`config.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.yaml) at runtime.

## Generate Your First Video

With configuration complete:

1. Navigate to the **Home** page (`web/pages/1_🎬_Home.py`)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/web/pages/1_%F0%9F%8E%AC_Home.py】
2. Enter a **topic** or paste a full script
3. Select a **template** (e.g., [`video_default.html`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/video_default.html) from `templates/`)
4. Click **🎬 Generate Video**

Progress bars display each pipeline stage: script generation → image synthesis → voice synthesis → final video rendering. The output MP4 appears in the UI and saves to the `output/` directory.

## Windows One-Click Installation

For Windows users wanting a no-installation experience, download the **Windows package** from the release section (documented at README lines 82-90)【/cache/repos/github.com/AIDC-AI/Pixelle-Video/main/README.md#L82-L90】.

The bundle includes:

- Pre-compiled `ffmpeg.exe`
- All Python dependencies via `uv`
- Double-clickable `start.bat` (equivalent to [`start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh))

Extract and run `start.bat` — no manual dependency installation required.

## Example API Calls

With the API server running, interact programmatically:

```bash

# Health check

curl http://localhost:8000/health

# Generate narration script

curl -X POST http://localhost:8000/api/content/narration \
     -H "Content-Type: application/json" \
     -d '{"topic":"Why reading every day matters"}'

# Synchronous video generation (videos under 30 seconds)

curl -X POST http://localhost:8000/api/video/generate/sync \
     -H "Content-Type: application/json" \
     -d '{
           "topic":"The future of AI",
           "template":"video_default.html",
           "tts_workflow":"edge_tts.json",
           "image_workflow":"image_flux.json"
         }'

```

The OpenAPI specification is available at [`/openapi.json`](https://github.com/AIDC-AI/Pixelle-Video/blob/main//openapi.json) (configured in [`api/config.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/config.py)).

## Key Architecture Files

| File | Purpose | Direct Link |
|------|---------|-------------|
| [`README.md`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/README.md) | Documentation and feature overview | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/README.md) |
| [`start_web.sh`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh) | Bash launcher for Streamlit UI | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/start_web.sh) |
| [`api/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/app.py) | FastAPI entry point | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/app.py) |
| [`api/config.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/config.py) | Runtime configuration | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/config.py) |
| [`api/tasks/manager.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/tasks/manager.py) | Asynchronous task orchestration | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/tasks/manager.py) |
| [`web/app.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/app.py) | Streamlit entry point | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/app.py) |
| `web/pages/1_🎬_Home.py` | Main video generation interface | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/web/pages/1_%F0%9F%8E%AC_Home.py) |
| [`config.example.yaml`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml) | Configuration template | [View](https://github.com/AIDC-AI/Pixelle-Video/blob/main/config.example.yaml) |

## Summary

To set up and run Pixelle-Video locally:

- **Install prerequisites**: `uv` and `ffmpeg` are required before cloning
- **Launch the UI**: `uv run streamlit run web/app.py` starts the web interface at `localhost:8501`
- **Configure services**: Add LLM, image generation, and TTS credentials in the System Configuration panel
- **Generate videos**: Enter a topic, select a template, and click the generate button
- **Optional API access**: Run `uv run python api/app.py` for direct backend access

Windows users can skip installation entirely by downloading the pre-built Windows package with `start.bat`.

## Frequently Asked Questions

### What are the minimum hardware requirements for running Pixelle-Video locally?

Pixelle-Video itself is lightweight and runs on CPU, but video generation performance depends on your chosen image and TTS backends. For local ComfyUI image generation, a CUDA-capable GPU with at least 8GB VRAM is recommended. Edge-TTS requires no local GPU. Always ensure sufficient disk space for ffmpeg temporary files and output videos.

### Can I use Pixelle-Video without installing Python dependencies?

Yes. Windows users can download the **Windows one-click package** from the releases page. This bundle includes pre-compiled `ffmpeg.exe`, all Python dependencies packaged via `uv`, and a `start.bat` file that launches the interface immediately. No manual `uv` or `ffmpeg` installation is required.

### How do I connect Pixelle-Video to my own ComfyUI instance?

In the **System Configuration** panel (⚙️), set the **Image Generation** option to "Local ComfyUI" and enter your ComfyUI URL (default: `http://127.0.0.1:8188`). Ensure your ComfyUI instance is running with the required model checkpoints and the workflow JSON files from `workflows/selfhost/*.json` are accessible. The backend communicates via the ComfyUI REST API defined in the workflow utilities.

### What is the difference between synchronous and asynchronous video generation?

**Synchronous generation** (`/api/video/generate/sync`) blocks until completion and is suitable for videos under 30 seconds. The API returns the final MP4 directly. **Asynchronous generation** submits a task to the queue managed by [`api/tasks/manager.py`](https://github.com/AIDC-AI/Pixelle-Video/blob/main/api/tasks/manager.py) and returns a task ID immediately. Poll the status endpoint or use WebSocket updates to track progress. Asynchronous mode handles longer videos and concurrent requests without blocking the API server.