media-exporter-processor/README.md

Media processing API with thumbnail generation and cloud storage

# Media Exporter Processor

A modern video processing API built with Bun, Hono, and TypeScript that adds GPS metadata to videos, generates WebP thumbnails, and uploads everything to R2/S3 storage.

## Features

- 🎥 **Video Processing**: Add GPS coordinates and timestamps to video metadata using exiftool
- 🖼️ **Thumbnail Generation**: Create WebP thumbnails in multiple sizes (512x512, 256x256, 128x128, 64x64) using ffmpeg
- ☁️ **Cloud Storage**: Upload videos and thumbnails to Cloudflare R2 or AWS S3 using Bun's native S3 client
- 🔒 **Authentication**: Time-safe token validation to prevent timing attacks
- ✅ **Validation**: Request validation using valibot schemas
- 🏗️ **Clean Architecture**: Modular services for maintainability

## Architecture

```
src/
├── services/
│   ├── AuthService.ts          # Token validation and middleware
│   ├── ThumbnailService.ts     # FFmpeg thumbnail generation
│   ├── UploadService.ts        # R2/S3 uploads using Bun S3Client
│   └── VideoProcessingService.ts # Video metadata processing
├── schemas/
│   └── VideoSchemas.ts         # Valibot validation schemas
├── utils/
│   ├── Config.ts               # Environment configuration
│   └── FileUtils.ts            # File handling utilities
└── index.ts                    # Main Hono application
```

## Prerequisites

- [Bun](https://bun.sh) runtime
- [ffmpeg](https://ffmpeg.org) for thumbnail generation
- [exiftool](https://exiftool.org) for video metadata
- Cloudflare R2 or AWS S3 bucket

### Install Dependencies (macOS)

```bash
# Install ffmpeg and exiftool
brew install ffmpeg exiftool

# Install Bun if not already installed
curl -fsSL https://bun.sh/install | bash
```

### Install Dependencies (Ubuntu/Debian)

```bash
# Install ffmpeg and exiftool
sudo apt update
sudo apt install ffmpeg libimage-exiftool-perl

# Install Bun if not already installed
curl -fsSL https://bun.sh/install | bash
```

## Setup

1. **Clone and install dependencies:**

```bash
git clone <repository-url>
cd media-exporter-processor
bun install
```

2. **Set up environment variables:**

Create a `.env` file with the following variables:

```bash
# Authentication
AUTH_TOKEN=your-secret-auth-token-here

# Cloudflare R2 Configuration
R2_ACCESS_KEY_ID=your-r2-access-key-id
R2_SECRET_ACCESS_KEY=your-r2-secret-access-key
R2_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
R2_BUCKET=your-bucket-name
R2_REGION=auto

# For AWS S3 instead of R2, use:
# R2_ENDPOINT=https://s3.amazonaws.com
# R2_REGION=us-east-1
```

3. **Start the development server:**

```bash
bun run dev
```

The server will start on `http://localhost:3000` (or the port specified by your deployment platform).

## API Usage

### Authentication

All endpoints require an `Authorization` header with a Bearer token:

```bash
Authorization: Bearer your-secret-auth-token-here
```

### Process Video

**POST** `/video-simple`

Upload a video file and add GPS metadata, generate thumbnails, and upload to R2/S3.

**Query Parameters:**

- `lat` (optional): Latitude coordinate (default: 37.7749)
- `lon` (optional): Longitude coordinate (default: -122.4194)
- `alt` (optional): Altitude in meters
- `timestamp` (optional): ISO date string or Unix timestamp

**Request Body:** Raw video file (MP4)

**Example:**

```bash
curl -X POST "http://localhost:3000/video-simple?lat=37.7749&lon=-122.4194&alt=100&timestamp=2024-01-15T10:30:00Z" \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: video/mp4" \
  --data-binary @video.mp4
```

**Response:**

```json
{
  "success": true,
  "message": "Video processed successfully",
  "video": {
    "url": "https://bucket.r2.cloudflarestorage.com/videos/1234567890-video.mp4",
    "key": "videos/1234567890-video.mp4",
    "size": 1048576
  },
  "thumbnails": {
    "512": {
      "size": 512,
      "url": "https://bucket.r2.cloudflarestorage.com/thumbnails/1234567890-video-512x512.webp",
      "key": "thumbnails/1234567890-video-512x512.webp"
    },
    "256": {
      "size": 256,
      "url": "https://bucket.r2.cloudflarestorage.com/thumbnails/1234567890-video-256x256.webp",
      "key": "thumbnails/1234567890-video-256x256.webp"
    },
    "128": {
      "size": 128,
      "url": "https://bucket.r2.cloudflarestorage.com/thumbnails/1234567890-video-128x128.webp",
      "key": "thumbnails/1234567890-video-128x128.webp"
    },
    "64": {
      "size": 64,
      "url": "https://bucket.r2.cloudflarestorage.com/thumbnails/1234567890-video-64x64.webp",
      "key": "thumbnails/1234567890-video-64x64.webp"
    }
  },
  "metadata": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 100,
    "creationDate": "2024-01-15T10:30:00.000Z",
    "originalFilename": "video-1234567890.mp4"
  }
}
```

### Health Check

**GET** `/`

Returns API status and enabled services.

```json
{
  "success": true,
  "message": "Media Exporter Processor API",
  "version": "2.0.0",
  "services": {
    "auth": "enabled",
    "thumbnails": "enabled",
    "upload": "enabled",
    "processing": "enabled"
  }
}
```

## Development

### Project Structure

- **Services**: Business logic separated into focused services
- **Schemas**: Valibot schemas for type-safe validation
- **Utils**: Shared utilities for configuration and file handling
- **Clean Architecture**: Easy to test and maintain

### Key Technologies

- **Bun**: Fast JavaScript runtime with built-in S3 client (5x faster than AWS SDK)
- **Hono**: Lightweight web framework optimized for edge computing
- **Valibot**: Schema validation with excellent TypeScript integration
- **FFmpeg**: Video processing and thumbnail generation
- **ExifTool**: Video metadata manipulation

### Performance Features

- **Bun S3 Client**: Native S3 implementation, 5x faster than AWS SDK
- **Parallel Processing**: Thumbnails generated and uploaded concurrently
- **Quality Optimization**: Generate largest thumbnail first, then resize for quality
- **Memory Efficient**: Temporary files cleaned up automatically

## Deployment

The application is designed for serverless deployment and includes:

- Docker support
- SST (Serverless Stack) configuration
- Environment variable validation
- Error handling and logging

## License

MIT License