README.md

---
title: HighQualityVideoGeneration
emoji: 🎬
colorFrom: blue
colorTo: purple
sdk: gradio
sdk_version: 6.0.1
app_file: app.py
pinned: false
short_description: Generate a short video from an image and a text prompt
---

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

## What this is

Image-to-video generation from [`thornmaze/WAMU_v3_WAN2.2_I2V_LIGHTNING`](https://huggingface.co/thornmaze/WAMU_v3_WAN2.2_I2V_LIGHTNING)
via `WanImageToVideoPipeline`, running on Hugging Face ZeroGPU.

## Post-processing

Two optional steps can run after generation:

| step | what | runs on |
|---|---|---|
| Frame interpolation ("Video Fluidity") | RIFE v4.26 (`thornmaze/RIFE`), half precision. 2x/4x/8x the native 16 fps. | GPU, inside the generation call |
| Upscaling ("Upscale 4×") | `4xLSDIRCompact` (SRVGGNetCompact, num_conv=16), fp16 on GPU (fp32 CPU fallback), tiled to bound peak memory. Fixed 4x. | GPU, inside the generation call |

Upscaling runs after interpolation, inside the same `@spaces.GPU` call as generation, so it bids for
ZeroGPU worker time like the rest of the pipeline (moved off the Space's shared CPU — see issue #11 —
to avoid CPU contention across concurrent visitors).

RIFE support code (`model/warplayer.py`, `model/loss.py`, `model/pytorch_msssim/`) is vendored from
[`hzwer/Practical-RIFE`](https://github.com/hzwer/Practical-RIFE) (MIT, see
[`LICENSES/RIFE-LICENSE`](LICENSES/RIFE-LICENSE)) — required as sibling-import targets for the
`train_log/RIFE_HDv3.py` module downloaded at runtime from `thornmaze/RIFE`.

The upscaling *code* (`postprocess/upscale/`) is vendored/adapted from
[`xinntao/Real-ESRGAN`](https://github.com/xinntao/Real-ESRGAN) (BSD-3-Clause License, see
[`LICENSES/REAL-ESRGAN-LICENSE`](LICENSES/REAL-ESRGAN-LICENSE)). The *weights* are
[`Phips/4xLSDIRCompact`](https://huggingface.co/Phips/4xLSDIRCompact) (CC BY 4.0, see
[`LICENSES/4xLSDIRCompact-LICENSE`](LICENSES/4xLSDIRCompact-LICENSE)), not Real-ESRGAN's own — see the
comment at the top of `postprocess/upscale/upscale.py` for why.

## Debug logging (optional)

Each inference call can optionally be logged (prompt, seed, generation/interpolation/upscale
settings, input image, pre-upscale output video, timing, success/error) to a private Hugging
Face Hub dataset repo. Disabled by default — nothing is logged until both secrets below are set.
Logging is based on legitimate interest (GDPR Art. 6(1)(f)), not consent — see the notice and
Privacy Policy shown in the app for details, including how to request access to or deletion of
your data. Configure independently per Space under *Settings → Variables and secrets*:

| variable | type | notes |
|---|---|---|
| `LOG_HF_TOKEN` | Secret | fine-grained token, write-only on the target dataset repo. Do **not** reuse the deploy `HF_TOKEN`. |
| `LOG_DATASET_REPO` | Secret | target dataset repo id; auto-created (private) on first log. |
| `LOG_STORAGE_CAP_GB` | Variable | total-storage retention cap; oldest entries pruned first once exceeded. Defaults to 10GB if unset — dev should set 50, prod 450. |
| `LOG_BATCH_INTERVAL` | Variable | seconds between batched log commits. Default 60. |

Logs are committed asynchronously in batches and never add latency to a generation request. The
logged video is the **pre-upscale** result (post-interpolation, before 4x super-resolution);
metadata references the image/video files by path rather than embedding them, so both stay
browsable/playable in the Hub dataset viewer.

## Status

Baseline (non-AOT) pipeline. AOT-compiled inference (faster, but requires a compatible
precompiled package for WAMU_v3) is tracked separately — see the repo's open issues.

LoRA loading is out of scope for this version (see SRS FR-8/C-4).