FramePack BucketResize (HY)

This is the least glamorous node in ComfyUI-FramePack-HY, and honestly that's why you should read this. FramePack is lllyasviel's sampling trick that compresses the temporal attention window so VRAM stops scaling linearly with clip length - the thing that made minute-scale video on a 4060 feel possible. But before any of that magic happens, the pack needs a starting frame, and that frame's shape matters more than you'd think. FramePackBucketResize_HY takes your first-frame image and snaps it to the nearest resolution bucket. It does one thing. It does it quietly. Getting it wrong just makes your video come out subtly worse in ways that are hard to blame on the sampler.

What a "bucket" is, and why you need one

Hunyuan-class video models aren't trained on arbitrary resolutions - they're trained on a discrete set of aspect-ratio buckets, like SDXL's famous list. If you hand the model a 1371×809 start frame, it's running outside its training distribution, and you'll see it in wobble, flicker, and squished composition. The bucket node solves that by keeping a fixed list of well-formed shapes per base resolution and stretching your image to whichever one is closest.

Here's the mechanism, straight from the source. Pick a base_resolution (512, 640, 768, or 1024) and it looks up that resolution's bucket list - for 640, that's pairs like 512×768, 544×704, 640×608 and their mirror images, all keeping roughly the same total pixel count. It scores every bucket with |h * bucket_w − w * bucket_h|, a pure aspect-ratio match, and takes the winner. Then it interpolates your image to that exact size. No cropping, no padding - your image gets stretched to fit the bucket. That's a feature (the model wants that shape), but it does mean a 16:9 photo ends up a little squished to reach a bucket like 768×512. The output width and height ints are the point: wire them into the sampler so its generation size matches the resized frame exactly.

The inputs that matter

• image - your start frame, straight from Load Image.
• base_resolution - 512 / 640 / 768 / 1024. Match the resolution your FramePack model was meant to run at; 640 is the default and is a reasonable starting point on consumer cards.
• resize_mode - lanczos, bilinear, bicubic, nearest. One trap: PyTorch has no lanczos, so the "lanczos" option actually runs bicubic under the hood. Fine - bicubic is the right call for a start frame anyway.
• alignment - center / top_left. Don't waste time on this one: the current code accepts it and never uses it. Since there's no crop, there's nothing to align.

Installing it

The whole pack installs at once. Easiest route is ComfyUI Manager → Install Custom Nodes → search "FramePack-HY" or "CY-CHENYUE". Manually:

cd /path/to/ComfyUI/custom_nodes
git clone https://github.com/CY-CHENYUE/ComfyUI-FramePack-HY.git
cd ComfyUI-FramePack-HY
pip install -r requirements.txt

Then restart ComfyUI. The real dependency list is diffusers, transformers, accelerate, scipy, torchsde, einops, safetensors - nothing exotic, but make sure you pip-install into the same Python that runs ComfyUI (the portable install's python_embeded if you use one). You'll also need a FramePack model in your diffusers folder, e.g. lllyasviel/FramePackI2V_HY, which the loader node finds automatically. That download is the heavy part, not this node.

Common issues

• Frame dims disagree with the sampler. The README hammers this: whatever width/height the bucket node reports is what the sampler and VAE encode must use. If you let them drift, you get latent-shape errors or subtle quality loss. Use the int outputs rather than re-typing numbers.
• "Alignment" does nothing. Not a bug report waiting to happen - it's just not implemented. Don't fiddle with it expecting a centered crop.
• Distorted start frames. Expected, since it stretches rather than crops. If the distortion bothers you, pick the bucket closest to your source's aspect ratio (the algorithm already does), or pre-crop your image to a bucket-shaped ratio yourself before this node.

The workflow this slots into: image → BucketResize → VAE Encode → CreateKeyframes → FramePack Sampler. It's the silent plumber in the middle. Most of the pack's reputation rides on the sampler; this node just keeps the input honest.