Skip to content

Make videos on the computer you already own. FreeVideo runs MiniMax H3 in as little as 8 GB of VRAM and 16 GB of RAM, and adapts its acceleration path to your hardware.

6.3 KB
Raw Blame
# Copyright 2026 The MiniMax and HuggingFace Teams. All rights reserved.
# Copyright 2026 FreeVideo contributors.
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy at http://www.apache.org/licenses/LICENSE-2.0
# Unless required by applicable law or agreed to in writing, software distributed
# under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
# CONDITIONS OF ANY KIND, either express or implied. See the License for the
# specific language governing permissions and limitations under the License.
"""Transpose the tile/layer loops to transfer each decoder layer once per clip.

Prologue/epilogue adapted from diffusers' MiniMaxH3VideoViTDecoder3d, pinned at
VDN 30b6b380c2482f3519469350810c2955d8847fd9. Spatial tile geometry, per-tile
GEMM shapes, temporal chunking and stitching remain those of the original VAE.
"""
import os
import types
from contextlib import nullcontext
import torch

from .offload import LayerOffloader


def compile_blocks(decoder):
    """Compile the decoder block once; all blocks share the graph, their weights are inputs.

    Decoding 1344x768x243 on Windows with an RTX 5060 Ti took 114.9 s eager. Compiled, it
    took 100.6 s in a fresh process that loaded the graph from the disk cache, and 105.4 s
    in one that compiled it first. On an RTX PRO 6000 it took 18.1 s and 14.6 s. The
    rounding of fused RMSNorm, rotary and residual work moves 0.7% of output values by
    one or two 8-bit levels. FREEVIDEO_VAE_COMPILE=0 keeps the eager blocks.
    """
    if os.environ.get('FREEVIDEO_VAE_COMPILE', '1').lower() in ('0', 'off', 'false'):
        return False
    for block in decoder.transformer_blocks:
        if not getattr(block, 'freevideo_compiled', False):
            block.forward = _fixed_reduction_order(torch.compile(block.forward, dynamic=False))
            block.freevideo_compiled = True
    return True


def _fixed_reduction_order(compiled):
    """Run the compiled block with Inductor's deterministic mode.

    Otherwise Inductor times several warp counts for each fused RMSNorm reduction
    when a process first runs the block, and the counts sum in different orders.
    About 1 process in 20 then decoded the same latents to pixels that differ by one
    8-bit level in 0.3% of values; 150 processes in this mode gave identical output.
    """
    def forward(*args, **kwargs):
        from torch._inductor import config
        with config.patch(deterministic=True):
            return compiled(*args, **kwargs)
    return forward


class TileDecoder:
    def __init__(self, decoder, prefetch=True, weight_source=None, resident_blocks=0):
        self.decoder = decoder
        self.resident_blocks = resident_blocks
        self.offloader = LayerOffloader(list(decoder.transformer_blocks)[resident_blocks:], prefetch=prefetch, manage_hooks=False,
                                       weight_source=weight_source)

    def decode(self, tiles):
        model = self.decoder
        states = []
        shapes = []
        ropes = []
        for tile in tiles:
            batch, channels, frames, height, width = tile.shape
            hidden = tile.permute(0, 2, 3, 4, 1).reshape(batch, frames * height * width, channels)
            hidden = model.proj_in(hidden)
            hidden = torch.cat([hidden, model.register_tokens.expand(batch, -1, -1),
                                torch.zeros_like(hidden[:, :1, :])], dim=1)
            grids = [2.0 * (torch.arange(0.5, size, dtype=torch.float32, device=hidden.device) / size) - 1.0
                     for size in (frames, height, width)]
            position = torch.stack(torch.meshgrid(*grids, indexing='ij'), dim=-1).flatten(0, 2)
            position = position.unsqueeze(0).expand(batch, -1, -1)
            position = torch.cat([position, position.new_zeros((batch, model.num_register_tokens + 1, 3))], dim=1)
            states.append(hidden)
            shapes.append((batch, frames, height, width))
            ropes.append(model.rope(position))
        for index in range(len(model.transformer_blocks)):
            context = (nullcontext(model.transformer_blocks[index]) if index < self.resident_blocks
                       else self.offloader.layer(index - self.resident_blocks))
            with context as block:
                for tile_index, hidden in enumerate(states):
                    states[tile_index] = block(hidden, ropes[tile_index])
        outputs = []
        for hidden, shape in zip(states, shapes):
            batch, frames, height, width = shape
            hidden = model.proj_out(model.norm_out(hidden))[:, :frames * height * width]
            hidden = hidden.view(batch, frames, height, width, model.out_channels,
                                 model.patch_size_t, model.patch_size, model.patch_size)
            hidden = hidden.permute(0, 4, 1, 5, 2, 6, 3, 7).contiguous()
            outputs.append(hidden.reshape(batch, model.out_channels, frames * model.patch_size_t,
                                          height * model.patch_size, width * model.patch_size))
        return outputs

    def install(self, vae):
        self.original = vae._decode_clip
        self.vae = vae

        def decode_clip(module, z):
            if not module.use_tiling:
                return self.decode([module.post_quant_conv(z)])[0]
            ratio = module.spatial_compression_ratio
            yi, yl, yo = module._split_tiles(z.shape[-2] * ratio, module.tile_sample_min_height,
                                            module.tile_sample_min_overlap_height)
            xi, xl, xo = module._split_tiles(z.shape[-1] * ratio, module.tile_sample_min_width,
                                            module.tile_sample_min_overlap_width)
            tiles = [module.post_quant_conv(z[..., y // ratio:(y + h) // ratio, x // ratio:(x + w) // ratio])
                     for y, h in zip(yi, yl) for x, w in zip(xi, xl)]
            values = self.decode(tiles)
            rows = [values[start:start + len(xi)] for start in range(0, len(values), len(xi))]
            return module._stitch_tiles(rows, yo, xo)

        vae._decode_clip = types.MethodType(decode_clip, vae)

    def close(self):
        self.offloader.close()
        if hasattr(self, 'vae'):
            self.vae._decode_clip = self.original