Zordon/README.md

![Zordon Screenshot](docs/screenshot.png)

---

# Zordon

A Python-based distributed rendering management tool that supports Blender, FFmpeg, and other render engines. Zordon efficiently manages render jobs across multiple machines, making it ideal for small render farms in home studios or small businesses.

## What is Zordon?

Zordon is a tool designed for small render farms, such as those used in home studios or small businesses, to efficiently manage and run render jobs for Blender, FFmpeg, and other video renderers. It simplifies the process of distributing rendering tasks across multiple available machines, optimizing the rendering workflow for artists, animators, and video professionals.

The system works by:
- **Server**: Central coordinator that manages job queues and distributes tasks to available workers
- **Clients**: Lightweight workers that run on rendering machines and execute assigned jobs
- **API**: RESTful endpoints for programmatic job submission and monitoring

## Features

- **Distributed Rendering**: Queue and distribute render jobs across multiple machines
- **Multi-Engine Support**: Compatible with Blender, FFmpeg, and extensible to other render engines
- **Desktop UI**: PyQt6 interface for job management and monitoring
- **REST API**: Flask-based API for programmatic access
- **Cross-Platform**: Runs on Windows, macOS, and Linux
- **Zero-Install Clients**: Lightweight client executables for worker machines

## Installation

### Prerequisites

- Python 3.11 or later
- Git

### Setup

1. Clone the repository:
   ```bash
   git clone https://github.com/blw1138/Zordon.git
   cd Zordon
   ```

2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```

3. (Optional) Install PyInstaller for building executables:
   ```bash
   pip install pyinstaller pyinstaller_versionfile
   ```

## Usage

### Quick Start

1. **Start the Server**: Run the central server to coordinate jobs.
   ```bash
   python server.py
   ```

2. **Launch Clients**: On each rendering machine, run the client to connect to the server.
   ```bash
   python client.py
   ```



### Detailed Workflow

#### Setting Up a Render Farm

1. Choose one machine as the server (preferably a dedicated machine with good network connectivity).
2. Build and distribute client executables to worker machines:
   ```bash
   pyinstaller client.spec
   ```
   Copy the generated executable to each worker machine.

3. Ensure all machines can communicate via network (same subnet recommended).

#### Submitting Render Jobs

Jobs can be submitted via the desktop UI or programmatically via the API:

- **Via UI**: Use the desktop interface to upload project files, specify render settings, and queue jobs.
- **Via API**: Send POST requests to `/api/jobs` with job configuration in JSON format.

Example API request:
```bash
curl -X POST http://localhost:5000/api/jobs \
  -H "Content-Type: application/json" \
  -d '{
    "engine": "blender",
    "project_path": "/path/to/project.blend",
    "output_path": "/path/to/output",
    "frames": "1-100",
    "settings": {"resolution": "1920x1080"}
  }'
```

#### Monitoring and Managing Jobs

- **UI**: View job status, progress, logs, and worker availability in real-time.
- **API Endpoints**:
  - `GET /api/jobs`: List all jobs
  - `GET /api/jobs/{id}`: Get job details
  - `DELETE /api/jobs/{id}`: Cancel a job
  - `GET /api/workers`: List connected workers

#### Worker Management

Workers automatically connect to the server when started. You can:
- View worker status and capabilities in the dashboard
- Configure worker priorities and resource limits
- Monitor CPU/GPU usage per worker

### Development Mode

For development and testing:

Run the server:
```bash
python server.py
```

Run a client (can run multiple for testing):
```bash
python client.py
```


### Building Executables

Build server executable:
```bash
pyinstaller server.spec
```

Build client executable:
```bash
pyinstaller client.spec
```

## Configuration

Settings are stored in `src/utilities/config.py`. Supports YAML/JSON for data serialization and environment-specific configurations.

## Architecture

Zordon follows a modular architecture with the following key components:

- **API Server** (`src/api/`): Flask-based REST API
- **Engine System** (`src/engines/`): Pluggable render engines (Blender, FFmpeg, etc.)
- **UI** (`src/ui/`): PyQt6-based interface
- **Job Management** (`src/render_queue.py`): Distributed job queue

Design patterns include Factory Pattern for engine creation, Observer Pattern for status updates, and Strategy Pattern for different worker implementations.

## Contributing

1. Fork the repository
2. Create a feature branch: `git checkout -b feature/your-feature`
3. Follow the code style guidelines in `AGENTS.md`
4. Test the build: `pyinstaller server.spec`
5. Submit a pull request

### Commit Message Format

```
feat: add support for new render engine
fix: resolve crash when engine path is invalid
docs: update API documentation
refactor: simplify job status handling
```

## Supported Render Engines

- **Blender**
- **FFmpeg**
- **Adobe After Effects** (planned)
- **Cinema 4D** (planned)
- **Autodesk Maya** (planned)

## System Requirements

- Windows 10 or later
- macOS Ventura (13.0) or later
- Linux (supported versions TBD)

## License

Zordon is licensed under the MIT License. See the [LICENSE](LICENSE.txt) file for more details.

## Notice

This software is in beta and intended for casual/hobbyist use. Not recommended for mission-critical environments.