# FikoYT Nodes — Tasarım Spec'i

**Tarih**: 2026-05-28
**Sahip**: FikoYT (fikri007@gmail.com)
**Hedef**: MVD'de yapılan her şeyi (image / video / audio / character / utility) bağımsız, profesyonel, tam parametreli ComfyUI node'ları olarak sunmak. Başka projelerde de kullanılabilir, birleştirilebilir.

---

## 1. Hedefler

- **Bağımsız paket**: `ComfyUI-FikoYT-Nodes`. MVD'ye bağımlılık yok.
- **MVD parite**: MVD'nin yaptığı her render iş akışı bir veya birkaç FikoYT node'u ile yapılabilir. Tüm parametreler expose.
- **Birleştirilebilir**: Standart ComfyUI tipleri (IMAGE/LATENT/MODEL/CLIP/VAE/CONDITIONING/AUDIO/MASK) → rgthree, KJNodes, comfy-controlnet vb. ile native çalışır.
- **Auto-download**: Her loader eksik modeli HF'den otomatik indirir (MVD'nin `hf_download` pattern'i).
- **Profesyonel**: Her node `sampler`, `scheduler`, `cfg`, `denoise`, `steps`, `seed`, `width/height`, `lora_stack`, `negative` gibi tüm ince ayarları açar.
- **Dağıtım**: `pyproject.toml` ile ComfyUI Registry'ye uygun.

---

## 2. Non-hedefler

- MVD UI / FastAPI endpoint'leri **taşınmayacak** (bunlar app-spesifik, MVD'de kalır).
- Proje yönetimi (`project/{name}/...`) **dahil değil** (MVD özel).
- Test Lab, Auto Mode, Batch Videos workflow orkestratörleri **dahil değil** (üst seviye orchestrators, MVD'de kalır).
- Geriye dönük yapılan migrasyonlar yok — yeni paket sıfırdan.

---

## 3. Paket Yerleşimi

```
ComfyUI/custom_nodes/ComfyUI-FikoYT-Nodes/
├── __init__.py                # NODE_CLASS_MAPPINGS + WEB_DIRECTORY
├── pyproject.toml             # Registry metadata (publisher: fikoyt)
├── requirements.txt
├── README.md
├── core/
│   ├── auto_download.py       # hf_download (resume+SHA), get_models_dir
│   ├── types.py               # FIKOYT_CHARACTER, FIKOYT_LORA_STACK
│   ├── registry.py            # curated models/LoRAs JSON loader
│   └── helpers.py             # tensor/aspect/seed util
├── image/
│   ├── flux_loader.py         # Flux dev/schnell/kontext loader + auto-dl
│   ├── flux_sampler.py        # KSampler wrapper, Flux ayarlı
│   ├── qwen_loader.py         # Qwen Image + Multi-Angle
│   ├── sdxl_loader.py
│   ├── pulid_v2.py            # PuLID v2 face apply
│   ├── instantid.py           # InstantID face apply
│   ├── ipadapter_v2.py        # IPAdapter v2 style
│   ├── dwpose_extract.py      # DWPose keypoint
│   ├── cn_union.py            # ControlNet Union apply
│   ├── sam2_mask.py           # SAM 2 segmentation
│   ├── kontext_edit.py        # Flux Kontext image edit
│   └── style_transfer.py
├── video/
│   ├── wan_t2v.py             # Wan 2.2 T2V/I2V
│   ├── wan_s2v.py             # Wan Sound-to-Video
│   ├── ltx_distilled.py       # LTX Distilled (T2V + I2V + LoRA stack)
│   ├── ltx_interpolate.py     # video interpolation
│   ├── ltx_upscale.py
│   ├── hunyuan_video.py
│   ├── infinitetalk.py
│   ├── humo_generate.py
│   ├── storyboard_concat.py   # video concat with crossfade
│   └── video_grid.py
├── audio/
│   ├── songgen_v2.py          # SongGen v2 (LeVo) PT + GGUF
│   ├── f5_tts.py              # F5-TTS klonlama (ref+speed)
│   ├── edge_tts.py            # Edge TTS 20 ses
│   ├── demucs_split.py        # Vokal/enstrüman ayrıştırma
│   ├── whisper_stt.py         # ses→metin
│   ├── audio_trim.py          # ffmpeg ile dilimle
│   ├── audio_concat.py
│   └── master_audio.py        # mastering preset
├── character/
│   ├── bind.py                # FIKOYT_CHARACTER bundle yarat
│   ├── unpack.py              # bundle'ı parçalara aç
│   ├── lora_stack_apply.py    # MODEL+CLIP'e LoRA stack uygula
│   └── face_swap_reactor.py
├── util/
│   ├── file_picker.py         # web/ ile dialog
│   ├── prompt_builder.py      # template + character bind
│   ├── lora_picker.py         # registry tabanlı dropdown
│   ├── aspect_preset.py       # 1:1/9:16/16:9/4:5 vb.
│   ├── seed_control.py
│   └── gallery_save.py
└── web/
    ├── js/file_picker.js      # dialog (MVD pattern, z-index 2147400000)
    └── js/lora_picker.js
```

---

## 4. Custom Tipler

| Tip | İçerik | Aç/Kapa |
|---|---|---|
| `FIKOYT_CHARACTER` | `{id, name, face_emb_path, lora_paths[], ref_image_path, base_prompt, base_neg}` | `Character Bind` ile yarat, `Character Unpack` ile parçala (→ IMAGE + STRING + FIKOYT_LORA_STACK) |
| `FIKOYT_LORA_STACK` | `List[{name, strength_model, strength_clip}]` | `LoRA Picker` ile yarat, `LoRA Stack Apply` ile MODEL+CLIP'e uygula |

Tüm diğer I/O standart ComfyUI tipleri. Custom tipler **opsiyonel** — bypass edilip standart node'larla aynı sonuç alınabilir.

---

## 5. Parametre Standardı (her sampler node'unda)

```
positive (STRING / CONDITIONING)
negative (STRING / CONDITIONING)
width, height, batch_size
steps, cfg, sampler_name, scheduler, denoise, seed
lora_stack (FIKOYT_LORA_STACK, optional)
character (FIKOYT_CHARACTER, optional)
control_image (IMAGE, optional)
control_strength
mask (MASK, optional)
```

Loader node'larında ek: `auto_download (bool)`, `precision (fp16/bf16/fp8)`, `vram_mode (default/lowvram/novram)`.

---

## 6. Auto-Download Stratejisi

- `core/auto_download.py` her node'a aynı API sunar: `ensure_model(repo_id, filename, subdir, sha256=None)`.
- Hedef yollar **standart ComfyUI**: `models/checkpoints`, `models/loras`, `models/vae`, `models/clip`, `models/controlnet`, `models/insightface`, `models/sams`, `models/diffusion_models` (video).
- Resume + SHA check + progress callback (MVD'nin `_legacy.py`'deki download bloklarından konsolide).
- Curated registry (`core/registry.py`): MVD'deki 58 LoRA + 32 model preseti JSON olarak gömülü → loader dropdown'larında görünür.

---

## 7. MVD ile İlişki

- MVD bağımlılık olarak FikoYT Nodes'u **kullanmaz** (bağımsız kalsın). MVD kendi node'larıyla yaşar.
- FikoYT Nodes, MVD'nin `_legacy.py` + `nodes/visual.py` + `wan/` + `ltx/` + `music_gen/` modüllerinden **kod transferi** ile başlar (kopya değil — yeniden yazım, sadeleştirme).
- MVD'nin endpoint'leri (FastAPI route'ları) **taşınmıyor** — bunlar app'e özel.
- İlerde MVD bu paketi opsiyonel olarak dependency yapabilir → kod tekrarı kaldırılır. Bu **ayrı bir sprint**.

---

## 8. Sprint Planı (yüksek seviye)

| Sprint | Kapsam | Çıktı |
|---|---|---|
| **F1** | Paket iskeleti + core/ + auto_download + types + registry + 1 örnek node (Flux Loader+Sampler) | ComfyUI restart sonrası menüde `FikoYT/image/Flux Loader` görünür, render çalışır |
| **F2** | Image katmanı: Qwen, SDXL, Kontekst, PuLID v2, InstantID, IPAdapter v2, DWPose, CN Union, SAM2, Style | Tüm image studio MVD parite |
| **F3** | Video katmanı: Wan T2V/I2V/S2V, LTX Distilled + interpolate + upscale, HunyuanVideo, InfiniteTalk, HuMo, Storyboard, Grid | Tüm video studio MVD parite |
| **F4** | Audio katmanı: SongGen v2, F5-TTS, Edge TTS, Demucs, Whisper, Trim/Concat, Mastering | Tüm audio studio MVD parite |
| **F5** | Character + Util: Bind/Unpack, LoRA Stack Apply, File Picker, Prompt Builder, LoRA Picker, Aspect Preset, Seed, Gallery Save, Face Swap Reactor | Karakter sistemi + utilities |
| **F6** | `pyproject.toml`, README, örnek workflow JSON'lar, ComfyUI Registry yayın hazırlığı | Paylaşılabilir paket |

Her sprint sonunda: `python -c "import ast"` syntax check + ComfyUI restart + en az 1 canlı render test.

---

## 9. Risk + Karar Noktaları

- **Bağımlılık çakışması**: MVD ve FikoYT Nodes aynı upstream paketleri (insightface, transformers, librosa) kullanır → `requirements.txt`'te **versiyon pinlemeyiz**, MVD'nin halihazırdaki kurulu paketlerini olduğu gibi kullanırız. (`requirements.txt`'te sadece minimum sürüm.)
- **Model yolu çakışması**: Her iki paket de aynı `ComfyUI/models/*` yollarına yazar → indirme idempotent (varsa atla). Çatışma yok.
- **Custom tip serileştirme**: `FIKOYT_CHARACTER` workflow JSON'da bir dict olarak serileşir. ComfyUI bunu otomatik halleder. Sorun yok.
- **GGUF / fp8 yükleme**: SongGen v2 GGUF + Wan fp8 → mevcut MVD loader kodu (smthemex node, ComfyUI-GGUF) kullanılır, FikoYT bunlara wrapper yazar (kopyalamaz).

---

## 10. Başarı Kriteri

1. ComfyUI restart sonrası `FikoYT/` kategorisi menüde görünür, 60+ node listelenir.
2. Her node'un INPUT_TYPES tüm parametreleri açar — gizli/hardcoded değer yok.
3. Bir Flux T2I workflow (Loader→LoRA Stack→Sampler→VAE Decode→Save) çalışır.
4. Bir Wan S2V workflow (Loader→Audio→S2V→Save Video) çalışır.
5. Bir SongGen v2 workflow (Loader→Lyrics→Generate→Master→Save Audio) çalışır.
6. Custom node'lar rgthree group'larına atılabilir, KJNodes Image Concat'a bağlanabilir.
7. README'de örnek 3 workflow JSON yer alır.