remotion_service/SERVER_README.md

# Remotion Render Service

A high-performance video rendering service built with ElysiaJS and Remotion. This service accepts S3 URLs for input videos, renders them using Remotion compositions, and returns S3 URLs for the rendered outputs.

## Features

- **S3 Integration**: Direct integration with S3-compatible storage (MinIO)
- **Remotion Rendering**: Leverages Remotion for high-quality video rendering
- **ElysiaJS Server**: Fast, type-safe API with automatic validation
- **Bun Runtime**: Utilizes Bun for optimal performance

## Project Structure

```
server/
├── server.ts                           # Main server entry point
├── shared/
│   └── config.ts                       # Global configuration
└── routers/
    ├── render_file/
    │   ├── index.ts                    # Render endpoint
    │   ├── service.ts                  # Render logic
    │   ├── types.ts                    # Type definitions
    │   └── constants.ts                # Endpoint constants
    └── services/
        └── s3_storage/
            ├── index.ts                # S3 service implementation
            ├── types.ts                # Type definitions
            ├── utils.ts                # Helper functions
            └── constants.ts            # Service constants
```

## Setup

1. **Install Dependencies**

   ```bash
   bun install
   ```

2. **Configure Environment**
   Copy `.env.example` to `.env` and fill in your configuration:

   ```bash
   cp .env.example .env
   ```

   Required environment variables:
   - `S3_ACCESS_KEY`: Your S3/MinIO access key
   - `S3_SECRET_KEY`: Your S3/MinIO secret key
   - `S3_BUCKET_NAME`: Target bucket name
   - `S3_ENDPOINT_URL`: S3/MinIO endpoint URL
   - `PORT`: Server port (default: 3001)

3. **Start the Server**
   ```bash
   bun run server
   ```

## API Endpoints

### `POST /render/file`

Renders a video from an S3 input URL and returns the rendered output S3 URL.

**Request Body:**

```json
{
  "inputS3Url": "https://minio.example.com/bucket/input/video.mp4",
  "compositionId": "Main",
  "outputFormat": "mp4"
}
```

**Response:**

```json
{
  "success": true,
  "outputS3Url": "https://minio.example.com/bucket/rendered/output.mp4",
  "metadata": {
    "inputFile": "https://minio.example.com/bucket/input/video.mp4",
    "outputFile": "https://minio.example.com/bucket/rendered/output.mp4",
    "renderTime": 12500,
    "fileSize": 5242880
  }
}
```

**Error Response:**

```json
{
  "success": false,
  "error": "Error message description"
}
```

### `GET /health`

Health check endpoint.

**Response:**

```json
{
  "status": "healthy",
  "uptime": 123.456,
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

### `GET /`

Service information endpoint.

**Response:**

```json
{
  "service": "Remotion Render Service",
  "version": "1.0.0",
  "status": "running",
  "timestamp": "2024-01-01T00:00:00.000Z"
}
```

## S3 Storage Service

The S3 storage service provides a comprehensive interface for interacting with S3-compatible storage:

- `uploadFile()`: Upload files to S3
- `downloadFile()`: Download files from S3
- `getFileUrl()`: Generate presigned URLs
- `deleteFile()`: Remove files from S3
- `checkFileExists()`: Verify file existence
- `getFileInfo()`: Retrieve file metadata
- `getLocalCopy()`: Download file to temp location
- `uploadFromLocalPath()`: Upload from local filesystem

## Development

### Run in Development Mode

```bash
bun run server
```

### Type Checking

```bash
bun run lint
```

## Architecture

The service follows a modular architecture:

1. **Server Layer** (`server.ts`): Main application setup and routing
2. **Router Layer** (`routers/`): Endpoint definitions and request handling
3. **Service Layer** (`services/`): Business logic and external integrations
4. **Shared Layer** (`shared/`): Global configuration and utilities

## Integration with Django Backend

This service is designed to work alongside the Django backend in `coffee_project_backend_v2`. The Django backend can make requests to this service to render videos stored in the shared MinIO storage.

Example Django integration:

```python
import requests

response = requests.post(
    'http://localhost:3001/render/file',
    json={
        'inputS3Url': input_url,
        'compositionId': 'Main',
        'outputFormat': 'mp4'
    }
)

result = response.json()
if result['success']:
    rendered_url = result['outputS3Url']
```

## Technologies

- **Bun**: Fast JavaScript runtime
- **ElysiaJS**: High-performance web framework
- **Remotion**: Programmatic video rendering
- **AWS SDK**: S3 client for storage operations
- **TypeScript**: Type-safe development