fablecut 1.12.1 → 1.13.0

package/CLAUDE.md

@@ -37,7 +37,10 @@ Every Claude Code session then has these tools:
 - `fablecut_export` — render the timeline to a file in `exports/` with the editor's own
   Fast export (open tab, or headless Chrome / Edge). See "Export" below.
 - `fablecut_scopes` — measure the graded picture at a moment (levels, clipping, colour
-  cast), as the editor's scopes see it. See "Color" below.
+  cast), as the editor's scopes see it; also what a grade layer or a clip's masks
+  select. See "Color" and "Masks" below.
+- `fablecut_track` — motion tracking: follow a region of a video clip, store it as
+  a track, and make a mask or another clip follow it. See "Tracking" below.
 
 ### Token-efficient editing (important for agents)
 
@@ -313,7 +316,8 @@ Examples in `library/svg/`: `sparkles.svg` (loop), `lower-third.svg`,
 | `scale` | 1 | |
 | `rotation` | 0 | degrees |
 | `opacity` | 1 | 0–1 |
-| `blend` | "normal" | multiply · screen · overlay · lighter · soft-light · hard-light · color-dodge · darken · lighten · difference |
+| `blend` | "normal" | how the clip lays over what is under it (see Track mattes and blending) |
+| `matte` · `matteTrack` | — | a track matte (see Track mattes and blending) |
 
 **Layout** (video/image/svg):
 | prop | default | notes |
@@ -424,6 +428,10 @@ intensity. Keyframe/transition it like any clip. Put it on V2/V3 above the
 footage. Example: 0.3 s impact shake over everything =
 `{kind:"adjust", track:"V3", duration:0.3, props:{shake:18}}`.
 
+**Masks** (`masks`, video/image/svg/text/adjust): shapes that cut what the clip
+shows — rect, ellipse, bezier, free-hand; feather, expand, invert, add /
+subtract / intersect, keyframes. See "Masks" below.
+
 **Animatable props** (usable in `keyframes`): x, y, scale, rotation, opacity,
 volume, pan, duck, speed, brightness, contrast, saturation, hue, blur, grayscale, sepia,
 invert, temperature, tint, vignette, cornerRadius, shake, rgbSplit, grain,
@@ -619,12 +627,12 @@ each one's qualifier looks at the picture as it reaches that layer.
 | `qualifier.hue` | `[centre°, width°, soft°]` — hues within ±width/2 of the centre, easing out over `soft`; wraps through red. Greys carry no hue, so a hue range leaves them out |
 | `qualifier.sat` · `qualifier.luma` | `[low, high, soft]` on 0…1 — saturation (HSV) / Rec.709 luma between low and high |
 | `qualifier.invert` | select everything else |
-| `mask.shape` | `ellipse` · `rect` · `poly` |
+| `mask.shape` | `ellipse` · `rect` · `poly` · `bezier` (or `freehand` with a `stroke`, fitted into a bezier — see "Masks") |
 | `mask.x` · `mask.y` | centre, as fractions of the clip's picture (0…1, y down) |
 | `mask.w` · `mask.h` | size, fractions of the picture's width / height (ellipse, rect) |
 | `mask.rotation` | degrees, clockwise |
 | `mask.feather` | soft edge, a fraction of the picture's height (0…0.5), centred on the outline |
-| `mask.points` | poly: 3–16 `[dx, dy]` corners around `x, y` (fractions of width / height) |
+| `mask.points` | poly: 3–16 `[dx, dy]` corners around `x, y` (fractions of width / height); bezier: 3–24 anchors `[dx, dy]` or `[dx, dy, inX, inY, outX, outY]` with curve handles |
 | `mask.invert` | grade outside the shape |
 | `mask.keys` | animate it: `[{t, x?, y?, w?, h?, rotation?, feather?, ease?}]`, `t` in seconds from the clip's start; each param eases between the keys that set it (`ease` on the arriving key, as for clip keyframes) |
 
@@ -639,8 +647,9 @@ curves edit that layer, and three more sections appear: the layer's name,
 reorder, **Delete**; **Qualifier** — **Pick** then click a colour in the
 monitor to select its hue, saturation and luma, then tune the ranges; and
 **Mask** — pick a shape and drag it on the monitor (inside moves it, the
-handles resize it, the knob rotates it, Shift snaps to 15°; on a poly,
-Ctrl-click adds a point and double-click removes one). **◆ Key** keys the
+handles resize it, the knob rotates it, Shift snaps to 15°; on a poly or
+bezier, Ctrl-click adds a point and double-click removes one), or **Draw** a
+free-hand outline on the monitor (it becomes a bezier). **◆ Key** keys the
 shape at the playhead; once it has keys, every change to the shape keys.
 
 **Wheel colours.** A wheel's `r, g, b` normally carry no brightness: they are a
@@ -703,6 +712,219 @@ other shot of the scene until its median and cast land near the hero's. In the
 editor, **Copy** / **Paste** on the Color tab pastes one clip's grade onto every
 selected clip.
 
+### Masks
+
+A clip's masks cut what it shows: only the parts the masks keep reach the
+frame, so a clip can be isolated, revealed or cut through, and anything under
+it shows in the gaps. They live in `props.masks` on any video, image, svg,
+text or adjustment clip. On an adjustment layer they limit where its effects
+and grade apply. They run in preview and export alike. The clip draws as usual,
+the masks cut it, and then its `opacity` and `blend` composite it.
+
+```jsonc
+"masks": [
+  { "name": "Subject", "shape": "ellipse", "x": 0.52, "y": 0.45, "w": 0.4, "h": 0.7, "feather": 40 },
+  { "name": "Hole", "shape": "rect", "mode": "subtract", "x": 0.6, "y": 0.4, "w": 0.1, "h": 0.1 },
+  { "shape": "bezier", "x": 0.3, "y": 0.7, "expand": 8,
+    "points": [[0, -0.1], [0.12, 0.08, 0, -0.05, 0, 0.05], [-0.12, 0.08]],
+    "keys": [{ "t": 0, "x": 0.3 }, { "t": 2, "x": 0.6, "ease": "linear" }] }
+]
+```
+
+| key | default | does |
+|---|---|---|
+| `shape` | — | `rect` · `ellipse` · `bezier` (write `freehand` with a `stroke` to have one drawn for you) |
+| `x` · `y` | 0.5 | centre, as fractions of the clip's picture (0…1, y down) |
+| `w` · `h` | 0.5 | size, fractions of the picture's width / height (rect, ellipse) |
+| `points` | — | bezier: 3–64 anchors around `x, y`, each `[dx, dy]` (a corner) or `[dx, dy, inX, inY, outX, outY]` (with curve handles relative to the anchor), all fractions of the picture's width / height |
+| `stroke` | — | freehand only: `[[u, v], …]` picture fractions along an outline; it is simplified and stored as an editable `bezier` |
+| `scale` · `rotation` | 1 · 0 | about the centre; degrees clockwise |
+| `mode` | `add` | how this mask combines with the ones before it: `add` · `subtract` · `intersect` · `difference` |
+| `invert` | false | use everything outside the shape |
+| `opacity` | 1 | 0…1, how strongly this mask counts |
+| `feather` | 0 | soft edge, project pixels, centred on the outline |
+| `expand` | 0 | grow (+) or shrink (−) the outline, project pixels |
+| `name` · `on` | — | a label; `on:false` turns the mask off |
+| `keys` | — | animate it: `[{t, x?, y?, w?, h?, scale?, rotation?, feather?, expand?, opacity?, points?, ease?}]`, `t` in seconds from the clip's start; each param eases between the keys that set it (`ease` on the arriving key, as for clip keyframes). `points` keys morph the outline and need the shape's point count |
+
+Masks combine bottom-up (first in the list first). The first one starts from
+nothing when it adds and from the whole picture otherwise, so a lone
+`subtract` cuts a hole in a full picture. At most 8 masks per clip.
+
+The picture a mask lives in is the clip's drawn rectangle for video, image
+and svg (after fit and crop), the text block for text, and the whole canvas
+for an adjustment layer. Masks follow the clip when it is moved, scaled,
+rotated or flipped, and keep the clip's keyframes.
+
+In the editor, the **Masks** section of the Inspector has **+ Rect**,
+**+ Ellipse**, **Pen** (click points on the monitor, drag while placing one to
+pull curve handles, click the first point or press Enter to close) and
+**Draw** (drag a free-hand outline). **Matte** shows the clip's matte in the
+monitor (white = visible). Pick a mask's chip to edit it: mode, **Invert**,
+the sliders, ↑ ↓ to reorder, **Copy**, **Delete**, and on the monitor, drag
+inside to move it, the edge handles to resize it and the knob to rotate it
+(Shift snaps to 15°). On a bezier, drag a point to move it, drag its handles
+to curve it (Alt breaks the pair), Alt-drag a point to pull fresh handles,
+Ctrl-click the outline to add a point, and double-click a point to remove
+it. **◆ Key** keys the whole mask at the playhead; once it has keys, every
+change keys. Esc steps back (point, then mask).
+
+**Agents** edit masks with patch ops:
+
+- `{op:"setMask", id, set:{shape:"ellipse", x:0.5, y:0.45, w:0.4, h:0.7, feather:40}}`
+  adds a mask (no `mask`, an index one past the end or a new name adds one; a
+  new mask needs `shape`). `{op:"setMask", id, mask:"Subject", set:{x:0.6}}`
+  edits one, by index (0 = first) or name, merging key by key (`null` resets a
+  key). `replace:true` starts it over, keeping its name. `ids:[…]` edits several clips.
+- A drawn outline: `set:{shape:"freehand", stroke:[[0.4, 0.3], [0.6, 0.32], …]}`.
+  It is stored as an editable bezier.
+- `{op:"setMaskKeys", id, mask, keys:[{t:0, x:0.3}, {t:2, x:0.7}]}` animates
+  one (`keys:null` stops it); `{op:"removeMask", id, mask}` deletes one.
+- `props.masks` written through `addClip` / `updateClip` is validated the same
+  way. Bad keys, shapes or values refuse the whole patch. Locks apply
+  (`force:true` as elsewhere).
+- `fablecut_scopes {time, mask:{clip}}` measures them: the % of the clip's
+  picture its masks keep (the feathered matte, measured alone) and the % of
+  the frame the masked clip covers. The compact project view lists each
+  clip's masks as `[2 masks: ellipse feather 40, rect subtract]`.
+
+Recipes: **spotlight** — a feathered ellipse on the clip; **split screen** —
+two clips on V1 / V2, a `rect` on the top one covering its half; **cut a
+logo out of the background** — a bezier around it, `feather` 2–4;
+**reveal** — a rect whose `w` (or `x`) keys from 0 to full; **effects only
+on the face** — an adjustment layer with a feathered ellipse, keyed to follow
+it; **vignette through an adjustment layer** — an inverted ellipse with
+`feather:200` and the layer's `brightness` down.
+
+### Track mattes and blending
+
+A **track matte** cuts a clip with the picture on another track: where that
+picture is opaque (alpha) or bright (luma), the clip shows. Set it on the
+clip being cut, the fill:
+
+| prop | does |
+|---|---|
+| `matte` | `alpha` · `alpha-inverted` · `luma` · `luma-inverted`. Alpha keeps the clip where the matte's pixels are opaque, luma where they are bright (white = shows, black = gone, Rec. 709 weights). The inverted modes keep the opposite |
+| `matteTrack` | the video track the matte comes from. Default: the video track directly above the clip (V2 for a clip on V1) |
+
+The matte track does not draw into the frame while a clip on screen uses it;
+it only cuts. Its clips keep their own transform, keyframes, opacity, masks
+and effects, so the matte can move, scale and animate on its own. When the
+matte track has nothing at that moment, `alpha` / `luma` show nothing of the
+clip and the inverted modes show all of it. Track mattes and masks combine:
+the matte cuts the clip, then its masks cut what is left, then `opacity` and
+`blend` composite it. A clip used as a matte is drawn without its own track
+matte. Audio clips take neither.
+
+`blend` is how a clip lays over what is under it: `normal` · `multiply` ·
+`screen` · `overlay` · `darken` · `lighten` · `color-dodge` · `color-burn` ·
+`hard-light` · `soft-light` · `difference` · `exclusion` · `hue` ·
+`saturation` · `color` · `luminosity` · `lighter` (add). Blending happens after
+masks and mattes, so a masked clip only blends where it is kept.
+
+In the editor, **Track matte** and **Matte track** sit under **Blend** in the
+Inspector's Transform section (the Adjustment layer section for an adjustment
+layer). The timeline marks a clip with a track matte ◐ and shows the clips
+that serve as its matte hatched, labelled **Matte**.
+
+**Agents:** `{op:"setMatte", id, matte:"luma"}` (or `ids:[…]`; `track:"V3"`
+picks the matte track, `track:null` goes back to the one above;
+`matte:null` removes it). `blend`, `matte` and `matteTrack` written through
+`addClip` / `updateClip` are validated too. `fablecut_scopes` lists each clip
+on screen with its `matte` (e.g. `luma from V2`), `blend`, and whether it is a
+matte itself.
+
+Recipes: **text filled with video** — the text on V2, the video on V1 with
+`matte:"alpha"`; **a shape reveal** — an svg or a masked solid on V2 whose
+scale keys up, the shot on V1 with `matte:"alpha"`; **light leaks / film
+burn** on V2 with `blend:"screen"`; **a grade only in the bright areas** — an
+adjustment layer with `matte:"luma"` over a copy of the shot;
+**a cut-out through a texture** — `luma-inverted` against a black-and-white
+texture.
+
+### Tracking
+
+Motion tracking follows something in a video clip frame by frame: a corner, a
+logo, a face, a sign. The result is a **track** stored on the clip, and masks
+and other clips **follow** it by having it written into their keys. Rendering
+never reads a track, so a followed mask or title renders and exports exactly
+like a hand-keyed one, and you can edit its keys afterwards.
+
+```jsonc
+"tracks": [
+  { "name": "Logo", "kind": "point", "w": 0.08, "h": 0.14,
+    "samples": [[0, 0.31, 0.42, 1, 0, 1], [0.0333, 0.312, 0.421, 1, 0, 0.98]] }
+]
+```
+
+| key | does |
+|---|---|
+| `name` | how masks, clips and agents refer to it (default `Track n`, or the mask's name) |
+| `kind` | `point` (position) or `box` (position, size and rotation were followed) |
+| `w` · `h` | the region that was matched, fractions of the clip's picture |
+| `samples` | one per frame: `[t, x, y, s, r, q]`. `t` is seconds from the clip's start, `x, y` is the centre (fractions of the picture, like masks), `s` is the scale and `r` the rotation (°) relative to the first sample, `q` is the match quality 0…1 |
+
+The tracker matches a small greyscale template of the region (normalized
+cross-correlation, sub-pixel, optionally over scale and rotation) and keeps
+the template fresh while anchoring it to the first frame so it does not
+drift. It stops where the match quality drops below 0.45 (the region was
+covered, left the frame or changed too much) and keeps what it tracked up to
+there. Pick regions with detail: corners, text, edges. Flat sky or a blank
+wall can't be tracked. A track without scale follows position only: if the
+thing grows, shrinks or turns noticeably, turn on Scale / Rotate (`scale` /
+`rotation`), or the match fades and the track stops early. Tracks are stored in clip time, so they move with the clip and follow
+trims and splits (re-track after changing its speed).
+
+In the editor:
+
+- **Mask tracking.** Select a mask on a video clip. Under its mode row,
+  **◀ Back** and **On ▶** follow what the mask covers from the playhead to
+  the clip's start or end, and key the mask's `x` / `y`. Turn on **Scale**
+  and **Rotate** to key those too. The keys are linear and simplified (a key
+  only where the motion turns, within ~1.5 px). Keys the mask had in that range lose their
+  position and keep everything else.
+- **Point tracking.** The Inspector's **Tracking** section (video clips):
+  **+ Track point**, then click the spot on the monitor. It tracks from the
+  playhead to the clip's end. **Region** sets the matched area (% of the
+  picture's width). Pick a track's chip to see its path and region on the
+  monitor, **◀ Track back** / **Track on ▶** to extend it from the playhead,
+  and **Delete** it.
+- **Attach a clip.** With a track picked, choose a clip in **Attach**
+  (any visual clip that overlaps it in time) and press **Attach to the track**. The clip
+  gets `x` / `y` keyframes (plus `scale` / `rotation` with those toggles on)
+  that ride on the track and keep it where it is at the playhead. Stickers,
+  titles, a blur box or a highlight then stay pinned to the moving thing.
+- Tracking runs from a private copy of the video, so the monitor does not
+  move. Progress shows in the Inspector, and **Esc** stops it and keeps what
+  it has. Each finished track is one undo step.
+
+**Agents:** `fablecut_track` runs the tracker in the editor (an open tab, else
+headless Chrome / Edge) and saves the result:
+
+- `{clip, point:{x:0.62, y:0.4}, at:12}` follows a spot from `at` to the
+  clip's end. `region:{x, y, w, h}` gives the area instead, `size` sets a
+  point's region (default 0.08 of the width), `direction:"backward"|"both"`
+  and `to` (timeline seconds) set the range, and `scale` / `rotation` follow
+  those too.
+- `apply:{mask:"Face"}` bakes the result into that mask's keys. Leave out
+  `point` / `region` and the mask's own outline is what gets followed.
+- `apply:{clip:"c_sticker", scale?, rotation?, at?}` pins another clip to
+  the track.
+- `name` names the track. Passing an existing name with `apply` and no
+  region re-applies the stored track without tracking again.
+- The reply gives the range, the match quality (min / mean; ≥ 0.8 is solid),
+  where it was lost, and what was keyed.
+- `{op:"removeTrack", id, track}` deletes a stored track; what followed it
+  keeps its keys. The compact project view lists tracks as
+  `[tracks: "Logo" point 0.00–4.20 s (127 samples)]`, never their samples.
+
+Recipes: **a title that follows a car** — track a point on the car, attach
+the title; **blur a face or a plate** — an ellipse mask on a blurred copy of
+the shot on the track above, then `apply:{mask:"Face"}`; **a screen replacement** —
+track the screen with Scale and Rotate on and attach the new picture, cropped
+to fit; **a highlight that stays on a UI element** in a screen recording —
+track the button, attach a rect svg.
+
 ### Semantics
 
 - Rendering order: V1 is drawn first, then V2, V3, … on top. SVG/image/text clips

package/README.md

@@ -178,15 +178,29 @@ same time.
   pivot, soft rolloff and saturation, plus **curves** — luma and R / G / B,
   hue vs hue, hue vs saturation, hue vs luma and saturation vs luma, with a
   picker that marks a colour from the monitor, and **layers** (secondaries):
-  a correction limited by an HSL **qualifier** and / or an ellipse, rect or
-  polygon **mask** (feathered, invertible, keyframable, dragged on the
-  monitor), with a matte view. Copy / paste a grade across shots.
+  a correction limited by an HSL **qualifier** and / or an ellipse, rect,
+  polygon, bezier or free-hand **mask** (feathered, invertible, keyframable,
+  dragged on the monitor), with a matte view. Copy / paste a grade across shots.
   Agents grade with the `setGrade` patch op and read the result as numbers
   with `fablecut_scopes` (levels, clipping, colour cast)
 - Quick filter sliders: brightness/contrast/saturation/hue, **temperature & tint**,
   blur, grayscale/sepia/invert, **vignette**, animated **film grain**
-- Blend modes (screen, multiply, overlay…), fit modes (contain/cover/stretch),
+- 17 blend modes (screen, multiply, overlay, color-burn, exclusion, hue,
+  luminosity…), fit modes (contain/cover/stretch),
   per-edge cropping, corner radius, flip H/V
+- **Masks** — isolate any part of a clip (video, image, SVG, text or an
+  adjustment layer): rectangle, ellipse, **bezier pen** and **free-hand**
+  shapes, several per clip, combined with add / subtract / intersect /
+  difference, each with feather, expansion, invert and opacity, all
+  keyframable (outlines morph). Draw and edit them on the monitor, with a
+  matte view. Agents use the `setMask` patch op and measure with `fablecut_scopes`
+- **Motion tracking** — follow a point or a region (with its scale and
+  rotation) through a video clip, then make a mask follow it or pin a title,
+  sticker or any clip to it; the result is ordinary editable keys. Agents use
+  `fablecut_track`
+- **Track mattes** — cut a clip with the picture on the track above by its
+  alpha or its luma (inverted or not): text filled with video, shape reveals,
+  texture cut-outs. The matte track hides itself. Agents use `setMatte`
 - **Chroma key** (green screen) with tolerance/softness + spill suppression
 - **AI background removal** (person cut-out, in-browser via MediaPipe)
 
@@ -379,7 +393,7 @@ Three equivalent control surfaces:
    `fablecut_get_project`, `fablecut_set_project`, `fablecut_patch_project`,
    `fablecut_import_media`, `fablecut_analyze_reference`,
    `fablecut_encode_profiles`, `fablecut_normalize_audio`, `fablecut_auto_duck`,
-   `fablecut_denoise`, `fablecut_export`, `fablecut_scopes`.
+   `fablecut_denoise`, `fablecut_export`, `fablecut_scopes`, `fablecut_track`.
 
    FableCut is also published on the **official MCP registry** as
    [`io.github.ronak-create/fablecut`](https://registry.modelcontextprotocol.io/v0/servers?search=fablecut)
@@ -555,11 +569,11 @@ examples in [`library/svg/`](library/svg/).
 
 ## Sponsors
 
-<a href="https://fluxionai.world/register?source=github&amp;campaign=github-fablecut&amp;promo=FABLECUT" target="_blank" rel="noopener noreferrer sponsored">
-  <img src="docs/sponsors/fluxion-ai-banner.png" alt="Fluxion AI — unified access to GPT, Claude and other leading AI models" width="640">
+<a href="https://fluxionai.space/register?source=github&amp;campaign=github-sidrune-fablecut&amp;promo=SDRFABLECUT" target="_blank" rel="noopener noreferrer sponsored">
+  <img src="docs/sponsors/sidrune-ai-banner.png" alt="Sidrune AI — one API for GPT, Claude and other leading AI models" width="640">
 </a>
 
-**[Fluxion AI](https://fluxionai.world/register?source=github&campaign=github-fablecut&promo=FABLECUT)** provides reliable, cost-efficient access to GPT, Claude, and other leading AI models through one unified API. Save up to 70% compared with official API pricing — and get $3 in API credits when you sign up through this link.
+**[Sidrune AI](https://fluxionai.space/register?source=github&campaign=github-sidrune-fablecut&promo=SDRFABLECUT)** — One API for GPT, Claude, and other leading AI models. Sign up and get $3 in API credit.
 
 ## Community