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

```powershell
# 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

```powershell
# 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

```bash
GET /health
```

**Response:**

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

### 2. Upload Video untuk Analysis

```bash
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:**

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

### 3. Get Task Status

```bash
GET /api/v1/task/{task_id}
```

**Response (Processing):**

```json
{
  "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):**

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

```bash
DELETE /api/v1/task/{task_id}
```

## 🧪 Testing dengan cURL

### Upload Video

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

### Check Status

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

## 🛠️ Development Setup (Tanpa Docker)

### 1. Install Dependencies

```powershell
# 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)**

```powershell
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

```powershell
python -m app.main
```

### 4. Run Worker (Terminal terpisah)

```powershell
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:

```env
# 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

```powershell
# 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

```powershell
# 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:**

```powershell
# 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:**

```powershell
# 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

```bash
# 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

```bash
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**