# RUN — как запускать генерацию

## Быстрый старт

```bash
cd /home/ubuntu/video
CUDA_VISIBLE_DEVICES=0 python3 generate.py \
  --pose drive.mp4 \
  --ref dealer/ \
  -o output.mp4 \
  --width 832 --height 480 \
  --steps 6 --shift 5 \
  --lora "lightx2v_I2V_14B_480p_cfg_step_distill_rank64_bf16.safetensors" \
  --lora-strength 0.8 \
  --fps 16 --mask \
  --positive "The person dances and gestures in a studio" \
  --negative ""
```

Время: ~1 мин SAM3-маски (только первый раз, дальше кэш) + ~1 мин загрузка моделей + ~1 мин генерация (81 кадр, 6 шагов).

## Обязательные параметры (критичные!)

| Параметр | Значение | Почему |
|---|---|---|
| `--shift` | 5 | Без ModelSamplingSD3 shift — мыльное пятно вместо видео |
| `--sampler` | euler (default) | Эталон из workflow автора |
| `--scheduler` | simple (default) | Эталон из workflow автора |
| `--steps` | 6 (default) | С distill-LoRA хватает; 20 без LoRA — хуже |
| `--lora` | lightx2v...rank64 | Distill LoRA, включает cfg=1 + мало шагов |
| `--lora-strength` | 0.8 | Как в workflow автора |
| `--negative` | "" | У автора пустой |

## Ключевые флаги

- `--ref` — файл ИЛИ директория. Директория = мультиреференс (первый по алфавиту = основной, остальные = доп. виды). Нативная поддержка SCAIL-2, до N изображений.
- `--mask` — SAM3-маски (pose_video_mask + reference_image_mask). Кэшируются в `./mask_cache/` по хэшу входных файлов. Повторный прогон — маски из кэша.
- `--replacement-mode` — режим замены (маски: белый фон для pose, чёрный для ref). С портретными рефами пока даёт мусор — см. NOTES.md.
- `--chunk-length 81 --overlap 5` — для видео >81 кадра идёт auto-extend чанками.
- `--max-frames N` — обрезать входное видео.
- `--seed` — для воспроизводимости. Внутри чанков seed инкрементируется.

## Типичные проблемы

- **Мыльное пятно** → забыл `--shift 5` или LoRA.
- **OOM при масках** → уже починено (inference_mode в masks.py); если повторится — не грузить ничего до SAM3.
- **Персона по центру вместо позиции из видео** → известная проблема animation mode, см. NOTES.md.
- GPU: работаем только на `cuda:0`. GPU 2–6 заняты чужой тренировкой (train-babka.py) — НЕ ТРОГАТЬ.

## Файлы проекта

- `generate.py` — основной скрипт (загрузка моделей → маски → генерация → mp4)
- `masks.py` — SAM3-маски с кэшем (single-person, max_objects=1)
- `composite.py` — crop-around-person + composite-back (написан, ещё НЕ подключён)
- `mask_cache/` — кэш масок (.pt)