# FikoYT Stüdyo — Tasarım Dokümanı (Spec)

**Tarih:** 2026-06-10
**Konum:** `D:\__sistem__\Masaustu\FikoYT.Yeni.Cag\video-uretim-1`
**Durum:** Kullanıcı onayı bekleniyor

## 1. Vizyon

CapCut Desktop seviyesinde ve arayüzünde, tamamen yerel çalışan, yapay zeka destekli **tam bir video/müzik üretim tesisi**. Tek Flutter Windows uygulaması; tüm AI üretimi **sadece ComfyUI** (`http://127.0.0.1:8188`) üzerinden. Müzik üretiminden sahne sahne video yönetmenliğine, karakter LoRA eğitiminden CapCut seviyesi timeline kurguya kadar uçtan uca pipeline.

**İlkeler:**
- Tek AI motoru: ComfyUI (LTX Desktop, ACE-Step standalone, WanGP sunucuları YOK)
- Sıfırdan temiz mimari + eski projelerden (`flutter-video-uret`, `fiko_film_studyo`) kanıtlanmış mantığın seçici taşınması
- Performans en üst öncelik; oyun UI tarzı, dark+light tema, bol animasyon, tam parametrik kontrol
- Her üretim tekrar üretilebilir (tüm parametreler kayıtlı)

## 2. Mimari

```
┌─────────────────────────── Flutter Windows (tek uygulama) ───────────────────────────┐
│  UI Katmanı: Stüdyolar │ Video Direktörü │ Editör (timeline) │ Sihirbazlar │ Galeri  │
│  State: Riverpod (AsyncNotifier/Notifier), modüler feature klasörleri                │
│  Domain: Proje, Sahne, Segment, Karakter, ÜretimKaydı, Şablon modelleri              │
│  Veri: Isar DB (projeler, karakterler, geçmiş, favoriler, kuyruk, LoRA katalog)      │
├──────────────┬─────────────────────┬─────────────────────┬───────────────────────────┤
│ ComfyUI      │ FFmpeg Servisi      │ Eğitim Servisi      │ Medya Servisi             │
│ İstemcisi    │ (yerel süreç)       │ (yerel süreç)       │ (media_kit)               │
│ HTTP+WS      │ concat/xfade/filter │ sd-scripts CLI      │ önizleme, waveform        │
│ :8188        │ _complex/render     │ (Flux karakter LoRA)│ thumbnail                 │
└──────────────┴─────────────────────┴─────────────────────┴───────────────────────────┘
        │                                      │
        ▼                                      ▼
  ComfyUI (LTX 2.3 / ACE-Step 1.5 /     sd-scripts (kohya)
  Flux+PuLID / Whisper / Gemini-Ollama  flux_train_network.py
  / SAM-2 / FL-AceStep-Training)
```

### 2.1 ComfyUI Entegrasyon Katmanı
- **İstemci:** HTTP (`/prompt`, `/history`, `/view`, `/object_info`, `/interrupt`, `/queue`) + WebSocket (`/ws`) ile node bazlı canlı ilerleme (`progress`, `executing`, `executed` event'leri)
- **Workflow Şablon Motoru:** Mevcut workflow JSON'ları (API format) uygulamaya parametrik şablon olarak gömülür. Şablonda enjeksiyon noktaları tanımlı: prompt, negatif, seed, çözünürlük, süre/frame, model, LoRA stack, ses dosyası, referans resim vb. Şablonlar `assets/workflows/` altında versiyonlu tutulur.
- **Model Keşfi:** `/object_info` ile checkpoint/diffusion/LoRA/VAE/text-encoder listeleri canlı çekilir; LoRA kataloğu (trigger word, önerilen multiplier, uyumlu modeller, kategori) Isar'da zenginleştirilir.
- **Üretim Kuyruğu:** Uygulama içi kuyruk → ComfyUI kuyruğu eşlemesi; çoklu iş, sıra değiştirme, iptal, hata yakalama, otomatik yeniden deneme; her işin tam parametre snapshot'ı ÜretimKaydı olarak Isar'a yazılır.

### 2.2 FFmpeg Servisi
- Timeline → `filter_complex` graph derleyici (render'da)
- Yardımcılar: ses bölme, son kare çıkarma, concat, audio mux, waveform PNG, thumbnail, GIF, proxy/önizleme render
- Eski `muzik_video_uret.py` / `flutter-video-uret` ffmpeg stratejileri uyarlanır

### 2.3 Eğitim Servisi
- **Flux Karakter LoRA:** `sd-scripts/flux_train_network.py` Flutter'dan `Process` ile çalıştırılır; stdout parse ederek step/loss canlı grafik; çıktı `.safetensors` otomatik `ComfyUI/models/loras/` klasörüne kopyalanır + kataloğa eklenir
- **ACE-Step Müzik LoRA:** ComfyUI `FL-AceStep-Training` node'larıyla workflow olarak (tara → LLM etiketle → ön işle → eğit), WS'ten canlı ilerleme

## 3. Üretim Modülleri

### 3.1 Müzik Stüdyosu (ACE-Step 1.5) — İLK ÖNCELİK
- **Müzik Sihirbazı** (eski ace_step_sihirbaz tam seti + fazlası): 20 kültür, 55 tür (37 müzik + 17 konuşma/spoken), 19 mood, 31 vokal karakteri, 150+ enstrüman çip kataloğu, BPM (50-220), enerji (0-100), yaratıcılık (0-1.5 → LM temp 0.4-1.6, enerji → CFG 3.0-9.5), vokal modu (erkek/kadın/çocuk/koro/düet/enstrümantal/konuşma)
- **Söz Editörü:** [Verse]/[Chorus]/[Bridge]/[Intro]/[Outro] yapı şablonları, satır bazlı düzenleme, Gemini/Ollama ile söz yazdırma/geliştirme/çeviri
- **Oto Müzik:** tek cümlelik fikir → Gemini ile tam tarif + tag + söz → üretim (eski "Oto Müzik Gemini" workflow'u)
- Model seçimi: turbo_aio / xl_sft / xl_turbo; tam parametre: seed, steps, CFG, temperature, top_p, süre (10-240sn), ton/dil
- Eğitilmiş sanatçı LoRA'sı seçimi (ör. kendi sesinizden eğitilen)
- Şablon kaydet/yükle, varyasyon üretimi (aynı ayar farklı seed), A/B karşılaştırmalı çalar, üretim geçmişi + favoriler

### 3.2 Resim Stüdyosu (Flux)
- T2I, I2I, inpaint (maske fırçasıyla "Resim Düzenleme"), farklı açı üretimi ("Resim Farklı Açılarda"), ardışık sahne üretimi, Qwen ile resim analizi/captioning
- **PuLID karakter tutarlılığı:** referans yüz → her üretimde aynı karakter; karakter kartından tek tık
- Tam parametre: model (flux1-dev-fp8 / GGUF Q8), çözünürlük presetleri + özel, seed, steps, CFG/guidance, denoise, sampler/scheduler
- **LoRA stack paneli** (tüm stüdyolarda ortak bileşen): çoklu LoRA, ayrı strength, trigger word otomatik prompt'a, uyumsuzluk uyarısı, kendi eğitilenler yıldızlı
- Toplu üretim (batch), galeri içi karşılaştırma, beğenilenden I2V'ye gönder

### 3.3 Video Stüdyosu (LTX 2.3)
- T2V, I2V, **ses-senkron video** (audio VAE ile müzik/konuşmaya tepkili), Sulphur model alternatifi
- Model seçimi: distilled-1.1 / dev-fp8 / GGUF Q6 / Sulphur bf16-fp8; tam parametre: çözünürlük, frame sayısı (örn. 121), fps (24), guidance, steps, motion strength, shift, seed
- **IC-LoRA presetleri:** Lipdub (dudak senkron), Cameraman (kamera hareketi), AudioReactive, Transition, Detailer, Refocus, Motion-Track-Control, TalkVid — her biri açıklamalı kart, önerilen strength ile tek tık
- Görünüm seviyeleri: **Basit** (presetler) / **Gelişmiş** (ana parametreler) / **Uzman** (workflow'daki tüm node parametreleri)

### 3.4 Video Direktörü (adım adım sahne stüdyosu — sistemin kalbi)
ComfyUI workflow mantığı, CapCut benzeri görsel akışta. Aşama çubuğu: **Müzik → Analiz → Bölümleme → Sahne Planı → Resimler → Videolar → Kurgu**. Her adıma geri dönülebilir.

1. **Müzik:** Yükle (MP3/WAV/FLAC) veya Müzik Stüdyosu'ndan al
2. **Analiz:** Beat/downbeat/onset + enerji bantları (silence/low/medium/high/climax) + Whisper söz dökümü (zaman damgalı) — "1-Beat Analiz" workflow'u
3. **Bölümleme:** Otomatik öneri (intro/verse/nakarat/klimaks) → waveform üstünde elle düzenleme: birleştir, böl, sınır kaydır, süre değiştir
4. **Sahne Planı — Çift Prompt Üretimi:** Her sahne için LLM (Gemini/Ollama) **iki prompt** üretir:
   - **Resim promptu** (Flux): kompozisyon, karakter, mekan, ışık, stil
   - **Video promptu** (LTX): hareket, kamera, sahne dinamiği — enerji seviyesine göre (sakinde yavaş push-in, klimaksta hızlı/dans)
   - Girdiler: bölüm sözleri, enerji, BPM, karakter/mekan/stil kilitleri, tema notu, prompt_style/style_suffix/negative_default şablonları (eski "2-Sahne Prompt Üretimi" + "LTX Prompt Creator V5" mantığı)
   - Toplu üretim veya sahne bazlı; her prompt düzenlenebilir; hızlı LLM komutları ("daha sinematik", "geceye çevir"); versiyon geçmişi
5. **Resimler:** Sahne kartından Flux + PuLID (karakter kilitli) üretim; beğen / yeniden üret / varyasyon; geçmiş saklanır; manuel resim ekleme de mümkün ("Sahneye Manuel Resim Ekle")
6. **Videolar:** Onaylı resimden I2V (sahne ses dilimi ile senkron); sahne bazlı bağımsız üretim/yeniden üretim
7. **Kurgu:** Onaylanan videolar müzikle hizalı otomatik timeline'a → Editör'de devam

Sahne kartı: söz + enerji + resim promptu + video promptu + üretilen resim + üretilen video + durum rozetleri tek kartta.

### 3.5 Karakter Stüdyosu
- **Karakter Kartı** (her şeyi birleştirir): kimlik (isim, rumuz, açıklama, cinsiyet, dil) + referans yüz seti (yüz/portre/tam gövde/sahne tipleri, birincil yüz) + persona prompt parçaları (saç rengi/tarzı, göz, yaş, ten, vücut, etnisite, varsayılan kıyafet, duruş, ek etiketler → tek stringe derleme) + negatif & stil etiketleri + **karakter kilidi** (sabit seed, PuLID, eğitilmiş LoRA) + kıyafet/sahne presetleri + ses kimliği
- **Karakter LoRA Eğitimi (Flux, sd-scripts):**
  - Dataset hazırlama: foto yükle → otomatik caption (Qwen/Gemini) → düzenlenebilir caption'lar → resim+txt çiftleri
  - Eğitim: rank/alpha, LR, steps/epoch, batch, çözünürlük — presetler (hızlı/dengeli/kalite) + uzman modu
  - Canlı izleme: step/loss grafiği, ara örnek üretimleri
  - Bitince: otomatik `models/loras/`'a kopya + katalog kaydı + karaktere bağlama
- **Sanatçı/Müzik LoRA Eğitimi (ACE-Step, ComfyUI node'ları):** şarkı klasörü → LLM oto-etiket (caption, BPM, key, tür, söz) → ön işleme → eğitim; WS canlı ilerleme; çıkan LoRA Müzik Stüdyosu'nda seçilebilir
- Karakter test üretimi: eğitim sonrası hızlı doğrulama gridi (aynı seed, farklı promptlar)

### 3.6 Sihirbazlar (tümü: geçmiş + favoriler + şablon + form snapshot, Isar'da)
- **Prompt Sihirbazı:** Karakter (20 alan: yaş, cinsiyet, etnisite, yüz şekli, vücut, ten, kaş, makyaj, aksesuar, saç rengi/uzunluk/stil, göz, kıyafet türü/rengi, ruh hali, poz, sahne uyumu, stil) / Mekan (12 alan: iç-dış, spesifik mekan, saat, hava, stil, atmosfer, renk paleti, mevsim, sıcaklık, kalabalık, mimari, bakış açısı) / Ürün (12 alan: tip, alt kategori, marka, materyal, renk, arka plan, aydınlatma, açı, açı seti, stil, fotoğrafçılık, prop'lar) + ortak ekler (serbest metin, sanat stili, lens, renk tema, sabit seed) + Ollama/Gemini geliştirme
- **Müzik Sihirbazı:** §3.1'deki tam katalog
- **Video/Sahne Sihirbazı:** sahne tipleri, kamera hareketleri, karakter tipleri, ifadeler, aksiyonlar, giyimler, ortamlar, ışıklandırmalar, görsel stiller, atmosferler (multi-chip), yoğunluk/detay/yaratıcılık slider'ları, LoRA stack, serbest not, negatif ek, seed
- Sihirbaz çıktısı tek tıkla: üretim formuna / sahne kartına / panoya

## 4. Editör — CapCut Seviyesi Tam Özellik Seti

### 4.1 Timeline Temel
Sınırsız multi-track (video/overlay/müzik/ses/yazı/efekt/adjustment), manyetik snap, sürükle-bırak, split, trim, ripple delete, copy/paste + nitelik yapıştırma, çoğalt, track'ler arası taşıma, compound clip (grupla), group/ungroup, marker'lar, klip renklendirme, klip/track kilitleme-gizleme-sessize alma, timeline zoom, sınırsız undo/redo, **transcript tabanlı kurgu** (Whisper dökümünden metin seçerek kes)

### 4.2 Hız & Zaman
Sabit hız (0.1x-100x), **curve speed** (Montage/Hero/Bullet/Jump Cut/Flash In-Out + özel eğri editörü), reverse, freeze frame, kare interpolasyonu ile pürüzsüz yavaşlatma (AI)

### 4.3 Geçişler
xfade tabanlı tam set: Basic (dissolve, fade, yönlü wipe), Camera/Lens, Slide, Zoom, Blur, Glitch, Circle, Slice, Shake, Light, 3D; süre ayarı, tümüne uygula; **AI geçiş** (LTX Transition LoRA ile iki sahne arası üretilmiş geçiş — CapCut'ta yok)

### 4.4 Efektler & Filtreler
Görsel efektler (blur, glow, VHS, retro, film grain, chromatic aberration, pixelate, glitch, neon, sparkle, lens, açılış/kapanış), filtre paketleri (yoğunluk ayarlı), motion blur

### 4.5 Renk
Parlaklık/kontrast/doygunluk/exposure/highlight-shadow/sıcaklık/tint/sharpen/grain/vignette/fade, HSL (8 kanal), Curves (RGB + kanal), histogram, LUT import (.cube), Color Match (referans kareden), Auto Adjust (AI), **adjustment layer** (altındaki tüm track'lere uygulanır)

### 4.6 Yazı & Altyazı
Zengin stil (font import TTF/OTF, boyut, renk, stroke, shadow, glow, arka plan, opacity, spacing), yazı şablonları, In/Out/Loop animasyonları (typewriter, flicker...), **otomatik altyazı** (Whisper: çoklu dil, word-by-word karaoke vurgu, caption şablonları, filler word temizleme), TTS (ACE-Step konuşma modu ile seslendirme), sticker desteği

### 4.7 Ses
Ses ayır (videodan), fade in/out, ses keyframe, pitch, **beat detection** (analizden otomatik işaretler) + **beat-snap** (klipler beat'e yapışır), gürültü azaltma, **auto ducking**, vokal ayırma (vocal isolation), ses kaydı, SFX kütüphanesi (yerel klasör)

### 4.8 Overlay & Kompozisyon
PiP, opacity, blend mode'lar (Multiply, Screen, Overlay, Darken, Lighten, Color Burn...), maskeler (Linear/Mirror/Circle/Rectangle/Star; feather, invert, keyframe'li), chroma key, **AI arka plan kaldırma** (SAM-2), stabilization, **motion tracking** (nesneye yazı/sticker sabitle), **keyframe animasyonu** (konum/ölçek/döndürme/opaklık + easing grafik editörü)

### 4.9 AI Editör Özellikleri (hepsi yerel)
- AI upscale, kare interpolasyonu, arka plan kaldırma (SAM-2)
- **Sahneyi yeniden üret:** timeline'daki AI klibe sağ tık → varyasyon üret (Video Direktörü köprüsü)
- **Boşluk doldurma:** iki klip arasına AI geçiş/sahne ürettir
- AI Movement (statik resme kamera hareketi → I2V ile)
- Smart cut: sessizlik/filler temizleme (Whisper tabanlı)
- Auto reframe: 16:9 → 9:16 akıllı kırpma (özne takipli, SAM-2)

### 4.10 Canvas & Export
Oran presetleri (16:9, 9:16, 1:1, 4:3, 3:4, 21:9 + özel), arka plan (renk/görsel/kendi videosundan blur), çözünürlük 480p-4K, fps 24/25/30/50/60, H.264/HEVC, MP4/MOV/WebM, bitrate (önerilen/özel), ayrı ses export (MP3/WAV), GIF, kapak seçimi, seçili aralık render, platform presetleri (Shorts/TikTok/Instagram/YouTube), taslak hızlı önizleme render

### 4.11 Önizleme Mimarisi
`media_kit` video çekirdeği + Flutter Impeller üzerinde GPU shader efekt katmanı (renk, filtre, geçiş önizlemesi gerçek zamanlı); final render aynı parametrelerle ffmpeg `filter_complex`'e derlenir — **gördüğün neyse render o**. Ağır timeline'larda proxy önizleme.

## 5. Veri Modeli (Isar)

| Koleksiyon | İçerik |
|---|---|
| Proje | ad, oran, fps, timeline JSON, oluşturma/güncelleme |
| Track / Klip | tip, kaynak, in/out, efektler, keyframe'ler, geçişler |
| Sahne (Direktör) | bölüm aralığı, sözler, enerji, resim/video promptları + versiyonları, üretim referansları, durum |
| Karakter | kimlik, referanslar, persona parçaları, kilit ayarları, LoRA ref, presetler, ses kimliği |
| ÜretimKaydı | tip, workflow şablonu, tüm parametreler (snapshot), çıktı dosyası, süre, durum |
| LoRAKatalog | dosya, kategori, trigger words, önerilen strength, uyumlu modeller, eğitilmiş mi |
| SihirbazGeçmişi / Favori / Şablon | kategori, form snapshot, üretilen prompt |
| EğitimKaydı | tip (flux/ace), dataset, parametreler, loss geçmişi, çıktı LoRA |

## 6. Hata Yönetimi
- ComfyUI erişilemez → durum çubuğunda bağlantı rozeti, otomatik yeniden bağlanma, kuyruk bekletme; "ComfyUI'yi başlat" kısayolu (`run_nvidia_gpu.bat`)
- Üretim hatası → node hatası Türkçeleştirilmiş mesajla kuyruk kartında; parametrelerle tek tık yeniden dene
- VRAM yetersizliği → model/çözünürlük düşürme önerisi
- Eğitim çökmesi → stdout/stderr log saklanır, son checkpoint'ten devam
- Tüm dosya işlemleri (kopyalama, render) atomik + geçici dosya üzerinden

## 7. Test Stratejisi
Kritik iş mantığı (kullanıcı tercihi gereği sadece bunlar):
- Workflow şablon enjeksiyon motoru (parametre → JSON doğruluğu)
- Timeline → ffmpeg filter_complex derleyici
- Beat/bölümleme hesaplamaları, prompt derleme (persona → string)

## 8. Fazlar

| Faz | Kapsam |
|---|---|
| **1** | İskelet (tema, navigasyon, Riverpod, Isar) + ComfyUI istemci/kuyruk/galeri + **Müzik Stüdyosu** (sihirbaz, söz editörü, oto müzik, şablonlar) |
| **2** | **Resim Stüdyosu** (Flux, PuLID, inpaint, açılar) + LoRA stack paneli + **Karakter Stüdyosu** (kart + Flux LoRA eğitimi) |
| **2.5** | ACE-Step sanatçı LoRA eğitimi + Prompt/Video sihirbazları |
| **3** | **Video Stüdyosu** (T2V/I2V/ses-senkron, IC-LoRA presetleri) + **Video Direktörü** (7 aşamalı akış) |
| **4a** | Timeline temel: track'ler, split/trim/ripple, hız, marker, undo/redo, önizleme, temel export |
| **4b** | Geçişler + efektler + renk (HSL/curves/LUT) + adjustment layer |
| **4c** | Yazı/altyazı (Whisper) + keyframe animasyon + maske/chroma/blend + ses araçları |
| **4d** | AI editör: arka plan kaldırma, auto reframe, smart cut, AI geçiş, sahne yeniden üretim, upscale/interpolasyon |
| **5** | Cila: transcript kurgu, motion tracking, beat-snap, compound clip, şablon sistemi, kısa film modu, performans turu |

## 9. Kapsam Dışı (şimdilik)
- MVD tam otomatik tek tık pipeline (Video Direktörü adım adım modeli tercih edildi)
- Bulut/işbirliği özellikleri, mobil platform
- RVC ses dönüşümü, FaceFusion face-swap (ileride değerlendirilecek)
- Efekt pazarı / paylaşım

## 10. Teknik Bağımlılıklar
- Flutter (Windows desktop), Riverpod, Isar, media_kit, dio/web_socket_channel, file_picker, desktop_drop
- Yerel: ComfyUI portable (:8188, CORS açık), ffmpeg (eski projedeki `video-uretim/ffmpeg` veya sistem), sd-scripts (kohya)
- ComfyUI custom node'ları mevcut: FL-AceStep-Training, PuLID-Flux, SAM-2, VideoHelperSuite, KJNodes, OllamaGemini, GGUF, MusicVideoDirector, FikoYT-Nodes