LiveWan

Steerable streaming text to video with a 1.3B parameter Wan2.1 student.

LiveWan generates 750 ms blocks of 640x368 video and can continue for about 4.3 minutes. Prompts can change without clearing the K/V cache, allowing the current scene to evolve instead of restarting.

Weights and data are available from JonathanColetti/LiveWan.

Demo

Try the Hugging Face Space. The previews are accelerated and link to recordings at normal speed.

Example	Preview	Full video
One continuous stream for 4 min 43 s	preview	video
Waterfall steered toward a lighthouse	preview	video
New world from a penguin sliding on snow	preview	video

Related prompts usually steer cleanly. Large changes can retain colours and shapes from the old scene because its K/V remains in context. Start a new scene when a clean cut is preferable.

Setup

Requirements:

• Linux and Python 3.10 or newer
• NVIDIA GPU with at least 12 GB VRAM
• Compute capability 8.0 or newer for bf16
• About 12 GB of disk for the minimum install or 29 GB for every feature

git clone https://github.com/JonathanColetti/LiveWan
cd LiveWan
python -m venv .venv
source .venv/bin/activate

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu128
pip install -e .
./setup.sh
livewan-serve

Open http://localhost:17070/?token=1234. The first start takes about 90 seconds while weights load and the VAE decoder compiles. Use --no-compile to skip compilation at a cost of about 50 ms per block.

setup.sh downloads assets into the repository. These features are optional:

SKIP_T5=1 ./setup.sh
SKIP_BASE=1 ./setup.sh

SKIP_T5 disables free text prompts but keeps the 96 prompt bank. SKIP_BASE disables new world generation and should be paired with --no-worldgen.

Paths can be changed with --assets, --base-dir, --wan-repo and --worlds-dir, or with the matching LIVEWAN_* environment variables.

For the environment used to produce the measurements below:

pip install torch==2.12.0 torchvision==0.27.0 --index-url https://download.pytorch.org/whl/cu130
pip install -r requirements-lock.txt
pip install -e . --no-deps

Troubleshooting

Symptom	Fix
no kernel image is available for execution	Install a torch wheel built for a newer CUDA version
CUDA out of memory at startup	Stop other GPU jobs or use --window 4
Missing Wan2.1_VAE.pth	Run setup.sh again or check --base-dir
World generation unavailable	Run setup without SKIP_BASE=1
Free text fails but bank prompts work	Run setup without SKIP_T5=1
401 unauthorized	Add ?token=1234 or the token passed to --token

Controls

Control	Behaviour	Cost
Steer	Changes text conditioning and keeps the K/V cache	Immediate
Scene	Clears the cache and opens another cached world	About 4 s

Every stream begins from a 21 latent frame world. A prompt controls what happens next; it does not create the opening frames. Use Scene > New scene from text to create a new opening world.

curl -X POST 'localhost:17070/api/world/new?token=1234' \
  -H 'Content-Type: application/json' \
  -d '{"prompt_text":"a lighthouse on a cliff in a storm","steps":30}'

Steps	Time on A100 40GB
20	about 35 s
30	about 52 s
50	about 87 s

Generated worlds retain their text conditioning, persist across restarts and can be deleted from the UI.

The browser also provides sharpen, contrast, saturation and brightness controls. These are display filters and do not change model output.

Access

The shared token protects HTTP and websocket routes.

livewan-serve --token 1234
livewan-serve --token ""

The default token is only suitable for local use. Use a long token or a reverse proxy when exposing the server publicly.

How it works

The checkpoint contains the stock 825 Wan2.1 1.3B tensors. Streaming is defined by the inference path in wanstreamer/:

• Block causal attention generates 3 latent frame blocks against cached history
• The world prefix stays pinned while old event frames are evicted
• Absolute temporal RoPE positions continue after cache eviction
• A clean context pass commits finished blocks to the K/V cache at t=0
• The renoise sampler uses the uniform few step schedule from distillation
• latent_norm keeps generated channel moments near the opening world

The VAE decoder also preserves its causal cache between blocks. This allows pixels to be emitted without decoding the full sequence again.

WanModel.freqs limits one stream to 1024 latent frames, or about 4.3 minutes.

Performance

Measured on an A100 40GB with bf16 and torch 2.12:

Stage	Time per block
Generate, 2 steps plus clean context	480 ms
Decode 12 frames with compiled VAE	343 ms
Total	about 823 ms for 750 ms of video

The K/V cache uses about 5.6 GB at --window 6. Reducing the window lowers memory at the cost of attention history.

Configuration	Peak or reserved VRAM
Bank prompts, --window 6	10.3 GB allocated, 14.5 GB reserved
Bank prompts, --window 4	11.0 GB reserved
Bank prompts, --window 2	9.7 GB reserved
Free text encoder	Adds 11.4 GB while resident
New world generation	13.0 GB peak with the base model resident

Training

The student was distilled for 3000 SF DMD iterations from a Wan2.1 T2V 14B teacher. Training used an effective batch of 64 on 8 H200 GPUs and took 41.6 hours at 66.5 seconds per iteration.

Step 3000 is the latest and only resumable checkpoint. Step 2250 is recommended for inference because it had less sharpness drift in the proxy evaluation. Compare their videos before treating the automatic metrics as a final quality judgment.

Chart data lives in docs/data/. Regenerate the figures with:

python3 scripts/eval/make_readme_charts.py

Project layout

Path	Contents
wanstreamer/	Streaming inference, attention, cache and RoPE
wanstreamer/serve/	Browser demo and world generation
scripts/train_dmd.py	SF DMD trainer
scripts/ and tools/	Training, evaluation and benchmarking utilities
docs/data/	Source data for the README charts

The Wan2.1 T2V 14B teacher and regenerated training data are not included. scripts/gen_teacher.py recreates the training samples.

Tests

python tests/test_streaming_core.py
python tests/test_attention_fallback.py
python tests/test_serve.py
python tests/test_auth.py

test_serve.py requires the GPU and can exceed 40 GB when the demo server is also running.

License

Apache 2.0. Derived from Wan2.1, also licensed under Apache 2.0. This is an unofficial community project and is not affiliated with Alibaba Group or the Wan Video team.