When Numbers Speak: Aligning Textual Numerals and
Visual Instances in Text-to-Video Diffusion Models

NUMINA is a training-free framework that tackles numerical misalignment in text-to-video diffusion models — the persistent failure of T2V models to generate the correct count of objects specified in prompts (e.g., producing 2 or 4 cats when "three cats" is requested). Unlike seed search or prompt enhancement approaches that treat the generation pipeline as a black box and rely on brute-force resampling or LLM-based prompt rewriting, NUMINA directly identifies where and why counting errors occur inside the model by analyzing cross-attention and self-attention maps at selected DiT layers. It constructs a countable spatial layout via a two-stage clustering pipeline, then performs layout-guided attention modulation during regeneration to enforce the correct object count — all without retraining or fine-tuning. On our introduced CountBench, this attention-level intervention provides principled, interpretable control over numerical semantics that seed search and prompt enhancement fundamentally cannot achieve, improves counting accuracy by up to 7.4% on Wan2.1-1.3B. Furthermore, because NUMINA operates partly orthogonally to inference acceleration techniques, it is compatible with training-free caching methods such as EasyCache, which accelerates diffusion inference via runtime-adaptive transformer output reuse.

NUMINA is implemented as a lightweight add-on to Wan2.1. You can set up the environment and integrate the modules by running the following commands:

# Clone Wan2.1 repo
git clone https://github.com/Wan-Video/Wan2.1.git
cd Wan2.1
# From within the Wan2.1 root directory
git clone https://github.com/H-EmbodVis/NUMINA.git numina_repo
# Copy NUMINA modules
cp -r numina_repo/numina ./numina
# Apply modifications to Wan2.1 files
cp numina_repo/wan/modules/attention.py ./wan/modules/attention.py
cp numina_repo/wan/modules/model.py ./wan/modules/model.py
cp numina_repo/wan/text2video.py ./wan/text2video.py
cp numina_repo/generate.py ./generate.py
# install dependencies
pip install -r numina_repo/requirements.txt

Please follow the Wan2.1 README for model checkpoint downloads and any platform-specific setup (e.g., FlashAttention).

Wan2.1/
├── ...
├── numina/ # NUMINA modules (new)
│ ├── __init__.py
│ ├── config.py # All hyperparameters
│ ├── token_mapper.py # Nouns → T5 token index mapping
│ ├── head_selection.py # attention head scoring
│ ├── layout.py # MeanShift + DBSCAN layout pipeline
│ └── modulation.py # Cross-attention bias for SDPA
├── wan/
│ ├── ...
│ ├── modules/
│ │ ├── ...
│ │ ├── attention.py # Modified: extraction + modulation paths
│ │ └── model.py # Modified: NUMINA state propagation
│ └── text2video.py # Modified: two-phase pipeline
└── generate.py # Modified: --numina CLI arguments

Modified Wan2.1 files (4 files):

• wan/modules/attention.py — Added manual attention for extraction + SDPA for modulation
• wan/modules/model.py — Added NUMINA state management and routing
• wan/text2video.py — Added generate_numina() two-phase pipeline with EasyCache integrated
• generate.py — Added NUMINA CLI arguments

python generate.py \
 --task t2v-1.3B \
 --ckpt_dir /path/to/Wan2.1-T2V-1.3B \
 --prompt "Three men are walking in the park." \
 --numina \
 --numina_noun_counts '{"men": 3}' \
 --size 832*480

For all other arguments (--offload_model, --t5_cpu, --sample_guide_scale, --base_seed, etc.), please refer to the Wan2.1 documentation.

This project is built on top of Wan2.1 by the Alibaba Wan Team.
Phase 1 pre-generation acceleration uses the EasyCache runtime-adaptive caching strategy.

If you find this repository useful in your research, please consider giving us a star ⭐ and a citation.

@inproceedings{sun2026numina,
 title={When Numbers Speak: Aligning Textual Numerals and Visual Instances in Text-to-Video Diffusion Models},
 author={Sun, Zhengyang and Chen, Yu and Zhou, Xin and Li, Xiaofan and Chen, Xiwu and Liang, Dingkang and Bai, Xiang},
 booktitle={Proc. of IEEE Intl. Conf. on Computer Vision and Pattern Recognition},
 year={2026}
}