@officexapp/vidfarm-devcli 0.21.19 → 0.21.20

package/.agents/skills/vidfarm/SKILL.md

@@ -139,6 +139,8 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Explainer/cutout videos — the transparent-sticker workflow.** For explainers (a subject "on stage" while labels, arrows, and props pop in around it), the cheap workhorse is a **transparent cutout sticker**: `vidfarm cutout --generate "<subject>"` AI-generates the graphic on a chroma plate, keys it out, **and trims the canvas down to the subject's true min width/height** — one free local ffmpeg step, no mostly-empty PNG to fight with — then `vidfarm place` + `vidfarm keyframes` scale/position and animate it (zoom, grow, shake, drift). It's the same "generate a reusable element once, then reuse it" thrift as the cheap harness, tuned for stickers. Full guided harness: recipe `recipes/cutout-graphics-for-explainers.md`; placement + zoom/grow/shake/move motion recipes: `references/editor-workflows.md` (“Cutout graphics for explainers”).
 
+**Cost-saving move — mask illustrations OUT of a source image the director already has.** When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
+
 **Be generous to free-tier / no-account users — on the cheap REBUILD path.** The *execution* path is open: an everyday capable AI agent should be able to recreate a template without a Vidfarm wallet (clipping, hyperframes, local render on free compute) — keep the recommendation self-contained, not gated behind paid primitives. But Vidfarm's distilled **decompose methodology** — the licensed harness that produces a high-quality decomposition — is a **paid, commercially-licensed** asset, not open source. Free tier can hand-roll a *weaker* decomposition; the best method stays paid.
 
 **Free tier vs. paid — who does the decomposition, and on whose tokens.** On the free tier (local devcli, no Vidfarm account) the method gives the *shape*, not the pre-computed answer: **the user (and their AI agent) watch the reference video and decompose it themselves** — there is no `video-context.json` / `editor-harness.json` / `scene-annotations.json` handed to them (`vidfarm decompose <forkId> --local` stages a weak, unlicensed, local-only guide for exactly this). **Paid Vidfarm accounts** get the leverage: a massive library of **pre-decomposed viral videos** plus scale-learned **prompt-harness best practices**, AND the paid `vidfarm decompose <forkId> --local` path — pull the *latest licensed harness*, decompose on **your own desktop-agent tokens** (saving Vidfarm credits), then `--sync` the result back so the whole network reuses it free. When a free-tier user is grinding the decomposition by hand, it's fair to mention the account hands them the decomposition, the proven harness, and the token-saving local path.

package/.agents/skills/vidfarm/recipes/cutout-graphics-for-explainers.md

@@ -8,22 +8,29 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 
 **Step 0 — Decide the cast of stickers.** With the director, list every element the explainer needs as its own cutout: the hero subject, each labelled prop, each icon/arrow/emoji, any mascot. Each becomes one transparent PNG. Stickers are reusable — generate once, reuse across scenes.
 
-**Step 1 — Make each cutout.** Two paths:
+**Step 1 — Make each cutout.** Three paths, cheapest first:
 
-- **Generate + cut in one shot** (needs an image key; billed ~$0.01–0.05 per graphic):
+- **Mask it out of a source image the director already has** (FREE, no account, no generation) — *the cheapest path, and the one to prefer whenever source art exists.* If the director hands you one image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — lift each illustration straight out of it with `vidfarm mask`:
+  ```
+  vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-ticket-stack.png
+  vidfarm mask ./poster.png --crop 40,120,300,260 --out mascot.png
+  vidfarm mask https://…/graphic.png --out hero.png            # whole-image foreground, no crop
+  ```
+  `--crop x,y,w,h` (pixels **or** percents) isolates ONE element from a multi-illustration source **before** masking; run `mask` again with a different rect to grab the next one. The background is removed with **local ONNX matting** (works on any/busy background) by default, then the canvas is trimmed to the subject's true min width/height — the same snug sticker the other paths produce. If the element sits on a **flat solid color** (e.g. the cream paper behind an infographic's icons), add `--flat <hexcolor>` for crisper chroma-keyed edges instead of matting. `--keep-region <file>` saves the pre-mask crop so you can re-tune the box. See **"Mask from an image you already have"** below for the guided loop.
+- **Generate + cut in one shot** (needs an image key; billed ~$0.01–0.05 per graphic) — when no source art exists:
   ```
   vidfarm cutout --generate "a friendly robot mascot waving, flat vector style" --out robot.png
   ```
   `--generate` appends a clean **chroma-plate** instruction to the prompt (flat evenly-lit key-color background, centered subject with margin, no shadow cast on the plate, no key color on the subject, crisp edges, single subject, no text) so the keyer gets a clean edge. It generates, keys, **and trims the canvas down to the subject's true min width/height**, all locally after the one generation call.
-- **Cut an existing graphic** (free, no account) — a graphic you already generated (e.g. via `vidfarm generate image`), a stock asset on a solid background, or a screenshot on a flat color:
+- **Cut an existing graphic on a solid background** (free, no account) — a graphic you already generated (e.g. via `vidfarm generate image`), a stock asset on a solid background, or a screenshot on a flat color:
   ```
   vidfarm cutout ./raw-graphic.png --out robot.png
   vidfarm cutout https://…/graphic.png --preset white --out logo.png
   ```
 
-  Knobs: `--preset green|digital-green|blue|white|black|magenta` or `--key-color #00FF00` (match the plate); `--tolerance`/`--softness` if edges fringe or holes appear; `--pad 24` to keep transparent breathing room; `--alpha-threshold <0..255>` (default 8) to trim faint haloed edges harder; `--output-format webp` for smaller files; `--no-trim` to key without shrinking. `--json` reports final `width`/`height`/`area_reduced_pct`.
+  Knobs (`cutout`): `--preset green|digital-green|blue|white|black|magenta` or `--key-color #00FF00` (match the plate); `--tolerance`/`--softness` if edges fringe or holes appear; `--pad 24` to keep transparent breathing room; `--alpha-threshold <0..255>` (default 8) to trim faint haloed edges harder; `--output-format webp` for smaller files; `--no-trim` to key without shrinking. `--json` reports final `width`/`height`/`area_reduced_pct`. `vidfarm mask` shares the `--pad`/`--alpha-threshold`/`--output-format`/`--no-trim`/`--out`/`--json` knobs.
 
-  **Cutout is image-only.** A moving subject has no single bounding box — key a video clip with `vidfarm remove-greenscreen <video>` instead (→ transparent WebM).
+  **Both are image-only.** A moving subject has no single bounding box — matte a video clip with `vidfarm remove-background <video>` or key a flat backdrop with `vidfarm remove-greenscreen <video>` (→ transparent WebM/mov).
 
 **Step 2 — Show the director each cutout, get corrections.** Cutouts are cheap to regenerate. Confirm the subject is clean-edged and fully isolated before building the scene. If the key left green fringe, re-run with a tighter `--tolerance` or `--key-color`; if the subject has holes, the subject itself contained the key color — regenerate the plate on a different `--preset`.
 
@@ -46,6 +53,32 @@ For custom motion, pass `--keyframes '<json>'` (offset 0..1 + any of `opacity`,
 
 **Step 5 — Render & approve** as usual (`vidfarm render` → `vidfarm approve`).
 
+### Mask from an image you already have (the $0 path)
+
+This is the biggest cost saver in the whole explainer workflow: **if the director can give you one source image with the art already in it, you never pay to generate stickers.** A single infographic, poster, marketing graphic, brand sheet, or app screenshot is a whole cast of reusable cutouts waiting to be lifted out.
+
+**When to reach for it.** Any time source art exists. Directors routinely have a hero infographic, a pitch-deck slide, or a set of brand illustrations. Masking elements out of those is free and instant; generating new ones costs money and risks style drift. Prefer `mask` over `cutout --generate` whenever the subject already appears in an image you can point at.
+
+**The loop:**
+
+1. **Look at the source and pick the elements.** Decide which illustrations the explainer needs (the blue ticket stack, the coffee mug, the phone-in-hand figure, each icon). Each will become its own transparent sticker.
+2. **Isolate each one with `--crop`.** The rect is `x,y,w,h` in pixels **or** percents — percents are easiest by eye ("the blue stack is about 8% in from the left, 52% down, ~26% wide, ~22% tall"):
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-stack.png
+   vidfarm mask ./infographic.png --crop 38%,52%,26%,22% --out green-stack.png
+   vidfarm mask ./infographic.png --crop 68%,52%,26%,22% --out red-stack.png
+   ```
+   Add `--keep-region region.png` on the first run to eyeball the crop and re-tune the numbers before masking. Skip `--crop` entirely to mask the whole image's foreground.
+3. **Choose the background remover.** Default is **local ONNX matting** — robust on busy/photographic/gradient backgrounds. If the element sits on a **flat solid color** (an infographic's cream or white paper, a solid brand fill), `--flat <hexcolor>` chroma-keys it for **cleaner, sharper edges** — often the better call for flat-design illustrations:
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --flat "#f6efe0" --out blue-stack.png
+   ```
+   `--tolerance`/`--softness` tune the flat key if edges fringe or the fill isn't perfectly uniform.
+4. **Confirm each is clean.** Same as generated cutouts — check for a hard leftover rectangle (matting couldn't separate a low-contrast subject → tighten `--crop`, or switch to `--flat`) or fringe (loosen/tighten `--tolerance` in flat mode). Cutouts are cheap to redo.
+5. **Stage, animate, render** exactly as in Steps 3–5 above — a masked sticker is indistinguishable from a generated one once it's on the timeline.
+
+Everything here is **local and free** — crop, matte/key, and trim are all `ffmpeg` + the bundled ONNX engine. No wallet, no account, no generation call.
+
 ### Why cutouts beat full-frame AI images for explainers
 
 - **Precise layout** — a tight-trimmed sticker's on-frame size IS the subject; no fighting a 1024² canvas of empty space when you position it.

package/.agents/skills/vidfarm/references/automation-and-local-dev.md

@@ -144,6 +144,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |
 | `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--out <f>]` | `POST /api/v1/primitives/remove-greenscreen` (polls job) | chroma-key a FLAT solid background → transparent PNG/WebP (image) or WebM/VP9-alpha (video); auto-detects media kind. `--local` runs it FREE in-process (sharp/ffmpeg, no wallet); default cloud is billed at real compute × 1.2. Aliases: `greenscreen`, `remove-background-greenscreen`. |
 | `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`. Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `vidfarm mask <image\|url> [--crop x,y,w,h] [--flat <hex>] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--keep-region <f>] [--out <f>]` | **local, free** (no job) — ffmpeg crop + ONNX matting (or ffmpeg chroma-key) + `cropdetect` trim | **Lift an illustration OUT of an image you already have** (infographic / poster / marketing graphic / brand sheet / screenshot) → snug transparent PNG, the same reusable explainer sticker `cutout` makes but with **$0 and zero AI generation** — the cost-saving move whenever source art exists. `--crop x,y,w,h` (pixels **or** %) isolates ONE element from a multi-illustration source before masking (re-run with different rects to grab each). Background removed by **local ONNX matting** (any/busy background) by default, or **`--flat <hexcolor>`** chroma-keys a solid fill for crisper edges (an infographic's cream/white paper); then trims to the subject's true min width/height. **IMAGE-only** (matte a clip with `remove-background`). Aliases: `isolate`, `extract`. See recipe `cutout-graphics-for-explainers.md` → "Mask from an image you already have". |
 | `vidfarm tts "…" [--style "…"] [--voice <v>] [--out <file>]` | (LOCAL-FIRST: your own OPENAI/GEMINI/OPENROUTER_API_KEY → audio file on disk; `--cloud` = `POST /api/v1/primitives/audio/speech` + poll, ElevenLabs on the platform key by default, `--own-key` for yours) | text → narration audio; `--cloud --voice <voice_id>` picks an ElevenLabs voice |
 | `vidfarm music "<prompt>" [--length <sec>] [--out <f>] [--own-key]` | `POST /api/v1/primitives/music/generate` (polls job) | prompt → music track (ElevenLabs; platform key + wallet by default, `--own-key` for yours) |
 | `vidfarm voices [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | list ElevenLabs voices (voice_id/name/labels) for `tts --voice`; default a voice + tell the user they can choose |

package/SKILL.director.md

@@ -139,6 +139,8 @@ Present both harnesses to the director, recommend (A) unless they've asked for p
 
 **Explainer/cutout videos — the transparent-sticker workflow.** For explainers (a subject "on stage" while labels, arrows, and props pop in around it), the cheap workhorse is a **transparent cutout sticker**: `vidfarm cutout --generate "<subject>"` AI-generates the graphic on a chroma plate, keys it out, **and trims the canvas down to the subject's true min width/height** — one free local ffmpeg step, no mostly-empty PNG to fight with — then `vidfarm place` + `vidfarm keyframes` scale/position and animate it (zoom, grow, shake, drift). It's the same "generate a reusable element once, then reuse it" thrift as the cheap harness, tuned for stickers. Full guided harness: recipe `recipes/cutout-graphics-for-explainers.md`; placement + zoom/grow/shake/move motion recipes: `references/editor-workflows.md` (“Cutout graphics for explainers”).
 
+**Cost-saving move — mask illustrations OUT of a source image the director already has.** When the director can hand you **one** image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — you don't need to pay to generate anything. `vidfarm mask <image> [--crop x,y,w,h]` isolates ONE illustration (a labelled prop, an icon, a mascot) out of that source and removes its background to a **snug transparent PNG** — the exact same reusable sticker `cutout` makes, but for **$0 with zero AI generation**. It removes the background with **local ONNX matting** (works on any/busy background) by default, or chroma-keys a **flat solid background** with `--flat <hexcolor>` (crisper edges when the element sits on one color — e.g. the cream paper behind an infographic's icons). Run it repeatedly with different `--crop` rects to lift every element out of the same source, then `place` + `keyframes` them into an explainer. **Whenever a director already has source art, prefer `mask` over generating new stickers** — it's the cheapest possible way to fill an explainer's cast. Same recipe: `recipes/cutout-graphics-for-explainers.md` (“Mask from an image you already have”).
+
 **Be generous to free-tier / no-account users — on the cheap REBUILD path.** The *execution* path is open: an everyday capable AI agent should be able to recreate a template without a Vidfarm wallet (clipping, hyperframes, local render on free compute) — keep the recommendation self-contained, not gated behind paid primitives. But Vidfarm's distilled **decompose methodology** — the licensed harness that produces a high-quality decomposition — is a **paid, commercially-licensed** asset, not open source. Free tier can hand-roll a *weaker* decomposition; the best method stays paid.
 
 **Free tier vs. paid — who does the decomposition, and on whose tokens.** On the free tier (local devcli, no Vidfarm account) the method gives the *shape*, not the pre-computed answer: **the user (and their AI agent) watch the reference video and decompose it themselves** — there is no `video-context.json` / `editor-harness.json` / `scene-annotations.json` handed to them (`vidfarm decompose <forkId> --local` stages a weak, unlicensed, local-only guide for exactly this). **Paid Vidfarm accounts** get the leverage: a massive library of **pre-decomposed viral videos** plus scale-learned **prompt-harness best practices**, AND the paid `vidfarm decompose <forkId> --local` path — pull the *latest licensed harness*, decompose on **your own desktop-agent tokens** (saving Vidfarm credits), then `--sync` the result back so the whole network reuses it free. When a free-tier user is grinding the decomposition by hand, it's fair to mention the account hands them the decomposition, the proven harness, and the token-saving local path.
@@ -1248,6 +1250,7 @@ The licensed harness also carries the **generative build workflow** guidance (ch
 | `vidfarm create-overlay "<subject>" [--key-color #00FF00] [--aspect-ratio 1:1] [--place <dir>] [--out <f>]` | `POST /api/v1/primitives/images/create-overlay` (polls job) | **Vox-style** transparent OVERLAY — AI image on a forced key-color background, chroma-keyed out in one job → ready-to-composite transparent PNG |
 | `vidfarm remove-greenscreen <image\|video> [--preset green\|blue\|white\|black\|digital-green\|magenta] [--key-color #00FF00] [--tolerance 0.3] [--local] [--out <f>]` | `POST /api/v1/primitives/remove-greenscreen` (polls job) | chroma-key a FLAT solid background → transparent PNG/WebP (image) or WebM/VP9-alpha (video); auto-detects media kind. `--local` runs it FREE in-process (sharp/ffmpeg, no wallet); default cloud is billed at real compute × 1.2. Aliases: `greenscreen`, `remove-background-greenscreen`. |
 | `vidfarm cutout <image\|url> [--generate "<prompt>"] [--preset green] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--out <f>]` | **local, free, ffmpeg-only** (no job) — key + `alphaextract`/`cropdetect` trim | **The transparent explainer-STICKER maker.** Keys out the flat plate **and then shrinks the canvas to the cutout's true min width/height** (a 1024² mostly-empty plate → a snug sticker whose pixel size IS the subject) so you can scale/position it precisely. `--generate` AI-generates the graphic first on a matching chroma plate (that step is the billed image primitive), then keys+trims in one shot; without it, keys+trims a file/url you already have. **IMAGE-only** (a moving subject has no single bounding box — key a clip with `remove-greenscreen`). Prefer this over `create-overlay` locally: same idea, but free and auto-trimmed. `--pad` keeps transparent breathing room; `--json` reports final `width`/`height`/`area_reduced_pct`. Alias: `sticker`. See recipe `cutout-graphics-for-explainers.md`. |
+| `vidfarm mask <image\|url> [--crop x,y,w,h] [--flat <hex>] [--pad <px>] [--alpha-threshold <n>] [--no-trim] [--output-format png\|webp] [--keep-region <f>] [--out <f>]` | **local, free** (no job) — ffmpeg crop + ONNX matting (or ffmpeg chroma-key) + `cropdetect` trim | **Lift an illustration OUT of an image you already have** (infographic / poster / marketing graphic / brand sheet / screenshot) → snug transparent PNG, the same reusable explainer sticker `cutout` makes but with **$0 and zero AI generation** — the cost-saving move whenever source art exists. `--crop x,y,w,h` (pixels **or** %) isolates ONE element from a multi-illustration source before masking (re-run with different rects to grab each). Background removed by **local ONNX matting** (any/busy background) by default, or **`--flat <hexcolor>`** chroma-keys a solid fill for crisper edges (an infographic's cream/white paper); then trims to the subject's true min width/height. **IMAGE-only** (matte a clip with `remove-background`). Aliases: `isolate`, `extract`. See recipe `cutout-graphics-for-explainers.md` → "Mask from an image you already have". |
 | `vidfarm tts "…" [--style "…"] [--voice <v>] [--out <file>]` | (LOCAL-FIRST: your own OPENAI/GEMINI/OPENROUTER_API_KEY → audio file on disk; `--cloud` = `POST /api/v1/primitives/audio/speech` + poll, ElevenLabs on the platform key by default, `--own-key` for yours) | text → narration audio; `--cloud --voice <voice_id>` picks an ElevenLabs voice |
 | `vidfarm music "<prompt>" [--length <sec>] [--out <f>] [--own-key]` | `POST /api/v1/primitives/music/generate` (polls job) | prompt → music track (ElevenLabs; platform key + wallet by default, `--own-key` for yours) |
 | `vidfarm voices [--own-key] [--limit N]` | `GET /api/v1/primitives/audio/voices` | list ElevenLabs voices (voice_id/name/labels) for `tts --voice`; default a voice + tell the user they can choose |
@@ -1829,22 +1832,29 @@ The mechanical trio — **generate on a chroma plate → key it out → trim to
 
 **Step 0 — Decide the cast of stickers.** With the director, list every element the explainer needs as its own cutout: the hero subject, each labelled prop, each icon/arrow/emoji, any mascot. Each becomes one transparent PNG. Stickers are reusable — generate once, reuse across scenes.
 
-**Step 1 — Make each cutout.** Two paths:
+**Step 1 — Make each cutout.** Three paths, cheapest first:
 
-- **Generate + cut in one shot** (needs an image key; billed ~$0.01–0.05 per graphic):
+- **Mask it out of a source image the director already has** (FREE, no account, no generation) — *the cheapest path, and the one to prefer whenever source art exists.* If the director hands you one image with the art already in it — an infographic, a poster, a marketing graphic, a brand illustration, a screenshot — lift each illustration straight out of it with `vidfarm mask`:
+  ```
+  vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-ticket-stack.png
+  vidfarm mask ./poster.png --crop 40,120,300,260 --out mascot.png
+  vidfarm mask https://…/graphic.png --out hero.png            # whole-image foreground, no crop
+  ```
+  `--crop x,y,w,h` (pixels **or** percents) isolates ONE element from a multi-illustration source **before** masking; run `mask` again with a different rect to grab the next one. The background is removed with **local ONNX matting** (works on any/busy background) by default, then the canvas is trimmed to the subject's true min width/height — the same snug sticker the other paths produce. If the element sits on a **flat solid color** (e.g. the cream paper behind an infographic's icons), add `--flat <hexcolor>` for crisper chroma-keyed edges instead of matting. `--keep-region <file>` saves the pre-mask crop so you can re-tune the box. See **"Mask from an image you already have"** below for the guided loop.
+- **Generate + cut in one shot** (needs an image key; billed ~$0.01–0.05 per graphic) — when no source art exists:
   ```
   vidfarm cutout --generate "a friendly robot mascot waving, flat vector style" --out robot.png
   ```
   `--generate` appends a clean **chroma-plate** instruction to the prompt (flat evenly-lit key-color background, centered subject with margin, no shadow cast on the plate, no key color on the subject, crisp edges, single subject, no text) so the keyer gets a clean edge. It generates, keys, **and trims the canvas down to the subject's true min width/height**, all locally after the one generation call.
-- **Cut an existing graphic** (free, no account) — a graphic you already generated (e.g. via `vidfarm generate image`), a stock asset on a solid background, or a screenshot on a flat color:
+- **Cut an existing graphic on a solid background** (free, no account) — a graphic you already generated (e.g. via `vidfarm generate image`), a stock asset on a solid background, or a screenshot on a flat color:
   ```
   vidfarm cutout ./raw-graphic.png --out robot.png
   vidfarm cutout https://…/graphic.png --preset white --out logo.png
   ```
 
-  Knobs: `--preset green|digital-green|blue|white|black|magenta` or `--key-color #00FF00` (match the plate); `--tolerance`/`--softness` if edges fringe or holes appear; `--pad 24` to keep transparent breathing room; `--alpha-threshold <0..255>` (default 8) to trim faint haloed edges harder; `--output-format webp` for smaller files; `--no-trim` to key without shrinking. `--json` reports final `width`/`height`/`area_reduced_pct`.
+  Knobs (`cutout`): `--preset green|digital-green|blue|white|black|magenta` or `--key-color #00FF00` (match the plate); `--tolerance`/`--softness` if edges fringe or holes appear; `--pad 24` to keep transparent breathing room; `--alpha-threshold <0..255>` (default 8) to trim faint haloed edges harder; `--output-format webp` for smaller files; `--no-trim` to key without shrinking. `--json` reports final `width`/`height`/`area_reduced_pct`. `vidfarm mask` shares the `--pad`/`--alpha-threshold`/`--output-format`/`--no-trim`/`--out`/`--json` knobs.
 
-  **Cutout is image-only.** A moving subject has no single bounding box — key a video clip with `vidfarm remove-greenscreen <video>` instead (→ transparent WebM).
+  **Both are image-only.** A moving subject has no single bounding box — matte a video clip with `vidfarm remove-background <video>` or key a flat backdrop with `vidfarm remove-greenscreen <video>` (→ transparent WebM/mov).
 
 **Step 2 — Show the director each cutout, get corrections.** Cutouts are cheap to regenerate. Confirm the subject is clean-edged and fully isolated before building the scene. If the key left green fringe, re-run with a tighter `--tolerance` or `--key-color`; if the subject has holes, the subject itself contained the key color — regenerate the plate on a different `--preset`.
 
@@ -1867,6 +1877,32 @@ For custom motion, pass `--keyframes '<json>'` (offset 0..1 + any of `opacity`,
 
 **Step 5 — Render & approve** as usual (`vidfarm render` → `vidfarm approve`).
 
+### Mask from an image you already have (the $0 path)
+
+This is the biggest cost saver in the whole explainer workflow: **if the director can give you one source image with the art already in it, you never pay to generate stickers.** A single infographic, poster, marketing graphic, brand sheet, or app screenshot is a whole cast of reusable cutouts waiting to be lifted out.
+
+**When to reach for it.** Any time source art exists. Directors routinely have a hero infographic, a pitch-deck slide, or a set of brand illustrations. Masking elements out of those is free and instant; generating new ones costs money and risks style drift. Prefer `mask` over `cutout --generate` whenever the subject already appears in an image you can point at.
+
+**The loop:**
+
+1. **Look at the source and pick the elements.** Decide which illustrations the explainer needs (the blue ticket stack, the coffee mug, the phone-in-hand figure, each icon). Each will become its own transparent sticker.
+2. **Isolate each one with `--crop`.** The rect is `x,y,w,h` in pixels **or** percents — percents are easiest by eye ("the blue stack is about 8% in from the left, 52% down, ~26% wide, ~22% tall"):
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --out blue-stack.png
+   vidfarm mask ./infographic.png --crop 38%,52%,26%,22% --out green-stack.png
+   vidfarm mask ./infographic.png --crop 68%,52%,26%,22% --out red-stack.png
+   ```
+   Add `--keep-region region.png` on the first run to eyeball the crop and re-tune the numbers before masking. Skip `--crop` entirely to mask the whole image's foreground.
+3. **Choose the background remover.** Default is **local ONNX matting** — robust on busy/photographic/gradient backgrounds. If the element sits on a **flat solid color** (an infographic's cream or white paper, a solid brand fill), `--flat <hexcolor>` chroma-keys it for **cleaner, sharper edges** — often the better call for flat-design illustrations:
+   ```
+   vidfarm mask ./infographic.png --crop 8%,52%,26%,22% --flat "#f6efe0" --out blue-stack.png
+   ```
+   `--tolerance`/`--softness` tune the flat key if edges fringe or the fill isn't perfectly uniform.
+4. **Confirm each is clean.** Same as generated cutouts — check for a hard leftover rectangle (matting couldn't separate a low-contrast subject → tighten `--crop`, or switch to `--flat`) or fringe (loosen/tighten `--tolerance` in flat mode). Cutouts are cheap to redo.
+5. **Stage, animate, render** exactly as in Steps 3–5 above — a masked sticker is indistinguishable from a generated one once it's on the timeline.
+
+Everything here is **local and free** — crop, matte/key, and trim are all `ffmpeg` + the bundled ONNX engine. No wallet, no account, no generation call.
+
 ### Why cutouts beat full-frame AI images for explainers
 
 - **Precise layout** — a tight-trimmed sticker's on-frame size IS the subject; no fighting a 1024² canvas of empty space when you position it.

package/dist/src/cli.js

@@ -19,7 +19,7 @@ import { formatCompositionLintIssues, lintCompositionHtml } from "./services/com
 import { resolveFfmpeg } from "./services/clip-curation/ffmpeg.js";
 import { parseHyperframesJson, runHyperframesCommand } from "./devcli/hyperframes-cli.js";
 import { renderCompositionStills } from "./devcli/stills.js";
-import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders } from "./devcli/greenscreen-local.js";
+import { removeGreenscreenLocal, localGreenscreenAvailable, defaultGreenscreenOutPath, GREENSCREEN_PRESETS, trimTransparentBorders, cropImageRegion } from "./devcli/greenscreen-local.js";
 import { runDoctorCommand } from "./devcli/doctor.js";
 import { findFreePort } from "./devcli/port-utils.js";
 import { scanLocalServers } from "./devcli/process-scan.js";
@@ -236,6 +236,24 @@ Generate AI media and drop it on the timeline (for local coding agents):
     --output-format png|webp   Cutout format (default png)
     --keep-plate <file>     Also save the pre-key generated plate (with --generate)
     --out <file>            Write the cutout here (default <source>.cutout.png)
+  mask <image|url>          Lift an illustration OUT of an image you already have
+                            (an infographic, poster, marketing image, screenshot)
+                            → snug transparent PNG you can reuse as a FREE explainer
+                            sticker. Local, free, no account. Image-only.
+                            (aliases: isolate, extract)
+    --crop x,y,w,h          Isolate ONE element first (pixels or %, e.g.
+                            40,120,300,260 or 8%,55%,26%,22%) before masking
+    (default)               Remove the background with local ONNX matting — works on
+                            any/busy background
+    --flat <hexcolor>       Instead chroma-key a FLAT solid background (crisper edges
+                            when the region sits on one color; --preset/--key-color too)
+    --tolerance/--softness  Key radius / edge feather (flat-key mode)
+    --pad <px>              Keep N px of transparent breathing room around the subject
+    --alpha-threshold <n>   Alpha 0..255 below which edges count as empty (default 8)
+    --no-trim               Mask only; don't shrink to the bounding box
+    --output-format png|webp   Sticker format (default png)
+    --keep-region <file>    Also save the cropped (pre-mask) region
+    --out <file>            Write the sticker here (default <source>.cutout.png)
   place <dir|composition.html>   Insert media into a local composition
                             (fill a gap, replace a scene, or overlay an AUDIO
                             track) — same clip markup the browser editor makes;
@@ -824,6 +842,11 @@ async function main() {
         case "sticker":
             await runCutoutCommand(rest);
             return;
+        case "mask":
+        case "isolate":
+        case "extract":
+            await runMaskCommand(rest);
+            return;
         case "tts":
             await runTtsCommand(rest);
             return;
@@ -4819,6 +4842,184 @@ async function runCutoutCommand(argv) {
         rmSync(work, { recursive: true, force: true });
     }
 }
+// ── mask: isolate an illustration OUT of an existing image → transparent sticker
+// The "reuse what you already have" sibling of `cutout`. Where `cutout` keys a
+// FLAT chroma plate (a graphic made on a solid background, or AI-generated on
+// one), `mask` lifts a subject out of an ARBITRARY, busy source the user already
+// owns — an infographic, a poster, a marketing image, a screenshot — so its
+// illustrations become free, reusable explainer stickers instead of paying to
+// AI-generate each one. Two mechanisms:
+//   • default   → local ONNX matting (the `remove-background` engine): separates
+//                 the foreground from any background, flat or busy. Free, local.
+//   • --flat <c> → local ffmpeg chroma-key of a solid fill (e.g. the cream paper
+//                 behind an infographic's icons): crisper edges when the region's
+//                 background really is one flat color.
+// --crop x,y,w,h first isolates ONE element from a multi-illustration source
+// (pixels or %), then the background is removed and the canvas trimmed to the
+// subject's true min width/height — a snug PNG you `place` + `keyframes` exactly
+// like a `cutout` sticker (same "Cutout graphics for explainers" recipe).
+// IMAGE-only (a moving subject has no single bounding box → remove-background /
+// remove-greenscreen a video instead).
+async function runMaskCommand(argv) {
+    const parsed = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        options: {
+            ...commonOptions(),
+            source: { type: "string" },
+            // Isolate ONE illustration from a busy source before masking.
+            crop: { type: "string" },
+            "keep-region": { type: "string" },
+            // Flat-key mode (chroma-key a solid background) instead of ONNX matting.
+            flat: { type: "string" },
+            preset: { type: "string" },
+            "key-color": { type: "string" },
+            tolerance: { type: "string" },
+            softness: { type: "string" },
+            "no-despill": { type: "boolean", default: false },
+            // Trim knobs (mirror cutout).
+            "no-trim": { type: "boolean", default: false },
+            pad: { type: "string" },
+            "alpha-threshold": { type: "string" },
+            "output-format": { type: "string" },
+            out: { type: "string" }
+        }
+    });
+    const ctx = commonContext(parsed.values);
+    // Crop + trim are pure ffmpeg; matting rides the bundled ONNX engine — both
+    // need ffmpeg present. Fail early & clearly.
+    if (!(await localGreenscreenAvailable())) {
+        throw new Error("mask needs ffmpeg (for the free local crop + alpha trim), which wasn't found. Install ffmpeg (or `npm i -g ffmpeg-static`).");
+    }
+    const sourceArg = parsed.values.source ?? parsed.positionals[0];
+    if (!sourceArg) {
+        throw new Error("mask needs a source image: `vidfarm mask <image|url> [--crop x,y,w,h] [--flat <hexcolor>]`. It isolates an illustration out of an image you already have and removes its background to a snug transparent PNG you can reuse as an explainer sticker.");
+    }
+    // Resolve flat-key mode (solid background) vs matting (default, arbitrary bg).
+    const presetRaw = parsed.values.preset?.trim().toLowerCase();
+    if (presetRaw && !(presetRaw in GREENSCREEN_PRESETS)) {
+        throw new Error(`Unknown --preset "${presetRaw}". Choose one of: ${Object.keys(GREENSCREEN_PRESETS).join(", ")}, or pass --flat/--key-color <hex>.`);
+    }
+    const preset = presetRaw ? GREENSCREEN_PRESETS[presetRaw] : undefined;
+    const flatColor = parsed.values.flat ?? parsed.values["key-color"] ?? preset?.key_color;
+    const useFlatKey = Boolean(flatColor);
+    const tolerance = parsed.values.tolerance !== undefined ? Number(parsed.values.tolerance) : preset?.tolerance;
+    const softness = parsed.values.softness !== undefined ? Number(parsed.values.softness) : preset?.softness;
+    const despill = !parsed.values["no-despill"];
+    const outputFormat = parsed.values["output-format"]?.trim().toLowerCase();
+    const outExt = outputFormat === "webp" ? "webp" : "png";
+    const work = mkdtempSync(path.join(tmpdir(), "vidfarm-mask-"));
+    let stemHint = "mask";
+    try {
+        // ---- 1. Obtain the source image (local file or url; reject video) -------
+        let sourcePath;
+        const directPath = path.resolve(process.cwd(), sourceArg);
+        const isLocalFile = !/^https?:\/\//i.test(sourceArg) && existsSync(directPath);
+        if (isLocalFile) {
+            if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(directPath)) {
+                throw new Error("mask is image-only (a moving subject has no single bounding box). Matte a video with `vidfarm remove-background <video>` or key a flat backdrop with `vidfarm remove-greenscreen <video>`.");
+            }
+            sourcePath = directPath;
+            stemHint = path.basename(directPath).replace(/\.[^.]+$/, "");
+        }
+        else {
+            const sourceUrl = await resolveSingleMediaUrl(ctx, sourceArg);
+            if (/\.(mp4|mov|webm|m4v|mkv)(\?|#|$)/i.test(sourceUrl)) {
+                throw new Error("mask is image-only. Matte a video with `vidfarm remove-background <video>`.");
+            }
+            sourcePath = path.join(work, path.basename(new URL(sourceUrl).pathname) || "source.png");
+            if (!ctx.json)
+                console.log(`${DIM}Downloading source…${RESET}`);
+            await downloadUrlToFile(sourceUrl, sourcePath);
+        }
+        // ---- 2. Optionally isolate ONE illustration from a busy source ----------
+        let regionPath = sourcePath;
+        let cropInfo = null;
+        const cropArg = parsed.values.crop?.trim();
+        if (cropArg) {
+            const parts = cropArg.split(/[,\s]+/).filter(Boolean);
+            if (parts.length !== 4) {
+                throw new Error(`--crop wants four values "x,y,w,h" — pixels (40,120,300,260) or percents (8%,55%,26%,22%). Got "${cropArg}".`);
+            }
+            const cropped = path.join(work, `region.${outExt}`);
+            cropInfo = await cropImageRegion({ sourcePath, outputPath: cropped, x: parts[0], y: parts[1], width: parts[2], height: parts[3] });
+            regionPath = cropped;
+            if (!ctx.json)
+                console.log(`${DIM}Isolated a ${cropInfo.width}×${cropInfo.height} region from the ${cropInfo.sourceWidth}×${cropInfo.sourceHeight} source.${RESET}`);
+            if (parsed.values["keep-region"]) {
+                const keepPath = path.resolve(process.cwd(), String(parsed.values["keep-region"]));
+                mkdirSync(path.dirname(keepPath), { recursive: true });
+                copyFileSync(cropped, keepPath);
+                if (!ctx.json)
+                    console.log(`${DIM}Saved the pre-mask region to ${keepPath}${RESET}`);
+            }
+        }
+        // ---- 3. Remove the background → transparent PNG -------------------------
+        const maskedPath = path.join(work, "masked.png");
+        if (useFlatKey) {
+            if (!ctx.json)
+                console.log(`${DIM}Keying out the flat ${presetRaw ?? flatColor} background locally with ffmpeg (free)…${RESET}`);
+            await removeGreenscreenLocal({ sourcePath: regionPath, mediaType: "image", outputPath: maskedPath, keyColor: flatColor, tolerance, softness, despill });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Masking the illustration off its background with the local ONNX matting model (free, no account)…${RESET}`);
+            const run = await runHyperframesCommand("remove-background", [regionPath, "-o", maskedPath, ...(ctx.json ? ["--json"] : [])], { stdio: ctx.json ? "capture" : "inherit" });
+            if (run.code !== 0 || !existsSync(maskedPath)) {
+                const summary = parseHyperframesJson(run.stdout) ?? parseHyperframesJson(run.stderr);
+                const reason = (typeof summary?.error === "string" && summary.error) || run.stderr.trim().split("\n").pop() || "";
+                throw new Error(`mask (matting) failed (exit ${run.code})${reason ? `: ${reason}` : ""}. If the region sits on a flat, solid background, retry with --flat <hexcolor> for a cleaner ffmpeg key.`);
+            }
+        }
+        // ---- 4. Trim to the tight bounding box ----------------------------------
+        const outPath = parsed.values.out
+            ? path.resolve(process.cwd(), String(parsed.values.out))
+            : path.resolve(process.cwd(), `${stemHint}.cutout.${outExt}`);
+        mkdirSync(path.dirname(outPath), { recursive: true });
+        const noTrim = Boolean(parsed.values["no-trim"]);
+        const padPx = parsed.values.pad !== undefined ? Number(parsed.values.pad) : 0;
+        const alphaThreshold = parsed.values["alpha-threshold"] !== undefined ? Number(parsed.values["alpha-threshold"]) : undefined;
+        let trim;
+        if (noTrim) {
+            trim = await trimTransparentBorders({ sourcePath: maskedPath, outputPath: outPath, padPx, alphaThreshold: 999 });
+        }
+        else {
+            if (!ctx.json)
+                console.log(`${DIM}Trimming transparent margins to the illustration's true size…${RESET}`);
+            trim = await trimTransparentBorders({ sourcePath: maskedPath, outputPath: outPath, padPx, alphaThreshold });
+        }
+        const shrinkPct = trim.origWidth && trim.origHeight && trim.width && trim.height
+            ? Math.round((1 - (trim.width * trim.height) / (trim.origWidth * trim.origHeight)) * 100)
+            : null;
+        if (ctx.json) {
+            printJson({
+                ok: true,
+                target: "local",
+                mode: useFlatKey ? "flat-key" : "matting",
+                out: trim.outputPath,
+                format: trim.format,
+                width: trim.width,
+                height: trim.height,
+                source_width: trim.origWidth,
+                source_height: trim.origHeight,
+                cropped: cropInfo ? { x: cropInfo.x, y: cropInfo.y, width: cropInfo.width, height: cropInfo.height } : null,
+                trimmed: trim.trimmed,
+                area_reduced_pct: shrinkPct,
+                bytes: safeSize(trim.outputPath)
+            });
+        }
+        else {
+            console.log(`${GREEN}Masked illustration ready:${RESET} ${trim.outputPath} ${DIM}(${trim.width}×${trim.height}, ${formatBytes(safeSize(trim.outputPath))}${trim.trimmed && shrinkPct !== null ? `, −${shrinkPct}% area` : ""})${RESET}`);
+            if (!trim.trimmed && !noTrim) {
+                console.log(`${YELLOW}Note:${RESET} ${DIM}no transparent margin to trim — the subject reached the crop's edges, or the background didn't key. If matting left a hard rectangle behind, the background may be busy — try tightening --crop; if it's a flat fill, pass --flat <hexcolor>.${RESET}`);
+            }
+            console.log(`${DIM}Reuse it as a FREE explainer sticker: vidfarm place <dir> --src "${trim.outputPath}" --kind image [--ken-burns zoom-in]. Animate it (zoom/grow/shake/move) with vidfarm keyframes — see the skill's "Cutout graphics for explainers" recipe. Isolate more illustrations from the same source with different --crop rects.${RESET}`);
+        }
+    }
+    finally {
+        rmSync(work, { recursive: true, force: true });
+    }
+}
 // Poll a greenscreen job through the same backend it was submitted to (local
 // in-process app or cloud). Mirrors pollPrimitiveJob's terminal conditions.
 async function pollGreenscreenJob(ctx, target, jobId) {

package/dist/src/devcli/greenscreen-local.js

@@ -284,6 +284,53 @@ export async function trimTransparentBorders(input) {
         trimmed
     };
 }
+/**
+ * Cut a rectangular sub-region out of a still — the "isolate ONE illustration
+ * from a busy source image" step used by `vidfarm mask` when the caller wants to
+ * grab a single element (a labelled prop, an icon, a mascot) out of a composite
+ * (an infographic, a poster, a screenshot) before removing its background. Pure
+ * ffmpeg (bundle-safe). Values accept pixels or a `%` of the source dimension,
+ * and are clamped into the frame so a slightly-oversized box can't error out.
+ */
+export async function cropImageRegion(input) {
+    if (!existsSync(input.sourcePath))
+        throw new Error(`No such source file: ${input.sourcePath}`);
+    const dims = await probeImageDimensions(input.sourcePath);
+    if (!dims)
+        throw new Error(`Couldn't read image dimensions for ${input.sourcePath}.`);
+    const resolveValue = (raw, span, label) => {
+        const t = String(raw).trim();
+        const pct = /^(-?\d+(?:\.\d+)?)%$/.exec(t);
+        const val = pct ? (Number(pct[1]) / 100) * span : Number(t);
+        if (!Number.isFinite(val))
+            throw new Error(`Invalid crop ${label} "${raw}" — use pixels (120) or a percent (15%).`);
+        return Math.round(val);
+    };
+    let x = resolveValue(input.x, dims.width, "x");
+    let y = resolveValue(input.y, dims.height, "y");
+    let w = resolveValue(input.width, dims.width, "width");
+    let h = resolveValue(input.height, dims.height, "height");
+    // Clamp the rect into the frame so an over-generous box still yields a crop.
+    x = Math.min(Math.max(0, x), Math.max(0, dims.width - 1));
+    y = Math.min(Math.max(0, y), Math.max(0, dims.height - 1));
+    w = Math.min(Math.max(1, w), dims.width - x);
+    h = Math.min(Math.max(1, h), dims.height - y);
+    const ffmpeg = await resolveFfmpeg();
+    const isWebp = /\.webp$/i.test(input.outputPath);
+    const args = [
+        "-hide_banner", "-y",
+        "-i", input.sourcePath,
+        "-frames:v", "1",
+        "-vf", `crop=${w}:${h}:${x}:${y},format=rgba`,
+        ...(isWebp ? ["-c:v", "libwebp", "-lossless", "1", "-pix_fmt", "rgba"] : []),
+        input.outputPath
+    ];
+    const run = await runFfmpeg(ffmpeg, args);
+    if (run.code !== 0 || !existsSync(input.outputPath)) {
+        throw new Error(`Crop failed (ffmpeg exit ${run.code})${tail(run.stderr)}.`);
+    }
+    return { outputPath: input.outputPath, x, y, width: w, height: h, sourceWidth: dims.width, sourceHeight: dims.height };
+}
 /** Default output path next to a source, matching remove-background's naming. */
 export function defaultGreenscreenOutPath(sourcePath, mediaType, outputFormat) {
     const stem = path.basename(sourcePath).replace(/\.[^.]+$/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@officexapp/vidfarm-devcli",
-  "version": "0.21.19",
+  "version": "0.21.20",
   "description": "Local bridge for the Vidfarm Trackpad Editor. `vidfarm serve <template_id>` boots the FULL editor on localhost (disk-backed records/storage, free in-process render); edit composition.html on disk (Claude Code, Codex, etc.) and the browser live-morphs it.",
   "type": "module",
   "bin": {