smithcooly2k odb9402 commited on
Commit
ef28144
·
0 Parent(s):

Duplicate from Motif-Technologies/Motif-Video-2B

Browse files

Co-authored-by: Dongpin oh <odb9402@users.noreply.huggingface.co>

.gitattributes ADDED
@@ -0,0 +1,52 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ *.7z filter=lfs diff=lfs merge=lfs -text
2
+ *.arrow filter=lfs diff=lfs merge=lfs -text
3
+ *.bin filter=lfs diff=lfs merge=lfs -text
4
+ *.bz2 filter=lfs diff=lfs merge=lfs -text
5
+ *.ckpt filter=lfs diff=lfs merge=lfs -text
6
+ *.ftz filter=lfs diff=lfs merge=lfs -text
7
+ *.gz filter=lfs diff=lfs merge=lfs -text
8
+ *.h5 filter=lfs diff=lfs merge=lfs -text
9
+ *.joblib filter=lfs diff=lfs merge=lfs -text
10
+ *.lfs.* filter=lfs diff=lfs merge=lfs -text
11
+ *.mlmodel filter=lfs diff=lfs merge=lfs -text
12
+ *.model filter=lfs diff=lfs merge=lfs -text
13
+ *.msgpack filter=lfs diff=lfs merge=lfs -text
14
+ *.npy filter=lfs diff=lfs merge=lfs -text
15
+ *.npz filter=lfs diff=lfs merge=lfs -text
16
+ *.onnx filter=lfs diff=lfs merge=lfs -text
17
+ *.ot filter=lfs diff=lfs merge=lfs -text
18
+ *.parquet filter=lfs diff=lfs merge=lfs -text
19
+ *.pb filter=lfs diff=lfs merge=lfs -text
20
+ *.pickle filter=lfs diff=lfs merge=lfs -text
21
+ *.pkl filter=lfs diff=lfs merge=lfs -text
22
+ *.pt filter=lfs diff=lfs merge=lfs -text
23
+ *.pth filter=lfs diff=lfs merge=lfs -text
24
+ *.rar filter=lfs diff=lfs merge=lfs -text
25
+ *.safetensors filter=lfs diff=lfs merge=lfs -text
26
+ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
27
+ *.tar.* filter=lfs diff=lfs merge=lfs -text
28
+ *.tar filter=lfs diff=lfs merge=lfs -text
29
+ *.tflite filter=lfs diff=lfs merge=lfs -text
30
+ *.tgz filter=lfs diff=lfs merge=lfs -text
31
+ *.wasm filter=lfs diff=lfs merge=lfs -text
32
+ *.xz filter=lfs diff=lfs merge=lfs -text
33
+ *.zip filter=lfs diff=lfs merge=lfs -text
34
+ *.zst filter=lfs diff=lfs merge=lfs -text
35
+ *tfevents* filter=lfs diff=lfs merge=lfs -text
36
+ assets/architecture.png filter=lfs diff=lfs merge=lfs -text
37
+ assets/banner.png filter=lfs diff=lfs merge=lfs -text
38
+ assets/showcase_i2v.png filter=lfs diff=lfs merge=lfs -text
39
+ assets/showcase_t2v.png filter=lfs diff=lfs merge=lfs -text
40
+ tokenizer/tokenizer.json filter=lfs diff=lfs merge=lfs -text
41
+ assets/i2v_sample.jpg filter=lfs diff=lfs merge=lfs -text
42
+ motif-video-technical-report.pdf filter=lfs diff=lfs merge=lfs -text
43
+ assets/astronaut.mp4 filter=lfs diff=lfs merge=lfs -text
44
+ assets/bird.mp4 filter=lfs diff=lfs merge=lfs -text
45
+ assets/fisherman.mp4 filter=lfs diff=lfs merge=lfs -text
46
+ assets/underwater.mp4 filter=lfs diff=lfs merge=lfs -text
47
+ assets/vows.mp4 filter=lfs diff=lfs merge=lfs -text
48
+ assets/woman.mp4 filter=lfs diff=lfs merge=lfs -text
49
+ assets/sage_compare_BF16.webp filter=lfs diff=lfs merge=lfs -text
50
+ assets/sage_compare_Q4_K_M.webp filter=lfs diff=lfs merge=lfs -text
51
+ assets/sage_compare_Q5_K_M.webp filter=lfs diff=lfs merge=lfs -text
52
+ assets/sage_compare_Q8_0.webp filter=lfs diff=lfs merge=lfs -text
.gitignore ADDED
The diff for this file is too large to render. See raw diff
 
README.md ADDED
@@ -0,0 +1,396 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ license: apache-2.0
3
+ language:
4
+ - en
5
+ tags:
6
+ - text-to-video
7
+ - image-to-video
8
+ - video-generation
9
+ - diffusion-transformer
10
+ pipeline_tag: text-to-video
11
+ library_name: diffusers
12
+ widget:
13
+ - text: "A vibrant blue jay perches gracefully on a slender branch, its feathers shimmering in the soft morning light. The bird's keen eyes scan the surroundings, capturing the essence of the tranquil forest. It flutters its wings briefly, showcasing the intricate patterns of blue, white, and black on its plumage. The background reveals a lush canopy of green leaves, with rays of sunlight filtering through, creating a dappled effect on the forest floor. The blue jay then tilts its head, emitting a melodious call that echoes through the serene woodland, adding a touch of magic to the peaceful scene."
14
+ output:
15
+ url: assets/bird.mp4
16
+ - text: "Underwater footage of a vibrant coral reef ecosystem with tropical fish swimming through coral formations. Natural sunlight filtering down through clear water creates dancing light patterns on the reef. Smooth underwater camera movement, natural color correction preserving authentic ocean blues and coral colors, documentary marine biology style, peaceful and educational mood."
17
+ output:
18
+ url: assets/underwater.mp4
19
+ - text: "An old fisherman mends his nets on a stone harbor wall, weathered hands moving with practiced speed through the green mesh. Shot on a 50mm lens with a slow dolly-in from his side, the afternoon sun throws warm light across his salt-stained coat and the worn granite beneath him. Behind him, a single wooden boat bobs gently in a turquoise bay. Gulls drift through the distant sky in soft focus. The camera settles on his hands, then racks focus to his weathered, squinting eyes."
20
+ output:
21
+ url: assets/fisherman.mp4
22
+ - text: "A lone astronaut drifts just outside a derelict space station, tethered by a single silver line as Earth's terminator glows blue-white behind her. Shot with a slow wide-to-medium push, the camera floats alongside her in weightless silence, the curvature of the planet filling the lower third of the frame. Sunlight rakes across the hull's scarred panels, casting long hard shadows that stretch and shift as she rotates. Her visor reflects the aurora below, ribbons of green pulling across the glass. She reaches out with a gloved hand and lets her fingertips graze a dented antenna, the gesture small and reverent."
23
+ output:
24
+ url: assets/astronaut.mp4
25
+ - text: "A woman standing in a sunlit field as flower petals swirl around her in slow motion. Each petal floats gently through the golden light, casting tiny shadows. Her hair moves like water, and time seems to stand still."
26
+ output:
27
+ url: assets/woman.mp4
28
+ ---
29
+
30
+ <p align="center">
31
+ <img src="assets/banner.png" width="100%" alt="Motif-Video 2B teaser"/>
32
+ </p>
33
+
34
+ <p align="center">
35
+ <h1 align="center">Motif-Video 2B</h1>
36
+ </p>
37
+
38
+ <p align="center">
39
+ <b>A micro-budget text-to-video diffusion transformer from Motif Technologies</b>
40
+ </p>
41
+
42
+ <p align="center">
43
+ 📑 <a href="https://arxiv.org/abs/2604.16503">Technical Report</a> &nbsp;|&nbsp;
44
+ 🤗 <a href="">Hugging Face</a> &nbsp;|&nbsp;
45
+ 🌐 <a href="https://motiftech.io/videoshowcase">Project Page</a>
46
+ </p>
47
+
48
+ ---
49
+
50
+ <!--
51
+ NOTE: This README is written against the CURRENT state of diffusers PR #13551
52
+ (pre-merge). The PR currently has issues:
53
+ - negative_prompt defaults to None (should be built-in)
54
+ - use_linear_quadratic_schedule defaults to True (should be False)
55
+ - DPMSolverMultistepScheduler crashes (pipeline always passes sigmas)
56
+ - No built-in SageAttention support (requires manual patching)
57
+
58
+ Code examples below include workarounds (explicit negative_prompt,
59
+ use_linear_quadratic_schedule=False, _FlowDPMSolver subclass).
60
+
61
+ TODO: Update after PR feedback is applied, and again after merge.
62
+ Tracking: https://github.com/MotifTechnologies/diffusers/pull/1
63
+ -->
64
+
65
+ ## 🔥 News
66
+
67
+ - **[2026-04-29]** **RTX 4090 benchmarks** added — SageAttention achieves ~3.16× speedup, all GGUF variants fit in 24 GB. See [GGUF + SageAttention](docs/gguf-sageattention.md#benchmark).
68
+ - **[2026-04-28]** **ComfyUI custom nodes** released: [ComfyUI-MotifVideo2B](https://github.com/MotifTechnologies/ComfyUI-MotifVideo2B). GGUF workflow support coming soon.
69
+ - **[2026-04-28]** **GGUF quantized weights** now available at [Motif-Video-2B-GGUF](https://huggingface.co/Motif-Technologies/Motif-Video-2B-GGUF) — up to 2.7 GB VRAM savings with no speed penalty. **SageAttention** support for ~2× faster inference. See [GGUF + SageAttention](#🧊-gguf--sageattention) below.
70
+ - **[2026-04-14]** We release **Motif-Video 2B**, our 2B-parameter text-to-video and image-to-video diffusion transformer, together with the full [technical report](https://arxiv.org/abs/2604.16503).
71
+
72
+ ---
73
+
74
+ ## 📖 Introduction
75
+
76
+ Training strong video generation models usually requires massive datasets, large parameter counts, and substantial compute. **Motif-Video 2B** asks whether competitive text-to-video quality is reachable at a much smaller budget — fewer than **10M training clips** and under **100,000 H200 GPU hours** — and shows that the answer is yes, provided the model design explicitly separates objectives that scaling would otherwise leave entangled.
77
+
78
+ Our central observation is that prompt alignment, temporal consistency, and fine-detail recovery interfere with one another when handled through the same pathway. Motif-Video 2B addresses this **objective interference** architecturally rather than relying on scale alone, through two contributions:
79
+
80
+ - **Shared Cross-Attention.** A residual cross-attention mechanism that reuses self-attention K/V weights to stabilize text–video alignment under long-context token sparsity, where standard joint attention dilutes text influence as the video token sequence grows.
81
+ - **Three-stage DDT-style backbone.** 12 dual-stream + 16 single-stream + 8 DDT decoder layers, separating early modality fusion, joint representation learning, and high-frequency detail reconstruction into dedicated components. Per-block attention analysis shows that the DDT decoder spontaneously develops inter-frame attention structure absent from the encoder layers.
82
+
83
+ These are paired with a micro-budget training recipe combining **TREAD token routing** and early-phase **REPA** with a frozen **V-JEPA** teacher — to our knowledge, the first time this combination has been applied to text-to-video training.
84
+
85
+ On VBench, Motif-Video 2B reaches **83.76%**, the highest Total Score among open-source models we evaluate, surpassing Wan2.1-14B at **7× fewer parameters** and roughly an order of magnitude less training data.
86
+
87
+ <!--
88
+ Architecture figure — replace with Figure 2 from the technical report
89
+ (the three-stage backbone + Shared Cross-Attention diagram).
90
+ -->
91
+ <p align="center">
92
+ <img src="assets/architecture.png" width="90%" alt="Motif-Video 2B architecture"/>
93
+ </p>
94
+
95
+ ---
96
+
97
+ ## ✨ Highlights
98
+
99
+ - **Two tasks, one set of weights.** A single checkpoint handles both **text-to-video (T2V)** and **image-to-video (I2V)** generation, trained jointly without a learnable task-type embedding.
100
+ - **Up to 720p, 121 frames.** The final model generates 720p video at 121 frames under the standard rectified flow-matching sampler.
101
+ - **Architectural specialization over brute-force scale.** Three-stage backbone with role-separated dual-stream / single-stream / DDT decoder layers.
102
+ - **Shared Cross-Attention.** Stabilizes text alignment under long video-token sequences by grounding cross-attention K/V in the self-attention manifold.
103
+ - **Micro-budget recipe.** TREAD token routing (≈27% per-step FLOP reduction) + early-phase REPA with V-JEPA teacher + offline bucket-balanced sampler (≈90% data utilization, up from ≈20% baseline).
104
+ - **Open and reproducible.** Trained on ~64×H200 GPUs with FSDP2, full curriculum and recipe documented in the technical report.
105
+
106
+ ---
107
+
108
+ ## 🏗️ Architecture
109
+
110
+ Motif-Video 2B is a flow-matching diffusion transformer organized around a single principle: each component is assigned a well-defined responsibility, and components with conflicting objectives are not asked to share capacity.
111
+
112
+ | Component | Choice |
113
+ |---|---|
114
+ | Text encoder | T5Gemma2 (encoder–decoder, UL2-adapted Gemma 3) |
115
+ | Video tokenizer | Wan2.1 VAE (8×8 spatial, 4× temporal compression), 2×2×1 patchify |
116
+ | Backbone | 12 dual-stream + 16 single-stream + 8 DDT decoder layers |
117
+ | Hidden dim / heads | 1536 / 12 heads × 128 |
118
+ | Normalization | QK-normalization throughout |
119
+ | Position encoding | RoPE |
120
+ | Cross-attention | **Shared Cross-Attention** in the single-stream stage |
121
+ | Objective | Rectified flow matching (velocity prediction) |
122
+ | I2V conditioning | First-frame latent + SigLIP image embeddings, with timestep-aware blur |
123
+
124
+ A high-level walkthrough of the role separation:
125
+
126
+ 1. **Dual-stream stage (12 layers).** Text and video tokens are processed through separate self-attention pathways, exchanging information via cross-attention. This prevents premature feature entanglement before either modality has formed coherent representations.
127
+ 2. **Single-stream stage (16 layers).** Text and video tokens attend freely in a joint sequence. **Shared Cross-Attention** is attached here to repair the text-attention dilution that emerges as the video token sequence grows.
128
+ 3. **DDT decoder (8 layers).** A dedicated velocity decoder atop the 28-layer encoder, freeing the encoder from high-frequency detail reconstruction. Per-block attention analysis shows that the DDT decoder develops inter-frame attention structure that single-stream layers do not.
129
+
130
+ For the full derivation of why Shared Cross-Attention shares K/V but not Q, and why this is necessary in addition to standard zero-init of W_O, see Section 3.3 of the [technical report](https://arxiv.org/abs/2604.16503).
131
+
132
+ <!--
133
+ Optional: insert Figure 3 (attention heatmaps across the three stages)
134
+ here as a secondary architecture figure. It is the strongest visual
135
+ evidence for the role-separation argument.
136
+ -->
137
+
138
+ ---
139
+
140
+ ## 🚀 Quickstart / Usage
141
+
142
+ ### Requirements
143
+
144
+ - Python 3.10+
145
+ - CUDA-capable GPU with **30GB+ VRAM** (e.g., A100, H100) — for 24GB GPUs see [Memory-efficient Inference](🔋-memory-efficient-inference)
146
+
147
+ ```bash
148
+ pip install "transformers>=5.5.4" torch accelerate ftfy einops sentencepiece regex Pillow imageio imageio-ffmpeg
149
+ pip install git+https://github.com/waitingcheung/diffusers.git@feat/motif-video
150
+ ```
151
+
152
+ ### Text-to-Video (T2V)
153
+
154
+ ```python
155
+ import torch
156
+ from diffusers import (
157
+ AdaptiveProjectedGuidance,
158
+ DPMSolverMultistepScheduler,
159
+ MotifVideoPipeline,
160
+ )
161
+ from diffusers.utils import export_to_video
162
+
163
+
164
+ guider = AdaptiveProjectedGuidance(
165
+ guidance_scale=8.0,
166
+ adaptive_projected_guidance_rescale=12.0,
167
+ adaptive_projected_guidance_momentum=0.1,
168
+ use_original_formulation=True,
169
+ normalization_dims="spatial",
170
+ )
171
+
172
+ pipe = MotifVideoPipeline.from_pretrained(
173
+ "Motif-Technologies/Motif-Video-2B",
174
+ torch_dtype=torch.bfloat16,
175
+ guider=guider,
176
+ )
177
+ pipe = pipe.to("cuda")
178
+
179
+ output = pipe(
180
+ prompt="A woman standing in a sunlit field as flower petals swirl around her in slow motion. Each petal floats gently through the golden light, casting tiny shadows. Her hair moves like water, and time seems to stand still.",
181
+ negative_prompt="text overlay, graphic overlay, watermark, logo, subtitles, timestamp, broadcast graphics, UI elements, random letters, frozen pose, rigid, static expression, jerky motion, mechanical motion, discontinuous motion, flat framing, depthless, dull lighting, monotone, crushed shadows, blown-out highlights, shifting background, fading background, poor continuity, identity drift, deformation, flickering, ghosting, smearing, duplication, mutated proportions, inconsistent clothing, flat colors, desaturated, tonally compressed, poor background separation, exposure shift, uneven brightness, color balance shift",
182
+ height=736,
183
+ width=1280,
184
+ num_frames=121,
185
+ num_inference_steps=50,
186
+ frame_rate=24,
187
+ )
188
+
189
+ export_to_video(output.frames[0], "output.mp4", fps=24)
190
+ ```
191
+
192
+ ### Image-to-Video (I2V)
193
+
194
+ ```python
195
+ import torch
196
+ from diffusers import (
197
+ AdaptiveProjectedGuidance,
198
+ DPMSolverMultistepScheduler,
199
+ MotifVideoPipeline,
200
+ )
201
+ from diffusers.utils import export_to_video, load_image
202
+
203
+ guider = AdaptiveProjectedGuidance(
204
+ guidance_scale=8.0,
205
+ adaptive_projected_guidance_rescale=12.0,
206
+ adaptive_projected_guidance_momentum=0.1,
207
+ use_original_formulation=True,
208
+ normalization_dims="spatial",
209
+ )
210
+
211
+ pipe = MotifVideoImage2VideoPipeline.from_pretrained(
212
+ "Motif-Technologies/Motif-Video-2B",
213
+ torch_dtype=torch.bfloat16,
214
+ guider=guider,
215
+ )
216
+ pipe = pipe.to("cuda")
217
+
218
+ image = load_image("https://huggingface.co/Motif-Technologies/Motif-Video-2B/resolve/main/assets/i2v_sample.jpg")
219
+
220
+ output = pipe(
221
+ prompt="Three friends stride through a sun-bleached meadow as a warm breeze ripples the tall dry grass around their legs.",
222
+ negative_prompt="text overlay, graphic overlay, watermark, logo, subtitles, timestamp, broadcast graphics, UI elements, random letters, frozen pose, rigid, static expression, jerky motion, mechanical motion, discontinuous motion, flat framing, depthless, dull lighting, monotone, crushed shadows, blown-out highlights, shifting background, fading background, poor continuity, identity drift, deformation, flickering, ghosting, smearing, duplication, mutated proportions, inconsistent clothing, flat colors, desaturated, tonally compressed, poor background separation, exposure shift, uneven brightness, color balance shift",
223
+ image=image,
224
+ height=736,
225
+ width=1280,
226
+ num_frames=121,
227
+ num_inference_steps=50,
228
+ frame_rate=24,
229
+ )
230
+
231
+ export_to_video(output.frames[0], "output.mp4", fps=24)
232
+ ```
233
+
234
+ ### CLI Inference
235
+
236
+ ```bash
237
+ # Text-to-Video (default settings)
238
+ python inference.py \
239
+ --prompt "A woman standing in a sunlit field as..." \
240
+ --output t2v_output.mp4
241
+
242
+ # With SageAttention (~2x faster, requires sageattention package)
243
+ python inference.py \
244
+ --prompt "Three friends stride through a sun-bleached meadow..." \
245
+ --use-sage-attention \
246
+ --output t2v_output.mp4
247
+ ```
248
+
249
+ See `inference.py --help` for all available options.
250
+
251
+ ### Recommended Settings
252
+
253
+ | Parameter | Default | Notes |
254
+ |---|---|---|
255
+ | Resolution | 1280×736 | 720p, best quality |
256
+ | Frames | 121 | ~5 seconds at 24fps |
257
+ | Scheduler | DPMSolver++ | `solver_order=2`, `flow_shift=15.0` |
258
+ | Guidance scale | 8.0 | With APG (`normalization_dims="spatial"`) |
259
+ | Inference steps | 50 | |
260
+ | Negative prompt | (built-in) | See code examples above |
261
+ | `use_linear_quadratic_schedule` | `False` | Must be set explicitly |
262
+ | dtype | bfloat16 | Recommended for H100/A100 |
263
+
264
+ ### 🔋 Memory-efficient Inference
265
+
266
+ For GPUs with 24 GB or less (e.g. RTX 4090, RTX 3090), CPU offloading and FP8 quantization can reduce peak VRAM from ~30 GB to ~15 GB with minimal speed impact.
267
+
268
+ | Mode | Peak VRAM | Recommended GPU |
269
+ |------|-----------|-----------------|
270
+ | `pipe.to("cuda")` | ~30 GB | A100, H100, H200 |
271
+ | `enable_model_cpu_offload()` | ~19 GB | RTX 4090, RTX 3090 |
272
+ | `+ FP8 quantization` | ~15 GB | RTX 4090, RTX 3090 |
273
+
274
+ > **Full guide** → [docs/memory-efficient-inference.md](docs/memory-efficient-inference.md)
275
+
276
+ ---
277
+
278
+ ### 🧊 GGUF + SageAttention
279
+
280
+ GGUF quantized weights at [Motif-Video-2B-GGUF](https://huggingface.co/Motif-Technologies/Motif-Video-2B-GGUF) — up to 2.7 GB VRAM savings with no speed penalty. Combined with [SageAttention](https://github.com/thu-ml/SageAttention) for ~1.6× faster inference.
281
+
282
+ | Variant | Sage (s/it) | Speedup | Peak alloc (GB) |
283
+ |---------|------------|---------|-----------------|
284
+ | BF16 | 14.75 | 1.58x | 15.12 |
285
+ | Q8_0 | 14.49 | 1.60x | 13.44 |
286
+ | Q4_K_M | 14.59 | 1.60x | 12.53 |
287
+
288
+ > **Full guide** → [docs/gguf-sageattention.md](docs/gguf-sageattention.md)
289
+
290
+ ---
291
+
292
+ ### 🖥️ ComfyUI
293
+
294
+ Official ComfyUI custom nodes: [ComfyUI-MotifVideo2B](https://github.com/MotifTechnologies/ComfyUI-MotifVideo2B)
295
+
296
+ > **Note:** Currently requires **High VRAM** mode. GGUF quantized model loading in ComfyUI is in progress.
297
+
298
+ ---
299
+
300
+ ## 📊 Performance
301
+
302
+ ### VBench
303
+
304
+ Motif-Video 2B achieves the highest **Total Score** among open-source models we evaluate.
305
+
306
+ | Model | Params | Total | Quality | Semantic |
307
+ |---|---|---|---|---|
308
+ | Wan2.2-T2V (prompt-opt.) | A14B | 84.23 | 85.42 | 79.50 |
309
+ | **Motif-Video 2B (Ours)** | **2B** | **83.76** | **84.59** | **80.44** |
310
+ | SANA-Video | 2B | 83.71 | 84.35 | 81.35 |
311
+ | Wan2.1-T2V | 14B | 83.69 | 85.59 | 76.11 |
312
+ | OpenSora 2.0 (T2I2V) | 11B | 83.60 | 84.40 | 80.30 |
313
+ | Wan2.1-T2V | 1.3B | 83.31 | 85.23 | 75.65 |
314
+ | HunyuanVideo | 13B | 83.24 | 85.09 | 75.82 |
315
+ | CogVideoX1.5-5B (prompt-opt.) | 5B | 82.17 | 82.78 | 79.76 |
316
+ | Step-Video-T2V | 30B | 81.83 | 84.46 | 71.28 |
317
+ | LTX-Video | 2B | 80.00 | 82.30 | 70.79 |
318
+
319
+ Notable per-dimension highlights for Motif-Video 2B (open-source):
320
+
321
+ - **Spatial Relationship: 83.02%** — best among open-source models
322
+ - **Semantic Score: 80.44%** — highest among open-source models reporting per-dimension results
323
+ - **Object Class: 92.93%**, **Multiple Objects: 77.29%**, **Imaging Quality: 70.50%** — second-best in their categories
324
+
325
+ The full 16-dimension breakdown is in Table 3 of the [technical report](https://arxiv.org/abs/2604.16503).
326
+
327
+ > **A note on VBench vs. perceptual quality.** Motif-Video 2B leads on VBench Total Score, but in our internal side-by-side comparisons against Wan2.1-T2V-14B we observe a perceptual gap in favor of the larger model on temporal stability and fine human anatomy. We discuss the sources of this gap (uniform dimension weighting, near-correct semantic credit) in Section 7 of the report. We report the gap explicitly rather than smoothing it over.
328
+
329
+ ### Human evaluation
330
+
331
+ In a blind pairwise study against six contemporaneous open-source baselines (SANA-Video, LTX-Video 2, Wan2.1-14B, Wan2.1-1.3B, Wan2.2-5B, CogVideoX-5B) on 40 LLM-generated prompts, Motif-Video 2B is preferred over both **SANA-Video** (similar parameter count) and **Wan2.1-1.3B** (similar parameter count, larger training corpus) on prompt-following and video-fidelity axes. Wan2.1-14B remains the preferred model overall, consistent with its 7× larger parameter count and substantially larger training data.
332
+
333
+ ---
334
+
335
+ ## 🎬 Showcase
336
+
337
+ <!--
338
+ Insert the qualitative grids from the technical report here:
339
+ - Figure 1 / Figure 12: T2V multi-prompt frame strips
340
+ - Figure 13: I2V example (input image + generated frames)
341
+ Use full-width or 2-column layout, matching Wan2.1's "Showcase" section.
342
+ -->
343
+
344
+ ### Text-to-Video
345
+
346
+ <p align="center">
347
+ <img src="assets/showcase_t2v.png" width="100%" alt="Motif-Video 2B T2V samples"/>
348
+ </p>
349
+
350
+ ### Image-to-Video
351
+
352
+ <p align="center">
353
+ <img src="assets/showcase_i2v.png" width="100%" alt="Motif-Video 2B I2V samples"/>
354
+ </p>
355
+
356
+ ---
357
+
358
+ ## ⚠️ Limitations
359
+
360
+ We report limitations as the boundary conditions under which the design decisions in this report should be interpreted, not as caveats.
361
+
362
+ - **Micro-scale semantic distortion.** Motif-Video 2B occasionally produces sub-object-level artifacts that leave the category label intact but break perceptual plausibility — distorted hands on close-up human subjects, degraded body structure under high-displacement motion, and attribute leakage between visually similar co-present subjects. We attribute these primarily to data coverage rather than backbone design.
363
+ - **Temporal failures.** Three distinct modes that frame-level metrics do not surface: (i) physically implausible liquid / cloth / collision dynamics, (ii) coherence loss under high scene complexity (multi-agent crowds), and (iii) unintended mid-clip scene transitions in long sequences.
364
+ - **Recipe components are evaluated jointly, not in isolation.** We do not present per-component ablations for Shared Cross-Attention, the DDT decoder, REPA phasing, or TREAD routing at full scale. Readers should interpret our results as evidence that the *composed* recipe works at 2B, not as a marginal-contribution claim about any single component.
365
+
366
+ We view temporal stability and data coverage — not architectural depth — as the primary remaining ceilings on this model. Both are the most natural axes for a future iteration that the current architecture is built to absorb.
367
+
368
+ ---
369
+
370
+ ## 📚 Citation
371
+
372
+ If you find Motif-Video 2B useful in your research, please cite:
373
+
374
+ ```bibtex
375
+ @techreport{motifvideo2b2026,
376
+ title = {Motif-Video 2B: Technical Report},
377
+ author = {Motif Technologies},
378
+ year = {2026},
379
+ institution = {Motif Technologies},
380
+ url = {https://arxiv.org/abs/2604.16503}
381
+ }
382
+ ```
383
+
384
+ ---
385
+
386
+ ## 🙏 Acknowledgements
387
+
388
+ We build on a number of excellent open-source projects, including the **Wan2.1 VAE** [Wan Team, 2025], **T5Gemma / Gemma 3** [Google], **TREAD** [Krause et al., 2025], **REPA** with the **V-JEPA** family of visual encoders [Bardes et al.], **DDT** [Wang et al.], and the broader **diffusers** and **Accelerate** ecosystems. Compute was provisioned on Microsoft Azure and orchestrated with **SkyPilot** on Kubernetes.
389
+
390
+ ---
391
+
392
+ ## 📄 License
393
+
394
+ <!-- TODO: confirm final license — apache-2.0 placeholder above. -->
395
+
396
+ This model is released under the Apache 2.0 License. See `LICENSE` for details.
assets/architecture.png ADDED

Git LFS Details

  • SHA256: 33f619ed4c78c185e5e40fec1b774dee5573e3f8f3a405785ebe9552b2a02c33
  • Pointer size: 131 Bytes
  • Size of remote file: 260 kB
assets/astronaut.mp4 ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:5c13fd69a91c40ce217162e1bee917c23b86fcd878301bcab11a48fcd3bfeded
3
+ size 1020141
assets/banner.png ADDED

Git LFS Details

  • SHA256: c01efdcc5579a31fb8926717fbc8ef24c317c9e2d852b4c084132b60da1ca602
  • Pointer size: 132 Bytes
  • Size of remote file: 7.57 MB
assets/bird.mp4 ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:ceddcad73d270f8a03a5bfa5ab6cc3dc74c9b1ff3db3a652151b5c26efd36e9c
3
+ size 757207
assets/fisherman.mp4 ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:4e67764b0104e66ec56dab3cc216f3887aef84d25f3bb7758443de1b8624c745
3
+ size 1506256
assets/i2v_sample.jpg ADDED

Git LFS Details

  • SHA256: a3709a6989fc201b9c4332eadc30d34b365a41ef300f6bf5ecc1fdc40a7c8969
  • Pointer size: 131 Bytes
  • Size of remote file: 378 kB
assets/sage_compare_BF16.webp ADDED

Git LFS Details

  • SHA256: c6de38ff09e335e7c33e7de359418b27de30af05b63d08f0d9ec521bfb7a583f
  • Pointer size: 132 Bytes
  • Size of remote file: 6.53 MB
assets/sage_compare_Q4_K_M.webp ADDED

Git LFS Details

  • SHA256: 6e7625ab6be438419a421f35f297963c80e1314e9cffdbbfe2fe9438966046cf
  • Pointer size: 132 Bytes
  • Size of remote file: 6.03 MB
assets/sage_compare_Q5_K_M.webp ADDED

Git LFS Details

  • SHA256: d4698ccf9716113f605de3a4d2e5ccff24dddfb9b34279a0a05da416a9e701d6
  • Pointer size: 132 Bytes
  • Size of remote file: 6.83 MB
assets/sage_compare_Q8_0.webp ADDED

Git LFS Details

  • SHA256: e4d15be42c5aa4cff9398a6b24922d7473a9815210651072f8ea4059fe288d7f
  • Pointer size: 132 Bytes
  • Size of remote file: 6.4 MB
assets/showcase_i2v.png ADDED

Git LFS Details

  • SHA256: 2b605ed63797b53532df7a0a52e1168c7847b3f2e6c5c4a4dfad0b901648c2f7
  • Pointer size: 133 Bytes
  • Size of remote file: 11.4 MB
assets/showcase_t2v.png ADDED

Git LFS Details

  • SHA256: c78f3dd58ad8562a082275a955bbbfbfc85cb7e48ce3c28ca55fb1fb625ef139
  • Pointer size: 132 Bytes
  • Size of remote file: 3.85 MB
assets/underwater.mp4 ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:184b72b8672bca924bf8f0b568488daac507eafd8dd8ddcb15f9928549309550
3
+ size 2024562
assets/woman.mp4 ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:2aa2e93ccc2d333f26323a0944e4a3e9c0ee3064824ae23b245f5ab2c548a947
3
+ size 2057707
docs/gguf-sageattention.md ADDED
@@ -0,0 +1,166 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # 🧊 GGUF + SageAttention
2
+
3
+ > See the main [README](../README.md) for `FlowDPMSolver` and pipeline setup.
4
+
5
+ GGUF quantized transformer weights are available at [Motif-Video-2B-GGUF](https://huggingface.co/Motif-Technologies/Motif-Video-2B-GGUF), reducing VRAM with minimal quality loss. Combined with [SageAttention](https://github.com/thu-ml/SageAttention) for ~2× faster attention computation.
6
+
7
+ ## GGUF Inference
8
+
9
+ ```bash
10
+ pip install gguf
11
+ ```
12
+
13
+ ```python
14
+ import torch
15
+ from diffusers import (
16
+ AdaptiveProjectedGuidance,
17
+ DPMSolverMultistepScheduler,
18
+ GGUFQuantizationConfig,
19
+ MotifVideoPipeline,
20
+ MotifVideoTransformer3DModel,
21
+ )
22
+ from diffusers.utils import export_to_video
23
+ from huggingface_hub import hf_hub_download
24
+
25
+ guider = AdaptiveProjectedGuidance(
26
+ guidance_scale=8.0,
27
+ adaptive_projected_guidance_rescale=12.0,
28
+ adaptive_projected_guidance_momentum=0.1,
29
+ use_original_formulation=True,
30
+ normalization_dims="spatial",
31
+ )
32
+
33
+ variant = "Q4_K_M" # Options: Q4_0, Q4_1, Q4_K_M, Q5_0, Q5_1, Q5_K_M, Q6_K, Q8_0, BF16
34
+ ckpt_path = hf_hub_download(
35
+ "Motif-Technologies/Motif-Video-2B-GGUF",
36
+ filename=f"motifv-2b-dev-{variant}.gguf",
37
+ )
38
+
39
+ transformer = MotifVideoTransformer3DModel.from_single_file(
40
+ ckpt_path,
41
+ quantization_config=GGUFQuantizationConfig(compute_dtype=torch.bfloat16),
42
+ config="Motif-Technologies/Motif-Video-2B",
43
+ revision="diffusers-integration",
44
+ subfolder="transformer",
45
+ torch_dtype=torch.bfloat16,
46
+ )
47
+
48
+ pipe = MotifVideoPipeline.from_pretrained(
49
+ "Motif-Technologies/Motif-Video-2B",
50
+ revision="diffusers-integration",
51
+ torch_dtype=torch.bfloat16,
52
+ guider=guider,
53
+ transformer=transformer,
54
+ )
55
+
56
+ pipe.scheduler = FlowDPMSolver(
57
+ num_train_timesteps=pipe.scheduler.config.get("num_train_timesteps", 1000),
58
+ algorithm_type="dpmsolver++",
59
+ solver_order=2,
60
+ prediction_type="flow_prediction",
61
+ use_flow_sigmas=True,
62
+ flow_shift=15.0,
63
+ )
64
+ pipe.enable_model_cpu_offload()
65
+
66
+ output = pipe(
67
+ prompt="A woman standing in a sunlit field as flower petals swirl around her in slow motion. Each petal floats gently through the golden light, casting tiny shadows. Her hair moves like water, and time seems to stand still.",
68
+ negative_prompt="text overlay, graphic overlay, watermark, logo, subtitles, timestamp, broadcast graphics, UI elements, random letters, frozen pose, rigid, static expression, jerky motion, mechanical motion, discontinuous motion, flat framing, depthless, dull lighting, monotone, crushed shadows, blown-out highlights, shifting background, fading background, poor continuity, identity drift, deformation, flickering, ghosting, smearing, duplication, mutated proportions, inconsistent clothing, flat colors, desaturated, tonally compressed, poor background separation, exposure shift, uneven brightness, color balance shift",
69
+ height=736,
70
+ width=1280,
71
+ num_frames=121,
72
+ num_inference_steps=50,
73
+ frame_rate=24,
74
+ use_linear_quadratic_schedule=False,
75
+ )
76
+ export_to_video(output.frames[0], "output.mp4", fps=24)
77
+ ```
78
+
79
+ ## SageAttention (Optional, ~1.6× faster)
80
+
81
+ Same prompt and seed, 1280x736, 121 frames, 50 steps. Left = SDPA, Right = SageAttention.
82
+
83
+ ![BF16](../assets/sage_compare_BF16.webp)
84
+ ![Q8_0](../assets/sage_compare_Q8_0.webp)
85
+ ![Q5_K_M](../assets/sage_compare_Q5_K_M.webp)
86
+ ![Q4_K_M](../assets/sage_compare_Q4_K_M.webp)
87
+
88
+ [SageAttention](https://github.com/thu-ml/SageAttention) accelerates attention by quantizing Q/K to INT8 and V to FP8, reducing memory bandwidth. Works with all GGUF variants.
89
+
90
+ **Install** (build from source — PyPI only has 1.x, need 2.x):
91
+
92
+ ```bash
93
+ # Set TORCH_CUDA_ARCH_LIST to match your GPU:
94
+ # "8.0" for A100/A30
95
+ # "8.6" for RTX 3090/3080/A40
96
+ # "8.9" for RTX 4090/4080/4070 Ti/L40/L40S (Ada Lovelace)
97
+ # "10.0" for RTX 5090/5080/5070 Ti (Blackwell)
98
+ # "9.0" for H100/H200
99
+ TORCH_CUDA_ARCH_LIST="9.0" pip install git+https://github.com/thu-ml/SageAttention.git --no-build-isolation
100
+ ```
101
+
102
+ **Usage with `inference.py`:**
103
+
104
+ ```bash
105
+ python inference.py --use-sage-attention --prompt "..."
106
+ ```
107
+
108
+ **Notes:**
109
+ - Requires NVIDIA GPU with SM70+
110
+ - SM90+ (H100, H200) — FP8 kernels for maximum speedup
111
+ - SM80-SM89 (A100, RTX 3090, RTX 4090) — FP16 kernels (still faster than SDPA)
112
+ - SM70-SM75 (V100, RTX 2080 Ti) — FP16 kernels
113
+ - Set `TORCH_CUDA_ARCH_LIST` to match your GPU when building (e.g., `"8.6"` for RTX 3090, `"8.9"` for RTX 4090)
114
+ - No quality degradation observed across all GGUF variants
115
+
116
+ ## Benchmark (H200)
117
+
118
+ Measured on NVIDIA H200, 1280x736, 121 frames, 50 steps, DPMSolver++ (order=2, flow_shift=15.0):
119
+
120
+ | Variant | SDPA (s/it) | Sage (s/it) | Speedup | Peak alloc (GB) | Peak rsv (GB) | Total SDPA (s) | Total Sage (s) |
121
+ |---------|------------|------------|---------|-----------------|----------------|----------------|----------------|
122
+ | BF16 | 23.36 | 14.75 | 1.58x | 14.78 / 15.12 | 24.93 / 24.90 | 1184 | 754 |
123
+ | Q8_0 | 23.16 | 14.49 | 1.60x | 13.10 / 13.44 | 23.14 / 23.11 | 1178 | 744 |
124
+ | Q6_K | 23.21 | 14.55 | 1.60x | 12.62 / 12.95 | 22.72 / 22.69 | 1178 | 747 |
125
+ | Q5_K_M | 23.33 | 14.69 | 1.59x | 12.39 / 12.72 | 22.45 / 22.42 | 1184 | 754 |
126
+ | Q5_1 | 23.54 | 14.96 | 1.57x | 12.47 / 12.81 | 22.66 / 22.62 | 1193 | 764 |
127
+ | Q5_0 | 23.26 | 14.67 | 1.59x | 12.37 / 12.71 | 22.55 / 22.52 | 1179 | 750 |
128
+ | Q4_K_M | 23.25 | 14.59 | 1.60x | 12.19 / 12.53 | 22.22 / 22.18 | 1178 | 747 |
129
+ | Q4_1 | 23.31 | 14.68 | 1.59x | 12.26 / 12.60 | 22.26 / 22.22 | 1181 | 750 |
130
+ | Q4_0 | 23.33 | 14.75 | 1.58x | 12.14 / 12.47 | 22.18 / 22.14 | 1188 | 760 |
131
+
132
+ Peak alloc/rsv columns show SDPA / Sage values. Sage adds ~0.3 GB alloc overhead (INT8/FP8 quantization buffers) with no change in reserved memory.
133
+
134
+ **Key findings:**
135
+ - **~1.59x faster with SageAttention** — consistent across all quantization levels
136
+ - **VRAM unchanged** — sage overhead is negligible (~0.3 GB alloc)
137
+ - **GGUF + Sage stacks** — Q4_K_M + Sage achieves 14.59 s/it at 12.53 GB alloc (vs BF16 SDPA: 23.36 s/it at 14.78 GB)
138
+
139
+ ---
140
+
141
+ ## Benchmark (RTX 4090)
142
+
143
+ Measured on NVIDIA RTX 4090 (24 GB), 1280x736, 121 frames, 50 steps, DPMSolver++ (order=2, flow_shift=15.0):
144
+
145
+ **Environment:** NGC `nvcr.io/nvidia/pytorch:26.01-py3`, Python 3.12.3, PyTorch 2.11.0+cu130, CUDA 13.0.
146
+ SageAttention built from source with `TORCH_CUDA_ARCH_LIST="8.9"`.
147
+
148
+ | Variant | SDPA (s/it) | Sage (s/it) | Speedup | Peak alloc (GB) | Total SDPA (s) | Total Sage (s) |
149
+ |---------|------------|------------|---------|-----------------|----------------|----------------|
150
+ | BF16 | 92.54 | 29.17 | 3.17x | 14.73 | 4665 | 1492 |
151
+ | Q8_0 | 92.51 | 29.18 | 3.17x | 13.02 | 4658 | 1493 |
152
+ | Q6_K | 92.81 | 29.41 | 3.16x | 12.58 | 4673 | 1504 |
153
+ | Q5_K_M | 92.79 | 29.43 | 3.15x | 12.36 | 4672 | 1505 |
154
+ | Q5_1 | 92.67 | 29.34 | 3.16x | 12.45 | 4667 | 1501 |
155
+ | Q5_0 | 92.64 | 29.34 | 3.16x | 12.34 | 4664 | 1500 |
156
+ | Q4_K_M | 92.62 | 29.29 | 3.16x | 12.16 | 4665 | 1502 |
157
+ | Q4_1 | 92.60 | 29.32 | 3.16x | 12.22 | 4668 | 1499 |
158
+ | Q4_0 | 92.64 | 29.32 | 3.16x | 12.11 | 4684 | 1500 |
159
+
160
+ Peak alloc is identical for SDPA/Sage (SageAttention adds no extra alloc overhead on RTX 4090). Peak reserved is ~14 GB with SDPA and ~16 GB with Sage.
161
+
162
+ **Key findings (RTX 4090):**
163
+ - **~3.16x faster with SageAttention** — SM89 FP16 kernels deliver larger relative speedup than H200's FP8 kernels (3.16x vs 1.59x) because SDPA is slower on 4090 while Sage remains fast
164
+ - **All variants fit in 24 GB** — Q4_0 + Sage peaks at 12.11 GB alloc (~16 GB reserved)
165
+ - **GGUF + Sage stacks** — Q4_K_M + Sage: 29.29 s/it at 12.16 GB (vs BF16 SDPA: 92.54 s/it at 14.73 GB)
166
+ - **No quality degradation** — identical to SDPA outputs across all variants
docs/memory-efficient-inference.md ADDED
@@ -0,0 +1,88 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Memory-efficient Inference
2
+
3
+ > See the main [README](../README.md) for `FlowDPMSolver` and `guider` setup.
4
+
5
+ By default, `pipe.to("cuda")` loads all components onto the GPU simultaneously, requiring **~30 GB VRAM**.
6
+
7
+ For GPUs with 24 GB or less (e.g. RTX 4090, RTX 3090), use `enable_model_cpu_offload()` with the `expandable_segments` allocator setting:
8
+
9
+ ```bash
10
+ export PYTORCH_CUDA_ALLOC_CONF=expandable_segments:True
11
+ ```
12
+
13
+ ```python
14
+ pipe = MotifVideoPipeline.from_pretrained(
15
+ "Motif-Technologies/Motif-Video-2B",
16
+ revision="diffusers-integration",
17
+ torch_dtype=torch.bfloat16,
18
+ guider=guider, # see T2V example above
19
+ )
20
+ pipe.scheduler = FlowDPMSolver(
21
+ num_train_timesteps=pipe.scheduler.config.get("num_train_timesteps", 1000),
22
+ algorithm_type="dpmsolver++",
23
+ solver_order=2,
24
+ prediction_type="flow_prediction",
25
+ use_flow_sigmas=True,
26
+ flow_shift=15.0,
27
+ )
28
+ pipe.enable_model_cpu_offload() # replaces pipe.to("cuda")
29
+
30
+ output = pipe(
31
+ prompt="...",
32
+ negative_prompt="...",
33
+ height=736, width=1280, num_frames=121, num_inference_steps=50,
34
+ frame_rate=24, use_linear_quadratic_schedule=False,
35
+ )
36
+ export_to_video(output.frames[0], "output.mp4", fps=24)
37
+ ```
38
+
39
+ This moves each component (text encoder → transformer → VAE) to GPU only when needed. The `expandable_segments` setting allows the CUDA memory allocator to efficiently reuse memory released by earlier components, avoiding fragmentation-related OOM errors.
40
+
41
+ | Mode | Peak VRAM | Speed | Recommended GPU |
42
+ |------|-----------|-------|-----------------|
43
+ | `pipe.to("cuda")` | ~30 GB | Fastest | A100, H100, H200 |
44
+ | `enable_model_cpu_offload()` | ~19 GB | Similar | RTX 4090, RTX 3090 |
45
+
46
+ ## FP8 Weight Quantization (Optional)
47
+
48
+ For further VRAM reduction, you can quantize the transformer weights to FP8 using [torchao](https://github.com/pytorch/ao):
49
+
50
+ ```bash
51
+ pip install torchao
52
+ ```
53
+
54
+ ```python
55
+ from torchao.quantization import quantize_, Float8WeightOnlyConfig
56
+
57
+ pipe = MotifVideoPipeline.from_pretrained(
58
+ "Motif-Technologies/Motif-Video-2B",
59
+ revision="diffusers-integration",
60
+ torch_dtype=torch.bfloat16,
61
+ guider=guider, # see T2V example above
62
+ )
63
+ pipe.scheduler = FlowDPMSolver(
64
+ num_train_timesteps=pipe.scheduler.config.get("num_train_timesteps", 1000),
65
+ algorithm_type="dpmsolver++",
66
+ solver_order=2,
67
+ prediction_type="flow_prediction",
68
+ use_flow_sigmas=True,
69
+ flow_shift=15.0,
70
+ )
71
+ quantize_(pipe.transformer, Float8WeightOnlyConfig())
72
+ pipe.enable_model_cpu_offload()
73
+
74
+ output = pipe(
75
+ prompt="...",
76
+ negative_prompt="...",
77
+ height=736, width=1280, num_frames=121, num_inference_steps=50,
78
+ frame_rate=24, use_linear_quadratic_schedule=False,
79
+ )
80
+ export_to_video(output.frames[0], "output.mp4", fps=24)
81
+ ```
82
+
83
+ This stores the transformer weights in FP8 (8-bit) instead of BF16 (16-bit), reducing peak VRAM from ~19 GB to ~15 GB while keeping all computation in BF16 precision.
84
+
85
+ | Mode | Peak VRAM | Notes |
86
+ |------|-----------|-------|
87
+ | `enable_model_cpu_offload()` | ~19 GB | BF16 baseline |
88
+ | `+ Float8WeightOnlyConfig` | ~15 GB | FP8 weights, BF16 compute |
feature_extractor/preprocessor_config.json ADDED
@@ -0,0 +1,23 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "do_convert_rgb": true,
3
+ "do_normalize": true,
4
+ "do_rescale": false,
5
+ "do_resize": true,
6
+ "image_mean": [
7
+ 0.5,
8
+ 0.5,
9
+ 0.5
10
+ ],
11
+ "image_processor_type": "SiglipImageProcessor",
12
+ "image_std": [
13
+ 0.5,
14
+ 0.5,
15
+ 0.5
16
+ ],
17
+ "resample": 3,
18
+ "rescale_factor": 0.00392156862745098,
19
+ "size": {
20
+ "height": 896,
21
+ "width": 896
22
+ }
23
+ }
model_index.json ADDED
@@ -0,0 +1,28 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "_class_name": "MotifVideoPipeline",
3
+ "_diffusers_version": "0.35.2",
4
+ "scheduler": [
5
+ "diffusers",
6
+ "FlowMatchEulerDiscreteScheduler"
7
+ ],
8
+ "text_encoder": [
9
+ "transformers",
10
+ "T5Gemma2Encoder"
11
+ ],
12
+ "tokenizer": [
13
+ "transformers",
14
+ "GemmaTokenizer"
15
+ ],
16
+ "transformer": [
17
+ "diffusers",
18
+ "MotifVideoTransformer3DModel"
19
+ ],
20
+ "vae": [
21
+ "diffusers",
22
+ "AutoencoderKLWan"
23
+ ],
24
+ "feature_extractor": [
25
+ "transformers",
26
+ "SiglipImageProcessor"
27
+ ]
28
+ }
scheduler/scheduler_config.json ADDED
@@ -0,0 +1,10 @@
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "_class_name": "DPMSolverMultistepScheduler",
3
+ "_diffusers_version": "0.36.0",
4
+ "algorithm_type": "dpmsolver++",
5
+ "flow_shift": 15.0,
6
+ "num_train_timesteps": 1000,
7
+ "prediction_type": "flow_prediction",
8
+ "solver_order": 2,
9
+ "use_flow_sigmas": true
10
+ }
text_encoder/config.json ADDED
@@ -0,0 +1,134 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "architectures": [
3
+ "T5Gemma2Encoder"
4
+ ],
5
+ "attention_dropout": 0.0,
6
+ "boi_token_index": 255999,
7
+ "dropout_rate": 0.0,
8
+ "dtype": "bfloat16",
9
+ "eoi_token_index": 256000,
10
+ "image_token_index": 256001,
11
+ "initializer_range": 0.02,
12
+ "mm_tokens_per_image": 256,
13
+ "model_type": "t5gemma2_encoder",
14
+ "text_config": {
15
+ "_sliding_window_pattern": 6,
16
+ "add_cross_attention": false,
17
+ "attention_bias": false,
18
+ "attention_dropout": 0.0,
19
+ "attn_logit_softcapping": null,
20
+ "bos_token_id": 2,
21
+ "cross_attention_hidden_size": null,
22
+ "decoder_start_token_id": null,
23
+ "dropout_rate": 0.0,
24
+ "dtype": "bfloat16",
25
+ "eos_token_id": 1,
26
+ "final_logit_softcapping": null,
27
+ "finetuning_task": null,
28
+ "head_dim": 256,
29
+ "hidden_activation": "gelu_pytorch_tanh",
30
+ "hidden_size": 2560,
31
+ "initializer_range": 0.02,
32
+ "intermediate_size": 10240,
33
+ "is_decoder": false,
34
+ "layer_types": [
35
+ "sliding_attention",
36
+ "sliding_attention",
37
+ "sliding_attention",
38
+ "sliding_attention",
39
+ "sliding_attention",
40
+ "full_attention",
41
+ "sliding_attention",
42
+ "sliding_attention",
43
+ "sliding_attention",
44
+ "sliding_attention",
45
+ "sliding_attention",
46
+ "full_attention",
47
+ "sliding_attention",
48
+ "sliding_attention",
49
+ "sliding_attention",
50
+ "sliding_attention",
51
+ "sliding_attention",
52
+ "full_attention",
53
+ "sliding_attention",
54
+ "sliding_attention",
55
+ "sliding_attention",
56
+ "sliding_attention",
57
+ "sliding_attention",
58
+ "full_attention",
59
+ "sliding_attention",
60
+ "sliding_attention",
61
+ "sliding_attention",
62
+ "sliding_attention",
63
+ "sliding_attention",
64
+ "full_attention",
65
+ "sliding_attention",
66
+ "sliding_attention",
67
+ "sliding_attention",
68
+ "sliding_attention"
69
+ ],
70
+ "max_position_embeddings": 131072,
71
+ "model_type": "t5gemma2_text",
72
+ "num_attention_heads": 8,
73
+ "num_hidden_layers": 34,
74
+ "num_key_value_heads": 4,
75
+ "pad_token_id": 0,
76
+ "prefix": null,
77
+ "query_pre_attn_scalar": 256,
78
+ "rms_norm_eps": 1e-06,
79
+ "rope_parameters": {
80
+ "full_attention": {
81
+ "factor": 8.0,
82
+ "rope_theta": 1000000,
83
+ "rope_type": "linear"
84
+ },
85
+ "sliding_attention": {
86
+ "rope_theta": 10000,
87
+ "rope_type": "default"
88
+ }
89
+ },
90
+ "sep_token_id": null,
91
+ "sliding_window": 1024,
92
+ "task_specific_params": null,
93
+ "tie_encoder_decoder": false,
94
+ "tie_word_embeddings": true,
95
+ "tokenizer_class": null,
96
+ "use_bidirectional_attention": false,
97
+ "use_cache": true,
98
+ "vocab_size": 262144
99
+ },
100
+ "tie_word_embeddings": true,
101
+ "transformers_version": "5.5.4",
102
+ "vision_config": {
103
+ "add_cross_attention": false,
104
+ "attention_dropout": 0.0,
105
+ "bos_token_id": null,
106
+ "cross_attention_hidden_size": null,
107
+ "decoder_start_token_id": null,
108
+ "dropout_rate": 0.0,
109
+ "dtype": "bfloat16",
110
+ "eos_token_id": null,
111
+ "finetuning_task": null,
112
+ "hidden_act": "gelu_pytorch_tanh",
113
+ "hidden_size": 1152,
114
+ "image_size": 896,
115
+ "intermediate_size": 4304,
116
+ "is_decoder": false,
117
+ "layer_norm_eps": 1e-06,
118
+ "model_type": "siglip_vision_model",
119
+ "num_attention_heads": 16,
120
+ "num_channels": 3,
121
+ "num_hidden_layers": 27,
122
+ "pad_token_id": null,
123
+ "patch_size": 14,
124
+ "prefix": null,
125
+ "sep_token_id": null,
126
+ "task_specific_params": null,
127
+ "tie_encoder_decoder": false,
128
+ "tie_word_embeddings": true,
129
+ "tokenizer_class": null,
130
+ "vision_use_head": false,
131
+ "vocab_size": 262144
132
+ },
133
+ "vocab_size": 262144
134
+ }
text_encoder/model.safetensors ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:2957deadcb660bb6e411a88c4f8860c5972f7f4eb856ac520d2628d1e225359f
3
+ size 8599946488
tokenizer/tokenizer.json ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:3220c5bec16e78ddf8e59c08fecdede7e8d31820cb5b3e69f17fed6a29a0b30c
3
+ size 33378248
tokenizer/tokenizer_config.json ADDED
@@ -0,0 +1,26 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "additional_special_tokens": null,
3
+ "backend": "tokenizers",
4
+ "boi_token": "<start_of_image>",
5
+ "bos_token": "<bos>",
6
+ "clean_up_tokenization_spaces": false,
7
+ "eoi_token": "<end_of_image>",
8
+ "eos_token": "<eos>",
9
+ "image_token": "<image_soft_token>",
10
+ "is_local": false,
11
+ "mask_token": "<mask>",
12
+ "model_max_length": 1000000000000000019884624838656,
13
+ "model_specific_special_tokens": {
14
+ "boi_token": "<start_of_image>",
15
+ "eoi_token": "<end_of_image>",
16
+ "image_token": "<image_soft_token>"
17
+ },
18
+ "pad_token": "<pad>",
19
+ "padding_side": "right",
20
+ "processor_class": "Gemma3Processor",
21
+ "sp_model_kwargs": null,
22
+ "spaces_between_special_tokens": false,
23
+ "tokenizer_class": "GemmaTokenizer",
24
+ "unk_token": "<unk>",
25
+ "use_default_system_prompt": false
26
+ }
transformer/config.json ADDED
@@ -0,0 +1,27 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "_class_name": "MotifVideoTransformer3DModel",
3
+ "_diffusers_version": "0.36.0",
4
+ "_library": "diffusers",
5
+ "attention_head_dim": 128,
6
+ "image_embed_dim": 1152,
7
+ "in_channels": 33,
8
+ "mlp_ratio": 4.0,
9
+ "norm_type": "layer_norm",
10
+ "num_attention_heads": 12,
11
+ "num_decoder_layers": 8,
12
+ "num_layers": 12,
13
+ "num_single_layers": 24,
14
+ "out_channels": 16,
15
+ "patch_size": 2,
16
+ "patch_size_t": 1,
17
+ "qk_norm": "rms_norm",
18
+ "rope_axes_dim": [
19
+ 16,
20
+ 56,
21
+ 56
22
+ ],
23
+ "rope_theta": 10000.0,
24
+ "text_embed_dim": 2560,
25
+ "enable_text_cross_attention_dual": false,
26
+ "enable_text_cross_attention_single": true
27
+ }
transformer/diffusion_pytorch_model.safetensors ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:786972d6909853d71533c0714e0d088bd982169fdc7cb89e2549b63e1fd1143d
3
+ size 7849331528
vae/config.json ADDED
@@ -0,0 +1,64 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ {
2
+ "_class_name": "AutoencoderKLWan",
3
+ "_diffusers_version": "0.35.2",
4
+ "_name_or_path": "Wan-AI/Wan2.2-T2V-A14B-Diffusers",
5
+ "attn_scales": [],
6
+ "base_dim": 96,
7
+ "decoder_base_dim": null,
8
+ "dim_mult": [
9
+ 1,
10
+ 2,
11
+ 4,
12
+ 4
13
+ ],
14
+ "dropout": 0.0,
15
+ "in_channels": 3,
16
+ "is_residual": false,
17
+ "latents_mean": [
18
+ -0.7571,
19
+ -0.7089,
20
+ -0.9113,
21
+ 0.1075,
22
+ -0.1745,
23
+ 0.9653,
24
+ -0.1517,
25
+ 1.5508,
26
+ 0.4134,
27
+ -0.0715,
28
+ 0.5517,
29
+ -0.3632,
30
+ -0.1922,
31
+ -0.9497,
32
+ 0.2503,
33
+ -0.2921
34
+ ],
35
+ "latents_std": [
36
+ 2.8184,
37
+ 1.4541,
38
+ 2.3275,
39
+ 2.6558,
40
+ 1.2196,
41
+ 1.7708,
42
+ 2.6052,
43
+ 2.0743,
44
+ 3.2687,
45
+ 2.1526,
46
+ 2.8652,
47
+ 1.5579,
48
+ 1.6382,
49
+ 1.1253,
50
+ 2.8251,
51
+ 1.916
52
+ ],
53
+ "num_res_blocks": 2,
54
+ "out_channels": 3,
55
+ "patch_size": null,
56
+ "scale_factor_spatial": 8,
57
+ "scale_factor_temporal": 4,
58
+ "temperal_downsample": [
59
+ false,
60
+ true,
61
+ true
62
+ ],
63
+ "z_dim": 16
64
+ }
vae/diffusion_pytorch_model.safetensors ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ version https://git-lfs.github.com/spec/v1
2
+ oid sha256:d6e524b3fffede1787a74e81b30976dce5400c4439ba64222168e607ed19e793
3
+ size 507591892