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

```bash
# 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

```bash
# Install dependencies
pip install -r requirements.txt

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

### Building

```bash
# 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:

```python
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:

```python
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