User guide.

WispFX pulls alpha mattes from ordinary footage inside After Effects and DaVinci Resolve. No green screen, roto or prompt is needed. It is built for the edges keyers and Roto Brush lose: hair, fur, smoke, glass, liquid and motion blur.

Contents: 1 System requirements · 2 Install · 3 Activating your licence · 4 Models and Hugging Face access · 5 Quick start · 6 The viewer · 7 Subject · 8 Quality · 9 Matte Refinement · 10 Hair Cleanup · 11 Output and despill · 12 Light wrap · 13 Where mattes are saved · 14 Engine · 15 DaVinci Resolve · 16 Updating · 17 Uninstalling · 18 Keyboard · 19 Troubleshooting · 20 Logs

1. System requirements

Measured speeds and VRAM limits were measured on an RTX 4090 (24 GB). Results for 8, 12 and 16 GB cards are estimates. <!-- TODO owner: test one real 8-12 GB and one 16 GB card. -->

2. Install

2.1 Unzip

Unzip the download to a short folder such as C:\WispFX. Do not unzip into OneDrive, into a deep folder under Downloads, or into Program Files.

2.2 Engine (once)

1. Run **setup_engine.bat**. It installs a private Python, the engine and its nodes. It does not touch any other ComfyUI you have and needs no admin rights.
2. Before downloading anything, it checks for an NVIDIA driver, enough free space and an internet connection. If it stops, the message says why. Fix that and run it again. Finished parts are kept, so a re-run is quick.
3. It ends by testing that PyTorch can use your GPU, and shows "Engine ready".

2.3 After Effects panel

1. Quit After Effects.
2. Run **install_ae_panel.bat**. It installs the signed panel and makes no registry changes. It refuses to run while After Effects is open.
3. Open After Effects, then Window > Extensions > WispFX.

2.4 DaVinci Resolve (optional)

See section 15.

3. Activating your licence

WispFX needs a licence before it renders. Your licence key is in the receipt email from Gumroad and in your Gumroad library.

1. Open the panel and expand Licence.
2. Paste the key into Licence Key.
3. Click Activate. This needs an internet connection the first time.
4. The Licence heading shows Licensed when it works.

Notes:

• Seats: a licence works on 2 computers by default. A purchase of several seats allows 2 computers per seat.
• Checks: WispFX re-checks the licence quietly about every 3 days while you are online. Re-checks do not use up a seat.
• Offline: you can work offline for up to 14 days after the last successful check. The Status line tells you how many days are left. After 14 days offline, rendering stops until WispFX can check the licence again.
• Refunds and disputes: a refunded or disputed sale is removed at the next online check.
• Trial: <!-- TODO owner: decide whether the 1.0 Gumroad build offers a trial. The current Gumroad-only build has no trial, and the trial controls are hidden. If a trial ships, describe it here: 14 days, mattes carry a watermark, renders stop when it ends. -->
• Buy: the Buy link opens the store page. <!-- TODO owner: the Buy link and support address are still placeholders in licence.py. Set the real store page and support email before release. -->

Moving to another computer

1. On the old computer, open Licence and click Deactivate This Computer.
2. Deactivating removes the licence from that computer only. Gumroad still counts the seat, so contact support to free it.
3. On the new computer, paste the key and click Activate.

Reinstalling Windows counts as a new computer, so it also needs a seat freed by support.

4. Models and Hugging Face access

The AI models are not in the download. WispFX fetches them from Hugging Face on first launch. Two of the model repositories are gated by Lightricks, so you need a free Hugging Face account and must accept the licence on each page.

The panel walks you through it in three steps. The setup card shows under the Download banner while a model is missing:

1. Account and access. Create a free account at huggingface.co, or sign in. Open each model page the card lists and accept its licence while logged in: Lightricks/LTX-2.5 and Lightricks/LTX-2.5-22b-IC-LoRA-Alpha-Gen. Accepting one does not accept the other. Each row shows its status, and reads "Access granted" when it is ready. Pick subject also needs Meta's SAM 3 page, once you use it.
2. Connect your account. Create an access token with Read permission at huggingface.co/settings/tokens, paste it into the token field and click Connect. WispFX stores the token on this computer only, and clears the field after you connect. Check Access tests each page again.
3. Accept the model licences and download. Tick the licence boxes, then click Download. Download stays disabled until every row reads "Access granted" and every box is ticked.

Prefer the command line? Run **HF Login.bat** in the WispFX folder instead of step 2. It stores the same token: paste it and press Enter. The token is shown as you paste it, so do this where nobody can see your screen.

The download size depends on your card. Draft (8 to 12 GB cards) fetches the smallest transformer. Quality and Max both use Lightricks' official int8 transformer (21.5 GB). You only download the transformer for your preset.

The first download is about 33 GB (Draft) to 43 GB (Quality and Max) without subject picking, and 3.45 GB more the first time you pick a subject. That includes Lightricks' text encoder (15.4 GB, in the gated Lightricks/LTX-2.5 repository). Setup uses it once to prepare the model on your GPU, then deletes it, so about 20 GB (Draft) to 30 GB (Quality and Max) stays on disk. Setup needs room for the encoder while it runs.

24 GB cards use Lightricks' official int8 weights: the 21.5 GB file ltx-2.5-22b-distilled-transformer-comfy-int8-convrot.safetensors from Lightricks' gated Lightricks/LTX-2.5 repository. WispFX does not host it.

A smaller first download is planned if Lightricks allows us to ship the pre-built file that replaces the encoder step. Until that is agreed, the encoder is downloaded once, as described here.

<!-- TODO owner: confirm that an interrupted download resumes where it stopped (owner test script, step A5). -->

5. Quick start

1. Select a footage layer in your comp: video or an image sequence. Pre-render precomps first.
2. Click Use Layer. WispFX uses the layer's frames inside the work area.
3. Click Pull Matte. The time next to the button is an estimate for your clip and GPU.
4. The matte is applied as a luma track matte on your layer. It is fully undoable with Ctrl+Z, and the result shows in the viewer.

To change the look, adjust Matte Refinement, Output or Despill, then click Update Matte. Update Matte takes seconds and does not re-render. Changes to Subject or Quality need Pull Matte again.

6. The viewer

• Hold Alt in any view to see the original plate.
• Drag the ruler under the viewer to scrub frames. Rendered frames show in blue.
• During a render, the viewer shows each finished pass live, with an orange sweep for the pass in progress.

7. Subject

Set Mode in the Subject section.

• Auto foreground: the model decides what is foreground. Works well for one clear subject.
• Picked subject: pick the subject yourself.
  1. Click the crosshair tool in the viewer toolbar.
  2. Click the person or object. Each click is a keep point.
  3. Alt-click (or right-click) to mark something to leave out.
  4. Optionally type a description in Describe, for example "the dog".
  5. The pick is tracked through the shot. If the subject changes shape or gets covered, click it again on that frame. Each frame you click becomes a keyframe, listed under Keyframes. Clear removes the current frame's clicks; All removes every keyframe.
• Edge Room (default 4%, range 1 to 12%): how far soft edges such as hair, motion blur and smoke may reach beyond the picked shape. Raise it if wispy hair is cut off. Lower it if nearby objects leak in.

Pick in Viewer

Use this to pick on the big Composition viewer instead of the panel viewer. It needs Mode: Picked subject and an After Effects layer as the source.

1. Click Keep to add an AF Pick + marker to the comp, selected, at the plate's centre.
2. Drag the marker onto the subject in the Composition viewer.
3. Click Leave to add an AF Pick - marker for something to leave out, and drag it.
4. Move the timeline to a frame where you want the pick, then click Use Points. The markers are read at that comp time and become this frame's picks.
5. Repeat for other frames if the subject changes.
6. Clear removes every AF Pick marker. Nothing else in the comp is touched.

The markers are guide layers and are not rendered. WispFX removes them when a render starts, because the points are already in the job.

<!-- TODO owner: Pick in Viewer is not yet checked in After Effects (owner test script, B4 and PICK_VIEWER.md checklist). Confirm steps 1 to 9 before release. -->

8. Quality

*Measured on an RTX 4090 for a 145-frame clip at 1280 by 656. The Quality menu shows the estimate for your clip and your GPU.

Max can stall or run slowly on smaller cards. Use it only on 30 GB or more.

The model works at the Model Res, then the matte is rebuilt at your footage's full resolution with edge detail taken from the plate. Even Draft delivers a full-resolution matte.

• Steps: 4 is the default. On the RTX 4090, 8 steps gave no visible gain at about 1.5 times the time.
• Frames/Pass: shots are split into passes of this length. Lower it only if the panel warns that GPU memory got tight; it does this automatically when needed. Shots longer than one pass are split into overlapping passes that blend with no seam.

9. Matte Refinement

Refinement changes the matte after the model runs. Use Update Matte to apply changes without rendering. Values are scrubbable like After Effects properties: drag to change, Shift-drag for big steps, Ctrl-drag for fine steps, or click a value to type it.

Refinement runs in this order:

1. Stabilize
2. Edge Detail (upsampling to full resolution)
3. Hair Cleanup
4. Clip Black and Clip White
5. Choke
6. Feather
7. Invert

Reset returns Matte Refinement to its defaults. <!-- TODO owner: Reset does not include Hair Cleanup yet (V1_GAPS M13). Remove this note once fixed. -->

Tips:

• Backlit hair: Quality, Edge Detail 60 to 80%, Choke 0.
• Fast motion blur: Choke 0, Feather 0. WispFX keeps blur as soft alpha, and choking cuts it.
• Chattering edges on a static shot: Stabilize 40 to 70%.
• Several people, one wanted: Pick the subject, click the person, then Alt-click the others.

10. Hair Cleanup

Hair Cleanup removes the faint glow of the old background that clings to hair and soft edges. WispFX rebuilds the real background from the whole shot and uses it as the reference. Strands that differ from that background are kept.

• Default 40%. Raise it if a coloured glow remains; set 0 to turn it off.
• Glass interiors and liquid are kept on purpose. Raising Hair Cleanup does not clear them.

11. Output and despill

Apply As

• Luma track matte (default): your original layer keeps its exact pixels, and the matte sits above it as a track matte. Best for most comps.
• Matte layer: adds the matte as its own layer only.
• RGBA cutout: a ProRes 4444 file with alpha and spill cleaning applied. Best when the subject goes onto a very different background.

ProRes 4444, also write: also writes an RGBA ProRes 4444 file with despilled colour.

Save to: WispFX cache (default, fastest) or Next to the footage (slower on USB drives). See section 13.

8-bit note: the RGBA cutout is built from 8-bit colour. For 10-bit or 12-bit, log or EXR footage, use Luma track matte mode, which keeps the original pixels.

<!-- TODO owner: colour-managed projects (linearised working space, OCIO or ACES) are not verified. Check the matte edge in such a project and add a note here (V1_GAPS M15). -->

Despill

Despill removes the old background's colour from soft edges.

Strength (0 to 100%, default 100%) sets how much of the correction is used. Lower values keep some of the plate's original edge colour.

In Luma track matte mode, despill is a live correction layer. Turning it on or off and changing its strength apply instantly in After Effects, with no re-render.

In RGBA cutout mode, despill is baked into the cutout when it is written.

12. Light wrap

Light wrap brings the new background's light onto the subject's edge, so it sits in the new plate.

1. Open Light Wrap. Choose the new background layer in Light from. The list refreshes each time you open it.
2. Select your WispFX layer in the comp and click Add Light Wrap.
3. Choose a Blend mode. Screen is the default.
4. Click Solo to see only the wrap light, to judge it.
5. Adjust Wrap Width, blur, intensity, exposure and saturation on the AF Light Wrap layer in Effect Controls.

Clicking Add Light Wrap again updates the same rig and keeps your values. Ctrl+Z undoes the change.

Layers that cannot be used as Light from: WispFX layers (AF ...), mattes, cameras, lights, and layers parented to the subject.

<!-- TODO owner: light wrap is not yet verified in After Effects (PANEL_APPLIED.md checklist, steps 1 to 11; V1_GAPS S16). Confirm before release. -->

13. Where mattes are saved

• Save to: WispFX cache (default): mattes go to the cache folder. The default is C:\AlphaForge\Mattes, or a folder named AlphaForge Mattes in your user folder if C: is not available.
• Save to: Next to the footage: mattes go beside the source files. Slower on USB drives.
• Cache folder: shows the current folder. Change... picks another folder. The folder button opens it.
• Choose a visible folder outside %LOCALAPPDATA%. After Effects refuses to import from there (see Troubleshooting, "Path is not valid").

Each render creates a folder named after the clip with a _alpha suffix, holding 16-bit PNG frames. A ProRes 4444 file (_alpha_rgba.mov) is written when that option is on. A _delta folder holds the despill correction when track matte mode is used.

WispFX never deletes mattes. Your comps point at these files, so delete old renders yourself, and only when no comp uses them. Deleting a matte takes the comps that use it offline. <!-- TODO owner: the Clean Up tool for old renders (V1_GAPS S10) is not built. Remove this note when it ships. -->

Models folder: the models are in the models folder inside the WispFX folder. To use an existing ComfyUI models folder instead, set models_dir in settings.json and restart the server. <!-- TODO owner: a Models folder picker in the Engine section is planned (V1_GAPS M7) but not built. -->

14. Engine

The engine is the GPU part of WispFX. The panel starts it for you.

• Status in the Engine section shows whether it is ready, starting or off.
• Start Engine appears when the engine is off. The first start can take a minute or more while the models load.
• Start with After Effects (default: on): WispFX starts the engine when After Effects opens. Turn it off if you prefer to start it yourself. The same setting appears on the start screen as "Start the engine when After Effects opens".
• The logo dot shows the state: green is ready, pulsing orange is rendering, red is offline.
• The engine stops when the WispFX server stops. You can also start it by hand with **Alpha Forge Server.bat**.

After a render, the engine keeps the models in GPU memory. Other GPU apps may run slower until the engine is stopped.

• Free GPU Memory unloads the models from the GPU and keeps the engine running. The next render loads them again, which takes a few seconds. Use it when After Effects or another GPU app is slow.
• Stop Engine shuts the GPU worker down and gives its memory back. WispFX keeps running. Start Engine brings the worker back, and the next render starts it too.
• GPU memory shows how much the engine holds and how much of the card is in use.
• Models folder (Change...) sets where the model files are kept. Existing models are not moved: move the model files into the new folder yourself, or download them again from the setup card.

15. DaVinci Resolve

Tested on DaVinci Resolve Studio 21 only. <!-- TODO owner: free Resolve is untested. -->

1. Close Resolve and run **Install for DaVinci Resolve.bat**. Windows asks for permission once, because the OFX effect is installed in Program Files.
2. Restart Resolve. Keep WispFX Server running while you work.

The effect: WispFX Matte. Find it under Effects > OpenFX > WispFX > WispFX Matte. Drop it on a clip on the Edit page, use it as a node on the Color page, or as a tool on the Fusion page.

• Pull Matte reads the clip's frames, mattes them on your GPU and shows Resolve's progress bar, with Cancel.
• Pick Subject in Browser... opens the WispFX panel with this clip, for click-to-select keyframes.
• Quality and Subject apply to the next pull. Subject takes text, for example "woman in red".
• Output: Cutout makes the clip transparent so tracks below show through (premultiplied). Matte shows the matte in black and white. Original passes the clip through.
• Shrink / Grow, Feather and Invert update live, with no re-render.

Limits: up to 1500 frames per pull. The model sees at most 1920 px on the long side. Despill is not in the effect yet. Use the script for a despilled matte.

The script: Workspace > Scripts > WispFX. Put the playhead over a clip and choose Quick matte or Pick in WispFX.... The despilled matte comes back as ProRes 4444 on the track above, in an "WispFX" bin.

<!-- TODO owner: confirm that Resolve refuses to render without a licence (V1_GAPS M1), and describe the message here once it is in place. -->

16. Updating

<!-- TODO owner: confirm these steps against the final release package and the update notice (V1_GAPS S2). -->

1. Quit After Effects and Resolve.
2. Close the WispFX server window if you started it by hand.
3. Unzip the new version to the same folder, or to a new folder and move the models folder across.
4. Run install_ae_panel.bat again. Run Install for DaVinci Resolve.bat again if you use Resolve.
5. Run setup_engine.bat again. It keeps what is already installed.

Your licence is kept in %APPDATA%\WispFX, and your mattes stay where they are.

17. Uninstalling

Use the uninstaller in the WispFX folder (uninstall.bat). It removes the After Effects panel and the Resolve effect and script. It asks before removing the models, the mattes and the engine, because those are large and your comps may use the mattes.

Before you uninstall, open Licence and click Deactivate This Computer, then contact support to free the seat if you plan to use the licence elsewhere.

<!-- TODO owner: describe the exact steps and what it removes once uninstall.bat ships (V1_GAPS M10). -->

18. Keyboard

19. Troubleshooting

20. Logs and support

Logs are in the logs folder inside the WispFX folder:

• server.log: the WispFX server.
• engine.log: the GPU engine.

When you contact support, send the two log files and tell us your GPU, your After Effects or Resolve version, and what you clicked when the problem happened.

Copy Diagnostics (About section) copies a report to the clipboard: the WispFX version, your GPU and driver, the model status, your last 20 jobs with their error messages, and the last 200 lines of the server log. Tokens, licence keys, e-mail addresses and your user name are removed first. Paste it into an e-mail to [email protected], with what you clicked when the problem happened.

Open Logs Folder (About section) opens the logs folder. A failed render keeps its error message in History: the message shows in the row, and its copy button copies it.

21. Responsible use

WispFX mattes are created with a generative AI model and are marked as such in their file metadata. If you use them to make content that shows real people or places in a way that could look real (a deep fake under the EU AI Act), you must disclose that the content was artificially manipulated.

Each job folder also has an alphaforge_provenance.json file. It records the model versions that made the mattes. Keep it with the files.

DaVinci Resolve

There are two ways to use WispFX in Resolve. Tested on DaVinci Resolve Studio 21.0; other versions, including the free edition, aren't tested yet.

Install

Run Install for DaVinci Resolve.bat (Windows asks for permission once, because OFX effects live in Program Files). Then restart Resolve and keep WispFX Server running.

1. The effect: WispFX Matte

Find it under Effects > OpenFX > WispFX > WispFX Matte. Drop it on a clip on the Edit page, use it as a node on the Color page, or as a tool on the Fusion page.

Inspector controls:

• Pull Matte reads the clip's frames, mattes them on your GPU, and shows Resolve's progress bar with Cancel. When it finishes, the clip has a real alpha channel.
• Pick Subject in Browser... opens the WispFX panel with this clip loaded, for click-to-select keyframes and previews. Resolve waits with Cancel available.
• Quality and Subject apply to the next pull. Subject takes text, for example "woman in red".
• Output offers three modes:
  • Cutout makes the clip transparent, so tracks below show through. The output is premultiplied, Resolve's convention.
  • Matte shows the matte in black and white, for checking it or for keys on the Color page.
  • Original passes the clip through untouched.
• Shrink / Grow, Feather and Invert update live, with no re-render.

The matte is cached as 16-bit PNGs in %APPDATA%\AlphaForge\ofx_cache\<key>. The key is a hidden parameter saved with the project, so the matte is still there after a restart. Pulling again replaces it and deletes the old cache.

Limits:

• Up to 1500 frames per pull. On the Fusion page Resolve reports the whole source file, so for long files the effect mattes a window starting 1 s before the playhead.
• The model sees at most 1920 px on the long side, and the matte is scaled to the timeline resolution.
• Despill isn't in the effect yet: the cutout keeps the plate's own edge colour. The script route below gives the despilled ProRes 4444.
• Windows only. Mac isn't supported.

Diagnostics: the plugin logs to %APPDATA%\AlphaForge\ofx.log.

2. The script: Workspace > Scripts > WispFX

Put the playhead over a clip and choose Quick matte or Pick in WispFX.... The despilled matte comes back as ProRes 4444 (straight alpha) on the track above, frame-aligned, in an "WispFX" bin. This is useful when you want a separate matte clip to grade or share.

Stuck on something the guide doesn't cover? The support page lists common fixes and how to reach us.