Command · Select Object
mask.objectSelect
AI Object Mask: segments the person or object you click on (positive and negative clicks), draw a box around, or name ("subject": a face, a person, a car...) on a frame of a clip with SAM 2.1 (local, on this computer), and tracks it through the shot.
- v1
- Capability EditSequence
- Tool
mask_objectSelect
Request
{
"command": "mask.objectSelect",
"params": {
"clip": 42,
"points": [
{
"positive": true,
"x": 0.52,
"y": 0.4
}
],
"time": "00:00:05:00"
}
}Parameters
acrossShotsboolean- Keep tracking across shot cuts (default false: stop at the cuts around the frame).
boxobject- A box around the object, normalised frame coordinates.
box.heightnumber (0.0..1.0)Required- 0..1 of the frame height.
box.widthnumber (0.0..1.0)Required- 0..1 of the frame width.
box.xnumber (0.0..1.0)Required- Left, 0..1.
box.ynumber (0.0..1.0)Required- Top, 0..1.
clipinteger | object (1..)Required- A clip id, or {"track", "time"} for the clip there.
colour`red` | `orange` | `yellow` | `green` | `cyan` | `blue` | `purple` | `pink` | `white` | `black` | `grey`- With "subject": the one of this colour ("the red car").
effectinteger (1..)- The effect the mask limits (clip.details lists them): blur the background (with "inverted"), grade only the subject. Omit for the clip's opacity mask: a cut-out that removes the background.
expansionnumber (-0.5..0.5)- Grow (+) or choke (-) the matte, in frame heights (default 0).
feathernumber (0.0..0.5)- Soft edge, in frame heights (default 0.004).
ininteger | string- Track no earlier than this (inside the clip). Timecode in the sequence's rate ("00:01:02:03") or ticks.
invertedboolean- Everything but the object (default false).
mode`add` | `subtract` | `intersect`- How it combines with the masks before it (default add).
namestring- The mask's name. Default the subject's, or "Object".
outinteger | string- Track no later than this (inside the clip). Timecode in the sequence's rate ("00:01:02:03") or ticks.
pick`largest` | `center` | `left` | `right`- With "subject": which one when there are several (default the largest).
pointsobject[]- Clicks on the object (positive) and off it (negative), normalised frame coordinates.
points[].positiveboolean- true: part of the object (default); false: not part of it.
points[].xnumber (0.0..1.0)Required- 0..1 of the frame width.
points[].ynumber (0.0..1.0)Required- 0..1 of the frame height.
propagate`none` | `forward` | `backward` | `both`- Track the object through the clip from the frame: default both ways (a job: progress, cancel); none = this frame only (refine first, then mask.propagate).
sequenceinteger (1..)- Sequence id; only needed when the project has several.
subjectstring- Instead of clicks: what to find on the frame, "face" or a COCO class ("person", "car", "dog", "bicycle", ...).
timeinteger | string- The frame the clicks or the box are on, inside the clip. Default the clip's first frame. Timecode in the sequence's rate ("00:01:02:03") or ticks.
Discussion
AI Object Mask: segments the person or object you click on (positive and negative clicks), draw a box around, or name ("subject": a face, a person, a car...) on a frame of a clip with SAM 2.1 (local, on this computer), and tracks it through the shot. The result is a mask that follows it, on an effect of the clip ("blur the background behind the speaker": a Gaussian Blur with an inverted object mask; "brighten the red car": a grade limited to it) or on the clip's opacity (remove the background). Stops at shot cuts unless acrossShots. One undo step; dryRun previews it.
Run it with wabcut-cli cmd <project> --json, from an MCP client as mask_objectSelect, or from an extension. See Edit commands for requests, references and results.
See also
mask.*
- mask.add
Add Mask. Adds a mask to a clip: to an effect ("effect"; the effect then only changes the masked area - a local correction, including the colour grade) or, without "effect", to the clip's opacity mask (it cuts the clip out).
- mask.list
List Masks. A clip's masks by effect, with their parameters (keys at media times) and paths.
- mask.propagate
Track Object Mask. Tracks an object mask's object through the clip (or In / Out) from its last clicked frame: after a selection made with "propagate": "none", or across a shot cut with acrossShots.
- mask.refine
Refine Object Mask. More clicks (positive: part of the object; negative: not) or a new box on a frame of an object mask: segments it again there and re-tracks from that frame.
- mask.remove
Remove Mask. Removes a mask from its effect.
- mask.update
Update Mask. Changes a mask: only the fields given (name, shape, mode, inverted, enabled, params, path / pathKeys).