Video Analysis Worker

AI-powered video analysis service with frame extraction, object detection, and scene understanding.

Quick Start

# 1. Install dependencies
pnpm install

# 2. Configure environment
cp .env.example .env
# Add required API keys:
#   - OPENAI_API_KEY or Azure OpenAI credentials
#   - DEEPGRAM_API_KEY (optional for transcription)

# 3. Start development server
npm run dev

# 4. Run quick test (10 frames)
npx tsx scripts/test-quick-10-frames.ts

Service URLs

• Production: https://video-analysis-worker-628338757341.us-central1.run.app
• Local: http://localhost:8081

Key Features

• Frame Extraction: Smart FFmpeg-based frame selection
• AI Analysis: GPT-4 Vision for scene understanding
• Object Detection: Computer vision object recognition
• Audio Transcription: Deepgram speech-to-text
• Real-time Updates: SSE streaming for progress tracking
• Rate Limiting: Redis-backed multi-instance safe limits
• Auto-scaling: Cloud Run 0→100 instances

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /health | GET | Health check (no auth) | | /api/v1/jobs | POST | Create analysis job | | /api/v1/jobs | GET | List user's jobs | | /api/v1/jobs/:id | GET | Get job status/results | | /api/v1/jobs/:id/stream | GET | SSE real-time updates | | /api/v1/jobs/:id | DELETE | Cancel pending job |

Create Job Example

curl -X POST https://video-analysis-worker.../api/v1/jobs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "videoUrl": "https://example.com/video.mp4",
    "options": {
      "frameInterval": 1,
      "maxFrames": 60,
      "frameQuality": "high"
    }
  }'

Environment Variables

# Required
OPENAI_API_KEY=sk-...           # Or Azure OpenAI config
PROJECT_ID=shotrush-v1
STORAGE_BUCKET_NAME=shotrush-v1.firebasestorage.app

# Production Redis
REDIS_HOST=10.110.0.3
REDIS_PORT=6379
REDIS_TLS=false

# Optional
DEEPGRAM_API_KEY=...            # Audio transcription
WORKER_URL=https://...           # Cloud Run URL

Documentation

• Architecture - System design, components, diagrams
• Deployment - Production setup, Cloud Run, Redis
• Testing - Test commands, validation

Technology Stack

| Component | Technology | |-----------|------------| | Runtime | Node.js 20 + TypeScript | | Framework | Express.js | | Database | Firestore | | Cache | Redis (Cloud Memorystore) | | Storage | Cloud Storage | | Queue | Cloud Tasks | | Deployment | Cloud Run | | Video | FFmpeg | | AI | OpenAI GPT-4 Vision |

Cost Estimates

Per 60-second video:

• Cloud Run: ~$0.0015 (2 min @ 2 vCPU, 4GB)
• AI Analysis: ~$0.27 (36 frames @ $0.0075/frame)
• Storage: ~$0.0005
• Total: ~$0.27/video

Monthly infrastructure:

• Cloud Run: ~$100 (avg 10 instances)
• Redis: ~$50 (1GB Memorystore)
• Firestore: ~$15 (1M reads, 500K writes)
• Total: ~$165/month + API costs

Development

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint

# Type check
npm run type-check

Deployment

# Deploy to Cloud Run (with Redis)
gcloud run deploy video-analysis-worker \
  --source . \
  --region=us-central1 \
  --vpc-egress=private-ranges-only \
  --network=default \
  --set-env-vars="REDIS_HOST=10.110.0.3,REDIS_PORT=6379" \
  --memory=4Gi \
  --cpu=2 \
  --timeout=3600

Monitoring

# View logs
gcloud run services logs read video-analysis-worker --region=us-central1

# Check Redis metrics
gcloud redis instances describe video-worker-redis --region=us-central1

Project Status

✅ Production Ready - v1.0.0

• API authentication with rate limiting
• SSE streaming for real-time updates
• Redis-backed rate limiting (Cloud Memorystore)
• Cloud Run deployment with auto-scaling
• Comprehensive testing suite

Last Updated: 2025-11-19