chatcup-local

<picture align="center"> <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg"> <img src="assets/logo.svg" width="120" alt="ChatCup Local"> </picture> <h1 align="center">ChatCup Local</h1> <p align="center"> <strong>AI-Powered Local Video Editing Server</strong><br> <em>Local-first MCP server that gives AI agents video editing superpowers — no cloud, no API keys, no monthly fees.</em> </p> <p align="center"> <a href="#"><img src="https://img.shields.io/badge/License-MIT-green?style=flat-square" alt="MIT License"></a> <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen?style=flat-square&logo=node.js" alt="Node.js"></a> <a href="https://ffmpeg.org/"><img src="https://img.shields.io/badge/FFmpeg-required-blue?style=flat-square&logo=ffmpeg" alt="FFmpeg"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Server-6C47FF?style=flat-square" alt="MCP"></a> <a href="https://github.com/Erkan9527/chatcup-local"><img src="https://img.shields.io/github/stars/Erkan9527/chatcup-local?style=social" alt="Stars"></a> </p> <p align="center"> <a href="README.zh-CN.md">中文</a> • <a href="#features">Features</a> • <a href="#quick-start">Quick Start</a> • <a href="#ai-agents">AI Agents</a> • <a href="#multimodal-models">Multimodal AI</a> • <a href="#tools">Tools</a> • <a href="#architecture">Architecture</a> </p> --- > **Edit video through natural language.** Ask any AI agent to "trim the first 5 seconds, add a caption overlay, and export as 1080p" — ChatCup Local handles it all locally on your machine. --- ## Features | Capability | Description | |------------|-------------| | 🎞️ **Timeline Editing** | Add, split, trim, and arrange clips with frame-level precision | | 🎨 **Overlay Compositing** | Multi-track overlays — charts, lower thirds, stickers, callouts, logos | | 🧠 **AI Captions** | Auto speech-to-text via Whisper + smart caption styling & SRT export | | 🤖 **Motion Graphics** | Dynamic JSX-based animations rendered locally via Remotion | | 📐 **Design Styles** | Apply branded presets — colors, fonts, layouts in one click | | 📝 **Script Editing** | Read & edit timeline scripts as Markdown from your AI agent | | 📤 **Multi-Format Export** | Video (H.264/H.265/VP9), audio, subtitles (SRT), XML project | | 🔐 **100% Private** | All processing on your machine — media never leaves your computer | | 🔌 **MCP Native** | Built on Model Context Protocol — works with any MCP-compatible AI agent | --- ## Quick Start ```bash git clone https://github.com/Erkan9527/chatcup-local.git cd chatcup-local npm install npm run build ``` **Prerequisites:** [Node.js](https://nodejs.org/) ≥ 20, [FFmpeg](https://ffmpeg.org/download.html). Optional: `whisper` CLI or `faster-whisper` for transcription. --- ## AI Agents ChatCup Local speaks **MCP (Model Context Protocol)** — the universal language for AI agents. Connect in seconds: ### OpenCode / Claude Code ```bash opencode mcp add chatcup-local -- node /path/to/chatcup-local/build/index.js claude mcp add chatcup-local -- node /path/to/chatcup-local/build/index.js ``` ### Cursor `Cursor Settings → MCP → New MCP Server`: ```json { "mcpServers": { "chatcup-local": { "command": "node", "args": ["/path/to/chatcup-local/build/index.js"] } } } ``` ### Codex / Copilot (`~/.codex/config.toml`) ```toml [mcp_servers.chatcup-local] command = "node" args = ["/path/to/chatcup-local/build/index.js"] ``` ### Pi Agent / WorkBuddy / Windsurf / Continue ```bash pi mcp add chatcup-local -- node /path/to/chatcup-local/build/index.js workbuddy mcp add chatcup-local -- node /path/to/chatcup-local/build/index.js ``` Any MCP-compatible client can also use the generic JSON config above. --- ## Multimodal Models ChatCup Local integrates with the **latest AI models (July 2026)**. Cloud models use your own API keys — zero vendor lock-in. ### Video Generation | Model | Maker | Status | Best For | |:---:|:---|:---:|:---| | **Veo 3.1** | <img src="https://upload.wikimedia.org/wikipedia/commons/d/d9/Google_Gemini_logo_2025.svg" height="28" alt="Google"> | ✅ Live | Native audio+video, 4K, best lip-sync | | **Gen-4.5** | <img src="https://upload.wikimedia.org/wikipedia/commons/1/1a/Runway_Logo.png" height="28" alt="Runway"> | ✅ Live | Production-grade, world consistency | | **Hailuo 2.3** | <img src="https://raw.githubusercontent.com/MiniMax-AI/MiniMax-01/main/figures/minimax.svg" height="28" alt="MiniMax"> | ✅ Live | Value leader, high motion quality | | **Kling 3.0** | Kuaishou | ✅ Live | Budget-friendly, long clips (up to 2 min) | | **FLUX 3** | Black Forest Labs | 🆕 EA | Unified image+video+audio model | | **Pika 2.5** | Pika | ✅ Live | Social-first creative effects | | **Luma Ray 3** | Luma AI | ✅ Live | HDR output, loopable clips | > **Open-source local options:** Wan 2.1 (Alibaba, Apache 2.0), Hunyuan Video (Tencent), LTX-Video (Lightricks), Mochi 1, CogVideoX — all run on consumer GPUs via ComfyUI. ### Frontier LLMs | Model | Maker | Multimodal | Context | Best For | |:---:|:---|:---:|:---:|:---| | **GPT-5.6 Sol** | <img src="https://upload.wikimedia.org/wikipedia/commons/9/97/OpenAI_logo_2025.svg" height="28" alt="OpenAI"> | ✅ Text+Image | 128K | Complex reasoning, scene planning, script gen | | **Claude Opus 4.8** | <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Claude_AI_logo.svg" height="28" alt="Anthropic"> | ✅ Text+Image | 1M | Code, long-doc, stable reasoning | | **Gemini 3.6 Flash** | <img src="https://upload.wikimedia.org/wikipedia/commons/d/d9/Google_Gemini_logo_2025.svg" height="28" alt="Google"> | ✅ **Native Video+Audio** | 1M | Upload raw video directly | | **DeepSeek V4 Pro** | <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" height="28" alt="DeepSeek"> | ❌ Text-only | 1M | Best coding value, open source (MIT) | | **Claude Fable 5** | <img src="https://upload.wikimedia.org/wikipedia/commons/8/8a/Claude_AI_logo.svg" height="28" alt="Anthropic"> | ✅ Text+Image | 1M | Most powerful Claude, agentic workflows | > **Key:** Only Gemini accepts **native video+audio** input. Claude & GPT accept frame-extracted images. ### Speech-to-Text | Model | Brand | WER | Price | Best For | |:---|:---|:---:|:---:|:---| | **GPT-4o Transcribe** | <img src="https://upload.wikimedia.org/wikipedia/commons/9/97/OpenAI_logo_2025.svg" height="28" alt="OpenAI"> | 4.1% | ~$0.006/min | High-accuracy batch transcription | | **Whisper large-v3-turbo** | <img src="https://upload.wikimedia.org/wikipedia/commons/9/97/OpenAI_logo_2025.svg" height="28" alt="OpenAI"> | ~5.3% | Free (self-host) | Local/offline transcription | | **ElevenLabs Scribe v2** | <img src="https://upload.wikimedia.org/wikipedia/commons/c/c7/ElevenLabs_Logo_03.svg" height="28" alt="ElevenLabs"> | 4.1% | $0.25/min | Real-time (150ms latency) | | **Whisper large-v3** | <img src="https://upload.wikimedia.org/wikipedia/commons/9/97/OpenAI_logo_2025.svg" height="28" alt="OpenAI"> | ~5.3% | Free (self-host) | Best accuracy, 98 languages | ### Image Generation | Model | Maker | Best For | |:---|:---|---:| | **FLUX.2 Pro** | Black Forest Labs | Best photorealism, 4MP output | | **Midjourney V8.1** | <img src="https://upload.wikimedia.org/wikipedia/commons/a/a7/Midjourney_Emblem_%28in-colour%29.svg" height="28" alt="Midjourney"> | Best artistic quality, 2K native | | **GPT Image 2** | <img src="https://upload.wikimedia.org/wikipedia/commons/9/97/OpenAI_logo_2025.svg" height="28" alt="OpenAI"> | Best text-in-image, successor to DALL-E 3 | ### Audio Generation | Model | Maker | Best For | |:---|:---|---:| | **Veo 3.1** (native audio) | <img src="https://upload.wikimedia.org/wikipedia/commons/d/d9/Google_Gemini_logo_2025.svg" height="28" alt="Google"> | Sync audio+video generation | | **ElevenLabs** | <img src="https://upload.wikimedia.org/wikipedia/commons/c/c7/ElevenLabs_Logo_03.svg" height="28" alt="ElevenLabs"> | Voiceovers, dubbing, TTS | | **FLUX 3** (native audio) | Black Forest Labs | Unified audio+video | ### Multimodal Workflow Example ``` 1. Claude writes a script → ChatCup imports it as a timeline 2. MiniMax Hailuo generates footage → AI video from text prompts 3. Whisper transcribes voiceover → GPT corrects captions 4. All assets composited → Exported locally in 1080p ``` --- ## Tools | Category | Tools | |----------|-------| | **Project** | `list_projects`, `create_project`, `target_project`, `delete_project`, `read_project` | | **Media** | `import_media`, `list_assets`, `get_asset`, `view_asset_frames` | | **Timeline** | `edit_item`, `split_item`, `manage_timelines`, `read_timeline`, `read_script`, `apply_script` | | **Tracks** | `manage_tracks`, `edit_track`, `multicam_sync` | | **Overlays** | `create_overlay_asset`, `insert_overlay`, `manage_design_style` | | **Motion Graphics** | `create_motion_graphic_from_code`, `edit_asset` | | **Captions** | `read_asr_provider`, `get_transcript`, `read_captions`, `edit_captions`, `manage_transcript` | | **Export** | `submit_export`, `track_export` | | **Utility** | `search_fonts`, `get_editor_url` | **40+ MCP tools** — see full docs in `src/tools/`. --- ## Architecture ```mermaid graph TB subgraph "AI Agent Layer" A[OpenCode] -->|MCP| H B[Claude Code] -->|MCP| H C[Cursor] -->|MCP| H D[Codex / Copilot] -->|MCP| H E[Pi Agent / WorkBuddy] -->|MCP| H end H["MCP JSON-RPC (stdio)"] subgraph "ChatCup Local Server" S[chatcup-local] --> PM[Project Manager] S --> MI[Media Importer / FFprobe] S --> TE[Timeline Engine] S --> OC[Overlay Compositor] S --> MG[Motion Graphics / Remotion] S --> TX[Transcription / Whisper] S --> EX[FFmpeg Exporter] PM --> DB[(JSON DB)] MI --> FS[(Media Store)] end subgraph "Local Storage" DB[~/.chatcup-local/db.json] FS[~/.chatcup-local/media/] EX --> OUT[~/.chatcup-local/exports/] end style A fill:#6C47FF,color:#fff style B fill:#6C47FF,color:#fff style C fill:#6C47FF,color:#fff style E fill:#6C47FF,color:#fff style S fill:#E84393,color:#fff style H fill:#333,color:#fff ``` --- ## Data Storage ``` ~/.chatcup-local/ ├── db.json # Projects, timelines, items, assets ├── media/ # Imported source files └── exports/ # Rendered output ``` --- ## Transcription Setup ```bash export LOCAL_ASR_PROVIDER=auto # auto | whisper-cli | faster-whisper | custom-command export LOCAL_ASR_MODEL=medium # tiny | base | small | medium | large export LOCAL_ASR_COMMAND='python3 /path/to/adapter.py --input {input} --language {language}' ``` --- ## Roadmap - [x] MCP server skeleton & project CRUD - [x] Media import with FFprobe analysis - [x] Timeline editing with frame precision - [x] Whisper transcription integration - [x] Motion-graphic rendering (Remotion) - [x] FFmpeg export (video/audio/subtitles/XML) - [x] Multi-track overlay workflow - [x] Caption styling & SRT export - [ ] **AI-assisted smart editing** — scene detection, auto-cuts, intelligent trimming - [ ] **Plugin system** — custom AI model integrations (bring your own model) - [ ] **Web-based preview panel** — real-time timeline preview in the browser - [ ] **Batch processing & export queuing** — multi-job render management --- ## Contributing 1. Fork the repo 2. Create your feature branch: `git checkout -b feature/amazing-feature` 3. Commit: `git commit -m 'feat: add amazing feature'` 4. Push: `git push origin feature/amazing-feature` 5. Open a Pull Request --- ## License MIT © [@Erkan9527](https://github.com/Erkan9527). See [LICENSE](LICENSE). ---