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.

7.6 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.
"""Bound packed-input and output-head intermediates without dropping any rows.

Adapted from the pinned Diffusers MiniMaxH3Transformer3DModel.forward. Scattering
is in-place under inference, modality projections are released immediately, and
the FP32 projections/output normalization run over bounded row chunks. GEMM
shape changes can alter rounding; this is an explicit optimization profile.
"""
import gc
import types
import torch
from .fp8 import input_dtype

from diffusers.models.transformers.transformer_minimax_h3 import MiniMaxH3TransformerOutput


def install_streamed_forward(model, chunk=1024, residual_offload=False):
    if chunk < 1:
        raise ValueError('Projection chunk must be positive')
    # Compiling for a new sequence length captures Python frames in reference
    # cycles that also hold the first block's output. The second block stages
    # that output to host memory and drops it, but the cycle keeps it alive
    # through the second block's attention until the collector happens to run:
    # on an RTX 3090 under Windows, 1344x768x362 second passes allocated
    # 6.82 GiB instead of 5.74. A staged block collects once right after it
    # drops its input, in the first forward of each new length.
    collected = set()

    def blocks(self, value, length, temb, adaln_indices, rotary):
        first = length not in collected
        collected.add(length)
        cache = getattr(self, '_freevideo_step_cache', None)
        cache = cache if cache is not None and not cache.disabled_reason and cache.block_level else None
        if cache is not None and not isinstance(value, torch.Tensor):
            cache.disabled_reason = 'residual_offload'
            cache = None
        for index, block in enumerate(self.transformer_blocks):
            if first and index in (1, 2) and hasattr(value, 'collect_after_store'):
                value.collect_after_store = True
            if cache is not None and index == 0:
                cache.before_first_block(value)
            value = block(value, temb, adaln_indices, rotary)
            if first and index == 0 and not hasattr(value, 'collect_after_store'):
                gc.collect()
            if cache is not None and index == 0 and cache.after_first_block(value):
                if cache.offloader is not None:
                    cache.offloader.end_pass_early()
                return value
        if cache is not None:
            cache.after_last_block(value)
        return value

    def forward(self, hidden_states, audio_hidden_states, encoder_hidden_states,
                timestep, timestep_indices, token_tags, position_ids,
                video_indices, audio_indices, text_indices, attention_kwargs=None, return_dict=True):
        if torch.is_grad_enabled():
            raise RuntimeError('Streamed packing requires inference without autograd')
        if attention_kwargs:
            raise ValueError('This profile expects already merged adapters without attention kwargs')
        length = position_ids.shape[0]
        if position_ids.shape != (length, 3) or token_tags.shape != (length,) or timestep_indices.shape != (length,):
            raise ValueError('Invalid packed sequence geometry')
        cache = getattr(self, '_freevideo_step_cache', None)
        if cache is not None and residual_offload and cache.block_level:
            # The first-block cache keeps packed residuals on the GPU; reusing
            # a whole step (EasyCache) does not touch them.
            cache.disabled_reason = 'residual_offload'
        cache = cache if cache is not None and not cache.disabled_reason else None
        sigmas = None
        if cache is not None:
            cache.begin(video_indices, audio_indices)
            if not cache.block_level:
                # H3 time is t = 1 - sigma; generated video rows come last.
                sigmas = (1. - float(timestep[timestep_indices[video_indices[-1]]]),
                          1. - float(timestep[timestep_indices[audio_indices[0]]]))
                cached = cache.skip_forward(hidden_states[0], audio_hidden_states[0], sigmas)
                if cached is not None:
                    video = cached[0][None].to(self.proj_out.weight.dtype)
                    audio = cached[1][None].to(self.audio_proj_out.weight.dtype)
                    return MiniMaxH3TransformerOutput(sample=video, audio_sample=audio) if return_dict else (video, audio)
        rotary = self.rope(position_ids)
        text = getattr(self, '_freevideo_refined_text', None)
        if text is None:
            text = self.context_embedder(encoder_hidden_states.to(input_dtype(self.context_embedder)))
            text = self.token_refiner(text)
        packed = text.new_zeros((text.shape[0], length, text.shape[-1]))
        packed.index_copy_(1, text_indices, text)
        del text
        for source, indices, projection in ((hidden_states, video_indices, self.proj_in),
                                            (audio_hidden_states, audio_indices, self.audio_proj_in)):
            for start in range(0, source.shape[1], chunk):
                projected = projection(source[:, start:start + chunk].to(projection.weight.dtype))
                packed.index_copy_(1, indices[start:start + chunk], projected.to(packed.dtype))
                del projected
        del source
        temb = self.time_embedder(self.time_proj(timestep).to(self.time_embedder.linear_1.weight.dtype))
        adaln_indices = timestep_indices * 3 + token_tags
        if residual_offload:
            from .residual import ResidualState
            state = ResidualState(packed)
            del packed
            try:
                state = blocks(self, state, length, temb, adaln_indices, rotary)
                packed = state.take()
                self._freevideo_residual_stats = state.stats()
            finally:
                state.close()
        else:
            packed = blocks(self, packed, length, temb, adaln_indices, rotary)
        video_all = torch.empty((packed.shape[0], length, self.proj_out.out_features),
                                dtype=self.proj_out.weight.dtype, device=packed.device)
        audio_all = torch.empty((packed.shape[0], length, self.audio_proj_out.out_features),
                                dtype=self.audio_proj_out.weight.dtype, device=packed.device)
        for start in range(0, length, chunk):
            normalized = self.norm_out(packed[:, start:start + chunk], temb, timestep_indices[start:start + chunk])
            normalized = normalized.to(self.proj_out.weight.dtype)
            video_all[:, start:start + chunk] = self.proj_out(normalized)
            audio_all[:, start:start + chunk] = self.audio_proj_out(normalized)
        video = video_all.index_select(1, video_indices)
        audio = audio_all.index_select(1, audio_indices)
        if sigmas is not None:
            cache.record_forward(hidden_states[0], audio_hidden_states[0], sigmas, video[0], audio[0])
        return MiniMaxH3TransformerOutput(sample=video, audio_sample=audio) if return_dict else (video, audio)

    model.forward = types.MethodType(forward, model)