hyworld

HYWorld (HY-WorldPlay) model components for FastVideo.

This module provides: - HYWorldTransformer3DModel: The main transformer model with ProPE and action conditioning - HYWorldVideoGenerator: Extended VideoGenerator for HYWorld inference - Utilities for pose processing and camera trajectory generation

fastvideo.models.dits.hyworld.HYWorldTransformer3DModel

HYWorldTransformer3DModel(config: HYWorldConfig, hf_config: dict[str, Any])

HY-World Transformer extending HunyuanVideo15 with: - ProPE (Projective Positional Encoding) for camera-aware attention - Action conditioning for interactive video generation

fastvideo.models.dits.hyworld.HYWorldTransformer3DModel.forward

forward(hidden_states: torch.Tensor, encoder_hidden_states: list[torch.Tensor], timestep: torch.LongTensor, encoder_hidden_states_image: list[torch.Tensor], encoder_attention_mask: list[torch.Tensor], action: torch.Tensor, viewmats: torch.Tensor, Ks: torch.Tensor, timestep_txt: torch.LongTensor, guidance: Optional[torch.Tensor] = None, timestep_r: Optional[torch.LongTensor] = None, attention_kwargs: Optional[dict[str, Any]] = None)

Forward pass with action and camera conditioning.

Parameters

action: torch.Tensor

Action tensor for action conditioning [B, T] or [B*T]

viewmats: torch.Tensor

Camera view matrices [B, T, 4, 4]

Ks: torch.Tensor

Camera intrinsics [B, T, 3, 3]

fastvideo.models.dits.hyworld.HYWorldDoubleStreamBlock

HYWorldDoubleStreamBlock(hidden_size: int, num_attention_heads: int, mlp_ratio: float, dtype: torch.dtype | None = None, supported_attention_backends: tuple[AttentionBackendEnum, ...] | None = None, prefix: str = '')

Extended MMDoubleStreamBlock with ProPE (Projective Positional Encoding) support for camera-aware attention in HY-World/WorldPlay models.

fastvideo.models.dits.hyworld.HYWorldDoubleStreamBlock.forward

forward(img: torch.Tensor, txt: torch.Tensor, encoder_attention_mask: torch.Tensor, vec: torch.Tensor, vec_txt: torch.Tensor, freqs_cis: tuple, original_seq_len: int, viewmats: torch.Tensor, Ks: torch.Tensor) -> tuple[torch.Tensor, torch.Tensor]

Forward pass with ProPE camera conditioning.

Parameters

img: torch.Tensor

Image/video tokens

txt: torch.Tensor

Text tokens

encoder_attention_mask: torch.Tensor

Text attention mask

vec: torch.Tensor

Modulation vector

freqs_cis: tuple

Rotary embedding frequencies

original_seq_len: int

Original (unpadded) image sequence length

viewmats: torch.Tensor

Camera view matrices for ProPE [B, T, 4, 4]

Ks: torch.Tensor

Camera intrinsics for ProPE [B, T, 3, 3]

Returns

tuple[torch.Tensor, torch.Tensor]

Tuple of (img, txt) output tokens

fastvideo.models.dits.hyworld.get_resolution_from_image

get_resolution_from_image(image_path, target_resolution = '480p')

Automatically determine resolution from input image.

Parameters

image_path

Path or URL to input image

target_resolution

Target resolution tier ("480p", "720p", etc.)

Returns

tuple[int, int]: (height, width) matching HY-WorldPlay's bucket selection