# Product Requirement Document (PRD)
## AI Long-to-Short Video Clipper Web Platform

---

## 1. Executive Summary & Problem Statement

### 1.1 Background & Objective
Pertumbuhan konsumsi video format pendek (Short-form video: TikTok, Instagram Reels, YouTube Shorts) menuntut kreator konten, podcaster, agensi periklanan, dan affiliate marketer untuk secara rutin memotong video panjang (podcast, webinar, livestream, talkshow) menjadi klip pendek 9:16 vertikal yang menarik perhatian (*hook-driven*).

Layanan SaaS komersial yang ada di pasar (*OpusClip, Klap, Submagic, Munch, Dumme*):
1. Membebankan biaya langganan berulang yang mahal ($30 - $150+/bulan).
2. Membatasi kuota menit pemrosesan (*credit usage limit*).
3. Memberikan keterbatasan kontrol privasi atas aset video mentah internal.

**Tujuan Proyek**: Membangun aplikasi web *self-hosted / on-premise cloud* open-source untuk konversi video format panjang menjadi video pendek vertikal bertenaga AI secara otomatis, cepat, hemat biaya (hanya bayar konsumsi GPU/API compute), tanpa batas menit bulanan.

---

## 2. Target Persona & Use Cases

| Persona | Kebutuhan Utama | Nilai Tambah Platform |
| :--- | :--- | :--- |
| **Podcast Creator & Studio** | Ekstraksi 5-10 highlight per episode 60 menit. | Deteksi multi-speaker, auto-crop active speaker, export massal. |
| **Affiliate Marketer / Clipper** | Membuat ratusan konten potongan produk/edukasi harian. | Fast batch processing, subtitle auto-highlight, no watermark. |
| **Agensi Media Digital** | Produksi konten klien volume tinggi. | White-label, multi-format export, custom preset branding/font. |
| **Educator / Webinar Host** | Memecah rekaman webinar jadi rangkuman materi ringkas. | Auto TL;DR hook detection, visual slides reframing. |

---

## 3. Core Functional Requirements

```
┌─────────────────┐     ┌───────────────────────┐     ┌──────────────────────┐
│ 1. Video Source │ ──> │ 2. Audio & STT Engine │ ──> │ 3. AI Hook Detection │
│ (Upload / Link) │     │ (Whisper + PyAnnote)  │     │ (LLM Scoring 0-100)  │
└─────────────────┘     └───────────────────────┘     └──────────────────────┘
                                                                 │
                                                                 ▼
┌─────────────────┐     ┌───────────────────────┐     ┌──────────────────────┐
│ 6. Fast Render  │ <── │ 5. Dynamic Subtitles  │ <── │ 4. Smart Re-framing  │
│ (FFmpeg Export) │     │ (Karaoke ASS/WebGL)   │     │ (Face / Split-Screen)│
└─────────────────┘     └───────────────────────┘     └──────────────────────┘
```

### 3.1 Ingestion & Pre-processing (Phase 1)
- **Sumber Input**:
  - Direct File Upload: MP4, MKV, MOV, WEBM (Ukuran maks: 2GB per berkas).
  - Web URL Scraper: YouTube, Google Drive link via `yt-dlp`.
- **Pre-flight Validation**:
  - Pengecekan resolusi minimal (720p), framerate, dan audio track sanity check.
  - Ekstraksi audio mentah instan ke format WAV 16kHz mono via FFmpeg untuk konsumsi AI Speech-to-Text.

### 3.2 Speech-to-Text & Diarization Engine (Phase 2)
- **Word-Level Timestamping**:
  - Menggunakan engine `faster-whisper` (Model: `large-v3` atau `medium.en`/`medium.id` fallback) via CTranslate2.
  - Menyimpan setiap token kata dengan metadata: `{ word, start_sec, end_sec, probability }`.
- **Speaker Diarization**:
  - Integrasi `pyannote.audio` untuk melabeli ID pembicara (`Speaker 0`, `Speaker 1`, dst.) sepanjang timeline video.

### 3.3 AI Highlight & Viral Hook Detection (Phase 3)
- **Semantic Window Segmentation**:
  - Transkrip dipecah menjadi unit segmen wacana koheren berdurasi 30 - 90 detik.
- **LLM Evaluator (Gemini 3.5/3.6 Flash / Local Ollama / OpenAI API)**:
  - Menganalisis transkrip terhadap parameter viralitas:
    1. **Hook Strength (0 - 100)**: Seberapa kuat 3 detik pertama memikat perhatian penonton.
    2. **Stand-alone Value**: Kelengkapan ide/cerita tanpa butuh konteks luar klip.
    3. **Emotional Engagement**: Lucu, kontroversial, edukatif, atau menyentuh emosi.
  - **Output AI**: Judul pendek *clicky*, tagar rekomendasi, estimasi viral score, dan *exact start/end timestamp*.

### 3.4 Smart Face Tracking & Re-framing 9:16 (Phase 4)
- **Computer Vision Pipeline**:
  - Deteksi wajah dan orientasi kepala via `OpenCV` + `MediaPipe Face Mesh` / `YOLOv8-Face`.
  - Pelacakan koordinat *bounding box* wajah per frame dengan *smoothing Kalman Filter* (mencegah kamera bergoyang kaku / jittery).
- **Layout Modes**:
  1. **Single Speaker Mode**: Kamera memusatkan pembicara aktif di tengah frame 1080x1920.
  2. **Dual Speaker Split-Screen Mode**: Menumpuk kamera Pembicara A di panel atas dan Pembicara B di panel bawah secara simultan saat terjadi dialog intensif.
  3. **Screen Share / Presentation Mode**: Feed presentasi/slide di bagian atas (16:9), kamera presenter di bagian bawah (lingkaran / kotak 1:1).

### 3.5 Dynamic Karaoke Captions & Visual Styling (Phase 5)
- **Gaya Subtitle Animasi**:
  - Tipe *Alex Hormozi / MrBeast Style*: Highlight kata aktif per suku kata/kata dengan perubahan warna kontras (Kuning Neon `#FFE600`, Hijau Neon `#00FF66`, Cyan `#00F0FF`).
  - Animasi teks: Pop-in scale up, bounce, dan dynamic text wave.
  - Auto-Emoji Insertion: Deteksi kata kunci secara semantik (contoh: "uang" ➔ 💰, "ide" ➔ 💡, "target" ➔ 🎯).
- **Format Engine**:
  - Kompilasi berkas subtitle format `.ass` (Advanced SubStation Alpha) presisi milidetik.
  - Dukungan canvas real-time rendering di browser sebelum ekspor final.

### 3.6 Timeline Editor & Video Export (Phase 6)
- **Web Editor Interface**:
  - Pemutar video 9:16 interaktif dengan scrubber timeline.
  - *Text-based Video Trimming*: Mengedit kata dalam teks transkrip otomatis memotong timeline video.
  - *Audio Background Ducking*: Menambahkan musik latar (BGM) dengan auto-volume down saat pembicara bersuara.
- **Rendering & Encoding**:
  - Export ke MP4 H.264 / AAC dengan akselerasi hardware NVENC / QuickSync / VAAPI.
  - Preset resolusi: 1080x1920 (Full HD 9:16) pada 30fps / 60fps.

---

## 4. Technical Architecture

```
[ Frontend: React / Next.js 14 + Tailwind CSS + Lucide Icons ]
                            │
                            │ (REST API & WebSockets)
                            ▼
[ API Gateway & Backend: FastAPI (Python 3.11+) ]
                            │
                            ├──> [ PostgreSQL: Metadata, User, Clip Data ]
                            ├──> [ Redis: Task Queue & PubSub Event Broker ]
                            │
                            ▼
               [ Asynchronous Task Workers (Celery) ]
                            │
       ┌────────────────────┼────────────────────┐
       ▼                    ▼                    ▼
[ Ingestion & Audio ] [ Whisper & Diarization ] [ AI Brain (LLM) ]
(yt-dlp, FFmpeg)      (faster-whisper, pyannote) (Gemini API)
       │                    │                    │
       └────────────────────┬────────────────────┘
                            ▼
               [ CV & Video Compositor ]
               (OpenCV, MediaPipe, FFmpeg)
                            │
                            ▼
               [ Local Storage / MinIO S3 ]
```

---

## 5. Database Schema Specification

### 5.1 `users`
- `id` (UUID, Primary Key)
- `email` (VARCHAR 255, Unique, Indexed)
- `password_hash` (VARCHAR 255)
- `full_name` (VARCHAR 100)
- `role` (ENUM: `'admin'`, `'creator'`, `'viewer'`)
- `created_at` (TIMESTAMP WITH TIME ZONE)

### 5.2 `projects`
- `id` (UUID, Primary Key)
- `user_id` (UUID, Foreign Key -> `users.id`)
- `title` (VARCHAR 255)
- `source_type` (ENUM: `'file_upload'`, `'youtube_url'`, `'gdrive_url'`)
- `source_url` (TEXT, Nullable)
- `raw_video_path` (TEXT)
- `duration_seconds` (FLOAT)
- `status` (ENUM: `'queued'`, `'downloading'`, `'transcribing'`, `'analyzing'`, `'completed'`, `'failed'`)
- `error_message` (TEXT, Nullable)
- `created_at`, `updated_at` (TIMESTAMP)

### 5.3 `transcripts`
- `id` (UUID, Primary Key)
- `project_id` (UUID, Foreign Key -> `projects.id`, Indexed)
- `full_text` (TEXT)
- `words_json` (JSONB: array of `{ word, start, end, speaker_id, confidence }`)
- `speakers_json` (JSONB: metadata profil speaker)

### 5.4 `clips`
- `id` (UUID, Primary Key)
- `project_id` (UUID, Foreign Key -> `projects.id`, Indexed)
- `title` (VARCHAR 255)
- `summary` (TEXT)
- `viral_score` (INT)
- `hook_score` (INT)
- `start_time` (FLOAT)
- `end_time` (FLOAT)
- `crop_layout` (ENUM: `'single_speaker'`, `'split_screen'`, `'picture_in_picture'`, `'custom'`)
- `subtitle_style_id` (UUID, Nullable)
- `rendered_video_path` (TEXT, Nullable)
- `thumbnail_path` (TEXT, Nullable)
- `status` (ENUM: `'draft'`, `'rendering'`, `'ready'`, `'failed'`)
- `created_at` (TIMESTAMP)

### 5.5 `subtitle_styles`
- `id` (UUID, Primary Key)
- `name` (VARCHAR 100)
- `font_family` (VARCHAR 100, default `'Montserrat'`)
- `font_size` (INT, default `52`)
- `primary_color` (VARCHAR 10, default `'#FFFFFF'`)
- `highlight_color` (VARCHAR 10, default `'#FFE600'`)
- `stroke_color` (VARCHAR 10, default `'#000000'`)
- `stroke_width` (INT, default `6`)
- `animation_type` (ENUM: `'pop_word'`, `'karaoke_smooth'`, `'fade'`, `'static'`)
- `show_emoji` (BOOLEAN, default `true`)

---

## 6. Core REST API Endpoints

### 6.1 Project Management
- `POST /api/v1/projects/upload` — Upload berkas video langsung (multipart/form-data).
- `POST /api/v1/projects/url` — Ingest video dari URL YouTube/GDrive.
- `GET /api/v1/projects` — Mengambil daftar proyek aktif pengguna.
- `GET /api/v1/projects/{id}` — Detail proyek, status task pipeline & transkrip.
- `DELETE /api/v1/projects/{id}` — Menghapus proyek dan berkas media terkait.

### 6.2 AI Processing & Clips
- `POST /api/v1/projects/{id}/process-clips` — Menjalankan worker AI highlight generator.
- `GET /api/v1/projects/{id}/clips` — Mengambil seluruh klip rekomendasi AI beserta viral score.
- `PUT /api/v1/clips/{clip_id}` — Memperbarui start/end time, layout crop, atau gaya subtitle.
- `POST /api/v1/clips/{clip_id}/render` — Menjalankan tugas rendering FFmpeg final.
- `GET /api/v1/clips/{clip_id}/download` — Endpoint streaming/download berkas MP4 jadi.

### 6.3 Real-Time WebSocket Telemetry
- `WS /api/v1/ws/tasks/{project_id}` — Stream progres real-time per tahapan (Download: 100%, STT: 45%, AI Score: 80%, Rendering: 90%).

---

## 7. MVP Development Roadmap & Milestones

```
Sprint 1: Core Engine Pipeline (STT + LLM Hook)
Sprint 2: Face Detection & 9:16 Smart Auto-Framing
Sprint 3: Animated Karaoke Subtitle & FFmpeg Compositor
Sprint 4: Frontend Web Dashboard & Fast Video Player
Sprint 5: Production Hardening, NVENC Acceleration & Polish
```

### Milestone 1: Core Engine Pipeline (Sprint 1)
- Konfigurasi FastAPI, Celery, dan Redis.
- Modul `yt-dlp` download dan ekstraksi audio FFmpeg.
- Pipeline `faster-whisper` transkripsi timestamp per kata.
- Modul prompt engineering Gemini Flash untuk analisis dan scoring klip.

### Milestone 2: Computer Vision Auto-Crop (Sprint 2)
- Integrasi `MediaPipe Face Mesh` untuk deteksi wajah horizontal video.
- Algoritma smoothing kamera (anti goyang).
- Template cropping dinamis (Single speaker & Split-screen dual presenter).

### Milestone 3: Subtitle Generator & Renderer (Sprint 3)
- Pembuat berkas `.ass` otomatis dengan gaya highlight per kata.
- Engine auto-emoji tagging.
- Pipeline rendering FFmpeg dengan burn-in subtitle dan BGM audio ducking.

### Milestone 4: Modern Web UI & Video Editor (Sprint 4)
- Dashboard Next.js 14 / Tailwind UI bertema Cinema Dark Modern.
- Form upload & URL bar dengan live progress bar.
- Galeri klip AI dengan badge Viral Score (🥇 95, 🥈 88, 🥉 82).
- Video player 9:16 dengan live interactive subtitle preview.

---

## 8. Non-Functional & Security Requirements

1. **Efisiensi Sumber Daya**: Pemrosesan video 10 menit selesai di bawah 60 detik pada mesin berpemanas GPU CUDA atau < 180 detik pada multi-core CPU.
2. **Skalabilitas**: Celery worker terdistribusi memudahkan penambahan node GPU secara horizontal.
3. **Data Privacy**: Seluruh berkas video tersimpan di penyimpanan privat lokal/S3 internal pengguna tanpa dikirim ke server pihak ketiga selain API transkrip/LLM.
4. **Resilience & Auto-Retry**: Mekanisme retry otomatis 3x dengan *exponential backoff* pada kegagalan download stream atau API timeout.