Guides

Compositions and nesting

Making compositions, placing one as a layer, editing inside it, pre-composing layers, and how a nested comp's size, time and sound behave.

A composition is a timeline of its own, with its own canvas, frame rate, duration and tracks. The film you're editing is the main composition. A document can also hold other compositions, and any layer can place one, the way After Effects nests a comp inside another. This page explains when nesting helps, how to build and edit a composition, and how a placed composition behaves.

When nesting helps

Something you use more than once. Build a lower third once and place it for each speaker. Edit the comp, and every placement changes with it.
A group with its own timing. A sequence placed as one layer can be moved, trimmed, slowed down with setSpeed or faded as a unit, and its inner timing stays intact.
A frame within the frame. A comp crops what's inside it to its own canvas. A slide or a wipe inside a square comp stays inside the square, even when the film is vertical.
One treatment for many layers. A filter, a mask or an opacity ramp on the composition layer applies to everything inside it as one picture.

If you only need several layers to move together, you don't need a composition. Parenting does that with less overhead; see Keyframes and easing.

Making a composition

addComp takes a name, a canvas and, optionally, a duration in seconds:

ymotion_edit {"ops":[{"verb":"addComp","args":{"name":"Lower third","canvas":{"width":1080,"height":320},"duration":4}}]}

The new composition's id is in the reply under made, as compIds. A few defaults to know:

The canvas's frame rate is the film's unless you pass fps.
A duration of 0 follows shown enabled pictures or audible sound, using the same automatic out-point policy as the main film. Hidden pictures, disabled layers and muted sound add no tail; a hidden track with real sound still counts. Picture and audio Solo are separate. Participating placements keep their structural spans; this does not invert every fade or inspect source silence.
The background is black, as in After Effects. That colour is what you'd see with the comp open on its own. Where the comp is placed, its background isn't drawn, so the layers inside sit over whatever is beneath them.

A new composition has one track, called Main. Its id is in the reply's comp; made lists the composition and not what's inside it. To read it back at any time, ask for the comp's tracks:

ymotion_read {"what":"tracks","compId":"<comp id>"}

Compositions are made from the main timeline, that is, without compId on the edit. A composition always lives at the top of the document, even when you place it inside another one.

Working inside a composition

Add compId to ymotion_edit and the verbs work inside that composition as if it were the document. Add compId to ymotion_read to read it the same way. One batch inside a comp is one undo step. A placement that would make a direct or indirect composition loop is refused, with the whole batch unchanged in a normal or dry run. The exceptions are the verbs that make, change or remove a composition by its id: addComp, precompose, removeComp, renameComp, setCompCanvas and setCompDuration. They are refused inside compId, with the whole batch unchanged. Run them on the main timeline, as described above and under Pre-composing; to pre-compose layers inside a composition, name it as hostId.

ymotion_edit {"compId":"<comp id>","label":"build the lower third","ops":[
  {"verb":"addLayer","args":{"trackId":"<comp's Main track>","content":{"kind":"shape","shape":{"kind":"rect"}},"start":0,"duration":4,"name":"Bar"}},
  {"verb":"addTrack","args":{"kind":"visual","name":"Name"}}
]}

Inside a composition, positions and sizes are fractions of the comp's canvas, not the film's.

ymotion_media {"action":"place"} always places on the main timeline. To use footage inside a composition, add a layer that names the document's asset id. The asset id comes from the reply when the file was first placed, or from the assets list in ymotion_read {"what":"summary"}; if the placed layer isn't wanted on the main timeline, removeLayer takes it off and the asset stays. A video added this way is fitted to the comp's canvas:

ymotion_edit {"compId":"<comp id>","ops":[{"verb":"addLayer","args":{"trackId":"<track in the comp>","content":{"kind":"video","assetId":"<asset id>"},"start":0,"duration":4,"name":"Footage"}}]}

The same track rule applies inside a comp as everywhere else. addLayer replaces whatever already occupies that track at those times, so put layers that are on screen together on separate tracks.

Placing a composition

A composition becomes a layer like any other:

ymotion_edit {"ops":[{"verb":"addLayer","args":{"trackId":"<track id>","content":{"kind":"composition","compId":"<comp id>"},"start":1,"duration":4,"name":"Lower third"}}]}

It's drawn at its own size, centred, and from there it behaves like a picture. A lower third placed this way sits in the middle of the frame; a transform.y of about 0.25 to 0.3 moves it into the lower part of a vertical film. You can move it, scale it, fit it with fitToComp, mask it, grade it, give it effects and keyframes, trim it and change its speed. Each placement is independent, so two copies can sit in different places at different times. What's inside them is shared.

The layer shows the comp's timeline at the matching moment: one second into the layer is one second into the comp, adjusted for any trim or speed change. Where the comp has nothing on it, or the placing's source clock is outside the comp's duration, nothing is drawn. An explicit freeze of a valid inner instant can hold that frame. Reverse reads the incoming side of a source cut: a full-span reverse begins with its last valid picture, and held word, font, colour or number changes authored exactly at the excluded source out point do not leak into it. Continuous animation keeps the exact source timestamp; the engine does not move it by a source frame or epsilon.

Some useful questions to ask before and after placing:

ymotion_read {"what":"ask","verb":"canPlaceComp","args":{"hostId":"<host comp id>","compId":"<comp id>"}} answers whether one comp can go inside another without making a loop. A placement that would make a direct or indirect loop is refused atomically; this query explains whether it is possible before a batch is written.
ymotion_read {"what":"ask","verb":"layersPlacing","args":{"compId":"<comp id>"}} lists every placement once across the main timeline and every composition, even when the read view has a compId. renameCompLayers, called without a scoped compId, bulk-renames those placements across all timelines.

Pre-composing

precompose is After Effects' Pre-compose with "Move all attributes into the new composition". It moves the named layers into a new composition and puts one composition layer in their place:

ymotion_edit {"ops":[{"verb":"precompose","args":{"layerIds":["<layer id>","<layer id>"],"name":"Intro"}}]}

Pre-compose isolates the selected layers. As in After Effects, a moved blend mode now blends with the new comp's transparent ground. Each track keeps its hidden flag. Parent/matte dependencies and adjustment scope changes are checked before anything is moved; the operation refuses instead of silently changing those relationships. Here's how the move works:

The layers keep their times and their stacking order.
The new comp is the size and length of the comp they came from.
The composition layer goes on a new track above the topmost of them. The tracks they left stay where they were, keeping any layers that weren't moved.
A parent link or track matte across the boundary is refused: include both sides, or unparent/clear the matte explicitly first. No layer is added to the selection behind your back.
An adjustment that would stop affecting external pictures, or a picture lifted above an external adjustment, is refused. Keep the grade outside or include its affected pictures. The host background remains outside the new comp: moving a grade changes its background interaction, the intended After Effects isolation behavior.
Sound moves too, and is heard exactly as before. A soloed sound is still refused, because Solo chooses among one comp's sounds.

To pre-compose layers that are already inside a nested composition, name that composition as hostId. Run this on the main timeline, without compId, so the new comp is created at the top of the document like every other:

ymotion_edit {"ops":[{"verb":"precompose","args":{"layerIds":["<layer id>"],"name":"Star rig","hostId":"<comp id>"}}]}

Composition settings

The main composition's size, frame rate and background are changed with setCanvas, its length with setDuration, and its name with renameProject. The same three verbs work on a nested composition when you add compId to the edit. You can also change a nested comp from outside, by its id:

ymotion_edit {"ops":[
  {"verb":"setCompCanvas","args":{"compId":"<comp id>","patch":{"width":1080,"height":1080}}},
  {"verb":"setCompDuration","args":{"compId":"<comp id>","duration":5}},
  {"verb":"renameComp","args":{"compId":"<comp id>","name":"Square card"}},
  {"verb":"renameCompLayers","args":{"compId":"<comp id>","name":"Square card"}}
]}

renameCompLayers renames the layers that place the comp on the timeline you run it on, so that timeline keeps up with the new name. removeComp deletes a composition together with every layer that places it, and the reply lists everything that went.

Sound inside a composition

A composition layer's sound is the comp's own mix, summed. That layer's level, fades, pan and audio effects then apply to the sum, the way a bus works in a mixing desk. So fading out a pre-composed scene fades its music and its dialogue together. ymotion_render {"what":"audio"} prints the plan, with each composition's sounds listed under it.

Looking at a composition

ymotion_render draws the main timeline. To see a composition, render a moment where it's placed. To see it without the rest of the film, soloLayer its composition layer, render, and then undo. Its background isn't drawn when it's placed, so you see the layers inside over the film's background.

Good to know

A comp is drawn at its own size and then scaled like a picture. Scaling a small comp up softens it. Build a comp at the size it will be seen, such as a 1080-wide lower third for a 1080-wide film.
Every placement costs a full frame of drawing at the comp's size, and comps inside comps multiply that cost. Nesting stops at eight levels.
Parenting stays inside a composition. A layer can only be parented to another layer in the same comp.
Ids inside a comp belong to that comp. Its track and layer ids are found only when you pass the comp's compId. Without it, the server reports that there's no such layer.