Ymotion
Help
Docs Connect a chatbot
Dashboard
All pages

Footage and sound

Putting things behind a person

Cut a person or any object out of footage or a photo as one layer, so titles sit behind it — and see the selection first.

A hook, title or explanatory graphic that passes behind somebody's head looks as though it belongs in the shot. Ymotion does it the way Instagram's Edits does: the subject is cut out of the footage once, and comes back as ONE layer, the footage again with everything round the subject taken away. It sits on top, the title goes between it and the footage, and the title disappears behind the subject's outline. The footage underneath is untouched.

Ordinary speech captions stay below the face, never across or above it. Use depth in the upper region for hooks, titles or explanatory graphics.

The cut-out is the one way Ymotion cuts a subject out; other editors call it rotoscoping, remove background or isolate subject. People are found by themselves, an object can be too, and anything else, such as a car, a product, a pet or a ball, is followed from a box or a few points.

The cut is a matte: a video the same length and size as the upload, white where the subject is and black everywhere else. It is made by a model, once, on a GPU, and kept beside the upload. Every preview and every export then reads that same file, so the film looks the same every time it is drawn. Anything in front of a person, such as a microphone, its arm or a cup in their hand, is part of the cut too, so a title behind them is behind the microphone as well.

The one call

Cut out only the PART of the video that needs it: the stretch where a title passes behind the subject, never the whole video. It is paid in credits by the frames it covers. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId, ask with the footage layer in the open document and the part, "from" and "to" in seconds on the main timeline:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","from":12,"to":20}

Left out, the whole of what the layer shows is cut out, and paid for by all of it; a part that runs past the layer ends where the layer does.

The first time, this starts the work and answers straight away with "status":"pending". Making a matte takes minutes rather than seconds, longer for longer footage, plus a minute or so while a GPU that was asleep starts up. Nothing in the film changes yet, and nothing has to wait for it: the matte goes on being made whether or not anybody asks. "While it works" below says what to do in the meantime.

Asking again with exactly the same call reports how far it has got, as a percentage and the time left. Asking doesn't hurry it, so ask once, when the rest of the film is done or after the time the reply gives. When it's done, the same call adds the cut-out and answers "status":"done". The structured reply always carries the call to make next, under call.

What it builds

One layer, a copy of the footage layer with everything it has: its grade, masks, fades, keyframes and track matte, its trim and speed. It is muted, so the sound isn't doubled, and it takes its alpha from the matte, so only the subject is drawn. Its id is the footage layer's followed by -cutout; the done reply names it under layerId, with footageId, the matte's asset under alphaAssetId, and the seconds of the file the matte holds.

It is a layer like any other. Move it, scale it, turn it, trim it, split it, duplicate it, key it, give it effects, a stroke or a shadow round the subject: the cut goes with it, because the matte is read at the same moment of the file as the footage, whatever the layer does. Past the seconds the matte holds, the layer draws nothing. Never rebuild it as a track matte of its matte, which is refused; setAlpha restores a lost alpha.

A part's layer is trimmed to that part, so it is on screen only there, on the footage's own frames. Two parts of one footage are two layers, the second -cutout-2. A part that overlaps one already in front for the same subject is refused, naming that one: the subject is in front there already. Where the footage's speed ramps or runs backwards, a trim would show other frames than the footage under it, so that layer runs as long as the footage and draws nothing outside the part.

Where it goes is place:

  • "top", the default: on a new track at the top of the footage's composition. Every track between the footage and it is behind the subject, which is what puts titles already on the film behind them.
  • "above": on a new track directly above the footage's own. Everything above that stays in front of the subject. The editor does this.
  • "only": no copy. The footage layer itself takes the matte as its alpha and keeps its sound, so only the subject is drawn and nothing of the footage is left under it.

An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId and place, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","from":12,"to":20,"place":"above"}

Asking again changes only the cut-out's alpha, never where it has been moved, its keys, its trim or its track. That is how a remake reaches it, and it reaches every layer that shares its alpha, such as the two halves of a split. Asking from the footage with different prompts, subject or unprompted is a different cut-out, and adds a second layer beside the first, -cutout-2.

Titles behind the person

Titles that are already on tracks above the footage are behind the person as soon as the cut-out is on top. New titles go on a track between the two, directly above the footage's track:

ymotion_edit {"ops":[{"verb":"addTrack","args":{"kind":"visual","name":"Titles","above":"<footage track id>"}}]}

then add the titles to that track as usual; see Type and titles. To keep something in front of the person, such as a lower third, move its track above the cut-out's:

ymotion_edit {"ops":[{"verb":"moveTrack","args":{"trackId":"<title track id>","toIndex":99}}]}

Large type placed partly behind the head and shoulders reads best. Render a few moments across the shot to check, since the person moves:

ymotion_render {"count":4}

Only the part needed, and kept

A cut-out is for the stretch where something crosses the subject. A title that passes behind the speaker for six seconds is a six-second cut-out, not the whole film; a title that sits in clear space needs none. Choose the part from the frames: where the text is on screen and overlaps the subject.

Every matte is kept beside the upload. Asking for the same part again, or for a part inside one already made, in this film or another, even after its layer was deleted, hands the kept matte back at once with no new GPU job, and the done reply says when it came from one kept. So when a cut-out is needed again, ask for it again rather than making it twice. Only "again":true makes one afresh.

Seeing the selection first

"select":true shows what the cut-out would be on ONE frame, at once, makes nothing and costs nothing. It is the look before the minutes: the reply carries a picture of the frame with the selection tinted blue and the rest dimmed, the selection's share of the frame and its box, the candidates found on it, and the exact call that tracks it. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId and select, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","select":true,"from":2.5}

With layerId, "from" is the moment on the main timeline, and must be one the layer shows; without it, the layer's first frame is used. With an upload, "from" is seconds into the file. A photo has one frame and needs neither.

With no prompts the reply lists the CANDIDATES on the frame, people first and then objects, each with a number, a label and how sure the model is, and says which the automatic pick takes. Look at the picture. If it's right, make the call the reply gives under call. If it isn't, say what you mean on the same frame and select again. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId, select and prompts, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","select":true,"prompts":[{"at":2.5,"keep":[[0.42,0.38]],"drop":[[0.7,0.5]]}]}

Each answer is the new selection, so add a point, look, add another. A selection is one frame: every prompt in it must be on that frame. When it's right, the reply's call tracks exactly that through the footage. Its prompts carry the frame's own time, and shots without a prompt are left empty, so only what you chose is cut out. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId, prompts and unprompted, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","from":2,"to":10,"prompts":[{"t":3.204,"keep":[[0.42,0.38]],"drop":[[0.7,0.5]]}],"unprompted":"none"}

The first selection after a while wakes a GPU, which takes about a quarter of a minute. The reply then says "status":"warming" with askAgainIn; ask again with the same call a few seconds later. Only the newest selection is shown: one asked while another was still waiting answers "status":"superseded", and needs nothing done. A selection is free, with no daily limit; a select_limit refusal is a service not yet redeployed, and no reason not to track.

Who is cut out

  • Automatic, people. With no prompts, every person large enough to be what the shot is about is cut out, in every shot; a shot with nobody in it is left empty.
  • Automatic, anything. "subject":"any" takes the people, and in a shot with nobody, the one object that most stands out, such as a dog, a car or a boat. A shot with neither is left empty, and the reply says so.
  • Your own. prompts say who on the frames they are on. A shot with a prompt follows what the prompt shows, and nothing else; a shot without one is left to the automatic pick, unless "unprompted":"none", which leaves it empty.
  • More than one. "obj" numbers subjects 1 to 6: prompts with the same obj on one frame describe one subject, and different numbers are different subjects, all cut out together.

A prompt is:

  • at, the moment in seconds on the main timeline, for a layer on the main timeline; or t, seconds into the file, for an upload or a layer inside a composition. It must fall inside the part being cut out. Either is put on the start of the frame on screen at that moment, so two moments on one frame are the same prompt.
  • box, [left, top, right, bottom] round the subject, in fractions of the footage's own frame from its top-left, 0 to 1. That frame isn't the composition's when the footage is fitted into a frame of another shape, so render it or select first.
  • keep, points on the subject, and drop, points that aren't it, as [x, y] fractions. A microphone in front of a person is meant to stay in the cut, so don't drop it.
  • obj, which subject, 1 to 6, when there is more than one.

A prompt needs a box or some keep points, and one subject has at most one box on any one frame. Different prompts make a different matte, so asking with prompts starts a new one.

"quality":"fast" skips the pass that reads the edge at full resolution. It's quicker and its edges are softer round hair; leave it at the default unless speed matters more.

Something other than a person

SAM 2 follows whatever it's shown. A box round any object on a frame where it's plainly in view is followed through the shot and its edge read the same way. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId, prompts and unprompted, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","from":2,"to":10,"prompts":[{"at":2.5,"box":[0.3,0.1,0.7,1]}],"unprompted":"none"}

Give one on each shot the subject is in. Selecting first shows whether the box takes too much or too little; add keep points on the subject or drop points beside it until it doesn't. What is in front of the subject, such as a hand holding it, is kept in the cut as it is for a person.

While it works

There's nothing to wait for. Go on with the rest of the film: the titles, their timing, type and styling, the sound. The cut-out changes none of that, and adds one layer when it is done.

  • Place and trim the footage, and set its speed, before asking. The cut-out is made for the part asked for, or what the layer shows, in seconds of the file, with up to half a second either side that its bound leaves room for.
  • Ask again once, when the rest of the film is done or after the time the reply gives. The pending reply's data says the same: next is what to do meanwhile, and askAgainIn the seconds after which an ask is worth making.
  • With layerId, the film has to be the open document when you ask again. If another has been opened since, switch back first; the pending reply names the film under document:
ymotion_doc {"action":"use","id":"<document id>"}
  • A film stays open only for the conversation it was opened in. To come back to it later, save it first. In a new conversation, first list saved files with ymotion_doc {"action":"files"}; then, if your tool list declares project, open one before making the same cut-out call:
ymotion_doc {"action":"open","project":"<project>"}
  • If there's nothing else to do, tell the person it's being made and stop asking. The same call made later collects it.

Tell the person once what's going on: the subject is being cut out on a GPU, it takes a few minutes, it happens once for this footage, and the film isn't changed until it's ready.

Only one cut-out is made at a time for an account. Asking for another while one is being made is refused and names the one in progress; carry on and ask again once that is done. The refusal's data carries next and askAgainIn. A job the GPU service says nothing new about for twelve hours is stopped.

Stopping one

"cancel":true with the same call stops the cut-out being made for exactly that request. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId and cancel, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","from":12,"to":20,"cancel":true}

The reply says what it came to. One still waiting for a GPU is dropped, and its credits are given back. One already running is stopped on the GPU, and the credits it held stay charged. One already handing its matte over can't be stopped, and is kept. Anything a stopped job delivers later is deleted. Its reply carries the call with "again":true, to make it after all.

What it costs, and how much one job holds

A cut-out runs on a GPU, so it is an AI job, paid in AI credits; nothing else here costs any. A video's is 1 credit to start and 1 for every started 200 frames of the stretch it covers: 30 seconds is 5 credits at 24 frames a second, 6 at 30 and 10 at 60; a photo's is one job of 1 credits.

  • Cut out only the seconds the edit needs, never the whole video: a cut-out is paid by its frames, so footage at 60 frames a second costs twice what 30 does. The half second added either side never adds a credit; a part just past a multiple of 200 frames does.
  • One job over a stretch costs less than several small ones.
  • Credits are held when a job starts and given back if it fails or is stopped before a GPU works on it. A part answered from a matte already made costs nothing, and so does a selection.
  • Replies say the cost and balance; ymotion_help {"topic":"account"} gives the balance. Say the cost before a long job.
  • A credits refusal starts and charges nothing. This account does not have enough AI credits for the requested job. Tell the person and continue editing; exports have their own allowance.

One job also has bounds of its own, since a GPU is paid by the frame:

  • A stretch's frames are the ones on screen in it, counted before anything is sent to a GPU. One cut-out is at most 9,000 of them, about five minutes at 30 frames a second, and at most ten minutes. Past either, the refusal names a "from"/"to" that would fit.
  • A stretch whose frames run at more than 120 a second isn't cut out, and making it again won't change that.

Every refusal carries a code in its structured reply, such as too_long, credits or bad_prompt.

Replacing the background

The cut-out doesn't take the background away by itself: the footage still draws underneath. To replace it, put the new background, such as a solid, a picture or another video, on a track directly above the footage's and below the cut-out's, which is where titles go:

ymotion_edit {"ops":[{"verb":"addTrack","args":{"kind":"visual","name":"Background","above":"<footage track id>"}}]}

The film's sound still plays from the footage underneath, since the cut-out is muted. To have no footage at all under the subject, cut it out with "place":"only" instead.

Starting again

A finished cut-out is kept and reused. To make it afresh, ask with "again":true. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId and again, use:

ymotion_media {"action":"cutout","layerId":"<footage layer id>","from":12,"to":20,"again":true}

The one already made is kept, and the film goes on drawing it until the new one is ready; asking again then swaps the cut-out's alpha for the new one. The old matte isn't deleted even then: any other film that draws it goes on drawing it, so it stays, counted, until the upload is removed. If the new one fails, asking again gives back the one made before, with a note saying why. If a cut-out fails, the reply gives this call, unless making it again would fail the same way; then it says what to change.

A replaced matte counts towards storage until the upload is removed. When the person asks for it to go, remove that one alone by its src, which describe lists under cutouts:

ymotion_media {"action":"remove","src":"<the replaced matte's src>"}

This is permanent: a film that still draws it draws nothing where the subject was.

An upload rather than a layer

Without a document, first inspect uploads with ymotion_media {"action":"list"}; then, if your tool list declares the cutout action, ask with the upload's id or with the src a document's asset carries:

ymotion_media {"action":"cutout","id":"<upload id>"}

This makes the matte and reports it, and changes no document. Without "from" and "to" it covers the whole file, and is paid for by all of it; give them, in seconds of the file, for the part needed. A stretch can be cut from a file of up to three hours and 8 GB. ymotion_media {"action":"describe","id":"<upload id>"} lists an upload's cut-outs under cutouts. The matte counts towards the account's storage and is removed with the upload; removing an upload while its cut-out is being made stops that job.

A photo, and removing its background

Removing a photo's background is this cut-out with "place":"only" and "subject":"object": the photo's main subject, a person, a product or anything else, is found over the whole picture, and the photo itself is cut, so only the subject stays on the page. It takes no prompts and no selection; a photo where nothing stands out is said so and left as it is. To choose the subject yourself, leave "subject" out (people) or send "any", or a box in "prompts".

The subject of a photo is cut out with the same call, by its layer in a design or a film, or by the upload. A photo is one moment, so it has no "from" or "to", and a prompt has "t":0 or none. The matte is a grey picture at the photo's own size as it is seen. In a design, "place":"above" keeps the photo behind the cut-out, so text on a track between the two passes behind the subject, and "only" cuts the photo itself, leaving just the subject. An older tool list can first inspect uploads with ymotion_media {"action":"list"}; then, if it declares the cutout action and layerId, place and subject, use:

ymotion_media {"action":"cutout","layerId":"<photo layer id>","place":"only","subject":"object"}

A photo is a JPEG, a PNG, a WebP or a GIF's one picture; anything else is refused before anything is sent. A selection of a photo needs no "from".

A film with an older cut-out

Films cut out before 2026-10-10 hold TWO layers for one cut-out: the copy, cut by a track matte, and the matte video on the track above it, switched off. They go on drawing as they always did. Asking again with the same call converts them in one step: the matte layer goes, and its track if that leaves it empty, and the copy keeps where it is and takes the matte as its alpha.

On an older cut-out service

The service is deployed separately, and an older one, version 1.4, knows none of this page's newer parts. With one, a selection is refused with needs_update, and the reply gives the call that tracks the same prompts without looking first. "subject":"any" is sent as people, "unprompted":"none" isn't sent, so shots without a prompt are cut automatically, and the reply says each once. A second subject is refused with needs_update. The rest works as before.

How it is made

A person and object detector finds who each shot is about, SAM 2.1 follows them through it, starting again at every cut, and BiRefNet reads the edge at the footage's own resolution, which keeps hair and fingers sharp and keeps what is in front of a person in the cut. The result is checked when it arrives: a matte that doesn't have exactly as many frames as the footage, at the same size, is refused rather than placed out of step.

The footage is read by that GPU service, which runs separately from this server. It keeps the matte only until it has been stored here, and drops it when the upload is removed; it keeps nothing for more than a day. If the person asks where their footage goes, that's the answer.

When it isn't available

This page is served only while the cut-out is switched on, so on this server it is on, and cutout is one of ymotion_media's actions.

A client keeps the tool list it was given when it connected. One given its list before the cut-out existed won't show cutout, layerId or prompts, and one given it before 2026-10-10 won't show select, subject, unprompted, place or cancel. A client may drop an argument its list doesn't show before the call leaves it. The server takes all of them; what arrives is up to the client. So when a call is refused for missing one, or the client won't send it, ask the person to refresh or reconnect Ymotion in their chatbot's settings. If the list declares cutout, {"action":"cutout","id":"<upload id>"} cuts out the people in an upload and changes no document. A list without these fields is no reason to tell the person the cut-out is off.

Without a GPU service configured, the refusal names CUTOUT_URL and CUTOUT_SECRET, for whoever runs the server.

Don't fake it with masks. A shape drawn by hand and keyed round a moving person doesn't follow their outline: the title disappears behind a box of the background, not behind the person, and it looks it. If the cut-out can't be made, set the title where it's clear of the person, and tell the person why.