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 runtime
• ffmpeg for thumbnail generation
• exiftool for video metadata
• Cloudflare R2 or AWS S3 bucket

Install Dependencies (macOS)

# 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)

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

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

2. Set up environment variables:

Create a .env file with the following variables:

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

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:

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:

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:

{
  "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.

{
  "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