winnerads-ai-editor

Terminal-native AI kurgucu. Bir senaryo verirsin, AI editör konuşarak preset'leri doğrular, belirsizlikleri sorar, medyaları indirir, Türkçe transkripsiyon yapar (Deepgram + WhisperX fallback), word-level karaoke altyazılı render eder, kullanıcının onayını alır ve mevcut scenario_outputs flow'una yükler.

v0.2 — Yeni özellikler:

• 🧠 Tam senaryo context: LLM'e manager_notes, kurgu_last_revision_note, description, hook, persona/awareness, önceki output'lar, review notları — hepsi tek mesajda.
• 🔀 Multi-cut step: Bir step'te birden çok aralık (note: "00:03-05, 00:09-11, 00:22-23") → pipeline otomatik concat.
• 🤖 Smart parse: parse_step_cuts note'taki zaman ifadelerini ("ilk 2 sn", "son 3 sn") deterministik parse eder, belirsizliklerde kullanıcıya doğrulatır.
• 🎯 Framing: framing_reels / framing_post (scale/offset/fitMode) → pipeline web UI ile aynı kadrajı üretir.
• 🔍 Gemini Vision (opsiyonel): yabancı marka, İngilizce yazı, burned altyazı, watermark tespiti + blur/drawbox/custom-text censor planı. Ürün bilinçli filtreleme — kendi ürününün yazılarını atlar.
• 🪄 Atomic re-render: --only subtitles|audio|concat flag'i ile sadece değişen kısmı yeniden render et (~5 sn vs 60 sn).
• 📝 Censor alanları: stepCensors[] — blur, black, brand (marka rengi kutusu), custom_text (alana kendi yazını koy).

Kurulum (tek komut)

macOS / Linux:

curl -fsSL https://www.winnerads.ai/install.sh | bash

Windows (PowerShell):

irm https://www.winnerads.ai/install.ps1 | iex

Bu komut:

1. Node.js 20 LTS kurar (yoksa)
2. ffmpeg kurar (yoksa)
3. Claude Code kurar (yoksa)
4. winnerads-ai-editor paketini kurar — postinstall otomatik:
   • Skill'i ~/.claude/skills/render-scenario/'a kopyalar
   • MCP'yi ~/.claude.json'a kaydeder
   • Shell'e render alias'ı ekler (zsh / bash / PowerShell)

İlk açılış

# Yeni terminal aç
claude login                       # Anthropic OAuth (Claude Max kapsamında)
render <senaryo-id>                # veya: claude "render senaryo <id>"

İlk komut sana sırayla:

• Telefon + şifre (videosystem hesabı)
• AI editör için bir isim (örn: "Zeynep")

sorar — token cache'lenir, bir hafta geçerli.

Günlük kullanım

render s542                                # tek senaryo
render https://winnerads.ai/senaryo/<id>   # URL ile
claude "tüm bekleyen senaryolarımı render et"   # toplu mod

Tool envanteri (MCP)

| Tool | Ne yapar | |---|---| | editor_login / editor_logout / editor_whoami / editor_set_name | Auth & profil | | list_my_scenarios / list_pending_scenarios | Senaryo listesi (due/priority/revize notu öne çıkarılır) | | get_scenario | TAM context — brief, revize, persona, awareness, varyasyonlar, önceki output'lar, notlar | | get_scenario_notes | Review notları (critical/important/suggestion, only_unresolved filter) | | get_scenario_outputs | Önceki render sürümleri + next version hesabı | | get_variation_siblings | Kardeş varyasyonların tam detayı (aynı ses paylaşımı tespit) | | parse_step_cuts | Note'taki zaman ifadelerini parse et, multi-cut destek, belirsizlik uyarısı | | analyze_scenario | Belirsizlik raporu | | get_file_metadata / download_file | Medya | | transcribe_file | Deepgram (fallback: WhisperX) | | analyze_step_visuals | Gemini Vision — overlay / marka / burned subtitle tespiti (opsiyonel, API key gerekir) | | get_preferences / update_preferences / reset_preferences | Render preset'leri | | upload_render_output | Mevcut editör flow'una yükle |

Gemini Vision (opsiyonel)

Step videolardaki yabancı marka, İngilizce yazı, burned altyazı, watermark tespiti için. Tamamen opsiyonel — skill kullanıcıya sorar, evet ise çalışır.

Ücretsiz key: https://aistudio.google.com/apikey

Setup:

# Setup wizard'da adım 4 seni yönlendirir, veya manuel:
echo "GEMINI_API_KEY=AIza..." >> ~/.config/winnerads/.env
chmod 600 ~/.config/winnerads/.env

Maliyet koruması:

• Default kapalı — kullanıcı istedikçe çalışır
• Sadece step'in cut aralığı upload edilir (full video değil)
• Multi-cut step için sadece ilk alt-kesim taranır
• ~$0.01-0.05 / step (gemini-2.5-flash, saniyeler kadar clip)

Ürün bilinci: product_name + product_brand tool'a geçirilir. Kendi ürününün yazıları otomatik "bizim ürün" olarak işaretlenir — censor önerilmez. Sadece gerçekten ilgisiz overlay'ler aday olur.

Mimari

┌─────────────────────────────────────────────────┐
│ Kullanıcı terminali                              │
│  $ render s542                                   │
│      ↓                                           │
│  Claude Code (LLM)                               │
│      ↓ (tool call: analyze_scenario)             │
│  winnerads-ai-editor (stdio)                │
│      ↓ (HTTP)                                    │
│  videosystem backend (Cloud Run)                 │
│      ↓ (PG / R2 / Deepgram / WhisperX)          │
│  Veri katmanı                                    │
│                                                  │
│  Render: lokal ffmpeg (~/.claude/skills/...)     │
│  Output: backend → R2 + scenario_outputs satırı  │
└─────────────────────────────────────────────────┘

Güvenlik

• DB'ye direkt erişim yok — her şey backend üzerinden
• Şifre cache'lenmez (sadece tool argümanı)
• JWT cache: ~/.config/winnerads/token.json (chmod 600 POSIX)
• 15 dk access token, 30 gün refresh
• Backend yetki kontrolünü enforce eder (assigned_to / variation group)

Geliştirici

git clone <repo>
cd videosystem/ai-editor-mcp
npm install
npm run typecheck
npm run build

# Yerel test
node dist/index.js   # stdio mode (Claude Code'a manuel attach)

Yapı

ai-editor-mcp/
├── src/
│   ├── index.ts                MCP entry, stdio transport
│   ├── lib/
│   │   ├── config.ts           env, paths, retry policy
│   │   ├── logger.ts           stderr structured logger
│   │   ├── errors.ts           EditorError taxonomy + Turkish messages
│   │   ├── storage.ts          token/profile/preferences (atomic write)
│   │   └── api-client.ts       HTTP client (auto-refresh + retry + backoff)
│   ├── tools/
│   │   ├── auth.ts             editor_login, editor_logout, editor_whoami, editor_set_name
│   │   ├── scenarios.ts        list_my_scenarios, get_scenario, list_pending_scenarios
│   │   ├── media.ts            get_file_metadata, download_file
│   │   ├── transcribe.ts       transcribe_file, analyze_scenario
│   │   ├── output-upload.ts    upload_render_output
│   │   └── preferences.ts      get/update/reset_preferences
│   └── types/
│       └── backend.ts          backend response shapes
├── skill/
│   ├── SKILL.md                Claude Code skill spec
│   ├── REFERENCE.md            DB şema referansı (AI bilgisi)
│   ├── scripts/
│   │   └── render-pipeline.mjs render orkestrasyonu (FFmpeg + ASS)
│   └── examples/
│       └── config-schema.json
├── scripts/
│   └── postinstall.mjs         skill copy + MCP register + alias
└── install/
    ├── install.sh              macOS/Linux one-shot
    └── install.ps1             Windows one-shot

Backend bağımlılıkları

Bu MCP, backend'de aşağıdaki endpoint'leri çağırır:

• POST /api/auth/login, /refresh, GET /api/auth/me
• GET /api/scenarios, GET /api/scenarios/:id
• GET /api/files/:id, GET /api/files/:id/signed-url
• POST /api/upload/r2-presigned, POST /api/upload/r2-complete
• POST /api/scenarios/:id/outputs
• POST /api/ai-editor/transcribe-file (yeni — ai-editor.ts route)
• POST /api/ai-editor/llm-analyze (yeni — ai-editor.ts route)

Env değişkenleri

Birincil konum: ~/.config/winnerads/.env (MCP auto-load, chmod 600). Env değişkenleri her zaman override eder.

| Var | Default | Anlam | |---|---|---| | AI_EDITOR_API_BASE | Production URL | Backend base URL (staging için override) | | AI_EDITOR_CONFIG_DIR | ~/.config/winnerads | Token + profil + cache lokasyonu | | AI_EDITOR_LOG_LEVEL | info | debug / info / warn / error | | GEMINI_API_KEY | — | Gemini Vision overlay tespiti (opsiyonel) | | GEMINI_MODEL | gemini-2.5-flash | Vision modeli (gemini-flash-lite-latest daha ucuz) |

Backend tarafı: | Var | Anlam | |---|---| | DEEPGRAM_API_KEY | Deepgram Nova-3 key (DB system_settings.deepgram_api_key da olabilir) | | REPLICATE_API_TOKEN | WhisperX fallback için |

Sorun giderme

"command not found: render" Yeni terminal aç (alias profile dosyasına yazılmış, mevcut shell'e yüklenmedi).

"Telefon veya şifre hatalı" Backend formatı +90 olmadan, sadece rakam: 5xxxxxxxxx.

"ffmpeg not found on PATH" Mac: brew install ffmpeg. Win: winget install Gyan.FFmpeg.

"Transcription failed" DEEPGRAM_API_KEY veya REPLICATE_API_TOKEN backend'de tanımlı mı?

Daha derin debug

AI_EDITOR_LOG_LEVEL=debug claude "render senaryo s542"

Stderr'a structured JSON loglar düşer.

Lisans

UNLICENSED — internal use only.