# Flutter Video Üretim Stüdyosu — Tasarım Dokümanı

**Tarih:** 2026-04-28
**Durum:** Onaylandı
**Sahibi:** fikri007@gmail.com

## 1. Amaç

Mevcut `Muzik-Video-Uret.bat` + `muzik_video_uret.py` pipeline'ını, **her segmenti tam özelleştirilebilen profesyonel bir Flutter masaüstü uygulamasına** dönüştürmek. Mp3 + görsel girişiyle uzun müzik videoları üretmek, segmentler arası geçişleri/efektleri yönetmek, çoklu çıkış preset'leriyle export etmek.

## 2. Kapsam

**Vardır:**
- Per-segment tam parametre kontrolü (prompt, süre, model, çözünürlük, oran, CFG, steps, kamera, seed, ses on/off, ses override, görsel override, face swap, gruplama)
- Üç görünüm modu: Studio / Timeline / Storyboard (state paylaşımlı, runtime geçiş)
- Dört tema: Material 3 Dark, Fluent (Win11), Özel Fiko (glassmorphic), shadcn Minimal — kullanıcı seçer
- AI prompt asistanı 4 katman: ses enerjisi, Whisper transkript, Ollama LLM önerisi, beat detection
- Job orchestrator: kuyruk, paralelizasyon (multi-LTX-instance auto-detect), resume, tek segment yeniden üret, varyant geçmişi
- Profesyonel export: geçişler (xfade), ses karışım modları, loudnorm, renk düzeltme/LUT, watermark, altyazı (SRT/Whisper), intro/outro, hız rampası, beat-sync snap, çoklu preset (YouTube/Shorts/Square)
- Tray icon + arka plan render
- Tüm seçilen kaynak dosyalar proje/kaynak/'a hash'li kopyalanır

**Yoktur:**
- Cloud render fallback (Replicate/RunPod)
- Mobil/web platform (Windows-first masaüstü)
- Mevcut Python script'in tam kaldırılması (sadece WanGP InfiniteTalk runner kalır)

## 3. Mimari

```
Flutter Desktop App
├─ UI (4 tema, 3 görünüm modu)
├─ State (Riverpod + Hive persistence)
└─ Servis Katmanı:
   ├─ LtxClient        — HTTP (port/token discovery, /api/generate, /api/generation/progress)
   ├─ FfmpegService    — split/concat/probe/loudnorm/xfade/lut/overlay
   ├─ FaceFusionRunner — subprocess
   ├─ WanGPRunner      — InfiniteTalk Python subprocess (tek kalan Python)
   ├─ AudioAnalyzer    — RMS + Whisper + onset/BPM
   ├─ OllamaClient     — HTTP, prompt önerisi
   ├─ JobOrchestrator  — kuyruk, paralel slot, resume
   └─ ProjectStore     — Hive + proje.json atomic write
```

**Bağlantılar:**
- LTX Desktop HTTP API (Electron app, port her başlatmada değişir → netstat parse + token file/manuel)
- ffmpeg.exe / ffprobe.exe (subprocess, stderr regex ile progress)
- FaceFusion venv Python (subprocess, var olan kurulum)
- WanGP venv Python (subprocess, var olan kurulum, sadece InfiniteTalk modu)
- whisper.cpp (subprocess, opsiyonel)
- Ollama HTTP (yereldeki gpt-oss:20b, opsiyonel)

## 4. Veri Modeli

```dart
class Proje {
  String id, isim;
  int versiyon;
  DateTime olusturmaTarihi, guncellemeTarihi;
  KaynakDosyalar kaynak;          // ses, gorsel, yuz, watermark, intro, outro, lut, srt
  GlobalAyarlar global;            // varsayılan model/çözünürlük/oran/segment süresi/CFG
  List<Segment> segmentler;
  List<SegmentGrubu> gruplar;
  List<Preset> presetler;
  AnalizSonuclari analiz;          // enerji + transkript + beats cache
  CikisAyarlari cikis;
  List<RenderGecmisi> renderGecmisi;
}

class Segment {
  String id;
  int sira;
  double basla, bit;
  // null → global'den miras
  String? prompt, negatifPrompt;
  String? model, cozunurluk, oran, kameraHareketi;
  int? sure, steps, seed;
  double? guidanceScale;
  bool? ses, faceSwapAcik;
  String? sesOverridePath, girisGorseliOverridePath;
  String? grupId;
  // Üretim durumu
  SegmentDurum durum;
  String? videoYolu;
  List<String> varyantYollari;
  String? sonKareYolu;
  AnalizMetadata? analizMeta;
  String? hataMesaji;
  Duration? uretimSuresi;
}

class CikisAyarlari {
  List<CikisPreset> presetler;
  GecisAyarlari gecisler;          // boundary-bazlı: none/crossfade/dissolve/cut
  SesKarisimiModu sesModu;          // tam_orijinal / segment_sesleri / mix / sessiz
  bool loudnessNormalize;
  RenkDuzeltme? renkDuzeltme;
  Watermark? watermark;
  Altyazi? altyazi;
  ClipEklentisi? intro, outro;
  HizRampasi? hizRampasi;
  bool beatSyncSnap;
}
```

Detaylı şema: brainstorm transcript, freezed kod üretimiyle final.

## 5. Proje Klasör Yapısı

```
proje_klasoru/
├── proje.json              ← versiyonlu ana dosya
├── kaynak/                 ← tüm seçilen dosyalar buraya kopyalanır (hash'li)
├── ses_segmentleri/        ← ffmpeg ile bölünmüş audio segment'leri
├── kareler/                ← son kareler (face-swap'lı varyantlar dahil)
├── segmentler/             ← üretilmiş video segment'leri (varyantlarla)
├── analiz/                 ← enerji.json, transkript.json, beats.json
├── on_izleme/              ← thumbnail cache
└── cikti/                  ← export preset çıktıları (youtube_1080p.mp4, shorts.mp4 ...)
```

## 6. UI Yapısı

**Ana pencere:** Title bar + sol nav rail (Projeler / Stüdyo / Render / Geçmiş / Ayarlar) + içerik alanı + alt mini render bar (her zaman görünür).

**Studio sayfası, üç görünüm modu (sekme ile geçiş):**

1. **Studio (varsayılan):** Sol segment listesi (sürükle-sıralanabilir, durum badge), orta-üst önizleme + varyant seçici, orta-alt mini timeline + waveform, sağ inspector (tüm segment parametreleri).

2. **Timeline (NLE):** Tam ekran timeline, waveform + onset/beat marker'ları, segment ribbon (renk = grup/enerji), inspector overlay panel, multi-select.

3. **Storyboard:** Pinterest-tarzı kart grid, tıkla → tam ekran modal editör + büyük preview. Tablet/dokunmatik dostu.

**Yan paneller (her görünümde toggle):**
- 🎵 Ses Asistanı (RMS grafiği, transkript, beat marker)
- 🤖 AI Prompt Asistanı (4 katman opsiyonel toggle, segment için 3 öneri)
- 📋 Render Kuyruğu (anlık aktif/bekleyen job listesi)

**Inspector field'ları:** prompt, negatif prompt, süre (5/6/8/10/20), çözünürlük, oran, model (fast/pro), CFG slider, steps slider, kamera hareketi, ses on/off + override, görsel override, face swap toggle, seed (rastgele ikonu), grup ataması.

## 7. Job Pipeline

**Job tipleri:** AnaliziYap, SegmentUret, InfiniteTalkUret, FaceSwapUygula, EnIyiKareyiCikar, Birlestir, CikisOlustur, TopluUret.

**Kuyruk:** PriorityQueue, sürükle ile sıra değiştir. LTX slot havuzu (multi-instance auto-detect, varsayılan tek). ffmpeg/face-swap/whisper/ollama kendi paralel havuzlarında.

**Resume:** Açılışta `durum=uretiliyor` job'ları kontrol — disk'te output varsa tamamlandı, yoksa kuyruğa geri at. Segment dosyası mevcutsa tekrar üretilmez (yeniden üret → `seg_v2.mp4`).

**İptal:** cancelToken; subprocess kill, LTX'e DELETE.

## 8. Tema Sistemi

`ThemeProvider`: aktifTema (4 seçenekten biri) + aydinlikModu (her temada light/dark) + aksanRengi (kullanıcı override). Tüm widget'lar `ThemedWidget` base'i kullanır. Settings'te canvas mockup ile preview.

## 9. Build Sırası

13 faz, ~22-25 iş günü:
- Faz 0: İskelet + tema (1g)
- Faz 1: Veri modeli + proje deposu + kaynak kopyalayıcı (1-2g)
- Faz 2: LTX bağlantısı (1g)
- Faz 3: ffmpeg servisleri (1-2g)
- Faz 4: Job orchestrator (2g)
- Faz 5: Studio görünümü + Inspector (3g)
- Faz 6: Timeline + Storyboard görünümleri (2g)
- Faz 7: Analiz servisleri (RMS/Whisper/beat) (2g)
- Faz 8: AI prompt asistanı (1-2g)
- Faz 9: Face swap + WanGP (1g)
- Faz 10: Çıkış pipeline'ı (geçiş/ses/LUT/watermark/altyazı/intro/outro/rampa/preset) (3g)
- Faz 11: Render sayfası + tray (1g)
- Faz 12: Geçmiş + multi-instance (1g)
- Faz 13: Polish (2g)

## 10. Bağımlılıklar (pubspec)

riverpod, freezed, json_serializable, dio, hive, go_router, window_manager, tray_manager, video_player, video_player_win, file_picker, desktop_drop, fluent_ui, forui, crypto, uuid, process_run, flutter_acrylic, fl_chart, flutter_animate.

## 11. Kabul Kriterleri

- [ ] Bat dosyasındaki tüm parametreler UI'dan ayarlanabiliyor
- [ ] Her segment ayrı prompt + ayrı tüm parametreler alabiliyor
- [ ] Bir segment "ses kapalı" (sessiz video) üretebiliyor
- [ ] Tek segmenti yeniden üretmek mümkün, varyant olarak saklanıyor
- [ ] Uygulama kapanıp açılınca render kaldığı yerden devam ediyor
- [ ] LTX Desktop yeniden başlatılınca yeni port/token otomatik bulunuyor
- [ ] InfiniteTalk modu (WanGP) çalışıyor
- [ ] Face swap zinciri (her segmentin son karesi) çalışıyor
- [ ] Çoklu çıkış preset'i tek seferde üretilebiliyor (YouTube + Shorts paralel)
- [ ] Tray icon, ana pencere kapansa bile job'lar bitene kadar devam ediyor
- [ ] 4 tema arasında runtime geçiş kayıpsız çalışıyor

## 12. Risk & Açık Sorular

- **LTX API'nin DELETE endpoint'i var mı?** İptal için netstat ile process kill alternatifi düşünülebilir.
- **Multi-LTX-instance**: aynı GPU'da iki LTX VRAM yetmeyebilir — kullanıcıya uyarı.
- **whisper.cpp Türkçe kalitesi**: medium model en az gerek; tiny yeterli olmaz.
- **Beat-sync snap**: agresif snap segment sürelerini bozabilir → "tolerans" slider eklenebilir.