FrameTour-RenderWorker/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

RenderWorker is a Python-based video processing service that renders video content using FFmpeg. It operates as both a Flask web service and a standalone worker process, processing video rendering tasks with templates, effects, and various transformations.

Architecture

The project uses a modern layered architecture with clear separation of concerns:

Core Components

• Services Layer (services/): Main business logic with dependency injection

  • RenderService: Handles video rendering operations
  • TemplateService: Manages video templates and resources
  • TaskService: Orchestrates the complete task lifecycle

• Entity Layer (entity/): Data models and domain logic

  • RenderTask: Core data model for rendering tasks
  • FFmpegCommandBuilder: Generates FFmpeg commands from tasks
  • effects/: Pluggable effect processing system (zoom, speed, skip, tail, cameraShot)

• Configuration (config/): Centralized configuration management

  • Environment-based configuration with dataclasses
  • FFmpeg, API, Storage, and Server configurations

• Utilities (util/): Common utilities for API, OSS, FFmpeg operations

Entry Points

• Web Service: app.py - Flask application serving HTTP endpoints
• Worker Process: index.py - Long-running task processor that polls for work
• Legacy Compatibility: Maintains backward compatibility with older entity/ffmpeg.py and biz/ modules

Common Commands

Running the Application

# Web service mode (Flask API)
python app.py

# Worker mode (background task processor)  
python index.py

# Worker with template redownload
python index.py redownload

Development Setup

# Install dependencies
pip install -r requirements.txt

# Environment setup
cp .env.example .env
# Edit .env with your configuration

Building

# Build standalone executable
pyinstaller index.spec

# Build updater
pyinstaller updater_helper.spec

Key Environment Variables

Required configuration (see .env.example):

• API_ENDPOINT: Backend API endpoint
• ACCESS_KEY: Authentication key
• TEMPLATE_DIR: Directory for template storage
• ENCODER_ARGS: FFmpeg encoder arguments (default: "-c:v h264")
• VIDEO_ARGS: Video processing arguments
• OTLP_ENDPOINT: OpenTelemetry endpoint for monitoring

Architecture Patterns

Service Layer Pattern

All new code should use the service layer:

from services import DefaultRenderService, DefaultTemplateService, DefaultTaskService

# Dependency injection
render_service = DefaultRenderService()
template_service = DefaultTemplateService()
task_service = DefaultTaskService(render_service, template_service)

# Process tasks
success = task_service.process_task(task_info)

Effect Processing System

Video effects use a pluggable architecture:

from entity.effects import registry
from entity.effects.base import EffectProcessor

# Get existing effect
processor = registry.get_processor('zoom', '0,2.0,1.5')

# Register new effect
class MyEffect(EffectProcessor):
    def validate_params(self) -> bool:
        return True
    
    def generate_filter_args(self, video_input: str, effect_index: int):
        return filter_args, output_stream
        
    def get_effect_name(self) -> str:
        return "myeffect"

registry.register('myeffect', MyEffect)

Task Processing Flow

1. Task Reception: API receives task via HTTP endpoint or polling
2. Template Resolution: Template service downloads/loads video templates
3. Task Creation: Task service creates RenderTask with effects and resources
4. Command Building: FFmpegCommandBuilder generates FFmpeg commands
5. Execution: RenderService executes FFmpeg with monitoring
6. Cleanup: Temporary files cleaned, results uploaded

Backward Compatibility

The codebase maintains compatibility with legacy components:

• biz.task.start_task() - Main task entry point
• entity.ffmpeg.FfmpegTask - Legacy task object (now simplified)
• template.get_template_def() - Template access

These should work but new development should use the service layer.

FFmpeg Integration

The system generates complex FFmpeg commands for video processing:

• Supports effects chaining (zoom, speed changes, cropping)
• Handles multiple input files and concatenation
• Manages audio processing and overlays
• Supports LUT color grading and subtitle embedding

Monitoring and Telemetry

• OpenTelemetry: Distributed tracing for request monitoring
• Structured Logging: Detailed logs for debugging
• Error Handling: Custom exception types (RenderError, FFmpegError, TemplateError)

File Organization

• Configuration and environment variables → config/
• Business logic and services → services/
• Data models and domain objects → entity/
• HTTP API and external integrations → util/
• Legacy compatibility layer → biz/
• Application entry points → app.py, index.py

Working with Templates

Templates define video processing workflows:

• Downloaded from remote API and cached locally
• Support video parts, effects, overlays, and audio
• Use placeholder system for dynamic content
• Managed by TemplateService with automatic updates

Development Notes

• The project recently underwent major architectural refactoring from monolithic to layered design
• New features should use the services layer and effect processor system
• Legacy code is maintained for compatibility but simplified
• All video processing ultimately uses FFmpeg with generated command lines
• The system supports both synchronous (web) and asynchronous (worker) operation modes