mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-09-14 18:01:20 +08:00
ukimsanov
97 lines
3.5 KiB
Plaintext
97 lines
3.5 KiB
Plaintext
---
|
||
title: "Remove a background"
|
||
description: "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
|
||
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.
|
||
|
||
## 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.
|
||
|
||
## 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
|
||
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.
|