hyperframes/docs/guides/remove-background.mdx

---
title: "Remove a background"
description: "Turn footage of a person or a portrait image into transparent media you can layer over a HyperFrames scene."
---

import { DocsVideo } from "/snippets/docs-video.jsx";

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.

<Frame caption="The same real frame before and after the local model. The softer hair and hand edges are the model’s actual limit on this source.">
  <img
    src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/remove-background-before-after-v1.png"
    alt="The original presenter frame beside its transparent cutout over a green background"
  />
</Frame>


<DocsVideo
  title="A presenter cut out of a real room, shown against the original and magnified at the hard edges"
  src="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/remove-background-demo-v3.mp4"
  poster="https://static.heygen.ai/hyperframes-oss/docs/images/showcase/remove-background-demo-v1.jpg"
/>

Every frame is real CLI output. The magnified panels sit on the hair edge and on
a shoulder a plant used to overlap, because those are where matting usually fails.

## Create the transparent file

Make sure FFmpeg is installed, then run:

```bash
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
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.

## Compositing patterns and pitfalls

Keep the media element stable and animate a wrapper when the cutout must move,
resize, or reveal. This avoids mixing media playback with the transform that
controls the composition.

When a cutout and its original background must remain frame-aligned, give both
media elements the same `data-start` and playback offset. Hide or reveal them
through wrappers instead of mounting one source later. Then scrub the cut point
and check the rendered frame, not only normal playback.

## 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
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.

`hyperframes check` judges text behind the cutout by the cutout's own alpha at
each sample time. A word partly behind the subject is reported as info with the
share it hides; a word 80% hidden, or two neighbouring words each half hidden,
is an error. You do not need `data-layout-allow-occlusion` for this layering.

## 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;
- the person holds something, especially a dark microphone, phone, card, or
  instrument: the model can drop all or part of it;
- 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
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.                                    |
| Part of a held object is missing  | The model matches people, not what they hold. Use another matting tool for that shot.           |

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

## Related topics

- [Use images and video](/guides/video-components)
- [Add an avatar presenter](/guides/avatar-presenter)
- [Apply media effects without changing the source file](/guides/media-effects)