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.

Related MCP server: VE-MCP

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

Panduan Instalasi Cepat

1. Pasang dependensi Python

Buka terminal di folder proyek ini lalu jalankan:

pip install -r requirements.txt

2. Atur API Key

Salin file contoh konfigurasi dan isi API key Gemini Anda:

cp .env.example .env

Buka file .env dan masukkan key:

GEMINI_API_KEY=AIzaSyD-xxxxxxxxxxxxxx

3. Buka Control Center & Siapkan FFmpeg

Jalankan antarmuka desktop:

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)

{
  "mcpServers": {
    "video-reframer": {
      "command": "python",
      "args": ["D:/Lucky/NgodingCuy/python-clipper-mcp/server.py"],
      "env": {
        "GEMINI_API_KEY": "AIzaSyD-xxxxxxxxxxxxxx"
      }
    }
  }
}

Cursor (~/.cursor/mcp.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)

{
  "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:

python tests/test_server.py