NOTES.md

# NOTES — саммари сессии (для продолжения)

## Цель

Заменить персону в видео на «дилера» (4 фото блондинки в чёрном платье) через
SCAIL-2 пайплайн, без ComfyUI-сервера — прямым Python-скриптом.

## Что сделано и работает ✅

1. **`generate.py`** — self-contained скрипт: ComfyUI ноды импортируются напрямую,
   без API/сервера/GUI. Модели → промпты → маски → `SCAILAutoExtend.generate()` → mp4.
2. **Мультиреференс работает нативно**: `reference_image` батчем `[N,H,W,C]` —
   первый = основной, остальные = доп. виды. WanAnimatePlus для этого НЕ нужен.
3. **Критичные параметры найдены** (из workflow автора, файл
   `ComfyUI/custom_nodes/scail-auto-extend/SCAIL Auto Extend.json`):
   `ModelSamplingSD3 shift=5` + `euler` + `simple` scheduler + `6 steps` +
   `lightx2v LoRA @ 0.8` + пустой negative. Без shift — мыло.
4. **SAM3-маски с кэшем** (`masks.py`): pose_video_mask + reference_image_mask,
   single-person (max_objects=1), кэш по хэшу входов в `mask_cache/`.
5. **Результат (animation mode, без масок и с масками)**: дилер перенесён
   (блондинка, чёрное платье), движения следуют видео, зелёный фон сохранён.
   81 кадр за ~1 мин на 6 шагах.
6. Ollama остановлен. GPU 2–6 — чужая тренировка, не трогаем.

## Что НЕ работает / открытые проблемы ❌

1. **Позиция персоны**: в исходнике она слева, в выходе — по центру.
   Маска (синий силуэт слева) идеальна, но НЕ управляет позицией.
   Гипотеза: pose mask — про «какие пиксели какой персоне» (multi-person),
   а layout модель берёт из референсов (центрированные портреты → центр).
2. **Replacement mode с нашими входами — мусор**: гигантское лицо дилера
   на весь кадр + брюнетка-двойник. Причины:
   - **Баг референсов**: портретные фото 3024×4032 центр-кропятся в ландшафт
     832×480 → остаётся полоса «подбородок–грудь», голова отрезана
     (`load_reference_images` в generate.py). Надо: letterbox/pad вместо crop
     или портретное разрешение.
   - Возможно, replacement mode ждёт полноростовый реф, а не хедшот.
3. **Маски не чинят позицию в animation mode** (проверено: result3 — всё равно центр).

## План действий (next steps)

### Ветка А: crop-and-composite (приоритет)
`composite.py` уже написан, не подключён. Идея:
1. Из SAM3-маски → union bbox персоны (`person_bbox` уже есть)
2. Кроп видео вокруг персоны с margin → портрет (напр. 576×832)
3. Генерация дилера в кропе (центрирование не мешает — кроп и так на персоне;
   заодно портрет = пропорции рефов дилера = голова не режется;
   персона ~340px ширины вместо 130px → лицо качественнее)
4. `composite_back` — вклейка в исходные кадры (с feather-маской)

### Ветка Б: идея пользователя — первый кадр через 4B edit-модель
Пользователь ранее делал так: брал 1-й кадр видео, прогонял через маленькую
4B-модель с редактированием (промпт «замени персону на персону из изображения»),
получал первый фрейм с нужной идентичностью. Дальше это можно использовать
как стартовый кадр/реф для видео-пайплайна. Кандидаты: Qwen-Image-Edit,
FLUX.2-klein-4b (уже лежит в diffusion_models: `flux-2-klein-4b-fp8.safetensors`!).
Обсудить на следующей сессии: стыковка с SCAIL-2 (edited first frame →
reference или previous_frames).

### Ветка В (отложено): WanAnimatePlus
`prefix_frames` (до 5 доп. рефов поверх нативных) + `transition_video`
(бесшовная склейка 21-кадровыми хвостами). Требует установки
ComfyUI-WanVideoWrapper + ComfyUI-WanAnimatePlus. Пока хватает нативного.

## Полезные факты

- SCAIL-2 = Wan 2.1 14B, pose кодируется на ПОЛОВИННОМ разрешении.
- Ширина/высота — кратны 32 (иначе circular-pad артефакты).
- `SCAILAutoExtend`: чанки 81 кадр, overlap 5, color transfer Reinhard LAB
  между чанками (борьба с дрифтом цвета).
- Маски в SCAIL-2 — цветные: animation mode = pose-маска на ЧЁРНОМ фоне,
  ref-маска на БЕЛОМ; replacement — наоборот. 28-канальный поток.
- Ссылки на демо-видео в README WanAnimatePlus протухли (user-attachments).
- Загрузка на HF: `hf upload AiArtLab/video . --repo-type model` (auth: recoilme).

## Текущие артефакты

- `dealer_test2.mp4` — animation без масок (центр, иначе хорошо)
- `dealer_test3.mp4` — animation с масками (центр, маска не влияет на позицию)
- `dealer_repl.mp4` — replacement mode (мусор, см. выше)
- `mask_cache/` — 2 набора масок (animation + replacement варианты)
- `dealer/` — 4 фото дилера (портрет 3024×4032, EXIF ок)
- `drive.mp4` — тестовое видео (женщина в красном корсете, зелёный экран,
  81 кадр, 1280×720, 16 fps, персона слева)