Guides

Cuts and transitions

Putting a transition on the cut between two shots, how the overlap is made, and when a straight cut or a hand-built dissolve is better.

A transition in Ymotion is a decision about a cut, written as ordinary keyframes. This page covers how to make a cut, how to put a transition on it, what happens to the two layers, and how to choose between a transition, a straight cut and a dissolve you build yourself.

What a transition writes

The document has no "transition" object. As in After Effects, a dissolve is two layers that overlap with an opacity ramp on the upper one. applyTransition writes exactly that kind of thing onto the two layers on either side of a cut: it extends them into each other where the transition needs both pictures, then adds keyframes, a mask or a filter to one or both (a dissolve, wipe or iris writes only to the incoming layer). Afterwards, the result is indistinguishable from work done by hand. You can read the keys with ymotion_read, adjust them, or, while it's still the last edit, remove the whole thing with one ymotion_doc {"action":"undo"}.

Making a cut

A transition sits on a cut: two layers on the same track, with the second starting exactly where the first ends. There are two common ways to get one.

To cut one shot in two, split it. splitLayer cuts a layer at a timeline time, and its reply lists the new layer under made. That's the half after the cut, which is the layer the transition goes on:

ymotion_edit {"ops":[{"verb":"splitLayer","args":{"layerId":"<video layer id>","t":2}}]}

To join two shots, place the second file where the first one ends, on the same track. For example, after a 4-second shot that starts at 0, use ymotion_media {"action":"place","id":"<media id>","trackId":"<the first shot's track>","start":4}. Without trackId, place picks a track that already holds video and is free at that time, which is usually the same one.

If the layers don't quite touch, the transition is refused, and the message says how far apart they are. Move one with moveLayer. Alternatively, closeGaps packs connected overlap groups on that track from 0 s, preserving every existing transition and internal overlap while closing gaps between groups. Anything on other tracks that was timed to them stays where it was; film markers and fixed duration stay unchanged too.

Applying one

Pass the id of the layer after the cut, and a transition id:

ymotion_edit {"ops":[{"verb":"applyTransition","args":{"layerId":"<layer after the cut>","transition":"dissolve"}}]}

These are the transitions available:

dissolve — Dissolve: both shots on screen at once, 0.6 s by default
blurDissolve — Blur: both shots on screen at once, 0.7 s by default; also amount
slide — Slide: both shots on screen at once, 0.5 s by default; also direction
whip — Whip: both shots on screen at once, 0.35 s by default; also direction, amount
wipe — Wipe: both shots on screen at once, 0.6 s by default; also direction, softness
iris — Iris: both shots on screen at once, 0.7 s by default; also softness
stack — Stack: both shots on screen at once, 0.6 s by default; also direction
zoom — Zoom: covers the cut, 0.5 s by default; also amount
flash — Flash: covers the cut, 0.45 s by default
blackout — Blackout: covers the cut, 0.8 s by default; also hold
filmBurn — Film burn: covers the cut, 0.9 s by default

Every transition takes over, its length in seconds. Some also take a direction, the way the move or the edge travels (0 left, 1 right, 2 up, 3 down), or a knob of their own. Pass only the ones you want to change:

ymotion_edit {"ops":[{"verb":"applyTransition","args":{"layerId":"<layer after the cut>","transition":"whip","params":{"over":0.3,"direction":1}}}]}

ymotion_find {"catalogue":"transitions","id":"whip"} gives each knob's range and default. Supplied knobs must be finite numbers within those inclusive ranges; otherwise the whole edit is refused with the knob and allowed range, before any overlap or keys are written. A legal value is never rounded to the slider step. "dryRun":true on the edit checks that a cut is there without writing anything. You can put transitions on several cuts in one batch, and the batch is still one undo step.

Overlap and cover

There are two kinds of transition, and the difference matters when your footage has no spare frames.

An overlap (dissolve, blurDissolve, slide, whip, wipe, iris, stack) shows both shots at once, so the two layers are extended into each other across the cut:

When both sides have footage beyond the cut, the overlap is centred on it. A split always has spare footage on both sides, since the rest of the file is still there.
When only one side has spare footage, the overlap leans onto that side.
When neither side has any, as with two whole files placed end to end, the outgoing shot holds its last frame for the length of the overlap. That's what Premiere does, and the leaving shot is the one the eye notices least.
Type, shapes, solids and stills can extend as far as needed. A reversed or speed-ramped layer is treated as having no spare footage. A composition layer's spare time runs to the comp's set duration, and a comp whose duration is 0 has none past its end.
The overlap is at most 95% of either layer's length, however long you ask for.

A cover (flash, blackout, filmBurn, zoom) hides the cut instead: the outgoing shot is taken to white (a film burn through orange), black or blur by the cut, and the incoming shot comes back out of it, half the length on each side. No layer changes length, so a cover is the clean choice for two whole files.

In both kinds, nothing moves in time. Every caption, sound effect and later layer stays where it was. The sound still cuts where the picture cut was: footage and composition sound buses extended for an overlap are silenced past the cut, ramped from 10 ms before it to 10 ms after so it doesn't click. If you want the sound to cross-fade too, build the dissolve by hand, as described below.

Changing or removing one

After an overlap, a second transition on the same cut is refused, because the layers already overlap there. A cover changes no lengths, so the cut is still a cut and a second transition is accepted and stacks on the first, filters and all. Either way, to swap one, undo it and apply the new one. To adjust the one you have, edit its keys: the incoming layer of a dissolve, for example, has an opacity ramp you can re-time with moveKey or reshape with setKeyHandles.

When an overlap extends footage that has sound, the cut in the sound is made with two keys on that layer's audio.volume, at its level then and at 0. Keys override the flat level, so a later setVolume or setLevel on that layer has no effect; change its level with setKeyValue on the key that holds it, and read the times with ymotion_read {"what":"keys","layerId":"<layer id>","path":"audio.volume"}.

Transitions work inside a nested composition too, with compId on the edit. See Compositions and nesting.

A dissolve by hand

Sometimes you want two shots overlapping by an exact amount, on different tracks, or with your own curve. Put the incoming shot on a track above the outgoing one, starting where you want the dissolve to begin, and ramp its opacity across the overlap. Here the outgoing shot runs from 0 to 4 s, so the incoming one starts at 3 s for a one-second dissolve, and the ramp's times are counted from the incoming layer's own start. It works best when the outgoing shot ends where the dissolve ends: if it runs on, its picture is hidden under the new one but its sound keeps playing.

ymotion_edit {"ops":[{"verb":"addTrack","args":{"kind":"visual","name":"Shot 2"}}]}

ymotion_media {"action":"place","id":"<media id>","trackId":"<that track>","start":3}

ymotion_edit {"label":"dissolve by hand","ops":[
  {"verb":"keyRamp","args":{"layerId":"<incoming layer>","path":"opacity","from":0,"to":1,"opts":{"start":0,"end":1,"ease":"linear"}}}
]}

A dissolve usually reads best linear: an eased one lingers on both pictures at once and reads as a double exposure rather than a change.

Both shots' sound plays during the overlap. To cross-fade it, give the outgoing layer a fadeOut and the incoming layer a fadeIn, each the length of the overlap. setFades sets both ends at once, so give the other end the value it should keep (0 for none):

ymotion_edit {"ops":[
  {"verb":"setFades","args":{"layerId":"<outgoing layer>","fadeIn":0,"fadeOut":1}},
  {"verb":"setFades","args":{"layerId":"<incoming layer>","fadeIn":1,"fadeOut":0}}
]}

See Sound, music and sound effects for more on levels and fades.

Choosing

These are starting points, not rules:

A reel carries a transition on every cut. A straight cut is for when the person asks for one. Most of the choice is which kind and how long, below.
Give the cut a job. A new view can answer a question, show a detail, compare two states or advance an action. Splitting continuous footage without changing its view or what follows creates a timeline boundary but leaves the picture continuous. A transition there adds a flourish without supplying the missing editorial reason.
Match the pace. Quick, energetic edits suit whip, zoom or flash at 0.25–0.4 s. A calm piece suits a dissolve of 0.6–1 s. A blackout with a larger hold, the share of it spent on black, marks a chapter break.
Pick one or two kinds per film and use them consistently. A different transition on every cut draws attention to the editing rather than the story.
Carry attention through it. Keep the important subject or detail easy to find on either side, and let the incoming shot be read after the transition settles. A reveal loses its effect when another title or gesture starts before the viewer can see what was revealed.
Give each transition its sound. A camera shutter whose click sits on the cut, and for a zoom a whoosh whose peak does. placeSfx puts a chosen sound's moment exactly on the time you give it; Sound effects for motion has the pairings.
For whole files with no spare footage, prefer a cover, unless a held last frame is acceptable.

Common pitfalls

Passing the outgoing layer. layerId is the layer that starts at the cut. If nothing on that track ends where it starts, the refusal says so.
A gap or an overlap already there. The layers have to meet exactly. If they already overlap at that point, the cut is treated as having a transition already.
Sound tracks. Transitions are between pictures, and a layer on an audio track is refused.
Judging it from the keys. Render the frames around the cut, for example ymotion_render {"times":[3.7,4.0,4.3]}, and look.