> ## Documentation Index
> Fetch the complete documentation index at: https://hyperframes-codex-docs-human-first-refactor.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Remove a background

> Turn footage of a person or a portrait image into transparent media you can layer over a HyperFrames scene.

Use background removal when a person needs to appear over designed text,
graphics, or another scene. HyperFrames runs the included human-segmentation
model locally; it does not upload the source or require an API key.

## Create the transparent file

Make sure FFmpeg is installed, then run:

```bash theme={null}
npx hyperframes remove-background subject.mp4 -o subject.webm
```

The first run downloads the model. Later runs reuse it.

Choose the output by destination:

| Output              | Use it for                                                       |
| ------------------- | ---------------------------------------------------------------- |
| Transparent `.webm` | A subject layered inside a web or HyperFrames composition        |
| Transparent `.mov`  | A ProRes 4444 round trip through Premiere, Resolve, or Final Cut |
| Transparent `.png`  | A single portrait image                                          |

```bash theme={null}
npx hyperframes remove-background subject.mp4 -o subject.mov
npx hyperframes remove-background portrait.jpg -o portrait.png
```

## Use the cutout

Import the transparent file into the project and place it above the
background, text, or graphic it should cover. Then check the complete clip,
especially hair, hands, fast movement, and the first and last frames.

If you animate the subject, animate a wrapper around the video. This keeps the
transparent media and the composition’s timing behavior together.

## Put something behind the subject

For text-behind-subject or another three-layer effect, you can create both the
foreground cutout and an inverse-alpha background plate in one pass:

```bash theme={null}
npx hyperframes remove-background subject.mp4 \
  -o subject.webm \
  --background-output plate.webm
```

The plate keeps the original surroundings and leaves a transparent
person-shaped hole. It is not an inpainted empty background. Place an opaque
graphic or scene beneath the hole, then place `subject.webm` above it.

## Know when it will work well

The included model is designed for people. It works best with a clear human
subject, stable framing, and reasonable contrast from the background.

Use another segmentation or masking tool when:

* the subject is a product, animal, or other object;
* fine hair crosses a busy background;
* frame-to-frame edge stability must meet high-end VFX standards;
* you need the original background reconstructed after removing the person.

Background removal is preprocessing. Run it once, keep the transparent result
in the project, and reuse it.

## Balance quality and speed

`--device auto` chooses the best available local provider. Inspect the detected
provider with:

```bash theme={null}
npx hyperframes remove-background --info
```

For WebM output, `--quality balanced` is the default. Use `best` when the
cutout sits directly over its original source and edge color must match; use
`fast` for a smaller file over an unrelated background.

## Common problems

| Problem                           | What to check                                                                                   |
| --------------------------------- | ----------------------------------------------------------------------------------------------- |
| The background is still opaque    | Confirm the output is transparent WebM, MOV, or PNG and preview it over a colored background.   |
| Edges flicker                     | Use a cleaner source, reduce fast movement, or use a stronger external matting tool.            |
| Processing is slow                | Check `--info`; CPU processing works but is much slower than an available accelerated provider. |
| The subject has a color halo      | Use `--quality best`, especially when layering over the original source.                        |
| The “background plate” has a hole | Expected: it is inverse alpha, not an inpainted clean plate.                                    |

The [CLI reference](/packages/cli#remove-background) lists every flag and
supported input.