# Video Reframer MCP: AI Video Clipper & Reframer 9:16

Aplikasi ini mengubah video horizontal YouTube (16:9) menjadi video vertikal (9:16) untuk TikTok, Reels, dan Shorts. Pemotongan kamera diproses otomatis berbasis pergantian scene (*Scene-Adaptive Dynamic Reframing*) dan deteksi wajah MediaPipe.

Proyek ini menyediakan dua antarmuka:
1. **Server MCP (Model Context Protocol)** yang bisa langsung dipanggil oleh AI Agent di Claude Desktop, Cursor, Antigravity, OpenCode, dan Windsurf.
2. **Desktop Control Center** berbasis NiceGUI untuk cek dependensi, unduh FFmpeg otomatis, dan pasang konfigurasi MCP dengan satu klik.

---

## Kemampuan Utama

- **Kurasi video YouTube (`curate_youtube_clips`)**: Menganalisis URL YouTube publik memakai model `gemini-3.8-flash` tanpa perlu mengunduh seluruh file video di awal. Menghasilkan rekomendasi klip dengan hook dan timestamp.
- **Unduh dan potong presisi (`fetch_and_trim_clip`)**: Hanya mengunduh rentang waktu yang dipilih menggunakan `yt-dlp` dan memisahkan file audio.
- **Deteksi shot kamera (`analyze_scene_composition`)**: Memotong klip tepat di pergantian sudut kamera memakai PySceneDetect ContentDetector, lalu menghitung posisi wajah dengan MediaPipe.
- **Layout 9:16 adaptif (`render_adaptive_video`)**:
  - 1 Wajah: Fullscreen 9:16 crop mengikuti pembicara.
  - 2 Wajah: Split screen atas-bawah (atau 1:1 jika duduk berdampingan).
  - 3+ Wajah: 1:1 di tengah dengan background ambient blur.
  - 0 Wajah / B-roll: 16:9 di tengah dengan background blur.
  - Audio tetap utuh tanpa desinkronisasi.
- **Dynamic CSS/JS animated captions (`render_dynamic_css_captions`)**:
  - Transkripsi kata via `gemini-3.5-transcribe`.
  - Pilihan preset animasi: `hormozi` (kuning tebal dengan pop-in), `mrbeast` (komik miring dengan bayangan kontras), `cyberpunk` (pulse neon), dan `minimal` (kapsul pill lembut).
  - Dirender menggunakan Headless Chrome/Edge lokal dan ditempelkan via FFmpeg pada area aman (`margin_v=380`).
- **Cover thumbnail 9:16 (`suggest_cover_hooks`, `render_short_cover`, `attach_cover_to_video`)**:
  - Menganalisis ekspresi wajah paling menarik dari frame asli.
  - Menghasilkan judul hook 2 tingkat (kata pemicu kuning + teks pendukung putih) di area dada/bawah agar tidak menutupi wajah.
  - Bisa digabungkan langsung ke 0.1 detik pertama video.

---

## Kebutuhan Sistem

- Python 3.10 atau lebih baru.
- Google Chrome atau Microsoft Edge (untuk render cover dan dynamic caption).
- FFmpeg (tersedia fitur download otomatis lewat aplikasi).
- API Key Google Gemini (gratis di [Google AI Studio](https://aistudio.google.com/apikey)).

---

## Panduan Instalasi Cepat

### 1. Pasang dependensi Python
Buka terminal di folder proyek ini lalu jalankan:

```bash
pip install -r requirements.txt
```

### 2. Atur API Key
Salin file contoh konfigurasi dan isi API key Gemini Anda:

```bash
cp .env.example .env
```

Buka file `.env` dan masukkan key:
```env
GEMINI_API_KEY=AIzaSyD-xxxxxxxxxxxxxx
```

### 3. Buka Control Center & Siapkan FFmpeg
Jalankan antarmuka desktop:

```bash
python ui.py
```

Pada antarmuka Control Center:
1. **Library Hasil Kerja**: Tonton langsung klip 9:16 hasil render dengan pemutar video web bawaan, periksa badge gaya subtitle (Hormozi, MrBeast, Cyberpunk, Minimalist), unduh klip, atau buka folder file di Windows Explorer dalam satu klik.
2. **Kesehatan Sistem & FFmpeg**: Klik tombol **Unduh & Pasang Otomatis** bila FFmpeg belum terpasang di komputer Anda. File `ffmpeg.exe` akan tersimpan di dalam folder `./bin/` lokal tanpa merusak PATH Windows.
3. **Integrasi MCP Multi-Agent**: Buka tab integrasi, lalu klik **Pasang Otomatis ke Semua yang Terdeteksi**. Konfigurasi MCP akan langsung disalin ke Claude Desktop, Cursor, Antigravity, atau OpenCode yang ada di komputer Anda.

---

## Menghubungkan MCP ke AI Agent Secara Manual

Jika Anda memilih memasukkan konfigurasi secara manual ke editor AI Anda, gunakan format berikut.

### Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "video-reframer": {
      "command": "python",
      "args": ["D:/Lucky/NgodingCuy/python-clipper-mcp/server.py"],
      "env": {
        "GEMINI_API_KEY": "AIzaSyD-xxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Cursor (`~/.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "video-reframer": {
      "command": "python",
      "args": ["D:/Lucky/NgodingCuy/python-clipper-mcp/server.py"],
      "env": {
        "GEMINI_API_KEY": "AIzaSyD-xxxxxxxxxxxxxx"
      }
    }
  }
}
```

### Google Antigravity (`~/.gemini/config/mcp_config.json`)
```json
{
  "mcpServers": {
    "video-reframer": {
      "command": "python",
      "args": ["D:/Lucky/NgodingCuy/python-clipper-mcp/server.py"],
      "env": {
        "GEMINI_API_KEY": "AIzaSyD-xxxxxxxxxxxxxx"
      }
    }
  }
}
```

*(Catatan: Ganti path `D:/Lucky/NgodingCuy/python-clipper-mcp/server.py` dengan lokasi folder tempat Anda meletakkan proyek ini).*

---

## Menggunakan Skill Bersama MCP

Proyek ini menyertakan folder `.agents/skills/` yang kompatibel dengan standar **Agent Skills**. Begitu folder repo ini dibuka di agent harness yang mendukung skills (seperti Antigravity, OpenCode, atau Claude Code), skill berikut akan aktif otomatis:

1. **`video-reframer-workflow`**: Prosedur utama untuk memproses video dari link YouTube sampai menjadi video 9:16 utuh.
2. **`video-caption-designer`**: Menangani penataan gaya animasi subtitle (Hormozi, MrBeast, Cyberpunk, Minimalist) melalui tool MCP `render_dynamic_css_captions`.
3. **`video-cover-designer`**: Membuat cover vertikal beresolusi 1080x1920 dengan safe zone wajah.
4. **`video-batch-automation`**: Menangani proses banyak video sekaligus secara otomatis setelah konfigurasi awal dijawab.

### Contoh Perintah ke AI Agent:
Setelah MCP dan skill aktif, Anda cukup mengetik instruksi di chat AI seperti biasa:

> *"Tolong ambil klip menarik dari video YouTube ini: https://www.youtube.com/watch?v=xxxx. Jadikan video vertikal 9:16, beri subtitle gaya hormozi, dan buatkan cover pembuka."*

AI Agent akan:
1. Memanggil `curate_youtube_clips` dan memberikan pilihan segmen terbaik.
2. Mengunduh segmen yang Anda setujui.
3. Mendeteksi shot kamera dan meminta persetujuan layout framing.
4. Merender video 9:16 dan menempelkan animasi caption sesuai preset pilihan Anda.
5. Menampilkan hasil audit retensi video.
6. Membuka Control Center secara otomatis (`open_control_center`) dan memberikan tautan: *"Kamu bisa melihat hasil kerja disini ya: http://127.0.0.1:8080"*.
7. Jika Anda ingin mencoba variasi gaya (misalnya *"coba ganti style subtitle jadi MrBeast"*), AI Agent langsung merender ulang versi baru dalam hitungan detik tanpa mengunduh ulang video dari awal!

---

## Menjalankan Pengujian

Untuk memastikan seluruh fungsi tool MCP dan sistem render berjalan baik:

```bash
python tests/test_server.py
```