README.md

metadata

title: SWARA - AI Public Speaking Evaluation
emoji: 🎤
colorFrom: blue
colorTo: purple
sdk: docker
app_port: 7860

🎤 SWARA API - AI-Powered Public Speaking Evaluation

API backend untuk sistem evaluasi public speaking berbasis AI.

📋 Fitur

• ✅ Async Video Processing - Non-blocking video analysis dengan RQ (Redis Queue)
• ✅ Multi-Model AI - Eye tracking, facial expression, gesture detection
• ✅ Level-based Evaluation - 5 level kesulitan dengan indikator berbeda
• ✅ RESTful API - FastAPI dengan OpenAPI documentation
• ✅ Cloud Redis - Upstash Redis untuk production
• ✅ Progress Tracking - Real-time progress updates untuk analysis

🏗️ Arsitektur

┌─────────────────────────────────────────┐
│         Docker Container                │
│                                         │
│  ┌──────────────┐    ┌──────────────┐  │
│  │   FastAPI    │───▶│    Redis     │  │
│  │ (Port 7860)  │    │ (Queue & KV) │  │
│  └──────────────┘    └──────────────┘  │
│         │                    │          │
│         │ POST /analyze      │          │
│         │ return task_id     │          │
│         │                    ▼          │
│         │           ┌──────────────┐   │
│         │           │  RQ Worker   │   │
│         │           │ (Background) │   │
│         │           └──────────────┘   │
│         │                    │          │
│         │ GET /task/{id}     │          │
│         │◀───────────────────┘          │
└─────────────────────────────────────────┘

🚀 Quick Start

Prerequisites

• Docker & Docker Compose
• Python 3.10+ (untuk development tanpa Docker)

1. Clone & Setup

# Clone repository (if applicable)
cd API-MODEL

# Copy environment file
cp .env.example .env

# Edit .env jika perlu (optional untuk local development)

2. Run dengan Docker Compose

# Build dan start semua services
docker-compose up --build

# Atau run di background
docker-compose up -d --build

# Lihat logs
docker-compose logs -f

# Stop services
docker-compose down

API akan tersedia di: http://localhost:7860

3. Akses Documentation

• Swagger UI: http://localhost:7860/docs
• ReDoc: http://localhost:7860/redoc
• OpenAPI JSON: http://localhost:7860/openapi.json

📖 API Endpoints

1. Health Check

GET /health

Response:

{
  "status": "healthy",
  "version": "1.0.0",
  "redis_connected": true,
  "timestamp": "2025-11-10T10:00:00"
}

2. Upload Video untuk Analysis

POST /api/v1/analyze
Content-Type: multipart/form-data

Parameters:

• video (file): Video file (max 50MB, max 1 minute)
• level (int): Level 1-5
• user_id (string, optional): User identifier

Response:

{
  "task_id": "abc123def456",
  "status": "pending",
  "message": "Video uploaded successfully. Processing has been queued.",
  "created_at": "2025-11-10T10:00:00"
}

3. Get Task Status

GET /api/v1/task/{task_id}

Response (Processing):

{
  "task_id": "abc123def456",
  "status": "processing",
  "progress": {
    "current_step": "processing",
    "percentage": 45.5,
    "message": "Analyzing facial expressions..."
  },
  "created_at": "2025-11-10T10:00:00"
}

Response (Completed):

{
  "task_id": "abc123def456",
  "status": "completed",
  "result": {
    "level": 2,
    "video_metadata": {
      "duration": 58.5,
      "fps": 30,
      "resolution": "1920x1080",
      "file_size": 15728640
    },
    "main_indicators": {
      "kontak_mata": {
        "score": 4,
        "raw_data": {...}
      }
    },
    "bonus_indicators": {
      "first_impression": {
        "detected": true,
        "raw_data": {...}
      },
      "face_expression": {...},
      "gesture": {...}
    },
    "processing_time": 42.3
  },
  "created_at": "2025-11-10T10:00:00",
  "completed_at": "2025-11-10T10:01:00"
}

4. Delete Task

DELETE /api/v1/task/{task_id}

🧪 Testing dengan cURL

Upload Video

curl -X POST "http://localhost:7860/api/v1/analyze" `
  -F "video=@test_video.mp4" `
  -F "level=2" `
  -F "user_id=user123"

Check Status

curl "http://localhost:7860/api/v1/task/abc123def456"

🛠️ Development Setup (Tanpa Docker)

1. Install Dependencies

# Create virtual environment
python -m venv venv
.\venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

2. Setup Redis (Local atau Upstash)

Option A: Local Redis (dengan Docker)

docker run -d -p 6379:6379 redis:7-alpine

Option B: Upstash Redis (Gratis)

1. Daftar di https://upstash.com
2. Create Redis database
3. Copy connection string ke .env:

REDIS_URL=redis://default:YOUR_PASSWORD@YOUR_ENDPOINT:6379

3. Run API Server

python -m app.main

4. Run Worker (Terminal terpisah)

python -m app.worker

📁 Project Structure

API-MODEL/
├── app/
│   ├── __init__.py
│   ├── main.py              # FastAPI app
│   ├── config.py            # Configuration
│   ├── models.py            # Pydantic models
│   ├── tasks.py             # Background tasks
│   ├── worker.py            # RQ worker
│   ├── api/
│   │   ├── routes.py        # API endpoints
│   ├── core/
│   │   ├── redis_client.py  # Redis connection
│   │   └── storage.py       # File storage
│   └── services/
│       ├── video_processor.py    # Main orchestrator
│       ├── eye_tracking.py       # Eye tracking service
│       ├── facial_expression.py  # Facial expression service
│       └── gesture_detection.py  # Gesture detection service
├── models/                  # AI model files
├── temp/                    # Temporary video storage
├── logs/                    # Application logs
├── docker-compose.yml
├── Dockerfile
├── requirements.txt
└── README.md

⚙️ Configuration

Edit .env file untuk konfigurasi:

# Environment
ENV=development

# Redis (Upstash atau local)
REDIS_URL=redis://localhost:6379

# API
API_HOST=0.0.0.0
API_PORT=7860

# Processing
MAX_VIDEO_SIZE_MB=50
MAX_VIDEO_DURATION_SECONDS=60
TASK_TIMEOUT_SECONDS=300

# Logging
LOG_LEVEL=INFO

📊 Monitoring

View Logs

# API logs
docker-compose logs -f api

# Worker logs
docker-compose logs -f worker

# Redis logs
docker-compose logs -f redis

# All logs
docker-compose logs -f

Check Redis Queue

# Connect to Redis container
docker exec -it swara-redis redis-cli

# Check queue length
LLEN swara:tasks

# View all keys
KEYS *

# Get task data
GET task:abc123def456

🔧 Troubleshooting

Problem: Redis connection failed

Solution:

# Check Redis is running
docker-compose ps

# Restart Redis
docker-compose restart redis

# Check Redis logs
docker-compose logs redis

Problem: Worker not processing tasks

Solution:

# Check worker logs
docker-compose logs worker

# Restart worker
docker-compose restart worker

# Check if worker is running
docker-compose ps worker

Problem: Video file too large

Solution:

• Compress video atau gunakan format yang lebih efisien
• Increase MAX_VIDEO_SIZE_MB di .env

📝 Next Steps (TODO)

Untuk complete implementation, Anda perlu:

1. Refactor existing code ke services:

   • app/services/eye_tracking.py - dari eye_tracking_production.py
   • app/services/facial_expression.py - dari facial_expression.py
   • app/services/gesture_detection.py - dari gesture_detection.py

2. Add audio processing:

   • app/services/audio_processor.py - untuk tempo, artikulasi, jeda
   • Speech-to-text integration
   • Kata pengisi & kata tidak senonoh detection

3. Add NLP processing:

   • app/services/nlp_processor.py - untuk kesesuaian topik, struktur kalimat
   • Topic matching
   • Sentence structure analysis

4. Optimization:

   • Implement frame sampling (5 fps instead of 30 fps)
   • Model loading optimization
   • Memory management

5. Testing:

   • Unit tests
   • Integration tests
   • Load testing

🚢 Deployment ke HuggingFace Spaces

1. Create Space

1. Go to https://huggingface.co/spaces
2. Create new Space (Docker type)
3. Clone repository

2. Prepare Files

# Add Dockerfile for HF Spaces
# (sudah ada di repository)

3. Setup Secrets

Di HuggingFace Space settings, add secrets:

• REDIS_URL - Upstash Redis URL
• ENV - production

4. Push & Deploy

git push origin main

HuggingFace akan auto-deploy!

📞 Support

Untuk pertanyaan atau issues, contact SWARA team.

---

Built with ❤️ by SWARA Team for LIDM Competition 2025