flamenco/README_NEW.md

Flamenco

Distributed render farm management system for Blender

---

Quick Start

Get up and running with Flamenco in minutes:

# Download latest release
curl -L https://flamenco.blender.org/download -o flamenco.zip
unzip flamenco.zip

# Start the Manager (central coordination server)
./flamenco-manager

# In another terminal, start a Worker (render node)  
./flamenco-worker

# Install the Blender add-on from addon/ directory
# Then submit your first render job from Blender!

Web Interface: Open http://localhost:8080 to manage your render farm.

What is Flamenco?

Flamenco is a free, open-source render farm manager that helps you distribute Blender renders across multiple computers. Whether you have a small home studio or a large production facility, Flamenco makes it easy to:

• Scale Your Renders - Distribute work across any number of machines
• Monitor Progress - Real-time web interface with job status and logs
• Manage Resources - Automatic worker discovery and load balancing
• Stay Flexible - Support for custom job types and rendering pipelines

Key Features

• 🚀 Easy Setup - One-click worker registration and automatic configuration
• 📊 Web Dashboard - Modern Vue.js interface for monitoring and management
• 🔧 Extensible - JavaScript-based job compilers for custom workflows
• 💾 Asset Management - Optional Shaman system for efficient file sharing
• 🔒 Secure - Worker authentication and task isolation
• 📱 Cross-Platform - Linux, Windows, and macOS support

Architecture

Flamenco consists of three main components that work together:

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│  Blender Add-on │───▶│    Manager      │◀───│     Worker      │
│  (Job Submit)   │    │ (Coordination)  │    │ (Task Execute)  │
└─────────────────┘    └─────────────────┘    └─────────────────┘
                              │                        │
                              │                ┌─────────────────┐
                              │                │     Worker      │
                              │                │ (Task Execute)  │
                              │                └─────────────────┘
                              │
                              │                ┌─────────────────┐
                              └───────────────▶│     Worker      │
                                               │ (Task Execute)  │
                                               └─────────────────┘

• Manager: Central server that receives jobs, breaks them into tasks, and distributes work
• Worker: Lightweight daemon that executes render tasks on individual machines
• Add-on: Blender plugin that submits render jobs directly from your Blender projects

Installation

Pre-built Releases

Download the latest release for your platform from flamenco.blender.org/download.

Building from Source

Prerequisites:

• Go 1.24.4+
• Node.js 18+ (for web app)
• Python 3.9+ (for add-on development)

Build all components:

# Install build tools and dependencies
make with-deps

# Build Manager and Worker binaries
make all

# Build web application
make webapp-static

# Run tests
make test

Development setup:

# Start Manager in development mode
make devserver-webapp  # Web app dev server (port 8081)
./flamenco-manager     # Manager with hot-reload webapp

# Start Worker
./flamenco-worker

Usage Examples

Basic Render Job

# In Blender with Flamenco add-on installed
import bpy

# Configure render settings
bpy.context.scene.render.filepath = "//render/"
bpy.context.scene.frame_start = 1
bpy.context.scene.frame_end = 250

# Submit to Flamenco
bpy.ops.flamenco.submit_job(
    job_name="My Animation",
    job_type="simple_blender_render"
)

Custom Job Types

Create custom rendering pipelines with JavaScript job compilers:

// custom_job_type.js
function compileJob(job) {
    const renderTasks = [];
    
    for (let frame = job.settings.frame_start; frame <= job.settings.frame_end; frame++) {
        renderTasks.push({
            name: `render-frame-${frame.toString().padStart(4, '0')}`,
            type: "blender",
            settings: {
                args: [
                    job.settings.blender_cmd, "-b", job.settings.filepath,
                    "-f", frame.toString()
                ]
            }
        });
    }
    
    return {
        tasks: renderTasks,
        dependencies: [] // Define task dependencies
    };
}

API Integration

Access Flamenco programmatically via REST API:

# Get farm status
curl http://localhost:8080/api/v3/status

# List active jobs  
curl http://localhost:8080/api/v3/jobs

# Get job details
curl http://localhost:8080/api/v3/jobs/{job-id}

More Advanced Examples

Worker Configuration

# flamenco-worker.yaml
manager_url: http://manager.local:8080
task_types: ["blender", "ffmpeg", "file-management"]
worker_name: "render-node-01"

# Resource limits
max_concurrent_tasks: 4
memory_limit: "16GB"

# Sleep schedule for off-hours
sleep_schedule:
  enabled: true
  days_of_week: ["monday", "tuesday", "wednesday", "thursday", "friday"]
  start_time: "22:00"
  end_time: "08:00"

Manager Configuration

# flamenco-manager.yaml
listen: :8080
database_url: "flamenco-manager.sqlite"

# Optional Shaman asset management
shaman:
  enabled: true
  storage_path: "/shared/assets"

# Variable definitions for cross-platform paths
variables:
  blender:
    linux: "/usr/bin/blender"
    windows: "C:\\Program Files\\Blender Foundation\\Blender\\blender.exe" 
    darwin: "/Applications/Blender.app/Contents/MacOS/blender"

Development

This repository contains the sources for Flamenco. The Manager, Worker, and Blender add-on sources are all combined in this one repository.

Project Structure

├── cmd/                    # Main entry points
│   ├── flamenco-manager/   # Manager executable
│   └── flamenco-worker/    # Worker executable
├── internal/               # Private Go packages
│   ├── manager/            # Manager implementation
│   └── worker/             # Worker implementation  
├── pkg/                    # Public Go packages
├── web/                    # Frontend code
│   ├── app/               # Vue.js webapp
│   └── project-website/   # Documentation site
├── addon/                  # Python Blender add-on
└── magefiles/             # Build system

Development Commands

# Code generation (after API changes)
make generate

# Development servers
make devserver-webapp       # Vue.js dev server
make devserver-website      # Hugo docs site

# Code quality
make vet                    # Go vet
make check                  # Comprehensive checks  
make format                 # Format all code

# Database management
make db-migrate-up          # Apply migrations
make db-migrate-status      # Check status

Contributing

We welcome contributions! Here's how to get started:

1. Fork the repository on GitHub
2. Create a feature branch: git checkout -b feature-name
3. Make your changes with tests
4. Run quality checks: make check
5. Submit a pull request

Development Guidelines:

• Follow existing code style
• Add tests for new features
• Update documentation as needed
• Use conventional commit messages

First-time contributors: Look for issues labeled good-first-issue.

Testing

# Run all tests
make test

# Test specific components
go test ./internal/manager/...
go test ./internal/worker/...

# Integration tests
go test ./internal/manager/job_compilers/

Documentation

• 📖 Full Documentation: flamenco.blender.org
• 🚀 Quick Start Guide: Getting Started
• 🔧 Development Setup: Development Environment
• 📋 API Reference: OpenAPI Spec
• ❓ FAQ: Frequently Asked Questions

Offline Documentation: Available in web/project-website/content/ directory.

Community & Support

• 🐛 Report Issues: GitHub Issues
• 💬 Discussions: Blender Chat #flamenco
• 📧 Mailing List: bf-flamenco
• 🎥 Video Tutorials: Blender Studio

License

Flamenco is licensed under the GNU General Public License v3.0 or later.

See LICENSE for the full license text.

---

Made with ❤️ by the Blender Community

Blender • Documentation • Releases