Setup

Run FastFrames locally: the first hour

Environment, download, one default clip, then the errors in the order you will meet them. Written for the 1.3B model first, with the 14B differences called out.

This is the checklist for turning a working demo into something you can run on your own machine without babysitting it. It is deliberately short on magic commands: the exact class names and arguments live on the model card, and copying a snippet from a blog post is the most common reason a first run fails.

Step 1: read the model card first

Open apple/FastFrames-L and apple/FastFrames-S on Hugging Face and read the usage section before downloading anything. Two things matter there: which pipeline is supported, and which stack versions the authors tested. If the card documents a diffusers pipeline, use its snippet verbatim for the first run.

Step 2: build the environment

You need a recent NVIDIA driver with a CUDA-capable build of PyTorch, and the video pipeline library the card names. Create an isolated environment so a later experiment does not break this one:

python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install torch --index-url https://download.pytorch.org/whl/cu124
pip install "huggingface_hub[cli]"

Install the video library the model card specifies on top of that. Do not mix GPU and CPU wheels: a CPU-only torch install is the second most common cause of a run that “works” in seconds and looks like a slideshow.

Step 3: download the weights on purpose

Pull the checkpoint with the CLI rather than inside the inference script, so a failed download does not look like a model error:

huggingface-cli download apple/FastFrames-S --local-dir ./ff-s

For the 14B checkpoint the same command is a roughly 28 GB download. Budget 60 GB of free disk and keep the cache on a local disk, not a network mount. The FastFrames-L guide explains why the size matters so much.

Step 4: one clip, default settings

Run the model card's example unchanged. Do not add a negative prompt, a seed, a resolution change or a longer duration on the first run — you want to know that the pipeline works before you learn anything about quality. Save the output with the seed so you can reproduce it.

Step 5: fix the errors in this order

  • Out of memory on the first allocation: reduce resolution first (memory scales with the square of resolution), then frame count, then consider FP8 or offloading.
  • Out of memory part-way through: this is activation memory rather than weights. Shorten the clip or enable sequential offloading.
  • Black or static video: almost always a wrong frame count or a mismatched sampler setting. Go back to the card's defaults.
  • Extremely slow with high GPU utilisation: you are probably in an offload configuration and paying for transfers. That is expected, not a bug.

Step 6: make it repeatable

Once one clip works, wrap it in a small script that takes a prompt, a seed, a resolution and a frame count, and writes a JSON file beside the output. You will generate far more clips than you can remember, and the only way to compare two ideas is to know exactly what produced each one.

Step 7: decide whether you need a server

If you only generate a handful of clips a day, run it locally and stop there. If you want to offer generation to other people, you need a queue, per-user limits and a way to cap spending before you write a single line of front-end code — an open model with a public form attached is an invoice waiting to happen.

Frequently asked

What software do I need to run FastFrames locally?

A recent NVIDIA driver, a CUDA build of PyTorch, the Hugging Face CLI and the video pipeline library named on the model card. Use a virtual environment and install the exact stack versions the card lists.

How much disk space does FastFrames need?

About 2.6 GB of weights for the 1.3B checkpoint and roughly 28 GB for the 14B one at FP16, plus cache copies. Budget 20 GB for the small model and 60 GB for the large one.

Why does FastFrames run out of memory immediately?

The weights do not fit. For the 14B model at FP16 they are about 28 GB before activations, so on a smaller card you need FP8 or INT4 weights, offloading, or both. Lower resolution first, then frame count.

Can I run FastFrames on a Mac?

The model card documents the CUDA stack. Apple silicon has no CUDA, so treat local inference there as an experiment rather than a supported path, and use a GPU machine or a community Space for real work.